[edk2-devel] [PATCH 1/4] CryptoPkg: add new X509 function definition.
Yao, Jiewen
jiewen.yao at intel.com
Mon Oct 10 00:34:15 UTC 2022
Hi
I feel the function name X509SetDateTime() is very confusing. From the function comment, it means: "Format a DateTime object into DataTime Buffer".
I also find the comment in X509GetValidity(), "x509SetDateTime to get a DateTime object from a DateTimeStr"
It seems "DataTimeStr" is " DateTime string like YYYYMMDDhhmmssZ "
So what is the relationship among "DateTime object", "DateTime Buffer", and "DateTime Str" ?
> -----Original Message-----
> From: Zhang, Qi1 <qi1.zhang at intel.com>
> Sent: Sunday, September 25, 2022 4:54 PM
> To: devel at edk2.groups.io
> Cc: Zhang, Qi1 <qi1.zhang at intel.com>; Yao, Jiewen
> <jiewen.yao at intel.com>; Wang, Jian J <jian.j.wang at intel.com>; Lu, Xiaoyu1
> <xiaoyu1.lu at intel.com>; Jiang, Guomin <guomin.jiang at intel.com>
> Subject: [PATCH 1/4] CryptoPkg: add new X509 function definition.
>
> REF: https://bugzilla.tianocore.org/show_bug.cgi?id=4082
>
> Cc: Jiewen Yao <jiewen.yao at intel.com>
> Cc: Jian J Wang <jian.j.wang at intel.com>
> Cc: Xiaoyu Lu <xiaoyu1.lu at intel.com>
> Cc: Guomin Jiang <guomin.jiang at intel.com>
> Signed-off-by: Qi Zhang <qi1.zhang at intel.com>
> ---
> CryptoPkg/Include/Library/BaseCryptLib.h | 374
> +++++++++++++++++++++++
> 1 file changed, 374 insertions(+)
>
> diff --git a/CryptoPkg/Include/Library/BaseCryptLib.h
> b/CryptoPkg/Include/Library/BaseCryptLib.h
> index 3026299e29..d7bf29c93f 100644
> --- a/CryptoPkg/Include/Library/BaseCryptLib.h
> +++ b/CryptoPkg/Include/Library/BaseCryptLib.h
> @@ -2459,6 +2459,380 @@ ImageTimestampVerify (
> OUT EFI_TIME *SigningTime
>
> );
>
>
>
> +/**
>
> + Retrieve the version from one X.509 certificate.
>
> +
>
> + If Cert is NULL, then return FALSE.
>
> + If CertSize is 0, then return FALSE.
>
> + If this interface is not supported, then return FALSE.
>
> +
>
> + @param[in] Cert Pointer to the DER-encoded X509 certificate.
>
> + @param[in] CertSize Size of the X509 certificate in bytes.
>
> + @param[out] Version Pointer to the retrieved version integer.
>
> +
>
> + @retval TRUE The certificate version retrieved successfully.
>
> + @retval FALSE If Cert is NULL or CertSize is Zero.
>
> + @retval FALSE The operation is not supported.
>
> +
>
> +**/
>
> +BOOLEAN
>
> +EFIAPI
>
> +X509GetVersion (
>
> + IN CONST UINT8 *Cert,
>
> + IN UINTN CertSize,
>
> + OUT UINTN *Version
>
> + );
>
> +
>
> +/**
>
> + Retrieve the serialNumber from one X.509 certificate.
>
> +
>
> + If Cert is NULL, then return FALSE.
>
> + If CertSize is 0, then return FALSE.
>
> + If this interface is not supported, then return FALSE.
>
> +
>
> + @param[in] Cert Pointer to the DER-encoded X509 certificate.
>
> + @param[in] CertSize Size of the X509 certificate in bytes.
>
> + @param[out] SerialNumber Pointer to the retrieved certificate
> SerialNumber bytes.
>
> + @param[in, out] SerialNumberSize The size in bytes of the SerialNumber
> buffer on input,
>
> + and the size of buffer returned SerialNumber on output.
>
> +
>
> + @retval TRUE The certificate serialNumber retrieved
> successfully.
>
> + @retval FALSE If Cert is NULL or CertSize is Zero.
>
> + If SerialNumberSize is NULL.
>
> + If Certificate is invalid.
>
> + @retval FALSE If no SerialNumber exists.
>
> + @retval FALSE If the SerialNumber is NULL. The required buffer
> size
>
> + (including the final null) is returned in the
>
> + SerialNumberSize parameter.
>
> + @retval FALSE The operation is not supported.
>
> +**/
>
> +BOOLEAN
>
> +EFIAPI
>
> +X509GetSerialNumber (
>
> + IN CONST UINT8 *Cert,
>
> + IN UINTN CertSize,
>
> + OUT UINT8 *SerialNumber, OPTIONAL
>
> + IN OUT UINTN *SerialNumberSize
>
> + );
>
> +
>
> +/**
>
> + Retrieve the issuer bytes from one X.509 certificate.
>
> +
>
> + If Cert is NULL, then return FALSE.
>
> + If CertIssuerSize is NULL, then return FALSE.
>
> + If this interface is not supported, then return FALSE.
>
> +
>
> + @param[in] Cert Pointer to the DER-encoded X509 certificate.
>
> + @param[in] CertSize Size of the X509 certificate in bytes.
>
> + @param[out] CertIssuer Pointer to the retrieved certificate subject
> bytes.
>
> + @param[in, out] CertIssuerSize The size in bytes of the CertIssuer buffer
> on input,
>
> + and the size of buffer returned CertSubject on output.
>
> +
>
> + @retval TRUE The certificate issuer retrieved successfully.
>
> + @retval FALSE Invalid certificate, or the CertIssuerSize is too small for
> the result.
>
> + The CertIssuerSize will be updated with the required size.
>
> + @retval FALSE This interface is not supported.
>
> +
>
> +**/
>
> +BOOLEAN
>
> +EFIAPI
>
> +X509GetIssuerName (
>
> + IN CONST UINT8 *Cert,
>
> + IN UINTN CertSize,
>
> + OUT UINT8 *CertIssuer,
>
> + IN OUT UINTN *CertIssuerSize
>
> + );
>
> +
>
> +/**
>
> + Retrieve the Signature Algorithm from one X.509 certificate.
>
> +
>
> + @param[in] Cert Pointer to the DER-encoded X509 certificate.
>
> + @param[in] CertSize Size of the X509 certificate in bytes.
>
> + @param[out] Oid Signature Algorithm Object identifier buffer.
>
> + @param[in,out] OidSize Signature Algorithm Object identifier buffer
> size
>
> +
>
> + @retval TRUE The certificate Extension data retrieved successfully.
>
> + @retval FALSE If Cert is NULL.
>
> + If OidSize is NULL.
>
> + If Oid is not NULL and *OidSize is 0.
>
> + If Certificate is invalid.
>
> + @retval FALSE If no SignatureType.
>
> + @retval FALSE If the Oid is NULL. The required buffer size
>
> + is returned in the OidSize.
>
> + @retval FALSE The operation is not supported.
>
> +**/
>
> +BOOLEAN
>
> +EFIAPI
>
> +X509GetSignatureAlgorithm (
>
> + IN CONST UINT8 *Cert,
>
> + IN UINTN CertSize,
>
> + OUT UINT8 *Oid, OPTIONAL
>
> + IN OUT UINTN *OidSize
>
> + );
>
> +
>
> +/**
>
> + Retrieve Extension data from one X.509 certificate.
>
> +
>
> + @param[in] Cert Pointer to the DER-encoded X509 certificate.
>
> + @param[in] CertSize Size of the X509 certificate in bytes.
>
> + @param[in] Oid Object identifier buffer
>
> + @param[in] OidSize Object identifier buffer size
>
> + @param[out] ExtensionData Extension bytes.
>
> + @param[in, out] ExtensionDataSize Extension bytes size.
>
> +
>
> + @retval TRUE The certificate Extension data retrieved
> successfully.
>
> + @retval FALSE If Cert is NULL.
>
> + If ExtensionDataSize is NULL.
>
> + If ExtensionData is not NULL and *ExtensionDataSize is
> 0.
>
> + If Certificate is invalid.
>
> + @retval FALSE If no Extension entry match Oid.
>
> + @retval FALSE If the ExtensionData is NULL. The required
> buffer size
>
> + is returned in the ExtensionDataSize parameter.
>
> + @retval FALSE The operation is not supported.
>
> +**/
>
> +BOOLEAN
>
> +EFIAPI
>
> +X509GetExtensionData (
>
> + IN CONST UINT8 *Cert,
>
> + IN UINTN CertSize,
>
> + IN CONST UINT8 *Oid,
>
> + IN UINTN OidSize,
>
> + OUT UINT8 *ExtensionData,
>
> + IN OUT UINTN *ExtensionDataSize
>
> + );
>
> +
>
> +/**
>
> + Retrieve the Validity from one X.509 certificate
>
> +
>
> + If Cert is NULL, then return FALSE.
>
> + If CertIssuerSize is NULL, then return FALSE.
>
> + If this interface is not supported, then return FALSE.
>
> +
>
> + @param[in] Cert Pointer to the DER-encoded X509 certificate.
>
> + @param[in] CertSize Size of the X509 certificate in bytes.
>
> + @param[in] From notBefore Pointer to DateTime object.
>
> + @param[in,out] FromSize notBefore DateTime object size.
>
> + @param[in] To notAfter Pointer to DateTime object.
>
> + @param[in,out] ToSize notAfter DateTime object size.
>
> +
>
> + Note: X509CompareDateTime to compare DateTime oject
>
> + x509SetDateTime to get a DateTime object from a DateTimeStr
>
> +
>
> + @retval TRUE The certificate Validity retrieved successfully.
>
> + @retval FALSE Invalid certificate, or Validity retrieve failed.
>
> + @retval FALSE This interface is not supported.
>
> +**/
>
> +BOOLEAN
>
> +EFIAPI
>
> +X509GetValidity (
>
> + IN CONST UINT8 *Cert,
>
> + IN UINTN CertSize,
>
> + IN UINT8 *From,
>
> + IN OUT UINTN *FromSize,
>
> + IN UINT8 *To,
>
> + IN OUT UINTN *ToSize
>
> + );
>
> +
>
> +/**
>
> + Format a DateTime object into DataTime Buffer
>
> +
>
> + If DateTimeStr is NULL, then return FALSE.
>
> + If DateTimeSize is NULL, then return FALSE.
>
> + If this interface is not supported, then return FALSE.
>
> +
>
> + @param[in] DateTimeStr DateTime string like YYYYMMDDhhmmssZ
>
> + Ref: https://www.w3.org/TR/NOTE-datetime
>
> + Z stand for UTC time
>
> + @param[out] DateTime Pointer to a DateTime object.
>
> + @param[in,out] DateTimeSize DateTime object buffer size.
>
> +
>
> + @retval TRUE The DateTime object create successfully.
>
> + @retval FALSE If DateTimeStr is NULL.
>
> + If DateTimeSize is NULL.
>
> + If DateTime is not NULL and *DateTimeSize is 0.
>
> + If Year Month Day Hour Minute Second combination is
> invalid datetime.
>
> + @retval FALSE If the DateTime is NULL. The required buffer
> size
>
> + (including the final null) is returned in the
>
> + DateTimeSize parameter.
>
> + @retval FALSE The operation is not supported.
>
> +**/
>
> +BOOLEAN
>
> +EFIAPI
>
> +X509SetDateTime (
>
> + IN CHAR8 *DateTimeStr,
>
> + OUT VOID *DateTime,
>
> + IN OUT UINTN *DateTimeSize
>
> + );
>
> +
>
> +/**
>
> + Compare DateTime1 object and DateTime2 object.
>
> +
>
> + If DateTime1 is NULL, then return -2.
>
> + If DateTime2 is NULL, then return -2.
>
> + If DateTime1 == DateTime2, then return 0
>
> + If DateTime1 > DateTime2, then return 1
>
> + If DateTime1 < DateTime2, then return -1
>
> +
>
> + @param[in] DateTime1 Pointer to a DateTime Ojbect
>
> + @param[in] DateTime2 Pointer to a DateTime Object
>
> +
>
> + @retval 0 If DateTime1 == DateTime2
>
> + @retval 1 If DateTime1 > DateTime2
>
> + @retval -1 If DateTime1 < DateTime2
>
> +**/
>
> +INT32
>
> +EFIAPI
>
> +X509CompareDateTime (
>
> + IN CONST VOID *DateTime1,
>
> + IN CONST VOID *DateTime2
>
> + );
>
> +
>
> +/**
>
> + Retrieve the Key Usage from one X.509 certificate.
>
> +
>
> + @param[in] Cert Pointer to the DER-encoded X509 certificate.
>
> + @param[in] CertSize Size of the X509 certificate in bytes.
>
> + @param[out] Usage Key Usage (CRYPTO_X509_KU_*)
>
> +
>
> + @retval TRUE The certificate Key Usage retrieved successfully.
>
> + @retval FALSE Invalid certificate, or Usage is NULL
>
> + @retval FALSE This interface is not supported.
>
> +**/
>
> +BOOLEAN
>
> +EFIAPI
>
> +X509GetKeyUsage (
>
> + IN CONST UINT8 *Cert,
>
> + IN UINTN CertSize,
>
> + OUT UINTN *Usage
>
> + );
>
> +
>
> +/**
>
> + Retrieve the Extended Key Usage from one X.509 certificate.
>
> +
>
> + @param[in] Cert Pointer to the DER-encoded X509 certificate.
>
> + @param[in] CertSize Size of the X509 certificate in bytes.
>
> + @param[out] Usage Key Usage bytes.
>
> + @param[in, out] UsageSize Key Usage buffer sizs in bytes.
>
> +
>
> + @retval TRUE The Usage bytes retrieve successfully.
>
> + @retval FALSE If Cert is NULL.
>
> + If CertSize is NULL.
>
> + If Usage is not NULL and *UsageSize is 0.
>
> + If Cert is invalid.
>
> + @retval FALSE If the Usage is NULL. The required buffer size
>
> + is returned in the UsageSize parameter.
>
> + @retval FALSE The operation is not supported.
>
> +**/
>
> +BOOLEAN
>
> +EFIAPI
>
> +X509GetExtendedKeyUsage (
>
> + IN CONST UINT8 *Cert,
>
> + IN UINTN CertSize,
>
> + OUT UINT8 *Usage,
>
> + IN OUT UINTN *UsageSize
>
> + );
>
> +
>
> +/**
>
> + Verify one X509 certificate was issued by the trusted CA.
>
> + @param[in] RootCert Trusted Root Certificate buffer
>
> +
>
> + @param[in] RootCertLength Trusted Root Certificate buffer length
>
> + @param[in] CertChain One or more ASN.1 DER-encoded X.509
> certificates
>
> + where the first certificate is signed by the Root
>
> + Certificate or is the Root Cerificate itself. and
>
> + subsequent cerificate is signed by the preceding
>
> + cerificate.
>
> + @param[in] CertChainLength Total length of the certificate chain, in
> bytes.
>
> +
>
> + @retval TRUE All cerificates was issued by the first certificate in
> X509Certchain.
>
> + @retval FALSE Invalid certificate or the certificate was not issued by the
> given
>
> + trusted CA.
>
> +**/
>
> +BOOLEAN
>
> +EFIAPI
>
> +X509VerifyCertChain (
>
> + IN CONST UINT8 *RootCert,
>
> + IN UINTN RootCertLength,
>
> + IN CONST UINT8 *CertChain,
>
> + IN UINTN CertChainLength
>
> + );
>
> +
>
> +/**
>
> + Get one X509 certificate from CertChain.
>
> +
>
> + @param[in] CertChain One or more ASN.1 DER-encoded X.509
> certificates
>
> + where the first certificate is signed by the Root
>
> + Certificate or is the Root Cerificate itself. and
>
> + subsequent cerificate is signed by the preceding
>
> + cerificate.
>
> + @param[in] CertChainLength Total length of the certificate chain, in
> bytes.
>
> +
>
> + @param[in] CertIndex Index of certificate. If index is -1 indecate
> the
>
> + last certificate in CertChain.
>
> +
>
> + @param[out] Cert The certificate at the index of CertChain.
>
> + @param[out] CertLength The length certificate at the index of
> CertChain.
>
> +
>
> + @retval TRUE Success.
>
> + @retval FALSE Failed to get certificate from certificate chain.
>
> +**/
>
> +BOOLEAN
>
> +EFIAPI
>
> +X509GetCertFromCertChain (
>
> + IN CONST UINT8 *CertChain,
>
> + IN UINTN CertChainLength,
>
> + IN CONST INT32 CertIndex,
>
> + OUT CONST UINT8 **Cert,
>
> + OUT UINTN *CertLength
>
> + );
>
> +
>
> +/**
>
> + Retrieve the tag and length of the tag.
>
> +
>
> + @param Ptr The position in the ASN.1 data
>
> + @param End End of data
>
> + @param Length The variable that will receive the length
>
> + @param Tag The expected tag
>
> +
>
> + @retval TRUE Get tag successful
>
> + @retval FALSe Failed to get tag or tag not match
>
> +**/
>
> +BOOLEAN
>
> +EFIAPI
>
> +Asn1GetTag (
>
> + IN OUT UINT8 **Ptr,
>
> + IN UINT8 *End,
>
> + OUT UINTN *Length,
>
> + IN UINT32 Tag
>
> + );
>
> +
>
> +/**
>
> + Retrieve the basic constraints from one X.509 certificate.
>
> +
>
> + @param[in] Cert Pointer to the DER-encoded X509
> certificate.
>
> + @param[in] CertSize size of the X509 certificate in bytes.
>
> + @param[out] BasicConstraints basic constraints bytes.
>
> + @param[in, out] BasicConstraintsSize basic constraints buffer sizs in
> bytes.
>
> +
>
> + @retval TRUE The basic constraints retrieve successfully.
>
> + @retval FALSE If cert is NULL.
>
> + If cert_size is NULL.
>
> + If basic_constraints is not NULL and
> *basic_constraints_size is 0.
>
> + If cert is invalid.
>
> + @retval FALSE The required buffer size is small.
>
> + The return buffer size is basic_constraints_size
> parameter.
>
> + @retval FALSE If no Extension entry match oid.
>
> + @retval FALSE The operation is not supported.
>
> + **/
>
> +BOOLEAN
>
> +EFIAPI
>
> +X509GetExtendedBasicConstraints (
>
> + CONST UINT8 *Cert,
>
> + UINTN CertSize,
>
> + UINT8 *BasicConstraints,
>
> + UINTN *BasicConstraintsSize
>
> + );
>
> +
>
> //
> ==========================================================
> ===========================
>
> // DH Key Exchange Primitive
>
> //
> ==========================================================
> ===========================
>
> --
> 2.26.2.windows.1
-=-=-=-=-=-=-=-=-=-=-=-
Groups.io Links: You receive all messages sent to this group.
View/Reply Online (#94850): https://edk2.groups.io/g/devel/message/94850
Mute This Topic: https://groups.io/mt/93903802/1813853
Group Owner: devel+owner at edk2.groups.io
Unsubscribe: https://edk2.groups.io/g/devel/unsub [edk2-devel-archive at redhat.com]
-=-=-=-=-=-=-=-=-=-=-=-
More information about the edk2-devel-archive
mailing list