RSA BSAFE Cert-C

Certificate Components for C

Crypto-C 6.2.1 Developer's Guide
Search

certext.h File Reference

This file contains the Cert-C certificate extension API and data types.

#include "basetype.h"
#include "certlist.h"
#include "certattr.h"
#include "certname.h"

Go to the source code of this file.

Data Structures

 AIA_DESCRIPTION
 Represents the Authority Information Access (AIA) extension for X.509 v3 certificates, and specifies how to obtain CA information about the issuer of the certificate. More...

 ALTERNATE_NAME
 Holds a variety of name forms. More...

 AUTHORITY_KEY_ID
 Represents the Authority Key Identifier extension for X.509 v3 certificates and CRLs. More...

 BASIC_CONSTRAINTS
 Represents the Basic Constraints extension for X.509 certificates. More...

 DIST_POINT_NAME
 Represents the ASN.1 DistributionPointName structure in RFC 2459. More...

 DISTRIBUTION_POINT
 Represents a CRL Distribution Point (DP) extension for X.509 v3 CRLs. More...

 EXTENDED_KEY_USAGE
 Represents the Extended Key Usage extension for X.509 v3 certificates. More...

 DEFINED_ATTRIBUTE
 Stores a domain-defined attribute of the O/R address. More...

 DEFINED_ATTRIBUTES
 Stores the domain-defined attributes of the O/R address. More...

 E163_4_ADDR
 A type of extended network address in the EXTENSION_ATTRIBUTE structure. More...

 EDI_PARTY_NAME
 Contains an alternate name in a format agreed upon between communicating EDI partners. More...

 EXTENDED_NETWORK_ADDR
 Contains an extended network address. More...

 EXTENSION_ATTRIBUTE
 Stores an extension attribute of the O/R address. More...

 EXTENSION_ATTRIBUTES
 When specifying an OR_ADDRESS structure (as a member of an ALTERNATE_NAME structure), use this structure to store the extension attributes of the O/R address. More...

 EXTENSION_INFO
 Retrieves extension entry information from an opaque EXTENSIONS_OBJ by calling C_GetExtensionInfo(). More...

 EXTENSION_TYPE_INFO
 Displays or changes the default setting of a supported standard extension. More...

 GENERAL_NAMES
 Represents the ASN.1 GeneralNames structure as described in RFC 2459. More...

 GENERAL_SUBTREE
 Specifies one or more naming subtrees, each defined by the name of the root of the subtree. More...

 ISSUING_DISTRIBUTION_POINT
 Represents an Issuing Distribution Point (DP) extension for X.509 v3 CRLs. More...

 NAME_CONSTRAINTS
 Contains a Name Constraints extension for X.509 v3 certificates. More...

 OCSP_ACCEPTABLE_RESPONSES
 Defines the acceptable OCSP response types. More...

struct  OCSP_CRL_REFERENCE
 Represents the CRL References extension for an OCSP response. More...

 OR_ADDRESS
 Contains an O/R address that is defined in the X.411 standard. More...

 ORG_UNIT_NAMES
 Contains an organizational unit name. More...

 OTHER_NAME
 Contains an application-defined alternate name. More...

 PDS_PARAMETER
 Contains a physical delivery system value. More...

 PERSONAL_NAME
 Contains a personal name. More...

 POLICY_CONSTRAINTS_36
 Represents the Policy Constraints extension for X.509 v3 certificates. More...

 POLICY_INFO
 Represents the Certificate Policies extension for X.509 v3 certificates. More...

 POLICY_MAPPING
 Represents a Policy Mappings extension for an X.509 v3 certificate. More...

 PRESENTATION_ADDR
 A type of extended network address in the EXTENSION_ATTRIBUTE structure. More...

 PRIVATE_KEY_USAGE_PERIOD
 Represents the Private Key Usage Period extension for X.509 v3 certificates. More...

 QualifierInfo
 Stores a policy qualifier. More...

 STANDARD_ATTRIBUTES
 Stores the standard attributes of the O/R address when specifying an OR_ADDRESS structure (as a member of an ALTERNATE_NAME structure). More...

 TYPED_STRING
 Holds a typed string. More...

 UNFORMATTED_POSTAL_ADDR
 Contains a non-formatted postal address. More...


Defines

#define TELETEX_PERSONAL_NAME
 Contains a personal name. More...

#define TELETEX_DOMAIN_DEFINED_ATTRS
 Contains an array of domain-defined attributes. More...


Typedefs

typedef struct TYPED_STRING
 Holds a typed string. More...

typedef struct EXTENSION_TYPE_INFO
 Displays or changes the default setting of a supported standard extension. More...

typedef struct EXTENSION_INFO
 Retrieves extension entry information from an opaque EXTENSIONS_OBJ by calling C_GetExtensionInfo().

typedef UINT4 KEY_USAGE
 Represents the Key Usage extension for X.509 v3 certificates. More...

typedef ITEM SUBJECT_KEY_ID
 Represents a Subject Key Identifier extension for an X.509 v3 certificate. More...

typedef ATTRIBUTES_OBJ SUBJECT_DIR_ATTRIB
 Represents a Subject Directory Attributes extension for an X.509 v3 certificate. More...

typedef struct OTHER_NAME
 Contains an application-defined alternate name. More...

typedef struct EDI_PARTY_NAME
 Contains an alternate name in a format agreed upon between communicating EDI partners. More...

typedef struct PERSONAL_NAME
 Contains a personal name. More...

typedef struct ORG_UNIT_NAMES
 Contains an organizational unit name. More...

typedef struct STANDARD_ATTRIBUTES
 Stores the standard attributes of the O/R address when specifying an OR_ADDRESS structure (as a member of an ALTERNATE_NAME structure).

typedef struct DEFINED_ATTRIBUTE
 Stores a domain-defined attribute of the O/R address. More...

typedef struct DEFINED_ATTRIBUTES
 Stores the domain-defined attributes of the O/R address. More...

typedef struct PDS_PARAMETER
 Contains a physical delivery system value. More...

typedef struct UNFORMATTED_POSTAL_ADDR
 Contains a non-formatted postal address. More...

typedef struct E163_4_ADDR
 A type of extended network address in the EXTENSION_ATTRIBUTE structure. More...

typedef struct PRESENTATION_ADDR
 A type of extended network address in the EXTENSION_ATTRIBUTE structure. More...

typedef struct EXTENDED_NETWORK_ADDR
 Contains an extended network address. More...

typedef struct EXTENSION_ATTRIBUTE
 Stores an extension attribute of the O/R address. More...

typedef struct EXTENSION_ATTRIBUTES
 When specifying an OR_ADDRESS structure (as a member of an ALTERNATE_NAME structure), use this structure to store the extension attributes of the O/R address.

typedef struct OR_ADDRESS
 Contains an O/R address that is defined in the X.411 standard. More...

typedef struct ALTERNATE_NAME
 Holds a variety of name forms. More...

typedef ALTERNATE_NAME GENERAL_NAME
 An application-defined ALTERNATE_NAME that can be converted to and from an ASN.1 data type, using ASN.1 encoding rules. More...

typedef ALTERNATE_NAME ISSUER_ALTNAME
 Represents an Issuer Alternate Name extension for an X.509 v3 certificate or CRL. More...

typedef ALTERNATE_NAME SUBJECT_ALTNAME
 Represents a Subject Alternate Name extension for an X.509 v3 certificate. More...

typedef struct AUTHORITY_KEY_ID
 Represents the Authority Key Identifier extension for X.509 v3 certificates and CRLs. More...

typedef struct BASIC_CONSTRAINTS
 Represents the Basic Constraints extension for X.509 certificates. More...

typedef struct PRIVATE_KEY_USAGE_PERIOD
 Represents the Private Key Usage Period extension for X.509 v3 certificates. More...

typedef struct QualifierInfo
 Stores a policy qualifier. More...

typedef struct POLICY_INFO
 Represents the Certificate Policies extension for X.509 v3 certificates. More...

typedef struct POLICY_CONSTRAINTS_36
 Represents the Policy Constraints extension for X.509 v3 certificates. More...

typedef struct EXTENDED_KEY_USAGE
 Represents the Extended Key Usage extension for X.509 v3 certificates. More...

typedef struct GENERAL_SUBTREE
 Specifies one or more naming subtrees, each defined by the name of the root of the subtree.

typedef struct NAME_CONSTRAINTS
 Contains a Name Constraints extension for X.509 v3 certificates. More...

typedef struct POLICY_MAPPING
 Represents a Policy Mappings extension for an X.509 v3 certificate. More...

typedef struct GENERAL_NAMES
 Represents the ASN.1 GeneralNames structure as described in RFC 2459. More...

typedef struct DIST_POINT_NAME
 Represents the ASN.1 DistributionPointName structure in RFC 2459. More...

typedef struct DISTRIBUTION_POINT
 Represents a CRL Distribution Point (DP) extension for X.509 v3 CRLs. More...

typedef struct ISSUING_DISTRIBUTION_POINT
 Represents an Issuing Distribution Point (DP) extension for X.509 v3 CRLs. More...

typedef GENERAL_NAME CERT_ISSUER
 Represents a Certificate Issuer extension for X.509 v3 CRL entries. More...

typedef struct AIA_DESCRIPTION
 Represents the Authority Information Access (AIA) extension for X.509 v3 certificates, and specifies how to obtain CA information about the issuer of the certificate. More...

typedef unsigned int REASON_CODE
 Represents a Reason Code extension for X.509 v3 CRL entries. More...

typedef struct OCSP_ACCEPTABLE_RESPONSES
 Defines the acceptable OCSP response types. More...

typedef GENERALIZED_TIME ARCHIVE_CUTOFF
 Represents the Archive Cutoff extension for an OCSP response. More...

typedef ITEM INSTRUCTION_CODE
 Represents a Hold Instruction Code extension for X.509 v3 CRL entries. More...

typedef GENERALIZED_TIME INVALID_DATE
 Represents an Invalidity Date extension for X.509 v3 CRL entries. More...


Enumerations

enum  OCSP_CRLREF_TYPE { OCSP_CRLREF_TYPE_UNSPECIFIED, OCSP_CRLREF_TYPE_URL, OCSP_CRLREF_TYPE_NUMBER, OCSP_CRLREF_TYPE_TIME }
 The OCSP_CRLREF_TYPE enumeration indicates the type of information contained in the OCSP_CRL_REFERENCE structure that is currently being used. More...


Functions

int C_GetExtensionTypeInfo (CERTC_CTX ctx, unsigned char *type, unsigned int typeLen, EXTENSION_TYPE_INFO *info)
 Searches for the extension type in applContext. More...

int C_RegisterExtensionType (CERTC_CTX ctx, EXTENSION_TYPE_INFO *info)
 Registers an application-defined extension type, or overrides the default setting of a supported standard extension type, with the value given in extenTypeInfo. More...

int C_UnregisterExtensionType (CERTC_CTX ctx, unsigned char *type, unsigned int typeLen)
 Resets or removes a registered extension handler and extension type from applContext. More...

int C_CreateExtensionsObject (EXTENSIONS_OBJ *extensionsObject, unsigned int extensionsObjectType, CERTC_CTX ctx)
 Creates an extensionsObject of type extensionsObjectType. More...

void C_DestroyExtensionsObject (EXTENSIONS_OBJ *extensionsObject)
 Destroys all extensions in extensionsObject and deletes all associated value lists. More...

int C_FindExtensionByType (EXTENSIONS_OBJ extensionsObject, unsigned char *type, unsigned int typeLen, unsigned int *index)
 Finds the extension of the type given in type. More...

int C_GetExtensionTypeByIndex (EXTENSIONS_OBJ extensionsObject, unsigned char **type, unsigned int *typeLen, unsigned int index)
 Retrieves the extension type from extensionsObject at the index given in index. More...

int C_GetExtensionCount (EXTENSIONS_OBJ extensionsObject, unsigned int *count)
 Retrieves the total number of extension entries in extensionsObject and returns it in count. More...

void C_ResetExtensionsObject (EXTENSIONS_OBJ extensionsObject)
 Returns extensionsObject to the state it was in after it was created. More...

int C_GetExtensionsObjectDER (EXTENSIONS_OBJ extensionsObject, unsigned char **der, unsigned int *derLen)
 Retrieves the DER-encoded value of all the extensions in extensionsObject. More...

int C_SetExtensionsObjectBER (EXTENSIONS_OBJ extensionsObject, unsigned char *ber, unsigned int berLen)
 Sets extensionsObject with the new extension entries given in ber. More...

int C_GetExtensionsInAttributesObj (EXTENSIONS_OBJ extensionsObject, ATTRIBUTES_OBJ attributesObject)
 Transfers the value of attributesObject into extensionsObject. More...

int C_GetAttributeInExtensionsObj (EXTENSIONS_OBJ extensionsObject, ATTRIBUTES_OBJ attributesObject)
 Transfers data from extensionsObject to attributesObject. More...

int C_CreateExtension (EXTENSIONS_OBJ extensionsObject, unsigned char *type, unsigned int typeLen, unsigned int *index, int criticality, EXTENSION_HANDLER *newHandler)
 Creates a new extension entry in extensionsObject. More...

int C_SetExtensionBER (EXTENSIONS_OBJ extensionsObject, unsigned int *index, unsigned char *ber, unsigned int berLen)
 Instantiates an extension with the information in ber and berLen. More...

int C_GetExtensionValue (EXTENSIONS_OBJ extensionsObject, unsigned int extenIndex, unsigned int valueIndex, POINTER *value)
 Retrieves the value referenced by valueIndex in the extension's value list. More...

int C_DestroyExtension (EXTENSIONS_OBJ extensionsObject, unsigned int index)
 Destroys one extension as referenced by index. More...

int C_GetExtensionInfo (EXTENSIONS_OBJ extensionsObject, unsigned int index, EXTENSION_INFO *extensionInfo)
 Retrieves information about the extension referenced by index, and places it in extensionInfo. More...

int C_AddExtensionValue (EXTENSIONS_OBJ extensionsObject, unsigned int index, POINTER value, unsigned int *valueIndex)
 Adds an extension value to an existing extension entry in extensionsObject, which must be referenced by index. More...

int C_DeleteExtensionValue (EXTENSIONS_OBJ extensionsObject, unsigned int index, unsigned int valueIndex)
 Deletes the extension value referenced by valueIndex in the extension entry referenced by index. More...

int C_GetExtensionDER (EXTENSIONS_OBJ extensionsObject, unsigned int index, unsigned char **valueDER, unsigned int *valueDERLen)
 Retrieves the DER encoding of the extension entry referenced by index. More...

int C_GetEncodedExtensionValue (EXTENSIONS_OBJ extensionsObject, unsigned int index, unsigned char **encodedValue, unsigned int *encodedValueLen)
 Retrieves the encoded form of the value(s) of the extension referenced by index. More...

int C_SetEncodedExtensionValue (EXTENSIONS_OBJ extensionsObject, unsigned int index, unsigned char *encodedValue, unsigned int encodedValueLen)
 Sets the extension referenced by index with the value given in encodedValue and encodedValueLen. More...

int C_CompareExtension (EXTENSIONS_OBJ extensionsObject1, unsigned int extensionIndex1, EXTENSIONS_OBJ extensionsObject2, unsigned int extensionIndex2)
 Compares two extensions. More...

int C_CompareExtensions (EXTENSIONS_OBJ extensionsObject1, EXTENSIONS_OBJ extensionsObject2)
 Compares two extensions objects (each representing a set of extensions). More...

Define Documentation

#define TELETEX_DOMAIN_DEFINED_ATTRS
 

Contains an array of domain-defined attributes. It can be used as an extension attribute in an OR_ADDRESS structure. (The OR_ADDRESS can be used as the alternate name in an ALTERNATE_NAME structure.) In the extension attribute structure, EXTENSION_ATTRIBUTE, if EA_TELETEX_DOMAIN_DEFINED_ATTRS is set as the extension attribute type, complete a TELETEX_DOMAIN_DEFINED_ATTRS structure to specify the extension attribute value. For a detailed description of the defined attribute structures, see DEFINED_ATTRIBUTES and DEFINED_ATTRIBUTE.

#define TELETEX_PERSONAL_NAME
 

Contains a personal name. It can be used as an extension attribute in an OR_ADDRESS structure. (The OR_ADDRESS can be used as the alternate name in an ALTERNATE_NAME structure.) In the extension attribute structure, EXTENSION_ATTRIBUTE, if EA_TELETEX_PERSONAL_NAME is set as the extension attribute type, complete a TELETEX_PERSONAL_NAME structure to specify the extension attribute value. For a detailed description of the personal name structure, see PERSONAL_NAME.

Typedef Documentation

typedef struct AIA_DESCRIPTION AIA_DESCRIPTION
 

Represents the Authority Information Access (AIA) extension for X.509 v3 certificates, and specifies how to obtain CA information about the issuer of the certificate. This information can include CA validation services and CA policy information, but it does not include CRLs.

The location of CRLs is specified by the CRL Distribution Points extension. (See DISTRIBUTION_POINT.)

This extension has a NON_CRITICAL default criticality. A certificate can have multiple AIA extensions simultaneously. Use this structure with C_AddExtensionValue() and C_GetExtensionValue().

typedef struct ALTERNATE_NAME ALTERNATE_NAME
 

Holds a variety of name forms. It is a component of several X.509 v3 certificate extensions:


It is also a component of the following CRL extensions: It is also a component of CERT_ISSUER and is used in PKI_POP_GEN_SIGNATURE_INFO.

typedef GENERALIZED_TIME ARCHIVE_CUTOFF
 

Represents the Archive Cutoff extension for an OCSP response. It indicates the OCSP responder has chosen to retain revocation information beyond the certificate's expiration date. The archive cutoff date is obtained by subtracting this retention period from the producedAt time in the OCSP response of the associated OCSP_EVIDENCE. The default criticality for this extension is NON_CRITICAL. An OCSP response can contain only one ARCHIVE_CUTOFF extension for each certificate for which status is being requested. This extension can be present only in an EXTENSIONS_OBJ of type OCSP_SINGLE_EXTENSIONS_OBJ. Use the ARCHIVE_CUTOFF structure with the C_AddExtensionValue() and C_GetExtensionValue() functions.

typedef struct AUTHORITY_KEY_ID AUTHORITY_KEY_ID
 

Represents the Authority Key Identifier extension for X.509 v3 certificates and CRLs. Identifies the public key that corresponds to the private key used to sign the certificate or CRL. The identification is based on the issuer's key identifier or on the issuer's name and serial number.

The certificate's or CRL's Authority Key Identifier extension can be used with the issuer's Subject Key Identifier extension to facilitate chain building. See SUBJECT_KEY_ID. The default criticality for this extension is NON_CRITICAL. A certificate or CRL can have only one Authority Key Identifier extension at a time.

Use this structure with C_AddExtensionValue() and C_GetExtensionValue().

typedef struct BASIC_CONSTRAINTS BASIC_CONSTRAINTS
 

Represents the Basic Constraints extension for X.509 certificates. It indicates whether or not the subject of the certificate can act as a CA, and specifies the constraints on that authority. The default criticality for this extension is CRITICAL. A certificate can have only one Basic Constraints extension at a time. Use the BASIC_CONSTRAINTS structure with C_AddExtensionValue() and C_GetExtensionValue().

typedef GENERAL_NAME CERT_ISSUER
 

Represents a Certificate Issuer extension for X.509 v3 CRL entries. This extension identifies the certificate issuer associated with an entry in an indirect CRL. An indirect CRL contains revocation notifications from CAs other than the CA that issued the CRL. The indirect CRL identifies only the issuer of the CRL, not the issuer of the certificates in the CRL. Therefore, the CA that issued the certificates in the CRL must be identified by a Certificate Issuer extension in each CRL entry. If a CRL's Issuing Distribution Point extension has the IDP_INDIRECT_CRL_ENABLED indicator set, it is an indirect CRL. The default criticality for this extension is CRITICAL. A CRL entry can have multiple Certificate Issuer extensions at the same time.

Use the CERT_ISSUER structure with the C_AddExtensionValue() and C_GetExtensionValue() functions.

typedef struct DEFINED_ATTRIBUTE DEFINED_ATTRIBUTE
 

Stores a domain-defined attribute of the O/R address. Use this structure to fill the array of attributes in one of the following:

typedef struct DEFINED_ATTRIBUTES DEFINED_ATTRIBUTES
 

Stores the domain-defined attributes of the O/R address. When specifying an OR_ADDRESS structure (as a member of an ALTERNATE_NAME structure), use the DEFINED_ATTRIBUTES structure to store the domain-defined attributes of the O/R address. This structure is also defined as TELETEX_DOMAIN_DEFINED_ATTRS. The teletex defined-attributes structure is used as an extension attribute in the OR_ADDRESS structure.

typedef struct DIST_POINT_NAME DIST_POINT_NAME
 

Represents the ASN.1 DistributionPointName structure in RFC 2459. It contains the DNs of a CRL distribution point and is used in two structures:

If DISTRIBUTION_POINT contains a distPointName value of type URI, then distPointName's value must point to the current CRL for the associated reasons. The reasons value is issued by the associated cRLIssuer. If the DISTRIBUTION_POINT omits reasons, the CRL must include revocations for all reasons. If the DISTRIBUTION_POINT omits cRLIssuer, the CRL must be issued by the CA that issued the certificate.

typedef struct DISTRIBUTION_POINT DISTRIBUTION_POINT
 

Represents a CRL Distribution Point (DP) extension for X.509 v3 CRLs. It identifies how the CRL DP is obtained. While both distPointName and cRLIssuers are optional fields, at least one of these fields must contain a value as RFC 2459 states that reasons cannot be the only field in the encoding. The default criticality for this extension is NON_CRITICAL. A CRL can have multiple CRL DP extensions at any time. Use this structure with C_AddExtensionValue() and C_GetExtensionValue().

typedef struct E163_4_ADDR E163_4_ADDR
 

A type of extended network address in the EXTENSION_ATTRIBUTE structure. Use this structure only if you are providing an OR_ADDRESS structure as the alternate name in an ALTERNATE_NAME structure, and you are completing an extended network address for the EXTENSION_ATTRIBUTE. This structure designates the E163-4 address number as the type of extended network address.

typedef struct EDI_PARTY_NAME EDI_PARTY_NAME
 

Contains an alternate name in a format agreed upon between communicating EDI partners. It represents an ediPartyName in ALTERNATE_NAME. If you set CN_EDI_PARTY_NAME as the altNametype, you must complete an EDI_PARTY_NAME to specify the altName.

typedef struct EXTENDED_KEY_USAGE EXTENDED_KEY_USAGE
 

Represents the Extended Key Usage extension for X.509 v3 certificates. This value indicates one or more purposes for which the public key in a certificate can be used. It can be used for these extended purposes in addition to, or in place of, the basic purposes indicated in the KEY_USAGE extension. Extended key purposes can be defined by any organization with a need to do so. The default criticality for this extension is NON_CRITICAL. A certificate can have multiple Extended Key Usage extensions at the same time. Use the this structure with C_AddExtensionValue() and C_GetExtensionValue().

typedef struct EXTENDED_NETWORK_ADDR EXTENDED_NETWORK_ADDR
 

Contains an extended network address. It can be used as an extension attribute in an OR_ADDRESS structure. (The OR_ADDRESS can be used as the alternate name in an ALTERNATE_NAME structure.)

To set the EXTENSION_ATTRIBUTE to contain EXTENDED_NETWORK_ADDR:

  1. Set the type in EXTENSION_ATTRIBUTE to EA_EXTENDED_NETWORK_ADDR.
  2. Set the value in EXTENSION_ATTRIBUTE to point to this structure.

typedef struct EXTENSION_ATTRIBUTE EXTENSION_ATTRIBUTE
 

Stores an extension attribute of the O/R address. Use this structure to fill the array of attributes in an EXTENSION_ATTRIBUTES structure.

typedef struct EXTENSION_TYPE_INFO EXTENSION_TYPE_INFO
 

Displays or changes the default setting of a supported standard extension. It also registers an application-defined extension type in the Cert-C context. This structure is used with C_GetExtensionTypeInfo() and C_RegisterExtensionType().

typedef ALTERNATE_NAME GENERAL_NAME
 

An application-defined ALTERNATE_NAME that can be converted to and from an ASN.1 data type, using ASN.1 encoding rules.

typedef struct GENERAL_NAMES GENERAL_NAMES
 

Represents the ASN.1 GeneralNames structure as described in RFC 2459. It contains a sequence of GENERAL_NAMEs. This structure is used in the DISTRIBUTION_POINT and DIST_POINT_NAME structures.

typedef ITEM INSTRUCTION_CODE
 

Represents a Hold Instruction Code extension for X.509 v3 CRL entries. This extension contains instructions about the action to be taken if a CRL entry indicates a certificate is on hold. It is an ITEM structure whose data member points to an instruction OID. This instruction code can indicate that, if a certificate is on hold, an application should reject the certificate, a user should call the certificate issuer, or some other such action should be taken. (If a CRL entry's Reason Code extension has the CR_CERTIFICATE_HOLD flag set, the certificate is on hold.) The default criticality for this extension is NON_CRITICAL. A CRL entry can have only one Hold Instruction Code extension at a time.

Use the INSTRUCTION_CODE structure with the C_AddExtensionValue() and C_GetExtensionValue() functions.

typedef GENERALIZED_TIME INVALID_DATE
 

Represents an Invalidity Date extension for X.509 v3 CRL entries. It indicates the time at which the private key in the certificate was compromised or the time at which the certificate was determined to be invalid.

The invalidity time can be earlier than the revocation time, which is the time at which the CA processed the revocation and updated the CRL. The default criticality for this extension is NON_CRITICAL. A CRL entry can have only one Invalidity Date extension at a time. Use the INVALID_DATE structure with the C_AddExtensionValue() and C_GetExtensionValue() functions.

typedef ALTERNATE_NAME ISSUER_ALTNAME
 

Represents an Issuer Alternate Name extension for an X.509 v3 certificate or CRL. It allows the issuer's alternative names to be bound to the certificate or CRL, in addition to the issuer's DN. The default criticality for this extension is NON_CRITICAL. However, if the certificate's issuer-distinguished-name field (issuerName) is empty, this extension must be marked CRITICAL. A certificate or CRL can have multiple Issuer Alternate Name extensions at the same time. Use the ISSUER_ALTNAME structure with the C_AddExtensionValue() and C_GetExtensionValue() functions.

typedef struct ISSUING_DISTRIBUTION_POINT ISSUING_DISTRIBUTION_POINT
 

Represents an Issuing Distribution Point (DP) extension for X.509 v3 CRLs. It identifies the CRL DP from which this CRL is distributed, and the types of information this CRL can contain. The default criticality for this extension is CRITICAL. A CRL can have only one Issuing DP extension at a time. Use this structure with C_AddExtensionValue() and C_GetExtensionValue().

typedef UINT4 KEY_USAGE
 

Represents the Key Usage extension for X.509 v3 certificates. This value indicates one or more purposes for which the public key in the certificate can be used. It can also be used for the purposes indicated in the Extended Key Usage extension. The default criticality for this extension is CRITICAL. A certificate can have only one Key Usage extension at a time. Use the KEY_USAGE type with the C_AddExtensionValue() and C_GetExtensionValue() functions. It contains one or more of the following bit-flags:

Key Usage Flag Description
CF_DIGITAL_SIGNATURE Indicates the key can be used to verify signatures other than non-repudiation signatures (CF_NON_REPUDIATION), certificate signatures (CF_KEY_CERT_SIGN), or CRL signatures (CF_CRL_SIGN).
CF_NON_REPUDIATION Indicates the key can be used to verify digital signatures that protect against falsely denying some action.
CF_KEY_ENCIPHERMENT Indicates the key can be used to encrypt other keys, such as for key transport.
CF_DATA_ENCIPHERMENT Indicates the key can be used to encrypt data other than keys.
CF_KEY_AGREEMENT Indicates the key can be used as a public key agreement key.
CF_KEY_CERT_SIGN Indicates the key can be used to verify the CA's signature on a certificate.
CF_CRL_SIGN Indicates the key can be used to verify the CA's signature on a CRL.
CF_ENCIPHER_ONLY Indicates the key is a public key agreement key that can be used only to encipher data. It is used together with the CF_KEY_AGREEMENT flag.
CF_DECIPHER_ONLY Indicates the key is a public key agreement key that can be used only to decipher data. It is used with the CF_KEY_AGREEMENT flag.

typedef struct NAME_CONSTRAINTS NAME_CONSTRAINTS
 

Contains a Name Constraints extension for X.509 v3 certificates. This extension is used only in CA certificates. It describes the name space where all subject names of subsequent certificates in a certification path must be located. The name constraints can apply to a subject's DN or to a subject's alternative names. The default criticality for this extension is CRITICAL. A certificate can have only one Name Constraints extension at a time. This structure is used with C_AddExtensionValue() and C_GetExtensionValue().

note.gif
If both permittedSubtrees and excludedSubtrees are present and the name spaces overlap, the exclusion statement takes precedence.

typedef struct OCSP_ACCEPTABLE_RESPONSES OCSP_ACCEPTABLE_RESPONSES
 

Defines the acceptable OCSP response types. This structure is an input parameter to C_SetExtensionValue().

typedef struct OR_ADDRESS OR_ADDRESS
 

Contains an O/R address that is defined in the X.411 standard. It represents an x400Address in the ALTERNATE_NAME structure. If CN_X400_ADDRESS is set as the altNameType, complete an OR_ADDRESS structure to specify the altName.

typedef struct ORG_UNIT_NAMES ORG_UNIT_NAMES
 

Contains an organizational unit name. It can be used as either a standard attribute or as an extension attribute in an OR_ADDRESS structure. (The OR_ADDRESS can be used as the alternate name in an ALTERNATE_NAME structure.)

  • In the standard attributes structure, STANDARD_ATTRIBUTES, if the SA_ORG_UNIT_NAMES_VALID flag is set in validFields, complete this structure to specify orgUnitNames.
  • In the extension attribute structure, EXTENSION_ATTRIBUTE, if EA_TELETEX_ORG_UNIT_NAME is set as the extension attribute type, complete an ORG_UNIT_NAMES structure to specify the extension attribute value.

typedef struct OTHER_NAME OTHER_NAME
 

Contains an application-defined alternate name. It represents an otherName in the ALTERNATE_NAME structure. If CN_OTHER_NAME is set as the altNameType, complete this structure to specify the altName.

typedef struct PDS_PARAMETER PDS_PARAMETER
 

Contains a physical delivery system value. It can be used as an extension attribute in an OR_ADDRESS structure. (The OR_ADDRESS structure can be used as the alternate name in an ALTERNATE_NAME structure.) In an extension attribute structure, EXTENSION_ATTRIBUTE, it is required to specify an extension attribute type and a corresponding extension attribute value.

typedef struct PERSONAL_NAME PERSONAL_NAME
 

Contains a personal name. It can be used as a standard attribute in an OR_ADDRESS structure (which can be used as an alternate name). In the STANDARD_ATTRIBUTES structure, when using this structure to specify a personalName, set the SA_PERSONAL_NAME_VALID flag in validFields. This structure is also defined as TELETEX_PERSONAL_NAME. The teletex structure is used as an extension attribute, rather than a standard attribute, in the OR_ADDRESS structure.

typedef struct POLICY_CONSTRAINTS_36 POLICY_CONSTRAINTS_36
 

Represents the Policy Constraints extension for X.509 v3 certificates. This extension is used only in CA certificates. It constrains path validation by requiring a policy identifier or by prohibiting policy mapping. The default criticality for this extension is NON_CRITICAL. A certificate can have only one Policy Constraints extension at a time. Use this structure with C_AddExtensionValue() and C_GetExtensionValue().

typedef struct POLICY_INFO POLICY_INFO
 

Represents the Certificate Policies extension for X.509 v3 certificates. It indicates the policy under which the certificate was issued and the purposes for which the certificate can be used. Applications with specific policy requirements can check the policyID to determine whether or not the certificate is acceptable. The default criticality for this extension is NON_CRITICAL. A certificate can have multiple Certificate Policies extensions at the same time. Use this structure with C_AddExtensionValue() and C_GetExtensionValue().

typedef struct POLICY_MAPPING POLICY_MAPPING
 

Represents a Policy Mappings extension for an X.509 v3 certificate. This extension is used only in CA certificates. It contains a pair of domain policies: one for the issuing CA, and another for the subject CA. These are considered to be equivalent by the issuing CA. The policy mapping indicates to the issuing CA that the subject CA's policy is comparable to its own policy. The default criticality for this extension is NON_CRITICAL. A certificate can have multiple Policy Mappings extensions at the same time. Use this structure with C_AddExtensionValue() and C_GetExtensionValue().

typedef struct PRESENTATION_ADDR PRESENTATION_ADDR
 

A type of extended network address in the EXTENSION_ATTRIBUTE structure. Use this structure only when providing an OR_ADDRESS structure as the alternate name in an ALTERNATE_NAME structure, and when completing an extended network address for the EXTENSION_ATTRIBUTE. This structure designates Presentation Address as the type of extended network address.

typedef struct PRIVATE_KEY_USAGE_PERIOD PRIVATE_KEY_USAGE_PERIOD
 

Represents the Private Key Usage Period extension for X.509 v3 certificates. It allows the certificate issuer to specify a different validity period for the private key than for the certificate. The default criticality for this extension is NON_CRITICAL. A certificate can have only one Private Key Usage Period extension at a time. Use this structure with C_AddExtensionValue() and C_GetExtensionValue().

typedef struct QualifierInfo QualifierInfo
 

Stores a policy qualifier. Use in the POLICY_INFO structure.

typedef unsigned int REASON_CODE
 

Represents a Reason Code extension for X.509 v3 CRL entries. It indicates the reason the certificate in the CRL entry was revoked. The default criticality for this extension is NON_CRITICAL. A CRL entry can have only one Reason Code extension at a time. Use the REASON_CODE number with the C_AddExtensionValue() and C_GetExtensionValue() functions.

It contains one of the following flags:

Reason Code Description
CR_UNSPECIFIED Indicates revocation of a certificate for an unspecified reason.
CR_KEY_COMPROMISE Indicates revocation of an end-entity certificate; the subject's private key or validation information has been compromised.
CR_CA_COMPROMISE Indicates revocation of a CA certificate; the subject's private key or validation information has been compromised.
CR_AFFILIATION_CHANGED Indicates the subject's name or other information has been changed.
CR_SUPERSEDED Indicates the certificate has been superseded.
CR_CESSATION_OF_OPERATION Indicates the certificate is no longer needed.
CR_CERTIFICATE_HOLD Indicates the certificate is on hold.
CR_REMOVE_FROM_CRL In a delta CRL, indicates the existing CRL entry should now be removed due to certificate expiration or hold release.
CR_PRIVILEGE_WITHDRAWN Indicates a certificate (public key or attribute certificate) was revoked because a privilege contained within that certificate has been withdrawn.
CR_AA_COMPROMISE Indicates it is known or suspected that aspects of the AA validated in the attribute certificate have been compromised.

typedef ALTERNATE_NAME SUBJECT_ALTNAME
 

Represents a Subject Alternate Name extension for an X.509 v3 certificate. It allows the subject's alternative names to be bound to the certificate, in addition to the subject's DN. For the certificate to be valid, all of the alternative names must also be verified by the CA, because the alternative names are also definitively bound to the subject's public key. The default criticality for this extension is NON_CRITICAL. However, if the certificate's subject-distinguished-name field (subjectName) is empty, this extension must be marked CRITICAL. The subject's alternative names can be constrained by the Name Constraints extension. A certificate can have multiple Subject Alternate Name extensions at the same time. Use the SUBJECT_ALTNAME structure with the C_AddExtensionValue() and C_GetExtensionValue() functions.

typedef ATTRIBUTES_OBJ SUBJECT_DIR_ATTRIB
 

Represents a Subject Directory Attributes extension for an X.509 v3 certificate. It contains additional attribute values, beyond those already contained in the subject's DN, that can be used to identify the subject of the certificate. The SUBJECT_DIR_ATTRIB object is an ATTRIBUTES_OBJ object. The default criticality for this extension is NON_CRITICAL. A certificate can have multiple Subject Directory Attributes extensions at the same time. Use the SUBJECT_DIR_ATTRIB object with the C_AddExtensionValue() and C_GetExtensionValue() functions.

typedef ITEM SUBJECT_KEY_ID
 

Represents a Subject Key Identifier extension for an X.509 v3 certificate. It is an ITEM structure whose data member points to the certificate subject's public key identifier. This identifier provides a way to identify certificates that contain a particular public key.

  • In a CA certificate, this extension is used to facilitate chain building. This extension should be included in all CA certificates. The CA should also place the same key identifier into the Authority Key Identifier extension of each certificate or CRL that it issues. This can help applications build a certificate chain back to the CA more quickly.
  • In an end-entity certificate, this extension is used to help applications quickly identify the appropriate end-entity certificate when the end entity has multiple certificates. This extension should be included in all end-entity certificates.
The default criticality for this extension is NON_CRITICAL. A certificate can have only one Subject Key Identifier extension at a time. Use the SUBJECT_KEY_ID structure with the C_AddExtensionValue() and C_GetExtensionValue() functions.

typedef struct TYPED_STRING TYPED_STRING
 

Holds a typed string. It can be used as either a standard attribute or an extension attribute in an OR_ADDRESS structure (which can be used as the alternate name in an ALTERNATE_NAME structure).

  • In the standard attributes structure, STANDARD_ATTRIBUTES, three fields are represented by this structure: countryName, administrationDomainName, and privateDomainName. It is also necessary to set the corresponding flag in validFields. See STANDARD_ATTRIBUTES for more information.
  • In the extension attribute structure, EXTENSION_ATTRIBUTE, two fields are represented by a TYPED_STRING structure. If either EA_POSTAL_CODE or EA_PHYSICAL_DELIVERY_COUNTRY_NAME is set as the extension attribute type, complete a TYPED_STRING structure to specify the extension attribute value.

typedef struct UNFORMATTED_POSTAL_ADDR UNFORMATTED_POSTAL_ADDR
 

Contains a non-formatted postal address. It can be used as an extension attribute in an OR_ADDRESS structure. (The OR_ADDRESS can be used as the alternate name in an ALTERNATE_NAME structure.) In the extension attribute structure, EXTENSION_ATTRIBUTE, if EA_UNFORMATTED_POSTAL_ADDR is set as the extension attribute type, complete an UNFORMATTED_POSTAL_ADDR structure to specify the extension attribute value.

Enumeration Type Documentation

enum OCSP_CRLREF_TYPE
 

The OCSP_CRLREF_TYPE enumeration indicates the type of information contained in the OCSP_CRL_REFERENCE structure that is currently being used.

Enumeration values:
OCSP_CRLREF_TYPE_UNSPECIFIED OCSP_CRL_REFERENCE.info is undefined.
OCSP_CRLREF_TYPE_URL OCSP_CRL_REFERENCE.info is a URL.
OCSP_CRLREF_TYPE_NUMBER OCSP_CRL_REFERENCE.info is a CRL number.
OCSP_CRLREF_TYPE_TIME OCSP_CRL_REFERENCE.info is a GENERALIZED_TIME structure.

Function Documentation

int C_AddExtensionValue (  EXTENSIONS_OBJ    extensionsObject,
unsigned int    index,
POINTER    value,
unsigned int *    valueIndex
)  ;
 

Adds an extension value to an existing extension entry in extensionsObject, which must be referenced by index.

Parameters:
extensionsObject [In, Out] The extensions object to update with the new extension value.
index [In] The index of the extension entry in the extensions object.
value [In] The extension value to add.
  • If the value is NULL_PTR, an error is returned.
  • If the extension entry has no value yet, the new value is added to the extension's value list.
  • If the extension entry already has one or more values and allows multiple values, the new value is appended to the value list.
  • If the extension entry already has a value and allows only a single value, the new value replaces the old value.
The C data structure for value is a generic pointer type; it must point to a C data structure that matches the extension's type.

When you provide this value pointer, Cert-C calls your extension handler's AllocAndCopy callback function to create a separate copy of value for the extensionsObject. Therefore, after this call to C_AddExtensionValue(), you can modify this copy of value.
valueIndex [Out] The index of the value in the extension entry's value list. The position of the inserted value is saved in valueIndex, unless valueIndex is (unsigned int *)NULL_PTR.
Returns:
0 indicates success.
See Errors for error information.
Samples:
extnutil.c, and smplsaltnm.c.

int C_CompareExtension (  EXTENSIONS_OBJ    extensionsObject1,
unsigned int    extensionIndex1,
EXTENSIONS_OBJ    extensionsObject2,
unsigned int    extensionIndex2
)  ;
 

Compares two extensions. The extensions match if they are of the same type, and if at least one value of the first extension matches a value of the second extension. In general, the entire DER encoding of both extensions must be identical for the extensions to match. However, this function implements more permissive matching rules for extensions of the following types:

  • ET_SUBJECT_ALTNAME
  • ET_ISSUER_ALT_NAME
  • ET_KEY_USAGE
  • ET_EXTENDED_KEY_USAGE.
For subject and issuer alternative names, this function compares individual values using the matching rules defined in RFC 2459. The value of the first extension is considered to be the constraint and the second value is matched against that constraint. The extension values (and therefore the extensions as a whole) match if the set of values described by the constraint includes the second value.

For key usage extensions, this function compares the individual bits of the first extension with the second. The extension match if all of the bits set in the first extension are also set in the second.

For extended key usage extensions, this function compares the individual key purpose identifiers of the two extensions. The extensions match if at least one identifier from the first extension is also contained in the second extension.

Parameters:
extensionsObject1 [In] The first extensions object.
extensionIndex1 [In] The index of the first extension to compare.
extensionsObject2 [In] The second extensions object.
extensionIndex2 [In] The index of the second extension to compare.
Returns:
If the extension entries match, returns 0 (zero). If not, returns a non-zero value.

int C_CompareExtensions (  EXTENSIONS_OBJ    extensionsObject1,
EXTENSIONS_OBJ    extensionsObject2
)  ;
 

Compares two extensions objects (each representing a set of extensions). The extensions objects match if each extension in the first object matches the corresponding extension in the second object. Call C_CompareExtension() to compare individual extensions.

Parameters:
extensionsObject1 [In] The first extensions set to compare.
extensionsObject2 [In] The second extensions set to compare.
Returns:
If the extension objects match, returns 0 (zero). If not, returns a non-zero value.

int C_CreateExtension (  EXTENSIONS_OBJ    extensionsObject,
unsigned char *    type,
unsigned int    typeLen,
unsigned int *    index,
int    criticality,
EXTENSION_HANDLER *    newHandler
)  ;
 

Creates a new extension entry in extensionsObject. If the extension type already exists in the extensions object, an error is returned. C_CreateExtensionsObject() constrains the extension type that can be created. If the extension type is not allowed, an error is returned. Otherwise, a new extension is created with the type set to type. Separate copies of type and newHandler are created for the new extension. The extension's value list is empty at this point.

Parameters:
extensionsObject [In, Out] The extensions object to update with the new extension.
type [In] The extension type.
typeLen [In] The length of the extension type.
index [Out] The index of the new extension in the extensions object.
criticality [In] The extension's criticality. Set this flag to one of the following values:

Criticality Flag Description
NOT_IN_USE The extension is created with the registered or default criticality.
CRITICAL If the override-criticality flag is set, the extension is marked critical.
NON_CRITICAL If the override-criticality flag is set, the extension is marked noncritical.

If this flag is set to NOT_IN_USE:
  • If it is an extension type whose criticality has been set by the C_RegisterExtensionType() function, the registered criticality is used.
  • Otherwise, the default criticality is used.
If this flag is set to CRITICAL or NON_CRITICAL:
  • If the default or registered override-criticality flag for this extension type is set to ALLOW_OVERRIDE_CRITICALITY, then the criticality of this extension is set to criticality.
  • If the override-criticality flag for this extension type is not set, then the E_OVERRIDE_CRITICAL_NOT_ALLOWED error is returned. Lastly, if the extension type is unknown, and if criticality is set to CRITICAL, then the E_UNKNOWN_CRITICAL_EXTENSION error is returned.
newHandler [In] The extension handler to be used for manipulating the values of this extension.
  • If newHandler is NULL_PTR, the new extension uses the default handler; a reference to the default handler is saved in the extension.
  • If newHandler is not NULL_PTR, and the registered handler for this extension type allows overriding, a copy of newHandler is saved in the extension. Otherwise, E_OVERRIDE_HANDLER_NOT_ALLOWED is returned.
The handler can be overridden only if the registered handler allows overriding. The replaced handler affects only the extension being created, and is destroyed when the extension is deleted. All supported standard extensions allow overriding of the default extension handlers.
Returns:
0 indicates success.
See Errors for error information.
Samples:
extnutil.c, and smplsaltnm.c.

int C_CreateExtensionsObject (  EXTENSIONS_OBJ *    extensionsObject,
unsigned int    extensionsObjectType,
CERTC_CTX    applContext
)  ;
 

Creates an extensionsObject of type extensionsObjectType. The extensionsObjectType constrains the types of extensions that can be added to the extensionsObject. If applContext is not NULL_PTR, a reference to it is saved in extensionsObject.

Parameters:
extensionsObject [Out] A pointer to an EXTENSIONS_OBJ.
extensionsObjectType [In] The type of extensions object to create.

Extensions Object Type Description
CERT_EXTENSIONS_OBJ Certificate extensions object
CRL_EXTENSIONS_OBJ CRL extensions object
CRL_ENTRY_EXTENSIONS_OBJ CRL entry extensions object
OCSP_REQUEST_EXTENSIONS_OBJ OCSP request extensions object
OCSP_SINGLE_EXTENSIONS_OBJ OCSP single-certificate extensions object

applContext [In] The Cert-C context.
Returns:
0 indicates success.
See Errors for error information.
Samples:
attrib.c, certutil.c, crlutil.c, exten.c, extnutil.c, kcscrs.c, kcsscep.c, pkcs10.c, pkcs11db.c, scepreq.c, and smplsaltnm.c.

int C_DeleteExtensionValue (  EXTENSIONS_OBJ    extensionsObject,
unsigned int    index,
unsigned int    valueIndex
)  ;
 

Deletes the extension value referenced by valueIndex in the extension entry referenced by index. All of the extension's values after the deleted value are shifted back by one. If the extension or the extension value is not found, an error is returned. Otherwise, the value is destroyed. The extension type handler's Destructor callback is called to free the memory associated with the extension value.

Parameters:
extensionsObject [In, Out] The extensions object.
index [In] The index of the extension entry that contains the value to be deleted.
valueIndex [In] The index of the value to delete.
Returns:
0 indicates success.
See Errors for error information.

int C_DestroyExtension (  EXTENSIONS_OBJ    extensionsObject,
unsigned int    index
)  ;
 

Destroys one extension as referenced by index. If the extension is not found, an error is returned. Otherwise, the extension and its associated value list are deleted. All the extensions after the deleted extension are shifted back by one in the extension index.

Parameters:
extensionsObject [In, Out] As an input parameter, it is the extensions object that contains the extension entry to destroy. As an output parameter, it is the updated extensions object.
index [In] The index of the extension entry to destroy.
Returns:
0 indicates success.
See Errors for error information.

void C_DestroyExtensionsObject (  EXTENSIONS_OBJ *    extensionsObject )  ;
 

Destroys all extensions in extensionsObject and deletes all associated value lists. Frees all memory used, and sets extensionsObject to NULL_PTR. No action is taken if extensionsObject is already (EXTENSIONS_OBJ)NULL_PTR.

Parameters:
extensionsObject [In, Out] As an input parameter, it is the extensions object that Cert-C should destroy. As an output parameter, it is (EXTENSIONS_OBJ)NULL_PTR.
Samples:
attrib.c, attributil.c, certutil.c, crlutil.c, dcrl.c, exten.c, extnutil.c, kcscrs.c, kcsscep.c, pkcs11db.c, scepreq.c, and smplsaltnm.c.

int C_FindExtensionByType (  EXTENSIONS_OBJ    extensionsObject,
unsigned char *    type,
unsigned int    typeLen,
unsigned int *    index
)  ;
 

Finds the extension of the type given in type. If an extension is found, its index is returned in index. Otherwise, an error is returned.

Parameters:
extensionsObject [In] The extensions object.
type [In] The extension type.
typeLen [In] The length of the extension type.
index [Out] The index of the extension.
Returns:
0 indicates success.
See Errors for error information.
Samples:
extnutil.c, and saltname.c.

int C_GetAttributeInExtensionsObj (  EXTENSIONS_OBJ    extensionsObject,
ATTRIBUTES_OBJ    attributesObject
)  ;
 

Transfers data from extensionsObject to attributesObject. If attributesObject does not include an attribute of the type AT_X509_V3_EXTENSIONS, a new attribute of this type is created with the value set to the DER-encoded value of the extensionsObject. Otherwise, its value is overwritten with the DER-encoded value of extensionsObject. If extensionsObject is empty, an error is returned and attributesObject remains unchanged.

Parameters:
extensionsObject [In] The extensions object.
attributesObject [Out] The attributes object.
Returns:
0 indicates success.
See Errors for error information.
Samples:
attrib.c, and attributil.c.

int C_GetEncodedExtensionValue (  EXTENSIONS_OBJ    extensionsObject,
unsigned int    index,
unsigned char **    encodedValue,
unsigned int *    encodedValueLen
)  ;
 

Retrieves the encoded form of the value(s) of the extension referenced by index. If the extension is found, its value list is encoded (by calling the extension handler's GetEncodedValue callback) and saved in encodedValue and encodedValueLen. Otherwise, an error is returned.

Parameters:
extensionsObject [In] The extensions object.
index [In] The extension's index.
encodedValue [Out] The encoded extension's value.
encodedValueLen [Out] The length of the encoded extension's value.
Returns:
0 indicates success.
See Errors for error information.
note.gif
Do not create any objects or items before calling this function. After calling this function, you share the returned fields with extensionsObj. If you modify any of these fields, you must call C_SetEncodedExtensionValue() to ensure that the internal state of the object is consistent with these modifications.

int C_GetExtensionCount (  EXTENSIONS_OBJ    extensionsObject,
unsigned int *    count
)  ;
 

Retrieves the total number of extension entries in extensionsObject and returns it in count.

Parameters:
extensionsObject [In] The extensions object.
count [Out] The number of extension entries in the extensions object.
Returns:
0 indicates success.
See Errors for error information.
Samples:
extnutil.c, and myprint.c.

int C_GetExtensionDER (  EXTENSIONS_OBJ    extensionsObject,
unsigned int    index,
unsigned char **    valueDER,
unsigned int *    valueDERLen
)  ;
 

Retrieves the DER encoding of the extension entry referenced by index. If the extension is found, valueDER is set to the DER encoding of the extension with the length valueDERLen. Otherwise, an error is returned.

valueDER includes the encoding of the extension type and criticality, and the DER encoding of the extension's value(s). If this function is called on an extension that currently has no extension value, an error is returned. For an unknown extension type, if the extension value is already DER-encoded, then its value is saved as is. Otherwise, it is encoded as an octet string.

Parameters:
extensionsObject [In] The extensions object.
index [In] The extension entry's index.
valueDER [Out] The DER-encoded extension entry.
valueDERLen [Out] The length of the DER-encoded extension entry.
Returns:
0 indicates success.
See Errors for error information.
note.gif
This function returns read-only fields. Do not create any objects or items before calling this function. Do not call any functions, such as C_Destroy*(), that modify these fields.
Samples:
extnutil.c.

int C_GetExtensionInfo (  EXTENSIONS_OBJ    extensionsObject,
unsigned int    index,
EXTENSION_INFO *    extensionInfo
)  ;
 

Retrieves information about the extension referenced by index, and places it in extensionInfo. The data structure for extensionInfo is EXTENSION_INFO. If an extension is not found, an error is returned. This function is intended to obtain a read-only type field. Do not attempt to call a C_Set*() or C_Destroy*() function on it.

Parameters:
extensionsObject [In] The extensions object.
index [In] The extension's index.
extensionInfo [Out] A pointer to the data structure for extensionInfo. If an extension is found, then the type and typeLen fields of extensionInfo are set to the type and type length of the extension. The criticalFlag field is set to the extension's criticality flag. The valueCount field is set to the number of values in the extension's value list. The reserved field is set to NULL_PTR, and should be ignored. The type field is undefined after either extensionsObject or the extension is destroyed.
Returns:
0 indicates success.
See Errors for error information.
note.gif
This function returns read-only fields. Do not create any objects or items before calling this function. Do not call any functions, such as C_Destroy*(), that modify these fields.
Samples:
extnutil.c, myprint.c, and saltname.c.

int C_GetExtensionsInAttributesObj (  EXTENSIONS_OBJ    extensionsObject,
ATTRIBUTES_OBJ    attributesObject
)  ;
 

Transfers the value of attributesObject into extensionsObject. If attributesObject does not contain an attribute of the type AT_X509_V3_EXTENSIONS, then the error E_NOT_FOUND is returned, and extensionsObject remains unchanged. Otherwise, the current value of extensionsObject is overwritten with the attribute's value.

Parameters:
extensionsObject [Out] The extensions object.
attributesObject [In] The attributes object.
Returns:
0 indicates success.
See Errors for error information.
Samples:
exten.c, and pkcs10.c.

int C_GetExtensionsObjectDER (  EXTENSIONS_OBJ    extensionsObject,
unsigned char **    der,
unsigned int *    derLen
)  ;
 

Retrieves the DER-encoded value of all the extensions in extensionsObject. For each extension type in the extensionsObject, the corresponding GetEncodedValue callback in the handler is called to obtain the encoded extension value.

Parameters:
extensionsObject [In] The extensions object.
der [Out] A pointer to the DER-encoded extension value.
derLen [Out] A pointer to the length of the DER-encoded extension value.
Returns:
0 indicates success.
See Errors for error information.
note.gif
This function returns read-only fields. Do not create any objects or items before calling this function. Do not call any functions, such as C_Destroy*(), that modify these fields.
Samples:
cert.c, crl.c, exten.c, pkcs10.c, and smplsaltnm.c.

int C_GetExtensionTypeByIndex (  EXTENSIONS_OBJ    extensionsObject,
unsigned char **    type,
unsigned int *    typeLen,
unsigned int    index
)  ;
 

Retrieves the extension type from extensionsObject at the index given in index.

Parameters:
extensionsObject [In] The extensions object.
type [Out] The extension type.
typeLen [Out] The length of the extension type.
index [In] The index of the extension entry.
Returns:
0 indicates success.
See Errors for error information.
note.gif
This function returns read-only fields. Do not create any objects or items before calling this function. Do not call any functions, such as C_Destroy*(), that modify these fields.

int C_GetExtensionTypeInfo (  CERTC_CTX    applContext,
unsigned char *    type,
unsigned int    typeLen,
EXTENSION_TYPE_INFO *    info
)  ;
 

Searches for the extension type in applContext. If it is not found, it searches the default standard extension table that Cert-C provides. An error is returned if an extension type is not found. Otherwise, the associated extension's information is copied into info. For example, to encode an extension value with an encoding scheme other than DER encoding, an application might call this function to obtain a copy of the extension handler. In this case, it overrides the handler's SetEncodedValue and GetEncodedValue callbacks with its own decoding and encoding functions. For the overriding to take effect globally, call C_RegisterExtensionType() with the modified handler. This affects only those extensions that are created after this call, not those that were created before it. Alternatively, call C_CreateExtension() for a local overriding of a single extension's handler and its criticality.

Parameters:
applContext [In] The Cert-C context.
type [In] The OID for the extension type.
typeLen [In] The length of the extension type's OID.
info [Out] The definition information for the extension type.
Returns:
0 indicates success.
See Errors for error information.
note.gif
This function returns read-only fields. Do not create any objects or items before calling this function. Do not call any functions, such as C_Destroy*(), that modify these fields.
Samples:
critical.c, and saltname.c.

int C_GetExtensionValue (  EXTENSIONS_OBJ    extensionsObject,
unsigned int    extenIndex,
unsigned int    valueIndex,
POINTER *    value
)  ;
 

Retrieves the value referenced by valueIndex in the extension's value list. The target extension is referenced by the extenIndex. The pointer to the extension value that is referenced by the valueIndex is saved in value. The data structure for value depends on the extension type. This function is intended to obtain a read-only value. Do not attempt to call a C_Set*() or C_Destroy*() function on it. The value is undefined after the extensionsObject or the extension is destroyed.

Parameters:
extensionsObject [In] The extensions object.
extenIndex [In] The extension's index.
valueIndex [In] The extension value's index.
value [Out] The extension value.
Returns:
0 indicates success.
See Errors for error information.
Samples:
extnutil.c, and saltname.c.

int C_RegisterExtensionType (  CERTC_CTX    applContext,
EXTENSION_TYPE_INFO *    extenTypeInfo
)  ;
 

Registers an application-defined extension type, or overrides the default setting of a supported standard extension type, with the value given in extenTypeInfo. When an extension type and its handler are registered, a new entry is created in applContext, with the given information in extenTypeInfo. The data structure for extenTypeInfo is EXTENSION_TYPE_INFO.

Parameters:
applContext [In] The Cert-C context.
extenTypeInfo [In] The extension definition information.

Setting the Extension-Type Fields

The type and typeLen contain the extension OID and length, respectively.

The criticality field indicates the extension's criticality. Set criticality to CRITICAL if the extension is always critical. Otherwise, set it to NON_CRITICAL.

Set the overrideCriticality flag to ALLOW_OVERRIDE_CRITICALITY if you want to allow a local overriding of the given criticality at C_CreateExtension() time. Otherwise, set it to 0 (zero).

Set the overrideHandlerFlag flag to ALLOW_OVERRIDE_HANDLER if you want to allow a local overriding of the given handler at C_CreateExtension() time. Otherwise, set it to 0 (zero).

The authenObjects field indicates the type of object that can include this extension type. It can be set to CERT_EXTENSIONS_OBJ, CRL_EXTENSIONS_OBJ, CRL_ENTRY_EXTENSIONS_OBJ, OCSP_REQUEST_EXTENSIONS_OBJ, OCSP_SINGLE_EXTENSIONS_OBJ, or a combination of these by 'OR'ing them together.

If the uniqueValue flag is set to a non-zero value, the extension type can have only a single value. If the flag is set to 0 (zero), the extension type can have multiple values.

If handler is (EXTENSION_HANDLER*)NULL_PTR, or if the callbacks in handler are not all provided, an error is returned.

Overriding the Extension-Type Fields

To override the default setting of a supported standard extension type, or of a preregistered application-defined extension of type type, only the criticality and the handler are allowed to change; other fields are ignored.
  • To override the default criticality, set overrideCriticality to a non-zero value, and criticality to the target criticality. Otherwise, set overrideCriticality to 0 (zero). If the target extension does not allow overriding of the criticality, an error is returned. Otherwise, the default criticality is replaced by criticality.
  • To override the default handler, set overrideHandler to a non-zero value and handler to the target callbacks. Otherwise, set overrideHandler to 0 (zero). If the callbacks in handler are not all provided, an error is returned. If the extension allows overriding of the handler, then handler replaces the default handler.
These overridings have a global effect on all C_CreateExtension() calls (after this call) performed within the application context, until C_UnregisterExtensionType() or C_FinalizeCertC() is called. Otherwise, an error is returned.

The callbacks provided in handler must manipulate the value (or possibly a list of values) for the extension type. Because a copy of the given extension type and its settings are saved in applContext, the application is expected to call C_FinalizeCertC() before it shuts down, to free the allocated memory.

All supported standard extension types allow the default handlers to be overridden.
Returns:
0 indicates success.
See Errors for error information.
Samples:
critical.c, saltname.c, and userextn.c.

void C_ResetExtensionsObject (  EXTENSIONS_OBJ    extensionsObject )  ;
 

Returns extensionsObject to the state it was in after it was created. It does this by deleting all the extensions and their value lists, and freeing any memory that was held by the object. The object type is the same as when the object was created.

Parameters:
extensionsObject [In, Out] As an input parameter, it is the extensions object that Cert-C should reset. As an output parameter, it is the reset extensions object.
Returns:
None.

int C_SetEncodedExtensionValue (  EXTENSIONS_OBJ    extensionsObject,
unsigned int    index,
unsigned char *    encodedValue,
unsigned int    encodedValueLen
)  ;
 

Sets the extension referenced by index with the value given in encodedValue and encodedValueLen. If an extension-type handler is not registered, then the encodedValue is added as an uninterpreted byte string. Otherwise, encodedValue is decoded and instantiated as a C data structure by calling the extension handler's SetEncodedValue callback. In both cases,the new value replaces any existing value. A separate copy of encodedValue is created internally for extensionsObject, so encodedValue can be reused by the caller.

Parameters:
extensionsObject [In, Out] The extensions object.
index [In] The extension index.
encodedValue [In] The encoded extension value.
encodedValueLen [In] The length of the encoded extension value.
Returns:
0 indicates success.
See Errors for error information.

int C_SetExtensionBER (  EXTENSIONS_OBJ    extensionsObject,
unsigned int *    index,
unsigned char *    ber,
unsigned int    berLen
)  ;
 

Instantiates an extension with the information in ber and berLen. If an extension of the same type already exists in extensionsObject, its value is overridden with the new data. Otherwise, a new extension entry is created.

For extension types whose criticalities can be overridden, if the incoming extension criticality is CRITICAL and it is registered as NON_CRITICAL, then the extension is saved with the criticality set to CRITICAL. However, if the incoming criticality is NON_CRITICAL but is registered as CRITICAL, E_INVALID_CRITICALITY is returned.

For extension types whose criticalities cannot be overridden, if the incoming criticality is not the same as the default or registered criticality, E_OVERRIDE_CRITICAL_NOT_ALLOWED is returned.

If an extension type is unknown and the incoming criticality is NON_CRITICAL, then the content is added as an uninterpreted byte string. (The SetEncodedValue callback in the default unknown extension type ET_UNKNOWN_TYPE handler is used to handle this case.) If an extension type is unknown and the incoming criticality is CRITICAL, then E_UNKNOWN_CRITICAL_EXTENSION is returned.

For an unknown noncritical extension type, if the extension value is not BER-encoded, this function returns an error. If it is BER-encoded and not of type VT_OCTET_STRING, then the value is saved as is. If the type is VT_OCTET_STRING, the content is saved as the extension value.

Parameters:
extensionsObject [In, Out] The extensions object.
index [In, Out] The extension index. If index is not (unsigned int *)NULL_PTR, then the index of the new extension is returned in index. Otherwise, it is not used.
ber [In] The BER-encoded extension value. When ber is accepted, it is decoded and instantiated with the new criticality and value (as a C data structure by calling the extension handler's SetEncodedValue callback). A separate copy of ber is created internally for extensionsObject, so the ber can be reused by the application.
berLen [In] The length of the BER-encoded extension value.
Returns:
0 indicates success.
See Errors for error information.

int C_SetExtensionsObjectBER (  EXTENSIONS_OBJ    extensionsObject,
unsigned char *    ber,
unsigned int    berLen
)  ;
 

Sets extensionsObject with the new extension entries given in ber. The extension types in ber must be compatible with the object type of the extensionsObject. If extensionsObject is already set with extension entries before calling this function, they are overwritten with any new extension entries. A separate copy of ber is created internally for extensionsObject, so that ber can be modified by the caller after calling this function. The incoming extensions are checked against the object type of the extensionsObject. If an extension type is unknown and the incoming criticality is NON_CRITICAL, then the content is added as an uninterpreted byte string. (The SetEncodedValue callback in the default unknown extension type ET_UNKNOWN_TYPE handler is used to handle this case.) If an extension type is unknown and the incoming criticality is CRITICAL, then E_UNKNOWN_CRITICAL_EXTENSION is returned. For extension types whose criticalities can be overridden, if the incoming extension criticality is CRITICAL and it is registered as NON_CRITICAL, then the extension is saved with the criticality set to CRITICAL. However, if the incoming criticality is NON_CRITICAL but is registered as CRITICAL, E_INVALID_CRITICALITY is returned. For extension types whose criticalities cannot be overridden, if the incoming criticality is not the same as the default or registered criticality, E_OVERRIDE_CRITICAL_NOT_ALLOWED is returned. For each extension type in ber, the corresponding SetEncodedValue callback in the handler is called to obtain the decoded extension value in a C data structure format. This structure is added to the extension's value list by calling the corresponding AllocAndCopy callback of the handler. If an extension of the same type occurs more than once, an error is returned.

Parameters:
extensionsObject [In, Out] The extensions object.
ber [In] The BER-encoded extension-type value.
berLen [In] The length of the BER-encoded extension-type value.
Returns:
0 indicates success.
See Errors for error information.
Samples:
attrib.c, and extnutil.c.

int C_UnregisterExtensionType (  CERTC_CTX    applContext,
unsigned char *    type,
unsigned int    typeLen
)  ;
 

Resets or removes a registered extension handler and extension type from applContext. If type is an application-defined extension type, this function removes the extension and its setting from applContext. After this point, any attempt to create or use this extension type results in an error. However, this does not affect those extensions of the same type that were created before this call. If the extension type is one of the supported standard extension types, and the corresponding setting was overridden, then this function resets the extension to the default value. After this point, the default setting is used for any attempt to create or use this extension type. However, this function does not affect those extensions of the same extension type that were created before this call. If the extension type is one of the supported standard extension types, and it was not overridden, then E_DEFAULT_STANDARD_EXTENSION is returned. Otherwise, E_NOT_FOUND is returned. If ctx is NULL_PTR, an error is returned. If type is NULL_PTR or typeLen is 0 (zero), then nothing occurs.

Parameters:
applContext [In] The Cert-C context.
type [In] The OID for the extension type.
typeLen [In] The length of the extension type's OID.
Returns:
0 indicates success.
See Errors for error information.

Copyright (c) 1999-2005 RSA Security Inc. All rights reserved. 067-001001-2720-001-000 - 2.7.2