Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

JCE: add WolfSSLKeyStore (WKS) KeyStore implementation #67

Merged
merged 2 commits into from
Jul 15, 2024

Conversation

cconlon
Copy link
Member

@cconlon cconlon commented Mar 15, 2024

This PR adds a KeyStore implementation inside WolfSSLKeyStore.java with the type WKS.

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 with wolfjce.wks.iterationCount Security property in java.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 as cacerts.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.

  • PBKDF2 salt is 16 bytes, randomly generated for each key storage operation
  • PBKDF2 iteration count defaults to 210,000 (current OWASP recommendation), but is user overridable with wolfjce.wks.iterationCount Security property in java.security file.
  • User password is converted from char[] to byte[] using UTF-8, consistent with how SunJCE uses UTF-8 for PBKDF2 SecretKeyFactory.
  • AES-CBC IV is randomly generated for each key storage operation

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 the WKS type KeyStore, as well as notes on how to convert a JKS type KeyStore to WKS using the Java keytool 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 default changeit to changeitchangeit 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, the examples/certs/keytool-print-wks.sh script can be used. This will call keytool -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.

@cconlon cconlon self-assigned this Mar 15, 2024
@cconlon cconlon force-pushed the KeyStore branch 2 times, most recently from 570a852 to 8747353 Compare May 9, 2024 22:34
@cconlon cconlon force-pushed the KeyStore branch 3 times, most recently from ab36f7a to dbe866a Compare June 21, 2024 21:00
@cconlon cconlon force-pushed the KeyStore branch 4 times, most recently from c687ade to da202d5 Compare July 5, 2024 19:57
@cconlon cconlon assigned JacobBarthelmeh and unassigned cconlon Jul 10, 2024
Copy link
Contributor

@JacobBarthelmeh JacobBarthelmeh left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Finished read through, going to do some run time tests yet. Thought I'd leave the current feedback here since I'm likely to not find anything the CI would not already have found with runtime tests.

@JacobBarthelmeh JacobBarthelmeh merged commit 5ce2d0e into wolfSSL:master Jul 15, 2024
31 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants