American Megatrends, Inc.

Aptio4 Crypto API

Copyright

Release Notes

© American Megatrends, Inc.


Release Notes - NDA Required

Information: THIS MODULE INCLUDES 3rd PARTY OPEN SOURCE LIBRARY

Component Name: Aptio cryptographic library and EFI APIs.

Component Type: PEI, DXE BS, DXE RT driver

AMI BIOS Core: Aptio 4.6.5.x

Location on SourceSafe: $:Alaska/BIN/Modules/CryptoPkg/;

Label: 4.6.5.x_CRYPTOAPI_020

Date: 01-17-2014

Component Description:

Crypto Library, PPI and UEFI Protocol for basic crypto operations:

Rsa2048, MD5, Sha256, Sha1, x509, PKCS7, PKCS1, DER ASN1.1, BER

Porting Guide: AMI_Aptio_4.6.x_Ami_Crypto_Package_Porting_Guide_NDA.doc

This module includes 3-rd party Open Source library code. Please refer to the section: 3rd Party Code section later in this document

AMI Build Tools:

Tools Label: 4.5.5_TOOLS_35, Dated: 2011-03-29

Visual eBios: RSS.5.70, Dated: 2010-10-06

Files changed in the Reference Code:

Modules update from last label:

* Required Fixes are in Red

Modules added to this label:

Modules removed from last label:

none

New features added in this label:

none

General Bug Fixes:

CryptoLib(x64,Pei).lib

1. Pkcs7 certificate chain validate. Fixed a bug with falsely identify match for leaf certificates if only Issuer names were a match

2. x509. Fix for Bleichenbacher's Pkcs#1v1.5 RSA signature vulnerability: Hash field must be aligned to right of the decoded sig.

An obscure condition possible only for rsa key e = 3

EIP addressed in this label:

Files changed for EIP fixes:

CryptoLib(x64,Pei).lib

Known issues and limitations in this label:

Section 12: Remaining Issues:

ISSUE AND DESCRIPTION

Unit Testing:

DOCUMENT ANY UNIT TESTING DONE BY ENGINEERING

Validation Testing:

DOCUMENT ANY BQA TESTING RESULTS

3rd Party Code Present in Component:

Aptio Crypto Library is based on Open Source crypto library (wpa_supplicant).

This Crypto library module is based on Open standard Crypto library – wpa_supplicant

and is built to function under UEFI environment.

It is dual-licensed under both the GPL version 2 and BSD license.

Either license may be used at your option.

WPA stands for Wi-Fi Protected Access, a wireless encryption standard.

Wpa_supplicant is a well-known open source implementation of WPA and WPA2 (IEEE 802.11i / RSN).

It is suitable for both desktop/laptop computers and embedded systems.

The core library provides basic TLS/crypto implementation for:

-TLSv1

-X.509 certificate processing

-PKCS #1

-ASN.1

-RSA

-bignum

(See http://hostap.epitest.fi/wpa_supplicant/ for more information for wpa_supplicant).

Release History:

4.6.5.x_CRYPTOAPI_019

CryptoLib(x64,Pei).lib: Fix provided for SCT tests that may use corrupted certificate during SetVariable() update: do a full leaf certificate binary comparison and not

just the public key portion

4.6.5.x_CRYPTOAPI_018

EIP#138512; 136764; 137431; 135555 and 134210: SCT issue reported due to improper parameter check inside CryptoLib->Pkcs7_x509_return_cert_pubKey()

Can't launch some OEM signed Efi utilities: replace check for uninitialized parameter inside CryptoLib->Pkcs7_certificate_validate_digest(

4.6.5.x_CRYPTOAPI_017

EIP#118850: Implement support for UEFI2.4 ECR 1009: Certificate Revocation Storage reduction and Timestamp Support.

AmiDigitalSignature.h: Add UEFI TimeStamp certificate definitions; add new Pkcs7 operation code–Pkcs7TimeStampCertVerifyGet

CryptoApi.sdl:New PKCS7_MUTEX_LOCK: Turn on mutex functionality for Pkcs7Verify back to back operations. Preserves internal context until mutex released/reset

CryptoDxe.c: Pkcs7Verify() – add TimeStamp signature processing(UEFI ECR1009); enable code branch for PKCS7_MUTEX_LOCK

CryptoLib.h: Expose TimeStamp validation functions: Pkcs7_certificate_validate_timestamp_digest, os_mktime, Pkcs7_x509_certificate_chain_validate_with_timestamp

4.6.5.x_CRYPTOAPI_016

AmiCertificate.h:Added Platform FwKey HOB structure

CryptoAPI.sdl: Add Token: CONFIG_PEI_PKCS7 to Support x509 & Pkcs7 in PEI CryptoLib. Add to CryptoPEI binary size ~8kb .

CryptoPei.c;CryptoDxe.c Improve FwKey handling. CryptoPEI pass FwKey location to Dxe via a Hob;

CryptoPei.c; Add dependency on CONFIG_PEI_PKCS7. Decrease code size if Pkcs7 support if off;

CryptoLib.h;Expose MD5 hash library function: md5_vector()

4.6.5.x_CRYPTOAPI_015

CryptoDxe.c: GetKey(): fix MemCpy() 2nd argument. Was not copying a key buffer

4.6.5.x_CRYPTOAPI_014

EIP#110823: The system cannot boot to UEFI(WIN8) OS if the Secure Flash Pkg module is not supported

CryptoDxe.c Update GetKey(); InSmmFunction() and NotInSmmFunction() routines to handle cases when Fw Key FFS file not present, e.g. no SecureFlash

eModule. Previous logic would not install Crypto API if no FW Key found

4.6.5.x_CRYPTOAPI_013

CryptoLib(x64,Pei).lib:EIP#108747 :Library files built in debug mode in the latest label 4.6.5.x_CRYPTOAPI_012

Removed printing of EfiTime... string in release mode

CryptoDxe.c Bug fix: Failure to validate new FwCapsule image under WinXP. InSmmFunction() the Key pointer gKeyBuf was not set to valid Key Buf in SMM

region. Pkcs7Verify()- fix error checking for input **Data parameter. Old: *Data!=NULL. New: Data != NULL

4.6.5.x_CRYPTOAPI_012

EIP#105015: Request to implement Pkcs7# Certificate signing in Aptio Fw Capsule update packages

EIP#102807: Ignore leaf certificate signature validation error if its public key matches the one found in a trusted certificate pool.

EIP#106441: REF-28581: SCT Execution - Auth Variable Error. Add MD5 Hash algorithm

-CryptoLib.Lib: -Add MD5 to list of supported Hash algorithms. SCT UEFI 2.3.1.c includes test packages signed using MD5 and RSA1024. While is does go not against UEFI spec, it

creates a security hole for Win8 bound platforms where use of MD5 hashing algorithm is prohibited

-Pkcs7 - ignore leaf certificate signature validation if it is found in trusted certificate pool

-Enable Pkcs#7 Certificate parsing in PEI instance of CryptoLib. Required to process signed Aptio Fw Capsules

-Added support for x509 DER formatted Platform Fw Key

-Increase heap size of internal PEI Crypto mem manager to 48k

4.6.5.x_CRYPTOAPI_011

EIP#104639: Failed to process Microsoft Test Signed bootmgfw.efi. Pkcs7_validate logic changed to process all certs in the cert store. Old logic skipped through the chain until Signing

cert match found

EIP#104046: Findings from Security review on Aptio4 Image verification. Include the fix for item #1: malloc() - check for potential mem heap overflow : max allocation mem size must

be less then the max number of Pages that can stored within UINT8 = 256*256=64kb

4.6.5.0_CRYPTOAPI_010

Cryptlib(x64).lib:

EIP#101406: Secure Boot Manual Logo test: Fail. Msft KEK leaf certificate has expired on 9/16/2012. According to Microsoft communication: UEFI Secure Boot should ignore certificate

expiration and this test case should continue to function

4.6.5.0_CRYPTOAPI_008

Protocol/AmiDigitalSignature.h

CryptoDxe.c

1. Pkcs7Verify() added new Pkcs7 operations:

Pkcs7CertValidateGetSignerKey - n-modulus of Signer key

Pkcs7CertGetMatchInCertChain - true if found a leaf cert matching to trust cert

Pkcs7CertValidateGetCAKey - n-modulus of CA key if detected in x509 chain

Pkcs7GetCAKey

Pkcs7GetSignerKey

2. UEFI 2.3.1. Errata C:

Added support for new Hash types defined by a GUID with 'NOPAD' keyword:

EFI_HASH_ALGORITHM_SHA1_NOPAD_GUID EFI_HASH_ALGORITHM_SHA256_NOPAD_GUID

Cryptlib(x64).lib

Add check for leaf certificates matching a trusted one only for Signer certificate and all others chained to Signed certificates.

Enable multi-level certificate chaining within PKCS#7 Certificate.

Add new lib function: Pkcs7_x509_return_Cert_pubKey() to return a pointer within x509 certificate to a public key.

Used by CryptoDXE: Pkcs7Verify to extract n-Modulus of a public key within given x509 Key certificate

Enhanced x509 certificate name parsing: Compress Unicode strings by removing zeroes between the characters.

4.6.5.0_CRYPTOAPI_008

AmiCertificate.h – add Extended FwCapsule GUID flags

CryptoDxe.c – EIP89280: When secure boot enable with secure flash disable, in Security page of setup menu same items will exist twice

Fix: Install Crypto Protocols even if Root FW Key not found (key’s comes with Secure Flash eModule4.6.5.0_CRYPTOAPI_007

CryptoDxe.c – PKCS#7 not able to process leaf layer certificate from x509 cert chain. Add new function to process leaf certificates in the cert chain: Crypto DXE

API call VerifyPkcs7()

4.6.5.0_CRYPTOAPI_0006

CryptoPei.c: Try different Ffs GUIDs to select proper FW Key format: SHA or RSA. Do not install Crypto PPI on S3 resume.

CryptoDxe.c : Add VerifyKey Function. Process VerifyKey according to the Key file format(SHA256 or RSA2048). Hash input RSA2048 key for comparison if PR Key stored as Hash

Fix GetKey (API call will be deprecated as not needed) to move PR Key from file to local storage.

AmiCertificate.h Add PR_KEY_FFS_FILE_SHA256_GUID for PR Key file in SHA256 Hash format

AmiDigitalSignature.h Add VerifyKey Protocol function to match Crypto PEI API

4.6.5.0_CRYPTOAPI_0005

Added BSD license disclaimer to Main Page of cryptlib.chm and added a separate licene.txt file to Crypto LIB module part.

4.6.5.0_CRYPTOAPI_0004

CryptoDxe.c : InSmmFunction()->InstallMultipleProtocols(). Change the Handle argument from ImageHandle to a DummyHandle=NULL

4.6.5.0_CRYPTOAPI_0003

CryptoDxe.c: GetRawImage: added freepool(HandleBuffer); AmiCertificate.h: removed obsolete FW capsule structures

Crypto*.lib : updated Pkcs7 parser to support SDK interpretation of AuthVariable signature format matching Msft Authenticode SignedData (will be obsolete after SCT 2.3.1 Alpha)

Fix WDK Level4 compiler warnings. Crypto library built using Windows Driver Kit version 7.0.1(Build 7600.16385.1)

Certificate_chain_validate: 1. Ignore Cert TimeSptamp check and CA attribute for Trusted Certs; Get the Time stamp at the Crypto Lib init. Fixed Win8 hang in pRS->GetTime in VirtualAddress mode; Win8 w/a. Stop displaying Debug traces once switched to VirtualAddress mode

Added new Pkcs7 parse Operation: Pkcs7CertValidateGetSignerKeyHash. Fix required to support Self-Signed Authenticated variables.

Crypto*.lib : updated library with new features-> add new function: Pkcs7_x509_return_signing_Key; include traces in release library. Traces enabled by setting SDL Token Crypto_trace_level to 1 or 2; Update GetTime functionality. Not called in Virtual Addr mode

© American Megatrends Inc.


Function by File Name

AMIBIOS Function Reference

By File Name

The following is a list of the source files.
For a list in alphabetical order, see In Alphabetical Order.

  • AmiCertificate.h
  • AmiDigitalSignature.h
  • CryptoDxe.c
  • CryptoPei.c
  • CryptoPPI.h
Built on 14:25:16 01/17/14


AmiCertificate.h

Description:
AMI FW Certificate defines and data structures

The following data structures are used in the file: AmiCertificate.h.

Variable | Description
AMI_CERTIFICATE_RSA2048_SHA256 | Certificate which encapsulates the UEFI RSA2048_SHA256 digital signature. The WIN_CERTIFICATE_UEFI_GUID structure is derived from WIN_CERTIFICATE and encapsulate the information needed to implement the digital signature algorithm Hdr.Hdr.wRevision = 0x0200 Hdr.Hdr.wCertificateType = 0x0EF1; WIN_CERT_TYPE_EFI_GUID Hdr.CertType = EFI_CERT_TYPE_RSA2048_SHA256_GUID;
APTIO_FW_CAPSULE_HEADER | Enhanced APTIO FW CAPSULE with certificate and the map of the modules in the capsule's volume to be included into the signature calculation
FW_CERTIFICATE | Aptio FW Capsule certificate block


AMI_CERTIFICATE_RSA2048_SHA256 in the AmiCertificate.h

Variable : AMI_CERTIFICATE_RSA2048_SHA256

File: AmiCertificate.h
Fields:

Name | Type | Description
Hdr | WIN_CERTIFICATE_UEFI_GUID | encapsulate the information needed to implement the digital signature algorithm
CertData | EFI_CERT_BLOCK_RSA_2048_SHA256 | Signature and Public key

Description:
Certificate which encapsulates the UEFI RSA2048_SHA256 digital signature.

The WIN_CERTIFICATE_UEFI_GUID structure is derived from
WIN_CERTIFICATE and encapsulate the information needed to
implement the digital signature algorithm
Hdr.Hdr.wRevision = 0x0200
Hdr.Hdr.wCertificateType = 0x0EF1; WIN_CERT_TYPE_EFI_GUID
Hdr.CertType = EFI_CERT_TYPE_RSA2048_SHA256_GUID;


APTIO_FW_CAPSULE_HEADER in the AmiCertificate.h

Variable : APTIO_FW_CAPSULE_HEADER

File: AmiCertificate.h
Fields:

Name | Type | Description
Name | Type | Description
CapHdr | EFI_CAPSULE_HEADER | UEFI 2.0 Capsule Hdr. Use APTIO_FW_CAPSULE_2_GUID
RomImageOffset | UINT16 | offset within the Fw Capsule header to the FW image
RomLayoutOffset | UINT16 | offset to the FW discriptor table used for signature calculation
FWCert | FW_CERTIFICATE | Certificate block. Format may change based on WIN_CERTIFICATE header Type.
Hdr | CertType | = EFI_CERT_TYPE_RSA2048_SHA256_GUID
Hdr | CertType | = EFI_CERT_TYPE_PKCS7_GUID
RomAreaMap | ROM_AREA
Payload

Description:
Enhanced APTIO FW CAPSULE with certificate and the map of the modules in the
capsule's volume to be included into the signature calculation


FW_CERTIFICATE in the AmiCertificate.h

Variable : FW_CERTIFICATE

File: AmiCertificate.h
Fields:

Name | Type | Description
SignCert | AMI_CERTIFICATE_RSA2048_SHA256 | Certificate contains a signature of a Capsule's payload and Signer's public key
RootCert | EFI_CERT_BLOCK_RSA_2048_SHA256 | Certificate contains a signature of a Signer's public key signed by the
Root | Key | , whose public portion is also included into this certificate.
For | Aptio | FW update process to succeed, either of these keys must match the instance of a Platform FW Key in the Flash.

Description:
Aptio FW Capsule certificate block


AmiDigitalSignature.h

Description:
AMI Digital Signature Protocol Definition

The following tables are used in the file: AmiDigitalSignature.h.

Table | Description
PKCS7_OPERATIONS | Enumerated Pkcs7 Operations. List of different Pkcs7 verify tasks to perform:


PKCS7_OPERATIONS in the AmiDigitalSignature.h

Table : PKCS7_OPERATIONS

File: AmiDigitalSignature.h
Fields:

Name | Number | Description
Pkcs7Arg0 | 0 | Function presence check. Must return EFI_SUCCESS
Pkcs7CertValidate | 1 | Validate Certificate
Pkcs7GetSignerCert | 2 | Return Signer Certificate in *Data. Performs cert chaining and time based validity tests
Pkcs7GetCACert | 3 | Return Root CA certificate referenced by Signer. Used to compare with Trusted Cert in FW
Pkcs7ValidateRootCert | 4 | Validate Root Certificate
x509ValidateCertChain | 5 | Validate Signer Certificate Chain
Pkcs7GetDigestAlgorithm | 6 | Return Signature Digest Algorithm
Pkcs7CertValidateGetCACert | 7 | Validate Pkcs7 Cert, return Root CA Certificate
Pkcs7CertValidateGetSignerCert | 8 | Validate Pkcs7 Cert, return Signer Certificate
Pkcs7CertValidateGetSignerKeyHash | 9 | Validate Pkcs7 Cert, return Signer Key Hash (SHA256)
Pkcs7CertValidateGetMatchInCertChain | 10 | Validate Pkcs7 Cert and return Success if match is found between Trust and any leaf certificates in the Pkcs7 Signer chain
Pkcs7CertValidateGetSignerKey | 11 | Validate Pkcs7 Cert, return ptr in *Data to n-modulus of a Signer Key
Pkcs7CertGetMatchInCertChain | 12 | Return Success if match is found between Trust and any leaf certificates in the Signer chain
Pkcs7CertValidateGetCAKey | 13 | Validate Pkcs7 Cert, return ptr in *Data to n-modulus of a Root CA Key
Pkcs7GetCAKey | 14 | Return ptr in *Data to n-modulus of a Root CA Key
Pkcs7GetSignerKey | 15 | Return ptr in *Data to n-modulus of a Signer Key
Pkcs7TimeStampCertValidateGet | 16 | Validate TimeStamp certificate chain in Pkcs7 Certificate. Return TimeOfSigning

Description:
Enumerated Pkcs7 Operations.
List of different Pkcs7 verify tasks to perform:


CryptoDxe.c

The following functions are used in the file: CryptoDxe.c.

Function | Description
CryptoDxe_Init | Entry point of Crypto DXE driver
CryptoGetFwKey | Passes FwKey info from a Hob to an external Key handler structure
GetKey | Return Firmware Signing Key from a local storage
Hash | Allows creating a Hash of an arbitrary message digest using one or more Hash algorithms
InSmmFunction |
NotInSmmFunction | This function is called from outside of SMM during SMM registration.
Pkcs1Verify | Function verifies that the specified signature matches the specified Hash. Verifies the RSA-SSA signature with EMSA-PKCS1-v1_5 encoding scheme defined in RSA PKCS#1. This function decrypts the signature with the provided key and then compares the decrypted value to the specified Hash value
Pkcs7Verify | Verifies the validity of a PKCS#7 signed data as described in "PKCS #7: Cryptographic Message Syntax Standard". Function perfors several operations on input Pkcs7 certificate based on the input Operation argument 1. Verifies validity of the signature contained inside the Certificate This function decrypts the signature with the Public key from the Signer certificate and then compares the decrypted value to the input Data 2. Extracts the Signer certificate in format of x509 3. Extracts Root CA certificate that used to sign the Signer certificate.
VerifyKey | Function compares the input PublicKey against Platform Signing Key (PK) image in the flash.


CryptoDxe_Init in the CryptoDxe.c

Function : CryptoDxe_Init

File: CryptoDxe.c
Description:
Entry point of Crypto DXE driver
Input:
EFI_HANDLE           ImageHandle,
EFI_SYSTEM_TABLE     *SystemTable
Output:
EFI_STATUS
Modified:
Notes:

Referrals:


CryptoGetFwKey in the CryptoDxe.c

Function : CryptoGetFwKey

File: CryptoDxe.c
Description:
Passes FwKey info from a Hob to an external Key handler structure
Input:
Key       - ptr to the buffer to hold the target key parameters
Output:
Status

EFI_NOT_FOUND  - Can't find the Key Hob
EFI_INVALID_PARAMETER - Wrong KeyID
EFI_LOAD_ERROR - Load fail.
EFI_SUCCESS    - Load success.


GetKey in the CryptoDxe.c

Function : GetKey

File: CryptoDxe.c
Description:
Return Firmware Signing Key from a local storage
Input:
This         Pointer to the AMI_DIGITAL_SIGNATURE_PROTOCOL instance.
Key          ptr to the buffer to hold the target key
AlgId        Key GUID
KeyLen       Length of the target Key buffer
Flags        Specifies additional flags to further customize the GetKey behavior.
Output:
EFI_SUCCESS
EFI_ACCESS_DENIED        The key could not be located
EFI_INVALID_PARAMETER    Wrong KeyID
BUFFER_TOO_SMALL         The Key->BlobSize will contain the size of the buffer to be prepared


Hash in the CryptoDxe.c

Function : Hash

File: CryptoDxe.c
Description:
Allows creating a Hash of an arbitrary message digest using one or more Hash algorithms
Input:
This          Pointer to the AMI_DIGITAL_SIGNATURE_PROTOCOL instance.
HashAlgorithm Points to the EFI_GUID which identifies the algorithm to use.
num_elem      Number of blocks to be passed via next argument:addr[]
addr[]        Pointer to array of UINT8* addresses of data blocks to be hashed
len           Pointer to array of integers containing length of each block listed by addr[]
Hash          Holds the resulting Hash computed from the message.
Output:
EFI_SUCCESS           Hash returned successfully.
EFI_INVALID_PARAMETER Message or Hash is NULL
EFI_UNSUPPORTED       The algorithm specified by HashAlgorithm is not supported by this
             driver.


InSmmFunction in the CryptoDxe.c

Function : InSmmFunction

File: CryptoDxe.c
Description:
Input:
Output:
Returns:


NotInSmmFunction in the CryptoDxe.c

Function : NotInSmmFunction

File: CryptoDxe.c
Description:
This function is called from outside of SMM during SMM registration.
Input:
IN EFI_HANDLE       ImageHandle
IN EFI_SYSTEM_TABLE *SystemTable
Output:
EFI_STATUS


Pkcs1Verify in the CryptoDxe.c

Function : Pkcs1Verify

File: CryptoDxe.c
Description:
Function verifies that the specified signature matches the specified Hash.
  Verifies the RSA-SSA signature with EMSA-PKCS1-v1_5 encoding scheme defined in
  RSA PKCS#1.
  This function decrypts the signature with the provided key and then compares
  the decrypted value to the specified Hash value
Input:
This          Pointer to the AMI_DIGITAL_SIGNATURE_PROTOCOL instance.
PublicKey     Handle to a key used for verifying signatures. This handle must be identifying a public key.
Hash          Handle of the Hash object to verify.
Signature     Pointer to the signature data to be verified.
SignatureSize The size, in bytes, of the signature data.
Flags         Specifies additional flags to further customize the signing/verifying behavior.
Output:
EFI_SUCCESS              The signature is successfully verified.
EFI_SECURITY_VIOLATION   The signature does not match the given message.
EFI_ACCESS_DENIED        The key could not be used in signature operation.
EFI_INVALID_PARAMETER    The size of input message or signature does not meet the criteria
              of the underlying signature algorithm.


Pkcs7Verify in the CryptoDxe.c

Function : Pkcs7Verify

File: CryptoDxe.c
Description:
Verifies the validity of a PKCS#7 signed data as described in "PKCS #7: Cryptographic
  Message Syntax Standard".
  Function perfors several operations on input Pkcs7 certificate
  based on the input Operation argument
  1. Verifies validity of the signature contained inside the Certificate
     This function decrypts the signature with the Public key from the Signer certificate
     and then compares the decrypted value to the input Data
  2. Extracts the Signer certificate in format of x509
  3. Extracts Root CA certificate that used to sign the Signer certificate.
Input:
This         Pointer to the AMI_DIGITAL_SIGNATURE_PROTOCOL instance.
P7Data       Pointer to the PKCS#7 DER encoded message to verify.
P7Size       Size of the PKCS#7 message in bytes.
TrustedCert  Pointer to a trusted/root X509 certificate encoded in DER, which
    is used for certificate chain verification.
CertSize     Size of the trusted certificate in bytes.
Data         Pointer to the content to be verified/returned at
DataSize     Size of Data in bytes
Operation    Specifies different tasks to perform:
    0-Function presence check. Must return EFI_SUCCESS
    1-Validate Certificate
    2-Return Signer Certificate in *Data. Performs cert chaining and time based validity tests
    3-Return Root CA certificate referenced by Signer. Used to compare with Trusted Cert in FW
    4-Validate Root Certificate
    5-Validate Signer Certificate Chain
    6-Return Signature Digest Algorithm
    7-Validate Certificate, return Root CA Certificate
    8-Validate Certificate, return Signer Certificate
    9-Validate Certificate, return Signer Key Hash (SHA256)
    10-Validate Certificate and return Success if match is found between Trust and any leaf certificates in the Signer chain
    11-Validate Certificate, return ptr in *Data to n-modulus of a Signer Key
    12-Return Success if match is found between Trust and any leaf certificates in the Signer chain
    13-Validate Certificate, return ptr in *Data to n-modulus of a Root CA Key
    14-Return ptr in *Data to n-modulus of a Root CA Key
    15-Return ptr in *Data to n-modulus of a Signer Key
    16-Validate TimeStamp certificate chain in Pkcs7 Certificate
    17-255 reserved values
Flags        Specifies additional flags to further customize the signing/verifying behavior.
Output:
EFI_SUCCESS              The specified PKCS#7 signed data is valid
EFI_SECURITY_VIOLATION   Invalid PKCS#7 signed data.
EFI_ACCESS_DENIED        The Trusted certificate does not have a match in SignedData.certificate store.
EFI_INVALID_PARAMETER    The size of input message or signature does not meet the criteria
              of the underlying signature algorithm.


VerifyKey in the CryptoDxe.c

Function : VerifyKey

File: CryptoDxe.c
Description:
Function compares the input PublicKey against
  Platform Signing Key (PK) image in the flash.
Input:
This            Pointer to the AMI_DIGITAL_SIGNATURE protocol instance.
KeyAlgorithm    Points to the EFI_GUID which identifies the PKpub algorithm to use.
PublicKey       Handle to a key used for verifying signatures.  This handle must be identifying a public key.
Output:
EFI_SUCCESS               The Key is successfully verified.
EFI_SECURITY_VIOLATION    The Key does not match current FW key.
EFI_ACCESS_DENIED         The key could not be used in signature operation.
EFI_INVALID_PARAMETER     The size of input message or signature does not meet the criteria
               of the underlying signature algorithm.


CryptoPei.c

The following functions are used in the file: CryptoPei.c.

Function | Description
CryptoGetRawImage | Loads binary from RAW section of X firwmare volume
CryptoPei_Init | This function is the entry point for this PEI.
PeiGetKey | Function returns Ptr to a Platform Signing Key (PK) Ffs inside Recovery FV (FV_BB or similar)
PeiHash | Allows creating a Hash of an arbitrary message digest using one or more Hash algorithms
PeiPkcs7Verify | Verifies the validity of a PKCS#7 signed data as described in "PKCS #7: Cryptographic Message Syntax Standard". Function verifies validity of the signature contained inside the Certificate This function decrypts the signature with the Public key from the Signer certificate and then compares the decrypted value to the input Data
PeiVerifyKey | Function compares the input PublicKey against Platform Signing Key (PK) image in the flash.
PeiVerifySig | Function verifies that the specified signature matches the specified Hash. This function decrypts the signature with the provided key and then compares the decrypted value to the specified Hash value


CryptoGetRawImage in the CryptoPei.c

Function : CryptoGetRawImage

File: CryptoPei.c
Description:
Loads binary from RAW section of X firwmare volume
Output:
Buffer - returns a pointer to allocated memory. Caller
           must free it when done.
   Size  - returns the size of the binary loaded into the
           buffer.


CryptoPei_Init in the CryptoPei.c

Function : CryptoPei_Init

File: CryptoPei.c
Description:
This function is the entry point for this PEI.
Input:
FfsHeader   Pointer to the FFS file header
PeiServices Pointer to the PEI services table
Output:
Return Status based on errors that occurred while waiting for
time to expire.


PeiGetKey in the CryptoPei.c

Function : PeiGetKey

File: CryptoPei.c
Description:
Function returns Ptr to a Platform Signing Key (PK) Ffs
  inside Recovery FV (FV_BB or similar)
Input:
This            Pointer to the AMI_CRYPT_DIGITAL_SIGNATURE_PPI instance.
KeyAlgorithm    Points to the EFI_GUID which identifies the PKpub algorithm to use.
PublicKey       Handle to a key used to return a ptr to a Key. This handle must be identifying a public key.
Output:
EFI_SUCCESS               The Key is successfully returned.
EFI_NOT_FOUND             The Key not found
EFI_ACCESS_DENIED         The key could not be used in signature operation.
EFI_INVALID_PARAMETER     The size of input message or signature does not meet the criteria
               of the underlying signature algorithm.


PeiHash in the CryptoPei.c

Function : PeiHash

File: CryptoPei.c
Description:
Allows creating a Hash of an arbitrary message digest using one or more Hash algorithms
Input:
This          Pointer to the AMI_CRYPT_DIGITAL_SIGNATURE_PPI instance.
HashAlgorithm Points to the EFI_GUID which identifies the algorithm to use.
num_elem      Number of blocks to be passed via next argument:addr[]
addr[]        Pointer to array of UINT8* addresses of data blocks to be hashed
len           Pointer to array of integers containing length of each block listed by addr[]
Hash          Holds the resulting Hash computed from the message.
Output:
EFI_SUCCESS           Hash returned successfully.
EFI_INVALID_PARAMETER Message or Hash is NULL
EFI_UNSUPPORTED       The algorithm specified by HashAlgorithm is not supported by this
             driver.


PeiPkcs7Verify in the CryptoPei.c

Function : PeiPkcs7Verify

File: CryptoPei.c
Description:
Verifies the validity of a PKCS#7 signed data as described in "PKCS #7: Cryptographic
  Message Syntax Standard".
  Function verifies validity of the signature contained inside the Certificate
  This function decrypts the signature with the Public key from the Signer certificate
  and then compares the decrypted value to the input Data
Input:
This         Pointer to the AMI_CRYPT_DIGITAL_SIGNATURE_PPI instance.
P7Data       Pointer to the PKCS#7 DER encoded message to verify.
P7Size       Size of the PKCS#7 message in bytes.
TrustedCert  Pointer to a trusted/root X509 certificate encoded in DER, which
    is used for certificate chain verification.
CertSize     Size of the trusted certificate in bytes.
Data         Pointer to the content to be verified/returned at
DataSize     Size of Data in bytes
Output:
EFI_SUCCESS              The specified PKCS#7 signed data is valid
EFI_SECURITY_VIOLATION   Invalid PKCS#7 signed data.
EFI_ACCESS_DENIED        The Trusted certificate does not have a match in SignedData.certificate store.
EFI_INVALID_PARAMETER    The size of input message or signature does not meet the criteria
              of the underlying signature algorithm.


PeiVerifyKey in the CryptoPei.c

Function : PeiVerifyKey

File: CryptoPei.c
Description:
Function compares the input PublicKey against
  Platform Signing Key (PK) image in the flash.
Input:
This            Pointer to the AMI_CRYPT_DIGITAL_SIGNATURE_PPI instance.
KeyAlgorithm    Points to the EFI_GUID which identifies the PKpub algorithm to use.
PublicKey       Handle to a key used for verifying signatures.  This handle must be identifying a public key.
Output:
EFI_SUCCESS               The Key is successfully verified.
EFI_SECURITY_VIOLATION    The Key does not match current FW key.
EFI_ACCESS_DENIED         The key could not be used in signature operation.
EFI_INVALID_PARAMETER     The size of input message or signature does not meet the criteria
               of the underlying signature algorithm.


PeiVerifySig in the CryptoPei.c

Function : PeiVerifySig

File: CryptoPei.c
Description:
Function verifies that the specified signature matches the specified Hash.
This function decrypts the signature with the provided key and then compares
the decrypted value to the specified Hash value
Input:
This          Pointer to the AMI_CRYPT_DIGITAL_SIGNATURE_PPI instance.
PublicKey     Handle to a key used for verifying signatures. This handle must be identifying a public key.
Hash          Handle of the Hash object to verify.
Signature     Pointer to the signature data to be verified.
SignatureSize The size, in bytes, of the signature data.
Flags         Specifies additional flags to further customize the signing/verifying behavior.
Output:
EFI_SUCCESS               The signature is successfully verified.
EFI_SECURITY_VIOLATION    The signature does not match the given message.
EFI_ACCESS_DENIED         The key could not be used in signature operation.
EFI_INVALID_PARAMETER     The size of input message or signature does not meet the criteria
               of the underlying signature algorithm.


CryptoPPI.h

Description:
AMI Digital Signature Protocol Definition


Functions in Alphabetical Order

In Alphabetical Order

The following topics provide a list in alphabetical order.
For a list by file name, see By File Name.

  • A
  • C
  • F
  • G
  • H
  • I
  • N
  • P
  • V


Functions in Alphabetical Order

A

Data Structure | Description
AMI_CERTIFICATE_RSA2048_SHA256 | Certificate which encapsulates the UEFI RSA2048_SHA256 digital signature. The WIN_CERTIFICATE_UEFI_GUID structure is derived from WIN_CERTIFICATE and encapsulate the information needed to implement the digital signature algorithm Hdr.Hdr.wRevision = 0x0200 Hdr.Hdr.wCertificateType = 0x0EF1; WIN_CERT_TYPE_EFI_GUID Hdr.CertType = EFI_CERT_TYPE_RSA2048_SHA256_GUID;
APTIO_FW_CAPSULE_HEADER | Enhanced APTIO FW CAPSULE with certificate and the map of the modules in the capsule's volume to be included into the signature calculation


Functions in Alphabetical Order

C

Function | Description
CryptoDxe_Init | Entry point of Crypto DXE driver
CryptoGetFwKey | Passes FwKey info from a Hob to an external Key handler structure
CryptoGetRawImage | Loads binary from RAW section of X firwmare volume
CryptoPei_Init | This function is the entry point for this PEI.


Functions in Alphabetical Order

F

Data Structure | Description
FW_CERTIFICATE | Aptio FW Capsule certificate block


Functions in Alphabetical Order

G

Function | Description
GetKey | Return Firmware Signing Key from a local storage


Functions in Alphabetical Order

H

Function | Description
Hash | Allows creating a Hash of an arbitrary message digest using one or more Hash algorithms


Functions in Alphabetical Order

I

Function | Description
InSmmFunction |


Functions in Alphabetical Order

N

Function | Description
NotInSmmFunction | This function is called from outside of SMM during SMM registration.


Functions in Alphabetical Order

P

Function | Description
PeiGetKey | Function returns Ptr to a Platform Signing Key (PK) Ffs inside Recovery FV (FV_BB or similar)
PeiHash | Allows creating a Hash of an arbitrary message digest using one or more Hash algorithms
PeiPkcs7Verify | Verifies the validity of a PKCS#7 signed data as described in "PKCS #7: Cryptographic Message Syntax Standard". Function verifies validity of the signature contained inside the Certificate This function decrypts the signature with the Public key from the Signer certificate and then compares the decrypted value to the input Data
PeiVerifyKey | Function compares the input PublicKey against Platform Signing Key (PK) image in the flash.
PeiVerifySig | Function verifies that the specified signature matches the specified Hash. This function decrypts the signature with the provided key and then compares the decrypted value to the specified Hash value
Pkcs1Verify | Function verifies that the specified signature matches the specified Hash. Verifies the RSA-SSA signature with EMSA-PKCS1-v1_5 encoding scheme defined in RSA PKCS#1. This function decrypts the signature with the provided key and then compares the decrypted value to the specified Hash value
Pkcs7Verify | Verifies the validity of a PKCS#7 signed data as described in "PKCS #7: Cryptographic Message Syntax Standard". Function perfors several operations on input Pkcs7 certificate based on the input Operation argument 1. Verifies validity of the signature contained inside the Certificate This function decrypts the signature with the Public key from the Signer certificate and then compares the decrypted value to the input Data 2. Extracts the Signer certificate in format of x509 3. Extracts Root CA certificate that used to sign the Signer certificate.

Table | Description
PKCS7_OPERATIONS | Enumerated Pkcs7 Operations. List of different Pkcs7 verify tasks to perform:


Functions in Alphabetical Order

V

Function | Description
VerifyKey | Function compares the input PublicKey against Platform Signing Key (PK) image in the flash.


General Information


Copyright

American Megatrends, Inc.
5555 Oakbrook Parkway
Suite 200
Norcross, GA 30093 (USA)

Copyright (c) 1999-2014 American Megatrends, Inc. All Rights Reserved.

This publication contains proprietary information, which is protected by copyright. No part of this publication may be reproduced, transcribed, stored in a retrieval system, translated into any language or computer language, or transmitted in any form whatsoever without the prior written consent of the publisher, American Megatrends, Inc.

American Megatrends, Inc. retains the right to update, change, modify this publication at any time, without notice.

For Additional Information

Call American Megatrends BIOS Sales Department at 1-800-828-9264 for additional information.

Limitations of Liability

In no event shall American Megatrends be held liable for any loss, expenses, or damages of any kind whatsoever, whether direct, indirect, incidental, or consequential, arising from the design or use of this product or the support materials provided with the product.

Limited Warranty

No warranties are made, either expressed or implied, with regard to the contents of this work, its merchantability, or fitness for a particular use. American Megatrends assumes no responsibility for errors and omissions or for the uses made of the material contained herein or reader decisions based on such use.

Trademark and Copyright Acknowledgments

All product names used in this publication are for identification purposes only and are trademarks of their respective Companies.