RSA Security logo

RSA BSAFE Cert-C
API Reference

pkcs11db.h File Reference

This file defines the public interface to the PKCS #11 database service provider, which enables access to certificate and private-key token objects.

It does not provide access to other PKCS #11 functionality, such as key generation, encryption, signing, and so on.

#include "service.h"
#include "bsafe.h"

Go to the source code of this file.

Data Structures

 PKCS11_INIT_PARAMS
 Passes token initialization information to the Cert-C PKCS #11 Database service provider initialization functions. More...


Typedefs

typedef PKCS11_INIT_PARAMS PKCS11_INIT_PARAMS
 Passes token initialization information to the Cert-C PKCS #11 Database service provider initialization functions. More...


Functions

int S_InitializePKCS11DB (CERTC_CTX ctx, POINTER params, SERVICE_FUNCS *funcs, POINTER *phP11DB)
 Never call the S_InitializePKCS11DB() function directly; instead, to initialize or register the Cert-C PKCS #11 Database Service Provider, call the C_InitializeCertC() or C_RegisterService() function. More...

int S_GetPKCS11Error (POINTER dbHandle, int *pLastLibErr)
 Call the S_GetPKCS11Error() function to retrieve an actual PKCS #11 error code. More...

Typedef Documentation

typedef struct PKCS11_INIT_PARAMS PKCS11_INIT_PARAMS
 

Passes token initialization information to the Cert-C PKCS #11 Database service provider initialization functions. When you use C_InitializeCertC() to register the Cert-C PKCS #11 Database service provider, the corresponding handlerParams should point to a PKCS11_INIT_PARAMS structure. Or, if you use C_RegisterService() to register the Cert-C PKCS #11 Database service provider, the corresponding params should point to a PKCS11_INIT_PARAMS structure. You can also use this structure to pass information back to either the application for use in subsequent SPI calls, or to the Crypto-C B_CreateHardwareChooser function.

Parameters:
pPKCS11Info This is both an input and output parameter. As an input parameter, it is a pointer to an initialized B_PKCS11_SESSION structure. This structure contains values for this service provider to establish a session to the token.

As an output parameter, it contains PKCS #11 library, token, and session information used during service-provider initialization. This structure can also be used when initializing the Crypto-C hardware chooser or when initializing the Cert-C Default Cryptographic service provider.

For more information on B_PKCS11_SESSION, see the "B_PKCS11_SESSION Values" section of S_InitializePKCS11DB(), Cert-C Default Cryptographic service provider, and also the Crypto-C Reference Manual.
dbHandle This output parameter is a copy of the service provider's context handle for this database. An application can use this value in later calls to other Cert-C PKCS #11 Database service provider S_*() functions.

Function Documentation

int S_GetPKCS11Error (  POINTER    dbHandle,
int *    pLastLibErr
)  ;
 

Call the S_GetPKCS11Error() function to retrieve an actual PKCS #11 error code. It is also possible to call this function after getting a non-service-provider-specific Cert-C error code to help determine the underlying error, if there is one.

The PKCS #11 library functions, which underlie each of the service provider SPI functions, can return many very specific and obscure PKCS #11 error codes. Many of these errors are mapped to existing, reasonably equivalent Cert-C error codes that clearly indicate the problem. There are Cert-C error codes defined specifically for this service provider to augment the current values (they relate mostly to problems during initialization). One of these Cert-C error codes, E_PKCS11DB_LIBRARY_ERROR, is a generic PKCS #11 service-provider error code. For more information on Cert-C error codes, see Cert-C Error Codes.

Parameters:
dbHandle This input parameter points to this instance of the Cert-C PKCS #11 Database Service Provider handle.
pLastLibErr This output parameter points to the most recently cached PKCS #11 library error.
Returns:
Returns an error code as defined by the PKCS #11 specification.
Note: The PKCS #11 error returned by this function is only the most recent error cached in the database context. It is unspecified which PKCS #11 result is cached if multiple PKCS #11 library calls are used to implement a single SPI.

int S_InitializePKCS11DB (  CERTC_CTX    ctx,
POINTER    params,
SERVICE_FUNCS *    funcs,
POINTER *    phP11DB
)  ;
 

Never call the S_InitializePKCS11DB() function directly; instead, to initialize or register the Cert-C PKCS #11 Database Service Provider, call the C_InitializeCertC() or C_RegisterService() function. Both functions take SERVICE_HANDLER and a POINTER to a parameters structure as parameters; SERVICE_HANDLER's Initialize parameter points to the S_InitializePKCS11DB() function, and the corresponding POINTER must point to a PKCS11_INIT_PARAMS structure.

Cert-C uses S_InitializePKCS11DB() to initialize the Cert-C PKCS #11 Database service provider functions and initialization parameters. S_InitializePKCS11DB() stores pointers to the Cert-C PKCS #11 Database service provider functions in funcs's db member, which is a DB_FUNCS structure. S_InitializePKCS11DB() uses the Cert-C PKCS #11 Database service-provider initialization parameters in params, which points to the PKCS11_INIT_PARAMS structure.

Note: This function, unlike initialization functions for the other Cert-C service providers, can modify the values in the params structure (PKCS11_INIT_PARAMS.PKCS11Info) so that the values of B_PKCS11_SESSION can be returned to the application and shared with other service providers.

Each registered Cert-C PKCS #11 Database Service Provider corresponds to one open and authenticated read-write session to a token. No error is returned if only a read-only session can be opened instead of a read-write session. The token must be present in the slot during service-provider registration. It must be in the same slot during subsequent database calls (until the service provider is unregistered).

If using a single session between the Cert-C PKCS #11 Database service provider and the cryptographic service provider, it does not matter which of the two service providers are initialized first. The service provider that is initialized first establishes the session; then the other service provider can be initialized with the values (B_PKCS11_SESSION's values) just obtained. Some database calls require the cryptographic service provider to be registered before being called, but this does not affect the initialization order of the service providers. It is very important that the Cert-C PKCS #11 Database service provider is initialized to access the same token as is specified for the Crypto-C chooser. This can be accomplished by sharing a common B_PKCS11_SESSION structure between this service provider and Crypto-C.

It is also possible to use a separate session for each service provider. However, in this case, it is the application's responsibility to ensure the two sessions refer to the same token (otherwise, objects referenced in one session will be meaningless to the other). If separate structures are used, then it is essential that the application supplies identical initialization information to both the Cert-C PKCS #11 Database service provider and Crypto-C.

B_PKCS11_SESSION Values

The following table describes B_PKCS11_SESSION's values and how they relate to the Cert-C PKCS #11 Database Service Provider. For more information, see B_PKCS11_SESSION, and the Crypto-C Reference Manual.

MemberDescription
sessionHandleReference to a session with a token. (in/out)
cryptokiFunctionsPointer to an array of functions (as returned by the PKCS #11 library). (in/out)
libraryNameA nul-terminated string specifying a vendor's PKCS #11 shared library (a .dll file on Windows) for explicit runtime loading. A NULL_PTR value indicates the library is statically linked or implicitly linked and loaded at application startup time. This value is ignored if sessionHandle and cryptokiFunctions are already provided on input. (in)
tokenLabelSpecifies the token label to open a session to. This value must match the label on the target token or an error will be returned. If tokenLabel.data is NULL_PTR, then the token in the lowest numbered slot which accepts the user-supplied PIN is the one accessed, and the token's label is returned. This value is ignored if sessionHandle is provided on input. (in)
passPhraseSpecifies the secret passphrase (PIN) needed to log in and obtain an authenticated session (to access private token objects). This value is ignored if sessionHandle is provided on input. (in)
surrenderContextSurrender context information (application-supplied callback) to pass on to the PKCS #11 library during session initialization. (in)

The service-provider initialization process differs depending on which B_PKCS11_SESSION structure values are set by the application before service-provider registration. This service provider will do one of the following:

  • Establish one read-write session for each registered service provider using the application-supplied token and logon information, and then modify the sessionHandle and cryptokiFunctions values with the established session information. An application can then use the resulting B_PKCS11_SESSION structure to register the cryptographic service provider or in a call to B_CreateHardwareChooser.

  • Use an existing session as identified by the sessionHandle and cryptokiFunctions values of a B_PKCS11_SESSION structure. A structure with valid values may already be available if your application has previously initialized the cryptographic service provider, called B_CreateHardwareChooser, or even made its own PKCS #11 function calls.
Currently, if the application sets B_PKCS11_SESSION.surrenderContext to NULL_PTR, then notification information is not passed to the PKCS #11 library. However, a notification callback function can be defined in an application. The PKCS #11 library can call this function during certain lengthy operations. Use surrenderContext to specify the callback function and one application supplied value to the PKCS #11 library during session initialization.

Note: Although Crypto-C associates a surrender context with an individual function call, PKCS #11 only associates a surrender context with a session. surrenderContext's Surrender function pointer must point to a function that matches the PKCS #11 CK_NOTIFY calling interface type, defined as follows: surrenderContext.handle is passed to the callback function as the pApplication parameter. See the PKCS #11 2.01 specification for a description of the hSession and event parameters, appropriate return values, and more general information about notification.

sessionHandle and cryptokiFunctions Values

The actual service-provider initialization algorithm is identical to the Crypto-C algorithm used in B_CreateHardwareChooser. The input values of sessionHandle and cryptokiFunctions yield four basic initialization cases:

  1. sessionHandle and cryptokiFunctions are both non-zero.

    This is a likely condition if the application wants this service provider to use an existing session, perhaps one already established for the cryptographic service provider or directly using B_CreateHardwareChooser.

    • The service provider will copy the given function list and session handle and use them to access the token during database calls.
    • All other values in the B_PKCS11_SESSION structure are ignored and not modified in any way.
    • The service provider is not responsible for closing the session.


  2. sessionHandle and cryptokiFunctions are both zero (or NULL_PTR).

    This is a likely condition if the session is extablished by the service provider first, and later the cryptographic service provider or Crypto-C also uses it.

    • The service provider explicitly loads the library indicated by libraryName. An error is returned if libraryName is NULL_PTR or the library file cannot be found.
    • The service provider then gets the list of Cryptoki functions from the library and modifies cryptokiFunctions and returns it to the application.

    • Service provider initialization then proceeds as in case 3.


  3. cryptokiFunctions is non-0 (non-zero) and sessionHandle is 0 (zero) (or NULL_PTR).

    This is a likely condition if the application specifies this service provider to establish the session to a statically linked (or implicitly loaded) library. The application will be responsible for obtaining the Cryptoki function list; for example, it must make one PKCS #11 function call to get the function list.

    • A session is opened to a token (possibly using tokenLabel) and sessionHandle is modified with the new session handle for return to the application.
    • If the tokenLabel.data is NULL_PTR, then the service provider sequentially scans all slots for a token, beginning with the lowest numbered slot, and opens a session to the first token that accepts the user-specified PIN. The service provider allocates memory for the token's label and modifies tokenLabel.data to point to that memory. This memory is now owned by the service provider and the application can copy the label value but must not free the allocated memory.
    • Log on to the token using passPhrase.
    • The resulting modified B_PKCS11_SESSION structure is in a state suitable for passing to Crypto-C or the cryptographic service provider without any further modification by the application.
    • The service provider is responsible for closing the session (for example, during service-provider unregistration or Cert-C finalization).


  4. sessionHandle is non-0 (non-zero) and cryptokiFunctions is 0 (zero) (or NULL_PTR).

    • The service provider returns an error. No session is established; the B_PKCS11_SESSION structure is unmodified.
Parameters:
ctx This input parameter points to an initialized Cert-C context handle.
params This input parameter points to a PKCS11_INIT_PARAMS structure that contains the Cert-C PKCS #11 Database service provider initialization parameters. Some of the values in params may be modified during initialization.
funcs This is both an input and output parameter. As an input parameter, it points to an allocated but uninitialized SERVICE_FUNCS union. As an output parameter, it points to the initialized Cert-C PKCS #11 Database Service Provider-specific functions in the db member of SERVICE_FUNCS, which is a DB_FUNCS structure.
phP11DB This output parameter points to this instance of the Cert-C PKCS #11 Database Service Provider handle.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.
Note: Specific PKCS #11 error values (and device errors) are logged.


RSA BSAFE® Cert-C 2.7 API Reference