RSA Security 5 manual Surrender Function

The Surrender Function

The Surrender Function

During lengthy operations, such as public-key computations and key generation, Crypto-C surrenders control to the application’s surrender function. The surrender function may notify users of the operation being performed, indicate that it is still performing, process operating system tasks, or execute other operations before returning to Crypto-C. The surrender function may also cause Crypto-C to cancel the operation by returning a non-zero value.

Your application specifies its surrender function through an A_SURRENDER_CTX value. A_SURRENDER_CTX is supplied as the surrenderContext argument to Crypto-C functions such as B_EncryptInit. A_SURRENDER_CTX is defined as follows:

typedef struct {
int (*Surrender) ();		/* surrender function callback */
POINTER	handle;	/* application-specific information */
POINTER	reserved;	/* reserved for future use */
} A_SURRENDER_CTX;

An A_SURRENDER_CTX value consists of a pointer to your application-specific callback function (that constitutes Crypto-C’s surrender function) and a pointer to application- specific information. The pointer to application-specific information is supplied directly to your callback and is not otherwise manipulated by Crypto-C. The reserved value should be set to NULL_PTR for future compatibility.

Atypical application initializes the A_SURRENDER_CTX value before calling a Crypto-C procedure. Each A_SURRENDER_CTX value may specify a different surrender function callback and a different handle.

For a sample surrender function, see “A Sample Surrender Function” in the User’s Manual.

1 2 R S A B S A F E C r y p t o - C L i b r a r y R e f e r e n c e M a n u a l