2 Definitions related to the Cryptographic Operations in IPsec.
4 Copyright (c) 2009 - 2011, Intel Corporation. All rights reserved.<BR>
6 This program and the accompanying materials
7 are licensed and made available under the terms and conditions of the BSD License
8 which accompanies this distribution. The full text of the license may be found at
9 http://opensource.org/licenses/bsd-license.php.
11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
15 #ifndef _EFI_IPSEC_CRYPTIO_H_
16 #define _EFI_IPSEC_CRYPTIO_H_
18 #include <Protocol/IpSecConfig.h>
19 #include <Library/DebugLib.h>
20 #include <Library/BaseCryptLib.h>
21 #include <Library/BaseMemoryLib.h>
22 #include <Library/MemoryAllocationLib.h>
24 #include "IpSecImpl.h"
25 #include "IkeCommon.h"
27 #define IPSEC_ENCRYPT_ALGORITHM_LIST_SIZE 4
28 #define IPSEC_AUTH_ALGORITHM_LIST_SIZE 3
29 #define IPSEC_HASH_ALGORITHM_LIST_SIZE 3
32 /// Authentication Algorithm Definition
33 /// The number value definition is aligned to IANA assignment
35 #define IKE_AALG_NONE 0x00
36 #define IKE_AALG_SHA1HMAC 0x02
37 #define IKE_AALG_NULL 0xFB
40 /// Encryption Algorithm Definition
41 /// The number value definition is aligned to IANA assignment
43 #define IKE_EALG_NONE 0x00
44 #define IKE_EALG_3DESCBC 0x03
45 #define IKE_EALG_NULL 0x0B
46 #define IKE_EALG_AESCBC 0x0C
49 Prototype of HMAC GetContextSize.
51 Retrieves the size, in bytes, of the context buffer required.
53 @return The size, in bytes, of the context buffer required.
58 (EFIAPI
*CRYPTO_HMAC_GETCONTEXTSIZE
)(
63 Prototype of HMAC Operation Initiating.
65 Initialization with a new context.
67 @param[out] Context Input Context.
68 @param[in] Key Pointer to the key for HMAC.
69 @param[in] KeySize The length of the Key in bytes.
71 @retval TRUE Initialization Successfully.
76 (EFIAPI
*CRYPTO_HMAC_INIT
)(
83 Prototype of HMAC update.
84 HMAC update operation. Continue an HMAC message digest operation, processing
85 another message block, and updating the HMAC context.
87 If Context is NULL, then ASSERT().
88 If Data is NULL, then ASSERT().
90 @param[in,out] Context The Specified Context.
91 @param[in,out] Data The Input Data to be digested.
92 @param[in] DataLength The length, in bytes, of Data.
94 @retval TRUE Update data successfully.
95 @retval FALSE The Context has been finalized.
100 (EFIAPI
*CRYPTO_HMAC_UPDATE
)(
101 IN OUT VOID
*Context
,
107 Prototype of HMAC finalization.
108 Terminate a HMAC message digest operation and output the message digest.
110 If Context is NULL, then ASSERT().
111 If HashValue is NULL, then ASSERT().
113 @param[in,out] Context The specified Context.
114 @param[out] HmacValue Pointer to a 16-byte message digest output buffer.
116 @retval TRUE Finalized successfully.
121 (EFIAPI
*CRYPTO_HMAC_FINAL
)(
122 IN OUT VOID
*Context
,
127 Prototype of Block Cipher GetContextSize.
129 Retrieves the size, in bytes, of the context buffer required.
131 @return The size, in bytes, of the context buffer required.
136 (EFIAPI
*CRYPTO_CIPHER_GETCONTEXTSIZE
)(
141 Prototype of Block Cipher initiation.
142 Initializes the user-supplied key as the specified context (key materials) for both
143 encryption and decryption operations.
145 If Context is NULL, then ASSERT().
146 If Key is NULL, then generate random key for usage.
148 @param[in,out] Context The specified Context.
149 @param[in] Key User-supplied cipher key.
150 @param[in] KeyBits Key length in bits.
152 @retval TRUE Block Cipher Initialization was successful.
157 (EFIAPI
*CRYPTO_CIPHER_INIT
)(
158 IN OUT VOID
*Context
,
164 Prototype of Cipher encryption.
165 Encrypts plaintext message with the specified cipher.
167 If Context is NULL, then ASSERT().
168 If InData is NULL, then ASSERT().
169 If Size of input data is not multiple of Cipher algorithm related block size,
172 @param[in] Context The specified Context.
173 @param[in] InData The input plaintext data to be encrypted.
174 @param[in] InputSize The size of input data.
175 @param[in] Ivec Pointer to Initial Vector data for encryption.
176 @param[out] OutData The resultant encrypted ciphertext.
178 @retval TRUE Encryption successful.
183 (EFIAPI
*CRYPTO_CIPHER_ENCRYPT
)(
185 IN CONST UINT8
*InData
,
187 IN CONST UINT8
*Ivec
,
192 Prototype of Cipher decryption.
193 Decrypts cipher message with specified cipher.
195 If Context is NULL, then ASSERT().
196 If InData is NULL, then ASSERT().
197 If Size of input data is not a multiple of a certaion block size , then ASSERT().
199 @param[in] Context The specified Context.
200 @param[in] InData The input ciphertext data to be decrypted.
201 @param[in] InputSize The InData size.
202 @param[in] Ivec Pointer to the Initial Vector data for decryption.
203 @param[out] OutData The resultant decrypted plaintext.
205 @retval TRUE Decryption successful.
210 (EFIAPI
*CRYPTO_CIPHER_DECRYPT
)(
212 IN CONST UINT8
*InData
,
214 IN CONST UINT8
*Ivec
,
219 Prototype of Hash ContextSize.
221 Retrieves the size, in bytes, of the context buffer required for specified hash operations.
223 @return The size, in bytes, of the context buffer required for certain hash operations.
228 (EFIAPI
*CRYPTO_HASH_GETCONTEXTSIZE
)(
233 Prototype of Hash Initiate.
235 Initializes user-supplied memory pointed by Context as specified hash context for
238 If Context is NULL, then ASSERT().
240 @param[out] Context Pointer to specified context being initialized.
242 @retval TRUE context initialization succeeded.
243 @retval FALSE context initialization failed.
248 (EFIAPI
*CRYPTO_HASH_INIT
)(
253 Prototype of Hash Update
255 Digests the input data and updates hash context.
257 This function performs digest on a data buffer of the specified size.
258 It can be called multiple times to compute the digest of long or discontinuous data streams.
259 Context should be already correctly initialized by HashInit(), and should not be finalized
260 by HashFinal(). Behavior with invalid context is undefined.
262 If Context is NULL, then ASSERT().
264 @param[in, out] Context Pointer to the specified context.
265 @param[in] Data Pointer to the buffer containing the data to be hashed.
266 @param[in] DataSize Size of Data buffer in bytes.
268 @retval TRUE data digest succeeded.
269 @retval FALSE data digest failed.
274 (EFIAPI
*CRYPTO_HASH_UPDATE
)(
275 IN OUT VOID
*Context
,
281 Prototype of Hash Finalization.
283 Completes computation of the digest value.
285 This function completes hash computation and retrieves the digest value into
286 the specified memory. After this function has been called, the context cannot
288 context should be already correctly initialized by HashInit(), and should not be
289 finalized by HashFinal(). Behavior with invalid context is undefined.
291 If Context is NULL, then ASSERT().
292 If HashValue is NULL, then ASSERT().
294 @param[in, out] Context Pointer to the specified context.
295 @param[out] HashValue Pointer to a buffer that receives the digest
298 @retval TRUE digest computation succeeded.
299 @retval FALSE digest computation failed.
304 (EFIAPI
*CRYPTO_HASH_FINAL
)(
305 IN OUT VOID
*Context
,
310 // The struct used to store the information and operation of Block Cipher algorithm.
312 typedef struct _ENCRYPT_ALGORITHM
{
314 // The ID of the Algorithm
318 // The Key length of the Algorithm
322 // Iv Size of the Algorithm
326 // The Block Size of the Algorithm
330 // The Function pointer of GetContextSize.
332 CRYPTO_CIPHER_GETCONTEXTSIZE CipherGetContextSize
;
334 // The Function pointer of Cipher initiation.
336 CRYPTO_CIPHER_INIT CipherInitiate
;
338 // The Function pointer of Cipher Encryption.
340 CRYPTO_CIPHER_ENCRYPT CipherEncrypt
;
342 // The Function pointer of Cipher Decryption.
344 CRYPTO_CIPHER_DECRYPT CipherDecrypt
;
348 // The struct used to store the information and operation of Authentication algorithm.
350 typedef struct _AUTH_ALGORITHM
{
352 // ID of the Algorithm
356 // The Key length of the Algorithm
360 // The ICV length of the Algorithm
364 // The block size of the Algorithm
368 // The function pointer of GetContextSize.
370 CRYPTO_HMAC_GETCONTEXTSIZE HmacGetContextSize
;
372 // The function pointer of Initiation
374 CRYPTO_HMAC_INIT HmacInitiate
;
376 // The function pointer of HMAC Update.
378 CRYPTO_HMAC_UPDATE HmacUpdate
;
380 // The fucntion pointer of HMAC Final
382 CRYPTO_HMAC_FINAL HmacFinal
;
386 // The struct used to store the information and operation of Hash algorithm.
388 typedef struct _HASH_ALGORITHM
{
390 // ID of the Algorithm
394 // The Key length of the Algorithm
398 // The ICV length of the Algorithm
402 // The block size of the Algorithm
406 // The function pointer of GetContextSize
408 CRYPTO_HASH_GETCONTEXTSIZE HashGetContextSize
;
410 // The function pointer of Initiation
412 CRYPTO_HASH_INIT HashInitiate
;
414 // The function pointer of Hash Update
416 CRYPTO_HASH_UPDATE HashUpdate
;
418 // The fucntion pointer of Hash Final
420 CRYPTO_HASH_FINAL HashFinal
;
424 Get the IV size of specified encryption algorithm.
426 @param[in] AlgorithmId The encryption algorithm ID.
428 @return The value of IV size.
432 IpSecGetEncryptIvLength (
437 Get the block size of specified encryption algorithm.
439 @param[in] AlgorithmId The encryption algorithm ID.
441 @return The value of block size.
445 IpSecGetEncryptBlockSize (
450 Get the required key length of the specified encryption algorithm.
452 @param[in] AlgorithmId The encryption algorithm ID.
454 @return The value of key length.
458 IpSecGetEncryptKeyLength (
463 Get the ICV size of the specified Authentication algorithm.
465 @param[in] AlgorithmId The Authentication algorithm ID.
467 @return The value of ICV size.
476 Get the HMAC digest length by the specified Algorithm ID.
478 @param[in] AlgorithmId The specified Algorithm ID.
480 @return The digest length of the specified Authentication Algorithm ID.
484 IpSecGetHmacDigestLength (
489 Generate a random data for IV. If the IvSize is zero, not needed to create
490 IV and return EFI_SUCCESS.
492 @param[in] IvBuffer The pointer of the IV buffer.
493 @param[in] IvSize The IV size in bytes.
495 @retval EFI_SUCCESS Create random data for IV.
507 This function calls relevant encryption interface from CryptoLib according to
508 the input algorithm ID. The InData should be multiple of block size. This function
509 doesn't perform the padding. If it has the Ivec data, the length of it should be
510 same with the block size. The block size is different from the different algorithm.
512 @param[in] AlgorithmId The Algorithm identification defined in RFC.
513 @param[in] Key Pointer to the buffer containing encrypting key.
514 @param[in] KeyBits The length of the key in bits.
515 @param[in] Ivec Point to the buffer containing the Initialization
517 @param[in] InData Point to the buffer containing the data to be
519 @param[in] InDataLength The length of InData in Bytes.
520 @param[out] OutData Point to the buffer that receives the encryption
523 @retval EFI_UNSUPPORTED The input Algorithm is not supported.
524 @retval EFI_OUT_OF_RESOURCE The required resource can't be allocated.
525 @retval EFI_SUCCESS The operation completed successfully.
529 IpSecCryptoIoEncrypt (
530 IN CONST UINT8 AlgorithmId
,
532 IN CONST UINTN KeyBits
,
533 IN CONST UINT8
*Ivec
, OPTIONAL
535 IN UINTN InDataLength
,
542 This function calls relevant Decryption interface from CryptoLib according to
543 the input algorithm ID. The InData should be multiple of block size. This function
544 doesn't perform the padding. If it has the Ivec data, the length of it should be
545 same with the block size. The block size is different from the different algorithm.
547 @param[in] AlgorithmId The Algorithm identification defined in RFC.
548 @param[in] Key Pointer to the buffer containing encrypting key.
549 @param[in] KeyBits The length of the key in bits.
550 @param[in] Ivec Point to the buffer containing the Initialization
552 @param[in] InData Point to the buffer containing the data to be
554 @param[in] InDataLength The length of InData in Bytes.
555 @param[out] OutData Pointer to the buffer that receives the decryption
558 @retval EFI_UNSUPPORTED The input Algorithm is not supported.
559 @retval EFI_OUT_OF_RESOURCE The required resource can't be allocated.
560 @retval EFI_SUCCESS The operation completed successfully.
564 IpSecCryptoIoDecrypt (
565 IN CONST UINT8 AlgorithmId
,
567 IN CONST UINTN KeyBits
,
568 IN CONST UINT8
*Ivec
, OPTIONAL
570 IN UINTN InDataLength
,
575 Digests the Payload with key and store the result into the OutData.
577 This function calls relevant Hmac interface from CryptoLib according to
578 the input algorithm ID. It computes all datas from InDataFragment and output
579 the result into the OutData buffer. If the OutDataSize is larger than the related
580 HMAC algorithm output size, return EFI_INVALID_PARAMETER.
582 @param[in] AlgorithmId The authentication Identification.
583 @param[in] Key Pointer of the authentication key.
584 @param[in] KeyLength The length of the Key in bytes.
585 @param[in] InDataFragment The list contains all data to be authenticated.
586 @param[in] FragmentCount The size of the InDataFragment.
587 @param[out] OutData For in, the buffer to receive the output data.
588 For out, the buffer contains the authenticated data.
589 @param[in] OutDataSize The size of the buffer of OutData.
591 @retval EFI_UNSUPPORTED If the AuthAlg is not in the support list.
592 @retval EFI_INVALID_PARAMETER The OutData buffer size is larger than algorithm digest size.
593 @retval EFI_SUCCESS Authenticate the payload successfully.
594 @retval otherwise Authentication of the payload fails.
599 IN CONST UINT8 AlgorithmId
,
602 IN HASH_DATA_FRAGMENT
*InDataFragment
,
603 IN UINTN FragmentCount
,
609 Digests the Payload and store the result into the OutData.
611 This function calls relevant Hash interface from CryptoLib according to
612 the input algorithm ID. It computes all datas from InDataFragment and output
613 the result into the OutData buffer. If the OutDataSize is larger than the related
614 Hash algorithm output size, return EFI_INVALID_PARAMETER.
616 @param[in] AlgorithmId The authentication Identification.
617 @param[in] InDataFragment A list contains all data to be authenticated.
618 @param[in] FragmentCount The size of the InDataFragment.
619 @param[out] OutData For in, the buffer to receive the output data.
620 For out, the buffer contains the authenticated data.
621 @param[in] OutDataSize The size of the buffer of OutData.
623 @retval EFI_UNSUPPORTED If the AuthAlg is not in the support list.
624 @retval EFI_SUCCESS Authenticated the payload successfully.
625 @retval EFI_INVALID_PARAMETER If the OutDataSize is larger than the related Hash
626 algorithm could handle.
627 @retval otherwise Authentication of the payload failed.
632 IN CONST UINT8 AlgorithmId
,
633 IN HASH_DATA_FRAGMENT
*InDataFragment
,
634 IN UINTN FragmentCount
,
640 Generates the Diffie-Hellman public key.
642 This function first initiate a DHContext, then call the DhSetParameter() to set
643 the prime and primelength, at end call the DhGenerateKey() to generates random
644 secret exponent, and computes the public key. The output returned via parameter
645 PublicKey and PublicKeySize. DH context is updated accordingly. If the PublicKey
646 buffer is too small to hold the public key, EFI_INVALID_PARAMETER is returned
647 and PublicKeySize is set to the required buffer size to obtain the public key.
649 @param[in, out] DhContext Pointer to the DH context.
650 @param[in] Generator Value of generator.
651 @param[in] PrimeLength Length in bits of prime to be generated.
652 @param[in] Prime Pointer to the buffer to receive the generated
654 @param[out] PublicKey Pointer to the buffer to receive generated public key.
655 @param[in, out] PublicKeySize For in, the size of PublicKey buffer in bytes.
656 For out, the size of data returned in PublicKey
659 @retval EFI_SUCCESS The operation performs successfully.
660 @retval Otherwise The operation is failed.
664 IpSecCryptoIoDhGetPublicKey (
665 IN OUT UINT8
**DhContext
,
667 IN UINTN PrimeLength
,
668 IN CONST UINT8
*Prime
,
669 OUT UINT8
*PublicKey
,
670 IN OUT UINTN
*PublicKeySize
674 Generates exchanged common key.
676 Given peer's public key, this function computes the exchanged common key, based
677 on its own context including value of prime modulus and random secret exponent.
679 @param[in, out] DhContext Pointer to the DH context.
680 @param[in] PeerPublicKey Pointer to the peer's Public Key.
681 @param[in] PeerPublicKeySize Size of peer's public key in bytes.
682 @param[out] Key Pointer to the buffer to receive generated key.
683 @param[in, out] KeySize For in, the size of Key buffer in bytes.
684 For out, the size of data returned in Key
687 @retval EFI_SUCCESS The operation performs successfully.
688 @retval Otherwise The operation is failed.
692 IpSecCryptoIoDhComputeKey (
693 IN OUT UINT8
*DhContext
,
694 IN CONST UINT8
*PeerPublicKey
,
695 IN UINTN PeerPublicKeySize
,
697 IN OUT UINTN
*KeySize
701 Releases the DH context. If DhContext is NULL, return EFI_INVALID_PARAMETER.
703 @param[in, out] DhContext Pointer to the DH context to be freed.
705 @retval EFI_SUCCESS The operation performs successfully.
706 @retval EFI_INVALID_PARAMETER The DhContext is NULL.
710 IpSecCryptoIoFreeDh (
711 IN OUT UINT8
**DhContext
715 Generates random numbers of specified size.
717 If the Random Generator wasn't initiated, initiate it first, then call RandomBytes.
719 @param[out] OutBuffer Pointer to buffer to receive random value.
720 @param[in] Bytes Size of random bytes to generate.
722 @retval EFI_SUCCESS The operation performs successfully.
723 @retval Otherwise The operation is failed.
727 IpSecCryptoIoGenerateRandomBytes (
728 OUT UINT8
* OutBuffer
,
733 Authenticate data with the certificate.
735 @param[in] InData Pointer to the Data to be signed.
736 @param[in] InDataSize InData size in bytes.
737 @param[in] PrivateKey Pointer to the private key.
738 @param[in] PrivateKeySize The size of Private Key in bytes.
739 @param[in] KeyPassWord Pointer to the password for retrieving private key.
740 @param[in] KeyPwdSize The size of Key Password in bytes.
741 @param[out] OutData The pointer to the signed data.
742 @param[in, out] OutDataSize Pointer to contain the size of out data.
746 IpSecCryptoIoAuthDataWithCertificate (
749 IN UINT8
*PrivateKey
,
750 IN UINTN PrivateKeySize
,
751 IN UINT8
*KeyPassWord
,
754 IN OUT UINTN
*OutDataSize
758 Verify the singed data with the public key which is contained in a certificate.
760 @param[in] InCert Pointer to the Certificate which contains the
762 @param[in] CertLen The size of Certificate in bytes.
763 @param[in] InCa Pointer to the CA certificate
764 @param[in] CaLen The size of CA certificate in bytes.
765 @param[in] InData Pointer to octet message hash to be checked.
766 @param[in] InDataSize Size of the message hash in bytes.
767 @param[in] Singnature The pointer to the RSA PKCS1-V1_5 signature to be verified.
768 @param[in] SigSize Size of signature in bytes.
770 @retval TRUE Valid signature encoded in PKCS1-v1_5.
771 @retval FALSE Invalid signature or invalid RSA context.
775 IpSecCryptoIoVerifySignDataByCertificate (
782 IN UINT8
*Singnature
,
787 Retrieves the RSA Public Key from one X509 certificate (DER format only).
789 @param[in] InCert Pointer to the certificate.
790 @param[in] CertLen The size of the certificate in bytes.
791 @param[out] PublicKey Pointer to the retrieved public key.
792 @param[out] PublicKeyLen Size of Public Key in bytes.
794 @retval EFI_SUCCESS Successfully get the public Key.
795 @retval EFI_INVALID_PARAMETER The CA certificate is malformed.
799 IpSecCryptoIoGetPublicKeyFromCert (
802 OUT UINT8
**PublicKey
,
803 OUT UINTN
*PublicKeyLen
807 Retrieves the subject name from one X509 certificate (DER format only).
809 @param[in] InCert Pointer to the X509 certificate.
810 @param[in] CertSize The size of the X509 certificate in bytes.
811 @param[out] CertSubject Pointer to the retrieved certificate subject.
812 @param[out] SubjectSize The size of Certificate Subject in bytes.
814 @retval EFI_SUCCESS Retrieved the certificate subject successfully.
815 @retval EFI_INVALID_PARAMETER The certificate is malformed.
819 IpSecCryptoIoGetSubjectFromCert (
822 OUT UINT8
**CertSubject
,
823 OUT UINTN
*SubjectSize