Certificate management convenience functions for your application code. More...

Functions
MOC_EXTERN sbyte4	CA_MGMT_allocCertDistinguishedName (certDistinguishedName **ppNewCertDistName)
	Allocate and initialize a `pCertificateDesc` structure. More...

MOC_EXTERN sbyte4	CA_MGMT_convertKeyBlobToPKCS8Key (const ubyte pKeyBlob, ubyte4 keyBlobLength, enum PKCS8EncryptionType encType, const ubyte pPassword, ubyte4 passwordLen, ubyte *ppRetPKCS8DER, ubyte4 pRetPkcs8DERLen)
	Encapsulate a Digicert SoT Platform keyblob in a protected PKCS #8 DER-encoded buffer. More...

MOC_EXTERN sbyte4	CA_MGMT_convertPKCS8KeyToKeyBlob (const ubyte pPKCS8DER, ubyte4 pkcs8DERLen, ubyte ppRetKeyBlob, ubyte4 pRetKeyBlobLength)
	Convert unprotected RSA private key to a Digicert SoT Platform private RSA keyblob. More...

MOC_EXTERN sbyte4	CA_MGMT_convertProtectedPKCS8KeyToKeyBlob (const ubyte pPKCS8DER, ubyte4 pkcs8DERLen, ubyte pPassword, ubyte4 passwordLen, ubyte *ppRetKeyBlob, ubyte4 pRetKeyBlobLength)
	Extract a protected RSA private key from a PKCS #8 DER- encoded buffer, converting it into a Digicert SoT Platform unprotected private RSA key blob. More...

MOC_EXTERN MSTATUS	CA_MGMT_convertRSAPublicKeyInfoDER (ubyte pDerRsaKey, ubyte4 derRsaKeyLength, ubyte ppRetKeyBlob, ubyte4 pRetKeyBlobLength)
	Convert the DER encoding of an RSA public key in PublicKeyInfo format into a Digicert key blob. More...

MOC_EXTERN sbyte4	CA_MGMT_decodeCertificate (ubyte pKeyFile, ubyte4 fileSize, ubyte ppDecodeFile, ubyte4 pDecodedLength)
	Convert PEM-encoded certificate to DER-encoded certificate. More...

MOC_EXTERN sbyte4	CA_MGMT_enumAltName (ubyte pCertificate, ubyte4 certificateLength, sbyte4 isSubject, CA_MGMT_EnumItemCBFun callbackFunc, void userArg)
	Enumerate the subject/issuer alternative names in a DER-encoded X.509 certificate, and invoke the given callback function for each alternative name. More...

MOC_EXTERN sbyte4	CA_MGMT_enumCrl (ubyte pCertificate, ubyte4 certificateLength, CA_MGMT_EnumItemCBFun callbackFunc, void userArg)
	Enumerate the CRLs (certificate revocation lists) in a certificate, and invoke the given callback function for each CRL. More...

MOC_EXTERN sbyte4	CA_MGMT_extractCertASN1Name (const ubyte pCertificate, ubyte4 certificateLength, sbyte4 isSubject, sbyte4 includeASN1SeqHeader, ubyte4 pASN1NameOffset, ubyte4 *pASN1NameLen)
	Get an X.509 certificate's subject or issuer DER-encoded ASN.1 name. More...

MOC_EXTERN sbyte4	CA_MGMT_extractCertDistinguishedName (ubyte pCertificate, ubyte4 certificateLength, sbyte4 isSubject, certDistinguishedName pRetDN)
	Get a DER-encoded X.509 certificate's subject or issuer (as specified by the `isSubject` parameter) distinguished name. More...

MOC_EXTERN sbyte4	CA_MGMT_extractCertTimes (ubyte pCertificate, ubyte4 certificateLength, certDistinguishedName pRetDN)
	Get a DER-encoded X.509 certificate's start and expiration times and dates. More...

MOC_EXTERN sbyte4	CA_MGMT_freeCertDistinguishedName (certDistinguishedName **ppFreeCertDistName)
	Free `certDistinguishedName` structure's memory. More...

MOC_EXTERN sbyte4	CA_MGMT_freeCertificate (certDescriptor *pRetCertificateDescr)
	Free memory allocated by CA_MGMT_generateCertificate(). More...

MOC_EXTERN sbyte4	CA_MGMT_freeNakedKey (ubyte **ppFreeKeyBlob)
	Free (release) a naked key blob's memory. More...

MOC_EXTERN sbyte4	CA_MGMT_generateCertificateExType (certDescriptor pRetCertificate, ubyte4 keyType, ubyte4 keySize, const certDistinguishedName pCertInfo, ubyte signAlgorithm, const certExtensions pExtensions, const certDescriptor pParentCertificate)
	Generate a signed X.509 certificate and public/private key pair. More...

MOC_EXTERN sbyte4	CA_MGMT_generateCertificateHybrid (certDescriptor pRetCertificate, ubyte4 curve, ubyte4 qsAlg, const certDistinguishedName pCertInfo, const certExtensions pExtensions, const certDescriptor pParentCertificate)
	Generates a signed X.509 certificate and private/public key pair for a hybrid authentication algorithm. More...

MOC_EXTERN sbyte4	CA_MGMT_generateNakedHybridKey (ubyte4 keyType, ubyte4 legacyKeyType, ubyte4 legacyKeySize, ubyte4 qsAlgoId, ubyte *ppRetNewKeyBlob, ubyte4 pRetNewKeyBlobLength)
	Generate a naked key. More...

MOC_EXTERN sbyte4	CA_MGMT_generateNakedKey (ubyte4 keyType, ubyte4 keySize, ubyte *ppRetNewKeyBlob, ubyte4 pRetNewKeyBlobLength)
	Generate a naked key. More...

MOC_EXTERN sbyte4	CA_MGMT_returnCertificatePrints (ubyte pCertificate, ubyte4 certLength, ubyte pShaFingerPrint, ubyte *pMD5FingerPrint)
	Generate an X.509 certificate's SHA-1 and MD5 fingerprints. More...

MOC_EXTERN MSTATUS	CA_MGMT_verifyCertDate (ubyte *pCert, ubyte4 certLen)
	Validate a DER-encoded X.509 certificate's start and expiration times and dates against the current time. More...

MOC_EXTERN sbyte4	CA_MGMT_verifyCertWithKeyBlob (certDescriptor pCertificateDescr, sbyte4 pIsGood)
	Verify correspondence of a `certDescriptor` key blob and certificate's key. More...

Detailed Description

Function Documentation

◆ CA_MGMT_allocCertDistinguishedName()

MOC_EXTERN sbyte4 CA_MGMT_allocCertDistinguishedName ( certDistinguishedName ** ppNewCertDistName )

This function allocates and initializaes (to zero) a pCertificateDesc structure.

Since: 1.41

Version: 6.4 and later

No flag definitions are required to use this function.

ca_mgmt.h

Parameters

ppNewCertDistName On return, structure referenced contains the allocated and initialized certificate.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

Remarks: This is a convenience function provided for your application's use; it is not used by Digicert SoT Platform internal code.

ca_mgmt.h

◆ CA_MGMT_convertKeyBlobToPKCS8Key()

MOC_EXTERN sbyte4 CA_MGMT_convertKeyBlobToPKCS8Key	(	const ubyte *	pKeyBlob,
		ubyte4	keyBlobLength,
		enum PKCS8EncryptionType	encType,
		const ubyte *	pPassword,
		ubyte4	passwordLen,
		ubyte **	ppRetPKCS8DER,
		ubyte4 *	pRetPkcs8DERLen
	)

This function encapsulates a Digicert SoT Platform keyblob in a protected PKCS #8 DER-encoded buffer.

Note: After you are done with the returned keyblob, be sure to free its memory by calling MOC_FREE() or CA_MGMT_freeNakedKey().

Since: 5.1

Version: 6.4 and later

To enable this function, the following flag must not be defined:

__DISABLE_MOCANA_CERTIFICATE_PARSING__

Additionally, the following flag must be defined:

__ENABLE_MOCANA_DER_CONVERSION__

ca_mgmt.h

Parameters

pKeyBlob	Pointer to Digicert SoT Platform key blob to convert.
keyBlobLength	Number of bytes in the keyblob (`pKeyBlob`).
encType	Type of encryption method to use; any of the `PKCS8EncryptionType` enumerations (except `PCKS8_EncryptionType_undefined`) in pkcs_key.h.
pPassword	Pointer to password to use to protect the PKCS #8 DER-encoded key.
passwordLen	Number of bytes in the password (`pPassword`).
ppRetPKCS8DER	On return, pointer to PKCS #8 DER-encoded key.
pRetPkcs8DERLen	On return, number of bytes in the DER-encoded key (`ppRetPKCS8DER`).

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

ca_mgmt.h

◆ CA_MGMT_convertPKCS8KeyToKeyBlob()

MOC_EXTERN sbyte4 CA_MGMT_convertPKCS8KeyToKeyBlob	(	const ubyte *	pPKCS8DER,
		ubyte4	pkcs8DERLen,
		ubyte **	ppRetKeyBlob,
		ubyte4 *	pRetKeyBlobLength
	)

This function converts an unprotected RSA private key (extracted from a PKCS #8 DER-encoded buffer) to a Digicert SoT Platform private RSA keyblob.

Note: After you are done with the returned keyblob, be sure to free its memory by calling MOC_FREE() or CA_MGMT_freeNakedKey().

Since: 5.1

Version: 5.1 and later

(internal changes, post-5.3.1...)

To enable this function, the following flag must not be defined:

__DISABLE_MOCANA_CERTIFICATE_PARSING__

Additionally, __DISABLE_MOCANA_KEY_GENERATION__ must not be defined, or one of the following flags must be defined:

__ENABLE_MOCANA_PEM_CONVERSION__
__ENABLE_MOCANA_DER_CONVERSION__

ca_mgmt.h

Parameters

pPKCS8DER	Pointer to PKCS #8 DER-encoded key.
pkcs8DERLen	Number of bytes in the DER-encoded key ($`pPKCS8DER`).
ppRetKeyBlob	On return, pointer to converted keyblob.
pRetKeyBlobLength	On return, number of bytes in the converted keyblob (`ppRetKeyBlob`).

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

ca_mgmt.h

◆ CA_MGMT_convertProtectedPKCS8KeyToKeyBlob()

MOC_EXTERN sbyte4 CA_MGMT_convertProtectedPKCS8KeyToKeyBlob	(	const ubyte *	pPKCS8DER,
		ubyte4	pkcs8DERLen,
		ubyte *	pPassword,
		ubyte4	passwordLen,
		ubyte **	ppRetKeyBlob,
		ubyte4 *	pRetKeyBlobLength
	)

This function extracts a protected RSA private key from a PKCS #8 DER-encoded buffer, and converts the key to a Digicert SoT Platform unprotected private RSA keyblob.

Note: After you are done with the returned keyblob, be sure to free its memory by calling MOC_FREE() or CA_MGMT_freeNakedKey().

Since: 5.1

Version: 6.4 and later

To enable this function, the following flag must not be defined:

__DISABLE_MOCANA_CERTIFICATE_PARSING__

Additionally, __DISABLE_MOCANA_KEY_GENERATION__ must not be defined, or one of the following flags must be defined:

__ENABLE_MOCANA_PEM_CONVERSION__
__ENABLE_MOCANA_DER_CONVERSION__

ca_mgmt.h

Parameters

pPKCS8DER	Pointer to PKCS #8 DER-encoded key.
pkcs8DERLen	Length in bytes of the DER-encoded key, `pPKCS8DER`.
pPassword	Pointer to password that protects the PKCS #8 DER-encoded key.
passwordLen	Length in bytes of the password, `pPassword`.
ppRetKeyBlob	On return, pointer to extracted/converted key blob.
pRetKeyBlobLength	On return, length of extracted/converted key blob `ppRetKeyBlob`.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

ca_mgmt.h

◆ CA_MGMT_convertRSAPublicKeyInfoDER()

MOC_EXTERN MSTATUS CA_MGMT_convertRSAPublicKeyInfoDER	(	ubyte *	pDerRsaKey,
		ubyte4	derRsaKeyLength,
		ubyte **	ppRetKeyBlob,
		ubyte4 *	pRetKeyBlobLength
	)

The ASN.1 definitions of PublicKeyInfo (also known as SubjectPublicKey) and RSAPublicKey are the following.


  PublicKeyInfo ::= SEQUENCE {
    algorithm       AlgorithmIdentifier,
    PublicKey       BIT STRING }

  RSAPublicKey ::= SEQUENCE {
    modulus           INTEGER,  -- n
    publicExponent    INTEGER   -- e  }

The DER encoding of an RSA public key might be RSAPublicKey or it might be PublicKeyInfo. If it is PublicKeyInfo, call this routine to convert it into a Digicert format key blob (which you can use to build an AsymmetricKey object). The BIT STRING of the PublicKeyInfo "wraps" the DER encoding of RSAPublicKey.

The function will allocate memory. The caller passes in the address of a ubyte pointer, the function will allocate memory to hold the key blob, fill that memory with the key blob and deposit the pointer at the address given. It is the repsonsibility of the caller to free that memory using MOC_FREE.

Make sure you free the buffer returned at the address ppRetKeyBlob using MOC_FREE when you are done with it.

To enable this function, at least one of the following flags must be defined in moptions.h:

__ENABLE_MOCANA_DER_CONVERSION__
__ENABLE_MOCANA_PEM_CONVERSION__

ca_mgmt.h

Parameters

pDerRsaKey	The DER encoding of an RSA public key following the ASN.1 definition PublicKeyInfo.
derRsaKeyLength	The length, in bytes, of the DER-encoded key.
ppRetKeyBlob	The address where the function will deposit a pointer to allocated memory containing the key data as a Digicert key blob.
pRetKeyBlobLength	The address where the function will deposit the length, in bytes, of the key blob.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

ca_mgmt.h

◆ CA_MGMT_decodeCertificate()

MOC_EXTERN sbyte4 CA_MGMT_decodeCertificate	(	ubyte *	pKeyFile,
		ubyte4	fileSize,
		ubyte **	ppDecodeFile,
		ubyte4 *	pDecodedLength
	)

This function converts a PEM-encoded certificate to a DER-encoded certificate. This function allocates memory that the caller must free (using MOC_FREE).

Since: 1.41

Version: 1.41 and later

(changed return type; added param validity checking...)

To enable this function, at least one of the following flags must be defined in moptions.h:

__ENABLE_MOCANA_PKCS10__
__ENABLE_MOCANA_PEM_CONVERSION__

ca_mgmt.h

Parameters

pKeyFile	Pointer to certificate file to decode.
fileSize	Number of bytes in certificate file.
ppDecodeFile	The address where the function will deposit allocated memory containing the DER version of the certificate.
pDecodedLength	On return, pointer to number of bytes in `ppDecodeFile`.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

Remarks: This is a convenience function provided for your application's use; it is not used by Digicert SoT Platform internal code.

ca_mgmt.h

◆ CA_MGMT_enumAltName()

MOC_EXTERN sbyte4 CA_MGMT_enumAltName	(	ubyte *	pCertificate,
		ubyte4	certificateLength,
		sbyte4	isSubject,
		CA_MGMT_EnumItemCBFun	callbackFunc,
		void *	userArg
	)

This function parses a DER-encoded X.509 certificate and compiles a list of SubjectAltName or IssuerAltName objects, depending on the value of the isSubject parameter. For each alternative name, this function invokes the callback function that is passed through the callbackFunc parameter.

Since: 4.0

Version: 4.0 and later

(internal changes, post-5.3.1...)

The callbackFunc parameter's callback function must have the following method signature:

sbyte4 userFunc(const ubyte *pContent, ubyte4 contentLen, ubyte4 contentType, ubyte4 index, void *userArg);

Syntax/parameters

Name	Type	Description
`<pContent>`	`const ubyte *`	Pointer to CRL buffer.
`<contentLen>`	`ubyte4`	Number of bytes in CRL buffer (`pContent`).
`<contentType>`	`ubyte4`	ASN.1 tag associated with the CRL, which indicates how to interpret the CRL's contents.

For details, refer to the description of the GeneralName type http://www.itu.int/ITU-T/asn1/database/itu-t/x/x509/1997/CertificateExtensions.html#CertificateExtensions.GeneralName.| |<index>|ubyte4|0-based index of this CRL's location in the CRL list.| |<userArg>|void *|Value of the userArg parameter when the CA_MGMT_enumAltName function was called.| | | |
| |Return value|sbyte4|Negative number to stop CRL enumeration; otherwise a number >= 0 to continue CRL enumeration.|

To enable this function, the following flag must be defined in moptions.h:

__ENABLE_MOCANA_CERTIFICATE_SEARCH_SUPPORT__

ca_mgmt.h

Parameters

pCertificate	Pointer to DER-encoded certificate to parse.
certificateLength	Number of bytes in the certificate (`pCertificate`).
isSubject	`TRUE` to find `SubjectAltName` objects; `FALSE` to find `IssuerAltName` objects.
callbackFunc	Pointer to user-defined callback function to invoke for each alternative name. See the description section for callback function details.
userArg	Pointer to argument to provide to callback function: `NULL` or a context to provide to the callback function.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

Remarks: This is a convenience function provided for your application's use; it is not used by Digicert SoT Platform internal code.

ca_mgmt.h

◆ CA_MGMT_enumCrl()

MOC_EXTERN sbyte4 CA_MGMT_enumCrl	(	ubyte *	pCertificate,
		ubyte4	certificateLength,
		CA_MGMT_EnumItemCBFun	callbackFunc,
		void *	userArg
	)

This function parses the CRLs (certificate revocation lists) in a certificate and finds its CRLs, and for each CRL invokes the callback function that is passed through the callbackFunc parameter.

Since: 2.02

Version: 4.0 and later

(internal changes, post-5.3.1...)

The callbackFunc parameter's callback function must have the following method signature:

sbyte4 userFunc(const ubyte *pContent, ubyte4 contentLen, ubyte4 contentType, ubyte4 index, void *userArg);

Syntax/parameters

Name	Type	Description
`<pContent>`	`const ubyte *`	Pointer to CRL buffer.
`<contentLen>`	`ubyte4`	Number of bytes in CRL buffer (`pContent`).
`<contentType>`	`ubyte4`	ASN.1 tag associated with the CRL, which indicates how to interpret the CRL's contents.

For details, refer to the description of the GeneralName type http://www.itu.int/ITU-T/asn1/database/itu-t/x/x509/1997/CertificateExtensions.html#CertificateExtensions.GeneralName.| |<index>|ubyte4|0-based index of this CRL's location in the CRL list.| |<userArg>|void *|Value of the userArg parameter when the CA_MGMT_enumCrl function was called.| | | |
| |Return value|sbyte4|Negative number to stop CRL enumeration; otherwise a number >= 0 to continue CRL enumeration.|

To enable this function, the following flag must be defined in moptions.h:

__ENABLE_MOCANA_CERTIFICATE_SEARCH_SUPPORT__

ca_mgmt.h

Parameters

pCertificate	Pointer to DER-encoded certificate to parse.
certificateLength	Number of bytes in the certificate (`pCertificate`).
callbackFunc	Pointer to user-defined callback function to invoke for each CRL. See the description section for callback function details.
userArg	Pointer to argument to provide to callback function: `NULL` or a context to provide to the callback function.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

Remarks: This is a convenience function provided for your application's use; it is not used by Digicert SoT Platform internal code.

ca_mgmt.h

◆ CA_MGMT_extractCertASN1Name()

MOC_EXTERN sbyte4 CA_MGMT_extractCertASN1Name	(	const ubyte *	pCertificate,
		ubyte4	certificateLength,
		sbyte4	isSubject,
		sbyte4	includeASN1SeqHeader,
		ubyte4 *	pASN1NameOffset,
		ubyte4 *	pASN1NameLen
	)

This function gets an X.509 certificate's subject or issuer (as specified by the isSubject parameter) DER-encoded ASN.1 name. The subject is typically used to generate a PKCS-10 request.

When choosing whether to specify includeASN1SeqHeader as TRUE or FALSE, keep in mind that DER-encoded objects (which can be nested) have a general format of tag+length+data. For this function, the tag+length represents the header. RFC 3280 defines a DER-encoded ASN1 as follows:

Name ::= CHOICE {
RDNSequence }

RDNSequence ::= SEQUENCE OF RelativeDistinguishedName

RelativeDistinguishedName ::=
SET OF AttributeTypeAndValue

AttributeTypeAndValue ::= SEQUENCE {
type     AttributeType,
value    AttributeValue }

AttributeType ::= OBJECT IDENTIFIER

AttributeValue ::= ANY DEFINED BY AttributeType

When you specify includeASN1SeqHeader as TRUE, the returned pASN1NameOffset points to the start of the tag part of the DER-encoded ASN1 name, which identifies this name as a SEQUENCE OF RelativeDistinguishedName objects. When you specify includeASN1SeqHeader as FALSE, the returned pASN1NameOffset points to the value part of the tag+length+data DER-encoded name, which is the first of the RelativeDistinguishedName objects in the name.

To add a name "as is" to a certificate or CSR (Certificate Signing Request), as in functions such as PKCS10_GenerateCertReqFromASN1() and PKCS10_generateCSRFromASN1(), include the header.

(details expanded post-5.3.1)

Since: 1.41

Version: 5.3 and later

(internal changes, post-5.3.1...)

To enable this function, the following flag must not be defined:

__DISABLE_MOCANA_CERTIFICATE_GENERATION__

ca_mgmt.h

Parameters

pCertificate	Pointer to the DER-encoded X.509 certificate of interest.
certificateLength	Length of the certificate, `pCertificate`, in bytes.
isSubject	`TRUE` to return the subject's distinguished name; `FALSE` to return the issuer's distinguished name.
includeASN1SeqHeader	`TRUE` to include the ASN.1 sequence; otherwise `FALSE` (to advance the `pASN1NameOffset` pointer past the header to the name's value).
pASN1NameOffset	On return, pointer to certificate's ASN.1 name field.
pASN1NameLen	On return, pointer to number of bytes in certificate's ASN.1 name.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

Remarks: This is a convenience function provided for your application's use; it is not used by Digicert SoT Platform internal code.

ca_mgmt.h

◆ CA_MGMT_extractCertDistinguishedName()

MOC_EXTERN sbyte4 CA_MGMT_extractCertDistinguishedName	(	ubyte *	pCertificate,
		ubyte4	certificateLength,
		sbyte4	isSubject,
		certDistinguishedName *	pRetDN
	)

This function gets a DER-encoded X.509 certificate's subject or issuer (as specified by the isSubject parameter) distinguished name.

Since: 1.41

Version: 1.41 and later

(internal changes, post-5.3.1...)

To enable this function, the following flag must not be defined:

__DISABLE_MOCANA_CERTIFICATE_GENERATION__

ca_mgmt.h

Parameters

pCertificate	Pointer to the DER-encoded X.509 certificate of interest.
certificateLength	Length of the certificate, `pCertificate`, in bytes.
isSubject	`TRUE` to return the subject's distinguished name; `FALSE` to return the issuer's distinguished name.
pRetDN	On return, pointer to the requested distinguished name.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

Remarks: This is a convenience function provided for your application's use; it is not used by Digicert SoT Platform internal code.

certDistinguishedName distName;
sbyte4 status;
status = CA_MGMT_extractCertDistinguishedName(pCertificate, certificateLength, 1, &distName);

ca_mgmt.h

◆ CA_MGMT_extractCertTimes()

MOC_EXTERN sbyte4 CA_MGMT_extractCertTimes	(	ubyte *	pCertificate,
		ubyte4	certificateLength,
		certDistinguishedName *	pRetDN
	)

This function gets a DER-encoded X.509 certificate's start and expiration times and dates.

Warning: The only meaningful fields in the returned pRetDN certDistinguisedName structure are pStartDate and pEndDate. Do not use the remaining fields in pRetDN.

Since: 1.41

Version: 1.41 and later

To enable this function, the following flag must not be defined:

__DISABLE_MOCANA_CERTIFICATE_GENERATION__

ca_mgmt.h

Parameters

pCertificate	Pointer to the DER-encoded X.509 certificate of interest.
certificateLength	Length of the certificate, `pCertificate`, in bytes.
pRetDN	On return, pointer to the certificate's start and end dates.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

Remarks: This is a convenience function provided for your application's use; it is not used by Digicert SoT Platform internal code.

ca_mgmt.h

◆ CA_MGMT_freeCertDistinguishedName()

MOC_EXTERN sbyte4 CA_MGMT_freeCertDistinguishedName ( certDistinguishedName ** ppFreeCertDistName )

This function frees the memory in the given certDistinguishedName structure, as well as all memory pointed to by the structure's fields.

Since: 1.41

Version: 1.41 and later

No flag definitions are required to use this function.

ca_mgmt.h

Parameters

ppFreeCertDistName Pointer to the X.509 certificate's distinguished name structure to release.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

Remarks: This is a convenience function provided for your application's use; it is not used by Digicert SoT Platform internal code.

ca_mgmt.h

◆ CA_MGMT_freeCertificate()

MOC_EXTERN sbyte4 CA_MGMT_freeCertificate ( certDescriptor * pRetCertificateDescr )

This function frees the memory in the specified certDescriptor buffer that was previously allocated by a call to CA_MGMT_generateCertificate().

Since: 1.41

Version: 1.41 and later

To enable this function, the following flag must not be defined:

__DISABLE_MOCANA_CERTIFICATE_GENERATION__

ca_mgmt.h

Parameters

pRetCertificateDescr Pointer to the X.509 certificate and key blob to free.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

Remarks: This is a convenience function provided for your application's use; it is not used by Digicert SoT Platform internal code.

sbyte4 status = 0;
status = CA_MGMT_freeCertificate(pFreeThisCertDescr);

ca_mgmt.h

◆ CA_MGMT_freeNakedKey()

MOC_EXTERN sbyte4 CA_MGMT_freeNakedKey ( ubyte ** ppFreeKeyBlob )

This function frees (releases)the memory used by a naked key blob.

Since: 2.02

Version: 2.02 and later

To enable this function, the following flag must not be defined:

__DISABLE_MOCANA_KEY_GENERATION__

ca_mgmt.h

Parameters

ppFreeKeyBlob Pointer to naked key blob to free (release).

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

ca_mgmt.h

◆ CA_MGMT_generateCertificateExType()

MOC_EXTERN sbyte4 CA_MGMT_generateCertificateExType	(	certDescriptor *	pRetCertificate,
		ubyte4	keyType,
		ubyte4	keySize,
		const certDistinguishedName *	pCertInfo,
		ubyte	signAlgorithm,
		const certExtensions *	pExtensions,
		const certDescriptor *	pParentCertificate
	)

This function generates a signed X.509 certificate and public/private key pair. If you do not specify a parent, pParentCertificate, the generated certificate is self-signed. (Self-signed certificates are typically used during application development and testing.)

To avoid losing a certificate in the event of power loss, store the generated certificate and key blob to persistent storage.

Since: 2.02

Version: 2.02 and later (Revised post-6.4, commit [3c61741], April 14, 2016.)

To enable this function, the following flags must not be defined:

__DISABLE_MOCANA_CERTIFICATE_GENERATION__
__DISABLE_MOCANA_CERTIFICATE_PARSING__
__DISABLE_MOCANA_KEY_GENERATION__

ca_mgmt.h

Parameters

pRetCertificate	Pointer to `certDescriptor` structure, which on return contains the generated certificate and key blob.
keyType	Explicitly specifies the type of key (RSA, DSA, ECC) instead of inferring it based on the keySize
keySize	On return, number of bits in the generated key.
pCertInfo	Pointer to distinguished name and associated information for creating the certificate.
signAlgorithm	Hash function to use to sign the certificate. The following enumerated values (defined in crypto.h) are supported: `ht_md5` `ht_sha1` `ht_sha256` `ht_sha3846` `ht_sha512` `ht_sha224`
pExtensions	NULL if no required extensions; otherwise pointer to a bit string representing the desired version 3 certificate extensions. For details about forming the bit string, see the `certExtensions` documentation.
pParentCertificate	NULL or pointer to a parent certificate. If NULL, a self-signed certificate is generated. Otherwise, a child certificate (signed using the parent certificate) is generated.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

Remarks: This is a convenience function provided for your application's use; it is not used by Digicert SoT Platform internal code.

sbyte status = 0;
certDescriptor newCertificate;
certDistinguishedName certSubjectName;
// omitted code: initialize all fields of newCertificate to 0,
// and set the fields of certSubjectName to the desired value
// generate a self-signed certificate for the EEC curve P-256 with no extensions
if (0 > (status = CA_MGMT_generateCertificateEx(&newCertificate, 256, &certSubjectName, ht_sha256, NULL, NULL)))
{
goto exit;
}

ca_mgmt.h

◆ CA_MGMT_generateCertificateHybrid()

MOC_EXTERN sbyte4 CA_MGMT_generateCertificateHybrid	(	certDescriptor *	pRetCertificate,
		ubyte4	curve,
		ubyte4	qsAlg,
		const certDistinguishedName *	pCertInfo,
		const certExtensions *	pExtensions,
		const certDescriptor *	pParentCertificate
	)

Generates a signed X.509 certificate and private/public key pair for a hybrid authentication algorithm consisting of ECDSA and a quantum safe algorithm. If you do not specify a parent, pParentCertificate, the generated certificate is self-signed. (Self-signed certificates are typically used during application development and testing.) This method allocates memory so be sure to call CA_MGMT_freeCertificate when done with the certificate.

To enable this function, the following flag must not be defined: To enable this function, the following flags must not be defined:

__DISABLE_MOCANA_CERTIFICATE_GENERATION__
__DISABLE_MOCANA_CERTIFICATE_PARSING__
__DISABLE_MOCANA_KEY_GENERATION__

ca_mgmt.h

Parameters

pRetCertificate	Pointer to `certDescriptor` structure, which on return contains the generated certificate and key blob.
curve	One of the following ECDSA curve identifiers `cid_EC_P256` `cid_EC_P384` `cid_EC_P512`
qsAlg	One of the following quantum safe algorithm identifiers listed in the enum above.
pCertInfo	Pointer to distinguished name and associated information for creating the certificate.
pExtensions	NULL if no required extensions; otherwise pointer to a bit string representing the desired version 3 certificate extensions. For details about forming the bit string, see the `certExtensions` documentation.
pParentCertificate	NULL or pointer to a parent certificate. If NULL, a self-signed certificate is generated. Otherwise, a child certificate (signed using the parent certificate) is generated.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

Remarks: This is a convenience function provided for your application's use; it is not used by Digicert SoT Platform internal code.

ca_mgmt.h

◆ CA_MGMT_generateNakedHybridKey()

MOC_EXTERN sbyte4 CA_MGMT_generateNakedHybridKey	(	ubyte4	keyType,
		ubyte4	legacyKeyType,
		ubyte4	legacyKeySize,
		ubyte4	qsAlgoId,
		ubyte **	ppRetNewKeyBlob,
		ubyte4 *	pRetNewKeyBlobLength
	)

Supports ability to generate hybrid keys.

This function generates a naked key—a key blob that has no associated certificate—. The naked key can be used as input to generate a certificate or as signing data for authentication.

Since: 2.02

Version: 2.02 and later

(internal changes, post-5.3.1...)

To enable this function, the following flags must be defined:

__ENABLE_MOCANA_QS__
__ENABLE_MOCANA_ECC__

And the following flag must not be defined:

__DISABLE_MOCANA_KEY_GENERATION__

ca_mgmt.h

Parameters

keyType	Type of key to generate. The following enumerated values (defined in ca_mgmt.h) are supported: `akt_undefined` `akt_rsa` `akt_ecc` `akt_ecc_ed` `akt_dsa` `akt_hybrid`
legacyKeyType	Value of non QS portion of hybrid key to generate. Only used if keyType is akt_hybrid.
legacyKeySize	Number of bits the generated key must contain. If keyType is akt_hybrid, field contains the value for legacyKeyType, else value for KeyType.
qsAlgoId	Value of QS portion of hybrid key to generate. Only used if keyType is akt_hybrid. The following enumerated values (defined in ca_mgmt.h) are supported: `cid_QS_SIG_DILITHIUM_2` `cid_QS_SIG_DILITHIUM_3` `cid_QS_SIG_DILITHIUM_4` `cid_QS_SIG_DILITHIUM_5` `cid_QS_SIG_FALCON_512` `cid_QS_SIG_FALCON_1024` `cid_QS_SIG_RAINBOW_IA_CLASSIC` `cid_QS_SIG_RAINBOW_IA_CYCLIC` `cid_QS_SIG_RAINBOW_IA_CYCLIC_COMPRESSED` `cid_QS_SIG_RAINBOW_IIIC_CLASSIC` `cid_QS_SIG_RAINBOW_IIIC_CYCLIC` `cid_QS_SIG_RAINBOW_IIIC_CYCLIC_COMPRESSED` `cid_QS_SIG_RAINBOW_VC_CLASSIC` `cid_QS_SIG_RAINBOW_VC_CYCLIC` `cid_QS_SIG_RAINBOW_VC_CYCLIC_COMPRESSED` `cid_QS_SIG_QTESLA_P_I` `cid_QS_SIG_MQDSS_31_48` `cid_QS_SIG_SPHINCS_HARAKA_128F_ROBUST` `cid_QS_SIG_SPHINCS_SHA256_128F_ROBUST` `cid_QS_SIG_SPHINCS_SHAKE256_128F_ROBUST`
ppRetNewKeyBlob	On return, pointer to generated naked key.
pRetNewKeyBlobLength	On return, pointer to number of bytes in the naked key (`ppRetNewKeyBlob`).

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

ca_mgmt.h

◆ CA_MGMT_generateNakedKey()

MOC_EXTERN sbyte4 CA_MGMT_generateNakedKey	(	ubyte4	keyType,
		ubyte4	keySize,
		ubyte **	ppRetNewKeyBlob,
		ubyte4 *	pRetNewKeyBlobLength
	)

This function generates a naked key—a key blob that has no associated certificate—. The naked key can be used as input to generate a certificate or as signing data for authentication.

Since: 2.02

Version: 2.02 and later

(internal changes, post-5.3.1...)

To enable this function, the following flag must not be defined:

__DISABLE_MOCANA_KEY_GENERATION__

ca_mgmt.h

Parameters

keyType	Type of key to generate. The following enumerated values (defined in ca_mgmt.h) are supported: `akt_undefined` `akt_rsa` `akt_ecc` `akt_ecc_ed` `akt_dsa`
keySize	Number of bits the generated key must contain.
ppRetNewKeyBlob	On return, pointer to generated naked key.
pRetNewKeyBlobLength	On return, pointer to number of bytes in the naked key (`ppRetNewKeyBlob`).

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

ca_mgmt.h

◆ CA_MGMT_returnCertificatePrints()

MOC_EXTERN sbyte4 CA_MGMT_returnCertificatePrints	(	ubyte *	pCertificate,
		ubyte4	certLength,
		ubyte *	pShaFingerPrint,
		ubyte *	pMD5FingerPrint
	)

This function generates and returns an X.509 certificate's SHA-1 and MD5 fingerprints—message digests (output of hash functions).

Since: 1.41

Version: 1.41 and later

To enable this function, the following flag must not be defined:

__DISABLE_MOCANA_CERTIFICATE_GENERATION__

ca_mgmt.h

Parameters

pCertificate	Pointer to the DER-encoded X.509 certificate of interest.
certLength	Length of the certificate, `pCertificate`, in bytes.
pShaFingerPrint	On return, pointer to the generated SHA-1 fingerprint.
pMD5FingerPrint	On return, pointer to the generated MD5 fingerprint.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

Remarks: This is a convenience function provided for your application's use; it is not used by Digicert SoT Platform internal code.

sbyte4 status = 0;
status = CA_MGMT_returnCertificatePrints(pCertificate, certLength, &ShaFgrBuf, &MD5FgrBuf);

ca_mgmt.h

◆ CA_MGMT_verifyCertDate()

MOC_EXTERN MSTATUS CA_MGMT_verifyCertDate	(	ubyte *	pCert,
		ubyte4	certLen
	)

This function gets a DER-encoded X.509 certificate's start and expiration times and dates and validates them against the current time.

To enable this function, the following flag must not be defined:

__DISABLE_MOCANA_CERTIFICATE_GENERATION__

ca_mgmt.h

Parameters

pCert	Pointer to the DER-encoded X.509 certificate of interest.
certLen	Length of the certificate, `pCertificate`, in bytes.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

ca_mgmt.h

◆ CA_MGMT_verifyCertWithKeyBlob()

MOC_EXTERN sbyte4 CA_MGMT_verifyCertWithKeyBlob	(	certDescriptor *	pCertificateDescr,
		sbyte4 *	pIsGood
	)

This function verifies that a certDescriptor key blob matches the X.509 certificate's key.

Since: 1.41

Version: 3.06 and later

To enable this function, the following flag must not be defined:

__DISABLE_MOCANA_CERTIFICATE_GENERATION__

ca_mgmt.h

Parameters

pCertificateDescr	Pointer to the certificate descriptor containing the X.509 certificate and key blob generated public key.
pIsGood	Pointer to buffer that on return contains `TRUE` if the certificate's key blob matches the cedrtificate's key; otherwise `FALSE`.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

Remarks: This is a convenience function provided for your application's use; it is not used by Digicert SoT Platform internal code.

ca_mgmt.h

Functions

Detailed Description

Function Documentation

◆ CA_MGMT_allocCertDistinguishedName()

◆ CA_MGMT_convertKeyBlobToPKCS8Key()

◆ CA_MGMT_convertPKCS8KeyToKeyBlob()

◆ CA_MGMT_convertProtectedPKCS8KeyToKeyBlob()

◆ CA_MGMT_convertRSAPublicKeyInfoDER()

◆ CA_MGMT_decodeCertificate()

◆ CA_MGMT_enumAltName()

Syntax/parameters

◆ CA_MGMT_enumCrl()

Syntax/parameters

◆ CA_MGMT_extractCertASN1Name()

◆ CA_MGMT_extractCertDistinguishedName()

◆ CA_MGMT_extractCertTimes()

◆ CA_MGMT_freeCertDistinguishedName()

◆ CA_MGMT_freeCertificate()

◆ CA_MGMT_freeNakedKey()

◆ CA_MGMT_generateCertificateExType()

◆ CA_MGMT_generateCertificateHybrid()

◆ CA_MGMT_generateNakedHybridKey()

◆ CA_MGMT_generateNakedKey()

◆ CA_MGMT_returnCertificatePrints()

◆ CA_MGMT_verifyCertDate()

◆ CA_MGMT_verifyCertWithKeyBlob()