PKCS11¶
The main goal of the PKCS#11-interface of the Open eCard App is to provide the functionality, which is required by Mozilla’s Firefox browser.
Mozilla’s overall crypto architecture as taken from [Grif09] is depicted in Figure 1.
Figure 1: Mozilla's Cryptographic Architecture ([Grif09], p. 22)
The important part is the usage of the PKCS#11-interface by the “Core Crypto Code” within the “Network Security Services” as explained in [NSS-PKCS#11].
As this browser is a successor of Netscape’s Communicator it is expected that the PKCS#11-usage in today’s Firefox is similar to the PKCS#11-usage explained in [NSS-PKCS#11].
Required Functions¶
General-Purpose Functions¶
Among the general-purpose functions defined in Section 11.4 of [NSS-PKCS#11] the following functions need to be supported:
C_Initialize
C_Finalize
C_GetFunctionList
C_GetInfo
C_Initialize
As explained in [NSS-PKCS#11] 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
. This function will use the IFD-function EstablishContext
to initialize the IFD-module.
C_Finalize
As explained in [NSS-PKCS#11] the Netscape Security Library calls C_Finalize
on shutdown and whenever it unloads a module.
This function will use the IFD-function ReleaseContext
to initialize the IFD-module.
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 function will only return static information and does not involve any IFD-function.
C_GetFunctionList
As explained in [NSS-PKCS#11] the Netscape Security Library calls C_GetFunctionList
on startup or when it loads a new module. In [NSS-PKCS#11] it is recommended that for a not implemented function there should at least be a stub that returns CKR_FUNCTION_NOT_SUPPORTED
.
This function will only return static information and does not involve any IFD-function.
Slot and Token Management¶
C_GetSlotList
As explained in [NSS-PKCS#11] 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. This means that the function C_WaitForSlotEvent
is not used by the Netscape Security Library.
This function uses the following IFD-functions:
ListIFDs
GetIFDCapabilities
GetStatus
C_GetSlotInfo
As explained in [NSS-PKCS#11] 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.
For a particular slot this function returns the following structure:
typedef struct CK_SLOT_INFO {
CK_UTF8CHAR slotDescription[64];
CK_UTF8CHAR manufacturerID[32];
CK_FLAGS flags;
CK_VERSION hardwareVersion;
CK_VERSION firmwareVersion;
} CK_SLOT_INFO;
Listing 1:
CK_SLOT_INFO
structure
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 the following table.
CFK_LOGIN_REQUIRED |
CFK_USER_PIN_INITIALIZED |
Netscape Security Library assumes that: |
---|---|---|
FALSE |
FALSE |
This is a general access device. The Netscape Security Library will use it without prompting the user for a PIN. |
TRUE |
FALSE |
The device is uninitialized. The Netscape Security Library attempts to initialize the device only if it needs to generate a key or needs to set the user PIN. The Netscape Security Library calls C_InitPIN to initialize the device and set the user PIN; if these calls are successful, the key is generated and at that point the CFK_USER_PIN_INITIALIZED flag should change from FALSE to TRUE . |
FALSE |
TRUE |
This is a general access device that can have a PIN set on it. Because it's a general access device, the Netscape Security Library never prompts for the PIN, even though it's possible to set a PIN with C_SetPIN . If the PIN is set successfully, the CFK_LOGIN_REQUIRED flag should change to TRUE . The Netscape Security Library uses this combination of flags for its internal token when the key database password is NULL . These are not standard PKCS #11 semantics; they are intended for the Netscape Security Library's internal use only. |
TRUE |
TRUE |
The device has been initialized and requires authentication. The Netscape Security Library checks whether the user is logged on, and if not prompts the user for a PIN. |
Table 1: Interpretation of flags ([NSS-PKCS#11], Table 1.1)
For a typical signature card in operational mode the two flags are TRUE
. On the other side the two flags for the private key on the eGK, which is used for card2card-authentication, are both FALSE
.
This function returns the CK_TOKEN_INFO
struct for a specific token.
typedef struct CK_TOKEN_INFO {
CK_UTF8CHAR label[32];
CK_UTF8CHAR manufacturerID[32];
CK_UTF8CHAR model[16];
CK_CHAR serialNumber[16];
CK_FLAGS flags;
CK_ULONG ulMaxSessionCount;
CK_ULONG ulSessionCount;
CK_ULONG ulMaxRwSessionCount;
CK_ULONG ulRwSessionCount;
CK_ULONG ulMaxPinLen;
CK_ULONG ulMinPinLen;
CK_ULONG ulTotalPublicMemory;
CK_ULONG ulFreePublicMemory;
CK_ULONG ulTotalPrivateMemory;
CK_ULONG ulFreePrivateMemory;
CK_VERSION hardwareVersion;
CK_VERSION firmwareVersion;
CK_CHAR utcTime[16];
} CK_TOKEN_INFO;
Listing 2:
CK_TOKEN_INFO
structure ([PKCS#11(v2.3)], p. 37)
C_GetMechanismList
As explained in [NSS-PKCS#11], the Netscape Security Library calls C_GetMechanismList
fairly frequently to identify the mechanisms supported by a token.
This function returns the CK_MECHANISM_INFO
struct for a specific token.
typedef struct CK_MECHANISM_INFO {
CK_ULONG ulMinKeySize;
CK_ULONG ulMaxKeySize;
CK_FLAGS flags;
} CK_MECHANISM_INFO;
Listing 3:
CK_MECHANISM_INFO
structure ([PKCS#11(v2.3)], p. 49)
Bit Flag | Mask | Meaning |
---|---|---|
CKF_HW |
0x00000001 | True if the mechanism is performed by the device; false if the mechanism is performed in software |
CKF_ENCRYPT |
0x00000100 | True if the mechanism can be used with C_EncryptInit |
CKF_DECRYPT |
0x00000200 | True if the mechanism can be used with C_DecryptInit |
CKF_DIGEST |
0x00000400 | True if the mechanism can be used with C_DigestInit |
CKF_SIGN |
0x00000800 | True if the mechanism can be used with C_SignInit |
CKF_SIGN_RECOVER |
0x00001000 | True if the mechanism can be used with C_SignRecoverInit |
CKF_VERIFY |
0x00002000 | True if the mechanism can be used with C_VerifyInit |
CKF_VERIFY_RECOVER |
0x00004000 | True if the mechanism can be used with C_VerifyRecoverInit |
CKF_GENERATE |
0x00008000 | True if the mechanism can be used with C_GenerateKey |
CKF_GENERATE_KEY_PAIR |
0x00010000 | True if the mechanism can be used with C_GenerateKeyPair |
CKF_WRAP |
0x00020000 | True if the mechanism can be used with C_WrapKey |
CKF_UNWRAP |
0x00040000 | True if the mechanism can be used with C_UnwrapKey |
CKF_DERIVE |
0x00080000 | True if the mechanism can be used with C_DeriveKey |
CKF_EXTENSION |
0x80000000 | True if there is an extension to the flags; false if no extensions. Must be false for this version. |
Table 2: Mechanism Information Flags ([PKCS#11(v2.3)], p. 50)
Session Management¶
C_OpenSession
As explained in [NSS-PKCS#11] 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.
This function will use the IFD-function Connect
to open a session to the token.
C_CloseSession
As explained in [NSS-PKCS#11] the Netscape Security Library calls C_CloseSession
to close sessions created for bulk encryption.
This function will use the IFD-function Disconnect
to close a session to the token.
C_CloseAllSessions
As explained in [NSS-PKCS#11] 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.
This function will use the IFD-function VerifyUser
to perform the authentication of a user.
C_Logout
The Netscape Security Library calls C_Logout
on a token's initial session
- when the password is timed out
- when performing any kind of private key operation if "ask always" is turned on
- when changing a password
- when the user logs out
Object Management¶
In the scope of a TLS-handshake the client needs to read the certificate from the card and send it to the server. This functionality is most likely performed using the following two functions.
C_GetAttributeValue
The Netscape Security Library calls 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_FindObjectsInit, C_FindObjects, C_FindFinal
The Netscape Security Library calls these functions frequently to look up objects by 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.
Cryptographic Operations¶
In the scope of a TLS-handshake the client needs to sign data, which is constructed based on previously exchanged messages in the handshake. This signature is most likely created using the functions C_SignInit
, C_Sign
and C_SignFinal
.
References¶
[Grif09] R. Griffin: Encryption and Key Management Tutorials, Part II: PKCS #11 – Enhancements and Opportunities, Talk at RSA 2009, ftp://ftp.rsasecurity.com/pub/pkcs/pkcs-11/v2-30/TUT-M51_Griffin_PKCS11.pdf
[NSS-PKCS#11] Implementing PKCS #11 for the Netscape Security Library, http://docs.oracle.com/cd/E19957-01/816-6150-10/pkcs.htm
[PKCS#11(v2.3)] RSA Laboratories: PKCS #11 Base Functionality v2.30: Cryptoki – Draft 4, 10 July 2009
Additional links¶
PKCS11 FAQ
https://developer.mozilla.org/en-US/docs/PKCS11_FAQ
Using the PKCS #11 Module Logger
NSS Technical Note: 2
http://www.mozilla.org/projects/security/pki/nss/tech-notes/tn2.html
Network Security Services (NSS)
(The main NSS page with lots of links to current material)
http://www.mozilla.org/projects/security/pki/nss/
PKCS#11
https://dev.openecard.org/issues/128
Chromium support for PKCS #11
https://dev.openecard.org/issues/163
Open eCard PKCS#11 IPC Design
https://dev.openecard.org/attachments/download/237/pkcs11.pptx
Updated by Hans-Martin Haase about 9 years ago · 7 revisions