302 lines
9.0 KiB
Markdown
302 lines
9.0 KiB
Markdown
|
||
## 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](./docs/design/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.
|
||
|