primeec_eg.h File Reference

Header for Elliptic Curve El-Gamal operations. More...

Go to the source code of this file.

Functions
MOC_EXTERN MSTATUS	ECEG_decrypt (MOC_ECC(hwAccelDescr hwAccelCtx) ECCKey *pPrivateKey, ubyte *pCiphertext, ubyte4 ciphertextLen, ubyte **ppPlaintext, ubyte4 *pPlaintextLen, void *pExtCtx)
	A one-shot El-Gamal decryption API. More...
MOC_EXTERN MSTATUS	ECEG_decryptPKCSv1p5 (MOC_ECC(hwAccelDescr hwAccelCtx) ECCKey *pPrivateKey, ubyte *pCiphertext, ubyte4 ciphertextLen, ubyte *pPlaintext, void *pExtCtx)
	Performs El-Gamal decryption and removal of PKCS v1.5 padding. More...
MOC_EXTERN MSTATUS	ECEG_encrypt (MOC_ECC(hwAccelDescr hwAccelCtx) ECCKey *pPublicKey, RNGFun rngFun, void *pRngArg, ubyte *pPlaintext, ubyte4 plaintextLen, ubyte **ppCiphertext, ubyte4 *pCiphertextLen, void *pExtCtx)
	A one-shot El-Gamal encryption API. More...
MOC_EXTERN MSTATUS	ECEG_encryptPKCSv1p5 (MOC_ECC(hwAccelDescr hwAccelCtx) ECCKey *pPublicKey, RNGFun rngFun, void *pRngArg, ubyte *pPlaintext, ubyte4 plaintextLen, ubyte *pCiphertext, void *pExtCtx)
	Performs El-Gamal encryption with PKCS v1.5 padding of a small plaintext message. More...
MOC_EXTERN MSTATUS	ECEG_final (MOC_ECC(hwAccelDescr hwAccelCtx) ECEG_CTX *pCtx, void *pExtCtx)
	Finalizes an ECEG_CTX context. More...
MOC_EXTERN MSTATUS	ECEG_init (MOC_ECC(hwAccelDescr hwAccelCtx) ECEG_CTX *pCtx, ECCKey *pKey, ubyte direction, RNGFun rngFun, void *pRngArg, void *pExtCtx)
	Initializes an ECEG_CTX context for encryption or decryption. More...
MOC_EXTERN MSTATUS	ECEG_update (MOC_ECC(hwAccelDescr hwAccelCtx) ECEG_CTX *pCtx, ubyte *pInputData, ubyte4 inputDataLen, ubyte *pOutputData, ubyte4 outputDataBufferLen, ubyte4 *pBytesWritten, void *pExtCtx)
	Updates an ECEG_CTX context with data to be encrypted or decrypted. More...

Detailed Description

Documentation file for Elliptic Curve El-Gamal APIs.

To enable the methods in this file one must define both flags

• __ENABLE_MOCANA_ECC__
• __ENABLE_MOCANA_ECC_ELGAMAL__

primeec_eg.h

Function Documentation

ECEG_decrypt()

MOC_EXTERN MSTATUS ECEG_decrypt	(	MOC_ECC(hwAccelDescr hwAccelCtx) ECCKey *	pPrivateKey,
		ubyte *	pCiphertext,
		ubyte4	ciphertextLen,
		ubyte **	ppPlaintext,
		ubyte4 *	pPlaintextLen,
		void *	pExtCtx
	)

A one-shot El-Gamal decryption API. This will allocate a buffer to hold the resulting plaintext. Be sure to FREE this buffer when done. Note the ciphertextLen must be a multiple of the ciphertext block size. This ciphertext blocksize is 4 times the curve's coordinate size in bytes.

Parameters

pPrivateKey	Pointer to the private key to be used for decryption.
pCiphertext	The buffer of data to be decrypted.
ciphertextLen	The length of the ciphertext in bytes. This must be a multiple of 4 times the curve's coordinate size in bytes. You may use the following table...

• P192 ciphertextLen should be a multiple of 96 bytes.
• P224 ciphertextLen should be a multiple of 112 bytes.
• P256 ciphertextLen should be a multiple of 128 bytes.
• P384 ciphertextLen should be a multiple of 192 bytes.
• P521 ciphertextLen should be a multiple of 264 bytes.

Parameters

ppPlaintext	Pointer to an allocated buffer that will hold the resulting plaintext.
pPlaintextLen	Contents will be set to the number of bytes written to the allocated buffer pointed to by ppPlaintext.
pExtCtx	An extended context reserved for future use.

Warning

Any bytes representing a counter prepended to a block of plaintext during encryption are NOT removed. If encryption was done via MOCANA's APIs then this consists of 4 prepended bytes. It is up to the user to remove or ignore these bytes (ie each block of plaintext recovered will be 4 bytes longer than the original plaintext). Encryption with other products may have a differing protocol with respect to the size and placement of the counter.

Returns

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

ECEG_decryptPKCSv1p5()

MOC_EXTERN MSTATUS ECEG_decryptPKCSv1p5	(	MOC_ECC(hwAccelDescr hwAccelCtx) ECCKey *	pPrivateKey,
		ubyte *	pCiphertext,
		ubyte4	ciphertextLen,
		ubyte *	pPlaintext,
		void *	pExtCtx
	)

Performs El-Gamal decryption and removal of PKCS v1.5 padding. In addition it is assumed there is a 4 byte counter prepended to the padded plaintext and that is also removed. The input ciphertext must consist of a single block, and thus ciphertextLen must be 4 times the curve's coordinate size in bytes.

Parameters

pPrivateKey	Pointer to the private key to be used for decryption.
pCiphertext	The buffer of ciphertext to be decrypted.
ciphertextLen	The length of the ciphertext in bytes. This must be 4 times the curve's coordinate size in bytes. You may use the table...

• P192 ciphertextLen should be 96 bytes.
• P224 ciphertextLen should be 112 bytes.
• P256 ciphertextLen should be 128 bytes.
• P384 ciphertextLen should be 192 bytes.
• P521 ciphertextLen should be 264 bytes.

Parameters

pPlaintext	Buffer to hold the resulting plaintext. The padding will be removed and the original plaintext will be written. If apriori you don't know the length of the resulting plaintext, make sure this buffer has enough space for the curve's coordinate size in bytes minus 15.
pExtCtx	An extended context reserved for future use.

Warning

The ECEG_decryptPKCSv1p5 API assumes encryption used a 4 byte counter prepended to the padded plaintext. This API will not work with an encrytion product that has a different counter size or counter placement protocol.

Returns

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

ECEG_encrypt()

MOC_EXTERN MSTATUS ECEG_encrypt	(	MOC_ECC(hwAccelDescr hwAccelCtx) ECCKey *	pPublicKey,
		RNGFun	rngFun,
		void *	pRngArg,
		ubyte *	pPlaintext,
		ubyte4	plaintextLen,
		ubyte **	ppCiphertext,
		ubyte4 *	pCiphertextLen,
		void *	pExtCtx
	)

A one-shot El-Gamal encryption API. This will allocate a buffer to hold the resulting ciphertext. Be sure to FREE this buffer when done. Note the plaintextLen must be a multiple of the plaintext block size. This plaintext blocksize is 4 bytes less than the curve's coordinate size in bytes.

Parameters

pPublicKey	Pointer to the public key to be used for encryption.
rngFun	Function pointer callback to a method that will provide random entropy.
pRngArg	Optional argument that may be needed by the rngFun provided.
pPlaintext	The buffer of data to be encrypted.
plaintextLen	The length of the plaintext in bytes. This must be a multiple of 4 bytes less than the curve's coordinate size in bytes. You may use the following table...

• P192 plaintextLen should be a multiple of 20 bytes.
• P224 plaintextLen should be a multiple of 24 bytes.
• P256 plaintextLen should be a multiple of 28 bytes.
• P384 plaintextLen should be a multiple of 44 bytes.
• P521 plaintextLen should be a multiple of 62 bytes.

Parameters

ppCiphertext	Pointer to an allocated buffer that will hold the resulting ciphertext.
pCiphertextLen	Contents will be set to the number of bytes written to the allocated buffer pointed to by ppCiphertext.
pExtCtx	An extended context reserved for future use.

Returns

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

ECEG_encryptPKCSv1p5()

MOC_EXTERN MSTATUS ECEG_encryptPKCSv1p5	(	MOC_ECC(hwAccelDescr hwAccelCtx) ECCKey *	pPublicKey,
		RNGFun	rngFun,
		void *	pRngArg,
		ubyte *	pPlaintext,
		ubyte4	plaintextLen,
		ubyte *	pCiphertext,
		void *	pExtCtx
	)

Performs El-Gamal encryption with PKCS v1.5 padding of a small plaintext message. The plaintextLen will be padded up to a full input block length, and thus cannot be bigger than 15 bytes less than the curve's coordinate size. Therefore we recommend only using P256, P384, or P521 with this API.

Parameters

pPublicKey	Pointer to the public key to be used for encryption.
rngFun	Function pointer callback to a method that will provide random entropy.
pRngArg	Optional argument that may be needed by the rngFun provided.
pPlaintext	The buffer of data to be encrypted.
plaintextLen	The length of the plaintext in bytes. This cannot be more than 15 bytes less than the curve's coordinate size...

• P192 plaintextLen cannot be bigger than 9 bytes.
• P224 plaintextLen cannot be bigger than 13 bytes.
• P256 plaintextLen cannot be bigger than 17 bytes.
• P384 plaintextLen cannot be bigger than 33 bytes.
• P521 plaintextLen cannot be bigger than 51 bytes.

Parameters

pCiphertext

A buffer that will hold the resulting ciphertext. The length of the ciphertext will always be 4 times the curve's coordinate size in bytes...

• P192 this buffer length should be 96 bytes.
• P224 this buffer length should be 112 bytes.
• P256 this buffer length should be 128 bytes.
• P384 this buffer length should be 192 bytes.
• P521 this buffer length should be 264 bytes.

Parameters

pExtCtx

An extended context reserved for future use.

Returns

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

ECEG_final()

MOC_EXTERN MSTATUS ECEG_final	(	MOC_ECC(hwAccelDescr hwAccelCtx) ECEG_CTX *	pCtx,
		void *	pExtCtx
	)

Finalizes an ECEG_CTX context. This will validate that the total input length of data was a valid multiple of the input block length, and if so will free and cleanup memory. Please see the ECEG_encrypt and ECEG_decrypt descriptions for more about the input block length.

Parameters

pCtx	Pointer to the context to be finalized.
pExtCtx	An extended context reserved for future use.

Returns

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

ECEG_init()

MOC_EXTERN MSTATUS ECEG_init	(	MOC_ECC(hwAccelDescr hwAccelCtx) ECEG_CTX *	pCtx,
		ECCKey *	pKey,
		ubyte	direction,
		RNGFun	rngFun,
		void *	pRngArg,
		void *	pExtCtx
	)

Initializes an ECEG_CTX context for encryption or decryption. Encryption only will require the use of an random number generator rngFun.

Parameters

pCtx	Pointer to the context to be initialized.
pKey	Pointer to an ECCKey. This must be a public key for encryption and a private key for decryption.
direction	The macro MOCANA_ECEG_ENCRYPT (0) for encryption or the macro MOCANA_ECEG_DECRYPT (1 or anything nonzero) for decryption.
rngFun	Function pointer callback to a method that will provide random entropy. This is only required for encryption and should be NULL for decryption.
pRngArg	Optional argument that may be needed by the rngFun provided.
pExtCtx	An extended context reserved for future use.

Returns

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

ECEG_update()

MOC_EXTERN MSTATUS ECEG_update	(	MOC_ECC(hwAccelDescr hwAccelCtx) ECEG_CTX *	pCtx,
		ubyte *	pInputData,
		ubyte4	inputDataLen,
		ubyte *	pOutputData,
		ubyte4	outputDataBufferLen,
		ubyte4 *	pBytesWritten,
		void *	pExtCtx
	)

Updates an ECEG_CTX context with data to be encrypted or decrypted. This method may be called as many times as neccessary. Output will be written to the pOutputData every time at least a full block length of input data has been surpassed in total. Please see the ECEG_encrypt and ECEG_decrypt descriptions for more about input and output block lengths.

Parameters

pCtx	Pointer to the context to be updated.
pInputData	The buffer of input data.
inputDataLen	The length of the input data in bytes.
pOutputData	Buffer that will hold the resulting output. There will only be output if we have surpassed another full block length of input data in total.
outputDataBufferLen	The length of the pOutputData buffer in bytes.
pBytesWritten	Contents will be set to the number of bytes actually written to the pOutputData buffer.
pExtCtx	An extended context reserved for future use.

Warning

When decrypting, any bytes representing a counter prepended to a block of plaintext during encryption, are NOT removed. If encryption was done via MOCANA's APIs then this consists of 4 prepended bytes. It is up to the user to remove or ignore these bytes (ie each block of plaintext recovered will be 4 bytes longer than the original plaintext). Encryption with other products may have a differing protocol with respect to the size and placement of the counter.

Returns

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