Certificate Store Functions

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

Functions
MOC_EXTERN MSTATUS	CERT_STORE_addIdentity (certStorePtr pCertStore, const ubyte *pDerCert, ubyte4 derCertLength, const ubyte *pKeyBlob, ubyte4 keyBlobLength)
	Load a certificate and key pair into the certificate store. More...
MOC_EXTERN MSTATUS	CERT_STORE_addIdentityEx (certStorePtr pCertStore, ubyte *pAlias, ubyte4 aliasLen, ubyte *pDerCert, ubyte4 derCertLength, ubyte *pKeyBlob, ubyte4 keyBlobLength)
	This is the same as CERT_STORE_addIdentity except the caller also supplies an "alias". More...
MOC_EXTERN MSTATUS	CERT_STORE_addIdentityNakedKey (certStorePtr pCertStore, const ubyte *pKeyBlob, ubyte4 keyBlobLength)
	This API adds a key blob to the certificate store. More...
MOC_EXTERN MSTATUS	CERT_STORE_addIdentityNakedKeyEx (certStorePtr pCertStore, ubyte *pAlias, ubyte4 aliasLen, ubyte *pKeyBlob, ubyte4 keyBlobLength)
	This is the same as CERT_STORE_addIdentityNakedKey, except the caller also supplies an "alias". More...
MOC_EXTERN MSTATUS	CERT_STORE_addIdentityPSK (certStorePtr pCertStore, const ubyte *pPskIdentity, ubyte4 pskIdentityLength, const ubyte *pPskHint, ubyte4 pskHintLength, const ubyte *pPskSecret, ubyte4 pskSecretLength)
	Add a PSK to the certificate store. More...
MOC_EXTERN MSTATUS	CERT_STORE_addIdentityWithCertificateChain (certStorePtr pCertStore, struct SizedBuffer *certificates, ubyte4 numCertificate, const ubyte *pKeyBlob, ubyte4 keyBlobLength)
	This is the same as CERT_STORE_addIdentity except the caller can specify multiple certificates. More...
MOC_EXTERN MSTATUS	CERT_STORE_addIdentityWithCertificateChainEx (certStorePtr pCertStore, ubyte *pAlias, ubyte4 aliasLen, struct SizedBuffer *certificates, ubyte4 numCertificate, const ubyte *pKeyBlob, ubyte4 keyBlobLength)
	This is the same as CERT_STORE_addIdentityWithCertificateChain, except the caller also supplies an "alias". More...
MOC_EXTERN MSTATUS	CERT_STORE_addIdentityWithCertificateChainExtData (certStorePtr pCertStore, struct SizedBuffer *certificates, ubyte4 numCertificate, const ubyte *pKeyBlob, ubyte4 keyBlobLength, ExtendedDataCallback extDataFunc, sbyte4 extDataIdentifier)
	This is the same as CERT_STORE_addIdentityWithCertificateChain, except the caller also supplies a callback and identifier. More...
MOC_EXTERN MSTATUS	CERT_STORE_addIdentityWithCertificateChainExtDataEx (certStorePtr pCertStore, ubyte *pAlias, ubyte4 aliasLen, struct SizedBuffer *certificates, ubyte4 numCertificate, const ubyte *pKeyBlob, ubyte4 keyBlobLength, ExtendedDataCallback extDataFunc, sbyte4 extDataIdentifier)
	This is the same as CERT_STORE_addIdentityWithCertificateChain, except the caller also supplies a callback and identifier. More...
MOC_EXTERN MSTATUS	CERT_STORE_addTrustPoint (certStorePtr pCertStore, const ubyte *pDerTrustPoint, ubyte4 derTrustPointLength)
	Add a trust point to a Digicert SoT Platform certificate store. More...
MOC_EXTERN MSTATUS	CERT_STORE_createStore (certStorePtr *ppNewStore)
	Create a certificate store object. More...
MOC_EXTERN MSTATUS	CERT_STORE_findCertificateByIssuerSerialNumber (const certStorePtr pCertStore, const ubyte *pIssuer, ubyte4 issuerLength, const ubyte *serialNumber, ubyte4 serialNumberLength, const ubyte **ppRetDerCert, ubyte4 *ppRetDerCertLength, const struct AsymmetricKey **pRetPrivateKey)
	Retrieve the certificate and associated private key if available. More...
MOC_EXTERN MSTATUS	CERT_STORE_findIdentityByAlias (certStorePtr pCertStore, ubyte *pAlias, ubyte4 aliasLen, struct AsymmetricKey **ppReturnIdentityKey, ubyte **ppRetDerCert, ubyte4 *pRetDerCertLength)
	Find the identity in the cert store associated with the given "alias". More...
MOC_EXTERN MSTATUS	CERT_STORE_findIdentityByAliasAndAlgo (certStorePtr pCertStore, ubyte4 pubKeyType, ubyte2 keyUsage, ubyte4 *pSupportedCertKeyAlgos, ubyte4 supportedCertKeyAlgosLen, ubyte4 *pSupportedSignAlgos, ubyte4 supportedSignAlgosLen, ubyte *pAlias, ubyte4 aliasLen, struct AsymmetricKey **ppReturnIdentityKey, struct SizedBuffer **ppRetCertificates, ubyte4 *pRetNumCertificates, void **ppRetHint)
	Find the identity in the cert store associated with the given "alias" and verify it satisfies a given public key type, a given keyUsage, and membership in a list of supported cert key algorithms, and membership in a list of supported sign algorithms. More...
MOC_EXTERN MSTATUS	CERT_STORE_findIdentityByTypeFirst (const certStorePtr pCertStore, enum authTypes authType, enum identityTypes identityType, const struct AsymmetricKey **ppRetIdentityKey, const ubyte **ppRetDerCert, ubyte4 *pRetDerCertLength, void **ppRetHint)
	Retrieve the first identity stored for the specified auth type and identity type. More...
MOC_EXTERN MSTATUS	CERT_STORE_findIdentityByTypeNext (const certStorePtr pCertStore, enum authTypes authType, enum identityTypes identityType, const struct AsymmetricKey **ppRetIdentityKey, const ubyte **ppRetDerCert, ubyte4 *pRetDerCertLength, void **ppRetHint)
	This function continues the search for a hint. More...
MOC_EXTERN MSTATUS	CERT_STORE_findIdentityCertChainFirst (const certStorePtr pCertStore, ubyte4 pubKeyType, ubyte4 supportedAlgoFlags, const struct AsymmetricKey **ppRetIdentityKey, const struct SizedBuffer **ppRetCertificates, ubyte4 *pRetNumberCertificate, void **ppRetHint)
	Retrieve the first identity stored for the specified key type and supported algorithm. More...
MOC_EXTERN MSTATUS	CERT_STORE_findIdentityCertChainFirstEx (const certStorePtr pCertStore, ubyte4 pubKeyType, ubyte2 keyUsage, ubyte4 supportedAlgoFlags, const struct AsymmetricKey **ppRetIdentityKey, const struct SizedBuffer **ppRetCertificates, ubyte4 *pRetNumberCertificate, void **ppRetHint)
	Retrieve the first identity stored for the specified key type and supported algorithm. More...
MOC_EXTERN MSTATUS	CERT_STORE_findIdentityCertChainFirstFromList (const certStorePtr pCertStore, ubyte4 pubKeyType, ubyte2 keyUsage, ubyte4 *pSupportedCertKeyIds, ubyte4 supportedCertKeyIdsLen, ubyte4 *pSupportedSignAlgoIds, ubyte4 supportedSignAlgoIdsLen, const struct AsymmetricKey **ppRetIdentityKey, const struct SizedBuffer **ppRetCertificates, ubyte4 *pRetNumberCertificate, void **ppRetHint)
	Retrieve the first identity stored for the specified key type and supported algorithms. More...
MOC_EXTERN MSTATUS	CERT_STORE_findIdentityCertChainNext (const certStorePtr pCertStore, ubyte4 pubKeyType, ubyte4 supportedKeyTypeAndAlgoFlags, const struct AsymmetricKey **ppRetIdentityKey, const struct SizedBuffer **ppRetCertificates, ubyte4 *pRetNumberCertificate, void **ppRetHint)
	Continue the search for an identity from the hint provided. More...
MOC_EXTERN MSTATUS	CERT_STORE_findIdentityCertChainNextEx (const certStorePtr pCertStore, ubyte4 pubKeyType, ubyte2 keyUsage, ubyte4 supportedKeyTypeAndAlgoFlags, const struct AsymmetricKey **ppRetIdentityKey, const struct SizedBuffer **ppRetCertificates, ubyte4 *pRetNumberCertificate, void **ppRetHint)
	Continue the search for an identity from the hint provided. More...
MOC_EXTERN MSTATUS	CERT_STORE_findIdentityCertChainNextFromList (const certStorePtr pCertStore, ubyte4 pubKeyType, ubyte2 keyUsage, ubyte4 *pSupportedCertKeyIds, ubyte4 supportedCertKeyIdsLen, ubyte4 *pSupportedSignAlgoIds, ubyte4 supportedSignAlgoIdsLen, const struct AsymmetricKey **ppRetIdentityKey, const struct SizedBuffer **ppRetCertificates, ubyte4 *pRetNumberCertificate, void **ppRetHint)
	Continue the search for an identity from the hint provided. More...
MOC_EXTERN MSTATUS	CERT_STORE_findTrustPointBySubject (MOC_ASYM(hwAccelDescr hwAccelCtx) const certStorePtr pCertStore, const ubyte *subject, ubyte4 subjectLength, const void *cbArg, CERT_STORE_MatchFun cb, const ubyte **ppRetDerCert, ubyte4 *pRetDerCertLength)
	Find a trusted certificate by subject and user defined callback. More...
MOC_EXTERN MSTATUS	CERT_STORE_findTrustPointBySubjectFirst (const certStorePtr pCertStore, const ubyte *subject, ubyte4 subjectLength, const ubyte **ppRetDerCert, ubyte4 *pRetDerCertLength, const void **iterator)
	Find a trusted certificate by subject. More...
MOC_EXTERN MSTATUS	CERT_STORE_findTrustPointBySubjectNext (const void **iterator, const ubyte **ppRetDerCert, ubyte4 *pRetDerCertLength)
	This function continues a search for a certificate based on the iterator. More...
MOC_EXTERN MSTATUS	CERT_STORE_releaseStore (certStorePtr *ppReleaseStore)
	Delete a certificate store object. More...

Detailed Description

Function Documentation

CERT_STORE_addIdentity()

MOC_EXTERN MSTATUS CERT_STORE_addIdentity	(	certStorePtr	pCertStore,
		const ubyte *	pDerCert,
		ubyte4	derCertLength,
		const ubyte *	pKeyBlob,
		ubyte4	keyBlobLength
	)

The caller provides a key and certificate pair to add into the certificate store. The key and certificate pair can be looked up later on. Note that the key is optional and the caller may only provide the certificate.

This function will parse the certificate and determine the key type the certificate and key pair belong to. It will also determine the signature algorithm used in the certificate. When retrieving the identity from the store the caller can pass in a bit field to restrict the certificate store search to certificates and keys based on the algorithms specified in the bit field.

Note that you can pass in either a cert, or a key and cert, but not a key alone (call CERT_STORE_addIdentityNakedKeyEx for that).

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

• __DISABLE_MOCANA_CERTIFICATE_PARSING__

Parameters

pCertStore	The cert store to which the entry will be added.
pDerCert	The DER of the cert to add.
derCertLength	The length, in bytes, of the cert.
pKeyBlob	If not NULL, the private key partner to the cert, in Mocana key blob format.
keyBlobLength	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.

CERT_STORE_addIdentityEx()

MOC_EXTERN MSTATUS CERT_STORE_addIdentityEx	(	certStorePtr	pCertStore,
		ubyte *	pAlias,
		ubyte4	aliasLen,
		ubyte *	pDerCert,
		ubyte4	derCertLength,
		ubyte *	pKeyBlob,
		ubyte4	keyBlobLength
	)

The alias is a name or label. It is simply another way to search for certs and keys. The caller supplies the cert and key as usual, but also an alias. The alias will be stored with the cert and key, in the same entry of the store. Later on, it will be possible to search for a cert or key (or both) by alias.

This function will check to see if an entry already exists with that alias. If one does exist, it will return an error. This means you cannot replace an entry with new data (same alias, new data). It also means you cannot add new data to an existing entry. For example, you might want to do this: generate a key pair, store the private key, make a cert request, and after you have the cert, add it to the entry with the key. That is not possible. You must add the key and cert at the same time.

Note that you can pass in either a cert, or a key and cert, but not a key alone (call CERT_STORE_addIdentityNakedKeyEx for that).

Note also that if pAlias is NULL, or aliasLen is 0, the function will return an error.

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

• __DISABLE_MOCANA_CERTIFICATE_PARSING__

Parameters

pCertStore	The cert store to which the entry will be added.
pAlias	The alias, or name of the entry.
aliasLen	The length, in bytes, of the alias.
pDerCert	The DER of the cert to add.
derCertLength	The length, in bytes, of the cert.
pKeyBlob	If not NULL, the private key partner to the cert, in Mocana key blob format.
keyBlobLength	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.

CERT_STORE_addIdentityNakedKey()

MOC_EXTERN MSTATUS CERT_STORE_addIdentityNakedKey	(	certStorePtr	pCertStore,
		const ubyte *	pKeyBlob,
		ubyte4	keyBlobLength
	)

This function adds a key blob to the certificate store. The key is stored in certificate store and the key algorithm is stored in the identity. The caller may query for the key identity based on the algorithm.

Parameters

pCertStore	The cert store to which the entry will be added.
pKeyBlob	The private key to store, in Digicert key blob format.
keyBlobLength	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.

CERT_STORE_addIdentityNakedKeyEx()

MOC_EXTERN MSTATUS CERT_STORE_addIdentityNakedKeyEx	(	certStorePtr	pCertStore,
		ubyte *	pAlias,
		ubyte4	aliasLen,
		ubyte *	pKeyBlob,
		ubyte4	keyBlobLength
	)

See the comments for CERT_STORE_addIdentityEx for more on alias.

This function will check to see if an entry already exists with that alias. If one does exist, it will return an error. This means you cannot replace an entry with new data (same alias, new data).

Parameters

pCertStore	The cert store to which the entry will be added.
pAlias	The alias, or name of the entry.
aliasLen	The length, in bytes, of the alias.
pKeyBlob	The private key to store, in Digicert key blob format.
keyBlobLength	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.

CERT_STORE_addIdentityPSK()

MOC_EXTERN MSTATUS CERT_STORE_addIdentityPSK	(	certStorePtr	pCertStore,
		const ubyte *	pPskIdentity,
		ubyte4	pskIdentityLength,
		const ubyte *	pPskHint,
		ubyte4	pskHintLength,
		const ubyte *	pPskSecret,
		ubyte4	pskSecretLength
	)

This API adds a pre-shared secret into the certificate store. The caller provides the PSK identity, the optional PSK hint, and the PSK itself. The PSK identity is the identity value the caller may use to look-up the PSK value itself. Providing a existing identity value will not override the original identity, both identities will exist. The caller may iterate through the list of PSKs based on the identity value. The optional hint value is defined by the user and is retrieved when retrieving a PSK. The hint value is caller specific data. The PSK secret value is the actual PSK data.

Parameters

pCertStore	The cert store to which the PSK will be added.
pPskIdentity	The PSK identity the caller may use to later look-up the the PSK.
pskIdentityLength	The length of the PSK identity.
pPskHint	Optional PSK hint value.
pskHintLength	Length of PSK hint value.
pPskSecret	PSK as a byte array.
pskSecretLength	Length of the PSK.

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.

CERT_STORE_addIdentityWithCertificateChain()

MOC_EXTERN MSTATUS CERT_STORE_addIdentityWithCertificateChain	(	certStorePtr	pCertStore,
		struct SizedBuffer *	certificates,
		ubyte4	numCertificate,
		const ubyte *	pKeyBlob,
		ubyte4	keyBlobLength
	)

The caller provides a key and certificate pair to add into the certificate store. The key and certificate pair can be looked up later on. Multiple certificates can be provided through this API.

This function parses the leaf certificate and key pair for the key algorithm and signature algorithm. The caller may look up the identity pair based on the key algorithm and signature algorithm.

Note that you can pass in either a cert, or a key and cert, but not a key alone (call CERT_STORE_addIdentityNakedKeyEx for that).

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

• __DISABLE_MOCANA_CERTIFICATE_PARSING__

Parameters

pCertStore	The cert store to which the entry will be added.
certificates	The array of DER certificates to add.
numCertificate	The number of DER certificates.
pKeyBlob	If not NULL, the private key partner to the first certificate, in Digicert key blob format.
keyBlobLength	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.

CERT_STORE_addIdentityWithCertificateChainEx()

MOC_EXTERN MSTATUS CERT_STORE_addIdentityWithCertificateChainEx	(	certStorePtr	pCertStore,
		ubyte *	pAlias,
		ubyte4	aliasLen,
		struct SizedBuffer *	certificates,
		ubyte4	numCertificate,
		const ubyte *	pKeyBlob,
		ubyte4	keyBlobLength
	)

See the comments for CERT_STORE_addIdentityEx for more on alias.

This function will check to see if an entry already exists with that alias. If one does exist, it will return an error. This means you cannot replace an entry with new data (same alias, new data). It also means you cannot add new data to an existing entry. For example, you might want to do this: generate a key pair, store the private key, make a cert request, and after you have the cert, add it to the entry with the key. That is not possible. You must add the key and cert at the same time.

The chain can be of length 1.

You can pass in a chain without a key, or a chain with a key (the key must match the first cert in the list, the cert at index 0). But you cannot pass in key without a chain.

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

• __DISABLE_MOCANA_CERTIFICATE_PARSING__

Parameters

pCertStore	The cert store to which the entry will be added.
pAlias	The alias, or name of the entry.
aliasLen	The length, in bytes, of the alias.
certificates	An array of certificates. The cert at index 0 must be the partner to the key (if a key is provided).
numCertificate	The number of certificates in the array.
pKeyBlob	If not NULL, the private key partner to the cert, in Mocana key blob format.
keyBlobLength	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.

CERT_STORE_addIdentityWithCertificateChainExtData()

MOC_EXTERN MSTATUS CERT_STORE_addIdentityWithCertificateChainExtData	(	certStorePtr	pCertStore,
		struct SizedBuffer *	certificates,
		ubyte4	numCertificate,
		const ubyte *	pKeyBlob,
		ubyte4	keyBlobLength,
		ExtendedDataCallback	extDataFunc,
		sbyte4	extDataIdentifier
	)

The callback and identifier will be associated to the key in certificate store.

The chain can be of length 1.

You can pass in a chain without a key, or a chain with a key (the key must match the first cert in the list, the cert at index 0). But you cannot pass in key without a chain.

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

• __DISABLE_MOCANA_CERTIFICATE_PARSING__

Parameters

pCertStore	The cert store to which the entry will be added.
certificates	An array of certificates. The cert at index 0 must be the partner to the key (if a key is provided).
numCertificate	The number of certificates in the array.
pKeyBlob	If not NULL, the private key partner to the cert, in Mocana key blob format.
keyBlobLength	The length, in bytes, of the key blob.
extDataFunc	Pointer to callback associated with key.
extDataIdentifier	A user defined value associated with key.

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.

CERT_STORE_addIdentityWithCertificateChainExtDataEx()

MOC_EXTERN MSTATUS CERT_STORE_addIdentityWithCertificateChainExtDataEx	(	certStorePtr	pCertStore,
		ubyte *	pAlias,
		ubyte4	aliasLen,
		struct SizedBuffer *	certificates,
		ubyte4	numCertificate,
		const ubyte *	pKeyBlob,
		ubyte4	keyBlobLength,
		ExtendedDataCallback	extDataFunc,
		sbyte4	extDataIdentifier
	)

The callback and identifier will be associated to the key in certificate store.

The chain can be of length 1.

You can pass in a chain without a key, or a chain with a key (the key must match the first cert in the list, the cert at index 0). But you cannot pass in key without a chain.

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

• __DISABLE_MOCANA_CERTIFICATE_PARSING__

Parameters

pCertStore	The cert store to which the entry will be added.
certificates	An array of certificates. The cert at index 0 must be the partner to the key (if a key is provided).
numCertificate	The number of certificates in the array.
pKeyBlob	If not NULL, the private key partner to the cert, in Mocana key blob format.
keyBlobLength	The length, in bytes, of the key blob.
extDataFunc	Pointer to callback associated with key.
extDataIdentifier	A user defined value associated with key.

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.

CERT_STORE_addTrustPoint()

MOC_EXTERN MSTATUS CERT_STORE_addTrustPoint	(	certStorePtr	pCertStore,
		const ubyte *	pDerTrustPoint,
		ubyte4	derTrustPointLength
	)

This function adds a trust point to a Digicert SoT Platform certificate store.

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

• __DISABLE_MOCANA_CERTIFICATE_PARSING__

Parameters

pCertStore	Pointer to the SoT Platform certificate store to which to add the trust point.
pDerTrustPoint	Pointer to the trust point to add.
derTrustPointLength	Number of bytes in the trust point (pDerTrustPoint).

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.

CERT_STORE_createStore()

MOC_EXTERN MSTATUS CERT_STORE_createStore

(

certStorePtr *

ppNewStore

)

This function creates a certificate store object. The caller may then use the certificate store APIs to add "identites" to the certificate store. These identities may represent certificates, keys, certifcate/key pairs, and PSKs. These identities, once loaded into the certificate store, may be retrieved at a later point in time through the certificate store APIs.

The caller must free the certificate store once it is done.

Parameters

ppNewStore

Pointer to store the new certificate store.

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.

CERT_STORE_findCertificateByIssuerSerialNumber()

MOC_EXTERN MSTATUS CERT_STORE_findCertificateByIssuerSerialNumber	(	const certStorePtr	pCertStore,
		const ubyte *	pIssuer,
		ubyte4	issuerLength,
		const ubyte *	serialNumber,
		ubyte4	serialNumberLength,
		const ubyte **	ppRetDerCert,
		ubyte4 *	ppRetDerCertLength,
		const struct AsymmetricKey **	pRetPrivateKey
	)

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

• __DISABLE_MOCANA_CERTIFICATE_PARSING__

Parameters

pCertStore	The store to search.
pIssuer	The bytestring representation of the certificate issuer.
issuerLength	The length in bytes of the issuer data.
serialNumber	The serial number of the certificate to be found.
serialNumberLength	The length in bytes of the serial number.
ppRetDerCert	If not NULL, the address where the function will deposit a reference to the cert stored (or cert[0] if it contains a chain) in the entry for the given issuer and serial number.
pRetDerCertLength	If not NULL, the address where the function will deposit the length, in bytes, of the cert.
pRetPrivateKey	If not NULL, the address where the function will deposit a reference to the key object inside the cert store for the entry associated with the given issuer and serial number if available.

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.

CERT_STORE_findIdentityByAlias()

MOC_EXTERN MSTATUS CERT_STORE_findIdentityByAlias	(	certStorePtr	pCertStore,
		ubyte *	pAlias,
		ubyte4	aliasLen,
		struct AsymmetricKey **	ppReturnIdentityKey,
		ubyte **	ppRetDerCert,
		ubyte4 *	pRetDerCertLength
	)

The function will look through the given store, and compare the alias in each entry with the one passed in. If it is the same, it will return the key and cert from that entry.

Note that an entry might have only a key or a cert, or both a key and cert.

The function will return references to the key and cert insde the store, it will not build a new AsymmetricKey object, nor will it allocate memory for the cert it returns. Do not alter or uninit the key and do not alter or free the cert buffer returned.

If the function cannot find an entry with the given alias, it will set the return key and cert args to NULL/0 and return OK. That is, if it finds no entry, that is not an error, it simply indicates there is no entry with that alias.

You might only want a key, and not a cert. If so, you can pass NULL for the ppRetDerCert and pRetDerCertLen args. That is not an error. The function will return a reference to the key and not a cert. Similarly, you can pass NULL for the key and receive only a cert.

It is possible an entry has no key, only a cert. This function will return a pointer to an AsymmetricKey, but it might be empty. Check the return key's type. If it is 0 (akt_undefined), there is no key.

Note that you might have stored a key and cert chain against the alias. However, this function returns only a cert. It returns the first cert in the chain (index 0), which is required to be the cert partner to the key.

Parameters

pCertStore	The store to search.
pAlias	The alias, or name of the entry, against which the cert will be made.
aliasLen	The length, in bytes, of the alias.
ppReturnIdentityKey	If not NULL, the address where the function will deposit a reference to the key object inside the cert store for the entry associated with the alias.
ppRetDerCert	If not NULL, the address where the function will deposit a reference to the cert stored (or cert[0] if it contains a chain) in the entry for the given alias.
pRetDerCertLength	If not NULL, the address where the function will deposit the length, in bytes, of the cert.

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.

CERT_STORE_findIdentityByAliasAndAlgo()

MOC_EXTERN MSTATUS CERT_STORE_findIdentityByAliasAndAlgo	(	certStorePtr	pCertStore,
		ubyte4	pubKeyType,
		ubyte2	keyUsage,
		ubyte4 *	pSupportedCertKeyAlgos,
		ubyte4	supportedCertKeyAlgosLen,
		ubyte4 *	pSupportedSignAlgos,
		ubyte4	supportedSignAlgosLen,
		ubyte *	pAlias,
		ubyte4	aliasLen,
		struct AsymmetricKey **	ppReturnIdentityKey,
		struct SizedBuffer **	ppRetCertificates,
		ubyte4 *	pRetNumCertificates,
		void **	ppRetHint
	)

The function will look through the given store, and compare the alias in each entry with the one passed in. If it is the same, it will return the key and cert from that entry.

Note that an entry might have only a key or a cert, or both a key and cert.

The function will return references to the key and cert insde the store, it will not build a new AsymmetricKey object, nor will it allocate memory for the cert it returns. Do not alter or uninit the key and do not alter or free the cert buffer returned.

If the function cannot find an entry with the given alias, it will set the return key and cert args to NULL/0 and return OK. That is, if it finds no entry, that is not an error, it simply indicates there is no entry with that alias.

You might only want a key, and not a cert. If so, you can pass NULL for the ppRetDerCert and pRetDerCertLen args. That is not an error. The function will return a reference to the key and not a cert. Similarly, you can pass NULL for the key and receive only a cert.

It is possible an entry has no key, only a cert. This function will return a pointer to an AsymmetricKey, but it might be empty. Check the return key's type. If it is 0 (akt_undefined), there is no key.

Note that you might have stored a key and cert chain against the alias. However, this function returns only a cert. It returns the first cert in the chain (index 0), which is required to be the cert partner to the key.

Parameters

pCertStore	The store to search.
pubKeyType	The algorithm of the private key to search for.
keyUsage	The key usage bits to search for in the certificate.
pSupportedCertKeyAlgos	An array of supported algorithm Ids for the certificate key. Pass in NULL if all ids are supported or support information is not relevant. The hashId bits of values in this array will be ignored.
supportedCertKeyAlgosLen	The number of algorithm ids in the pSupportedCertKeyAlgos array.
pSupportedSignAlgos	An array of supported algorithm Ids for the signing algorithm. Pass in NULL if all ids are supported or support information is not relevant.
supportedSignAlgosLen	The number of algorithm ids in the pSupportedSignAlgos array.
pAlias	The alias, or name of the entry, against which the cert will be made.
aliasLen	The length, in bytes, of the alias.
ppReturnIdentityKey	If not NULL, the address where the function will deposit a reference to the key object inside the cert store for the entry associated with the alias.
ppRetCertificates	If not NULL, the address where the function will deposit the certificates found.
pRetNumberCertificate	If not NULL, the address where the function will deposit the number of certificates found.
ppRetHint	If not NULL, the address where the first identity will be stored.

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.

CERT_STORE_findIdentityByTypeFirst()

MOC_EXTERN MSTATUS CERT_STORE_findIdentityByTypeFirst	(	const certStorePtr	pCertStore,
		enum authTypes	authType,
		enum identityTypes	identityType,
		const struct AsymmetricKey **	ppRetIdentityKey,
		const ubyte **	ppRetDerCert,
		ubyte4 *	pRetDerCertLength,
		void **	ppRetHint
	)

This function retrieves the first identity stored in certificate store for the specified auth type and identity type.

For auth types look at the authTypes enum in cert_store.h and for the identity type look at identityTypes enum in cert_store.h. This API retrieves the certificate and key pair stored in the certificate store for the found identity. The hint that is retrieved from this API may be used in other certificate store APIs to start a search from the specified hint. If the first identity does meet the callers criteria then they may use the hint to continue searching for a similar identity.

Parameters

pCertStore	The store to search.
authType	The authentication type. Look at cert_store.h regarding this enum.
identityType	The identity type. Look at cert_store.h regarding this enum.
ppRetIdentityKey	If not NULL, the address where the function will deposit a reference to the key object inside the cert store for the entry associated with the alias.
ppRetDerCert	If not NULL, the address where the function will deposit a reference to the cert stored (or cert[0] if it contains a chain) in the entry for the given alias.
pRetDerCertLength	If not NULL, the address where the function will deposit the length, in bytes, of the cert.
ppRetHint	If not NULL, the address where the first identity will be stored.

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.

CERT_STORE_findIdentityByTypeNext()

MOC_EXTERN MSTATUS CERT_STORE_findIdentityByTypeNext	(	const certStorePtr	pCertStore,
		enum authTypes	authType,
		enum identityTypes	identityType,
		const struct AsymmetricKey **	ppRetIdentityKey,
		const ubyte **	ppRetDerCert,
		ubyte4 *	pRetDerCertLength,
		void **	ppRetHint
	)

The hint is mandatory.

This function is similar to CERT_STORE_findIdentityByTypeFirst but instead of stopping at the first match, the caller must provide a starting hint (through CERT_STORE_findIdentityByTypeFirst or another certificate store API) which will be used as the starting point.

Parameters

pCertStore	The store to search.
authType	The authentication type. Look at cert_store.h regarding this enum.
identityType	The identity type. Look at cert_store.h regarding this enum.
ppRetIdentityKey	If not NULL, the address where the function will deposit a reference to the key object inside the cert store for the entry associated with the alias.
ppRetDerCert	If not NULL, the address where the function will deposit a reference to the cert stored (or cert[0] if it contains a chain) in the entry for the given alias.
pRetDerCertLength	If not NULL, the address where the function will deposit the length, in bytes, of the cert.
ppRetHint	If not NULL, the address where the first identity will be stored.

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.

CERT_STORE_findIdentityCertChainFirst()

MOC_EXTERN MSTATUS CERT_STORE_findIdentityCertChainFirst	(	const certStorePtr	pCertStore,
		ubyte4	pubKeyType,
		ubyte4	supportedAlgoFlags,
		const struct AsymmetricKey **	ppRetIdentityKey,
		const struct SizedBuffer **	ppRetCertificates,
		ubyte4 *	pRetNumberCertificate,
		void **	ppRetHint
	)

This API is the same CERT_STORE_findIdentityCertChainFirstEx but does allow the caller to specify the key usage bits.

Parameters

pCertStore	The store to search.
pubKeyType	The algorithm of the private key to search for.
supportedAlgoFlags	Bit field which can specify both certificate and key algorithms to look for.
ppRetIdentityKey	If not NULL, the address where the function will deposit a reference to the private key.
ppRetCertificates	If not NULL, the address where the function will deposit the certificates found.
pRetNumberCertificate	If not NULL, the address where the function will deposit the number of certificates found.
ppRetHint	If not NULL, the address where the first identity will be stored.

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.

CERT_STORE_findIdentityCertChainFirstEx()

MOC_EXTERN MSTATUS CERT_STORE_findIdentityCertChainFirstEx	(	const certStorePtr	pCertStore,
		ubyte4	pubKeyType,
		ubyte2	keyUsage,
		ubyte4	supportedAlgoFlags,
		const struct AsymmetricKey **	ppRetIdentityKey,
		const struct SizedBuffer **	ppRetCertificates,
		ubyte4 *	pRetNumberCertificate,
		void **	ppRetHint
	)

The caller may use this API to search for a particular identity based on the key type and supported algorithm.

The key type specifies the algorithm to search for. These key types will be the akt_* key values defined in ca_mgmt.h.

To further limit the search the caller must pass in a supported algorithm flags bit field. For further information on these bit fields look at the CERT_STORE_ALGO_* flags defined in cert_store.h. Note that this bit field is both for limiting the search based on certificate and key information.

The certificate and key pair search is also limited on the usage bits set in the certificate itself. The caller may query for particular bits set in the certificate such as the digital signature, key encipherment bit, etc. The key usage bits can be found in parsecert.h. The key usage bit should be an ORing of the bits. For example

(1 << digitalSignature) | (1 << keyEncipherment)

This API will perform an exact match against the key usage bits.

On return, if a valid identity is found based on the algorithms provided, the certificate(s) and key will be returned as well as the hint which the caller may use to continue the search if the identity found is not suitable.

Parameters

pCertStore	The store to search.
pubKeyType	The algorithm of the private key to search for.
keyUsage	The key usage bits to search for in the certificate.
supportedAlgoFlags	Bit field which can specify both certificate and key algorithms to look for.
ppRetIdentityKey	If not NULL, the address where the function will deposit a reference to the private key.
ppRetCertificates	If not NULL, the address where the function will deposit the certificates found.
pRetNumberCertificate	If not NULL, the address where the function will deposit the number of certificates found.
ppRetHint	If not NULL, the address where the first identity will be stored.

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.

CERT_STORE_findIdentityCertChainFirstFromList()

MOC_EXTERN MSTATUS CERT_STORE_findIdentityCertChainFirstFromList	(	const certStorePtr	pCertStore,
		ubyte4	pubKeyType,
		ubyte2	keyUsage,
		ubyte4 *	pSupportedCertKeyIds,
		ubyte4	supportedCertKeyIdsLen,
		ubyte4 *	pSupportedSignAlgoIds,
		ubyte4	supportedSignAlgoIdsLen,
		const struct AsymmetricKey **	ppRetIdentityKey,
		const struct SizedBuffer **	ppRetCertificates,
		ubyte4 *	pRetNumberCertificate,
		void **	ppRetHint
	)

The caller may use this API to search for a particular identity based on the key type and supported algorithms for either the certificate key, the signing algorithm, or both.

The key type specifies the certificate key type to search for. These key types will be the akt_* key values defined in ca_mgmt.h.

To further limit the search the caller may pass in two arrays of supported algorithm ids. One is for the certificate key and one is for the signing algorithm. One may pass in NULL if all keys/algorithms are supported or if support information is not relevant. Each id in the array should be a 32 bit value. The first 8 bits are the keytype as give in ca_mgmt.h. For non-quantum hybrid choices the next 8 bits are the hash algorithm used as given in crypto.h. For ECC based algos the last 8 bits are the curveId as given in ca_mgmt.h. For quantum-safe hybrid choices the middle 16 bits are the quantum-safe identifier as given in ca_mgmt.h with the last 8 bits being the curve identifier. For the certificate key array the hashAlgo bits will be ignored. This will allow callers to pass in the same array for both the the signing algorithm and certificate key in most use cases.

On return, if a valid identity is found based on the algorithms provided, the certificate(s) and key will be returned as well as the hint which the caller may use to continue the search if the identity found is not suitable.

Parameters

pCertStore	The store to search.
pubKeyType	The algorithm of the private key to search for.
keyUsage	The key usage bits to search for in the certificate.
pSupportedCertKeyIds	An array of supported algorithm Ids for the certificate key. Pass in NULL if all ids are supported or support information is not relevant. The hashId bits of values in this array will be ignored.
supportedCertKeyIdsLen	The number of algorithm ids in the pSupportedCertKeyIds array.
pSupportedSignAlgoIds	An array of supported algorithm Ids for the signing algorithm. Pass in NULL if all ids are supported or support information is not relevant.
supportedSignAlgoIdsLen	The number of algorithm ids in the pSupportedSignAlgoIds array.
ppRetIdentityKey	If not NULL, the address where the function will deposit a reference to the private key.
ppRetCertificates	If not NULL, the address where the function will deposit the certificates found.
pRetNumberCertificate	If not NULL, the address where the function will deposit the number of certificates found.
ppRetHint	If not NULL, the address where the first identity will be stored.

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.

CERT_STORE_findIdentityCertChainNext()

MOC_EXTERN MSTATUS CERT_STORE_findIdentityCertChainNext	(	const certStorePtr	pCertStore,
		ubyte4	pubKeyType,
		ubyte4	supportedKeyTypeAndAlgoFlags,
		const struct AsymmetricKey **	ppRetIdentityKey,
		const struct SizedBuffer **	ppRetCertificates,
		ubyte4 *	pRetNumberCertificate,
		void **	ppRetHint
	)

The caller must provide a hint.

This API is the same CERT_STORE_findIdentityCertChainNextEx but does allow the caller to specify the key usage bits.

Parameters

pCertStore	The store to search.
pubKeyType	The algorithm of the private key to search for.
supportedAlgoFlags	Bit field which can specify both certificate and key algorithms to look for.
ppRetIdentityKey	If not NULL, the address where the function will deposit a reference to the private key.
ppRetCertificates	If not NULL, the address where the function will deposit the certificates found.
pRetNumberCertificate	If not NULL, the address where the function will deposit the number of certificates found.
ppRetHint	If not NULL, the address where the first identity will be stored.

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.

CERT_STORE_findIdentityCertChainNextEx()

MOC_EXTERN MSTATUS CERT_STORE_findIdentityCertChainNextEx	(	const certStorePtr	pCertStore,
		ubyte4	pubKeyType,
		ubyte2	keyUsage,
		ubyte4	supportedKeyTypeAndAlgoFlags,
		const struct AsymmetricKey **	ppRetIdentityKey,
		const struct SizedBuffer **	ppRetCertificates,
		ubyte4 *	pRetNumberCertificate,
		void **	ppRetHint
	)

The caller must provide a hint.

This function is the same as CERT_STORE_findIdentityCertChainFirstEx but it will continue the search from the hint provided. A typical flow would be to call CERT_STORE_findIdentityCertChainFirstEx first to get an identity, check whether that identity is suitable or not, and if it is not suitable then call this API with the hint retrieved from CERT_STORE_findIdentityCertChainFirstEx to continue searching. This API will update the hint value provided as new matches are found.

Parameters

pCertStore	The store to search.
pubKeyType	The algorithm of the private key to search for.
keyUsage	The key usage bits to search for in the certificate.
supportedAlgoFlags	Bit field which can specify both certificate and key algorithms to look for.
ppRetIdentityKey	If not NULL, the address where the function will deposit a reference to the private key.
ppRetCertificates	If not NULL, the address where the function will deposit the certificates found.
pRetNumberCertificate	If not NULL, the address where the function will deposit the number of certificates found.
ppRetHint	Hint which specifies where to begin the search from.

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.

CERT_STORE_findIdentityCertChainNextFromList()

MOC_EXTERN MSTATUS CERT_STORE_findIdentityCertChainNextFromList	(	const certStorePtr	pCertStore,
		ubyte4	pubKeyType,
		ubyte2	keyUsage,
		ubyte4 *	pSupportedCertKeyIds,
		ubyte4	supportedCertKeyIdsLen,
		ubyte4 *	pSupportedSignAlgoIds,
		ubyte4	supportedSignAlgoIdsLen,
		const struct AsymmetricKey **	ppRetIdentityKey,
		const struct SizedBuffer **	ppRetCertificates,
		ubyte4 *	pRetNumberCertificate,
		void **	ppRetHint
	)

The caller must provide a hint.

This function is the same as CERT_STORE_findIdentityCertChainFirstFromList but it will continue the search from the hint provided. A typical flow would be to call CERT_STORE_findIdentityCertChainFirstFromList first to get an identity, check whether that identity is suitable or not, and if it is not suitable then call this API with the hint retrieved from CERT_STORE_findIdentityCertChainFirstFromList to continue searching. This API will update the hint value provided as new matches are found.

Parameters

pCertStore	The store to search.
pubKeyType	The algorithm of the private key to search for.
keyUsage	The key usage bits to search for in the certificate.
pSupportedCertKeyIds	An array of supported algorithm Ids for the certificate key. Pass in NULL if all ids are supported or support information is not relevant. The hashId bits of values in this array will be ignored.
supportedCertKeyIdsLen	The number of algorithm ids in the pSupportedCertKeyIds array.
pSupportedSignAlgoIds	An array of supported algorithm Ids for the signing algorithm. Pass in NULL if all ids are supported or support information is not relevant.
supportedSignAlgoIdsLen	The number of algorithm ids in the pSupportedSignAlgoIds array.
ppRetIdentityKey	If not NULL, the address where the function will deposit a reference to the private key.
ppRetCertificates	If not NULL, the address where the function will deposit the certificates found.
pRetNumberCertificate	If not NULL, the address where the function will deposit the number of certificates found.
ppRetHint	Hint which specifies where to begin the search from.

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.

CERT_STORE_findTrustPointBySubject()

MOC_EXTERN MSTATUS CERT_STORE_findTrustPointBySubject	(	MOC_ASYM(hwAccelDescr hwAccelCtx) const certStorePtr	pCertStore,
		const ubyte *	subject,
		ubyte4	subjectLength,
		const void *	cbArg,
		CERT_STORE_MatchFun	cb,
		const ubyte **	ppRetDerCert,
		ubyte4 *	pRetDerCertLength
	)

This function retrieves a trusted certificate based on the subject name. The search begins from the first trusted certificate. The caller passes in the subject name to search by and a user defined callback which is used to determine whether or not the certificate is a valid match or not. This API does not provide a iterator object back to the caller because it will loop through all of the identities and each subject match will invoke the callback to check whether the certificate is suitable or not.

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

• __DISABLE_MOCANA_CERTIFICATE_PARSING__

Parameters

pCertStore	Pointer to the SoT Platform certificate store to search for the certificate.
subject	Pointer to the subject.
subjectLength	Length of the subject in bytes.
cbArg	Caller provided callback argument.
cb	User defined callback to check whether certificate is suitable or not.
ppRetDerCert	Reference to the certificate found. This is an internal reference. The caller should not modify this buffer. Value may be NULL if no certificate is found.
pRetDerCertLength	Length of the certificate found.

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.

CERT_STORE_findTrustPointBySubjectFirst()

MOC_EXTERN MSTATUS CERT_STORE_findTrustPointBySubjectFirst	(	const certStorePtr	pCertStore,
		const ubyte *	subject,
		ubyte4	subjectLength,
		const ubyte **	ppRetDerCert,
		ubyte4 *	pRetDerCertLength,
		const void **	iterator
	)

This function retrieves a trusted certificate based on the subject name. The search begins from the first trusted certificate. The caller passes in the subject name to search by and the certificate and iterator object is returned. The iterator object may be used with other certificate store APIs to continue the search if the certificate found was not suitable.

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

• __DISABLE_MOCANA_CERTIFICATE_PARSING__

Parameters

pCertStore	Pointer to the SoT Platform certificate store to search for the certificate.
subject	Pointer to the subject.
subjectLength	Length of the subject in bytes.
ppRetDerCert	Reference to the certificate found. This is an internal reference. The caller should not modify this buffer. Value may be NULL if no certificate is found.
pRetDerCertLength	Length of the certificate found.
iterator	The current iterator for the certificate found. Value may be NULL if no certificate is found.

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.

CERT_STORE_findTrustPointBySubjectNext()

MOC_EXTERN MSTATUS CERT_STORE_findTrustPointBySubjectNext	(	const void **	iterator,
		const ubyte **	ppRetDerCert,
		ubyte4 *	pRetDerCertLength
	)

This function is similar to CERT_STORE_findTrustPointBySubjectFirst, but it will continue searching for certificates based on the iterator provided by the caller.

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

• __DISABLE_MOCANA_CERTIFICATE_PARSING__

Parameters

iterator	Iterator object to start searching from.
ppRetDerCert	Reference to the certificate found. This is an internal reference. The caller should not modify this buffer. Value may be NULL if no certificate is found.
pRetDerCertLength	Length of the certificate found.

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.

CERT_STORE_releaseStore()

MOC_EXTERN MSTATUS CERT_STORE_releaseStore

(

certStorePtr *

ppReleaseStore

)

This function frees up the certificate store and any identities stored in the certificate store. Note that if the caller has retrieved any references from the certificate store, this call will free up any identities, which will cause the references to be invalidated.

Parameters

ppReleaseStore

Pointer to the certificate store to delete.

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.