NetworkPkg/IScsiDxe/IScsiCHAP.h

   1 /** @file
   2   The header file of CHAP configuration.
   3
   4 Copyright (c) 2004 - 2018, Intel Corporation. All rights reserved.<BR>
   5 SPDX-License-Identifier: BSD-2-Clause-Patent
   6
   7 **/
   8
   9 #ifndef _ISCSI_CHAP_H_
  10 #define _ISCSI_CHAP_H_
  11
  12 #define ISCSI_AUTH_METHOD_CHAP                    "CHAP"
  13
  14 #define ISCSI_KEY_CHAP_ALGORITHM                  "CHAP_A"
  15 #define ISCSI_KEY_CHAP_IDENTIFIER                 "CHAP_I"
  16 #define ISCSI_KEY_CHAP_CHALLENGE                  "CHAP_C"
  17 #define ISCSI_KEY_CHAP_NAME                       "CHAP_N"
  18 #define ISCSI_KEY_CHAP_RESPONSE                   "CHAP_R"
  19
  20 //
  21 // Identifiers of supported CHAP hash algorithms:
  22 // https://www.iana.org/assignments/ppp-numbers/ppp-numbers.xhtml#ppp-numbers-9
  23 //
  24 #define ISCSI_CHAP_ALGORITHM_MD5                  5
  25 #define ISCSI_CHAP_ALGORITHM_SHA256               7
  26
  27 //
  28 // Byte count of the largest digest over the above-listed
  29 // ISCSI_CHAP_ALGORITHM_* hash algorithms.
  30 //
  31 #define ISCSI_CHAP_MAX_DIGEST_SIZE                SHA256_DIGEST_SIZE
  32
  33 #define ISCSI_CHAP_STEP_ONE                       1
  34 #define ISCSI_CHAP_STEP_TWO                       2
  35 #define ISCSI_CHAP_STEP_THREE                     3
  36 #define ISCSI_CHAP_STEP_FOUR                      4
  37
  38
  39 #pragma pack(1)
  40
  41 typedef struct _ISCSI_CHAP_AUTH_CONFIG_NVDATA {
  42   UINT8 CHAPType;
  43   CHAR8 CHAPName[ISCSI_CHAP_NAME_STORAGE];
  44   CHAR8 CHAPSecret[ISCSI_CHAP_SECRET_STORAGE];
  45   CHAR8 ReverseCHAPName[ISCSI_CHAP_NAME_STORAGE];
  46   CHAR8 ReverseCHAPSecret[ISCSI_CHAP_SECRET_STORAGE];
  47 } ISCSI_CHAP_AUTH_CONFIG_NVDATA;
  48
  49 #pragma pack()
  50
  51 //
  52 // Typedefs for collecting sets of hash APIs from BaseCryptLib.
  53 //
  54 typedef
  55 UINTN
  56 (EFIAPI *CHAP_HASH_GET_CONTEXT_SIZE) (
  57   VOID
  58   );
  59
  60 typedef
  61 BOOLEAN
  62 (EFIAPI *CHAP_HASH_INIT) (
  63   OUT VOID *Context
  64   );
  65
  66 typedef
  67 BOOLEAN
  68 (EFIAPI *CHAP_HASH_UPDATE) (
  69   IN OUT VOID       *Context,
  70   IN     CONST VOID *Data,
  71   IN     UINTN      DataSize
  72   );
  73
  74 typedef
  75 BOOLEAN
  76 (EFIAPI *CHAP_HASH_FINAL) (
  77   IN OUT VOID  *Context,
  78   OUT    UINT8 *HashValue
  79   );
  80
  81 typedef struct {
  82   UINT8                      Algorithm;      // ISCSI_CHAP_ALGORITHM_*, CHAP_A
  83   UINT32                     DigestSize;
  84   CHAP_HASH_GET_CONTEXT_SIZE GetContextSize;
  85   CHAP_HASH_INIT             Init;
  86   CHAP_HASH_UPDATE           Update;
  87   CHAP_HASH_FINAL            Final;
  88 } CHAP_HASH;
  89
  90 ///
  91 /// ISCSI CHAP Authentication Data
  92 ///
  93 typedef struct _ISCSI_CHAP_AUTH_DATA {
  94   ISCSI_CHAP_AUTH_CONFIG_NVDATA *AuthConfig;
  95   UINT32                        InIdentifier;
  96   UINT8                         InChallenge[1024];
  97   UINT32                        InChallengeLength;
  98   //
  99   // The hash algorithm (CHAP_A) that the target selects in
 100   // ISCSI_CHAP_STEP_TWO.
 101   //
 102   CONST CHAP_HASH               *Hash;
 103   //
 104   // Calculated CHAP Response (CHAP_R) value.
 105   //
 106   UINT8                         CHAPResponse[ISCSI_CHAP_MAX_DIGEST_SIZE];
 107
 108   //
 109   // Auth-data to be sent out for mutual authentication.
 110   //
 111   // While the challenge size is technically independent of the hashing
 112   // algorithm, it is good practice to avoid hashing *fewer bytes* than the
 113   // digest size. In other words, it's good practice to feed *at least as many
 114   // bytes* to the hashing algorithm as the hashing algorithm will output.
 115   //
 116   UINT32                        OutIdentifier;
 117   UINT8                         OutChallenge[ISCSI_CHAP_MAX_DIGEST_SIZE];
 118 } ISCSI_CHAP_AUTH_DATA;
 119
 120 /**
 121   This function checks the received iSCSI Login Response during the security
 122   negotiation stage.
 123
 124   @param[in] Conn             The iSCSI connection.
 125
 126   @retval EFI_SUCCESS          The Login Response passed the CHAP validation.
 127   @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
 128   @retval EFI_PROTOCOL_ERROR   Some kind of protocol error occurred.
 129   @retval Others               Other errors as indicated.
 130
 131 **/
 132 EFI_STATUS
 133 IScsiCHAPOnRspReceived (
 134   IN ISCSI_CONNECTION  *Conn
 135   );
 136 /**
 137   This function fills the CHAP authentication information into the login PDU
 138   during the security negotiation stage in the iSCSI connection login.
 139
 140   @param[in]       Conn        The iSCSI connection.
 141   @param[in, out]  Pdu         The PDU to send out.
 142
 143   @retval EFI_SUCCESS           All check passed and the phase-related CHAP
 144                                 authentication info is filled into the iSCSI
 145                                 PDU.
 146   @retval EFI_OUT_OF_RESOURCES  Failed to allocate memory.
 147   @retval EFI_PROTOCOL_ERROR    Some kind of protocol error occurred.
 148
 149 **/
 150 EFI_STATUS
 151 IScsiCHAPToSendReq (
 152   IN      ISCSI_CONNECTION  *Conn,
 153   IN OUT  NET_BUF           *Pdu
 154   );
 155
 156 /**
 157   Initialize the CHAP_A=<A1,A2...> *value* string for the entire driver, to be
 158   sent by the initiator in ISCSI_CHAP_STEP_ONE.
 159
 160   This function sanity-checks the internal table of supported CHAP hashing
 161   algorithms, as well.
 162 **/
 163 VOID
 164 IScsiCHAPInitHashList (
 165   VOID
 166   );
 167 #endif