MdePkg/Include/Protocol/Eap.h

   1 /** @file
   2   EFI EAP(Extended Authenticaton Protocol) Protocol Definition
   3   The EFI EAP Protocol is used to abstract the ability to configure and extend the
   4   EAP framework.
   5   The definitions in this file are defined in UEFI Specification 2.3.1B, which have
   6   not been verified by one implementation yet.
   7
   8   Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR>
   9   SPDX-License-Identifier: BSD-2-Clause-Patent
  10
  11   @par Revision Reference:
  12   This Protocol is introduced in UEFI Specification 2.2
  13
  14 **/
  15
  16 #ifndef __EFI_EAP_PROTOCOL_H__
  17 #define __EFI_EAP_PROTOCOL_H__
  18
  19
  20 #define EFI_EAP_PROTOCOL_GUID \
  21   { \
  22     0x5d9f96db, 0xe731, 0x4caa, {0xa0, 0xd, 0x72, 0xe1, 0x87, 0xcd, 0x77, 0x62 } \
  23   }
  24
  25 typedef struct _EFI_EAP_PROTOCOL EFI_EAP_PROTOCOL;
  26
  27 ///
  28 /// Type for the identification number assigned to the Port by the
  29 /// System in which the Port resides.
  30 ///
  31 typedef VOID *  EFI_PORT_HANDLE;
  32
  33 ///
  34 /// EAP Authentication Method Type (RFC 3748)
  35 ///@{
  36 #define EFI_EAP_TYPE_TLS 13 ///< REQUIRED - RFC 5216
  37 ///@}
  38
  39 //
  40 // EAP_TYPE MD5, OTP and TOEKN_CARD has been removed from UEFI2.3.1B.
  41 // Definitions are kept for backward compatibility.
  42 //
  43 #define EFI_EAP_TYPE_MD5                4
  44 #define EFI_EAP_TYPE_OTP                5
  45 #define EFI_EAP_TYPE_TOKEN_CARD         6
  46
  47 /**
  48   One user provided EAP authentication method.
  49
  50   Build EAP response packet in response to the EAP request packet specified by
  51   (RequestBuffer, RequestSize).
  52
  53   @param[in]      PortNumber     Specified the Port where the EAP request packet comes.
  54   @param[in]      RequestBuffer  Pointer to the most recently received EAP- Request packet.
  55   @param[in]      RequestSize    Packet size in bytes for the most recently received
  56                                  EAP-Request packet.
  57   @param[in]      Buffer         Pointer to the buffer to hold the built packet.
  58   @param[in, out] BufferSize     Pointer to the buffer size in bytes.
  59                                  On input, it is the buffer size provided by the caller.
  60                                  On output, it is the buffer size in fact needed to contain
  61                                  the packet.
  62
  63   @retval EFI_SUCCESS            The required EAP response packet is built successfully.
  64   @retval others                 Failures are encountered during the packet building process.
  65
  66 **/
  67 typedef
  68 EFI_STATUS
  69 (EFIAPI *EFI_EAP_BUILD_RESPONSE_PACKET)(
  70   IN EFI_PORT_HANDLE        PortNumber,
  71   IN UINT8                  *RequestBuffer,
  72   IN UINTN                  RequestSize,
  73   IN UINT8                  *Buffer,
  74   IN OUT UINTN              *BufferSize
  75   );
  76
  77 /**
  78   Set the desired EAP authentication method for the Port.
  79
  80   The SetDesiredAuthMethod() function sets the desired EAP authentication method indicated
  81   by EapAuthType for the Port.
  82
  83   If EapAuthType is an invalid EAP authentication type, then EFI_INVALID_PARAMETER is
  84   returned.
  85   If the EAP authentication method of EapAuthType is unsupported by the Ports, then it will
  86   return EFI_UNSUPPORTED.
  87   The cryptographic strength of EFI_EAP_TYPE_TLS shall be at least of hash strength
  88   SHA-256 and RSA key length of at least 2048 bits.
  89
  90   @param[in] This                A pointer to the EFI_EAP_PROTOCOL instance that indicates
  91                                  the calling context.
  92   @param[in] EapAuthType         The type of the EAP authentication method to register. It should
  93                                  be the type value defined by RFC. See RFC 2284 for details.
  94   @param[in] Handler             The handler of the EAP authentication method to register.
  95
  96   @retval EFI_SUCCESS            The EAP authentication method of EapAuthType is
  97                                  registered successfully.
  98   @retval EFI_INVALID_PARAMETER  EapAuthType is an invalid EAP authentication type.
  99   @retval EFI_UNSUPPORTED        The EAP authentication method of EapAuthType is
 100                                  unsupported by the Port.
 101
 102 **/
 103 typedef
 104 EFI_STATUS
 105 (EFIAPI *EFI_EAP_SET_DESIRED_AUTHENTICATION_METHOD)(
 106   IN EFI_EAP_PROTOCOL            *This,
 107   IN UINT8                       EapAuthType
 108   );
 109
 110 /**
 111   Register an EAP authentication method.
 112
 113   The RegisterAuthMethod() function registers the user provided EAP authentication method,
 114   the type of which is EapAuthType and the handler of which is Handler.
 115
 116   If EapAuthType is an invalid EAP authentication type, then EFI_INVALID_PARAMETER is
 117   returned.
 118   If there is not enough system memory to perform the registration, then
 119   EFI_OUT_OF_RESOURCES is returned.
 120
 121   @param[in] This                A pointer to the EFI_EAP_PROTOCOL instance that indicates
 122                                  the calling context.
 123   @param[in] EapAuthType         The type of the EAP authentication method to register. It should
 124                                  be the type value defined by RFC. See RFC 2284 for details.
 125   @param[in] Handler             The handler of the EAP authentication method to register.
 126
 127   @retval EFI_SUCCESS            The EAP authentication method of EapAuthType is
 128                                  registered successfully.
 129   @retval EFI_INVALID_PARAMETER  EapAuthType is an invalid EAP authentication type.
 130   @retval EFI_OUT_OF_RESOURCES   There is not enough system memory to perform the registration.
 131
 132 **/
 133 typedef
 134 EFI_STATUS
 135 (EFIAPI *EFI_EAP_REGISTER_AUTHENTICATION_METHOD)(
 136   IN EFI_EAP_PROTOCOL                     *This,
 137   IN UINT8                                EapAuthType,
 138   IN EFI_EAP_BUILD_RESPONSE_PACKET        Handler
 139   );
 140
 141 ///
 142 /// EFI_EAP_PROTOCOL
 143 /// is used to configure the desired EAP authentication method for the EAP
 144 /// framework and extend the EAP framework by registering new EAP authentication
 145 /// method on a Port. The EAP framework is built on a per-Port basis. Herein, a
 146 /// Port means a NIC. For the details of EAP protocol, please refer to RFC 2284.
 147 ///
 148 struct _EFI_EAP_PROTOCOL {
 149   EFI_EAP_SET_DESIRED_AUTHENTICATION_METHOD   SetDesiredAuthMethod;
 150   EFI_EAP_REGISTER_AUTHENTICATION_METHOD      RegisterAuthMethod;
 151 };
 152
 153 extern EFI_GUID gEfiEapProtocolGuid;
 154
 155 #endif
 156