NetworkPkg/IScsiDxe/IScsiCHAP.h

/** @file
  The header file of CHAP configuration.

Copyright (c) 2004 - 2018, Intel Corporation. All rights reserved.<BR>
SPDX-License-Identifier: BSD-2-Clause-Patent

**/

#ifndef _ISCSI_CHAP_H_
#define _ISCSI_CHAP_H_

#define ISCSI_AUTH_METHOD_CHAP  "CHAP"

#define ISCSI_KEY_CHAP_ALGORITHM   "CHAP_A"
#define ISCSI_KEY_CHAP_IDENTIFIER  "CHAP_I"
#define ISCSI_KEY_CHAP_CHALLENGE   "CHAP_C"
#define ISCSI_KEY_CHAP_NAME        "CHAP_N"
#define ISCSI_KEY_CHAP_RESPONSE    "CHAP_R"

//
// Identifiers of supported CHAP hash algorithms:
// https://www.iana.org/assignments/ppp-numbers/ppp-numbers.xhtml#ppp-numbers-9
//
#define ISCSI_CHAP_ALGORITHM_MD5     5
#define ISCSI_CHAP_ALGORITHM_SHA256  7

//
// Byte count of the largest digest over the above-listed
// ISCSI_CHAP_ALGORITHM_* hash algorithms.
//
#define ISCSI_CHAP_MAX_DIGEST_SIZE  SHA256_DIGEST_SIZE

#define ISCSI_CHAP_STEP_ONE    1
#define ISCSI_CHAP_STEP_TWO    2
#define ISCSI_CHAP_STEP_THREE  3
#define ISCSI_CHAP_STEP_FOUR   4

#pragma pack(1)

typedef struct _ISCSI_CHAP_AUTH_CONFIG_NVDATA {
  UINT8    CHAPType;
  CHAR8    CHAPName[ISCSI_CHAP_NAME_STORAGE];
  CHAR8    CHAPSecret[ISCSI_CHAP_SECRET_STORAGE];
  CHAR8    ReverseCHAPName[ISCSI_CHAP_NAME_STORAGE];
  CHAR8    ReverseCHAPSecret[ISCSI_CHAP_SECRET_STORAGE];
} ISCSI_CHAP_AUTH_CONFIG_NVDATA;

#pragma pack()

//
// Typedefs for collecting sets of hash APIs from BaseCryptLib.
//
typedef
UINTN
(EFIAPI *CHAP_HASH_GET_CONTEXT_SIZE)(
  VOID
  );

typedef
BOOLEAN
(EFIAPI *CHAP_HASH_INIT)(
  OUT VOID *Context
  );

typedef
BOOLEAN
(EFIAPI *CHAP_HASH_UPDATE)(
  IN OUT VOID       *Context,
  IN     CONST VOID *Data,
  IN     UINTN      DataSize
  );

typedef
BOOLEAN
(EFIAPI *CHAP_HASH_FINAL)(
  IN OUT VOID  *Context,
  OUT    UINT8 *HashValue
  );

typedef struct {
  UINT8                         Algorithm;   // ISCSI_CHAP_ALGORITHM_*, CHAP_A
  UINT32                        DigestSize;
  CHAP_HASH_GET_CONTEXT_SIZE    GetContextSize;
  CHAP_HASH_INIT                Init;
  CHAP_HASH_UPDATE              Update;
  CHAP_HASH_FINAL               Final;
} CHAP_HASH;

///
/// ISCSI CHAP Authentication Data
///
typedef struct _ISCSI_CHAP_AUTH_DATA {
  ISCSI_CHAP_AUTH_CONFIG_NVDATA    *AuthConfig;
  UINT32                           InIdentifier;
  UINT8                            InChallenge[1024];
  UINT32                           InChallengeLength;
  //
  // The hash algorithm (CHAP_A) that the target selects in
  // ISCSI_CHAP_STEP_TWO.
  //
  CONST CHAP_HASH                  *Hash;
  //
  // Calculated CHAP Response (CHAP_R) value.
  //
  UINT8                            CHAPResponse[ISCSI_CHAP_MAX_DIGEST_SIZE];

  //
  // Auth-data to be sent out for mutual authentication.
  //
  // While the challenge size is technically independent of the hashing
  // algorithm, it is good practice to avoid hashing *fewer bytes* than the
  // digest size. In other words, it's good practice to feed *at least as many
  // bytes* to the hashing algorithm as the hashing algorithm will output.
  //
  UINT32    OutIdentifier;
  UINT8     OutChallenge[ISCSI_CHAP_MAX_DIGEST_SIZE];
} ISCSI_CHAP_AUTH_DATA;

/**
  This function checks the received iSCSI Login Response during the security
  negotiation stage.

  @param[in] Conn             The iSCSI connection.

  @retval EFI_SUCCESS          The Login Response passed the CHAP validation.
  @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
  @retval EFI_PROTOCOL_ERROR   Some kind of protocol error occurred.
  @retval Others               Other errors as indicated.

**/
EFI_STATUS
IScsiCHAPOnRspReceived (
  IN ISCSI_CONNECTION  *Conn
  );

/**
  This function fills the CHAP authentication information into the login PDU
  during the security negotiation stage in the iSCSI connection login.

  @param[in]       Conn        The iSCSI connection.
  @param[in, out]  Pdu         The PDU to send out.

  @retval EFI_SUCCESS           All check passed and the phase-related CHAP
                                authentication info is filled into the iSCSI
                                PDU.
  @retval EFI_OUT_OF_RESOURCES  Failed to allocate memory.
  @retval EFI_PROTOCOL_ERROR    Some kind of protocol error occurred.

**/
EFI_STATUS
IScsiCHAPToSendReq (
  IN      ISCSI_CONNECTION  *Conn,
  IN OUT  NET_BUF           *Pdu
  );

/**
  Initialize the CHAP_A=<A1,A2...> *value* string for the entire driver, to be
  sent by the initiator in ISCSI_CHAP_STEP_ONE.

  This function sanity-checks the internal table of supported CHAP hashing
  algorithms, as well.
**/
VOID
IScsiCHAPInitHashList (
  VOID
  );

#endif