Crypto Bin Package

Version 20190329.0.4

Copyright (C) Microsoft Corporation. All rights reserved. SPDX-License-Identifier: BSD-2-Clause-Patent

About

The purpose of this package is to provide a wrapper around BaseCryptLib without having to compile the EFI. In theory, linking against BaseCryptLib should give you a higher rate of compression since it will inline code, but in practice the linker gets clever and messes things up.

It is comprised of a Library Instance that is called SharedCryptoLib. It is contains many of the functions included by BaseCryptLib as well as a few more (mainly X509 related stuff). The library simply locates the protocol and then calls the protocol version of BaseCryptLib (SharedCryptoProtocol). It should be a drop in replacement for the BaseCryptLib. Alternatively, you call the protocol directly.

The protocol is installed by a prebuilt EFI that gets downloaded via nuget. The EFI is packaged for consumption via an INF that is loaded and installed.

Diagram showing dependencies

Building SharedCryptoPkg

There are two pieces to be build: the library and the driver. The library is to be included in your project

There are 24 different versions of the prebuild driver. One for each arch (X86, AARCH64, ARM, X64) and for each phase (DXE, PEI, SMM) and for mode (DEBUG, RELEASE). The nuget system should take care of downloading the correct version for your project.

Supported Functions

  • Pkcs
  • PKCS1_ENCRYPT_V2 Encrypts a blob using PKCS1v2 (RSAES-OAEP) schema. On success, will return the encrypted message in a newly allocated buffer.
  • PKCS5_PW_HASH Hashes a password using Pkcs5
  • PKCS7_VERIFY_EKU Receives a PKCS7 formatted signature, and then verifies that the specified EKU's are present in the end-entity leaf signing certificate
  • PKCS7_VERIFY Verifies the validity of a PKCS7 signed data. The data can be wrapped in a ContentInfo structure.
  • RSA
  • RSA_VERIFY_PKCS1 Verifies the RSA-SSA signature with EMSA-PKCS1-v1_5 encoding scheme defined in RSA PKCS1
  • RSA_FREE Release the specified RSA context
  • RSA_GET_PUBLIC_KEY_FROM_X509 Retrieve the RSA Public Key from one DER-encoded X509 certificate.
  • SHA
  • SHA1_GET_CONTEXT_SIZE Retrieves the size, in bytes, of the context buffer required for SHA-1 hash operations.
  • SHA1_INIT Initializes user-supplied memory pointed by Sha1Context as SHA-1 hash context for subsequent use.
  • SHA1_DUPLICATE Makes a copy of an existing SHA1 context
  • SHA1_UPDATE Digests input and updates SHA content
  • SHA1_FINAL Completes computation of SHA1 digest values
  • SHA1_HASH_ALL Computes the SHA1 message digest of an data buffer
  • SHA256_GET_CONTEXT_SIZE Retrieves the size, in bytes, of the context buffer required for SHA-256 hash operation
  • SHA256_INIT Initializes user-supplied memory pointed by Sha1Context as SHA-256 hash context for subsequent use.
  • SHA256_DUPLICATE Makes a copy of an existing SHA256 context
  • SHA256_UPDATE Digests input and updates SHA content
  • SHA256_FINAL Completes computation of SHA256 digest values
  • SHA256_HASH_ALL Computes the SHA256 message digest of an data buffer
  • X509
  • X509_GET_SUBJECT_NAME retrieve the subject bytes from one X.509 cert
  • X509_GET_COMMON_NAME Retrieve the common name (CN) string from one X.509 certificate.
  • X509_GET_ORGANIZATION_NAME Retrieve the organization name (O) string from one X.509 certificate.
  • MD5 +
  • Hmac
  • HMAC_SHA256_GetContextSize
  • HMAC_SHA256_New
  • HMAC_SHA256_Free
  • HMAC_SHA256_Init
  • HMAC_SHA256_Duplicate
  • HMAC_SHA256_Update
  • HMAC_SHA256_Final
  • HMAC_SHA1_GetContextSize
  • HMAC_SHA1_New
  • HMAC_SHA1_Free
  • HMAC_SHA1_Init
  • HMAC_SHA1_Duplicate
  • HMAC_SHA1_Update
  • HMAC_SHA1_Final
  • Random
  • RANDOM_Bytes Generates a pseudorandom byte stream of the specified size
  • RANDOM_Seed Sets up the seed value for the pseudorandom number generator.

Supported Architectures

This currently supports x86, x64, AARCH64, and ARM.

Including in your platform

There are two ways to include this in your project: getting the protocol directly or using SharedCryptoLib. SharedCryptoLib is a wrapper that is a super set of the API for BaseCryptLib so you can just drop it in.

Sample DSC change

This would replace where you would normally include BaseCryptLib.

[LibraryClasses.X64]
    BaseCryptLib|SharedCryptoPkg/Library/SharedCryptoLib/SharedCryptoLibDxe.inf
    ...

[LibraryClasses.IA32.PEIM]
    BaseCryptLib|SharedCryptoPkg/Library/SharedCryptoLib/SharedCryptoLibPei.inf
    ...

[LibraryClasses.DXE_SMM]
    BaseCryptLib|SharedCryptoPkg/Library/SharedCryptoLib/SharedCryptoLibSmm.inf
    ...

Sample FDF change

TODO: re-evaluate this once nuget dependency is live Include this file in your FV and the module will get loaded.

[FV.FVDXE]
    INF  SharedCryptoPkg/Package/SharedCryptoPkgDxe.inf
    ...
    ...