RSA Security logo

RSA BSAFE Cert-C
API Reference

basetype.h File Reference

This file defines the basic Cert-C types.

The file aglobal.h that is included here and elsewhere is a RSA BSAFE Crypto-C header and is found in the Crypto-C package. The typedef for POINTER that is used throughout Cert-C originates in aglobal.h.

#include "aglobal.h"

Go to the source code of this file.

Data Structures

 BIT_STRING
 A low-level structure that holds an ordered sequence of bits. More...

 GENERALIZED_TIME
 Stores a time value. More...


Typedefs

typedef BIT_STRING BIT_STRING
 A low-level structure that holds an ordered sequence of bits. More...

typedef GENERALIZED_TIME GENERALIZED_TIME
 Stores a time value. More...

typedef POINTER CERTC_CTX
 Use the Cert-C context, CERTC_CTX, to collect a number of common parameters and state variables. More...

typedef POINTER LIST_OBJ
 Use the LIST_OBJ object to store and pass a collection of abstract data types, including types defined by Cert-C and types defined by your application. More...

typedef POINTER NAME_OBJ
 Cert-C uses a NAME_OBJ object to represent the names of entities involved in privacy enhancement. More...

typedef POINTER ATTRIBUTES_OBJ
 Cert-C uses an ATTRIBUTES_OBJ object to store and pass extra information about the certificate subject in a certification request. More...

typedef POINTER EXTENSIONS_OBJ
 Cert-C represents X.509 v3 extensions with an EXTENSIONS_OBJ object. More...

typedef POINTER CERT_OBJ
 Cert-C represents certificate information with a CERT_OBJ object. More...

typedef POINTER CRL_ENTRIES_OBJ
 Some CRL functions act on CRL_ENTRIES_OBJ objects instead of on CRL_OBJ objects. More...

typedef POINTER CRL_OBJ
 Cert-C represents CRL information with a CRL_OBJ object. More...

typedef POINTER SERVICE
 A service handle. More...

typedef POINTER DB_ITERATOR
 Use the database iterator handle, DB_ITERATOR, to sequentially retrieve records of a particular type from a database or a set of databases. More...

Typedef Documentation

typedef POINTER ATTRIBUTES_OBJ
 

Cert-C uses an ATTRIBUTES_OBJ object to store and pass extra information about the certificate subject in a certification request. An attributes object contains an attribute set represented in two forms: as a DER encoding and a list of attributes. The two forms provide equivalent information. The DER encoding is an unsigned character string that represents the attribute set. The attributes list gives each attribute in the set, one at a time.

An attribute set is made up of attributes. Each attribute has an attribute type and one or more values. Some attribute types, such as the time at which a message is signed, can only have one value; other attribute types, such as a postal address, can have multiple values. There is no significance to the ordering of the different attribute types in an attribute set, or to the ordering of multiple values for a particular attribute type.

Attributes-Object Functions

Use a Cert-C function to view or modify information in an ATTRIBUTES_OBJ. When you call one of these functions, you cannot assume that the ATTRIBUTES_OBJ points to any specific information. Some examples of the functions that Cert-C provides for manipulating an attributes object are listed in the following table:

Function Description
C_CreateAttributesObject() Creates a new attributes object.
C_GetAttributesDER() Gets a pointer to the DER encoding that represents the attribute set.
C_SetAttributesBER() Modifies the value of an attribute set to a given BER encoding.
C_GetAttributeTypeCount()      Gets the number of attributes in an attributes object’s attribute list.
C_GetAttributeType() Gets the type of a specific attribute from an attributes object’s attribute list.
C_GetAttributeValueCount() Gets the number of attribute values for a specific attribute type in an attributes object’s attribute list.
C_GetAttributeValueDER() Gets the DER encoding of a specific value of a specific attribute in an attributes object’s attribute list.
C_GetStringAttribute() Gets the contents and type tag of a specific string-based attribute in an attributes object list.
C_DeleteAttributeType() Deletes a specific attribute type and all its values from an attributes object’s attribute list.
C_AddAttributeValueBER() Adds the BER encoding of an attribute value to a specific attribute type in an attributes object’s attribute list.
C_AddStringAttribute() Adds the contents and type tag of a specific string-based attribute to an attributes object’s attribute list.
C_ResetAttributesObject() Resets an attributes object, returning the attributes object to the state produced by calling the C_CreateAttributesObject() function.
C_DestroyAttributesObject()     Destroys an attributes object, freeing the memory the attributes object occupied.

Attribute Types and Constraints

Cert-C defines a number of attribute types. For some attribute types, Cert-C places some constraints on the corresponding attribute values and their tags. For additional attributes information, see Attribute Types and Constraints. This section lists the attribute types and lengths (given as variables that the application can reference), the attribute descriptions, and the attribute value and length constraints.

For more information on Cert-C objects, see Cert-C Objects.

typedef struct BIT_STRING BIT_STRING
 

A low-level structure that holds an ordered sequence of bits. The BIT_STRING structure is used with the C_BERDecodeBitString(), C_DEREncodeBitString(), and C_DEREncodeNamedBitString() functions. It is also used in the CERT_FIELDS structure.

For example, given the following 12-bit string: 1011 0000 1001

Create the following BIT_STRING structure:

    BIT_STRING newBitString;
    unsigned char bitData[2];

    bitData[0] = 0xB0;
    bitData[1] = 0x90;
    newBitString.data = bitData;
    newBitString.len = 2;
    newBitString.unusedBits = 4;

typedef POINTER CERT_OBJ
 

Cert-C represents certificate information with a CERT_OBJ object. Use the CERT_OBJ object to store and pass information about a particular certificate.

A certificate's version can be CERT_VERSION_1, CERT_VERSION_2, or CERT_VERSION_3.

  • If a certificate's version is CERT_VERSION_2, then it can contain an issuerUniqueID and a subjectUniqueID.
  • If a certificate's version is CERT_VERSION_3, then it can also include an extensionsObject, which represents X.509 v3 certificate extensions.
Certificate-Object Functions

Use a Cert-C function to view or modify information in a CERT_OBJ object. When you call one of these functions, you cannot assume that the CERT_OBJ points to any specific information. Some examples of the functions that Cert-C provides for manipulating certificates and checking certificate signatures are listed in the following table:

Function Description
C_CreateCertObject() Creates a certificate object.
C_GetCertFields() Gets the content of the CERT_FIELDS structure in the certificate object.
C_SetCertFields() Sets a certificate object to the values provided in a CERT_FIELDS structure.
C_GetCertDER() Gets the DER encoding of a certificate object.
C_SetCertBER() Sets the BER encoding of a certificate object.
C_GetCertInnerDER() Gets the DER encoding of the inner portion of a certificate object.
C_SetCertInnerBER() Sets the BER encoding of the inner portion of a certificate object.
C_SignCert() Signs a certificate object.
C_VerifyCertSignature()   Checks the signature on a certificate object.
C_DestroyCertObject() Destroys a certificate object, freeing the memory that the certificate object occupied.

For more information on Cert-C objects, see Cert-C Objects.

typedef POINTER CERTC_CTX
 

Use the Cert-C context, CERTC_CTX, to collect a number of common parameters and state variables. CERTC_CTX tracks the lists of currently registered service providers, a surrender context, and a random algorithm object for use in Crypto-C calls. Cert-C does not use a separate context for each service provider; instead, it has one context that knows about multiple service providers. Use the C_InitializeCertC() and C_FinalizeCertC() functions to manage the Cert-C context. Call C_InitializeCertC() before calling any other Cert-C function. This function allocates the Cert-C context and initializes the specified service providers and the internal fields of the context.

typedef POINTER CRL_ENTRIES_OBJ
 

Some CRL functions act on CRL_ENTRIES_OBJ objects instead of on CRL_OBJ objects. Use the CRL_ENTRIES_OBJ object to access CRL entries information stored in a CRL_OBJ. The CRL_ENTRIES_OBJ is the part of the CRL_OBJ object that actually contains the serial numbers, revocation times, and X.509 v3 CRL Entry extensions for each revoked certificate.

Cert-C does not provide a way to create or destroy a CRL_ENTRIES_OBJ. Instead, it must be accessed through the crlEntries field of the CRL_FIELDS data structure. To get a CRL_FIELDS structure for the examination of the CRL_ENTRIES_OBJ, call C_GetCRLFields(). To obtain the CRL_ENTRIES_OBJ, access the crlEntries field of the CRL_FIELDS structure.

Cert-C provides functions to add and delete entries in the CRL_ENTRIES_OBJ as well as to reset the CRL_ENTRIES_OBJ. After CRL entries are added or deleted, call C_SignCRL() to make the CRL valid again.

CRL-Entries-Object Functions

Use a Cert-C function to view or modify information in a CRL_ENTRIES_OBJ. When you call one of these functions, you cannot assume that the CRL_ENTRIES_OBJ points to any specific information. Some examples of the functions that Cert-C provides for manipulating a CRL entries object are listed in the following table:

Function Description
C_AddCRLEntry() Adds a CRL entry to a CRL_ENTRIES_OBJ .
C_GetCRLEntriesCount() Gets the number of entries in a CRL_ENTRIES_OBJ .
C_FindCRLEntryBySerialNumber() Finds a CRL entry given its serial number.
C_GetCRLEntry() Gets an entry from a CRL_ENTRIES_OBJ .
C_DeleteCRLEntry() Deletes an entry from a CRL_ENTRIES_OBJ .
C_ResetCRLEntries() Resets a CRL_ENTRIES_OBJ .

For more information on Cert-C objects, see Cert-C Objects.

typedef POINTER CRL_OBJ
 

Cert-C represents CRL information with a CRL_OBJ object. Use CRL objects to keep track of revoked certificates. A CRL object contains a list of CRL entries, each consisting of a certificate serial number and a revocation time. The serial numbers identify the certificates that were revoked by the CRL issuer. In addition, just like certificates, CRLs have an issuer, a validity period, and a signature.

If the CRL version is CRL_VERSION_2, then the CRL_OBJ must also contain an EXTENSIONS_OBJ, which represents X.509 v3 CRL extensions. Each CRL entry can also contain an EXTENSIONS_OBJ, which represents X.509 v3 CRL Entry extensions.

CRL-Object Functions

Use a Cert-C function to view or modify information in a CRL_OBJ object. When you call one of these functions, you cannot assume that the CRL_OBJ points to any specific information. Some examples of the functions that Cert-C provides for manipulating a CRL object are listed in the following table:

Function Description
C_CreateCRLObject() Creates a CRL object.
C_GetCRLDER() Gets the DER encoding of a CRL object.
C_SetCRLBER() Sets the BER encoding of a CRL object.
C_GetCRLFields() Gets a CRL_FIELDS structure corresponding to the CRL object.
C_SetCRLFields() Sets a CRL object with the given information in the given CRL_FIELDS structure.
C_GetCRLInnerDER() Gets the DER encoding of the "inner" portion of the CRL object, which does not contain the signature.
C_SetCRLInnerBER() Sets a CRL object to the BER encoding of the "inner" portion of the CRL, which does not contain the signature.
C_SignCRL() Signs a CRL object.
C_VerifyCRLSignature() Verifies the signature on a CRL object.
C_PrepareUnsignedCRLForIssuer()   Prepares an empty, unsigned CRL for an issuer.
C_DestroyCRLObject() Destroys a CRL object, freeing the memory that the CRL object occupied.

For more information on Cert-C objects, see Cert-C Objects.

typedef POINTER DB_ITERATOR
 

Use the database iterator handle, DB_ITERATOR, to sequentially retrieve records of a particular type from a database or a set of databases. Each of the C_SelectFirst*() functions initializes the DB_ITERATOR handle. Call the C_FreeIterator() function to set DB_ITERATOR to NULL_PTR. The C_SelectFirst*() and C_SelectNext*() function calls also free DB_ITERATOR when they encounter an error, or when all of the records of the requested type are retrieved.

typedef POINTER EXTENSIONS_OBJ
 

Cert-C represents X.509 v3 extensions with an EXTENSIONS_OBJ object. The EXTENSIONS_OBJ represents an extension set that contains one or more extension entries. Each extension entry is represented in two forms: a DER encoding and a list of values. The two forms provide equivalent information. The DER encoding of an extension entry is represented by an unsigned character string. The value list gives each value in the extension entry one at a time.

Each extension entry includes the extension type, its criticality, its handler, and a value list. There is only one extension entry for each extension type in the extensions object. The value list for some extension types can have only a single value at a time; the value list for other extension types can have multiple values at the same time.

When creating a CRL_OBJ or a CERT_OBJ by calling the C_CreateCRLObject() or C_CreateCertObject() function, respectively, Cert-C creates an EXTENSIONS_OBJ internally. It is accessed through the crlExtensions field of the CRL_FIELDS data structure, the crlEntryExtensions field of the CRL_ENTRY_INFO data structure, or the certExtensions field of the CERT_FIELDS data structure. An EXTENSIONS_OBJ can also be created explicitly (without creating a certificate or CRL object) by calling the C_CreateExtensionsObject() function.

Cert-C supports the following five X.509 v3 extensions-object types:

  • Certificate extensions (CERT_EXTENSIONS_OBJ)
  • CRL extensions (CRL_EXTENSIONS_OBJ)
  • CRL entry extensions (CRL_ENTRY_EXTENSIONS_OBJ)
  • OCSP request extensions (OCSP_REQUEST_EXTENSIONS_OBJ)
  • OCSP single-certificate extensions (OCSP_SINGLE_EXTENSIONS_OBJ)

Cert-C also supports application-defined extensions.

All extensions added to an extensions object must be of the same extensions-object type. Therefore, it is necessary to provide an extensions-object type when calling the following functions: C_CreateExtension(), C_SetExtensionBER(), C_SetEncodedExtensionValue(), and C_SetExtensionsObjectBER().

Extensions-Object Functions

Use a Cert-C function to view or modify information in an EXTENSIONS_OBJ. Before calling one of these functions, you cannot assume that the EXTENSIONS_OBJ points to any specific information. Some examples of the functions that Cert-C provides for manipulating an extensions object are listed in the following table:

Function Description
C_AddExtensionValue() Adds an extension value to an existing extension entry.
C_CompareExtension() Compares two extensions.
C_CompareExtensions() Compares two extensions objects (each representing a set of extensions).
C_CreateExtension() Creates a new extension entry in extensionsObject.
C_CreateExtensionsObject() Creates an extensionsObject of type extensionsObjectType.
C_DeleteExtensionValue() Deletes an extension value.
C_DestroyExtensionsObject() Destroys the extensionsObject by deleting all the extensions and their value lists.
C_FindExtensionByType() Finds an extension entry in the extensions object using the extension type.
C_GetEncodedExtensionValue()     Gets the encoded form of the extension's value(s).
C_GetExtensionCount() Gets the total number of extension types contained in an extensions object.
C_GetExtensionDER() Gets the DER encoding of an extension. The encoded value consists of the extension type, criticality, and the encoding of the extension’s value list.
C_GetExtensionInfo() Gets information about an extension, including associated values.
C_RegisterExtensionType() Registers an application-defined extension or overrides the default setting of a supported standard extension.
C_ResetExtensionsObject() Returns extensionsObject to the state it was in when it was created.
C_SelectCertByExtensions() Retrieves one or more certificates identified by the specified extensions and base subject name.
C_SetEncodedExtensionValue()     Sets the extension.
C_SetExtensionBER() Sets an extension with the given information.
C_SetExtensionsObjectBER() Sets extensionsObject with the new extensions.

For more information on Cert-C objects, see Cert-C Objects.

typedef struct GENERALIZED_TIME GENERALIZED_TIME
 

Stores a time value. The time value is represented in the Generalized Time format, defined in the X.680 standard, ASN.1. The GENERALIZED_TIME structure is used in the INVALID_DATE, OCSP_EVIDENCE, PKI_MSG_FIELDS, and PRIVATE_KEY_USAGE_PERIOD structures, and with the C_DEREncodeGeneralizedTime() and C_BERDecodeGeneralizedTime() functions.

For example, the following statements input the UTC time of 6 minutes, 27.000003 seconds after 9:00 P.M. on November 6, 1985 (the X.680 UTC time is 19851106210627.000003Z).

    GENERALIZED_TIME generalizedTime;

    generalizedTime.year = 1985;
    generalizedTime.month = 11;
    generalizedTime.day = 6;
    generalizedTime.hour = 21;
    generalizedTime.minute = 6;
    generalizedTime.second = 27;
    generalizedTime.microSecond = 3;
    generalizedTime.timeZone = 0;

typedef POINTER LIST_OBJ
 

Use the LIST_OBJ object to store and pass a collection of abstract data types, including types defined by Cert-C and types defined by your application. The list object is a generic container for multiple values; the values can be of the same type or of different types. For example:

  • Cert-C list objects: Cert-C uses a list object to store an extension's value list. It also uses a list object to store extension values that consist of multiple components, such as the Certificate Policies extension.

  • Application-defined list objects: An application can use a list object as a container for any kind of value. Each value can even be defined by a different data structure, provided that the LIST_OBJ_ENTRY_HANDLER was set up correctly.
Cert-C provides functions that you can use to maintain list objects of common Cert-C data types. For example, it provides a set of functions to maintain list objects that contain ITEM structures, CERT_OBJ objects, and CRL_OBJ objects; these functions are declared in the certlist.h header file. As another example, a set of functions in the cms.h header file maintains list objects that contain RECIPIENT_INFO structures. Before creating any functions to manage lists of Cert-C objects or structures, check the description of the object or structure to see whether the list management functions are already provided by Cert-C.

List-Object Functions

Use a Cert-C function to view or modify information in a LIST_OBJ object. For application-defined data types, provide a LIST_OBJ_ENTRY_HANDLER. Some examples of the functions that Cert-C provides for adding an entry, deleting an entry, searching for an entry, and so forth, are given in the following table:

Function Description
C_CreateListObject() Creates a list object.
C_DestroyListObject() Destroys the list object, freeing all occupied memory.
C_GetListObjectCount() Gets the number of entries in the list object.
C_AddListObjectEntry() Adds an entry to the list object.
C_InsertListObjectEntry() Inserts an entry to the list object at a given position.
C_GetListObjectEntry() Gets an entry from the list object.
C_DeleteListObjectEntry()     Destroys an entry in the list object, freeing all memory occupied by the entry.
C_ResetListObject() Destroys all entries in the list object, freeing all memory occupied by these entries.

For more information on Cert-C objects, see Cert-C Objects.

typedef POINTER NAME_OBJ
 

Cert-C uses a NAME_OBJ object to represent the names of entities involved in privacy enhancement. A name object contains a distinguished name (DN), as defined in the X.500 standard. The DN is represented in two forms: as a DER encoding and as a list of AVAs. The two forms provide equivalent information.

An X.500-defined DN specifies a path through an X.500-defined directory tree. The DER encoding is a string of unsigned characters representing the path; the AVA list contains the AVAs that define each level traversed by the path through the tree. Each level involves one or more AVAs; the AVA list indicates whether successive AVAs are part of the same level or different levels. There is no significance to the order of AVAs within a level. Furthermore, some environments require that an AVA of any type appears only once within a level. However, Cert-C does not enforce this requirement.

The following figure shows a complete DN for an employee named Alice Algorithm. The first level gives the DN for the United States. The second level and the first level together give the DN for RSA Security, in the United States. All three levels together give the DN for Alice Algorithm, a cryptographic systems programmer at RSA Security, in the United States. Because they occur within the same level, there is no significance to the order in which Alice's common name and title are specified.



Name-Object Functions

Use a Cert-C function to view or modify information in a NAME_OBJ object. When you call one of these functions, you cannot assume that the NAME_OBJ object points to any specific information. Some examples of the functions that Cert-C provides for manipulating a name object are listed in the following table:

Function Description
C_CreateNameObject() Creates a new name object.
C_GetNameDER() Gets a pointer to the DER encoding that represents the value of the name.
C_SetNameBER() Modifies the value of a name to a given BER encoding.
C_IsSubjectSubordinateToIssuer()   Checks whether the subject is subordinate to the issuer.
C_ResetNameObject() Deletes all the name AVA entries in the name object and frees all the associated memory.
C_DestroyNameObject() Deletes the name object and deallocates all memory blocks associated with it.

AVA-List Functions

Every DN is comprised of one or more levels and each level can have one or more AVAs. Each AVA has a type, such as AT_ORGANIZATION, and a value, such as the name of the organization. The value also has a tag, which is usually VT_PRINTABLE_STRING; but the value can have a different tag if it can be represented in a form other than a printable string.

A typical application calls C_GetNameAVACount() to get the number of AVAs in an AVA list. Next, the application calls C_GetNameAVA() to obtain each AVA in a name that is being displayed. Then the application calls C_AddNameAVA() to construct a new name or add lower levels to an existing name prefix.

Some of the functions that Cert-C provides for accessing or modifying a name object’s AVA list are listed in the following table:

Function Description
C_GetNameAVACount()     Gets the number of attribute-value assertions in a name object’s AVA list.
C_GetNameAVA() Gets a specific attribute-value assertion from a name object’s AVA list.
C_AddNameAVA() Adds an attribute-value assertion to a name object’s AVA list.

Attribute Types and Constraints

Cert-C defines a number of attribute types. For some attribute types, Cert-C places some constraints on the corresponding attribute values and their tags. For additional attributes information, see Attribute Types and Constraints. This section lists the attribute types and lengths (given as variables that the application can reference), the attribute descriptions, and the attribute value and length constraints.

For more information on Cert-C objects, see Cert-C Objects.

AVA Example

The following example code shows a way to construct the DN for the employee Alice Algorithm described earlier:

NAME_OBJ nameObject = (NAME_OBJ)NULL_PTR;
C_CreateNameObject (&nameObject);
C_AddNameAVA
  (nameObject, AT_COUNTRY, AT_COUNTRY_LEN,
  VT_PRINTABLE_STRING, "US", 2, 1, NULL_PTR);

C_AddNameAVA
  (nameObject, AT_ORGANIZATION, AT_ORGANIZATION_LEN,
  VT_PRINTABLE_STRING, "RSA Security",
  12, 1, NULL_PTR);
C_AddNameAVA
  (nameObject, AT_COMMON_NAME, AT_COMMON_NAME_LEN,
  VT_PRINTABLE_STRING, "Alice Algorithm", 15, 1,
  NULL_PTR);
C_AddNameAVA
  (nameObject, AT_TITLE, AT_TITLE_LEN,
  VT_PRINTABLE_STRING, "Cryptographic Systems Programmer",
  32, 0, NULL_PTR);

typedef POINTER SERVICE
 

A service handle. This service handle can be used as an input parameter for some Cert-C functions. It can be bound to the service handle to a single service-provider instance, or to a sequence of service-provider instances, all of the same type. Use the C_BindService() and C_BindServices() functions to create a SERVICE handle. These functions bind one or more service providers to the handle. Cert-C functions that target a specific service provider or set of service providers have a SERVICE handle as a parameter.



RSA BSAFE® Cert-C 2.7 API Reference