# 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](https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html#pbkdf2)) 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](https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-132.pdf). 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.