Typedefs
typedef MSTATUS(*	MKeyContextCallback) (AsymmetricKey pAsymKey, void pLocalInfo, ubyte4 state)

typedef MSTATUS(*	MKeySerialize) (MOC_ASYM(hwAccelDescr hwAccelCtx) AsymmetricKey , serializedKeyFormat, ubyte , ubyte4 )
	This is what an MKeySerialize really is. More...

Functions
MOC_EXTERN MSTATUS	CRYPTO_copyAsymmetricKey (AsymmetricKey pNew, const AsymmetricKey pSrc)
	Copy the contents an AsymmetricKey to another caller allocated AsymmetricKey. More...

MOC_EXTERN MSTATUS	CRYPTO_createDSAKey (AsymmetricKey pKey, struct vlong *ppVlongQueue)
	Populate an existing AsymmetricKey structure with a new DSA key. More...

MOC_EXTERN MSTATUS	CRYPTO_createECCKey (AsymmetricKey *pKey, PEllipticCurvePtr pEC)
	Populate a caller allocated AsymmetricKey structure with a new empty ECC key. More...

MOC_EXTERN MSTATUS	CRYPTO_createECCKeyEx (AsymmetricKey *pKey, ubyte4 eccCurveId)
	Populate a caller allocated AsymmetricKey structure with a new empty ECC key. More...

MOC_EXTERN MSTATUS	CRYPTO_createRSAKey (AsymmetricKey pKey, struct vlong *ppVlongQueue)
	Populate an existing AsymmetricKey structure with a new RSA key. More...

MOC_EXTERN MSTATUS	CRYPTO_deserializeAsymKey (MOC_ASYM(hwAccelDescr hwAccelCtx) ubyte pSerializedKey, ubyte4 serializedKeyLen, MocCtx pMocCtx, AsymmetricKey pDeserializedKey)
	Deserialize a key, building an AsymmetricKey from the byte array that is the key data. More...

MOC_EXTERN MSTATUS	CRYPTO_deserializeAsymKeyWithCreds (MOC_ASYM(hwAccelDescr hwAccelCtx) ubyte pSerializedKey, ubyte4 serializedKeyLen, MocCtx pMocCtx, ubyte pPassword, ubyte4 passwordLen, void pLoadCtx, AsymmetricKey pDeserializedKey)
	Deserialize a key, building an AsymmetricKey from the byte array that is the key data. More...

MOC_EXTERN MSTATUS	CRYPTO_deserializeKey (MOC_ASYM(hwAccelDescr hwAccelCtx) ubyte pSerializedKey, ubyte4 serializedKeyLen, MKeySerialize pSupportedAlgorithms, ubyte4 supportedAlgorithmCount, AsymmetricKey *pDeserializedKey)
	Deserialize a key, building an AsymmetricKey from the byte array that is the key data. More...

MOC_EXTERN MSTATUS	CRYPTO_findKeyInfoComponents (ubyte pKeyInfo, ubyte4 keyInfoLen, ubyte ppAlgId, ubyte4 pAlgIdLen, ubyte *ppKeyData, ubyte4 pKeyDataLen, intBoolean *isPrivate)
	Find the algorithm identifier and the actual key info in the KeyInfo. More...

MOC_EXTERN ubyte4	CRYPTO_getECCurveId (const AsymmetricKey *pKey)
	Get the ECC curveId from an AsymmetricKey. More...

MOC_EXTERN MSTATUS	CRYPTO_getKeyTapInfo (ubyte pKey, ubyte4 keyLen, MocCtx pMocCtx, byteBoolean pIsTap, ubyte4 pProvider, ubyte4 pModuleId)
	Checks a serialized key to see if it is a tradition TAP key or Secure Storage key and outputs the provider and module if so. More...

MOC_EXTERN MSTATUS	CRYPTO_initAsymmetricKey (AsymmetricKey *pKey)
	Initialize a caller allocated AsymmetricKey. More...

MOC_EXTERN MSTATUS	CRYPTO_loadAlgoId (AsymmetricKey pAsymKey, void *ppAlgoId)

MOC_EXTERN MSTATUS	CRYPTO_loadAsymmetricKey (AsymmetricKey pAsymKey, ubyte4 keyType, void *ppAlgKey)
	Load the AlgKey into the AsymKey, transferring ownership to the AsymKey. More...

MOC_EXTERN MSTATUS	CRYPTO_makeKeyInfo (intBoolean isPrivateKey, ubyte pAlgId, ubyte4 algIdLen, ubyte pKeyData, ubyte4 keyDataLen, ubyte *ppKeyInfo, ubyte4 pKeyInfoLen)
	Build SubjectPublicKeyInfo or PrivateKeyInfo. More...

MOC_EXTERN MSTATUS	CRYPTO_matchPublicKey (const AsymmetricKey pKey1, const AsymmetricKey pKey2)
	Determine if two AsymmetricKey structures contain the same key values. More...

MOC_EXTERN MSTATUS	CRYPTO_serializeAsymKey (MOC_ASYM(hwAccelDescr hwAccelCtx) AsymmetricKey pKeyToSerialize, serializedKeyFormat format, ubyte ppSerializedKey, ubyte4 pSerializedKeyLen)
	Serialize an asymmetric key. More...

MOC_EXTERN MSTATUS	CRYPTO_serializeAsymKeyToStorage (MOC_ASYM(hwAccelDescr hwAccelCtx) AsymmetricKey pKeyToSerialize, serializedKeyFormat format, ubyte pId, ubyte4 idLen, ubyte4 tokenId, ubyte *ppSerializedKey, ubyte4 pSerializedKeyLen)
	Serialize an asymmetric key to secure storage with a given token and identifier. More...

MOC_EXTERN MSTATUS	CRYPTO_serializeKey (MOC_ASYM(hwAccelDescr hwAccelCtx) AsymmetricKey pKeyToSerialize, MKeySerialize pSupportedAlgorithms, ubyte4 supportedAlgorithmCount, serializedKeyFormat format, ubyte *ppSerializedKey, ubyte4 pSerializedKeyLen)
	Serialize an asymmetric key. More...

MOC_EXTERN MSTATUS	CRYPTO_setDSAParameters (MOC_DSA(hwAccelDescr hwAccelCtx) AsymmetricKey pKey, const ubyte p, ubyte4 pLen, const ubyte q, ubyte4 qLen, const ubyte g, ubyte4 gLen, const ubyte y, ubyte4 yLen, const ubyte x, ubyte4 xLen, struct vlong **ppVlongQueue)
	Populate an existing AsymmetricKey structure with a new DSA key and sets all of the DSA key parameters. More...

MOC_EXTERN MSTATUS	CRYPTO_setECCParameters (MOC_ECC(hwAccelDescr hwAccelCtx) AsymmetricKey pKey, ubyte4 curveId, const ubyte point, ubyte4 pointLen, const ubyte *scalar, ubyte4 scalarLen)
	Populate a caller allocated AsymmetricKey structure with the provided ECC key data. More...

MOC_EXTERN MSTATUS	CRYPTO_setHybridParameters (AsymmetricKey pKey, ubyte4 curveId, ubyte4 qsAlgId, ubyte pPubKey, ubyte4 pubKeyLen)
	Populate a caller allocated AsymmetricKey structure with the provided hybrid public key data. More...

MOC_EXTERN MSTATUS	CRYPTO_setRSAParameters (MOC_RSA(hwAccelDescr hwAccelCtx) AsymmetricKey pKey, ubyte4 exponent, const ubyte modulus, ubyte4 modulusLen, const ubyte p, ubyte4 pLen, const ubyte q, ubyte4 qLen, struct vlong **ppVlongQueue)
	Populate an existing AsymmetricKey structure with the provided RSA key data. More...

MOC_EXTERN MSTATUS	CRYPTO_uninitAsymmetricKey (AsymmetricKey pKey, struct vlong *ppVlongQueue)
	Uninitialize an AsymmetricKey. More...

MOC_EXTERN MSTATUS	KeySerializeDsa (MOC_ASYM(hwAccelDescr) AsymmetricKey , serializedKeyFormat, ubyte , ubyte4 )
	This is an implementation of MKeySerialize. More...

MOC_EXTERN MSTATUS	KeySerializeEcc (MOC_ASYM(hwAccelDescr) AsymmetricKey , serializedKeyFormat, ubyte , ubyte4 )
	This is an implementation of MKeySerialize. More...

MOC_EXTERN MSTATUS	KeySerializeHybrid (AsymmetricKey , serializedKeyFormat, ubyte , ubyte4 )
	This is an implementation of MKeySerialize. More...

MOC_EXTERN MSTATUS	KeySerializeQs (AsymmetricKey , serializedKeyFormat, ubyte , ubyte4 )
	This is an implementation of MKeySerialize. More...

MOC_EXTERN MSTATUS	KeySerializeRsa (MOC_ASYM(hwAccelDescr) AsymmetricKey , serializedKeyFormat, ubyte , ubyte4 )
	This is an implementation of MKeySerialize. More...

MOC_EXTERN MSTATUS	KeySerializeTpmRsa (AsymmetricKey , serializedKeyFormat, ubyte , ubyte4 )

Typedef Documentation

◆ MKeySerialize

typedef MSTATUS(* MKeySerialize) (MOC_ASYM(hwAccelDescr hwAccelCtx) AsymmetricKey *, serializedKeyFormat, ubyte **, ubyte4 *)

For the serialize and deserialize key functions, you specify which algorithms you support by passing in an array of MKeySerialize. This is what that type is.

Although an MKeySerialize is a function pointer, do not call one directly, only pass them as arguments to the serialize and deserialize functions.

The actual MKeySerialize you pass to the functions will be declared as KeySerialize*, such as KeySerializeRsa, KeySerializeEcc, or KeySerializeDsa.

Note that there is no implementation of MKeySerializ such as KeySerializeMocAsymKey that serializes and deserializes mocasym keys. That is because a MocAsymKey knows how to serialize and deserialize itself. For deserializing into a MocAsymKey, see the documentation for CRYPTO_deserializeKey.

Function Documentation

◆ CRYPTO_copyAsymmetricKey()

MOC_EXTERN MSTATUS CRYPTO_copyAsymmetricKey	(	AsymmetricKey *	pNew,
		const AsymmetricKey *	pSrc
	)

Parameters

pNew	Pointer to the caller allocated AsymmetricKey that will be filled with the contents of the source key.
pSrc	Pointer to the key to be copied.

Returns: OK (0) if successful, otherwise a negative number error code from merrors.h.

◆ CRYPTO_createDSAKey()

MOC_EXTERN MSTATUS CRYPTO_createDSAKey	(	AsymmetricKey *	pKey,
		struct vlong **	ppVlongQueue
	)

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

__ENABLE_MOCANA_DSA__

Parameters

pKey	Pointer to a caller allocated AsymmetricKey structure to be populated with a new DSA key. If the structure already contains another key it will be cleared before being re-populated.
ppVlongQueue	Optional pointer to a vlong queue that will be used for the underlying DSA key creation.

Returns: OK (0) if successful, otherwise a negative number error code from merrors.h.

◆ CRYPTO_createECCKey()

MOC_EXTERN MSTATUS CRYPTO_createECCKey	(	AsymmetricKey *	pKey,
		PEllipticCurvePtr	pEC
	)

Note

This function should not be used with the cryptointerface, use CRYPTO_createECCKeyEx instead. To enable this function, the following flag must be defined:

__ENABLE_MOCANA_ECC__

Parameters

pKey	Pointer to a caller allocated AsymmetricKey structure to be populated.
pEC	One of the prime elliptic curve pointers specifying the curve to use for key creation. The declarations for the various prime curves can be found in primeec.h.

Returns: OK (0) if successful, otherwise a negative number error code from merrors.h.

◆ CRYPTO_createECCKeyEx()

MOC_EXTERN MSTATUS CRYPTO_createECCKeyEx	(	AsymmetricKey *	pKey,
		ubyte4	eccCurveId
	)

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

__ENABLE_MOCANA_ECC__
__ENABLE_MOCANA_CRYPTO_INTERFACE__

Parameters

pKey	Pointer to a caller allocated AsymmetricKey structure to be populated.
eccCurveId	The curveId to use for key creation.

Returns: OK (0) if successful, otherwise a negative number error code from merrors.h.

◆ CRYPTO_createRSAKey()

MOC_EXTERN MSTATUS CRYPTO_createRSAKey	(	AsymmetricKey *	pKey,
		struct vlong **	ppVlongQueue
	)

Parameters

pKey	Pointer to a caller allocated AsymmetricKey structure to be populated with a new RSA key. If the structure already contains another key it will be cleared before populating with the new RSA key data.
ppVlongQueue	Optional pointer to a vlong queue that will be used for the underlying RSA key creation.

Returns: OK (0) if successful, otherwise a negative number error code from merrors.h.

◆ CRYPTO_deserializeAsymKey()

MOC_EXTERN MSTATUS CRYPTO_deserializeAsymKey	(	MOC_ASYM(hwAccelDescr hwAccelCtx) ubyte *	pSerializedKey,
		ubyte4	serializedKeyLen,
		MocCtx	pMocCtx,
		AsymmetricKey *	pDeserializedKey
	)

The caller supplies the serialized key and an initialized AsymmetricKey. The function will determine the format of the serialized key (Digicert blob, DER, etc.), then search through the provided MocCtx for an operator that will know how to deserialize the data and build the appropriate key. If no MocCtx is provided, the internal MocCtx created by the crypto interface core will be used.

If you are deserializing into a MocAsym Key, you can pass NULL for the pMocCtx.

Parameters

pSerializedKey	The byte array that is the serialized key.
serializedKeyLen	The length, in bytes, of the serialized key.
pMocCtx	The MocCtx to use when searching for operators, may be NULL.
pDeserializedKey	The key object into which the key will be placed.

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.

◆ CRYPTO_deserializeAsymKeyWithCreds()

MOC_EXTERN MSTATUS CRYPTO_deserializeAsymKeyWithCreds	(	MOC_ASYM(hwAccelDescr hwAccelCtx) ubyte *	pSerializedKey,
		ubyte4	serializedKeyLen,
		MocCtx	pMocCtx,
		ubyte *	pPassword,
		ubyte4	passwordLen,
		void *	pLoadCtx,
		AsymmetricKey *	pDeserializedKey
	)

Pkcs8 password protoected keys and TAP password protected keys may also be deserialized.

The caller supplies the serialized key and an initialized AsymmetricKey. The function will determine the format of the serialized key (Digicert blob, DER, etc.), then search through the provided MocCtx for an operator that will know how to deserialize the data and build the appropriate key. If no MocCtx is provided, the internal MocCtx created by the crypto interface core will be used.

If you are deserializing into a MocAsym Key, you can pass NULL for the pMocCtx.

Parameters

pSerializedKey	The byte array that is the serialized key.
serializedKeyLen	The length, in bytes, of the serialized key.
pMocCtx	The MocCtx to use when searching for operators, may be NULL.
pPassword	(Optional) The password for pkcs8 or TAP password protected keys.
passwordLen	The length of the password in bytes.
pLoadCtx	(Optional) Pointer to a context that can be used for key loading, typically a `TAP_Context`. If provided it will force the load of `TAP_Key`.
pDeserializedKey	The key object into which the key will be placed.

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.

◆ CRYPTO_deserializeKey()

MOC_EXTERN MSTATUS CRYPTO_deserializeKey	(	MOC_ASYM(hwAccelDescr hwAccelCtx) ubyte *	pSerializedKey,
		ubyte4	serializedKeyLen,
		MKeySerialize *	pSupportedAlgorithms,
		ubyte4	supportedAlgorithmCount,
		AsymmetricKey *	pDeserializedKey
	)

The caller supplies the serialized key and an initialized AsymmetricKey. The function will determine the format of the serialized key (Digicert blob, DER, etc.), then find the appropriate MKeySerialize from the supplied array that will know how to deserialize the data and build the appropriate key.

You also specify which algorithms you are willing to support with the pSupportedAlgorithms array. Suppose you only support ECC keys in your application. Maybe you want to keep your application small, so you don't want to load up code that knows how to serialize RSA or DSA keys. You create an array of MKeySerialize elements and pass that array.

For example,

  AsymmetricKey asymKey;
  MKeySerialize pSupported[2] = {
    KeySerializeRsa,
    KeySerializeEcc
  };

  status = CRYPTO_initAsymmetricKey (&asymKey);
  if (OK != status)
    goto exit;

  status = CRYPTO_deserializeKey (
    pSerializedKey, serializedKeyLen, pSupported, 2, &asymKey);
  if (OK != status)
    goto exit;

    . . .

exit:
  CRYPTO_uninitAsymmetricKey (&asymKey, NULL);

If you want to deserialize a mocasym key, you must initialize the AsymmetricKey with the function CRYPTO_initMocAsymKey. That key object will know how to deserialize a serialized key for that mocasym key, but will not be able to deserialize any other key. So while deserializeKey can generally operate on any key, that is, determine the key algorithm from the serialized data itself and parse it, if the AsymmetricKey is built to be a mocasym key, then it will only know how to parse the appropriate key data. If you have an app that might run across a mocasym key or a non-mocasym key, then you will likely have to call deserializeKey twice, once for the mocasym key and if that didn't work, a second time for general keys.

If you are deserializing into a MocAsym Key, you can pass NULL for the supportedAlgorithms.

Parameters

pSerializedKey	The byte array that is the serialized key.
serializedKeyLen	The length, in bytes, of the serialized key.
pSupportedAlgorithms	An array of MKeySerialize. These are the algorithms your application is willing to support.
supportedAlgorithmCount	The number of entries in the pSupportedAlgorithms array.
pDeserializedKey	The key object into which the key will be placed.

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.

◆ CRYPTO_findKeyInfoComponents()

MOC_EXTERN MSTATUS CRYPTO_findKeyInfoComponents	(	ubyte *	pKeyInfo,
		ubyte4	keyInfoLen,
		ubyte **	ppAlgId,
		ubyte4 *	pAlgIdLen,
		ubyte **	ppKeyData,
		ubyte4 *	pKeyDataLen,
		intBoolean *	isPrivate
	)

The algId might contain necessary info for the key. For example, with DSA and ECC keys, the public parameters are in the algId, not the actual key data. With RSA, there's no key information in the algId.

In addition, the algId contains the OID of the algorithm, in order to verify the key is indeed the key expected.

The KeyInfo might be SubjectPublicKeyInfo or PrivateKeyInfo. Depending on which type of key it is, the algId is in a different location, and the actual key data is wrapped in either a BIT STRING or OCTET STRING, and also in a different location.

This function will find where in the encoding the algID and actual key data are located. It will return pointers to locations inside the encoded key where these values begin. The function does not allocate memory. Do NOT free the buffers returned.

Note that the key data address returned will point to the key data that is wrapped. That is, it will NOT return the OCTET STRING or BIT STRING, but rather the actual data those STRINGs wrap.

The function will indicate whether the key is public or private. The caller passes in the address of an intBoolean, the function will set it to TRUE if the key is private and FALSE if it is public.

Parameters

pKeyInfo	The DER encoding of the key, either SubjectPublicKeyInfo or PrivateKeyInfo.
keyInfoLen	The length, in bytes, of the KeyInfo.
ppAlgId	The address where the function will deposit the address where, in the KeyInfo, the algId begins.
pAlgIdLen	The address where the function will deposit the length, in bytes, of the algId.
ppKeyData	The address where the function will deposit the address where, in the KeyInfo, the KeyData begins.
pKeyDataLen	The address where the function will deposit the length, in bytes, of the KeyData.
isPrivate	The address where the function will deposit TRUE if the serialized key is private or FALSE if it is public.

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.

◆ CRYPTO_getECCurveId()

MOC_EXTERN ubyte4 CRYPTO_getECCurveId ( const AsymmetricKey * pKey )

Parameters

pKey	Pointer to the AsymmetricKey containing an ECC from which to retrieve the curveId.

Returns: One of the nonzero curveId as defined in ca_mgmt.h on success, zero on failure.

◆ CRYPTO_getKeyTapInfo()

MOC_EXTERN MSTATUS CRYPTO_getKeyTapInfo	(	ubyte *	pKey,
		ubyte4	keyLen,
		MocCtx	pMocCtx,
		byteBoolean *	pIsTap,
		ubyte4 *	pProvider,
		ubyte4 *	pModuleId
	)

Parameters

pKey	The serialized key you want to check.
keyLen	The length of the serialized key in bytes.
pMocCtx	The MocCtx to use when searching for operators, may be NULL.
pIsTap	Will be set to `TRUE` if the serialized key is a TAP or Secure Storage Key.
pProvider	Contents will be set to the provider.
pModuleId	Contents will be set to the module id.

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.

◆ CRYPTO_initAsymmetricKey()

MOC_EXTERN MSTATUS CRYPTO_initAsymmetricKey ( AsymmetricKey * pKey )

CRYPTO_uninitAsymmetricKey should be called once the key is no longer needed.

Note: This function does not allocate the AsymmetricKey structure, the caller is responsible for that.

Parameters

pKey	Pointer to the AsymmetricKey to be initialized.

Returns: OK (0) if successful, otherwise a negative number error code from merrors.h.

◆ CRYPTO_loadAsymmetricKey()

MOC_EXTERN MSTATUS CRYPTO_loadAsymmetricKey	(	AsymmetricKey *	pAsymKey,
		ubyte4	keyType,
		void **	ppAlgKey
	)

The caller passes in an existing but empty AsymmetricKey, along with an algorithm key (RSAKey, DSAKey, ECCKey, MocAsymKey). The function will set the AsymKey with the AlgKey. But it will also take ownership, so that when CRYPTO_uninitAsymmetricKey is called, that function will destroy the algorithm key.

For example, suppose you build an RSAKey. Maybe you called RSA_createKey, and RSA_generateKey, or RSA_cloneKey. Normaly, you would perform operations on that object and then when done with it call RSA_freeKey.

However, there is a function you want to call that takes an AsymmetricKey as an argument, not an RSAKey. So you need to "convert" your RSAKey into an AsymmetricKey. To do so, call this load function.

You pass in the empty AsymKey, along with the algorithm key and its type. The function will load the algorithm key and take ownership. You actually pass in the address of the pointer to the algorithm key. The function will go to that address and find the key to load, load it, and then set that address to NULL, indicating that you no longer have direct control of that key, and if you called freeKey, it would not destroy it, because you would be calling freeKey on a NULL.

For example,


  RSAKey *pRSAKey = NULL;
  AsymmetricKey asymKey;

  status = CRYPTO_initAsymmetricKey (&asymKey);
  if (OK != status)
    goto exit;

  status = RSA_createKey (&pRSAKey);
  if (OK != status)
    goto exit;

  status = RSA_generateKey (randCtx, pRSAKey, 2048, NULL);
  if (OK != status)
    goto exit;

  status = CRYPTO_loadAsymmetricKey (
    &asymKey, akt_rsa, (void **)&pRSAKey);
  if (OK != status)
    goto exit;

  // At this point, if the load succeeded, pRSAKey is NULL.

  < rest of operation >

exit:
  RSA_freeKey (&pRSAKey, NULL);
  CRYPTO_uninitAsymmetricKey (&asymKey, NULL);

In the above example, the exit code calls RSA_freeKey because you called RSA_createKey. If the load succeeded, the pointer pRSAKey points to NULL, so the freeKey call will do nothing. So why call freeKey? Because suppose something went wrong during the call to RSA_generateKey, then you would have never loaded the RSAKey, but it would still need to be freed.

Note that the keyType is one of the akt_ enum values.

The third argument is a pointer to pointer. Functions with such an argument are generally constructors or destructors (alloc and free). This is definitely not a constructor, but it isn't exactly a destructor. But it is similar to a destructor in that once you run this function, you no longer have any direct responsibility for the AlgKey.

Parameters

pAsymKey	The key object that will take control of the algorithm key.
keyType	The type of the key, one of the akt_ enum values.
ppAlgKey	The address of an algorithm key object, such as RSAKey, DSAKey, etc.

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.

◆ CRYPTO_makeKeyInfo()

MOC_EXTERN MSTATUS CRYPTO_makeKeyInfo	(	intBoolean	isPrivateKey,
		ubyte *	pAlgId,
		ubyte4	algIdLen,
		ubyte *	pKeyData,
		ubyte4	keyDataLen,
		ubyte **	ppKeyInfo,
		ubyte4 *	pKeyInfoLen
	)

If privateKey is TRUE, build PrivateKeyInfo, if FALSE, build SubjectPublicKeyInfo.

This function will allocate memory for the output buffer and return that buffer at the address given by ppKeyInfo.

◆ CRYPTO_matchPublicKey()

MOC_EXTERN MSTATUS CRYPTO_matchPublicKey	(	const AsymmetricKey *	pKey1,
		const AsymmetricKey *	pKey2
	)

Parameters

pKey1	Key to be compared with key2.
pKey2	Key to be compared with key1.

Returns: OK (0) if keys are equal, otherwise a negative number error code from merrors.h.

◆ CRYPTO_serializeAsymKey()

MOC_EXTERN MSTATUS CRYPTO_serializeAsymKey	(	MOC_ASYM(hwAccelDescr hwAccelCtx) AsymmetricKey *	pKeyToSerialize,
		serializedKeyFormat	format,
		ubyte **	ppSerializedKey,
		ubyte4 *	pSerializedKeyLen
	)

This will "convert" the key object into a single byte array.

An AsymmetricKey contains a key of some algorithm, RSA, DSA, ECC, or custom. If you want it as a single buffer (rather than a collection of integers and other values), call this function. It will allocate memory to hold the serialized key and return that buffer to you. It is the caller's responsibility to free that memory by calling MOC_FREE.

You specify the format of the serialized key with the format argument. It will be one of the values specified in the serializedKeyFormat enum. Note that not all keys will support all formats. For example, you won't be able to serialize an RSAKey using eccPublicKeyDer. It's also possible that some keys won't support all versions of the Digicert blob.

Keys will not be able to be serialized into all formats. Certainly a public key cannot be serialized into a private key DER. But it is also possible that some key cannot be serialized into all Digicert Blob versions. Versions 0 and 1 are older versions and should not be used in new code. They are there for backwards compatibility.

Parameters

pKeyToSerialize	The AsymmetricKey you want serialized.
format	The format into which you want the key to be serialized.
ppSerializedKey	The address where the function will deposit a pointer to allocated memory containing the serialized key. It is the responsiblity of the caller to free that memory using MOC_FREE.
pSerializedKeyLen	the address where the function will deposit the length, in bytes, of the serialized 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.

◆ CRYPTO_serializeAsymKeyToStorage()

MOC_EXTERN MSTATUS CRYPTO_serializeAsymKeyToStorage	(	MOC_ASYM(hwAccelDescr hwAccelCtx) AsymmetricKey *	pKeyToSerialize,
		serializedKeyFormat	format,
		ubyte *	pId,
		ubyte4	idLen,
		ubyte4	tokenId,
		ubyte **	ppSerializedKey,
		ubyte4 *	pSerializedKeyLen
	)

Parameters

pKeyToSerialize	The AsymmetricKey you want serialized.
format	The format into which you want the key's outer identifier to be serialized. The inner key will always be serialized in DER form.
pId	Buffer holding the identifier for the key.
idLen	The length of the id in bytes.
token	The token (ie secure storage application id) to be used.
ppSerializedKey	The address where the function will deposit a pointer to allocated memory containing the serialized key. It is the responsiblity of the caller to free that memory using MOC_FREE.
pSerializedKeyLen	the address where the function will deposit the length, in bytes, of the serialized 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.

◆ CRYPTO_serializeKey()

MOC_EXTERN MSTATUS CRYPTO_serializeKey	(	MOC_ASYM(hwAccelDescr hwAccelCtx) AsymmetricKey *	pKeyToSerialize,
		MKeySerialize *	pSupportedAlgorithms,
		ubyte4	supportedAlgorithmCount,
		serializedKeyFormat	format,
		ubyte **	ppSerializedKey,
		ubyte4 *	pSerializedKeyLen
	)

This will "convert" the key object into a single byte array.

An ASymmetricKey contains a key of some algorithm, RSA, DSA, ECC, or custom. If you want it as a single buffer (rather than a collection of integers and other values), call this function. It will allocate memory to hold the serialized key and return that buffer to you. It is the caller's responsibility to free that memory by calling MOC_FREE.

You specify the format of the serialized key with the format argument. It will be one of the values specified in the serializedKeyFormat enum. Note that not all keys will support all formats. For example, you won't be able to serialize an RSAKey using eccPublicKeyDer. It's also possible that some keys won't support all versions of the Digicert blob.

You also specify which algorithms you are willing to support with the pSupportedAlgorithms array. Suppose you only support ECC keys in your application. Maybe you want to keep your application small, so you don't want to load up code that knows how to serialize RSA or DSA keys. You create an array of MKeySerialize elements and pass that array.

For example,


  ubyte4 pubKeyDerLen;
  ubyte *pPubKeyDer = NULL;
  MKeySerialize pSupported[2] = {
    KeySerializeRsa,
    KeySerializeEcc
  };

  status = CRYPTO_serializeKey (
    &asymKey, pSupported, 2, publicKeyInfoDer,
    &pPubKeyDer, &pubKeyDerLen);
  if (OK != status)
    goto exit;

    . . .

exit:
  MOC_FREE ((void **)&pPubKeyDer);

Keys will not be able to be serialized into all formats. Certainly a public key cannot be serialized into a private key DER. But it is also possible that some key cannot be serialized into all Digicert Blob versions. Versions 0 and 1 are older versions and should not be used in new code. They are there for backwards compatibility.

Parameters

pKeyToSerialize	The AsymmetricKey you want serialized.
pSupportedAlgorithms	An array of MKeySerialize. These are the algorithms your application is willing to support.
supportedAlgorithmCount	The number of entries in the pSupportedAlgorithms array.
format	The format into which you want the key to be serialized.
ppSerializedKey	The address where the function will deposit a pointer to allocated memory containing the serialized key. It is the responsiblity of the caller to free that memory using MOC_FREE.
pSerializedKeyLen	the address where the function will deposit the length, in bytes, of the serialized 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.

◆ CRYPTO_setDSAParameters()

MOC_EXTERN MSTATUS CRYPTO_setDSAParameters	(	MOC_DSA(hwAccelDescr hwAccelCtx) AsymmetricKey *	pKey,
		const ubyte *	p,
		ubyte4	pLen,
		const ubyte *	q,
		ubyte4	qLen,
		const ubyte *	g,
		ubyte4	gLen,
		const ubyte *	y,
		ubyte4	yLen,
		const ubyte *	x,
		ubyte4	xLen,
		struct vlong **	ppVlongQueue
	)

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

__ENABLE_MOCANA_DSA__

Parameters

pKey	Pointer to a caller allocated AsymmetricKey structure to be populated with a new DSA key and its parameters. If the structure already contains another key it will be cleared before being re-populated.
p	Buffer holding the DSA prime p as a Big Endian byte array.
pLen	The length of p in bytes.
q	Buffer holding the DSA cyclic group order q as a Big Endian byte array.
qLen	The length of q in bytes.
g	Buffer holding the DSA cyclic group generator g as a Big Endian byte array.
gLen	The legnth of q in bytes.
y	Optional. Buffer holding the DSA public key y as a Big Endian byte array.
yLen	The length of y in bytes.
x	Optional. Buffer holding the DSA private key x as a Big Endian byte array.
xLen	The length of x in bytes.
ppVlongQueue	Optional. Pointer to a vlong queue that will be used for the underlying DSA key creation.

Returns: OK (0) if successful, otherwise a negative number error code from merrors.h.

◆ CRYPTO_setECCParameters()

MOC_EXTERN MSTATUS CRYPTO_setECCParameters	(	MOC_ECC(hwAccelDescr hwAccelCtx) AsymmetricKey *	pKey,
		ubyte4	curveId,
		const ubyte *	point,
		ubyte4	pointLen,
		const ubyte *	scalar,
		ubyte4	scalarLen
	)

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

__ENABLE_MOCANA_ECC__

Parameters

pKey	Pointer to a caller allocated AsymmetricKey structure to be populated.
curveId	The curveId specifying which curve to use.
point	The public point data.
pointLen	Length in bytes of the point data.
scalar	The private scalar data.
scalarLen	Length in bytes of the scalar data.

Returns: OK (0) if successful, otherwise a negative number error code from merrors.h.

◆ CRYPTO_setHybridParameters()

MOC_EXTERN MSTATUS CRYPTO_setHybridParameters	(	AsymmetricKey *	pKey,
		ubyte4	curveId,
		ubyte4	qsAlgId,
		ubyte *	pPubKey,
		ubyte4	pubKeyLen
	)

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

__ENABLE_MOCANA_ECC__
__ENABLE_MOCANA_QS__

Parameters

pKey	Pointer to a caller allocated AsymmetricKey structure to be populated.
curveId	The curve identifier from ca_mgmt.h.
qsAlgId	The quantum safe algorithm identifier from ca_mgmt.h.
pPubKey	The hybrid public key consisting of an ECC point followed by the QS public key.
pubKeyLen	Length in bytes of the hybrid public key.

Returns: OK (0) if successful, otherwise a negative number error code from merrors.h.

◆ CRYPTO_setRSAParameters()

MOC_EXTERN MSTATUS CRYPTO_setRSAParameters	(	MOC_RSA(hwAccelDescr hwAccelCtx) AsymmetricKey *	pKey,
		ubyte4	exponent,
		const ubyte *	modulus,
		ubyte4	modulusLen,
		const ubyte *	p,
		ubyte4	pLen,
		const ubyte *	q,
		ubyte4	qLen,
		struct vlong **	ppVlongQueue
	)

Parameters

pKey	Pointer to the caller allocated AsymmetricKey structure to be populated.
exponent	RSA public key exponent.
modulus	Pointer to a buffer containing the modulus, represented as a buffer of bytes in big endian format.
modulusLen	Length in bytes of the modulus material.
p	Pointer to a buffer containing first prime number for RSA key calculation. If both primes and associated lengths are not provided, only the public key data will be set.
pLen	Length in bytes of the first prime number.
q	Pointer to a buffer containing second prime number for RSA key calculation. If both primes and associated lengths are not provided, only the public key data will be set.
qLen	Length in bytes of the second prime number.
ppVlongQueue	Optional pointer to a vlong queue to use for this operation.

Returns: OK (0) if successful, otherwise a negative number error code from merrors.h.

◆ CRYPTO_uninitAsymmetricKey()

MOC_EXTERN MSTATUS CRYPTO_uninitAsymmetricKey	(	AsymmetricKey *	pKey,
		struct vlong **	ppVlongQueue
	)

Parameters

pKey	Pointer to the AsymmetricKey to be uninitialized.
ppVlongQueue	Optional pointer to a vlong queue. When freeing RSA and DSA keys, the underlying vlongs will be placed into this queue so other operations can just use the memory from the queue instead of allocating new memory.

Returns: OK (0) if successful, otherwise a negative number error code from merrors.h.