Content

Introduction

The CXI API provides a general purpose Java interface to be used with the CryptoServer firmware module CXI.
To use this interface the firmware module must be loaded into the CryptoServer and the application must have been linked against the library file 'CryptoServerCXI.jar'.

The CXI API supports two operating modes:

Dedicated Mode: One instance of CXI represents a logical connection to one CryptoServer.
This mode has to be used if a dedicated CryptoServer should be addressed (e.g. for key management).
Cluster Mode: One instance of CXI represents a logical connection to a cluster of CryptoServers.
This mode supports a failover mechanism, that automatically switches to another CryptoServer in case of a communication error.
The API only returns an error if the communication to all devices failed or if the CryptoServer responds an application error.

See Programming Interface how to apply an operating mode.
The CXI API offers various cryptographic services:

Constructors
- create instance that represents a logical connection to a dedicated CryptoServer
- create instance that represents a logical connection to a cluster of CryptoServers
- create instance based on a configuration file (either dedicated or cluster)
Key Management
- key generation (DES, AES, RSA, ECDSA, DSA)
- import and export of keys
- backup and restore of keys
- get/set key properties
Cryptography
- encryption (DES, AES, RSA, ECIES)
- signature generation (ECDSA, RSA)
- signature verification (ECDSA, RSA)
- MAC calculation (DES, AES)
- MAC verification (DES, AES)
- calculation of shared secrets (ECDSA)
- generation of random bytes
- HASH/HMAC computation
Miscellaneous Functions
- execute arbitrary command on CryptoServer
- get version of CXI API and CXI firmware module

The complete class overview can be found here.

Key Storage

CXI identifies keys by their key name, key group and key specifier. The key name is mandatory, group and specifier are optional and may be omitted. In either case the combination of name, group and specifier has to be unique.
Keys can either be stored on the CryptoServer (internally) or on the host PC (externally). On generation or import of keys the application can decide whether to store the key internally (internalStorage = true) or externally (internalStorage = false).
An internal key is stored in the key database within the CryptoServer. The application receives a key handle linking to the key on the CryptoServer. In the case of an external key, the application receives a key blob containing key attributes and key components. Key components within a key blob are encrypted with the CryptoServer's Master Backup Key.
CXI offers a key store (KeyStore) that can be used to store external keys, but the application may also use other storage locations for external keys (e.g. key files).
Any function on the CryptoServer that needs a key as input parameter (e.g. encryption or signature creation) accepts both key handles and key blobs. If a key handle is given the key is loaded from the CryptoServer's key database. If a key blob is given the key is decrypted with the Master Backup Key. Essentially the usage of internal and external keys can be mixed.

Authentication

Any user who wants to execute security relevant commands on the CryptoServer has to authenticate to the CryptoServer. Some commands can either be executed by one user holding the exclusive permissions or by several users with shared permissions (e.g. Two-person/Four-eyes rule). In either case the CryptoServer adds all authenticated users' permission levels and checks whether the desired command may be executed.

The CryptoServer API supports the following authentication methods:

RSA Signature and ECDSA Signature
The command is signed with the private part of the RSA or ECDSA key and the CryptoServer verifies the signature with the public part of the key.
The private part of the key (used to create the signature) can be stored on the following media:
- plaintext key file
- password-encrypted key file
- smartcard (the smartcard reader has to be connected to the host PC)
In either case the public part of the key has to be imported into the CryptoServer on creation of the user.
RSA Smartcard
This method is a special case of RSA Signature, where the smartcard reader is directly connected to the CryptoServer.
HMAC password
Password authentication using a Hash-based Message Authentication Code.

Note
Smartcard users are not supported on a cluster of CryptoServers (see CryptoServerAPI.CryptoServerCluster).
In order to apply an authentication method a user with the corresponding authentication mechanism is needed. The authentication mechanism has to be assigned on creation of the user and can't be changed later on.

Pure authentication (without secure messaging) can be applied by using one of the prepareAuthenticationXXX methods (see CryptoServerAPI.CryptoServer).

Secure Messaging

Instead of authenticating every command, the CryptoServer API allows creation of an encrypted 'Secure Messaging' session with the CryptoServer. Thereby the user only authenticates the creation of the session (exchange of the session key). The session 'remembers' the permissions of all users being logged in. Any command sent through this session is automatically authenticated with the combined permissions of the users.

Note: If a session remains idle (no command was sent) for more than 15 minutes, the session expires and is automatically invalidated by the CryptoServer.
Use CryptoServerAPI.CryptoServer.keepSessionAlive() or CryptoServerAPI.CryptoServerCluster.keepSessionAlive() to prevent a session from expiring.

A session can be created using the getSessionKeyDH method (see CryptoServerAPI.CryptoServer).

In order to simplify session creation the following methods combine authentication and secure messaging:

Key Access Restrictions

Any user who wants to access an - internal or external - key has to authenticate to the CryptoServer (see above).

If a key has been assigned to a group (on key generation or import), it may only be accessed by a user who is a member of the same group. To achieve this, the user attribute 'CXI_GROUP' has to be set on creation of the user. The CXI_GROUP attribute may also contain wildcards '*' or question marks '?' in order to assign a user to multiple groups.
Examples:

User 1: CXI_GROUP=test
This user may only access keys with the group attribute 'test', other keys are 'invisible' for the user.
User 2: CXI_GROUP=test*
This user may only access whose entity attributes start with 'test' (e.g. 'test', 'test01', 'test_xxx'), other keys are 'invisible' for the user.
User 3: CXI_GROUP=*
This user is allowed to access all keys.

If no group attribute has been set for a key, the key may be accessed by all users regardless of their group membership.

Failover

CXI provides fault tolerant operation on a CryptoServer cluster. In case of communication errors the API automatically switches to the next device and tries to execute the command on that CryptoServer. Only if the API wasn't able to execute the command on any device, it gives up and throws an exception.
After having successfully switched to another device the API stays connected to this device and does not switch back. Optionally a fallback interval time may be configured causing the API to switch back to the first (primary) device of the device list after a certain amount of time.
CryptoServerCXI also provides an event handler interface to obtain information about state changes and errors occurring on the cluster.
By default the event handler messages are written to the default log file (see CxiLog ).
The application may also implement its own event handler and register it, see CryptoServerCluster.setEventHandler(CryptoServerCluster.EventHandler).

Programming Interface

In order to use the CXI API the application has to be linked against the CXI library file (CryptoServerCXI.jar).
The API consists of its main class CXI and several other classes that are needed to deal with objects (e.g. keys, properties, configuration).
Main class:

CryptoServerCXI

Other classes:

The complete class overview can be found here.

CXI offers three constructors to be used for different purposes:

\n Opens the specified CryptoServer with the given connection timeouts. Use this constructor if you want to use a single device exclusively.
\n Opens multiple CryptoServers as a cluster. Use this constructor if you want to set up a fault-tolerant system that supports failover.
CryptoServerCXI.CryptoServerCXI.CryptoServerCXI(CryptoServerAPI.CryptoServerConfig config)
Reads the device configuration from the given configuration file. Here you can either configure a single device (e.g. 'Device = PCI:0') or multiple devices as a cluster
(e.g. 'Device = PCI:0 192.168.4.1 192.168.4.2').

Note: Don't use cluster mode if a dedicated CryptoServer should be addressed!

Examples

The following code illustrates how to manage keys with the CXI API:

import CryptoServerAPI.*;
import CryptoServerCXI.*;
 
// create instance of CryptoServerCXI (opens connection to CryptoServer)
CryptoServerCXI cxi = new CryptoServerCXI("192.168.4.1", 3000);
cxi.setTimeout(60000);
 
// logon a user with smartcard authentication (has to be a member of group 'test')
cxi.logonSign("CXI_RSA", ":cs2:cyb:USB0", NULL);
 
// create a key
CryptoServerCXI.KeyAttributes attr = new CryptoServerCXI.KeyAttributes();
attr.setAlgo(CryptoServerCXI.KEY_ALGO_AES);
attr.setSize(256); 
attr.setGroup("test");
attr.setName("AES test key");
 
CryptoServerCXI.Key aesKey = cxi.generateKey(attr, 0, true);

The following code illustrates how to use cryptographic functions:

import CryptoServerAPI.*;
import CryptoServerCXI.*;
 
// create configuration object
CryptoServerConfig config = new CryptoServerConfig("d:/temp/cxi.cfg");
 
// create new Cxi object with the given configuration
CryptoServerCXI cxi = new CryptoServerCXI(config);
 
// logon a user with password mechanism (has to be a member of group 'test')
cxi.logonPass("CXI_HMAC", "utimaco");
 
// open previously generated AES key
CryptoServerCXI.KeyAttributes attr = new CryptoServerCXI.KeyAttributes(); 
attr.setGroup("test");
attr.setName("AES test key");
 
CryptoServerCXI.Key aesKey = cxi.findKey(attr, true);
 
// encrypt data with the key
byte [] data = "Yes we can".getBytes();
int mech = CryptoServerCXI.MECH_MODE_ENCRYPT | CryptoServerCXI.MECH_CHAIN_CBC | CryptoServerCXI.MECH_PAD_PKCS5;
byte [] crypto = cxi.crypt(key, mech, null, data, null);
CryptoServerUtil.xtrace("encrypted data", crypto); 

Supported Algorithms

The CXI firmware module supports the following algorithms and mechanisms:

Algorithm	Key Sizes [bit]	Mode	Chaining	Padding
DES	56,112,168	Encryption, Decryption	ECB, CBC	None, PKCS#5, ISO7816, Random
DES	56,112,168	Mac	CBC, CBC-Retail, CFB-Retail	None, Zero, PKCS#5, ISO7816, Random
AES	128,192,256	Encryption, Decryption	ECB, CBC, GCM, CCM	None, PKCS#5, ISO7816, Random
AES	128,192,256	Mac	CBC, GMAC	None, Zero, PKCS#5, ISO7816, Random
RSA	512...16384 (delta = 1bit)	Encryption, Decryption	-	None, PKCS#1, PKCS-OAEP
RSA	512...16384 (delta = 1bit)	Sign, Verify	-	PKCS#1, X9.31, PKCS-PSS
ECDSA	Brainpool: 160..512 NIST: 192..521 secp: 112..571	Encryption, Decryption (ECIES)	-	-
ECDSA	Brainpool: 160..512 NIST: 192..521 secp: 112..571

Sign, Verify
(Raw Format, ASN.1 Format)

-

DSA

P: 512..1024, Q: 160

Sign, Verify

-

The following hash algorithms are supported:

SHA1
SHA224
SHA256
SHA384
SHA512
SHA3-224
SHA3-256
SHA3-384
SHA3-512
MD5
RipeMD160

Installation

Step 1:

Load the firmware module package (e.g. SecurityServer-XX-Series-x.x.x.mpkg) into the CryptoServer.

Example:
csadm <authentication> LoadPkg=SecurityServer-Se2-Series-4.01.0.5.mpkg

Step 2:

Create one or more users with authentication mechanism either HMAC-password or signature (RSA, ECDSA) and the following properties:

permission of level 2 in group 0 ('00000002').
attribute 'CXI_GROUP=<key-group>', where 'key-group' represents the group of keys the user will be allowed to access.
Use wildcards ('*', '?') to assign a user to multiple groups.

Example:
csadm <authentication> AddUser=<username>,00000002{CXI_GROUP=test*},hmacpwd,<password>

Requirements

Java jurisdiction policy file

There are US laws restricting the export of software containing "strong" cryptographic mechanisms. Therefore the SUN JCE provider (which is used by the CXI API) does not support "strong" encryption by default, leading to an exception in the CXI API. To remove these restrictions, please download the package called "unlimited strength jurisdiction policy files" from Oracle's website (unfortunately Oracle's general terms and conditions do not allow packaging these files).
After this replace the old files local_policy.jar and US_export_policy.jar in the folder <java-installation-path>\<java-jre-name>\lib\security by the newly downloaded ones. Now the provider can make use of all cryptographic algorithms and the exception should not longer occur.

Microsoft Visual C++ 2008 SP1 redistributable package

On Microsoft Windows the CXI API requires the redistributable package runtime library to be installed. It is required to run applications developed with Visual C++ 2008 SP1 on a PC that have no Visual C++ 2008 SP1 installed. The package is automatically installed on installation of the Utimaco CryptoServer Product CD, but it also can be obtained from the Microsoft websites (a version for 32 bit and 64 bit is available).