three_des.h File Reference

Header file for the NanoCrypto 3DES API. More...

Go to the source code of this file.

Functions
MOC_EXTERN MSTATUS	Clone3DESCtx (MOC_SYM(hwAccelDescr hwAccelCtx) BulkCtx pCtx, BulkCtx *ppNewCtx)
	Clone a TDES context previously created with Create3DESCtx. More...
MOC_EXTERN BulkCtx	Create2Key3DESCtx (MOC_SYM(hwAccelDescr hwAccelCtx) ubyte *keyMaterial, sbyte4 keyLength, sbyte4 encrypt)
	Get a new 3DES context data structure (for operations using two DES keys) and prepare the key schedule. More...
MOC_EXTERN BulkCtx	Create3DESCtx (MOC_SYM(hwAccelDescr hwAccelCtx) ubyte *keyMaterial, sbyte4 keyLength, sbyte4 encrypt)
	Get a new 3DES context data structure (for operations using three DES keys) and prepare the key schedule. More...
MOC_EXTERN MSTATUS	Delete3DESCtx (MOC_SYM(hwAccelDescr hwAccelCtx) BulkCtx *ctx)
	Delete 3DES context data structure. More...
MOC_EXTERN MSTATUS	Do3DES (MOC_SYM(hwAccelDescr hwAccelCtx) BulkCtx ctx, ubyte *data, sbyte4 dataLength, sbyte4 encrypt, ubyte *iv)
	3DES-encrypt or 3DES-decrypt a data buffer. More...
MOC_EXTERN MSTATUS	Do3DesCbcWithPkcs5Pad (MOC_SYM(hwAccelDescr hwAccelCtx) BulkCtx ctx, ubyte *pDataToProcess, ubyte4 dataLength, ubyte *pProcessedData, ubyte4 bufferSize, ubyte4 *pProcessedDataLen, sbyte4 encryptFlag, ubyte *pInitVector)

Detailed Description

Header file for the NanoCrypto 3DES API.

Function Documentation

Clone3DESCtx()

MOC_EXTERN MSTATUS Clone3DESCtx	(	MOC_SYM(hwAccelDescr hwAccelCtx) BulkCtx	pCtx,
		BulkCtx *	ppNewCtx
	)

Parameters

pCtx	Pointer to a BulkCtx returned by Create3DESCtx.
ppNewCtx	Double pointer to the BulkCtx to be created and populated with the key data from the source key.

Returns

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

Create2Key3DESCtx()

MOC_EXTERN BulkCtx Create2Key3DESCtx	(	MOC_SYM(hwAccelDescr hwAccelCtx) ubyte *	keyMaterial,
		sbyte4	keyLength,
		sbyte4	encrypt
	)

This function creates and returns a context data structure for 3DES operations that use two 3DES keys, and prepares the key schedule (intermediate key material). This is the first function your application calls when performing 3DES operations (encryption or decryption). Your application uses the returned structure in subsequent Do3DES() function calls.

FIPS Approved
Suite B Algorithm
Flowchart	3DES

The 3DES context is an opaque data structure that holds information such as DES context and keys. To avoid memory leaks, your application code must call the Delete3DESCtx() function after completing 3DES-related operations (because the 3DES context is dynamically allocated by this function during context creation).

Warning

If NULL is returned for the context pointer, you cannot use it as input to any subsequent Do3DES() function calls.

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

• __DISABLE_3DES_CIPHERS__

three_des.h

Parameters

hwAccelCtx	If a hardware acceleration flag is defined, this macro expands to an additional parameter, "hwAccelDescr hwAccelCtx". Otherwise, this macro resolves to nothing.
keyMaterial	3DES keys to use for encryption or decryption. Two keys must be provided.
keyLength	Total number of bytes in the 3DES keys; must be a valid 3DES key length (expected value is 16 bytes total for the two keys).
encrypt	TRUE to prepare the key schedule for encryption; FALSE to prepare the key schedule for decryption.

Returns

NULL if any error; otherwise pointer to created 3DES context.

three_des.h

Create3DESCtx()

MOC_EXTERN BulkCtx Create3DESCtx	(	MOC_SYM(hwAccelDescr hwAccelCtx) ubyte *	keyMaterial,
		sbyte4	keyLength,
		sbyte4	encrypt
	)

This function creates and returns a context data structure for 3DES operations that use three 3DES keys, and prepares the key schedule (intermediate key material). This is the first function your application calls when performing 3DES operations (encryption or decryption). Your application uses the returned structure in subsequent Do3DES() function calls.

FIPS Approved
Suite B Algorithm
Flowchart	3DES

The 3DES context is an opaque data structure that holds information such as DES context and keys. To avoid memory leaks, your application code must call the Delete3DESCtx function after completing 3DES-related operations (because the 3DES context is dynamically allocated by this function during context creation).

Warning

If NULL is returned for the context pointer, you cannot use it as input to any subsequent Do3DES() function calls.

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

• __DISABLE_3DES_CIPHERS__

three_des.h

Parameters

hwAccelCtx	If a hardware acceleration flag is defined, this macro expands to an additional parameter, "hwAccelDescr hwAccelCtx". Otherwise, this macro resolves to nothing. But... what does the user specify? In the 5.3.1 docs, we just said that this was "Reserved for future use." Ditto this for all aes_ccm.{c,h} functions.
keyMaterial	3DES keys to use for encryption or decryption. Three keys must be provided.
keyLength	Total umber of bytes in the 3DES keys; must be a valid 3DES key length (expected value is 24 bytes total for the three keys).
encrypt	TRUE to prepare the key schedule for encryption; FALSE to prepare the key schedule for decryption.

Returns

NULL if any error; otherwise pointer to created 3DES context.

three_des.h

Delete3DESCtx()

MOC_EXTERN MSTATUS Delete3DESCtx

(

MOC_SYM(hwAccelDescr hwAccelCtx) BulkCtx *

ctx

)

This function deletes a 3DES context data structure previously created by Create3DESCtx() or Create2Key3DESCtx(). To avoid memory leaks, your application must call this function after completing 3DES-related operations for a given context.

FIPS Approved
Suite B Algorithm
Flowchart	3DES

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

• __DISABLE_3DES_CIPHERS__

three_des.h

Parameters

hwAccelCtx	If a hardware acceleration flag is defined, this macro expands to an additional parameter, "hwAccelDescr hwAccelCtx". Otherwise, this macro resolves to nothing.
ctx	Pointer to 3DES context 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.

three_des.h

Do3DES()

MOC_EXTERN MSTATUS Do3DES	(	MOC_SYM(hwAccelDescr hwAccelCtx) BulkCtx	ctx,
		ubyte *	data,
		sbyte4	dataLength,
		sbyte4	encrypt,
		ubyte *	iv
	)

This function 3DES-encrypts or 3DES-decrypts a data buffer in CBC mode. Before calling this function, your application must call the Create3DESCtx() or Create2Key3DESCtx() function to dynamically create a valid 3DES context.

FIPS Approved
Suite B Algorithm
Flowchart	3DES

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

• __DISABLE_3DES_CIPHERS__

three_des.h

Parameters

hwAccelCtx	If a hardware acceleration flag is defined, this macro expands to an additional parameter, "hwAccelDescr hwAccelCtx". Otherwise, this macro resolves to nothing.
ctx	3DES context, previously created by Create3DESCtx() or Create2Key3DESCtx().
data	Data to be encrypted or decrypted.
dataLength	Number of bytes of data to be encrypted or decrypted (data).
encrypt	TRUE to encrypt the data; FALSE to decrypt the data.
iv	Unique IV for the 3DES operation (encryption or decryption).

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.

three_des.h

Do3DesCbcWithPkcs5Pad()

MOC_EXTERN MSTATUS Do3DesCbcWithPkcs5Pad	(	MOC_SYM(hwAccelDescr hwAccelCtx) BulkCtx	ctx,
		ubyte *	pDataToProcess,
		ubyte4	dataLength,
		ubyte *	pProcessedData,
		ubyte4	bufferSize,
		ubyte4 *	pProcessedDataLen,
		sbyte4	encryptFlag,
		ubyte *	pInitVector
	)

This is the similar to Do3DES, except it will pad the data as well, using the method outlined in PKCS #5. That calls for padding with the padLen bytes of the byte padLen. That is, the pad is

    01
    02 02
    03 03 03
     . . .
    07 07 07 07 07 07 07
    08 08 08 08 08 08 08 08

This processess all the data in one call, it does not process by parts.

Note that P5 padding always pads. When encrypting, if the data length is not a multiple of 8, it will pad to make sure the total length is a multiple of 8. If the length is a multiple of 8, it will pad with 8 bytes. In this way, when decrypting, there is always pad. The decryptor can know how many pad bytes there are.

If encrypting (the encrypt arg is TRUE), the output will be longer than the input. Hence, we can't encrypt in place. That means you must supply the output buffer. If you want to encrypt in place, make sure the buffer has at least 8 bytes beyond the end of dataLength, and pass the same buffer as the processedData arg.

You supply a buffer and its size. If the size is not big enough, the function will set *pProcessedData to the size required and return ERR_BUFFER_TOO_SMALL. But you can simply supply an output buffer to be 8 bytes longer than the input when encrypting, and a buffer the same size as the input buffer when decrypting.

When decrypting, the actual size of output will be smaller than the input, but the function can't know how many pad bytes will be stripped until it decrypts. However, the function will not decrypt until it knows it has an output buffer big enough. Hence, it will require a buffer that is big enough to handle any possible pad size. For simplicity, the function will simply require an output buffer the same size as the input.

The decrypted data will be shorter than the encrypted data. The function will decrypt the last block, strip the padding, and copy only the non-pad bytes into the outpu buffer.

When encrypting, the function will use the 8 bytes at iv to XOR with the first block of plaintext before encrypting. It will then XOR the previous block of ciphertext with each next block of plaintext before encrypting.

Before calling this function, you must build a BulkCtx by calling Create3DESCtx or Create2Key3DESCtx. Call Delete3DESCtx when done with the BulkCtx.

If encrypting, pass in 1 or TRUE for the encryptFlag arg. To decrypt, pass in 0 or FALSE. Note that when you build the BulkCtx, you must specify whether the ctx will be used for encrypting or decrypting.