RSA Security 5.2.2 manual Sample Surrender Function, Reserved for future use

System Considerations In Crypto-C

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

} A_SURRENDER_CTX;

Chapter 1 also gives the form that a surrender function must have:

int (*Surrender) (
POINTER handle	/* application-specific information */
);

If you define a surrender function within the surrender context, Crypto-C functions will call it at regular intervals during execution. Depending on the application, the surrender function can perform one of a number of operations.

For example, a surrender function can:

•Notify the user of the current status of execution, either once at the beginning or once every second, for instance.

•Allow the user to cancel the operation.

•Suspend the Crypto-C function to allow other operations to execute.

Even when you do not need a surrender function to manage lengthy function calls, you can create one to perform other tasks. For example, you could use a surrender function to allow other applications to cut into a Crypto-C routine, no matter how quickly the routine executes. A surrender context is a potent debugging tool as well.

A Sample Surrender Function

As an example, we will construct a surrender function that announces the start of a Crypto-C function, and prints out a dot on the screen every second.

#include <time.h>

int GeneralSurrenderFunction (handle) POINTER handle;

{

static time_t currentTime; time_t getTime;

C h a p t e r 4 U s i n g C r y p t o - C 1 1 9