Previous section.

Common Security: CDSA and CSSM, Version 2
Copyright © 1999 The Open Group

CSSM Error Handling

Introduction

This Appendix presents a specification for error handling in CSSM that provides a consistent mechanism across all layers of CSSM for returning errors to the caller.

All CSSM API functions return a value of type CSSM_RETURN. The value CSSM_OK indicates that the function was successful. Any other value is an error value from a service provider or CSSM. There are two types of error values that can be returned from a CSSM API function when the return value is not CSSM_OK:

CSSM reserves a set of pre-defined numeric offset values for its use; these offset values must be used as defined in the CSSM specification. A separate set of predefined offset values is reserved for module developers to indicate custom error values.

The calling application must determine how to handle an error returned by an API. Detailed descriptions of the error values are available in the corresponding Chapters of this specification,

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

Error Values and Error Codes Scheme

Error Value refers to the 32-bit CSSM_RETURN value.

Error Code refers to the code portion of the Error Value.

The code is an offset from the error base for a specific CSSM module type.

This Appendix includes:

Module-specific error value definitions reside in the associated module definition chapter of the specification.

Error Codes and Error Value Enumeration

Configurable CSSM Error Code Constants

These constants define constants that are configurable. 


#define CSSM_BASE_ERROR (0x00000000)
The implementation-defined CSSM error code base value. 


#define CSSM_ERRORCODE_MODULE_EXTENT (0x00000800)
The implementation-defined number of error codes allocated for each module type. This number must be greater than CSSM_ERRORCODE_COMMON_EXTENT, and should allow at least half the space for spec-defined error codes. 


#define CSSM_ERRORCODE_CUSTOM_OFFSET (0x00000400)
The platform-specific offset at which custom error codes are allocated. Must be greater than CSSM_ERRCODE_COMMON_EXTENT and less than CSSM_ERRORCODE_MODULE_EXTENT.

CSSM Error Code Constants 


#define CSSM_ERRORCODE_COMMON_EXTENT (0x80)
The number of error codes allocated to indicate "common" errors. 


#define CSSM_CSSM_BASE_ERROR (CSSM_BASE_ERROR) 


#define CSSM_CSSM_PRIVATE_ERROR (CSSM_BASE_ERROR + CSSM_ERROR_CUSTOM_OFFSET) 


#define CSSM_CSP_BASE_ERROR (CSSM_CSSM_BASE_ERROR+CSSM_ERRORCODE_MODULE_EXTENT) 


#define CSSM_CSP_PRIVATE_ERROR (CSSM_CSP_BASE_ERROR + CSSM_ERROR_CUSTOM_OFFSET) 


#define CSSM_DL_BASE_ERROR (CSSM_CSP_BASE_ERROR + CSSM_ERRORCODE_MODULE_EXTENT) 


#define CSSM_DL_PRIVATE_ERROR (CSSM_DL_BASE_ERROR + CSSM_ERROR_CUSTOM_OFFSET) 


#define CSSM_CL_BASE_ERROR (CSSM_DL_BASE_ERROR + CSSM_ERRORCODE_MODULE_EXTENT) 


#define CSSM_CL_PRIVATE_ERROR (CSSM_CL_BASE_ERROR + CSSM_ERROR_CUSTOM_OFFSET) 


#define CSSM_TP_BASE_ERROR (CSSM_CL_BASE_ERROR + CSSM_ERRORCODE_MODULE_EXTENT) 


#define CSSM_TP_PRIVATE_ERROR (CSSM_TP_BASE_ERROR + CSSM_ERROR_CUSTOM_OFFSET ) 


#define CSSM_KR_BASE_ERROR (CSSM_TP_BASE_ERROR + CSSM_ERRORCODE_MODULE_EXTENT) 


#define CSSM_KR_PRIVATE_ERROR (CSSM_KR_BASE_ERROR + CSSM_ERROR_CUSTOM_OFFSET) 


#define CSSM_AC_BASE_ERROR (CSSM_KR_BASE_ERROR + CSSM_ERRORCODE_MODULE_EXTENT) 


#define CSSM_AC_PRIVATE_ERROR (CSSM_AC_BASE_ERROR + CSSM_ERROR_CUSTOM_OFFSET)

General Error Values

The following error values can be returned from any CSSM API. 


#define CSSMERR_CSSM_INVALID_ADDIN_HANDLE \
    (CSSM_CSSM_BASE_ERROR + CSSM_ERRORCODE_COMMON_EXTENT + 1)
The given service provider handle is not valid 


#define CSSMERR_CSSM_NOT_INITIALIZED \
    (CSSM_CSSM_BASE_ERROR + CSSM_ERRORCODE_COMMON_EXTENT + 2)
A function is called without initializing CSSM 


#define CSSMERR_CSSM_INVALID_HANDLE_USAGE \
    (CSSM_CSSM_BASE_ERROR + CSSM_ERRORCODE_COMMON_EXTENT + 3)
Handle does not match with service type 


#define CSSMERR_CSSM_PVC_REFERENT_NOT_FOUND \
    (CSSM_CSSM_BASE_ERROR + CSSM_ERRORCODE_COMMON_EXTENT + 4)
A reference to the calling module was not found in the list of authorized callers. 


#define CSSMERR_CSSM_FUNCTION_INTEGRITY_FAIL \
    (CSSM_CSSM_BASE_ERROR + CSSM_ERRORCODE_COMMON_EXTENT + 5)
Function address is not within the verified module

Common Error Codes For All Module Types

The following codes can be returned by multiple module types. 


#define CSSM_ERRCODE_INTERNAL_ERROR (0x0001)
General system error; indicates that an operating system or internal state error has occurred and the system may not be in a known state 


#define CSSM_ERRCODE_MEMORY_ERROR ( 0x0002 )
A memory error occurred 


#define CSSM_ERRCODE_MDS_ERROR  ( 0x0003 )
The MDS could not be accessed to complete the operation 


#define CSSM_ERRCODE_INVALID_POINTER (0x0004)
An input/output function parameter or input/output field inside of a data structure is an invalid pointer 


#define CSSM_ERRCODE_INVALID_INPUT_POINTER (0x0005)
An input function parameter or input field in a data structure is an invalid pointer 


#define CSSM_ERRCODE_INVALID_OUTPUT_POINTER (0x0006)
An output function parameter or output field in a data structure is an invalid pointer 


#define CSSM_ERRCODE_FUNCTION_NOT_IMPLEMENTED (0x0007)
The function is not implemented by the service provider 


#define CSSM_ERRCODE_SELF_CHECK_FAILED (0x0008)
The module failed a self-check 


#define CSSM_ERRCODE_OS_ACCESS_DENIED (0x0009)
The operating system denied access to a required resource 


#define CSSM_ERRCODE_FUNCTION_FAILED (0x000A)
The function failed for an unknown reason. 


#define CSSM_ERRCODE_MODULE_MANIFEST_VERIFY_FAILED (0x000B)
Module's manifest verification failed 


#define CSSM_ERRCODE_INVALID_GUID (0x000C)
Invalid GUID

Common Error Codes for ACLs

The following code enumeration values apply to any module that supports ACLs. 


#define CSSM_ERRCODE_OPERATION_AUTH_DENIED (0x0020)
The access credentials were insufficient to permit the requested action to complete 


#define CSSM_ERRCODE_OBJECT_USE_AUTH_DENIED (0x0021)
The access credentials were insufficient to permit the associated object to be used 


#define CSSM_ERRCODE_OBJECT_MANIP_AUTH_DENIED (0x0022)
The access credentials were insufficient to permit manipulation of the object that is the target of an operation (i.e. CSSM_WrapKey(), CSSM_UnwrapKey()). 


#define CSSM_ERRCODE_OBJECT_ACL_NOT_SUPPORTED (0x0023)
An ACL is specified for a new object and the service provider does not support ACLs for objects of that type 


#define CSSM_ERRCODE_OBJECT_ACL_REQUIRED (0x0024)
An ACL is not specified for a new object and the service provider requires an ACLs for objects of that type 


#define CSSM_ERRCODE_INVALID_ACCESS_CREDENTIALS (0x0025)
The access credentials are invalid 


#define CSSM_ERRCODE_INVALID_ACL_BASE_CERTS (0x0026)
The base certificates were corrupt or not recognized as the indicated type 


#define CSSM_ERRCODE_ACL_BASE_CERTS_NOT_SUPPORTED (0x0027)
The type of at least one certificate in the base certificates is not supported 


#define CSSM_ERRCODE_INVALID_SAMPLE_VALUE (0x0028)
The sample value is corrupt or not recognized as the indicated type 


#define CSSM_ERRCODE_SAMPLE_VALUE_NOT_SUPPORTED (0x0029)
The type of at least one sample is not supported 


#define CSSM_ERRCODE_INVALID_ACL_SUBJECT_VALUE (0x002A)
The subject value is corrupt or not recognized as the indicated type 


#define CSSM_ERRCODE_ACL_SUBJECT_TYPE_NOT_SUPPORTED (0x002B)
The type of the subject value is not supported 


#define CSSM_ERRCODE_INVALID_ACL_CHALLENGE_CALLBACK (0x002C)
The challenge or subject callback function pointer is invalid 


#define CSSM_ERRCODE_ACL_CHALLENGE_CALLBACK_FAILED (0x002D)
The challenge or subject callback to the client failed 


#define CSSM_ERRCODE_INVALID_ACL_ENTRY_TAG (0x002E)
The entry tag value is not valid. 


#define CSSM_ERRCODE_ACL_ENTRY_TAG_NOT_FOUND (0x002F)
No ACL entry was found with the specified entry tag 


#define CSSM_ERRCODE_INVALID_ACL_EDIT_MODE (0x0030)
The edit mode specified when changing an ACL entry is not valid 


#define CSSM_ERRCODE_ACL_CHANGE_FAILED (0x0031)
The ACL update operation failed 


#define CSSM_ERRCODE_INVALID_NEW_ACL_ENTRY (0x0032)
The ACL entry specified for an initial or modified value is invalid 


#define CSSM_ERRCODE_INVALID_NEW_ACL_OWNER (0x0033)
The ACL owner specified for a modified value is invalid 


#define CSSM_ERRCODE_ACL_DELETE_FAILED (0x0034)
ACL entry to be deleted was not found 


#define CSSM_ERRCODE_ACL_REPLACE_FAILED (0x0035)
ACL entry to be replaced was not found 


#define CSSM_ERRCODE_ACL_ADD_FAILED (0x0036)
Unable to add new ACL entry

Common Error Codes for Specific Data Types

Error values with the following code enumeration values may be returned from any function that takes as input a Cryptographic Context Handle. 


#define CSSM_ERRCODE_INVALID_CONTEXT_HANDLE (0x0040)
Invalid context handle

Error values with the following code enumeration values may be returned from any function that takes as input a version. 


#define CSSM_ERRCODE_INCOMPATIBLE_VERSION (0x0041)
Version is not compatible with the current version

Error values with the following code enumeration values may be returned from any function that takes as input the associated input pointer types. 


#define CSSM_ERRCODE_INVALID_CERTGROUP_POINTER (0x0042)
Invalid pointer for certificate group 


#define CSSM_ERRCODE_INVALID_CERT_POINTER (0x0043)
Invalid pointer for certificate 


#define CSSM_ERRCODE_INVALID_CRL_POINTER (0x0044)
Invalid pointer for certificate revocation list 


#define CSSM_ERRCODE_INVALID_FIELD_POINTER (0x0045)
Invalid pointer for certificate or CRL fields (OID/value pairs)

Error values with the following code enumeration values may be returned from any function that takes as input a CSSM_DATA. 


#define CSSM_ERRCODE_INVALID_DATA (0x0046)
The data in an input parameter is invalid

Error values with the following code enumeration values may be returned from any function that takes as input an encoded unsigned CRL. 


#define CSSM_ERRCODE_CRL_ALREADY_SIGNED (0x0047)
Attempted to modify a CRL that has already been signed

Error values with the following code enumeration values may be returned from any function that takes as input a number of fields. 


#define CSSM_ERRCODE_INVALID_NUMBER_OF_FIELDS (0x0048)
Invalid argument for number of certificate fields

Error values with the following code enumeration values may be returned from any function whose operation includes verification of a certificate or CRL. 


#define CSSM_ERRCODE_VERIFICATION_FAILURE (0x0049)
Certificate or CRL verification failed

Error values with the following code enumeration values may be returned from any function that takes as input a DB handle. 


#define CSSM_ERRCODE_INVALID_DB_HANDLE (0x004A)
Invalid database handle

Error values with the following code enumeration values may be returned from any function that deals with privilege. 


#define CSSM_ERRCODE_PRIVILEGE_NOT_GRANTED (0x004B)
Requested privilege has not been granted to the module requesting the privilege

Error values with the following code enumeration values may be returned from any function that takes as input a CSSM_DL_DB_LIST. 


#define CSSM_ERRCODE_INVALID_DB_LIST (0x004C)
Invalid CSSM_DL_DB_LIST. 


#define CSSMERR_ERRCODE_INVALID_DB_LIST_POINTER (0x004D)
Invalid database list pointer

Error values with the following code enumeration values may be returned from any function that takes as input a certificate template, certificate or CRL. 


#define CSSM_ERRCODE_UNKNOWN_FORMAT (0x004E)
Unknown format or invalid structure for certificate template, certificate or CRL 


#define CSSM_ERRCODE_UNKNOWN_TAG (0x004F)
Unknown OID specified in certificate template, certificate or CRL field

Error values with the following code enumeration values may be returned from any function that takes as input the associated handle. 


#define CSSM_ERRCODE_INVALID_CSP_HANDLE (0x0050)
Invalid CSP handle 


#define CSSM_ERRCODE_INVALID_DL_HANDLE (0x0051)
Invalid DL handle 


#define CSSM_ERRCODE_INVALID_CL_HANDLE (0x0052)
Invalid CL handle 


#define CSSM_ERRCODE_INVALID_TP_HANDLE (0x0053)
Invalid TP handle 


#define CSSM_ERRCODE_INVALID_KR_HANDLE (0x0054)
Invalid KR handle 


#define CSSM_ERRCODE_INVALID_AC_HANDLE (0x0055)
Invalid AC handle

Error values with the following code enumeration values may be returned from any function that takes as input a passthrough ID. 


#define CSSM_ERRCODE_INVALID_PASSTHROUGH_ID (0x0056)
Invalid passthrough ID
Click here to return to the publication details.

Contents Next section Index