Sorry for confusing. This function is to format DataTimeStr to a DataTime object through DataTime buffer.
So will change the function name to X509FormatDateTime() and modify this comment to "Format DataTimeStr to a DataTime object in DataTime buffer". Thanks! -----Original Message----- From: Yao, Jiewen <jiewen....@intel.com> Sent: Monday, October 10, 2022 8:34 AM To: Zhang, Qi1 <qi1.zh...@intel.com>; devel@edk2.groups.io Cc: Wang, Jian J <jian.j.w...@intel.com>; Lu, Xiaoyu1 <xiaoyu1...@intel.com>; Jiang, Guomin <guomin.ji...@intel.com> Subject: RE: [PATCH 1/4] CryptoPkg: add new X509 function definition. 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.zh...@intel.com> > Sent: Sunday, September 25, 2022 4:54 PM > To: devel@edk2.groups.io > Cc: Zhang, Qi1 <qi1.zh...@intel.com>; Yao, Jiewen > <jiewen....@intel.com>; Wang, Jian J <jian.j.w...@intel.com>; Lu, > Xiaoyu1 <xiaoyu1...@intel.com>; Jiang, Guomin <guomin.ji...@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....@intel.com> > Cc: Jian J Wang <jian.j.w...@intel.com> > Cc: Xiaoyu Lu <xiaoyu1...@intel.com> > Cc: Guomin Jiang <guomin.ji...@intel.com> > Signed-off-by: Qi Zhang <qi1.zh...@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 (#94871): https://edk2.groups.io/g/devel/message/94871 Mute This Topic: https://groups.io/mt/93903802/21656 Group Owner: devel+ow...@edk2.groups.io Unsubscribe: https://edk2.groups.io/g/devel/unsub [arch...@mail-archive.com] -=-=-=-=-=-=-=-=-=-=-=-
