CSSM Error-Handling

Introduction

All CSSM API functions will return one of the following:

1. CSSM_RETURN-an enumerated type consisting of CSSM_OK and CSSM_FAIL. If it is CSSM_FAIL, an error code indicating the reason for failure can be obtained by calling CSSM_GetError().

2. CSSM_BOOL-an enumerated type consisting of CSSM_TRUE and CSSM_FALSE. If it is CSSM_FALSE, an error code may be available (but not always) by calling CSSM_GetError.

3. A pointer to a data structure, a handle, a file size or whatever is logical for the function to return. An error code may be available (but not always) by calling CSSM_GetError.

Check documentation for individual functions to determine if error information will be available and what error values the function uses. Note that there will be additional error values defined by add-in modules. The information available from CSSM_GetError will include both the error number and a GUID (global unique ID) that will associate the error with the add-in module that set it. The GUID of each add-in module can be obtained by calling CSSM_XX_ListModules (where XX = CSP, CL, DL, or TP). CSSM_CompareGuids can then be called to determine from which module an error came.

Each add-in module must have a mechanism for reporting their errors to the calling application. In general, there are two types of errors an add-in module can return:

• Errors CSSM has defined for it to use (CSSM_CSP_INVALID_SECURITY_LIST)

• Errors particular to an add-in module (XXX_CSP_BAD_HW_TOKEN_SERIAL_NUMBER)

Since some errors are predefined by CSSM, those errors have a set of pre-defined numeric values which are reserved by CSSM, and cannot be used arbitrarily by add-in modules. For errors that are particular to an add-in module, a different set of predefined values has been reserved for their use.

It will be up to the calling application to determine how to handle the error returned by CSSM_GetError(). Detailed descriptions of the error values will be available in the corresponding specification, the <cssmerr.h> header file, and the documentation for specific add-in modules. If a routine does not know how to handle the error, it may choose to pass the error on up the chain to its caller.

Error values should not be overwritten, if at all possible. Overwriting the return destroys valuable error handling and debugging information. This means an add-in module ot type A can return an error code defined by an add-in module of type B.

Data Structures

typedef enum cssm_bool {
    CSSM_FALSE = 0,
    CSSM_TRUE = 1,
} CSSM_BOOL

typedef enum cssm_return {
    CSSM_OK = 0,
    CSSM_FAIL = -1
} CSSM_RETURN

typedef struct cssm_error {
    uint32 error;
    CSSM_GUID guid;
} CSSM_ERROR, *CSSM_ERROR_PTR

Error Handling Functions