 |
TrustCore SDK NanoCrypto API reference
version 7.0
|
|
TrustCore SDK NanoCrypto API reference
version 7.0
|
Header file for the NanoCrypto RC2 API. More...
Go to the source code of this file.
Functions | |
| MOC_EXTERN MSTATUS | CloneRC2Ctx (MOC_SYM(hwAccelDescr hwAccelCtx) BulkCtx pCtx, BulkCtx *ppNewCtx) |
| Clone an existing RC2 context. More... | |
| MOC_EXTERN BulkCtx | CreateRC2Ctx (MOC_SYM(hwAccelDescr hwAccelCtx) ubyte *keyMaterial, sbyte4 keyLength, sbyte4 encrypt) |
| Get a new RC2 context data structure and prepare the key schedule. More... | |
| MOC_EXTERN BulkCtx | CreateRC2Ctx2 (MOC_SYM(hwAccelDescr hwAccelCtx) ubyte *keyMaterial, sbyte4 keyLength, sbyte4 effectiveBits) |
| Get a new RC2 context data structure and prepare the key schedule with arbitrary effective bits. More... | |
| MOC_EXTERN MSTATUS | DeleteRC2Ctx (MOC_SYM(hwAccelDescr hwAccelCtx) BulkCtx *ctx) |
| Delete RC2 context data structure. More... | |
| MOC_EXTERN MSTATUS | DoRC2 (MOC_SYM(hwAccelDescr hwAccelCtx) BulkCtx ctx, ubyte *data, sbyte4 dataLength, sbyte4 encrypt, ubyte *iv) |
| RC2-encrypt or RC2-decrypt a data buffer. More... | |
This file contains the NanoCrypto RC2 API methods.
All the explanatory write-up was added after the 5.3.1 release, and should be eng-reviewed for accuracy and appropriateness.
The RC2 cipher is a block cipher that uses a 64-bit block and a key with a length from 8 to 128 bits. For details about the RC2 algorithm, refer to RFC 2268, A Description of the RC2(r) Encryption Algorithm.
The NanoCrypto RC2 API requires that the key length be specified using a count of bytes. That is, valid key lengths are from 1 to 16, with 16 (128 bits) being the expected value.
The NanoCrypto RC2 API implements the RC2 cipher in CBC mode. No other modes are directly supported.
To apply the RC2 cipher in CBC mode, the NanoCrypto DoRC2() function first checks that the input buffer is a multiple of the RC2 block size, 64 bits. If the check fails, the function returns an error. If the check succeeds, DoRC2() breaks the input plaintext into a series of 64-bit blocks. For the first block in the plaintext, DoRC2() XORs the block with an initialization vector, and then encrypts the result. For all subsequent blocks in the plaintext, DoRC2() XORs the current plaintext block with the ciphertext produced from the encryption of the previous block, and then it encrypts the block.
The process of XORing each plaintext block with a different value (either the initialization vector or the ciphertext of the previous block) transforms plaintext blocks before encryption, which ensures different ciphertext results from identical plaintext. That is, the RC2 mode is good at hiding larger patterns in the ciphertext.
To decrypt a ciphertext block in CBC mode, the DoRC2() function first checks that the input buffer is a multiple of the RC2 block size, 64 bits. If the check fails, the function returns an error. If the check succeeds, DoRC2() reverses the encryption process. For the first block in the ciphertext, DoRC2() decrypts the cipher text, then it XORs the result with the initialization vector. For all subsequent blocks, DoRC2() decrypts the block, then XORs it with the ciphertext of the previous block.
RC2 in CBC mode requires that all buffers input for encryption or decryption have a size that is an even multiple of the RC2 block size, 64 bits. If the buffer is smaller than an even multiple of 64 bits, you must pad the buffer before submitting it to the DoRC2() function. To prevent leakage of information from the first block, CBC mode requires that you never reuse an initialization vector under the same key. Therefore, to encrypt a series of messages under the same Blowfish key in CBC mode, you must base the initialization vector on a counter that is guaranteed not to repeat for as many messages (not blocks) as are to be encrypted under that key.
As input, CBC mode requires an initialization vector (IV), sometimes referred to as a nonce — a value used "not more than once". The generation of this IV is external from the NanoCrypto API functions; that is, you must handle it within your application. Further, the message recipient must know the IV in order to decrypt the message. For the CBC mode, the IV need not be secret, which simplifies the problem of getting the IV to the recipient. However, to save bandwidth, you might prefer a method in which the recipient independently generates the IV, although such a method might not be suitable for the CBC mode, for which the IV must be unpredictable for any given plaintext.
As a source of unique nonce values, you can use a counter (as described in Appendix B of NIST Special Publication 800-38A, 2001 Edition) or a message number. Another commonly used method is to generate a random data block using a FIPS-approved (and therefore cryptographically strong) random number generator to use for the nonce. In addition, IVs for CFB mode should be unique for all messages encrypted under the same key. Reusing an IV leaks information on the first block of plaintext, and on any prefix shared by the two messages.
To enable the NanoCrypto RC2 functions, the following flag must be defined in moptions.h:
__ENABLE_ARC2_CIPHERS__ Additionally, the following flag must not be defined:
__ARC2_HARDWARE_CIPHER__ | MOC_EXTERN MSTATUS CloneRC2Ctx | ( | MOC_SYM(hwAccelDescr hwAccelCtx) BulkCtx | pCtx, |
| BulkCtx * | ppNewCtx | ||
| ) |
This function clones the provided context and returns the cloned context to the caller. The cloned context is at the same state as the caller provided context.
To avoid memory leaks, your application code must call the DeleteRC2Ctx() function after completing RC2-related operations on the cloned context.
To enable the NanoCrypto RC2 functions, the following flag must be defined
__ENABLE_ARC2_CIPHERS__ | pCtx | Pointer to a BulkCtx returned by CreateRC2Ctx. |
| ppNewCtx | Double pointer to the BulkCtx to be created and populated with the key data from the source key. |
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.| MOC_EXTERN BulkCtx CreateRC2Ctx | ( | MOC_SYM(hwAccelDescr hwAccelCtx) ubyte * | keyMaterial, |
| sbyte4 | keyLength, | ||
| sbyte4 | encrypt | ||
| ) |
This function creates and returns a context data structure for RC2 operations, and prepares the key schedule (intermediate key material). This is the first function your application calls when performing RC2 operations (encryption or decryption). Your application uses the returned structure in subsequent DoRC2() functions.
| FIPS Approved | 
|
| Suite B Algorithm |
|
| Flowchart | RC2 |
The RC2 context is an opaque data structure that holds information such as key length, key schedule, and mode of operation. To avoid memory leaks, your application code must call the DeleteRC2Ctx() function after completing RC2-related operations (because the RC2 context is dynamically allocated by this function during context creation).
NULL is returned for the context pointer, you cannot use it as input to any subsequent RC2 function calls.To enable the NanoCrypto RC2 functions, the following flag must be defined
__ENABLE_ARC2_CIPHERS__ | 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_ecb.{c,h} functions. |
| keyMaterial | RC2 key to use for encryption or decryption. |
| keyLength | Number of bytes in the RC2 key; must be a valid RC2 key length (expected value is 16 bytes). |
| encrypt | Unused. An RC2 context is the same for encryption as it is for decryption. |
NULL if any error; otherwise pointer to created RC2 context.| MOC_EXTERN BulkCtx CreateRC2Ctx2 | ( | MOC_SYM(hwAccelDescr hwAccelCtx) ubyte * | keyMaterial, |
| sbyte4 | keyLength, | ||
| sbyte4 | effectiveBits | ||
| ) |
This function creates and returns a context data structure for RC2 operations, and prepares the key schedule (intermediate key material) with arbitrary effective bits. This is the first function your application calls when performing RC2 operations (encryption or decryption). Your application uses the returned structure in subsequent DoRC2() functions.
The RC2 context is an opaque data structure that holds information such as key length, key schedule, and mode of operation. To avoid memory leaks, your application code must call the DeleteRC2Ctx() function after completing RC2-related operations (because the RC2 context is dynamically allocated by this function during context creation).
NULL is returned for the context pointer, you cannot use it as input to any subsequent RC2 function calls.To enable the NanoCrypto RC2 functions, the following flag must be defined
__ENABLE_ARC2_CIPHERS__ | hwAccelCtx | If a hardware acceleration flag is defined, this macro expands to an additional parameter, "hwAccelDescr hwAccelCtx". Otherwise, this macro resolves to nothing. |
| keyMaterial | RC2 key to use for encryption or decryption. |
| keyLength | Number of bytes in the RC2 key; must be a valid RC2 key length (expected value is 16 bytes). |
| effectiveBits | The number of effective bits of key material to prepare. |
NULL if any error; otherwise pointer to created RC2 context.| MOC_EXTERN MSTATUS DeleteRC2Ctx | ( | MOC_SYM(hwAccelDescr hwAccelCtx) BulkCtx * | ctx | ) |
This function deletes an RC2 context previously created by CreateRC2Ctx(). To avoid memory leaks, your application must call this function after completing RC2-related operations for a given context.
| FIPS Approved |
|
| Suite B Algorithm |
|
| Flowchart | RC2 |
To enable the NanoCrypto RC2 functions, the following flag must be defined
__ENABLE_ARC2_CIPHERS__ | 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 RC2 context to delete. |
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.| MOC_EXTERN MSTATUS DoRC2 | ( | MOC_SYM(hwAccelDescr hwAccelCtx) BulkCtx | ctx, |
| ubyte * | data, | ||
| sbyte4 | dataLength, | ||
| sbyte4 | encrypt, | ||
| ubyte * | iv | ||
| ) |
This function RC2-encrypts or RC2-decrypts a data buffer. Before calling this function, your application must call the CreateRC2Ctx() function to dynamically create a valid RC2 context. This function applies the RC2 cipher in CBC mode.
| FIPS Approved |
|
| Suite B Algorithm |
|
| Flowchart | RC2 |
To enable the NanoCrypto RC2 functions, the following flag must be defined
__ENABLE_ARC2_CIPHERS__ | hwAccelCtx | If a hardware acceleration flag is defined, this macro expands to an additional parameter, "hwAccelDescr hwAccelCtx". Otherwise, this macro resolves to nothing. |
| ctx | RC2 context, previously created by CreateRC2Ctx(). |
| data | Data to be encrypted or decrypted in-place. |
| dataLength | Number of bytes of data to be encrypted or decrypted (data). |
| encrypt | TRUE to encrypt the data; FALSE to decrypt the data. |
| iv | Initialization vector. |
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.