RSA BSAFE Cert-C API Reference

Cert-C PKCS #11 Database Service Provider

The Cert-C PKCS #11 Database service provider implements the database interface to the object handling services of a PKCS #11 v2.x library and token-supporting authenticated read-write access to certificates and private-keys.

Additional PKCS #11 functionality can be provided through other service providers; for example, cryptographic services can be provided through a cryptographic service provider. (The Cert-C Default Cryptographic service provider can be used when initialized using the S_InitializeDefaultCSP2 initialization function.) No security officer services are enabled through this service provider; for example, initializing the token.

This service provider's functionality is subject to the following limitations regarding objects, sessions, and accessibility:

Token Objects

The following token objects are supported:

• Certificates: a public object
• Private-keys: a private object that requires users to log in using a PIN

The following token objects are not supported:

• CRLs: not directly supported by PKCS #11
• Public keys: supported by PKCS #11, but not directly supported by the Cert-C database API
• Secret (symmetric) keys: Cert-C or application generates them as needed
• General data objects: supported by PKCS #11, but not directly supported by the Cert-C API

PKCS #11 Services

The following PKCS #11 services are supported:

• Authenticated read-write access to certificates
• Authenticated read-write access to private keys

The following PKCS #11 services are not supported:

• Encryption and decryption
• Message digesting
• Signing, MACing, and verifying
• Key management (for example, generating a key pair)
• Random number generation
• Security officer services

Many of these functions are supported by Crypto-C, either directly or through the Cert-C Default Cryptographic service provider.

PKCS #11 represents certificates and keys as objects stored on a token residing in a slot. A token can be an actual physical storage device (for example, a smartcard) or implemented completely in software. Users access the objects on a token by opening a session to the token that iseither read-only or read-write. Sessions initially have access only to public objects such as certificates and public keys, and gain access to private objects-for example private-keys-by logging in and being authentication with a user-supplied PIN value.

During query operations, a certificate's complete BER value is returned to the application; this is the same for all the Cert-C database service providers. However, private keys are handled differently. This is because private-key confidentiality is an intrinsic part of PKCS #11.

During insert operations, this service provider creates key objects on the token with the most restrictive default attributes to maintain the greatest confidentiality possible. Similarly, an existing key object might have restrictions that prevent an application from obtaining various key component values during a query.

As a result of a query, this service provider obtains an abstract reference to the entire private-key object, and then sets this reference into the B_KEY_OBJ object returned to the application. This reference information is set using the KI_Token info type as defined in Crypto-C. For information about the actual KI_Token internalKey format, see the RSA BSAFE Crypto-C Developer's Guide. The application never has to deal with specific PKCS #11 object references-only Crypto-C's B_KEY_OBJ.

Private keys that are returned to the application must be passed to Crypto-C along with a properly initialized chooser; otherwise, Crypto-C cannot make use of the key. It is very important that the Cert-C PKCS #11 Database service provider is initialized to access the same token specified for the Crypto-C chooser when it was initialized. This can be accomplished by sharing a common B_PKCS11_SESSION structure between this service provider and Crypto-C. For information about this structure, see the RSA BSAFE Crypto-C Reference. If separate structures (and possibly different session handles) are used, then it is essential the application supplies identical initialization information to both the Cert-C PKCS #11 Database service provider and Crypto-C.

This service provider was compiled with RSA Laboratories version 2.6 header files (pkcs11.h, pkcs11t.h, and pkcs11f.h) and a macro definition file called p11cc.h. These files are located in Cert-C's top-level include directory. Verify that these header files are compatible with the chosen vendor's PKCS #11 API library. It might be necessary to modify or replace these files if this service provider does not work with the vendor's PKCS #11 API library. If these files are modified, recompile the Cert-C PKCS #11 Database service provider.

The data structures used with this service provider are DB_FUNCS and PKCS11_INIT_PARAMS. This service provider uses all of the DB_FUNCS functions except SelectCertByAttributes and those functions that refer to CRLs.

Cert-C PKCS #11 Database service provider's implementation of these functions does not differ from the API implementation, except with regards to the attributes used. The specific attributes that are required for each function are described later in this section.

Note: To use the Cert-C PKCS #11 Database service provider in an application where static linking is chosen, the application must link with the vendor's static library file. Otherwise, if dynamic linking is chosen, the vendor's library file to link (a dll file on Windows or a shared library file on Unix) must be specified during service-provider registration.