 |
JCE Provider
|
|
JCE Provider
|
| Copyright: | 2024 by Utimaco IS GmbH Office Aachen Germanusstrasse 4 D-52080 Aachen |
| Phone: | +49 241-1696-200 |
| Telefax: | +49 241-1696-222 |
| Internet: | www.utimaco.com |
| Mail: | support-cs@utimaco.com |
| Document-Number: | 20100001 |
| Document-Version: | 1.2.0 |
| Date: | 10.10.2024 |
| Author | Dipl.-Ing. (FH) Sebastian Pranzkat |
| All rights reserved: | No part of this documentation may be reproduced or processed, copied, distributed by a retrieval system in any form (print, photocopies or any other means) without prior written consent of Utimaco IS GmbH. Utimaco IS GmbH reserves the right to modify or supplement the documentation at any time without previous announcement. Utimaco IS GmbH is not liable for misprints and damage resulting from this. |
This document describes the Java Cryptographic Engine Provider (JCE) for Utimaco IS hardware security module CryptoServer.
JCE is a cryptographic extension to Oracle's Java framework. It defines a unified interface between an application and a cryptographic device. With this concept a Java application must not know about specific drivers to access the CryptoServer directly.
In order to use the CryptoServer JCE provider, the firmware module CXI must be loaded into the CryptoServer and the CryptoServer JCE provider must be installed on the host system.
The CryptoServer JCE Provider needs the runtime environment of Java Framework 1.8 or higher.
In addition the Java security policy has to be configured to support unlimited algorithm strength. To achieve this, the appropriate jurisdiction policy files have to be installed (see Chapter Provider Installation).
To work with JCE, your CryptoServer requires the CXI firmware module and its dependencies. All necessary firmware modules should already be installed on your CryptoServer. For more information about firmware packages, see [1].
The Utimaco CryptoServer JCE Provider supports a failover mechanism if two or more CryptoServer have been configured as a cluster (see Chapter Configuration File). If command execution fails on one device the provider automatically switches to another device, connects and authenticates to it and tries to execute the command on that device. The provider consecutively tries to execute the command on one device at a time and throws an exception if all devices fail.
In order to use the failover feature the following conditions must be fulfilled:
CryptoServerJCE.cfg).
|
In order to install the CryptoServer JCE provider statically on the system the following steps have to be performed:
CryptoServerJCE.jar to the directory <java-home>/lib/ext java.security, located in <java-home>/lib/security: <n>: denotes the preference order of the provider<configuration-file>: optionally defines the path to a configuration file to be loaded by the providerUS_export_policy.jar local_policy.jar <java-home>/lib/security. Alternatively the CryptoServer JCE Provider can be used dynamically by simply copying the file CryptoServerJCE.jar to the <class-path> directory. In this case the above steps can be skipped.
The CryptoServer JCE provider can read parameters from a configuration file. This file may contain the following parameter:
| Parameter | Description | Default |
|---|---|---|
| Device | Device address(es) to connect a single CryptoServer or a CryptoServer cluster (see below). | - |
| Timeout | Specifies the maximum time in milliseconds to wait before a command is aborted if the device is not responding. | 30000 |
| ConnectionTimeout | Specifies the maximum time in milliseconds to wait if a connection to the device cannot be established. | 3000 |
| DefaultUser | Default user name to be used to authenticate to the CryptoServer | JCE |
| KeyGroup | Key Group property to be set on generation and import of a key | - |
| KeepSessionAlive | Keeps a session alive and prevents it from expiring after 15 minutes idle time. | 0 |
| EndSessionOnShutdown | Enables a hook to release the resources (cluster, session, etc) when a controlled process shuts down the JVM (1 = Enabled, 0 = Disabled). | 0 |
| StoreKeysExternal | Store keys in external keystore | False |
| KeyStorePath | Path to the external keystore | - |
| KeyStoreType | Type of the external keystore. If present, the value can be ODBC or Legacy. | - |
| LogFile | Path to logging file | - |
| LogLevel | loglevel to be logged (0 = NONE; 1 = ERROR; 2 = WARNING; 3 = INFO; 4 = TRACE;) | 2 |
| LogSize | Maximum size of logfile in kilobytes | 10000 |
| HashProvider | Provider-name to be used for Hashing and RNG (value CryptoServer means calculation by SW, HSM means calculation by HW). | CryptoServer |
There are several possibilities to address the CryptoServer with the Device configuration parameter. Here are some examples:
| Address | Description |
|---|---|
/dev/cs2.0 | Local CryptoServer in a Linux system. |
PCI:0 | Local CryptoServer in a Windows system. |
TCP:cslan01 | Hostname of a CryptoServer LAN |
TCP:194.168.4.107 | IP-Address of a CryptoServer LAN |
TCP:288@cslan01 | Host name and port number of a CryptoServer LAN |
TCP:288@194.168.4.107 | IP-Address and port number of a CryptoServer LAN |
Example of the configuration file CryptoServer.cfg:
If multiple devices should be addressed the devices have to be separated with a space character. The parameter definition may span across multiple lines, each line has to be terminated by a backslash charter (\).
Example of the configuration-file CryptoServer.cfg in case of a cluster:
The location of the configuration file is evaluated by the CryptoServer JCE Provider using the following search order:
CryptoServer.cfg is placed into the user's home directory. | Algorithm | Padding Modes |
|---|---|
| NonewithRSA | PKCS1 |
| SHA1withRSA | PKCS1, PSS |
| SHA224withRSA | PKCS1, PSS |
| SHA256withRSA | PKCS1, PSS |
| SHA384withRSA | PKCS1, PSS |
| SHA512withRSA | PKCS1, PSS |
| SHA3-224withRSA | PKCS1, PSS |
| SHA3-256withRSA | PKCS1, PSS |
| SHA3-384withRSA | PKCS1, PSS |
| SHA3-512withRSA | PKCS1, PSS |
| MD5withRSA | PKCS1, PSS |
| SHA1withECDSA | - |
| SHA224withECDSA | - |
| SHA256withECDSA | - |
| SHA384withECDSA | - |
| SHA512withECDSA | - |
| SHA3-224withECDSA | - |
| SHA3-256withECDSA | - |
| SHA3-384withECDSA | - |
| SHA3-512withECDSA | - |
| MD5withECDSA | - |
| NONEwithDSA | - |
| SHA1withDSA | - |
| SHA224withDSA | - |
| SHA256withDSA | - |
| SHA384withDSA | - |
| SHA512withDSA | - |
| SHA3-224withDSA | - |
| SHA3-256withDSA | - |
| SHA3-384withDSA | - |
| SHA3-512withDSA | - |
| NONEwithDSAinP1363Format | - |
| SHA1withDSAinP1363Format | - |
| SHA224withDSAinP1363Format | - |
| SHA256withDSAinP1363Format | - |
| NONEwithECDSAinP1363Format | - |
| SHA1withECDSAinP1363Format | - |
| SHA224withECDSAinP1363Format | - |
| SHA256withECDSAinP1363Format | - |
| SHA384withECDSAinP1363Format | - |
| SHA512withECDSAinP1363Format | - |
| Algorithm |
|---|
| RSA |
| EC |
| DSA |
| Algorithm |
|---|
| RSA |
| EC |
| DSA |
| Algorithm |
|---|
| DES |
| DESede |
| AES |
| Algorithm |
|---|
| CryptoServer |
| Algorithm |
|---|
| SHA1PRNG |
| CryptoServer |
| Algorithm |
|---|
| DES |
| DESede |
| AES |
| Algorithm | Block Modes | Padding Modes |
|---|---|---|
| DES | ECB, CBC | NONE, PKCS5, ISO10126 |
| DESede | ECB, CBC | NONE, PKCS5, ISO10126 |
| AES | ECB, CBC, OFB | NONE, PKCS5, ISO10126 |
| AES | GCM, CCM | NONE |
| RSA | - | NONE, PKCS1, OAEP |
| Algorithm | Block Modes | Padding Modes |
|---|---|---|
| DES | CBC | NONE |
| DESwithPKCS5Padding | CBC | PKCS5 |
| DESwithISO10126Padding | CBC | ISO10126 |
| AES | CBC | NONE |
| AESwithPKCS5Padding | CBC | PKCS5 |
| AESwithISO10126Padding | CBC | ISO10126 |
| Algorithm | Modes |
|---|---|
| DES | HmacMD5 |
| DES | HmacSHA1 |
| DES | HmacSHA224 |
| DES | HmacSHA256 |
| DES | HmacSHA384 |
| DES | HmacSHA512 |
| DES | HmacSHA3-224 |
| DES | HmacSHA3-256 |
| DES | HmacSHA3-384 |
| DES | HmacSHA3-512 |
| DES | HmacRMD160 |
| AES | HmacMD5 |
| AES | HmacSHA1 |
| AES | HmacSHA224 |
| AES | HmacSHA256 |
| AES | HmacSHA384 |
| AES | HmacSHA512 |
| AES | HmacSHA3-224 |
| AES | HmacSHA3-256 |
| AES | HmacSHA3-384 |
| AES | HmacSHA3-512 |
| AES | HmacRMD160 |
| Modes |
|---|
| MD5 |
| SHA-1 |
| SHA-224 |
| SHA-256 |
| SHA-384 |
| SHA-512 |
| SHA3-224 |
| SHA3-256 |
| SHA3-384 |
| SHA3-512 |
| RMD-160 |
1.9.5