CSSM Error Handling

Introduction

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:

• Error values which CSSM has defined specifically (e.g. CSSMERR_CSSM_INTERNAL_ERROR)

• Error values which are particular to a module - a custom error value.

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 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:

• A listing of Configurable CSSM Error Code Constants

• A listing of CSSM Error Code Constants

• A listing of General Error Values that may be returned by the CSSM core module from any CSSM API

• Listings of common error codes. Common error codes are codes that can be associated with multiple module types.

• A listing of Configurable CSSM Error Code Constants for specific module types

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

• #define CSSM_BASE_ERROR CSSM_ERRORCODE_MODULE_EXTENT

  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. The minimum value for this constant is 0x00000800.

• #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.
  

  The minimum value for this constant is 0x00000400.

• #define CSSM_ERRORCODE_COMMON_EXTENT (0x100)

  The number of error codes allocated to indicate "common" errors.

CSSM Error Code Constants

#define CSSM_CSSM_BASE_ERROR (CSSM_BASE_ERROR) 

#define CSSM_CSSM_PRIVATE_ERROR (CSSM_BASE_ERROR + CSSM_ERRCODE_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_ERRCODE_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_ERRCODE_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_ERRCODE_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_ERRCODE_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_ERRCODE_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_ERRCODE_CUSTOM_OFFSET) 

General Error Values

#define CSSMERR_CSSM_INVALID_ADDIN_HANDLE \
    (CSSM_CSSM_BASE_ERROR + CSSM_ERRORCODE_COMMON_EXTENT + 1) 

#define CSSMERR_CSSM_NOT_INITIALIZED \
    (CSSM_CSSM_BASE_ERROR + CSSM_ERRORCODE_COMMON_EXTENT + 2) 

#define CSSMERR_CSSM_INVALID_HANDLE_USAGE \
    (CSSM_CSSM_BASE_ERROR + CSSM_ERRORCODE_COMMON_EXTENT + 3) 

#define CSSMERR_CSSM_PVC_REFERENT_NOT_FOUND \
    (CSSM_CSSM_BASE_ERROR + CSSM_ERRORCODE_COMMON_EXTENT + 4) 

#define CSSMERR_CSSM_FUNCTION_INTEGRITY_FAIL \
    (CSSM_CSSM_BASE_ERROR + CSSM_ERRORCODE_COMMON_EXTENT + 5) 

Common Error Codes For All Module Types

#define CSSM_ERRCODE_INTERNAL_ERROR (0x0001) 

#define CSSM_ERRCODE_MEMORY_ERROR ( 0x0002 ) 

#define CSSM_ERRCODE_MDS_ERROR  ( 0x0003 ) 

#define CSSM_ERRCODE_INVALID_POINTER (0x0004) 

#define CSSM_ERRCODE_INVALID_INPUT_POINTER (0x0005) 

#define CSSM_ERRCODE_INVALID_OUTPUT_POINTER (0x0006) 

#define CSSM_ERRCODE_FUNCTION_NOT_IMPLEMENTED (0x0007) 

#define CSSM_ERRCODE_SELF_CHECK_FAILED (0x0008) 

#define CSSM_ERRCODE_OS_ACCESS_DENIED (0x0009) 

#define CSSM_ERRCODE_FUNCTION_FAILED (0x000A) 

#define CSSM_ERRCODE_MODULE_MANIFEST_VERIFY_FAILED (0x000B) 

#define CSSM_ERRCODE_INVALID_GUID (0x000C) 

Common Error Codes for ACLs

#define CSSM_ERRCODE_OPERATION_AUTH_DENIED (0x0020) 

#define CSSM_ERRCODE_OBJECT_USE_AUTH_DENIED (0x0021) 

#define CSSM_ERRCODE_OBJECT_MANIP_AUTH_DENIED (0x0022) 

#define CSSM_ERRCODE_OBJECT_ACL_NOT_SUPPORTED (0x0023) 

#define CSSM_ERRCODE_OBJECT_ACL_REQUIRED (0x0024) 

#define CSSM_ERRCODE_INVALID_ACCESS_CREDENTIALS (0x0025) 

#define CSSM_ERRCODE_INVALID_ACL_BASE_CERTS (0x0026) 

#define CSSM_ERRCODE_ACL_BASE_CERTS_NOT_SUPPORTED (0x0027) 

#define CSSM_ERRCODE_INVALID_SAMPLE_VALUE (0x0028) 

#define CSSM_ERRCODE_SAMPLE_VALUE_NOT_SUPPORTED (0x0029) 

#define CSSM_ERRCODE_INVALID_ACL_SUBJECT_VALUE (0x002A) 

#define CSSM_ERRCODE_ACL_SUBJECT_TYPE_NOT_SUPPORTED (0x002B) 

#define CSSM_ERRCODE_INVALID_ACL_CHALLENGE_CALLBACK (0x002C) 

#define CSSM_ERRCODE_ACL_CHALLENGE_CALLBACK_FAILED (0x002D) 

#define CSSM_ERRCODE_INVALID_ACL_ENTRY_TAG (0x002E) 

#define CSSM_ERRCODE_ACL_ENTRY_TAG_NOT_FOUND (0x002F) 

#define CSSM_ERRCODE_INVALID_ACL_EDIT_MODE (0x0030) 

#define CSSM_ERRCODE_ACL_CHANGE_FAILED (0x0031) 

#define CSSM_ERRCODE_INVALID_NEW_ACL_ENTRY (0x0032) 

#define CSSM_ERRCODE_INVALID_NEW_ACL_OWNER (0x0033) 

#define CSSM_ERRCODE_ACL_DELETE_FAILED (0x0034) 

#define CSSM_ERRCODE_ACL_REPLACE_FAILED (0x0035) 

#define CSSM_ERRCODE_ACL_ADD_FAILED (0x0036) 

Common Error Codes for Specific Data Types

#define CSSM_ERRCODE_INVALID_CONTEXT_HANDLE (0x0040) 

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) 

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)

#define CSSM_ERRCODE_INVALID_CERT_POINTER (0x0043)

#define CSSM_ERRCODE_INVALID_CRL_POINTER (0x0044)

#define CSSM_ERRCODE_INVALID_FIELD_POINTER (0x0045)

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)

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)

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)

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)

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)

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) 

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)

#define CSSM_ERRCODE_INVALID_DB_LIST_POINTER (0x004D)

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)

#define CSSM_ERRCODE_UNKNOWN_TAG (0x004F)

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) 

#define CSSM_ERRCODE_INVALID_DL_HANDLE (0x0051) 

#define CSSM_ERRCODE_INVALID_CL_HANDLE (0x0052) 

#define CSSM_ERRCODE_INVALID_TP_HANDLE (0x0053) 

#define CSSM_ERRCODE_INVALID_KR_HANDLE (0x0054) 

#define CSSM_ERRCODE_INVALID_AC_HANDLE (0x0055) 

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)

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

#define CSSM_ERRCODE_INVALID_NETWORK_ADDR (0x0057) 

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

#define CSSM_ERRCODE_INVALID_CRYPTO_DATA (0x0058)