VE 07KeyMgmt: Difference between revisions

From MozillaWiki
Jump to navigation Jump to search
m (Reverted edit of Msrq, changed back to last version by RyanJones)
No edit summary
Line 1: Line 1:
''This is a draft document''


=Key Management=
# Our private key and certificate databases are hash (Berkeley DB 1.85) indexed flat files (regular files). Temporary (session) keys are stored in memory (RAM).
# Private keys and secret keys are stored in the private key database. At Security Level 1, the operating system is restricted to a single operator mode of operation, which protects against unauthorized disclosure, modification, and substitution of the private keys and secret keys stored in the private key database. At Security Level 2, we use the discretionary access control mechanism of the operating system on the private key database to protect against unauthorized disclosure, modification, and substitution of the private keys and secret keys stored in the private key database. <div class=note>The private keys and secret keys stored in the private key database are actually encrypted using three-key Triple DES in CBC mode (DES-EDE3-CBC) to provide additional protection against unauthorized disclosure, modification, and substitution. Although Triple DES is an Approved security function, the key encrypting key is derived from the user's password using an extension of the PKCS #5 PBKDF1 key derivation function (see the <code>[http://www.mozilla.org/projects/security/pki/nss/fips/nss-source/mozilla/security/nss/lib/softoken/lowpbe.c.dep.html#nsspkcs5_PBKDF1Extended nsspkcs5_PBKDF1Extended]</code> function) with an 16-octet salt, an iteration count of 1, and SHA-1 as the underlying hash function. Since password-based encryption such as PKCS #5 is not FIPS Approved, the private and secret keys in the private key database are considered in plaintext form by FIPS 140-2 (see FIPS 140-2 Section 4.7 and FIPS 140-2 IG 7.1). For more information on how the secret and private keys in the private key database are password-encrypted, see the <code>[http://www.mozilla.org/projects/security/pki/nss/fips/nss-source/mozilla/security/nss/lib/softoken/lowpbe.c.dep.html#nsspkcs5_CipherData nsspkcs5_CipherData]</code> function.</div>
# When the secret keys and private keys reside in memory, they are protected by the OS from unauthorized disclosure, modification, and substitution.
# Public keys are stored in two ways.
#* Public keys in public/private key pairs (owned by the operator) are stored as attributes of the associated private keys in the private key database. <div class=note>Attributes of private keys are also password-encrypted as explained in the note above.</div>
#* X.509 v3 certificates containing public keys are stored DER encoded in the certificate database. The certificates are not encrypted, but are digitally signed by the Certification Authority (CA) that created them.
#* At Security Level 1, the operating system is restricted to a single operator mode of operation, which protects against unauthorized modification and substitution of the public keys and certificates stored in the private key and certificate databases. At Security Level 2, we use the discretionary access control mechanism of the operating system on the private key and certificate databases to protect against unauthorized modification and substitution of the public keys and certificates stored in the private key and certificate databases.
# When the public keys reside in memory, they are protected by the OS from unauthorized modification and substitution.
# The NSS cryptographic module uses the following cryptographic keys, cryptographic key components, and CSPs in the FIPS Approved mode of operation:
#* AES secret keys
#* Triple DES secret keys
#* HMAC secret keys
#* DSA public keys and private keys
#* RSA public keys and private keys (used for key transport and digital signatures)
#* ECDSA public keys and private keys
#* Diffie-Hellman public keys and private keys (used for key agreement)
#* EC Diffie-Hellman public keys and private keys (used for key agreement)
#* seed-key of the Approved RNG
#* TLS premaster secret (used in deriving the TLS master secret)
#* TLS master secret (used in the generation of symmetric cipher keys, IVs, and MAC secrets for TLS)
#* authentication data (passwords).
# The NSS cryptographic module uses the following cryptographic keys internally. These keys are not visible to the operator.
#* The Triple DES key derived from the user's password, used to encrypt the secret keys and private keys stored in the private key database.
#* The 1024-bit DSA public keys for the software/firmware integrity test are stored along with the DSA signatures in the .chk files for the softoken (PKCS #11) and freebl shared libraries/DLLs. The DSA domain parameters (prime p, subprime q, base g) and public key (y) are stored in a straight binary format (i.e., not DER encoded).
# No passwords (e.g., the password for password-based encryption, or the private key database password) are stored on disk in plaintext.
# An extension of the PKCS #5 PBKDF1 key derivation function (see the <code>[http://www.mozilla.org/projects/security/pki/nss/fips/nss-source/mozilla/security/nss/lib/softoken/lowpbe.c.dep.html#nsspkcs5_PBKDF1Extended nsspkcs5_PBKDF1Extended]</code> function) is used to convert a user's password to a DES-EDE3 (three-key Triple DES) key that is used to encrypt a known plaintext to determine if it matches the password verifier stored in the database.
# Prior to exiting the NSS cryptographic module, all passwords entered by users and private keys (stored on disk) are zeroized from memory.
=Key Generation=
The <code>FC_GenerateKey</code> and <code>FC_GenerateKeyPair</code> functions of the NSS cryptographic module perform key generation. <code>FC_GenerateKey</code> generates secret keys and domain parameters, and <code>FC_GenerateKeyPair</code> generates public/private key pairs.
'''Approved key generation method:''' The NSS cryptographic module uses the Approved RNG specified as Algorithm 1 of FIPS 186-2 Change Notice 1 to generate cryptographic keys used by the Approved and non-Approved security functions. The validation certificate for the Approved RNG is [http://csrc.nist.gov/cryptval/rng/rngval.html#208 Cert# 208].
Secret keys for symmetric key algorithms and HMAC are generated using the output of the Approved RNG.
DSA public and private keys are generated using the method specified in FIPS 186-2 with Change Notice 1.
RSA public and private keys are generated using the method specified in [http://www.rsasecurity.com/rsalabs/node.asp?id=2125 PKCS #1].
The prime numbers that are generated for both RSA and DSA are tested using Miller-Rabin test (FIPS 186-2 Appendix 2.1. A Probabilistic Primality Test).
ECDSA public and private keys are generated using the method specified in ANSI X9.62-1998.
'''Security of key generation method:''' The seed-key, ''XKEY'', of the Approved RNG is 256 bits. The keys generated by the NSS cryptographic module have at most 256 bits of security. (See NIST [http://csrc.nist.gov/publications/nistpubs/800-57/SP800-57-Part1.pdf Special Publication (SP) 800-57 Part 1], Table 2 in Section 5.6.1 on page 63.) Therefore, compromising the security of the key generation method (e.g., guessing the seed value to initialize the Approved RNG) requires at least as many operations as determining the value of the generated key.
The initial value of ''XKEY'' is derived using the following procedure.
* We obtain 1024 bytes from the system random number generator. On Windows XP SP 2, we call the CryptGenRandom function in the CryptoAPI. On Solaris, HP-UX, Linux, and Mac OS X, we read from the special device /dev/urandom.<div class=note>On HP-UX B.11.11, one must install the HP-UX Strong Random Number Generator (KRNG11i) bundle to add the /dev/random and /dev/urandom special files. The KRNG11i bundle can be downloaded for free from the HP software depot, and installation is straightforward.</div> We set ''XKEY'' to the SHA-256 hash of these 1024 bytes.<pre>XKEY = SHA-256(1024 bytes from the system RNG)</pre> This is performed in the <code>RNG_RNGInit</code> function.
* We then add extra entropy input to ''XKEY'' using SHA-256 as the mixing function:<pre>XKEY = SHA-256(XKEY || entropy_input)</pre> This is performed in the <code>RNG_SystemInfoForRNG</code> function. The mixing function is modeled after the reseed processes for the '''Hash_DRBG''' and '''Dual_EC_DRBG''' deterministic random bit generators in NIST SP 800-90 and the Reseed function for the Fortuna random number generator in Ferguson and Schneier's Practical Cryptography. The extra entropy input is either time-varying or machine-varying. On Unix, it includes:
** various high-resolution clocks, several times. Examples are
*** <code>gettimeofday</code>
*** <code>gethrtime</code> on Solaris
*** <code>times</code> on Mac OS X
*** the CR16 interval timer in the PA-RISC processor on HP-UX B.11.11 (see also http://h21007.www2.hp.com/dspp/tech/tech_TechSingleTipDetailPage_IDX/1,2366,5057,00.html)
** the names, values, and memory addresses of all the environment variables.
** static system information or current system/kernel statistics, twice. Examples are
*** the overall system statistics returned by the <code>sysinfo</code> function on Linux
*** machine hardware name, OS release level, and hardware serial number returned by the <code>sysinfo</code> function on Solaris
*** version number of OSF/AES OSC supported and version of CPU architecture returned by the <code>sysconf</code> function on HP-UX
*** the maximum number of simultaneous processes per user id, the maximum number of streams that a process may have open at any one time, and the maximum number of open files per user id returned by the <code>sysconf</code> function on Mac OS X
** the host name (returned by <code>gethostname</code>)
** the status information (<code>struct stat</code>) and contents of the file specified in the environment variable <code>NSRANDFILE</code>
** the status information (<code>struct stat</code>) and contents of the files <code>/etc/passwd</code>, <code>/etc/utmp</code>
** the status information (<code>struct stat</code>) of the directories <code>/tmp</code>, <code>/var/tmp</code>, <code>/usr/tmp</code>
** the output of the <code>"netstat -ni"</code> command.
* On Windows, the extra entropy input includes
** various high-resolution clocks, such as <code>QueryPerformanceCounter</code>, <code>GetTickCount</code> and <code>time</code>, several times.
** information about the system's current usage of both physical and virtual memory returned by <code>GlobalMemoryStatus</code>
** the bitmask representing the currently available disk drives returned by <code>GetLogicalDrives</code>
** the NetBIOS name of the local computer returned by <code>GetComputerName</code>
** the pseudo handle and process identifier of the current process returned by <code>GetCurrentProcess</code> and <code>GetCurrentProcessId</code>
** information about the file system and volume of the root of the current directory returned by <code>GetVolumeInformation(NULL, ...)</code>
** information about the current disk, including the amount of free space on the current disk, returned by <code>GetDiskFreeSpace(NULL, ...)</code>
** the number of files in <code>C:\WINDOWS\system32</code> and the status information and contents of the first 10 readable files and then 10 or 11 files spread throughout the directory
'''References'''
Michael Howard and David C. LeBlanc, Writing Secure Code, Second Edition, Microsoft Press, 2002.
Michael Howard's Web Log, ''Cryptographically Secure Random number on Windows without using CryptoAPI'', http://blogs.msdn.com/michael_howard/archive/2005/01/14/353379.aspx.
D. Eastlake, 3rd, J. Schiller, and S. Crocker, RFC 4086 (formerly RFC 1750): Randomness Requirements for Security, June 2005.  This RFC recommends the use of /dev/urandom and CryptGenRandom.
Elaine Barker and John Kelsey, NIST Special Publication 800-90: Recommendation for Random Number Generation Using Deterministic Random Bit Generators, June 2006.
=Key Establishment Techniques=
The NSS cryptographic module uses the following asymmetric key establishment techniques listed in FIPS 140-2 Implementation Guidance Section 7.1, which FIPS 140-2 Annex D says are allowed in a FIPS Approved mode of operation:
* Diffie-Hellman (key agreement). The module supports Diffie-Hellman public key sizes of 1024-2236 bits, corresponding to 80-112 bits of security.
* EC Diffie-Hellman (key agreement). The module supports elliptic curve key sizes of 163-571 bits, corresponding to 80-256 bits of security.
* Key Wrapping using RSA keys (PKCS #1, key wrapping). The module supports RSA key sizes of 1024-8192 bits, corresponding to 80-192 bits of security. <div class=note>'''Note:''' The Cryptographic Algorithm Validation Program (CAVP) can only validate RSA key sizes up to 4096 bits, so our RSA algorithm implementation has only been validated for RSA key sizes of 1024-4096 bits.</div>
The strengths of security of the asymmetric key establishment techniques are obtained from Table 2 of Section 5.6.1, NIST SP 800-57 Part 1.
<div class=note>'''Caveats:'''
Since the NSS cryptographic module allows a key establishment method to establish a cryptographic key that is stronger than the key establishment method, the following caveats are required by FIPS 140-2 IG 7.5:
* Diffie-Hellman (key agreement, key establishment methodology provides between 80 bits and 112 bits of encryption strength)
* EC Diffie-Hellman (key agreement, key establishment methodology provides between 80 bits and 256 bits of encryption strength)
* RSA (PKCS #1, key wrapping, key establishment methodology provides between 80 bits and 192 bits of encryption strength)
The [http://www.mozilla.org/projects/security/pki/nss/fips/secpolicy.pdf Security Policy Rule 20] is also annotated with these caveats.
</div>
The NSS cryptographic module does not implement the Over-The-Air-Rekeying (OTAR) Protocol.
=Entity Association Assurance=
Each instance of the NSS cryptographic module is owned by a single operator (the ''module owner'').
By definition, all the secret and private keys in the NSS cryptographic module are associated with the module owner.
The public and private keys are correlated based on their PKCS #11 CKA_ID attribute. The public and private keys in a key pair have the same CKA_ID value. In the NSS cryptographic module, the CKA_ID attribute of a public key or private key is the SHA-1 hash of (a component of) the (associated) public key.
If a public key's CKA_ID value is the same as that of a private key in the NSS cryptographic module, the public key is associated with the module owner. Otherwise, the public key is associated with an entity other than the module owner. Such a public key is usually extracted from a public key certificate, which contains the name of the entity associated with the public key, and imported into the NSS cryptographic module. The operator of the NSS cryptographic module is responsible for associating such a public key with the right entity. The NSS cryptographic module only knows such a public key doesn't belong to the module owner because it doesn't have the associated private key.
The NSS cryptographic module returns unique PKCS #11 object handles (CK_OBJECT_HANDLE) for the stored or imported cryptographic keys. With the object handles as unique identifiers, the operator can associate the keys with the correct entity (self or another entity).
=Key Entry and Output Methods=
The NSS cryptographic module does not employ either manual or electronic key entry and output methods.
The NSS cryptographic module does not support entry of the seed key during key generation.
The NSS cryptographic module uses automated key transport methods, so the cryptographic key being transported needs to meet the key entry/output requirements (in Section 4.7.4 of FIPS 140-2). Automated key transport methods use the <code>FC_UnwrapKey</code> and <code>FC_WrapKey</code> functions.
* The <code>FC_UnwrapKey</code> function enters an encrypted secret or private key into the NSS cryptographic module.
* The <code>FC_WrapKey</code> function outputs an encrypted secret or private key from the NSS cryptographic module.
For example, in a TLS handshake with RSA key exchange, the NSS SSL library (outside the cryptographic module boundary) calls <code>FC_WrapKey</code> to output the premaster secret (encrypted with the server's RSA public key) from the cryptographic module on the client side, sends it to the server in the ClientKeyExchange message, and calls FC_UnwrapKey to enter the RSA-encrypted premaster secret into the cryptographic module on the server side.
Encrypted secret and private keys, entered into or output from the NSS cryptographic module and used in the FIPS Approved mode of operation, are encrypted using one of the following Approved algorithms:
* Key Wrapping using RSA keys
* AES
* Triple DES
<div class=note>'''Note:''' If the AES or Triple DES key is derived from a password, the encrypted secret or private key is considered to be in plaintext form because password-based encryption is not FIPS Approved.</div>
In the FIPS Approved mode of operation, secret keys, private keys, and TLS premaster secret may be established using automated methods (e.g., key transport protocols such as Key Wrapping using RSA keys). These keys can only be entered into or output from the NSS cryptographic module in encrypted form (using <code>FC_UnwrapKey</code> and <code>FC_WrapKey</code>).
=Random Number Generator=
There is only one random number generator (RNG) used in the NSS cryptographic module. The RNG is an Approved RNG, implementing Algorithm 1 of FIPS 186-2 Change Notice 1. (The RNG validation certificate is [http://csrc.nist.gov/cryptval/rng/rngval.html#208 Cert# 208].) The Approved RNG is used within the NSS cryptographic module for all cryptographic purposes, including the generation of cryptographic keys used by an Approved security function.
If the seed and seed key input to the Approved RNG have the same value, the Approved RNG returns a failure status code and doesn't produce any output. The check is done by the <code>memcmp</code> function call in the function <code>[http://www.mozilla.org/projects/security/pki/nss/fips/nss-source/mozilla/security/nss/lib/freebl/prng_fips1861.c.dep.html#FIPS186Change_GenerateX FIPS186Change_GenerateX]</code>:
            if (memcmp(XKEY_old, XSEEDj, BSIZE) == 0) {
                /* Should we add the error code SEC_ERROR_BAD_RNG_SEED? */
                PORT_SetError(SEC_ERROR_INVALID_ARGS);
                rv = SECFailure;
                goto done;
            }
=Key Zeroization=
The NSS cryptographic module performs explicit zeroization steps to clear the memory region previously occupied by a plaintext secret key, private key, or password. The function used to zeroize memory used by plaintext secret and private keys and passwords is the Standard C library function <code>memset()</code> or its synonym <code>PORT_Memset()</code>:
  #define PORT_Memset    memset
If the memory is allocated from the heap, the [http://www.mozilla.org/projects/security/pki/nss/fips/nss-source/mozilla/security/nss/lib/util/secport.c.dep.html#PORT_ZFree <code>PORT_ZFree()</code>] function can be used to both zeroize and free memory:
  void
  PORT_ZFree(void *ptr, size_t len)
  {
      if (ptr) {
          memset(ptr, 0, len);
          PR_Free(ptr);
      }
  }
(<code>PR_Free()</code> calls the Standard C library function <code>free()</code> to free memory allocated from the heap.)
A plaintext secret or private key is zeroized when it is deleted (with a <code>FC_DestroyObject</code> call).
All plaintext secret and private keys are zeroized when
* the NSS cryptographic module is shut down (with a <code>FC_Finalize</code> call),
* the NSS cryptographic module is reinitialized (with a <code>FC_InitToken</code> call), or
* the NSS cryptographic module switches between the FIPS and non-FIPS modes (with a <code>NSC_Finalize</code>/<code>FC_Initialize</code> or <code>FC_Finalize</code>/<code>NSC_Initialize</code> call sequence).
Passwords are automatically zeroized by the NSS cryptographic module immediately after use.
The <code>memset()</code> function is extremely fast. Zeroization can be performed in a time that is not sufficient to compromise plaintext secret and private keys and passwords.

Revision as of 23:22, 19 December 2006

Retrieved from "https://wiki.mozilla.org/index.php?title=VE_07KeyMgmt&oldid=44865"