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 #pragma pack(1)
  39
  40 typedef struct _ISCSI_CHAP_AUTH_CONFIG_NVDATA {
  41   UINT8    CHAPType;
  42   CHAR8    CHAPName[ISCSI_CHAP_NAME_STORAGE];
  43   CHAR8    CHAPSecret[ISCSI_CHAP_SECRET_STORAGE];
  44   CHAR8    ReverseCHAPName[ISCSI_CHAP_NAME_STORAGE];
  45   CHAR8    ReverseCHAPSecret[ISCSI_CHAP_SECRET_STORAGE];
  46 } ISCSI_CHAP_AUTH_CONFIG_NVDATA;
  47
  48 #pragma pack()
  49
  50 //
  51 // Typedefs for collecting sets of hash APIs from BaseCryptLib.
  52 //
  53 typedef
  54 UINTN
  55 (EFIAPI *CHAP_HASH_GET_CONTEXT_SIZE)(
  56   VOID
  57   );
  58
  59 typedef
  60 BOOLEAN
  61 (EFIAPI *CHAP_HASH_INIT)(
  62   OUT VOID *Context
  63   );
  64
  65 typedef
  66 BOOLEAN
  67 (EFIAPI *CHAP_HASH_UPDATE)(
  68   IN OUT VOID       *Context,
  69   IN     CONST VOID *Data,
  70   IN     UINTN      DataSize
  71   );
  72
  73 typedef
  74 BOOLEAN
  75 (EFIAPI *CHAP_HASH_FINAL)(
  76   IN OUT VOID  *Context,
  77   OUT    UINT8 *HashValue
  78   );
  79
  80 typedef struct {
  81   UINT8                         Algorithm;   // ISCSI_CHAP_ALGORITHM_*, CHAP_A
  82   UINT32                        DigestSize;
  83   CHAP_HASH_GET_CONTEXT_SIZE    GetContextSize;
  84   CHAP_HASH_INIT                Init;
  85   CHAP_HASH_UPDATE              Update;
  86   CHAP_HASH_FINAL               Final;
  87 } CHAP_HASH;
  88
  89 ///
  90 /// ISCSI CHAP Authentication Data
  91 ///
  92 typedef struct _ISCSI_CHAP_AUTH_DATA {
  93   ISCSI_CHAP_AUTH_CONFIG_NVDATA    *AuthConfig;
  94   UINT32                           InIdentifier;
  95   UINT8                            InChallenge[1024];
  96   UINT32                           InChallengeLength;
  97   //
  98   // The hash algorithm (CHAP_A) that the target selects in
  99   // ISCSI_CHAP_STEP_TWO.
 100   //
 101   CONST CHAP_HASH                  *Hash;
 102   //
 103   // Calculated CHAP Response (CHAP_R) value.
 104   //
 105   UINT8                            CHAPResponse[ISCSI_CHAP_MAX_DIGEST_SIZE];
 106
 107   //
 108   // Auth-data to be sent out for mutual authentication.
 109   //
 110   // While the challenge size is technically independent of the hashing
 111   // algorithm, it is good practice to avoid hashing *fewer bytes* than the
 112   // digest size. In other words, it's good practice to feed *at least as many
 113   // bytes* to the hashing algorithm as the hashing algorithm will output.
 114   //
 115   UINT32    OutIdentifier;
 116   UINT8     OutChallenge[ISCSI_CHAP_MAX_DIGEST_SIZE];
 117 } ISCSI_CHAP_AUTH_DATA;
 118
 119 /**
 120   This function checks the received iSCSI Login Response during the security
 121   negotiation stage.
 122
 123   @param[in] Conn             The iSCSI connection.
 124
 125   @retval EFI_SUCCESS          The Login Response passed the CHAP validation.
 126   @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
 127   @retval EFI_PROTOCOL_ERROR   Some kind of protocol error occurred.
 128   @retval Others               Other errors as indicated.
 129
 130 **/
 131 EFI_STATUS
 132 IScsiCHAPOnRspReceived (
 133   IN ISCSI_CONNECTION  *Conn
 134   );
 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
 168 #endif