RSA BSAFE Cert-C

EXTENSION_HANDLER Reference

Cert-C provides a default extension handler for each Cert-C-defined extension type. However, when overriding a default extension handler or when defining a new extension type, it is necessary to provide the callback functions. The following table lists the four callback functions to provide for each extension type, and the Cert-C functions that call each callback function:

Callback Function	Cert-C Functions that Call the Callback
`AllocAndCopy`	C_AddExtensionValue()
`Destructor`	C_DeleteExtensionValue()
`GetEncodedValue`	C_GetEncodedExtensionValue()
`SetEncodedValue`	C_SetEncodedExtensionValue() C_SetExtensionsObjectBER() C_SetExtensionBER()

The EXTENSION_HANDLER structure is used in the EXTENSION_TYPE_INFO structure, and as:

An input to the C_RegisterExtensionType() function. Use this function to:

Specify a customized extension handler for a Cert-C-defined extension type
Specify an application-defined extension type

Note: When overriding the default handler or registering a new extension type, it is necessary to provide all the callback functions listed in EXTENSION_HANDLER. Otherwise, Cert-C returns an error when calling C_RegisterExtensionType().

An output from the C_GetExtensionTypeInfo() function. Use this function to get the default or registered extension handler for a particular extension type.

An input to the C_CreateExtension() function. Use this function to override the default or registered extension handler for a particular extension type.

C_GetExtensionTypeInfo

C_RegisterExtensionType

Data Fields

AllocAndCopy	The AllocAndCopy callback function allocates memory for newValue and copies the information given in value to newValue. If AllocAndCopy is successful, it returns `0` (zero). If AllocAndCopy fails to allocate memory, it returns the `E_ALLOC` error. If the data in value is not valid, then AllocAndCopy does not allocate memory and it returns the `E_DATA` error. This function is called by C_AddExtensionValue() to add an extension value into an existing extension entry. newValue An output field that contains the new copy of value that is returned by the AllocAndCopy function. value An input field that contains extension information to be duplicated by the AllocAndCopy function.
Destructor	The Destructor callback function de-allocates the value that was allocated by AllocAndCopy, freeing all memory associated with it. If the value is `(POINTER)NULL_PTR`, then Destructor performs no operation. The Destructor function is called by the C_DeleteExtensionValue() function to delete an extension value from an extension entry.
GetEncodedValue	The GetEncodedValue callback function is called by the C_GetEncodedExtensionValue() function to encode the extension entry's value list. GetEncodedValue calls the C_GetListObjectCount() and C_GetListObjectEntry() functions to extract the extension value(s) to be encoded from the valueList. GetEncodedValue allocates a block of memory to store the encoded value and saves a pointer to this block in der and its length in derLen. GetEncodedValue encodes all the value(s) in the valueList. If GetEncodedValue is successful, it returns `0` (zero); if it fails, it returns a non-zero value. The C_GetEncodedExtensionValue() function saves the der value in the extension entry. The der value is destroyed when you modify or destroy the extension entry that owns the valueList. valueList An input field containing the list of extension values that are to be encoded by the GetEncodedValue function. der An output field that the GetEncodedValue function uses to store the encoded extension values. derLen An output field that contains the length of the encoded extension values.
SetEncodedValue	The SetEncodedValue callback function decodes the extension value given in ber and berLen into a C data structure representation of the value(s). The Cert-C function passes a listEntryHandler to SetEncodedValue. The list handler includes its own AllocAndCopy and Destructor callbacks that recognize the data structure for the decoded value of this extension type. SetEncodedValue calls the C_AddListObjectEntry() function to add the C data structure representation of the value(s) to the valueList. These new value entries can be destroyed by the C_DeleteExtension(), C_DeleteExtensionValue(), or C_DestroyExtensionsObject() functions. The Cert-C function that calls this function creates valueList; it is destroyed when the extension that owns the valueList is destroyed. This function is called by C_SetExtensionsObjectBER(), C_SetExtensionBER(), and C_SetEncodedExtensionValue(). valueList An input field containing the list of extension values that are to be decoded by the SetEncodedValue function. The Cert-C function that calls this function creates valueList; it is destroyed when the extension that owns the valueList is destroyed. ber An input field used to store the value to bedecoded. berLen An input field used to store the length of the values to be decoded. listEntryHandler An input/output field that points to a `LIST_OBJ_ENTRY_HANDLER` structure. The application can use this to insert application-defined extension values into the valueList.

00275 typedef struct EXTENSION_HANDLER {
00276   /* Allocate and add new value to the value list */
00277   int (*AllocAndCopy) (
00278     POINTER *newValue,          /* (out) new copy of value */
00279     POINTER  value);            /* value to be copied */
00280 
00281   /* Delete value allocated by AllocAndCopy by freeing its storage */
00282   VALUE_DESTRUCTOR Destructor;
00283 
00284   /* Get value in encoded format */
00285   int (*GetEncodedValue) (
00286     LIST_OBJ        valueList,  /* values to be encoded */
00287     unsigned char **der,        /* (out) encoded values */
00288     unsigned int   *derLen);    /* (out) length of encoded values */
00289 
00290   /* Decode the encoded value into components and save */
00291   int (*SetEncodedValue) (
00292     LIST_OBJ       valueList,         /* decoded value(s) */
00293     unsigned char *ber,               /* value(s) to be decoded */
00294     unsigned int   berLen,            /* length of value(s) to be decoded */
00295     LIST_OBJ_ENTRY_HANDLER
00296                   *listEntryHandler); /* list entry handler */
00297 } EXTENSION_HANDLER;