General-Purpose Functions
C_Initialize
The Netscape Security Library calls C_Initialize
on startup or when it loads a new module. The Netscape Security Library always passes NULL
, as required by the PKCS #11 specification, in the single C_Initialize
parameter pReserved
.
C_Finalize
The Netscape Security Library calls C_Finalize
on shutdown and whenever it unloads a module.
C_GetFunctionList
The Netscape Security Library calls C_GetFunctionList
on startup or when it loads a new module. The function list returned should include all the PKCS 2.0 function calls. If you don't implement a function, you should still provide a stub that returns CKR_FUNCTION_NOT_SUPPORTED
.
C_GetInfo
The Netscape Security Library calls C_GetInfo
on startup or when it loads a new module. The version numbers, manufacturer IDs, and so on are displayed when the user views the information. The supplied library names are used as the default library names; currently, these names should not include any double quotation marks. (This is more restrictive than PKCS 2.0 and may change in future versions of Communicator.)
Slot and Token Management
C_GetSlotList
The Netscape Security Library calls C_GetSlotList
on startup or when it loads a new module, requests all the module's slots, and keeps track of the list from that point on. The slots are expected to remain static: that is, the module never has more slots or fewer slots than the number on the original list.
C_GetSlotInfo
The Netscape Security Library calls C_GetSlotInfo
on startup or when it loads a new module and reads in the information that can be viewed on the slot information page. If the CKF_REMOVABLE_DEVICE
flag is set, the Netscape Security Library also calls C_GetSlotInfo
whenever it looks up slots to make sure the token is present. If the CKF_REMOVABLE_DEVICE
flag is not set, the Netscape Security Library uses that token information without checking again.
If the CKF_REMOVABLE_DEVICE
flag is not set, the CKF_TOKEN_PRESENT
flag must be set, or else the Netscape Security Library marks the slot as bad and will never use it.
The Netscape Security Library doesn't currently use the CKF_HW_SLOT
flag.
C_GetTokenInfo
If a token is a permanent device (that is, if the CKF_REMOVABLE_DEVICE
flag is not set), the Netscape Security Library calls C_GetTokenInfo
only on startup or when it loads a new module. If the token is a removable device, the Netscape Security Library may call C_GetTokenInfo
anytime it's looking for a new token to check whether the token is write protected, whether it can generate random numbers, and so on.
The Netscape Security Library expects CK_TOKEN_INFO.label
to contain the name of the token.
If the CKF_WRITE_PROTECTED
flag is set, the Netscape Security Library won't use the token to generate keys.
The Netscape Security Library interprets the combination of the CKF_LOGIN_REQUIRED
and CKF_USER_PIN_INITIALIZED
flags as shown in Table 1.1.
C_GetMechanismList
The Netscape Security Library calls C_GetMechanismList
fairly frequently to identify the mechanisms supported by a token.
C_GetMechanismInfo
The Netscape Security Library currently doesn't call C_GetMechanismInfo
. This function may be called in the future, so you should implement it anyway.
C_InitToken
The Netscape Security Library never calls C_InitToken
.
C_InitPIN
The Netscape Security Library calls C_InitPIN
only in the key generation case, as noted in this document under C_GetTokenInfo, when CFK_LOGIN_REQUIRED = TRUE
and CFK_USER_PIN_INITIALIZED = FALSE
.
C_SetPIN
Called only in the key generation case, as noted in this document under
C_GetTokenInfo, when CFK_LOGIN_REQUIRED = TRUE
and CFK_USER_PIN_INITIALIZED = FALSE
.
Session Management
C_OpenSession
The Netscape Security Library calls C_OpenSession
whenever it initializes a token and keeps the session open as long as possible. The Netscape Security Library almost never closes a session after it finishes doing something with a token. It uses a single session for all single-part RSA operations such as logging in, logging out, signing, verifying, generating keys, wrapping keys, and so on.
The Netscape Security Library opens a separate session for each part of a multipart encryption (bulk encryption). If it runs out of sessions, it uses the initial session for saves and restores.
C_CloseSession
The Netscape Security Library calls C_CloseSession
to close sessions created for bulk encryption.
C_CloseAllSessions
The Netscape Security Library may call C_CloseAllSessions
when it closes down a slot.
C_GetSessionInfo
The Netscape Security Library calls C_GetSessionInfo
frequently.
If a token has been removed during a session, C_GetSessionInfo
should return either CKR_SESSION_CLOSED
or CKR_SESSION_HANDLE_INVALID
. If a token has been removed and then the same or another token is inserted, C_GetSessionInfo
should return CKR_SESSION_HANDLE_INVALID
.
C_Login
The Netscape Security Library calls C_Login
on a token's initial session whenever CKF_LOGIN_REQUIRED
is TRUE
and the user state indicates that the user isn't logged in.
C_Logout
The Netscape Security Library calls C_Logout
on a token's initial session
C_CreateObject
when loading new private keys and new certificates into a token. Typically, the Netscape Security Library uses C_CreateObject
for creating a new private key if PKCS #12 is operating or if your writable token doesn't support C_GenerateKeyPair
. Currently PKCS #12 isn't allowed to import onto a token.
The Netscape Security Library also uses C_CreateObject
to create new session keys. The Netscape Security Library sometimes loads raw key data and builds a key from that.
The Netscape Security Library will be doing more and more session key generation on tokens in the future. It's also possible for the Netscape Security Library to load a key if the private key that decrypted the key is located on a different slot. For example, if a particular token can't do DES encryption, the Netscape Security Library decrypts the key, then copies it over to the token that can do DES encryption.
The Netscape Security Library creates certificates as token objects. It loads the token object only if the private key for that certificate exists on the token and was generated by the Netscape Security Library. All the fields defined by PKCS #11 for certificates are set.
The Netscape Security Library also sets the CKA_ID
and CKA_LABEL
attributes for the token. Currently, the CKA_ID
attribute is set to the modulus for RSA or to the public value on DSA. The Netscape Security Library may hash this value in the future. In either case, the Netscape Security Library does set the CKA_ID
attribute and expects it to remain the same. If a certificate is loaded, the value of the certificate's CKA_ID
attribute must match the value of the CKA_ID
attribute for the corresponding private key, and the value of the certificate's CKA_LABEL
attribute must also match the value of the CKA_LABEL
attribute for the private key. For private keys that don't include certificates, the Netscape Security Library doesn't set the CKA_LABEL
attribute, or sets it to NULL
, until it receives the certificate.
C_CopyObject
but may sometimes do so for non-token private keys.
C_DestroyObject
to destroy certificates and keys on tokens.
C_GetObjectSize
.
C_GetAttributeValue
to get the value of attributes for both single objects and multiple objects. This is useful for extracting public keys, nonsecret bulk keys, and so on.
C_SetAttributeValue
to change labels on private keys.
CKA_ID
or CKA_LABEL
. These values must match the equivalent values for related keys and certificates and must be unique among key pairs on a given token.
The Netscape Security Library also looks up certificates by CK_ISSUER
and CK_SERIAL
. If those fields aren't set on the token, S/MIME won't work.
External key tokens need to support C_Decrypt
and C_Sign
. If they have a read/write value and can't generate a key pair, the Netscape Security Library uses its own C_GenerateKeyPair
and loads the key with C_CreateObject
.
Signing tokens just need to support C_Sign
and possibly C_GenerateKeyPair
.
In addition to C_Sign
and C_GenerateKeyPair
, signing and decryption tokens should also support C_Decrypt
and, optionally, C_UnwrapKey
.
Multipurpose tokens should support all the functions listed in Table 1.2, except that C_WrapKey
and C_UnwrapKey
are optional. The Netscape Security Library always attempts to use these two functions but uses C_Encrypt
and C_Decrypt
instead if C_WrapKey
and C_UnwrapKey
aren't implemented.
Installation
You can install your module in any convenient location on the user's hard disk, but you must tell the user to type the module name and location in the Cryptographic Modules portion of the Communicator Security Info window. To do so, the user should follow these steps:
C_InitPIN
, C_SetPIN
, or C_GenerateKeyPair
, you must support simultaneous read-only and read/write sessions.
C_SeedRandom
, C_GenerateRandom
, and C_Digest
(for SHA, MD5, and MD2). If your token requires authentication before executing these functions, your token cannot provide the default implementation for them. (You can still use your token for other default functions.) Communicator 4.0 does not support replacement of default functions. Later versions will provide such support.
C_CreateObject
, it writes the entire set of RSA components. It expects to be able to read back the modulus and the value of the CKA_ID
attribute. It also expects to be able to set the label and the subject on the key after creating it.
CKA-ID
). It doesn't matter how the key ID is generated, as long as it is unique for the token and maps to a single certificate.
The only exception to this requirement involves key generation for a new certificate, during which an orphan key waits for a brief time for a matching certificate. The Netscape Security Library uses part of the public key (modulus for RSA, value for DSA) as the key ID during this time.
Netscape Security Library doesn't currently use token public keys, but if it ever does, it would expect the value of the CKA_ID
attribute to be associated with a single certificate.