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
  26 //
  27 // Byte count of the largest digest over the above-listed
  28 // ISCSI_CHAP_ALGORITHM_* hash algorithms.
  29 //
  30 #define ISCSI_CHAP_MAX_DIGEST_SIZE                MD5_DIGEST_SIZE
  31
  32 #define ISCSI_CHAP_STEP_ONE                       1
  33 #define ISCSI_CHAP_STEP_TWO                       2
  34 #define ISCSI_CHAP_STEP_THREE                     3
  35 #define ISCSI_CHAP_STEP_FOUR                      4
  36
  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   This function fills the CHAP authentication information into the login PDU
 137   during the security negotiation stage in the iSCSI connection login.
 138
 139   @param[in]       Conn        The iSCSI connection.
 140   @param[in, out]  Pdu         The PDU to send out.
 141
 142   @retval EFI_SUCCESS           All check passed and the phase-related CHAP
 143                                 authentication info is filled into the iSCSI
 144                                 PDU.
 145   @retval EFI_OUT_OF_RESOURCES  Failed to allocate memory.
 146   @retval EFI_PROTOCOL_ERROR    Some kind of protocol error occurred.
 147
 148 **/
 149 EFI_STATUS
 150 IScsiCHAPToSendReq (
 151   IN      ISCSI_CONNECTION  *Conn,
 152   IN OUT  NET_BUF           *Pdu
 153   );
 154
 155 /**
 156   Initialize the CHAP_A=<A1,A2...> *value* string for the entire driver, to be
 157   sent by the initiator in ISCSI_CHAP_STEP_ONE.
 158
 159   This function sanity-checks the internal table of supported CHAP hashing
 160   algorithms, as well.
 161 **/
 162 VOID
 163 IScsiCHAPInitHashList (
 164   VOID
 165   );
 166 #endif