NSS Cryptographic Module Version 3.12.9.1 FIPS 140-2 Non-Proprietary Security Policy Level 1 Validation Red Hat, Inc. Document Version 1.32 April 3, 2012 Table of Contents 1. Introduction .................................................................................................................................... 3 2. Platform List .................................................................................................................................. 5 3. Note on Calling the API Functions ................................................................................................ 5 4. Module Ports and Interfaces .......................................................................................................... 7 4.1 Physical Cryptographic Boundary ..................................................................................... 7 4.2 Logical Cryptographic Boundary ....................................................................................... 8 4.3 Logical Interfaces ................................................................................................................. 8 4.4 PKCS #11 .............................................................................................................................. 9 4.5 Inhibition of Data Output ..................................................................................................... 9 4.6 Disconnecting the Output Data Path From the Key Processes .................................... 9 5. Security Rules .............................................................................................................................. 10 6. Roles and Authentication Policy .................................................................................................. 16 6.1 Specification of Roles ........................................................................................................ 16 6.2 Role Assumption ................................................................................................................ 16 6.3 Strength of Authentication Mechanism ........................................................................... 16 6.4 Multiple Concurrent Operators ......................................................................................... 17 7. Access Control Policy .................................................................................................................. 18 7.1 Security-Relevant Information .......................................................................................... 18 8. Self-Tests ...................................................................................................................................... 19 9. Random Number Generator ......................................................................................................... 20 10. Mitigation of Other Attacks ...................................................................................................... 21 11. Access to Audit Data ................................................................................................................ 22 11.1 Access to syslog Log Files ................................................................................................ 22 11.2 Access to System Audit Log ............................................................................................. 22 12. Sample Cryptographic Module Initialization Code.................................................................. 23 13. Specification of Services .......................................................................................................... 26 14. Acknowledgments .................................................................................................................... 36 15. References ................................................................................................................................ 36 Page 2 1. Introduction A security policy includes the precise specification of the security rules under which the cryptographic module must operate, including rules derived from the security requirements of the FIPS PUB 140-2 standard, and the additional security rules listed below. The rules of operation of the cryptographic module that define within which role(s) and under what circumstances (when performing which services) an operator is allowed to maintain or disclose each security relevant data item of the cryptographic module. There are three major reasons for developing and following a precise cryptographic module security policy: To induce the cryptographic module vendor to think carefully and precisely about whom they want to allow access to the cryptographic module, the way different system elements can be accessed, and which system elements to protect. To provide a precise specification of the cryptographic security to allow individuals and organizations (e.g., validators) to determine whether the cryptographic module, as implemented, does obey (satisfy) a stated security policy. To describe to the cryptographic module user (organization, or individual operator) the capabilities, protections, and access rights they will have when using the cryptographic module. The NSS cryptographic module is an open-source, general-purpose cryptographic library, with an API based on the industry standard PKCS #11 version 2.20 [1]. It is available for free under the Mozilla Public License, the GNU General Public License, and the GNU Lesser General Public License. The NSS cryptographic module is jointly developed by Red Hat and Sun engineers and is used in Mozilla Firefox, Thunderbird, and many server applications from Red Hat and Sun. Section Level Cryptographic Module Specification 1 Cryptographic Module Ports and Interfaces 1 Roles, Services, and Authentication 1 Finite State Model 1 Physical Security N/A Operational Environment 1 Cryptographic Key Management 1 EMI/EMC 1 Self-Tests 1 Design Assurance 2 Mitigation of Other Attacks 1 Overall Level 1 The NSS cryptographic module has two modes of operation: the FIPS Approved mode and non-FIPS Approved mode. By default, the module operates in the non-FIPS Approved mode. To operate the module in the FIPS Approved mode, an application must adhere to the security rules in the Security Rules section and initialize the module properly. If an application initializes the NSS cryptographic module by calling the standard PKCS #11 function C_GetFunctionList and calls the API functions via the function pointers in that list, it selects the non-FIPS Approved mode. To operate the Page 3 NSS cryptographic module in the FIPS Approved mode, an application must call the API functions via an alternative set of function pointers. Rule 7 of the Security Rules section specifies how to do this. This document may be freely reproduced and distributed in its entirety. Page 4 2. Platform List FIPS 140-2 conformance testing of the NSS cryptographic module was performed on the following platforms listed below. The list was configured with no elliptic curve cryptography (ECC) support Security Level 1 64-bit binary on Intel Core i7 running Red Hat Enterprise Linux v6.2 64-bit binary on Intel Core i7 running Red Hat Enterprise Linux v6.2 with AES-NI enabled 32-bit binary on Intel Core i7 running Red Hat Enterprise Linux v6.2 The NSS cryptographic module supports many other platforms. If you would like to have the module validated on other platforms, please contact us. 3. Note on Calling the API Functions The NSS cryptographic module has two parallel sets of API functions, FC_xxx and NSC_xxx, that implement the FIPS Approved and non-FIPS Approved modes of operation, respectively. For example, FC_Initialize initializes the module's library for the FIPS Approved mode of operation, whereas its counterpart NSC_Initialize initializes the library for the non-FIPS Approved mode of operation. If an application initialized and uses both the FIPS Approved and non-FIPS Approved interfaces, each interface will contain it's own CPS which are not shared by the other interface. For an application to be in FIPS mode it must have only the FIPS Approved interfaces open. All the API functions for the FIPS Approved mode of operation are listed in the Specification of Services section. Among the module's API functions, only FC_GetFunctionList and NSC_GetFunctionList are exported and therefore callable by their names. (The C_GetFunctionList function mentioned in the Introduction section is also exported and is just a synonym of NSC_GetFunctionList.) All the other API functions must be called via the function pointers returned by FC_GetFunctionList or NSC_GetFunctionList. FC_GetFunctionList and NSC_GetFunctionList each return a CK_FUNCTION_LIST structure containing function pointers named C_xxx such as C_Initialize and C_Finalize. The C_xxx function pointers in the CK_FUNCTION_LIST structure returned by FC_GetFunctionList point to the FC_xxx functions, whereas the C_xxx function pointers in the CK_FUNCTION_LIST structure returned by NSC_GetFunctionList point to the NSC_xxx functions. For brevity, we use the following convention to describe API function calls. Again we use FC_Initialize and NSC_Initialize as examples: When we say “call FC_Initialize,” we mean “call the FC_Initialize function via the C_Initialize function pointer in the CK_FUNCTION_LIST structure returned by FC_GetFunctionList.” When we say “call NSC_Initialize,” we mean “call the NSC_Initialize function via the C_Initialize function pointer in the CK_FUNCTION_LIST structure returned by NSC_GetFunctionList.” Page 5 Page 6 4. Module Ports and Interfaces The NSS cryptographic module is a software cryptographic implementation. No hardware or firmware components are included. All input to the module is via function arguments; all output is returned to the caller either as return codes or as updated memory objects pointed to by some of the arguments. All keys, encrypted data, and control information are exchanged through calls to library functions (logical interfaces). The physical ports, physical covers, doors, or openings; manual controls; and physical status indicators of the NSS cryptographic module are those of the general purpose computer it runs on. 4.1 Physical Cryptographic Boundary Page 7 4.2 Logical Cryptographic Boundary 4.3 Logical Interfaces The following four logical interfaces have been designed within the NSS cryptographic module. 1. Data input interface: function input arguments that specify plaintext data; ciphertext or signed data; cryptographic keys (plaintext or encrypted) and initialization vectors; and passwords that are to be input to and processed by the NSS cryptographic module. 2. Data output interface: function output arguments that receive plaintext data; ciphertext data and digital signatures; and cryptographic keys (plaintext or encrypted) and initialization vectors from the NSS cryptographic module. 3. Control input interface: function calls, or input arguments that specify commands and control data (e.g., algorithms, algorithm modes, or module settings) used to control the operation of the NSS cryptographic module 4. Status output interface: function return codes, error codes, or output arguments that receive status information used to indicate the status of the NSS cryptographic module The NSS cryptographic module uses different function arguments for input and output to distinguish between data input, control input, data output, and status output, to disconnect the logical paths followed by data/control entering the module and data/status exiting the module. The NSS cryptographic module doesn't use the same buffer for input and output. After the NSS cryptographic Page 8 module is done with an input buffer that holds security-related information, it always zeroizes the buffer so that if the memory is later reused as an output buffer, no sensitive information may be inadvertently leaked. 4.4 PKCS #11 The logical interfaces of the NSS cryptpgraphic module consist of the PKCS #11 (Cryptoki) API. The API itself defines the cryptographic boundary, i.e., all access to the cryptographic module is through this API. The module has three PKCS #11 tokens: two tokens that implement the non-FIPS Approved mode of operation, and one token that implements the FIPS Approved mode of operation. The FIPS PKCS #11 token is designed specifically for FIPS 140-2, and allows applications using the NSS cryptographic module to operate in a strictly FIPS mode. The functions in the PKCS #11 API are listed in the table in the Specification of Services section. 4.5 Inhibition of Data Output All data output via the data output interface is inhibited when the NSS cryptographic module is in the Error state or performing self-tests. In Error State: The Boolean state variable sftk_fatalError tracks whether the NSS cryptographic module is in the Error state. Most PKCS #11 functions, including all the functions that output data via the data output interface, check the sftk_fatalError state variable and, if it is true, return the CKR_DEVICE_ERROR error code immediately. Only the functions that shut down and restart the module, reinitialize the module, or output status information can be invoked in the Error state. These functions are FC_GetFunctionList, FC_Initialize, FC_Finalize, FC_GetInfo, FC_GetSlotList, FC_GetSlotInfo, FC_GetTokenInfo, FC_InitToken, FC_CloseSession, FC_CloseAllSessions, and FC_WaitForSlotEvent. During Self-Tests: The NSS cryptographic module performs power-up self-tests in the FC_Initialize function. Since no other PKCS #11 function (except FC_GetFunctionList) may be called before FC_Initialize returns successfully, all data output via the data output interface is inhibited while FC_Initialize is performing the self-tests. 4.6 Disconnecting the Output Data Path From the Key Processes During key generation and key zeroization, the NSS cryptographic module may perform audit logging, but the audit records do not contain sensitive information. The NSS cryptographic module doesn't return the function output arguments until key generation or key zeroization is finished. Therefore, the logical paths used by output data exiting the module are logically disconnected from the processes/threads performing key generation and key zeroization. Page 9 5. Security Rules The following list specifies the security rules that the NSS cryptographic module and each product using the module must adhere to: 1) The NSS cryptographic module consists of the following shared libraries and the associated .chk files: On each of Red Hat Enterprise Linux 6.2 x86, and Red Hat Enterprise Linux 6.2 x86_64 (with and without AES-NI): libsoftokn3.so • libsoftokn3.chk • libfreebl3.so • libfreebl3.chk • libnssdbm3.so • libnssdbm3.chk • 2) INSTALLATION INSTRUCTIONS: The module must be installed, setup and initialized in the FIPS-Approved mode by the Crypto- Officer by following the instructions below. Refer to the Sample Cryptographic Module Initialization Code section of this document for a sample code to assist with this. 1. Obtain the validated version of the module (3.12.9.1) either from Red Hat in the form of a pre- compiled executable distribution [rpm] or from Mozilla directly [http://developr.mozilla.org/en/NSS_3.12.9_release_notes] and install the module on the platform. For example, for the operational environment used during the FIPS-validation testing (Red hat Linux 6.2), Red Hat provides a pre-compiled rpm packages available (nss-softoken-3.12.9- 11.el6.rpm and nss-softoken-freebl-3.12.9-11.el6.rpm) and one can install these packages with the command “ rpm -U nss-softoken-freebl-3.12.9-11.el6.rpm nss-softoken-3.12.9-11.el6.rpm” or even “yum update nss-softoken” if the Red Hat Enterprise Server 6.2's yum repository is connected to the Red Hat Network. After installing the library, follow the steps below. Step 1: Install the shared libraries and the associated .chk files in a directory on the shared library/DLL search path, which can be a system library directory (/usr/lib on Unix/Linux) or a directory specified in the following environment variable: Linux: LD_LIBRARY_PATH An install using rpm automatically takes care of the proper location of the install files. Step 2: Use the chmod utility to set the file mode bits of the shared libraries to 0755 so that all users can execute the library files, but only the files' owner can modify (i.e., write, replace, and delete) the files. For example, on most Unix and Linux platforms, $ chmod 0755 libsoftokn3.so libfreebl3.so libplc4.so libplds4.so libnspr4.so The discretionary access control protects the binaries stored on disk from being tampered with. An install using rpm automatically takes care of the proper permissions of the library. Page 10 Step 3: Use the chmod utility to set the file mode bits of the associated .chk files to 0644. For example, on most Unix and Linux platforms, $ chmod 0644 libsoftokn3.chk libfreebl*3.chk libnssdbm3.chk An install using rpm automatically takes care of the proper permissions of the library check files. Step 4: As specified in Rule 7, to operate the NSS cryptographic module in the FIPS Approved mode, an application must call the alternative PKCS #11 function FC_GetFunctionList and call the API functions via the function pointers in that list. The user must initialize the password when using the module for the first time. Before the user password is initialized, access to the module must be controlled. See the Sample Cryptographic Module Initialization Code section below for an example code to accomplish this. 3) MODULE INITIALIZATION STEPS: The following module initialization steps must be followed by the Crypto-Officer before starting to use the NSS module: a) Ensure that the system has NSPR library installed. This should include the library files libplc4.so, libplds4.so and libnspr4.so (Refer to Rule #5 for more details). b) Set the environment variable NSS_ENABLE_AUDIT to 1 before using the NSS module with an application. c) Use the application to get the function pointer list using the NSS API „FC_GetFunctionList‟. d) Use the API FC_Initialize to initialize the module. Using the FC_GetFunctionList in step c) above ensured that we selected FIPS mode, and the subsequent FC_Initialize call then initializes the module in FIPS-mode. Ensure that this returns CKR_OK. A return code other than CKR_OK will mean the FIPS-mode was not enabled, and in that case, the module must be reset and initialized again. e) For the first login, provide a NULL password and login using the function pointer C_Login, which will in-turn call FC_Login API of the module. This is required to set the initial NSS User password. f) Now, set the initial User role password using the function pointer C_InitPIN. This will call the module‟s API FC_InitPIN API. Then, logout using the function pointer C_Logout, which will call the module‟s API FC_Logout. g) The User role can now be assumed on the module by logging in using the User password. And the Crypto-Officer role can be implicitly assumed by performing the Crypto-Officer services as listed in Section „Specification of Services‟ of this document. 4) The environment variable NSS_ENABLE_AUDIT must be set to 1 before the application starts. 5) The NSS cryptographic module version 3.12.9.1 requires the Netscape Portable Runtime (NSPR) libraries version 4.8.7 or later so NSPR must be installed on the machine before NSS module can be successfully used. NSPR provides a cross-platform API for non-GUI operating system facilities. NSPR is outside the cryptographic boundary because none of the NSPR functions are cryptography-relevant. Page 11 NSPR consists of the following shared libraries/DLLs on Red Hat Enterprise Linux 6 x86, and Red Hat Enterprise Linux 6 x86_64: libplc4.so libplds4.so libnspr4.so 6) The NSS cryptographic module consists of software libraries compiled for each supported platform. 7) The cryptographic module performs a software integrity check to ensure the integrity of the cryptographic module loaded into memory. 8) Applications wishing to run in the FIPS Approved mode will call FC_GetFunctionList for the list of function pointers and call the API functions via the function pointers in that list for all cryptographic operations. (See the Note on Calling the API functions section.) The module changes from FIPS Approved mode to non-FIPS Approved mode when a FC_Finalize/NSC_Initialize sequence is executed; it changes from non-FIPS Approved mode to FIPS Approved mode when a NSC_Finalize/FC_Initialize sequence is executed. 9) NSS cryptographic module can be configured to use different private key database formats: key3.db or key4.db. “key3.db” format is based on the Berkeley DataBase engine and should not be used by more than one process concurrently. “key4.db” format is based on SQL DataBase engine and can be used concurrently by multiple processes. Both databases are considered outside the cryptographic boundary and all data stored in these databases is considered stored in plaintext. The interface code of the NSS cryptographic module that accesses data stored in the database is considered part of the cryptographic boundary. 10) Secret and private keys, plaintext passwords, and other security-relevant data items are maintained under the control of the cryptographic module. Secret and private keys must be passed to the calling application only in encrypted (wrapped) form with FC_WrapKey and entered from calling application only in encrypted (wrapped) form with FC_UnwrapKey. The cryptographic algorithms allowed for this purpose in FIPS-mode are Triple DES or AES (symmetric key algorithms) or RSA (asymmetric key algorithm) using the corresponding Approved modes and key sizes as listed in Rule #12 below. Note: If the secret and private keys passed to higher-level callers are encrypted using a symmetric key algorithm, the encryption key may be derived from a password. In such a case, they should be considered to be in plaintext form in the FIPS Approved mode. 11) Automated key transport methods must use FC_WrapKey and FC_UnwrapKey to input or output secret and private keys to or from the module. 12) Once the FIPS Approved mode of operation has been selected, the user must only use the FIPS 140-2 cipher suite. 13) The FIPS 140-2 cipher suites consist solely of Triple DES (FIPS 46-3) or AES (FIPS 197) for symmetric key encryption and decryption. Secure Hash Standard (SHA-1, SHA-256, SHA-384, and SHA-512) (FIPS 180-2) for hashing. HMAC (FIPS 198) for keyed hash. Random number generator Hash DRBG (NIST SP800-90). Page 12 Diffie-Hellman primitives or Key Wrapping using RSA keys for key establishment. DSA (FIPS 186-2 with Change Notice 1), RSA (PKCS #1 v2.1),for signature generation and verification. Algorithm validation certificates: Algorithm Cert# Description Triple DES 1240 TECB(e/d; KO 1,2); TCBC(e/d; KO 1,2) AES 1908 ECB(e/d; 128,192,256); CBC(e/d; 128,192,256) SHS 1675 SHA-1 (BYTE-only) SHA-256 (BYTE-only) SHA-384 (BYTE-only) SHA-512 (BYTE-only) HMAC 1145 HMAC-SHA1 (Key Sizes Ranges Tested: KSBS ) HMAC-SHA256 ( Key Size Ranges Tested: KSBS ) HMAC-SHA348 ( Key Size Ranges Tested: KSBS ) HMAC-SHA512 ( Key Size Ranges Tested: KSBS ) DRBG 165 SP 800-90 [ Hash_DRBG: SHA-256] RSA 979 ALG[RSASSA-PKCS1_V1_5]; SIG(gen); SIG(ver); 1024 , 1536 , 2048 , 3072 , 4096 , SHS: SHA-1 , SHA-256 , SHA-384 , SHA-512 DSA 602 PQG(gen) MOD(1024); PQG(ver) MOD(1024); KEYGEN(Y) MOD(1024); SIG(gen) MOD(1024); SIG(ver) MOD(1024); Page 13 Caveats: The NSS cryptographic module implements the following cryptographic algorithms which are allowed for use in the FIPS-Approved mode of operation: Diffie-Hellman (key agreement; key establishment methodology provides between 80 and 112 bits of encryption strength) RSA encrypt/decrypt for key wrapping (key wrapping; key establishment methodology provides between 80 and 150 bits of encryption strength) AES key wrapping (key wrapping; key establishment methodology provides between 128 and 256 bits of encryption strength) Triple-DES key wrapping (key wrapping; key establishment methodology provides 80 or 112 bits of encryption strength) 14) The NSS cryptographic module implements the following non-Approved algorithms, which must NOT be used in the FIPS Approved mode of operation: RC2 , RC4, DES, SEED, or CAMELLIA for symmetric key encryption and decryption. • MD2 or MD5 for hashing • J-PAKE for symmetric key exchange • HKDF for symmetric key derive. • 15) Once the FIPS Approved mode of operation has been selected, Triple DES and AES must be must be the only algorithms used for performing encryption and decryption using either ECB or CBC mode. 16) Once the FIPS Approved mode of operation has been selected, SHA-1, SHA-256, SHA-386, and SHA-512 must be the only algorithms used to perform one-way hashes of data. 17) Once the FIPS Approved mode of operation has been selected, RSA must be limited in its use to generating and verifying PKCS #1 signatures, and to encrypting and decrypting key material for key exchange. 18) Once the FIPS Approved mode of operation has been selected, DSA can be used in addition to RSA to generate and verify signatures. 19) The module does not share CSPs between an Approved mode of operation and a non-Approved mode of operation. 20) All cryptographic keys used in the FIPS Approved mode of operation must be generated in the FIPS Approved mode or imported while running in the FIPS Approved mode. 21) The cryptographic module performs explicit zeroization steps to clear the memory region previously occupied by a plaintext secret key, private key, or password. A plaintext secret or private key gets zeroized when it is passed to a FC_DestroyObject call. All plaintext secret and private keys must be zeroized when the NSS cryptographic module: is shut down (with a FC_Finalize call); or when reinitialized (with a FC_InitToken call); or when the state changes between the FIPS Approved mode and non-FIPS Approved mode (with a NSC_Finalize/FC_Initialize or FC_Finalize/NSC_Initialize sequence). All zeroization is to be performed by storing the value 0 into every byte of the memory region previously occupied by a plaintext secret key, private key, or password. Page 14 (End of Security Rules) Page 15 6. Roles and Authentication Policy 6.1 Specification of Roles The NSS cryptographic module supports two authorized roles for operators. The NSS User role has access to all cryptographically secure services of the module (those that use the secret and private keys of the module) and is also responsible for the retrieval, updating, and deletion of keys from the private key database. The Crypto Officer role is supported for the installation of the module and for other general- purpose services (such as message digest and random number generation services) and status services of the module. The Crypto-Officer does not have access to any service that utilizes the secret or private keys of the module. The Crypto-Officer must control the access to the module both before and after installation. Control consists of management of physical access to the computer, executing the NSS cryptographic module code as well as management of the security facilities provided by the operating system. The NSS cryptographic module does not have a maintenance role. 6.2 Role Assumption The NSS cryptographic module implements a User role and a Crypto-Officer role. The Crypto-Officer role is implicitly assumed by an operator while installing the module by following the instructions in the „Security Rules‟ section of this document and while performing the Crypto-Officer services on the module. The module also implements a password-based authentication for the NSS User role. To perform sensitive User role services using the cryptographic module, an operator must log into the module and perform an authentication procedure using the password information unique to the User role operator. The password is initialized by the Crypto-Officer role as part of module initialization and can be changed by the NSS User role operator. If a User-role service is called before the operator is authenticated, it returns the CKR_USER_NOT_LOGGED_IN error code. The operator must call the FC_Login function to provide the required authentication. Once a password has been established for the NSS cryptographic module, the module allows the user to use the private services if and only if the user successfully authenticates to the module. Password establishment and authentication are required for the operation of the module. 6.3 Strength of Authentication Mechanism In the FIPS Approved mode, the NSS cryptographic module imposes the following requirements on the password. These requirements are enforced by the module on password initialization or change. The password must be at least seven characters long. Page 16 The password must consist of characters from three or more character classes. We define five character classes: digits (0-9), ASCII lowercase letters, ASCII uppercase letters, ASCII non- alphanumeric characters (such as space and punctuation marks), and non-ASCII characters. If an ASCII uppercase letter is the first character of the password, the uppercase letter is not counted toward its character class. Similarly, if a digit is the last character of the password, the digit is not counted toward its character class. To estimate the probability that a random guess of the password will succeed, we assume that the characters of the password are independent with each other, and the probability of guessing an individual character of the password is less than 1/10. Since the password is at least 7 characters long, the probability that a random guess of the password will succeed is less than (1/10)^7 = 1/10,000,000. After each failed authentication attempt in the FIPS Approved mode, the NSS cryptographic module inserts a one-second delay before returning to the caller, allowing at most 60 authentication attempts during a one-minute period. Therefore, the probability of a successful random guess of the password during a one-minute period is less than 60 * 1/10,000,000 = 0.6 * (1/100,000). 6.4 Multiple Concurrent Operators The NSS cryptographic module doesn't allow concurrent operators. On a multi-user operating system, this is enforced by making the NSS certificate and private key databases readable and writable by the owner of the files only. Note: FIPS 140-2 Implementation Guidance Section 6.1 clarifies the use of a cryptographic module on a server. When a cryptographic module is implemented in a server environment, the server application is the user of the cryptographic module. The server application makes the calls to the cryptographic module. Therefore, the server application is the single user of the cryptographic module, even when the server application is serving multiple clients. Page 17 7. Access Control Policy This section identifies the cryptographic keys and CSPs that the user has access to while performing a service, and the type of access the user has to the CSPs. 7.1 Security-Relevant Information The NSS cryptographic module employs the following cryptographic keys and CSPs in the FIPS Approved mode of operation. Note that the private key database (key3.db/key4.db) mentioned below is outside the cryptographic boundary. DSA integrity test public key: The module stores a 1024-bit public key for performing the • power-up integrity test in the three .chk files for the three corresponding .so module binaries. AES secret keys: The module supports 128-bit, 192-bit, and 256-bit AES keys. The keys may be • stored in memory or in the private key database (key3.db/key4.db). Hash_DRBG secret values: Hash DRBG entropy - 880-bit value externally-obtained for module • DRBG; stored in plaintext in volatile memory. Hash DRBG V value - Internal Hash DRBG state value; stored in plaintext in volatile memory. Hash DRBG C value - Internal Hash DRBG state value; stored in plaintext in volatile memory. Triple-DES secret keys: 168-bit. The keys may be stored in memory or in the private key • database (key3.db/key4.db). HMAC secret keys: HMAC key size must be greater than or equal to half the size of the hash • function output. The keys may be stored in memory or in the private key database (key3.db/key4.db). DSA public keys and private keys: The module supports DSA key sizes of 512-1024 bits. DSA • keys of only 1024 bits must be used in the FIPS Approved mode of operation. The keys may be stored in memory or in the private key database (key3.db/key4.db). RSA public keys and private keys (used for digital signatures and key transport): The module • supports RSA key sizes of 1024-8192 bits. The keys may be stored in memory or in the private key database (key3.db/key4.db). Diffie-Hellman public keys and private keys: The module supports Diffie-Hellman public key • sizes of 1024-2236 bits. The keys may be stored in memory or in the private key database (key3.db/key4.db). TLS premaster secret (used in deriving the TLS master secret): 48-byte. Stored in memory. • TLS master secret (a secret shared between the peers in TLS connections, used in the generation • of symmetric cipher keys, IVs, and MAC secrets for TLS): 48-byte. Stored in memory. Authentication data (User role password): Stored in salted form in the private key database • (key3.db/key4.db). Note: The NSS cryptographic module does not implement the TLS protocol. The NSS cryptographic module implements the cryptographic operations, including TLS-specific key generation and derivation operations, that can be used to implement the TLS protocol. Page 18 8. Self-Tests In the FIPS Approved mode of operation the cryptographic module does not allow critical errors to compromise security. Whenever a critical error (e.g., a self-test failure) is encountered, the cryptographic module enters an error state and the library needs to be reinitialized to resume normal operation. Reinitialization is accomplished by calling FC_Finalize followed by FC_Initialize. Upon initialization of the cryptographic module library in the FIPS Approved mode of operation using FC_Initialize, the following power-up self-tests are performed by the module: a) Triple DES encrypt/decrypt KAT, b) AES encrypt/decrypt KAT, c) SHA-1 KAT, d) SHA-256 KAT, e) SHA-384 KAT, f) SHA-512 KAT, g) HMAC-SHA-1/-SHA-256/-SHA-384/-SHA-512 KAT, h) RSA encrypt/decrypt KAT, i) RSA signature generation/verification KAT, j) DSA signature generation/verification KAT, k) Random number generation KAT, and l) Software integrity test (the authentication technique is DSA with 1024-bit prime modulus p). Shutting down and restarting the NSS cryptographic module with the FC_Finalize and FC_Initialize functions executes the same power-up self-tests detailed above when initializing the module library for the FIPS Approved mode. This allows an operator to execute these power-up self-tests on demand as defined in Section 4.9.1 of FIPS 140-2. In the FIPS Approved mode of operation, the cryptographic module performs a pair-wise consistency test upon each invocation of RSA, and DSA key pair generation as defined in Section 4.9.2 of FIPS 140-2. In the FIPS Approved mode of operation, the cryptographic module performs a continuous random number generator test upon each invocation of the pseudorandom number generator as defined in Section 4.9.2 of FIPS 140-2. Page 19 9. Random Number Generator The cryptographic module performs pseudorandom number generation using NIST SP 800-90 Hash Deterministic Random Bit Generator using SHA-256. When running on the tested RHEL 6.2 platform, the cryptographic module initializes its pseudorandom number generator by obtaining at least 110 bytes of random data from the operating system. The data obtained contains at least 440 bits of entropy. At the time of reseed, the extra entropy input is added by invoking a noise generator. The noise is derived from the execution environment such that it is not predictable. The source of noise is considered to be outside the logical boundary of the cryptographic module. A product using the cryptographic module should periodically reseed the module's pseudorandom number generator with unpredictable noise by calling FC_SeedRandom. After 246 calls to the random number generator the cryptographic module obtains another 110 bytes of random data from the operating system to reseed the random number generator. Page 20 10. Mitigation of Other Attacks The NSS cryptographic module is designed to mitigate the following attacks. Specific Other Attacks Mitigation Mechanism Limitations RSA blinding Timing attack on RSA was first demonstrated by Paul Kocher in 1996 [2], who contributed the mitigation Timing attacks on RSA None code to our module. Most recently Boneh and Brumley [3] showed that RSA blinding is an effective defense against timing attacks on RSA. This mechanism Cache invariant modular requires intimate knowledge of the exponentiation cache line sizes of Cache-timing attacks on the modular This is a variant of a modular the processor. The exponentiation operation used in RSA exponentiation mechanism may be implementation that Colin and DSA ineffective when the Percival [4] showed to module is running defend against cache-timing on a processor attacks. whose cache line sizes are unknown. Double-checking RSA signatures Arithmetic errors in RSA signatures might leak the Arithmetic errors in RSA signatures None private key. Ferguson and Schneier [5] recommend that every RSA signature generation should verify the signature just generated. Page 21 11. Access to Audit Data The NSS cryptographic module may use the Unix syslog function and the audit mechanism provided by the operating system to audit events. Auditing is turned off by default. Auditing capability must be turned on as part of the initialization procedures by setting the environment variable NSS_ENABLE_AUDIT to 1. The Crypto-Officer must also configure the operating system's audit mechanism. Access to the audit data is described in the next two subsections. 11.1 Access to syslog Log Files On Unix (including Linux and Mac OS X), the NSS cryptographic module uses the syslog function to audit events, so the audit data are stored in the system log. Only the root user can modify the system log. On some platforms, only the root user can read the system log; on other platforms, all users can read the system log. The system log is usually under the /var/adm or /var/log directory. The exact location of the system log is specified in the /etc/syslog.conf file. The NSS cryptographic module uses the default user facility and the info, warning, and err severity levels for its log messages. We give an example below. Red Hat Enterprise Linux 5: The /etc/syslog.conf file on Red Hat Enterprise Linux 6.2 has: *.info;mail.none;authpriv.none;cron.none /var/log/messages which specifies that /var/log/messages is the system log. 11.2 Access to System Audit Log The NSS cryptographic module can also be configured to use the audit mechanism provided by the operating system to audit events. The audit data would then be stored in the system audit log. Only the root user can read or modify the system audit log. To turn on this capability on Red Hat Enterprise Linux 6.2, it is necessary to create a symbolic link from the library file /usr/lib/libaudit.so.0 to /usr/lib/libaudit.so.1.0.0 (on 32-bit platforms) and /usr/lib64/libaudit.so.0 to /usr/lib64/libaudit.so.1.0.0 (on 64-bit platforms). On Red Hat Enterprise Linux 6.2, the system audit log is in the /var/log/audit directory. Page 22 12. Sample Cryptographic Module Initialization Code The following sample code uses NSPR functions (declared in the header file "prlink.h") for dynamic library loading and function symbol lookup. #include "prlink.h" #include "cryptoki.h" #include #include #include /* * An extension of the CK_C_INITIALIZE_ARGS structure for the * NSS cryptographic module. The 'LibraryParameters' field is * used to pass instance-specific information to the library * (like where to find its config files, etc). */ typedef struct CK_C_INITIALIZE_ARGS_NSS { CK_CREATEMUTEX CreateMutex; CK_DESTROYMUTEX DestroyMutex; CK_LOCKMUTEX LockMutex; CK_UNLOCKMUTEX UnlockMutex; CK_FLAGS flags; CK_CHAR_PTR *LibraryParameters; CK_VOID_PTR pReserved; } CK_C_INITIALIZE_ARGS_NSS; int main() { char *libname; PRLibrary *lib; CK_C_GetFunctionList pFC_GetFunctionList; CK_FUNCTION_LIST_PTR pFunctionList; CK_RV rv; CK_C_INITIALIZE_ARGS_NSS initArgs; CK_SLOT_ID slotList[2], slotID; CK_ULONG ulSlotCount; CK_TOKEN_INFO tokenInfo; CK_SESSION_HANDLE hSession; CK_UTF8CHAR password[] = "1Mozilla"; PRStatus status; /* * Get the platform-dependent library name of the NSS * cryptographic module. */ libname = PR_GetLibraryName(NULL, "softokn3"); assert(libname!= NULL); lib = PR_LoadLibrary(libname); assert(lib!= NULL); PR_FreeLibraryName(libname); pFC_GetFunctionList = (CK_C_GetFunctionList) PR_FindFunctionSymbol(lib, "FC_GetFunctionList"); assert(pFC_GetFunctionList!= NULL); rv = (*pFC_GetFunctionList)(&pFunctionList); assert(rv == CKR_OK); Page 23 /* Call FC_xxx via the function pointer pFunctionList->C_xxx */ initArgs.CreateMutex = NULL; initArgs.DestroyMutex = NULL; initArgs.LockMutex = NULL; initArgs.UnlockMutex = NULL; initArgs.flags = CKF_OS_LOCKING_OK; initArgs.LibraryParameters = (CK_CHAR_PTR *) "configdir='.' certPrefix='' keyPrefix='' " "secmod='secmod.db' flags= "; initArgs.pReserved = NULL; rv = pFunctionList->C_Initialize(&initArgs); assert(rv == CKR_OK); ulSlotCount = sizeof(slotList)/sizeof(slotList[0]); rv = pFunctionList->C_GetSlotList(CK_TRUE, slotList, &ulSlotCount); assert(rv == CKR_OK); slotID = slotList[0]; rv = pFunctionList->C_OpenSession(slotID, CKF_RW_SESSION | CKF_SERIAL_SESSION, NULL, NULL, &hSession); assert(rv == CKR_OK); /* set the operator's initial password, if necessary */ rv = pFunctionList->C_GetTokenInfo(slotID, &tokenInfo); assert(rv == CKR_OK); if (!(tokenInfo.flags & CKF_USER_PIN_INITIALIZED)) { /* * As a formality required by the PKCS #11 standard, the * operator must log in as the PKCS #11 Security Officer (SO), * with the predefined empty string password, to set the * operator's initial password. */ rv = pFunctionList->C_Login(hSession, CKU_SO, NULL, 0); assert(rv == CKR_OK); rv = pFunctionList->C_InitPIN(hSession, password, strlen(password)); assert(rv == CKR_OK); /* log out as the PKCS #11 SO */ rv = pFunctionList->C_Logout(hSession); assert(rv == CKR_OK); } /* the module is now ready for use */ /* authenticate the operator using a password */ rv = pFunctionList->C_Login(hSession, CKU_USER, password, strlen(password)); assert(rv == CKR_OK); /* use the module's services ... */ rv = pFunctionList->C_CloseSession(hSession); assert(rv == CKR_OK); Page 24 rv = pFunctionList->C_Finalize(NULL); assert(rv == CKR_OK); status = PR_UnloadLibrary(lib); assert(status == PR_SUCCESS); return 0; } The mode of operation of the NSS cryptographic module is determined by the second argument passed to the PR_FindFunctionSymbol function. For the non-FIPS Approved mode of operation, look up the standard PKCS #11 function • C_GetFunctionList. For the FIPS Approved mode of operation, look up the alternative function • FC_GetFunctionList. Page 25 13. Specification of Services Cryptographic module services consists of Crypto-Officer services, which require no operator authentication, and User services, which require operator authentication. Crypto-Officer services do not require access to the secret and private keys and other critical security parameters (CSPs) associated with the user. Note: CSPs are security-related information (e.g. secret and private keys, and authentication data such as passwords) whose disclosure or modification can compromise the security of a cryptographic module. Message digesting services are available to Crypto-Officer only when CSPs are not accessed. Services which access CSPs (e.g., FC_GenerateKey, FC_GenerateKeyPair) require authentication. The table below lists each service as an API function and correlates role, service type, and type of access to the cryptographic keys and CSPs. Access types R, W, and Z stand for Read, Write, and Zeroize, respectively. Note: The message digesting functions (except FC_DigestKey) are allowed to the Crypto-Officer role and do not require User role authentication to the module. These services do not use any keys of the module. FC_DigestKey computes the message digest (hash) of the value of a secret key, so it is available only to the NSS User role. Service Role Function Name Description Cryptographic Keys Access type, Category and CSPs RWZ Accessed FIPS 140-2 FC_GetFunctionList returns the list of none - Crypto- specific function pointers for Officer the FIPS Approved mode of operation Module Crypto- FC_InitToken initializes or User password and all Z Initialization Officer reinitializes a token keys Crypto- FC_InitPIN initializes the user's User password W Officer password, i.e., sets the user's initial password General Crypto- FC_Initialize initializes the module none - purpose Officer library for the FIPS Approved mode of operation. This function provides the power-up self-test service. Crypto- FC_Finalize finalizes (shuts down) all keys Z Officer the module library Crypto- FC_GetInfo obtains general none - Officer information about the module library Page 26 Service Role Function Name Description Cryptographic Keys Access type, Category and CSPs RWZ Accessed Slot and Crypto- FC_GetSlotList obtains a list of slots in none - token Officer the system management Crypto- FC_GetSlotInfo obtains information none - Officer about a particular slot Crypto- FC_GetTokenInfo obtains information none - Officer about the token. This function provides the Show Status service. Crypto- FC_WaitForSlotEvent This function is not none - Officer supported by the NSS cryptographic module. Crypto- FC_GetMechanismList obtains a list of none - Officer mechanisms (cryptographic algorithms) supported by a token Crypto- FC_GetMechanismInfo obtains information none - Officer about a particular mechanism FC_SetPIN changes the user's NSS User User password RW password Page 27 Service Role Function Name Description Cryptographic Keys Access type, Category and CSPs RWZ Accessed Session Crypto- FC_OpenSession opens a connection none - management Officer ("session") between an application and a particular token Crypto- FC_CloseSession closes a session All keys of the session Z Officer Crypto- FC_CloseAllSessions closes all sessions with all keys Z Officer a token Crypto- FC_GetSessionInfo obtains information none - Officer about the session. This function provides the Show Status service. Crypto- FC_GetOperationState saves the state of the none - Officer cryptographic operation in a session. This function is only implemented for message digest operations. Crypto- FC_SetOperationState restores the state of the none - Officer cryptographic operation in a session. This function is only implemented for message digest operations. FC_Login logs into a token NSS User User password R FC_Logout logs out from a token NSS User none - Page 28 Service Role Function Name Description Cryptographic Keys Access type, Category and CSPs RWZ Accessed Object NSS User FC_CreateObject creates an object key W management NSS User FC_CopyObject creates a copy of an original key R object W new key NSS User FC_DestroyObject destroys an object key Z NSS User FC_GetObjectSize obtains the size of an key R object in bytes NSS User FC_GetAttributeValue obtains an attribute key R value of an object NSS User FC_SetAttributeValue modifies an attribute key W value of an object NSS User FC_FindObjectsInit initializes an object none - search operation NSS User FC_FindObjects continues an object keys matching the R search operation search criteria NSS User FC_FindObjectsFinal finishes an object search none - operation Encryption FC_EncryptInit initializes an encryption NSS User AES/Trriple-DES R and operation encryption key decryption FC_Encrypt encrypts single-part NSS User AES/Trriple-DES R data encryption key FC_EncryptUpdate continues a multiple- NSS User AES/Trriple-DES R part encryption encryption key operation FC_EncryptFinal finishes a multiple-part NSS User AES/Trriple-DES R encryption operation encryption key FC_DecryptInit initializes a decryption NSS User AES/Trriple-DES R operation decryption key FC_Decrypt decrypts single-part NSS User AES/Trriple-DES R encrypted data decryption key FC_DecryptUpdate continues a multiple- NSS User AES/Trriple-DES R part decryption decryption key operation FC_DecryptFinal finishes a multiple-part NSS User AES/Trriple-DES R decryption operation decryption key Page 29 Service Role Function Name Description Cryptographic Keys Access type, Category and CSPs RWZ Accessed Message Crypto- FC_DigestInit initializes a message- none - digesting Officer digesting operation Crypto- FC_Digest digests single-part none - Officer data Crypto- FC_DigestUpdate continues a multiple- none - Officer part digesting operation NSS User FC_DigestKey continues a multi-part key R message-digesting (see the note at the operation by digesting end of the the value of a secret table) key as part of the data already digested Crypto- FC_DigestFinal finishes a multiple- none - Officer part digesting operation Page 30 Service Role Function Name Description Cryptographic Keys Access type, Category and CSPs RWZ Accessed Signature and NSS User FC_SignInit initializes a signature RSA/DSA signing key, R verification operation HMAC key NSS User FC_Sign signs single-part data RSA/DSA signing key, R HMAC key NSS User FC_SignUpdate continues a multiple- RSA/DSA signing key, R part signature HMAC key operation NSS User FC_SignFinal finishes a multiple- RSA/DSA signing key, R part signature HMAC key operation NSS User FC_SignRecoverInit initializes a signature RSA/DSA signing key R operation, where the data can be recovered from the signature NSS User FC_SignRecover signs single-part data, RSA/DSA signing key R where the data can be recovered from the signature NSS User FC_VerifyInit initializes a RSA/DSA Verification R verification operation key, HMAC key NSS User FC_Verify verifies a signature on RSA/DSA Verification R single-part data key, HMAC key NSS User FC_VerifyUpdate continues a multiple- RSA/DSA Verification R part verification key, HMAC key operation NSS User FC_VerifyFinal finishes a multiple- RSA/DSA Verification R part verification key, HMAC key operation NSS User FC_VerifyRecoverInit initializes a RSA/DSA verification R verification operation key where the data is recovered from the signature NSS User FC_VerifyRecover verifies a signature on RSA/DSA verification R single-part data, where key the data is recovered from the signature Page 31 Service Role Function Name Description Cryptographic Keys Access type, Category and CSPs RWZ Accessed Dual-function NSS User FC_DigestEncryptUpdate continues a multiple- RSA/DSA encryption R cryptographic part digesting and key operations encryption operation NSS User FC_DecryptDigestUpdate continues a multiple- RSA/DSA decryption R part decryption and key digesting operation NSS User FC_SignEncryptUpdate continues a multiple- RSA/DSA signing key, R part signing and HMAC key encryption operation R RSA/DSA encryption key NSS User FC_DecryptVerifyUpdate continues a multiple- RSA/DSA decryption R part decryption and key verify operation RSA/DSA verification R key, HMAC key Key NSS User FC_GenerateKey generates a secret key key W management (used by TLS to generate premaster secrets) NSS User FC_GenerateKeyPair generates a RSA/DSA key pair W public/private key pair. This function performs the pair-wise consistency tests. NSS User FC_WrapKey wraps (encrypts) a key wrapping key R R key to be wrapped NSS User FC_UnwrapKey unwraps (decrypts) a unwrapping key R key W unwrapped key NSS User FC_DeriveKey derives a key from a base key R base key (used by TLS to derive keys from the derived key W master secret) Page 32 Service Role Function Name Description Cryptographic Keys Access type, Category and CSPs RWZ Accessed Random Crypto- FC_SeedRandom mixes in additional none RW number Officer seed material to the generation random number generator Crypto- FC_GenerateRandom generates random data. none RW Officer This function performs the continuous random number generator test. Parallel Crypto- FC_GetFunctionStatus a legacy function, none - function Officer which simply returns management the value 0x00000051 (function not parallel) Crypto- FC_CancelFunction a legacy function, none - Officer which simply returns the value 0x00000051 (function not parallel) The following list of services are available in non-FIPS mode. Note that they are the same as the FIPS mode services listed in the table above, but with the NSC_xxx tag in front of the API function, instead of FC_xxx. The behaviors of these functions are identical to their FIPS mode counterparts. NSC_GetFunctionList NSC_InitToken NSC_InitPIN NSC_Initialize NSC_Finalize NSC_GetInfo NSC_GetSlotList NSC_GetSlotInfo NSC_GetTokenInfo NSC_WaitForSlotEvent NSC_GetMechanismList NSC_GetMechanismInfo NSC_SetPIN NSC_OpenSession NSC_CloseSession NSC_CloseAllSessions NSC_GetSessionInfo NSC_GetOperationState NSC_SetOperationState NSC_Login NSC_Logout Page 33 NSC_CreateObject NSC_CopyObject NSC_DestroyObject NSC_GetObjectSize NSC_GetAttributeValue NSC_SetAttributeValue NSC_FindObjectsInit NSC_FindObjects NSC_FindObjectsFinal NSC_EncryptInit NSC_Encrypt NSC_EncryptUpdate NSC_EncryptFinal NSC_DecryptInit NSC_Decrypt NSC_DecryptUpdate NSC_DecryptFinal NSC_DigestInit NSC_Digest NSC_DigestUpdate NSC_DigestKey NSC_DigestFinal NSC_SignInit NSC_Sign NSC_SignUpdate NSC_SignFinal NSC_SignRecoverInit NSC_SignRecover NSC_VerifyInit NSC_Verify NSC_VerifyUpdate NSC_VerifyFinal NSC_VerifyRecoverInit NSC_VerifyRecover NSC_DigestEncryptUpdate NSC_DecryptDigestUpdate NSC_SignEncryptUpdate NSC_DecryptVerifyUpdate NSC_GenerateKey NSC_GenerateKeyPair NSC_WrapKey NSC_UnwrapKey NSC_DeriveKey NSC_SeedRandom NSC_GenerateRandom NSC_GetFunctionStatus Page 34 NSC_CancelFunction Page 35 14. Acknowledgments Wan-Teh Chang, Glen Beasley, Neil Williams, Matthew Harmsen, John Hines, Ian McGreer, Bishakha Banerjee, and Alexie Volkov wrote previous versions of this document. Julien Pierre and Steve Parkinson's review comments improved the presentation and accuracy of the information. The current version was written by Bob Relyea. 15. References [1] RSA Laboratories, “PKCS #11 v2.20: Cryptographic Token Interface Standard”, 2004. (http://www.rsasecurity.com/rsalabs/node.asp?id=2133) [2] P. Kocher, "Timing Attacks on Implementations of Diffie-Hellman, RSA, DSS, and Other Systems," CRYPTO '96, Lecture Notes In Computer Science, Vol. 1109, pp. 104-113, Springer-Verlag, 1996. (http://www.cryptography.com/timingattack/) [3] D. Boneh and D. Brumley, "Remote Timing Attacks are Practical," http://crypto.stanford.edu/~dabo/abstracts/ssl-timing.html. [4] C. Percival, "Cache Missing for Fun and Profit," http://www.daemonology.net/papers/htt.pdf. [5] N. Ferguson and B. Schneier, Practical Cryptography, Sec. 16.1.4 "Checking RSA Signatures", p. 286, Wiley Publishing, Inc., 2003. Page 36