	RSA BSAFE Cert-C	Certificate Components for C
		Crypto-C 6.2.1 Developer's Guide
		Search

basetype.h File Reference

This file contains 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 struct BIT_STRING

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

typedef struct 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.

typedef struct BIT_STRING BIT_STRING

A low-level structure that holds an ordered sequence of bits. This structure is used with C_BERDecodeBitString(), C_DEREncodeBitString() and C_DEREncodeNamedBitString(). 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.

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.

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.

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 C_CreateExtensionsObject().
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().

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 C_DEREncodeGeneralizedTime() and C_BERDecodeGeneralizedTime().
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.

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.

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.

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 struct	BIT_STRING
	A low-level structure that holds an ordered sequence of bits. More...
typedef struct	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...