Skip to content

Latest commit

 

History

History
301 lines (219 loc) · 9.05 KB

README_JCE.md

File metadata and controls

301 lines (219 loc) · 9.05 KB
Raw

wolfCrypt JCE Provider

The wolfCrypt JCE Provider is currently set up to be compiled together into the same JAR file as the normal wolfcrypt-jni classes.

The wolfCrypt JCE Provider is located in the following package:

com.wolfssl.wolfcrypt.jce.provider

Compiling the JCE provider is done using the same instructions as wolfcrypt-jni. Follow direction in the README.md for compiling the package, but make sure to use one of the following "ant" build targets:

build-jce-debug
build-jce-release

This JCE provider has been tested on OSX (Oracle JVM), Linux (OpenJDK), and Android platforms.

Pre-compiled and signed wolfCrypt JNI/JCE JAR's are included with the stable releases of the JCE provider. See below for more details.

System and Security Property Support

wolfJCE supports the following System and Security properties for behavior customization and debugging.

Security Property Support

The following Java Security properties can be set in the java.security file for JCE provider customization:

Security Property Default To Enable Description
wolfjce.wks.iterationCount 210,000 Numeric PBKDF2 iteration count (10,000 minimum)
wolfjce.wks.maxCertChainLength 100 Integer Max cert chain length

System Property Support

The following Java System properties can be set on the command line or programatically for JCE provider customization:

System Property Default To Enable Description
wolfjce.debug "false" "true" Enable wolfJCE debug logging

Algorithm Support:

The JCE provider currently supports the following algorithms:

MessageDigest Class
    MD5
    SHA-1
    SHA-256
    SHA-384
    SHA-512

SecureRandom Class
    DEFAULT (maps to HashDRBG)
    HashDRBG

Cipher Class
    AES/CBC/NoPadding
    AES/CBC/PKCS5Padding
    AES/GCM/NoPadding
    DESede/CBC/NoPadding
    RSA
    RSA/ECB/PKCS1Padding

Mac Class
    HmacMD5
    HmacSHA1
    HmacSHA256
    HmacSHA384
    HmacSHA512

Signature Class
    MD5withRSA
    SHA1withRSA
    SHA256withRSA
    SHA384withRSA
    SHA512withRSA
    SHA1withECDSA
    SHA256withECDSA
    SHA384withECDSA
    SHA512withECDSA

KeyAgreement Class
    DiffieHellman
    DH
    ECDH

KeyPairGenerator Class
    RSA
    EC
    DH

CertPathValidator Class
    PKIX

SecretKeyFactory
    PBKDF2WithHmacSHA1
    PBKDF2WithHmacSHA224
    PBKDF2WithHmacSHA256
    PBKDF2WithHmacSHA384
    PBKDF2WithHmacSHA512
    PBKDF2WithHmacSHA3-224
    PBKDF2WithHmacSHA3-256
    PBKDF2WithHmacSHA3-384
    PBKDF2WithHmacSHA3-512

KeyStore
    WKS

SecureRandom.getInstanceStrong()

When registered as the highest priority security provider, wolfJCE will provide SecureRandom with the underlying HashDRBG algorithm.

Java applications can alternatively call the SecureRandom.getInstanceStrong() API to get a "known strong SecureRandom implementation". To provide this with wolfJCE, the java.security file needs to be modified by setting the securerandom.strongAlgorithms property to:

securerandom.strongAlgorithms=HashDRBG:wolfJCE

Note that the securerandom.source property in java.security has no affect on the wolfJCE provider.

WolfSSLKeyStore (WKS) Implementation Details and Usage

wolfJCE implements one custom KeyStore class named WolfSSLKeyStore, represented as "WKS". If wolfJCE has been installed as a Security provider, this KeyStore can be used with:

KeyStore store = KeyStore.getInstance("WKS");

Algorithm Use and FIPS 140-2 / 140-3 Compatibility

The WKS KeyStore has been designed to be compatible with wolfCrypt FIPS 140-2 and 140-3.

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

This KeyStore uses a different format that is not directly compatible with existing formats (ex: JKS, PKCS12, etc). Other KeyStore types will need to be converted over to WKS KeyStore objects for FIPS compliant use with wolfCrypt FIPS 140-2/3.

Stored Object Compatibility

The WKS KeyStore supports storage of PrivateKey, Certificate, and SecretKey objects.

Converting Other KeyStore Formats to WKS

The Java keytool application can be used to convert between KeyStore formats. This can be easily used for example to convert a JKS KeyStore into a WKS format KeyStore.

The following example command would convert a KeyStore in JKS format named server.jks to a KeyStore in WKS format named server.wks:

keytool -importkeystore -srckeystore server.jks -destkeystore server.wks \
    -srcstoretype JKS -deststoretype WKS \
    -srcstorepass "pass" -deststorepass "pass" \
    -provider com.wolfssl.provider.jce.WolfCryptProvider \
    --providerpath /path/to/wolfcrypt-jni.jar

To list entries inside a WKS keystore using the keytool, a command similar to the following can be used (with the -list option):

keytool -list -provider com.wolfssl.provider.jce.WolfCryptProvider \
    --providerpath /path/to/wolfcrypt-jni.jar \
    -storetype WKS -storepass "pass" -keystore server.wks

If running the above commands gives an error about the native wolfcryptjni shared library not being found, you may need to add the library location to LD_LIBRARY_PATH (Linux) or DYLD_LIBRARY_PATH (Mac OSX), ie:

export LD_LIBRARY_PATH=/path/to/libwolfcryptjni.so:$LD_LIBRARY_PATH

Converting System cacerts to WKS Format KeyStore

For FIPS compatibility, users who do not want to use non-wolfSSL KeyStore implementations (ex: JKS) may need to convert the system cacerts or jssecacerts KeyStore to WKS format. This can be done using the keytool command as described above (default password for cacerts is 'changeit'), or the helper script located in this package at:

examples/certs/systemcerts/system-cacerts-to-wks.sh

This is a shell script that takes no arguments. It tries to detect the location of the active Java installation and converts cacerts and/or jssecacerts to WKS format if they are found. Converted KeyStores are placed under the same directory as the script, specifically:

examples/certs/systemcerts/cacerts.wks
examples/certs/systemcerts/jssecacerts.wks

Design Notes

More complete design documentation can be found in docs/WolfSSLKeyStore.md.

Example / Test Code

JUnit test code can act as a good usage reference, and is located under the ./src/test/java/com/wolfssl/provider/jce/test/ directory for each wolfJCE engine class.

There are some JCE examples located under the examples/provider directory, including:

ProviderTest

This is an example that prints out all Security providers that are registered in the system. It then programatically registers wolfJCE as the highest-level provider and prints out the list again.

This example will be built when using the following ant targets:

$ ant build-jce-debug
$ ant build-jce-release

The example can then be run using:

$ ./examples/provider/ProviderTest.sh

JAR Code Signing

The Oracle JDK/JVM requires that JCE providers who implement several of the classes above be signed by a code signing certificate issued by Oracle.

Full details on obtaining a JCE Code Signing Certifciate can be found here:

http://www.oracle.com/technetwork/java/javase/tech/getcodesigningcertificate-361306.html

For instructions on signing the "wolfcrypt-jni.jar" file generated by the ant build system, please see the main README.md included in this package.

Using a Pre-Signed JAR File

wolfSSL (company) has it's own set of code signing certificates from Oracle that allow wolfJCE to be authenticated in the Oracle JDK. With each release of wolfJCE, wolfSSL ships a couple pre-signed versions of the ‘wolfcrypt-jni.jar”, located at:

wolfcrypt-jni-X.X.X/lib/signed/debug/wolfcrypt-jni.jar wolfcrypt-jni-X.X.X/lib/signed/release/wolfcrypt-jni.jar

This pre-signed JAR can be used with the JUnit tests, without having to re-compile the Java source files. To run the JUnit tests against this JAR file:

$ cd wolfcrypt-jni-X.X.X $ cp ./lib/signed/release/wolfcrypt-jni.jar ./lib $ ant test

Support

Please email support@wolfssl.com with any questions or feedback.

The wolfJCE User Manual (PDF), available from the wolfSSL website contains additional details on using the wolfCrypt JCE provider.