PKCS11 » History » Revision 2
Revision 1 (Johannes Schmölz, 12/18/2012 07:43 PM) → Revision 2/7 (Johannes Schmölz, 12/19/2012 11:44 AM)
h1. 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. !mozilla-crypto-architecture.jpg! _Figure 1: Mozilla's Cryptographic Architecture ([Grif09], p. 22)_ Architecture_ 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]. h2. Required Functions h3. 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_Initialize * @C_Finalize@ C_Finalize * @C_GetFunctionList@ C_GetFunctionList * @C_GetInfo@ C_GetInfo *C_Initialize* As explained in [NSS-PKCS#11] the Netscape Security Library calls @C_Initialize@ C_Initialize on startup or when it loads a new module. The Netscape Security Library always passes @NULL@, NULL, as required by the PKCS #11 specification, in the single @C_Initialize@ C_Initialize parameter @pReserved@. pReserved. This function will use the IFD-function @EstablishContext@ EstablishContext to initialize the IFD-module. *C_Finalize* As explained in [NSS-PKCS#11] the Netscape Security Library calls @C_Finalize@ C_Finalize on shutdown and whenever it unloads a module. This function will use the IFD-function @ReleaseContext@ ReleaseContext to initialize the IFD-module. *C_GetInfo* The Netscape Security Library calls @C_GetInfo@ 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@ 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@. CKR_FUNCTION_NOT_SUPPORTED. This function will only return static information and does not involve any IFD-function. h3. Slot and Token Management *C_GetSlotList* As explained in [NSS-PKCS#11] the Netscape Security Library calls @C_GetSlotList@ 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@ C_WaitForSlotEvent is not used by the Netscape Security Se-curity Library. This function uses the following IFD-functions: * @ListIFDs@ ListIFDs * @GetIFDCapabilities@ GetIFDCapabilities * @GetStatus@ GetStatus *C_GetSlotInfo* As explained in [NSS-PKCS#11] the Netscape Security Library calls @C_GetSlotInfo@ 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@ CKF_REMOVABLE_DEVICE flag is set, the Netscape Security Library also calls @C_GetSlotInfo@ C_GetSlotInfo whenever it looks up slots to make sure the token is present. If the @CKF_REMOVABLE_DEVICE@ CKF_REMOVABLE_DEVICE flag is not set, the Netscape Security Library uses that token information without checking again. If the @CKF_REMOVABLE_DEVICE@ CKF_REMOVABLE_DEVICE flag is not set, the @CKF_TOKEN_PRESENT@ 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@ CKF_HW_SLOT flag. For a particular slot this function returns the following structure: <pre><code class="c"> 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; </code></pre> _Listing 1: @CK_SLOT_INFO@ structure_ *C_GetTokenInfo* If a token is a permanent device (that is, if the @CKF_REMOVABLE_DEVICE@ CKF_REMOVABLE_DEVICE flag is not set), the Netscape Security Library calls @C_GetTokenInfo@ 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@ 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 CK_TOKEN_INFO.label to contain the name of the token. If the @CKF_WRITE_PROTECTED@ 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@ CKF_LOGIN_REQUIRED and @CKF_USER_PIN_INITIALIZED@ 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. | TODO: insert table _Table 1: Interpretation of flags ([NSS-PKCS#11], Table 1.1)_ For a typical signature card in operational mode the two flags are @TRUE@. TRUE. On the other side the two flags for the private key on the eGK, which is used for card2card-authentication, are both @FALSE@. FALSE. This function returns the @CK_TOKEN_INFO@ CK_TOKEN_INFO struct for a specific token. <pre><code class="c"> 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; </code></pre> _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@ C_GetMechanismList fairly frequently to identify the mechanisms supported by a token. This function returns the @CK_MECHANISM_INFO@ CK_MECHANISM_INFO struct for a specific token. <pre><code class="c"> typedef struct CK_MECHANISM_INFO { CK_ULONG ulMinKeySize; CK_ULONG ulMaxKeySize; CK_FLAGS flags; } CK_MECHANISM_INFO; </code></pre> _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. | TODO: insert table _Table 2: Mechanism Information Flags ([PKCS#11(v2.3)], p. 50)_ h3. Session Management *C_OpenSession* As explained in [NSS-PKCS#11] the Netscape Security Library calls @C_OpenSession@ 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 some-thing 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@ Connect to open a session to the token. *C_CloseSession* As explained in [NSS-PKCS#11] the Netscape Security Library calls @C_CloseSession@ C_CloseSession to close sessions created for bulk encryption. This function will use the IFD-function @Disconnect@ Disconnect to close a session to the token. *C_CloseAllSessions* As explained in [NSS-PKCS#11] the Netscape Security Library may call @C_CloseAllSessions@ C_CloseAllSessions when it closes down a slot. *C_GetSessionInfo* The Netscape Security Library calls @C_GetSessionInfo@ C_GetSessionInfo frequently. If a token has been removed during a session, @C_GetSessionInfo@ C_GetSessionInfo should return either @CKR_SESSION_CLOSED@ CKR_SESSION_CLOSED or @CKR_SESSION_HANDLE_INVALID@. CKR_SESSION_HANDLE_INVALID. If a token has been removed and then the same or another token is inserted, @C_GetSessionInfo@ C_GetSessionInfo should return @CKR_SESSION_HANDLE_INVALID@. CKR_SESSION_HANDLE_INVALID. *C_Login* The Netscape Security Library calls @C_Login@ C_Login on a token's initial session whenever @CKF_LOGIN_REQUIRED@ CKF_LOGIN_REQUIRED is @TRUE@ TRUE and the user state indicates that the user isn't logged in. This function will use the IFD-function @VerifyUser@ VerifyUser to perform the authentication of a user. *C_Logout* The Netscape Security Library calls @C_Logout@ 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 h3. 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@ C_GetAttributeValue to get the value of attributes attrib-utes 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@ CKA_ID or @CKA_LABEL@. 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@ CK_ISSUER and @CK_SERIAL@. CK_SERIAL. If those fields aren't set on the token, S/MIME won't work. h3. 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@ C_SignInit, C_Sign and @C_SignFinal@. C_SignFinal. h2. 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