Cipher Object Functions
The Cipher Object is a wrapper that provides a common interface for all supported cryptographic algorithms. It is implemented as a structure containing the addresses of functions, as well as a data pointer that keeps the internal state of the instance. The contents of the data field are private, and should not be accessed or modified externally.
In this section, the following functions in the cipher object are specified:
>New
>Free
New
Creates a new instance of the same type of the cipher object. This function can be used as a generic means to clone a cipher object if two cipher operations must be carried out in parallel.
Synopsis
#include “fmciphobj.h”
struct CipherObj * (*New)(struct CipherObj * ctx);
| Parameter | Description |
|---|---|
ctx
|
The address of an existing cipher object. This parameter must not be NULL. |
Return Value
Address of a new instance of the Cipher Object. If the system does not have enough memory to complete the operation, NULL is returned.
Comments
The returned Cipher Object should be freed by calling its Free() function (see Free).
Free
This function must be used for all cipher objects that are no longer required to free all of its resources. The cipher object must not be used after this function returns.
Synopsis
#include “fmciphobj.h”
int (*Free)(struct CipherObj * ctx);
| Parameter | Description |
|---|---|
ctx
|
The address of the cipher object to be freed. |
Return Value
None
GetInfo
This function can be called to obtain the values of the algorithm-dependent parameters of a cipher object.
Synopsis
#include “fmciphobj.h”
int (*GetInfo)(struct CipherObj * ctx, struct CipherInfo * info);
| Parameter | Description |
|---|---|
ctx
|
The address of a cipher object. |
info
|
The address of the info structure that will contain the algorithm information when the function returns. |
Return Value
0: Operation completed successfully.
Otherwise, an error occured. For descriptions of various error codes generated by cipher object functions, see Cipher Object Function Error Codes.
Comments
The info structure is defined as (from fmciphobj.h):
struct CipherInfo {
char name[32];
unsigned int minKeyLength;
unsigned int maxKeyLength;
unsigned int blockSize;
unsigned int defSignatureSize;
struct CipherObj * ciph;
};
The field meanings are:
>name: Name of the cipher algorithm. Zero terminated.
>minKeyLength: Minimum key length, in number of bytes
>maxKeyLength: Maximum key length, in number of bytes
>blockSize: Cipher block size, in number of bytes
>defSignatureSize: Default Signature size, in number of bytes
>ciph: The address of the cipher object (obsolete, and not filled in by most cipher objects).
EncInit
This function initializes the cipher object for an encrypt operation. It must be called prior to any EncryptUpdate or EncryptFinal calls.
Synopsis
#include “fmciphobj.h”
int (*EncInit)(struct CipherObj * ctx,
int mode,
const void * key, unsigned int klength,
const void * param, unsigned int plength);
| Parameter | Description |
|---|---|
ctx
|
The address of a cipher object instance. |
mode
|
The encrypt mode. Different algorithms support different values for this parameter. Please consult Algorithm-Specific Cipher Information for the possible values for a certain algorithm. |
key
|
The address of a buffer containing the key value. The encoding of the key is algorithm-dependent. However, for most block ciphers, this buffer contains the key value. Please consult Algorithm-Specific Cipher Information for key encoding information. |
klength
|
Number of bytes in the key buffer. |
param
|
The address of the buffer containing various parameters for the encrypt operation. The contents and the encoding of this buffer are algorithm and mode dependent. However, for most block ciphers this buffer contains the IV when one of the CBC modes is used. Please consult Algorithm-Specific Cipher Information for key encoding information. |
plength
|
Number of bytes in the param buffer. |
Return Value
0: The operation was successful.
Otherwise, an error occured. For descriptions of various error codes generated by cipher object functions, see Cipher Object Function Error Codes.
EncryptUpdate
This function is used to encrypt some data. It can be used in two ways: discovering the output buffer length, or performing encryption.
If the target buffer address, tgt, is NULL, then the variable pointed to by plen is updated to contain the length of the output that is required to perform the operation.
If the target buffer address is not NULL, then the currently buffered data and the input buffer contents are combined, and as many blocks as possible are encrypted. The result of the encrypted blocks are placed in the output buffer. If there are any remaining bytes, they are internally buffered. The number of bytes placed in the target buffer is also written to the variable pointed by plen.
Synopsis
#include “fmciphobj.h”
int (*EncryptUpdate)(struct CipherObj * ctx,
void * tgt, unsigned int tlength, unsigned int * plen,
const void * src, unsigned int length);
| Parameter | Description |
|---|---|
ctx
|
The address of a cipher object instance. |
tgt
|
The address of the output buffer. It may be set to NULL for output buffer length estimation. |
tlength
|
Total number of bytes available in the output buffer. |
plen
|
Address of a variable that will receive the number of bytes placed in the target buffer. This variable must not be NULL. |
src
|
Address of the buffer containing the input data. |
length
|
Number of bytes in the src buffer. |
Return Value
0: Operation completed successfully.
Otherwise, an error occured. For descriptions of various error codes generated by cipher object functions, see Cipher Object Function Error Codes.
EncryptFinal
This function must be called to finish an encryption operation. It can be used for either discovering the target buffer length, or for actually performing the operation.
If the target buffer address, tgt, is NULL, then the variable pointed to by plen is updated to contain the length of the output that is required to perform the operation.
If the target buffer address is not NULL, then the currently buffered data is padded (if the mode permits it), and encrypted. The result is placed in the tgt buffer. The number of bytes placed in the target buffer is also written to the variable pointed by plen. If the current mode does not allow padding, and there is buffered data, then an error is returned.
Synopsis
#include “fmciphobj.h”
int (*EncryptFinal)(struct CipherObj * ctx,
void * tgt, unsigned int tlength, unsigned int * plen);
| Parameter | Description |
|---|---|
ctx
|
The address of a cipher object instance. |
tgt
|
The address of the output buffer. It may be set to NULL for output buffer length estimation. |
tlength
|
Total number of bytes available in the output buffer. |
plen
|
Address of a variable that will receive the number of bytes placed in the target buffer. This variable must not be NULL. |
Return Value
0: Operation completed successfully.
Otherwise, an error occured. For descriptions of various error codes generated by cipher object functions, see Cipher Object Function Error Codes.
Comments
This function finalizes the encryption context. EncInit() must be called again to encrypt more data, even when the key is the same.
DecInit
This function initializes the cipher object for a decrypt operation. It must be called prior to any DecryptUpdate or DecryptFinal calls.
Synopsis
#include “fmciphobj.h”
int (*DecInit)(struct CipherObj * ctx,
int mode,
const void * key, unsigned int klength,
const void * param, unsigned int plength);
| Parameter | Description |
|---|---|
ctx
|
The address of a cipher object instance. |
mode
|
The encrypt mode. Different algorithms support different values for this parameter. Please consult Algorithm-Specific Cipher Information for the possible values for a certain algorithm. |
key
|
The address of a buffer containing the key value. The encoding of the key is algorithm-dependent. However, for most block ciphers, this buffer contains the key value. Please consult Algorithm-Specific Cipher Information for key encoding information. |
klength
|
Number of bytes in the key buffer. |
param
|
The address of the buffer containing various parameters for the encrypt operation. The contents and the encoding of this buffer are algorithm and mode dependent. However, for most block ciphers this buffer contains the IV when one of the CBC modes is used. Please consult Algorithm-Specific Cipher Information for key encoding information. |
plength
|
Number of bytes in the param buffer. |
Return Value
0: The operation was successful.
Otherwise, an error occured. For descriptions of various error codes generated by cipher object functions, see Cipher Object Function Error Codes.
DecryptUpdate
This function is used to decrypt some data. This function can be used in two ways: discovering the output buffer length, or performing decryption.
If the target buffer address, tgt, is NULL, then the variable pointed to by plen is updated to contain the length of the output that is required to perform the operation.
If the target buffer address is not NULL, then the currently buffered data and the input buffer contents are combined, and as many blocks as possible are decrypted. The result of the decrypted blocks are placed in the output buffer. If there are any remaining bytes, they are internally buffered. The number of bytes placed in the target buffer is also written to the variable pointed by plen.
Synopsis
#include “fmciphobj.h”
int (*DecryptUpdate)(struct CipherObj * ctx,
void * tgt, unsigned int tlength, unsigned int * plen,
const void * src, unsigned int length);
| Parameter | Description |
|---|---|
ctx
|
The address of a cipher object instance. |
tgt
|
The address of the output buffer. It may be set to NULL for output buffer length estimation. |
tlength
|
Total number of bytes available in the output buffer. |
plen
|
Address of a variable that will receive the number of bytes placed in the target buffer. This variable must not be NULL. |
src
|
Address of the buffer containing the input data. |
length
|
Number of bytes in the src buffer. |
Return Value
0: Operation completed successfully.
Otherwise, an error occured. For descriptions of various error codes generated by cipher object functions, see Cipher Object Function Error Codes.
DecryptFinal
This function must be called to finish a decryption operation. It can be used for either discovering the target buffer length, or for actually performing the operation.
If the target buffer address, tgt, is NULL, then the variable pointed to by plen is updated to contain the length of the output that is required to perform the operation.
If the target buffer address is not NULL, and the mode is padded mode, the final block is decrypted and the padding bytes are removed before they are placed in the tgt buffer. If there is not exactly one block of data in the buffer, an error is returned.
Synopsis
#include “fmciphobj.h”
int (*DecryptFinal)(struct CipherObj * ctx,
void * tgt, unsigned int tlength, unsigned int * plen);
| Parameter | Description |
|---|---|
ctx
|
The address of a cipher object instance. |
tgt
|
The address of the output buffer. It may be set to NULL for output buffer length estimation. |
tlength
|
Total number of bytes available in the output buffer. |
plen
|
Address of a variable that will receive the number of bytes placed in the target buffer. This variable must not be NULL. |
Return Value
0: Operation completed successfully.
Otherwise, an error occured. For descriptions of various error codes generated by cipher object functions, see Cipher Object Function Error Codes.
Comments
This function finalizes the decryption context. DecInit() must be called again to decrypt more data, even when the key is the same.
SignInit
This function initializes the cipher object for a signature (MAC for block ciphers) operation. It must be called prior to any SignUpdate, SignFinal or SignRecover calls.
Synopsis
#include “fmciphobj.h”
int (*SignInit)(struct CipherObj * ctx,
int mode,
const void * key, unsigned int klength,
const void * param, unsigned int plength);
| Parameter | Description |
|---|---|
ctx
|
The address of a cipher object instance. |
mode
|
The encrypt mode. Different algorithms support different values for this parameter. Please consult Algorithm-Specific Cipher Information for the possible values for a certain algorithm. |
key
|
The address of a buffer containing the key value. The encoding of the key is algorithm-dependent. However, for most block ciphers, this buffer contains the key value. Please consult Algorithm-Specific Cipher Information for key encoding information. |
klength
|
Number of bytes in the key buffer. |
param
|
The address of the buffer containing various parameters for the encrypt operation. The contents and the encoding of this buffer are algorithm and mode dependent. However, for most block ciphers this buffer contains the IV when one of the CBC modes is used. Please consult Algorithm-Specific Cipher Information for key encoding information. |
plength
|
Number of bytes in the param buffer. |
Return Value
0: The operation was successful.
Otherwise, an error occured. For descriptions of various error codes generated by cipher object functions, see Cipher Object Function Error Codes.
SignUpdate
This function can be used to update a multi-part signing or MAC operation.
Synopsis
#include “fmciphobj.h”
int (*SignUpdate)(struct CipherObj * ctx,
const void * src, unsigned int length);
| Parameter | Description |
|---|---|
ctx
|
The address of a cipher object instance. |
src
|
Address of the buffer containing the input data. |
length
|
Number of bytes in the src buffer. |
Return Value
0: Operation completed successfully.
Otherwise, an error occured. For descriptions of various error codes generated by cipher object functions, see Cipher Object Function Error Codes.
Comments
Usually, only block cipher algorithms implement this function.
SignFinal
This function must be called to finish a signing or MAC operation. It can be used for either discovering the target buffer length, or for actually performing the operation.
If the target buffer address, tgt, is NULL, then the variable pointed to by plen is updated to contain the length of the output that is required to perform the operation.
If the target buffer address is not NULL, then the signing operation is completed, and the signature is placed in the output buffer.
Synopsis
#include “fmciphobj.h”
int (*SignFinal)(struct CipherObj * ctx,
void * tgt, unsigned int tlength, unsigned int * plen);
| Parameter | Description |
|---|---|
ctx
|
The address of a cipher object instance. |
tgt
|
The address of the output buffer. It may be set to NULL for output buffer length estimation. |
tlength
|
Total number of bytes available in the output buffer. |
plen
|
Address of a variable that will receive the number of bytes placed in the target buffer. This variable must not be NULL. |
Return Value
0: Operation completed successfully.
Otherwise, an error occured. For descriptions of various error codes generated by cipher object functions, see Cipher Object Function Error Codes.
Comments
This function finalizes the signature context. SignInit() must be called again to sign more data, even when the key is the same.
SignRecover
This function implements a single-part signing or MAC operation. It can be used for either discovering the target buffer length, or for actually performing the operation.
If the target buffer address, tgt, is NULL, then the variable pointed to by plen is updated to contain the length of the output that is required to perform the operation.
If the target buffer address is not NULL, then the signing operation is performed, and the signature is placed in the output buffer.
Synopsis
#include “fmciphobj.h”
int (*SignRecover)(struct CipherObj * ctx,
void * tgt, unsigned int tlength, unsigned int * plen,
const void * src, unsigned int length);
| Parameter | Description |
|---|---|
ctx
|
The address of a cipher object instance. |
tgt
|
The address of the output buffer. It may be set to NULL for output buffer length estimation. |
tlength
|
Total number of bytes available in the output buffer. |
plen
|
Address of a variable that will receive the number of bytes placed in the target buffer. This variable must not be NULL. |
src
|
Address of the buffer containing the input data. |
length
|
Number of bytes in the src buffer. |
Return Value
0: The operation was successful.
Otherwise, an error occured. For descriptions of various error codes generated by cipher object functions, see Cipher Object Function Error Codes.
Comments
Most block cipher algorithm cipher objects do not implement this function.
VerifyInit
This function initializes the cipher object for a signature or MAC verification operation. It must be called prior to any VerifyUpdate, VerifyFinal, Verify or VerifyRecover calls.
Synopsis
#include “fmciphobj.h”
int (*VerifyInit)(struct CipherObj * ctx,
int mode,
const void * key, unsigned int klength,
const void * param, unsigned int plength);
| Parameter | Description |
|---|---|
ctx
|
The address of a cipher object instance. |
mode
|
The encrypt mode. Different algorithms support different values for this parameter. Please consult Algorithm-Specific Cipher Information for the possible values for a certain algorithm. |
key
|
The address of a buffer containing the key value. The encoding of the key is algorithm-dependent. However, for most block ciphers, this buffer contains the key value. Please consult Algorithm-Specific Cipher Information for key encoding information. |
klength
|
Number of bytes in the key buffer. |
param
|
The address of the buffer containing various parameters for the encrypt operation. The contents and the encoding of this buffer are algorithm and mode dependent. However, for most block ciphers this buffer contains the IV when one of the CBC modes is used. Please consult Algorithm-Specific Cipher Information for key encoding information. |
plength
|
Number of bytes in the param buffer. |
Return Value
0: The operation was successful.
Otherwise, an error occured. For descriptions of various error codes generated by cipher object functions, see Cipher Object Function Error Codes.
VerifyUpdate
This function can be used to update a multi-part signature or MAC verification operation.
Synopsis
#include “fmciphobj.h”
int (*VerifyUpdate)(struct CipherObj * ctx,
const void * src, unsigned int length);
| Parameter | Description |
|---|---|
ctx
|
The address of a cipher object instance. |
src
|
Address of the buffer containing the input data. |
length
|
Number of bytes in the src buffer. |
Return Value
0: Operation completed successfully.
Otherwise, an error occured. For descriptions of various error codes generated by cipher object functions, see Cipher Object Function Error Codes.
Comments
Usually, only block cipher algorithms implement this function.
VerifyFinal
This function must be called to finish a signature or MAC verification operation. It can be used for either discovering the target buffer length, or for actually performing the operation.
If the target buffer address, tgt, is NULL, then the variable pointed to by plen is updated to contain the length of the output that is required to perform the operation.
If the target buffer address is not NULL, then the verification operation is completed. In addition to the verification, the recovered signature is placed in the output buffer.
Synopsis
#include “fmciphobj.h”
int (*VerifyFinal)(struct CipherObj * ctx,
const void * sig, unsigned int slength,
void * tgt, unsigned int tlength, unsigned int * plen);
| Parameter | Description |
|---|---|
ctx
|
The address of a cipher object instance. |
sig
|
The address of the buffer containing the signature or the MAC. |
slength
|
Number of bytes in the sig buffer. |
tgt
|
The address of the output buffer. It may be set to NULL for output buffer length estimation. |
tlength
|
Total number of bytes available in the output buffer. |
plen
|
Address of a variable that will receive the number of bytes placed in the target buffer. This variable must not be NULL. |
Return Value
0: The signature or MAC was correct.
Otherwise, an error occured or the signature or MAC was incorrect. For descriptions of various error codes generated by cipher object functions, see Cipher Object Function Error Codes.
Comments
This function finalizes the verification context. VerifyInit() must be called again to verify more data, even when the key is the same.
VerifyRecover
This function implements a single-part signature or MAC verification operation with recovery. It can be used for either discovering the target buffer length, or for actually performing the operation.
If the target buffer address, tgt, is NULL, then the variable pointed to by plen is updated to contain the length of the output that is required to perform the operation.
If the target buffer address is not NULL, then the verification operation is performed. In addition to the verification, the recovered signature is placed in the output buffer.
Synopsis
#include “fmciphobj.h”
int (*VerifyRecover)(struct CipherObj * ctx,
const void * sig, unsigned int slength,
void * tgt, unsigned int tlength, unsigned int * plen,
const void * src, unsigned int length);
| Parameter | Description |
|---|---|
ctx
|
The address of a cipher object instance. |
sig
|
The address of the buffer containing the signature or the MAC. |
slength
|
Number of bytes in the sig buffer. |
tgt
|
The address of the output buffer. It may be set to NULL for output buffer length estimation. |
tlength
|
Total number of bytes available in the output buffer. |
plen
|
Address of a variable that will receive the number of bytes placed in the target buffer. This variable must not be NULL. |
src
|
Address of the buffer containing the input data. |
length
|
Number of bytes in the src buffer. |
Return Value
0: The operation was successful.
Otherwise, an error occured. For descriptions of various error codes generated by cipher object functions, see Cipher Object Function Error Codes.
Comments
Most block cipher algorithm cipher objects do not implement this function.
This function finalizes the verification context. VerifyInit() must be called again to verify more data, even when the key is the same.
Verify
This function implements a single-part signature or MAC verification operation without recovery. The return value indicates whether the signature or MAC was correct.
Synopsis
#include “fmciphobj.h”
int (*Verify)(struct CipherObj * ctx,
const void * sig, unsigned int slength,
const void * src, unsigned int length);
| Parameter | Description |
|---|---|
ctx
|
The address of a cipher object instance. |
sig
|
The address of the buffer containing the signature or the MAC. |
slength
|
Number of bytes in the sig buffer. |
src
|
Address of the buffer containing the input data. |
length
|
Number of bytes in the src buffer. |
Return Value
0: The operation was successful.
Otherwise, an error occured. For descriptions of various error codes generated by cipher object functions, see Cipher Object Function Error Codes.
Comments
Most block cipher algorithm cipher objects do not implement this function.
This function finalizes the verification context. VerifyInit() must be called again to verify more data, even when the key is the same.
LoadParam
This function may be used to load the saved parameters of a cipher object. This function is used in conjunction with the UnloadParam function.
Synopsis
#include “fmciphobj.h”
int (*LoadParam)(struct CipherObj * ctx,
const void * param, unsigned int length);
| Parameter | Description |
|---|---|
ctx
|
The address of a cipher object instance. |
param
|
The address of the buffer containing various parameters for the encrypt operation. The contents and the encoding of this buffer are algorithm and mode dependent. However, for most block ciphers this buffer contains the IV when one of the CBC modes is used. Please consult Algorithm-Specific Cipher Information for key encoding information. |
length
|
Number of bytes in the param buffer. |
Return Value
0: The operation was successful.
Otherwise, an error occured. For descriptions of various error codes generated by cipher object functions, see Cipher Object Function Error Codes.
Comments
The LoadParam and UnloadParam functions are not very useful, as they do not encode the key value along with the operational parameters.
UnloadParam
This function may be used to save the operational parameters of a cipher object. This function is used in conjunction with the LoadParam function.
Synopsis
#include “fmciphobj.h”
int (*UnloadParam)(struct CipherObj * ctx,
void * param, unsigned int length, unsigned int *plen);
| Parameter | Description |
|---|---|
ctx
|
The address of a cipher object instance. |
param
|
The address of the buffer containing various parameters for the encrypt operation. The contents and the encoding of this buffer are algorithm and mode dependent. However, for most block ciphers this buffer contains the IV when one of the CBC modes is used. Please consult Algorithm-Specific Cipher Information for key encoding information. |
length
|
Number of bytes in the param buffer. |
plen
|
Address of a variable that will receive the number of bytes placed in the param buffer. This variable must not be NULL. |
Return Value
0: The operation was successful.
Otherwise, an error occured. For descriptions of various error codes generated by cipher object functions, see Cipher Object Function Error Codes.
Comments
The LoadParam and UnloadParam functions are not very useful, as they do not encode the key value along with the operational parameters.
Config (Obsolete)
This function can be used to restore the configuration of a cipher object. It is used in conjunction with the Status function.
Synopsis
#include “fmciphobj.h”
int (*Config)(struct CipherObj * ctx, const void * parameters, unsigned int length);
| Parameter | Description |
|---|---|
ctx
|
The address of a cipher object instance. |
parameters
|
The address of the buffer that contains the information returned from the Status function. |
length
|
Number of bytes in the parameters buffer. |
Return Value
0: Operation was successful
Otherwise, an error occured. For descriptions of various error codes generated by cipher object functions, see Cipher Object Function Error Codes.
Comments
This function is now obsolete, and is not implemented by any of the cipher objects.
Status (Obsolete)
This function can be used to take a snapshot of the current configuration of the cipher object, which can be used to restore it using the Config function.
Synopsis
#include “fmciphobj.h”
int (*Status)(struct CipherObj * ctx, void * parameters, unsigned int length);
| Parameter | Description |
|---|---|
ctx
|
The address of a cipher object instance. |
parameters
|
The address of the buffer that contains the configuration information. |
length
|
Number of bytes in the parameters buffer. |
Return Value
0: Operation was successful
Otherwise, an error occured. For descriptions of various error codes generated by cipher object functions, see Cipher Object Function Error Codes.
Comments
This function is now obsolete, and is not implemented by any of the cipher objects.
EncodeState (Obsolete)
This function definition is left for historical reasons. None of the Cipher objects implement this.
DecodeState (Obsolete)
This function definition is left for historical reasons. None of the Cipher objects implement this.
Cipher Object Function Error Codes
The table below lists the error codes that may be returned from cipher object functions.
| Name | Value | Description |
|---|---|---|
CO_PARAM_INVALID
|
0x0001 | Some input value is invalid or missing. |
CO_SIG_INVALID
|
0x0002 | Bad signature during verify operation. |
CO_LENGTH_INVALID
|
0x0003 | Invalid length of data or parameter i.e. not multiple of block. |
CO_DEVICE_ERROR
|
0x0004 | An unexpected internal error that may be caused by bad input data. |
CO_GENERAL_ERROR
|
0x0005 | An unexpected internal error that may be caused by bad input data. |
CO_MEMORY_ERROR
|
0x0006 | malloc() failed. |
CO_BUFFER_TOO_SMALL
|
0x0007 | Output buffer supplied to command is too small. |
CO_DATA_INVALID
|
0x0008 | Input data badly formatted. |
CO_NEED_IV_UPDATE
|
0x0009 | Not used. |
CO_NOT_SUPPORTED
|
0x000A | CiphObj member function not implemented. For example, HMAC Encrypt. |
CO_DUPLICATE_IV_FOUND
|
0x000B | Only possible with DES3 output feedback (OFB) mode. |
CO_FIPSG_ERROR
|
0x000C | Not used. |
CO_FUNCTION_NOT_IMPLEMENTED
|
0x000D | CiphObj member function not implemented. For example,HMAC Encrypt. |
CO_POINT_INVALID
|
0x000E | Public key is not valid for the ECC curve. |
