JCE: add WolfSSLKeyStore (WKS) KeyStore implementation #67
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR adds a
KeyStore
implementation insideWolfSSLKeyStore.java
with the typeWKS
.This KeyStore has been designed to be compatible with wolfCrypt FIPS 140-2 and 140-3.
KeyStore Integrity
When a KeyStore is stored (
engineStore()
), an HMAC-SHA512 is calculated over the encoded contents and appended to the output. HMAC calculation is done over all store contents as well as PBKDF2 salt length, salt, and iteration count. HMAC key is derived from user-provided password using PBKDF2-HMAC-SHA512 with a random 16-byte salt. Iteration count defaults to 210,000 (current OWASP recommendation), but is user overridable withwolfjce.wks.iterationCount
Security property injava.security
file.When a KeyStore is loaded (
engineLoad()
), if a password has been provided, the HMAC-SHA512 is regenerated and compared in constant time to the encoded value. HMAC verification is skipped if no password has been provided, which is consistent with existing Java KeyStore (JKS) and allows for easy replacement use of system CA certificate stores such ascacerts.jks
, where users are not expected to provide the password when loading.PrivateKey and SecretKey Protection
PrivateKey and SecretKey objects stored are protected inside the KeyStore using AES-CBC-256 with HMAC-SHA512 in an Encrypt-then-MAC manner. PKCS#5 PBKDF2-HMAC-SHA512 is used to generate 96 bytes of key material which is split between a 32-byte AES-CBC-256 key and 64-byte HMAC-SHA512 key.
wolfjce.wks.iterationCount
Security property injava.security
file.char[]
tobyte[]
using UTF-8, consistent with how SunJCE uses UTF-8 for PBKDF2 SecretKeyFactory.Design Notes
More complete design documentation can be found in docs/WolfSSLKeyStore.md.
Tests
Tests have been added inside
src/test/java/com/wolfssl/provider/jce/test/WolfSSLKeyStoreTest.java
.Usage
README_JCE.md
has been updated with notes on using theWKS
type KeyStore, as well as notes on how to convert a JKS type KeyStore to WKS using the Javakeytool
application.System CA Cert Replacement
A script has been included at
examples/certs/systemcerts/system-cacerts-to-wks.sh
which can be used to try and convert the System CA/root certificate bundles to WKS type (ex: cacerts, jssecacerts files). Store passwords are updated from defaultchangeit
tochangeitchangeit
to meet wolfCrypt FIPS minimum HMAC key size limitation.Examples
New example WKS type KeyStore files have been added which are converted versions of our example JKS KeyStore files. The
examples/certs/update-jks-wks.sh
script has been added to easily re-convert JKS files if needed when they get updated. To confirm that Java keytool can parse WolfSSLKeyStore (WKS) format stores ok, theexamples/certs/keytool-print-wks.sh
script can be used. This will callkeytool -list
on each WKS KeyStore which is expected to pass successfully.ant test Output
Method and class names are now output to the terminal when running
ant test
, which should help users realize that tests are not stalled but are just running in the background.