WolfSSLKeyStore.md

wolfSSL KeyStore (WKS) Design Notes

The WKS KeyStore format was designed to be compatible with wolfCrypt FIPS 140-2 and 140-3, meaning it utilizes FIPS validated cryptographic algorithms. This document includes notes on the design and algorithm choices used by WKS. For details on the wolfCrypt FIPS 140-2/3 cryptographic module and boundary, please reference the appropriate Security Policy or contact fips@wolfssl.com.

User Customizable Properties

Security Property	Default	Min	Description
wolfjce.wks.iterationCount	210,000	10,000	PBKDF2 iteration count
wolfjce.wks.maxCertChainLength	100	N/A	Max cert chain length

Notes on Algorithm and Security Properties

PBKDF2-HMAC-SHA512 was chosen over PBKDF2-HMAC-SHA256 for AES and HMAC key generation to allow use of fewer iterations (210,000, as per current OWASP recommendations) versus the recommended 600,000 for SHA-256.

PBKDF2 salt size of 128-bits (16 bytes) is used to follow recommendations in NIST SP 800-132, Page 6.

AES-CBC (AES/CBC/PKCS5Padding) was chosen over AES-GCM since AES-GCM requires that each {key,nonce} combination be unique. Simply generating a random nonce via RNG does not guarantee uniqueness, and we have no way of maintaining an accurate counter across KeyStore objects and store/load operations.

Different keys are used for PrivateKey/SecretKey encryption and HMAC, and derived from one larger PBKDF2 operation (96 bytes) then split between encryption (32-byte key) and HMAC (64-byte key) operations. A random salt is generated for each PBKDF2 key generation operation.

HMAC values are calculated over content but also the PBKDF2 salt length, salt, and iteration count, and all other key parameters (ex: IV and length) to also include those in the integrity check.

KeyStore Integrity

HMAC Generation During KeyStore Storage

When WKS KeyStore objects are stored (engineStore()), the following format is used. This is composed of a HEADER section, an ENTRIES section, followed lastly by an HMAC generated over the HEADER and ENTRIES, including the PBKDF2 salt, salt length, and iteration count.

The HEADER includes a magic number specific to the WKS KeyStore type (7), a WKS KeyStore version (may be incremented in the future as features are added or if the WKS type definition changes), and a count of the entries included in the store.

The ENTRIES section is made up of one or more WKSPrivateKey, WKSSecretKey, or WKSCertificate entries. These represent the storage of a PrivateKey, SecretKey, and Certificate objects respectively.

Generation of the HMAC happens during a call to engineStore(OutputStream stream, char[] password) and is generated in the following manner:

• Input password must not be null or zero length
• Input password is converted from char[] into byte[] using password conversion algorithm described below.
• Random salt of size WKS_PBKDF2_SALT_SIZE (128 bits) is generated
• HMAC-SHA512 key (64-bytes) is generated with PBKDF2-HMAC-SHA512 using:
  • Password byte array
  • Random 16-byte salt (WKS_PBKDF2_SALT_SIZE)
  • 210,000 iterations (WKS_PBKDF2_ITERATION_COUNT), but can be overriden by user by setting wolfjce.wks.iterationCount Security property. Minimum iteration count is 10,000.
• The final HMAC-SHA512 is calculated using the derived key over the bytes of HEADER, ENTRIES, salt length, salt, and iteration count. It is then written out to the OutputStream.

HMAC Verification During KeyStore Load

When a WKS KeyStore is loaded with engineLoad(InputStream stream, char[] password), the input password is optional. If a password is provided, the KeyStore integrity will be checked using the included HMAC, otherwise the integrity check will be skipped. This design is to maintain consistency with how the Java JKS format handles integrity checks upon KeyStore load, and allows for easy conversion and use of files such as cacerts to a WKS type where users do not normally provide the password when loading the KeyStore file.

Since the HMAC is stored at the end of the KeyStore stream, engineLoad() buffers KeyStore bytes as they are read in, up to and including the PBKDF2 salt size, salt, and PBKDF2 iteration count. Once all entries have been read, the HMAC is read and verified:

• The salt length is read, sanitized against WKS_PBKDF2_SALT_SIZE
• The salt is read
• The PBKDF2 iteration count is read, and checked against min size of WKS_PBKDF2_MIN_ITERATIONS
• Caching of data is paused while the HMAC is read in next
• The original HMAC length is read
• An HMAC-SHA512 is regenerated over the buffered header and entry bytes
  • Password is converted from char[] to byte[] as explained below
  • An HMAC-SHA512 key (64-bytes) is calculated as explained above, using salt that was read from input KeyStore stream
  • The generated HMAC value is calculated using this key
• The generated HMAC is compared in both size and contents against the stored HMAC. If these are different, an IOException is thrown.

Stored WKS format:

 *   HEADER:
 *     magicNumber                       (int / 7)
 *     keystoreVersion                   (int)
 *     entryCount                        (int)
 *   ENTRIES (can be any of below, depending on type)
 *     [WKSPrivateKey]
 *       entryId                         (int / 1)
 *       alias                           (UTF String)
 *       creationDate.getTime()          (long)
 *       kdfSalt.length                  (int)
 *       kdfSalt                         (byte[])
 *       kdfIterations                   (int)
 *       iv.length                       (int)
 *       iv                              (byte[])
 *       encryptedKey.length             (int)
 *       encryptedKey                    (byte[])
 *       chain.length                    (int)
 *       FOR EACH CERT:
 *         chain[i].getType()            (UTF String)
 *         chain[i].getEncoded().length  (int)
 *         chain[i].getEncoced()         (byte[])
 *       hmac.length                     (int)
 *       hmac (HMAC-SHA512)              (byte[])
 *     [WKSSecretKey]
 *       entryId                         (int / 3)
 *       alias                           (UTF String)
 *       creationDate.getTime()          (long)
 *       key.getAlgorithm()              (UTF String)
 *       kdfSalt.length                  (int)
 *       kdfIterations                   (int)
 *       kdfSalt                         (byte[])
 *       iv.length                       (int)
 *       iv                              (byte[])
 *       encryptedKey.length             (int)
 *       encryptedKey                    (byte[])
 *       hmac.length                     (int)
 *       hmac (HMAC-SHA512)              (byte[])
 *     [WKSCertificate]
 *       entryId                         (int / 2)
 *       alias                           (UTF String)
 *       creationDate.getTime()          (long)
 *       cert.getType()                  (UTF String)
 *       cert.getEncoded().length        (int)
 *       cert.getEncoced()               (byte[])
 *   HMAC PBKDF2 salt length             int
 *   HMAC PBKDF2 salt                    (byte[])
 *   HMAC PBKDF2 iterations              int
 *   HMAC length                         int
 *   HMAC (HMAC-SHA512)                  (byte[])

PrivateKey Protection

A PrivateKey entry is stored into the KeyStore with the engineSetKeyEntry() method, exposed publicly through KeyStore as setKeyEntry(), when passing in a Key of type PrivateKey. The password argument is not allowed to be null, otherwise a KeyStoreException is thrown.

void setKeyEntry(String alias, Key key, char[] password, Certificate[] chain)

Process of storing a PrivateKey is as follows:

• Sanity check the certificate chain:
  • Chain is not null or zero length chain
  • Chain is made up of X509Certificate objects
  • Chain cert signatures are correct as we walk up the chain. The cert chain should be ordered from leaf cert (entity) to top-most intermedate certificate. The last cert is loaded as a trusted root, and used to verify the rest of the chain, since we don't have the root CA cert available at this point.
• Verify private key (Key key) matches the leaf certificate (chain[0])
• Encrypt private key before storing into KeyStore map:
  • Generate random PBKDF2 salt, of size WKS_PBKDF2_SALT_SIZE bytes
  • Generate random IV, of size WKS_ENC_IV_LENGTH bytes
  • Convert password from char[] into byte[] using password conversion algorithm described below.
  • Encryption key is derived using PBKDF2-SHA256 using byte array, random salt, and WKS_PBKDF2_ITERATION_COUNT (or customized) iteration count.
    • 96-byte key is generated with PBKDF2 in total, split between 32-byte AES-CBC-256 and 64-byte HMAC-SHA512 keys.
  • Encrypt key bytes using AES-CBC-256
  • Generate HMAC-SHA512 over encrypted key and other WKSPrivateKey object members
  • Zeroize KEK and HMAC keys (generated from PBKDF2)

When importing a PrivateKey from a KeyStore stream, the process is reversed. Initially during engineLoad(), parameters are read in as well as the encrypted key:

• Read PBKDF2 salt length, sanity check against WKS_PBKDF2_SALT_SIZE
• Read PBKDF2 salt
• Read PBKDF2 iterations, sanity check against WKS_PBKDF2_MIN_ITERATIONS
• Read encryption IV, santiy check against WKS_ENC_IV_LENGTH
• Read encrypted key
• Read certificate chain if present, check length against WKS_MAX_CHAIN_COUNT
• Read HMAC value into object variable, will be checked when user gets key out

The PrivateKey is stored encrypted internal to the WolfSSLKeyStore until a caller retrieves it with getKey(). At that point, WolfSSLKeyStore:

• Derives the decryption key using PBKDF2-SHA256
  • Converts password from char[] to byte[] using algorithm below
  • Uses salt and iteration count stored internally from encryption process or read from KeyStore stream after loading
  • Derives decryption key and HMAC key with PBKDF2-HMAC-SHA512
  • Regenerate and verify HMAC against stored value
  • Decrypts key using AES-CBC-256
  • Zeroizes KEK and HMAC keys (generated from PBKDF2)

SecretKey Protection

A SecretKey entry is stored into the KeyStore with the engineSetKeyEntry() method, exposed publicly through KeyStore as setKeyEntry(), when passing in a Key of type SecretKey. The password argument is not allowed to be null, otherwise a KeyStoreException is thrown.

void setKeyEntry(String alias, Key key, char[] password, Certificate[] chain)

Process of storing a SecretKey is the same as PrivateKey above, except there is no certificate so no certifiate or private key sanity checks are done. The same encrypt/decrypt process is shared between PrivateKey and SecretKey protection.

Certificate Protection

A Certificate entry is stored into the KeyStore with the engineSetCertificateEntry() method. Certificate entries are not protected and are stored directly into the KeyStore.

They are integrity protected by the KeyStore HMAC when a KeyStore is written out to a stream with engineStore(), but otherwise have no internal encryption or integrity protection since no password is provided when storing certificates.

Password Conversion Algorithm

The Java KeyStore class specifies that passwords are provided by the user as a Java character array (char[]). Before using a password as input to PBKDF2, wolfJCE is converts it into a byte array. In Java, one character (char) is composed of two bytes (byte). RFC 2898 (PBKDF2) considers a password to be an octet string and recommends for interop ASCII or UTF-8 encoding be used. SunJCE uses UTF-8 for PBKDF2 SecretKeyFactory, so we do the same in WolfSSLKeyStore using WolfCryptSecretKeyFactory.passwordToByteArray(char[]).

Support

Please email support@wolfssl.com with any questions.