Command Flags

Collaboration diagram for Command Flags:

Modules
	Key Components

Classes
class	CryptoServerCXI.Key
	This class is used to encapsulate CXI keys. More...
class	CryptoServerCXI.KeyFile
	This class is used to write the public components of an RSA key into a keyfile. More...
class	CryptoServerCXI.KeyAttributes
	This class provides methods to create and handle key attribute (property) lists. More...
class	CryptoServerCXI.KeyComponents
	This class provides methods to create and handle key component lists. More...
class	CryptoServerCXI.MechanismParameter
	This class is used to construct a mechanism parameter which provides additional, mechanism-specific information. More...
class	CryptoServerCXI.MechParamOAEP
	This class is used to construct a mechanism parameter for RSA encryption / decryption with PKCS#1_v2.1 RSAES-OAEP padding scheme. More...
class	CryptoServerCXI.MechParamPSS
	This class is used to construct a mechanism parameter for RSA signature creation / verification with PKCS#1_v2.1 RSASSA-PSS padding scheme. More...
class	CryptoServerCXI.MechParamECIES
	This class is used to construct a mechanism parameter for 'Elliptic Curve (Augmented) Encryption Scheme' (ECIES, see ANSI X9.63). More...
class	CryptoServerCXI.MechParamGCM
	This class is used to construct a mechanism parameter for AES encryption / decryption with GCM (Galois Counter Mode, see NIST SP-800-38D) chaining. More...
class	CryptoServerCXI.MechParamGMAC
	This class is used to construct a mechanism parameter for AES MAC creation / verification with 'Galois Counter MAC' chaining (GMAC, see NIST SP-800-38D). More...
class	CryptoServerCXI.MechParamCCM
	This class is used to construct a mechanism parameter for AES encryption / decryption in mode Counter with CBC-MAC (CCM, see NIST SP-800-38C). More...
class	CryptoServerCXI.KeyAttAndComp
	This class is used to encapsulate key attributes (see KeyAttributes) and key components (see KeyComponents) of a key. More...
class	CryptoServerCXI.ECPublicKey
	This class provides methods to create and handle public EC keys. More...
class	CryptoServerCXI.ECParameter
	This class provides methods to handle EC domain parameters. More...
class	CryptoServerCXI.KeyStore
	Key storage for external (MBK encrypted) keys More...
class	CryptoServerCXI.ByteArray
	Flexible byte array. More...

Functions
static double	getVersion ()
	Returns the version of the CXI API (x.xx).
	Key (byte[] value) throws CryptoServerException
	Creates a key object from the given data. More...
boolean	isHandle ()
	Inquires if the key contains a key handle. More...
byte[]	getEncoded ()
	Returns the key in its encoded (serialized) form. More...
KeyAttributes	getAttributes () throws CryptoServerException
	Returns the key attributes. More...
byte[]	getUName () throws NoSuchAlgorithmException, CryptoServerException
	Returns the unique key name. More...
	KeyAttributes ()
	Creates an empty key attribute list.
	KeyAttributes (byte[] list, int ofs) throws CryptoServerException
	Creates a key attribute list from the given (serialized) attribute stream. More...
	KeyAttributes (byte[] list) throws CryptoServerException
	Creates a key attribute list from the given (serialized) attribute stream. More...
KeyAttributes	clone ()
	Creates a full copy of the source object. More...
byte[]	toByteArray () throws CryptoServerException
	Serializes the attribute list and returns an attribute stream. More...
void	setAlgo (int algo)
	Sets the key algorithm attribute. More...
int	getAlgo ()
	Returns the key algorithm attribute. More...
void	setType (int type)
	Sets the key type attribute. More...
int	getType ()
	Returns the key type attribute (see Key Types).
void	setSize (int size)
	Sets the key size. More...
int	getSize ()
	Returns the key size in bits. More...
void	setExport (int exp)
	Sets the key export attribute. More...
int	getExport ()
	Returns the key export attribute. More...
void	setUsage (int usage)
	Sets the key usage attribute. More...
int	getUsage ()
	Returns the key usage attribute. More...
void	setLabel (String label) throws CryptoServerException
	Sets the key label attribute. More...
String	getLabel () throws CryptoServerException
	Returns the key label attribute. More...
void	setExponent (byte[] exp)
	Sets the public exponent of a RSA key. More...
void	setExponent (BigInteger exp)
	Sets the public exponent of a RSA key. More...
byte[]	getExponent ()
	Returns the public exponent of a RSA key. More...
void	setModulus (byte[] mod)
	Sets the modulus of a RSA key. More...
void	setModulus (BigInteger mod)
	Sets the modulus of a RSA key. More...
byte[]	getModulus ()
	Returns the modulus of a RSA key. More...
void	setParamP (byte[] par)
	Sets the prime value P of a DSA key. More...
void	setParamP (BigInteger par)
	Sets the prime value P of a DSA key. More...
byte[]	getParamP ()
	Returns the prime value P of a DSA key. More...
void	setParamQ (byte[] par)
	Sets the prime value Q of a DSA key. More...
void	setParamQ (BigInteger par)
	Sets the prime value Q of a DSA key. More...
byte[]	getParamQ ()
	Returns the prime value Q of a DSA key. More...
void	setParamG (byte[] par)
	Sets the generator value G of a DSA key. More...
void	setParamG (BigInteger par)
	Sets the generator value G of a DSA key. More...
byte[]	getParamG ()
	Returns the generator value G of a DSA key.
void	setDSAPub (byte[] par)
	Sets the public key part of a DSA key. More...
void	setDSAPub (BigInteger par)
	Sets the public key part of a DSA key. More...
byte[]	getDSAPub ()
	Returns the public key part of a DSA key.
void	setCurve (String name) throws CryptoServerException
	Sets the domain parameter of an ECDSA key. More...
void	setCurve (byte[] curve)
	Sets the domain parameter of an ECDSA key. More...
void	setCurve (ECParameterSpec curve) throws CryptoServerException
	Sets the domain parameter for an ECDSA key. More...
byte[]	getCurve ()
	Returns the domain parameters for a ECDSA key. More...
byte[]	getCurveEncoded () throws IOException, CryptoServerException
	Returns the domain parameters for a ECDSA key. More...
void	setECPub (byte[] par)
	Sets the public key part of a ECDSA key. More...
void	setECPub (BigInteger par)
	Sets the public key part of a ECDSA key. More...
byte[]	getECPub ()
	Returns the public key part of a ECDSA key. More...
void	setName (String name) throws CryptoServerException
	Sets the key name attribute. More...
String	getName () throws CryptoServerException
	Returns the key name. More...
void	setGroup (String group) throws CryptoServerException
	Sets the key group attribute. More...
String	getGroup () throws CryptoServerException
	Returns the key group. More...
void	setSpecifier (int spec)
	Sets the key specifier attribute. More...
int	getSpecifier ()
	Returns the key specifier. More...
void	setGenerationDate (Date date)
	Sets the generation date attribute of the key. More...
void	setGenerationDate (byte[] utcTime)
	Sets the generation date attribute of the key. More...
void	setExpirationDate (Date date)
	Sets the expiration date attribute of the key. More...
void	setExpirationDate (byte[] utcTime)
	Sets the expiration date attribute of the key. More...
Date	getGenerationDate ()
	Returns the generation date attribute or null if the data attribute was not set. More...
Date	getExpirationDate ()
	Returns the expiration date attribute or null if the data attribute was not set. More...
void	setCertificate (byte[] cert)
	Sets a certificate for the key. More...
byte[]	getCertificate ()
	Returns the certificate or null if the key doesn't have a certificate attribute.
void	setMechs (int[] mechs) throws CryptoServerException, UnsupportedEncodingException
	Sets an int array with mechanisms for a key. More...
byte[]	getMechs ()
	Returns a list of key mechanisms as byte array. More...
void	setFIPSUsage (int usage)
	Sets the fips key usage/padding specifier attribute. More...
int	getFIPSUsage ()
	Returns the fips key usage/padding specifier attribute. More...

Variables
static final int	FLAG_OVERWRITE = 0x00000001
	Overwrite key if already existing.
static final int	FLAG_EXTERNAL = 0x00000002
	Don't store key on CryptoServer but return MBK encrypted key blob to be stored externally.
static final int	FLAG_VOLATILE = 0x00000004
	Volatile key storage (until next restart of CryptoServer)
static final int	FLAG_HASH_PART = 0x00000020
	Don't finalize hash, return hash digest info instead.
static final int	FLAG_HASH_DATA = 0x00000040
	Given data has to be hash.
static final int	FLAG_ENCRYPT_SECRET = 0x00000080
	Encrypt shared secret with MBK.
static final int	FLAG_CRYPT_INIT = 0x00000100
	Initialize En/Decryption Operation (RFU)
static final int	FLAG_CRYPT_FINAL = 0x00000200
	Finalize En/Decryption Operation.
static CryptoServerLog	CxiLog = new CryptoServerLog("cxi.log", CryptoServerLog.LogLevel.Warning, 0x100000)
	Static instance of CryptoServerLog that provides unified logging. More...

Constructors
	CryptoServerCXI (String device) throws IOException, NumberFormatException, CryptoServerException
	Creates a new connection to a single CryptoServer. More...
	CryptoServerCXI (String device, int timeout) throws IOException, NumberFormatException, CryptoServerException
	Creates a new connection to a single CryptoServer. More...
	CryptoServerCXI (String[] devices, int timeout) throws IOException, CryptoServerException
	Creates a new connection to a CryptoServer cluster. More...
	CryptoServerCXI (CryptoServerConfig config) throws IOException, CryptoServerException
	Creates a new connection to a CryptoServer or CryptoServer cluster. More...

Miscellaneous Functions
int	getFirmwareVersion () throws IOException, CryptoServerException
	Returns the version number of the CryptoServer firmware module CXI (x.x.x.x).

Functions for Key Management
Key	generateKey (int flags, KeyAttributes keyTemplate, int mech) throws IOException, CryptoServerException
	Generates a new keys according on the given template (key attributes). More...
Key	generateKey (int flags, KeyAttributes keyTemplate) throws IOException, CryptoServerException
	Generates a new keys according on the given template (key attributes). More...
KeyAttributes	generateDSADomainParam (int psize, int qsize, int mech) throws IOException, CryptoServerException
	Creates the domain parameter (P, Q and G), needed to create a DSA key (see CryptoServerCXI.CryptoServerCXI.generateKey). More...
byte[]	generateDSAPQParam (int psize, int qsize, int mech, int hash, byte[] seed, int index) throws IOException, CryptoServerException
	Creates the domain parameter (P and Q), needed to create a DSA key (see CryptoServerCXI.CryptoServerCXI.generateKey) as described in FIPS 186-4. More...
KeyAttributes	generateDSAGParam (byte[] mechParamAndPropList) throws IOException, CryptoServerException
	Creates the domain parameter G, needed to create a DSA key (see CryptoServerCXI.CryptoServerCXI.generateKey) as described in FIPS 186-4. More...
Key	findKey (int flags, KeyAttributes keyTemplate) throws IOException, CryptoServerException
	Finds a key in the internal database of the CryptoServer and returns either a key handle or a key backup blob. More...
Key	findKey (KeyAttributes keyTemplate) throws IOException, CryptoServerException
	Finds a key in the internal database of the CryptoServer and returns a key handle. More...
KeyAttributes	getKeyAttributes (Key key, boolean all) throws IOException, CryptoServerException
	Inquires key attributes of a key. More...
Key	setKeyAttributes (Key key, KeyAttributes attr) throws IOException, CryptoServerException
	Sets one or more key attributes for a key. More...
KeyAttributes	getKeyAttributes (Key key, int[] desired) throws IOException, CryptoServerException
KeyAttributes[]	listKeys (KeyAttributes keyTemplate) throws IOException, CryptoServerException
	Enumerates the keys which are currently stored in the CXI database on the CryptoServer. More...
KeyAttributes[]	listKeys () throws IOException, CryptoServerException
	Enumerates the keys which are currently stored in the CXI database on the CryptoServer. More...
Key	backupKey (Key key) throws IOException, CryptoServerException
	Exports a key as key backup blob. More...
Key	restoreKey (int flags, Key key, KeyAttributes keyTemplate) throws IOException, CryptoServerException
	Restores (imports) a key from a key backup blob, see Format of Key Blobs. More...
void	deleteKey (Key key) throws IOException, CryptoServerException
	Delete a key from the CryptoServer. More...
byte[]	exportKey (Key key, int type, Key wrapKey, int mech) throws IOException, CryptoServerException
	Export a key from the CryptoServer. More...
byte[]	exportKey (Key key, int type, Key wrapKey) throws IOException, CryptoServerException
	Export a key from the CryptoServer. More...
KeyAttAndComp	exportClearKey (Key key, int type) throws IOException, CryptoServerException
	Export a key (cleartext) from the CryptoServer. More...
Key	importKey (int flags, int type, KeyAttributes keyTemplate, byte[] keyBlob, Key wrapKey, int mech) throws IOException, CryptoServerException
	Imports a key blob of type 'Simple Blob' (see Format of Key Blobs). More...
Key	importKey (int flags, int type, KeyAttributes keyTemplate, byte[] keyBlob, Key wrapKey) throws IOException, CryptoServerException
	Imports a key blob of type 'Simple Blob' (see Format of Key Blobs). More...
Key	importClearKey (int flags, int type, KeyAttributes keyTemplate, KeyComponents keyComponents) throws IOException, CryptoServerException
	Imports a clear text key. More...

Cryptographic Functions
byte[]	crypt (int flags, Key key, int mech, byte[] mechParam, byte[] data, ByteArray iv, ByteArray tag, byte[] tag_in) throws IOException, CryptoServerException
	Encrypt or decrypt data. More...
byte[]	crypt (Key key, int mech, byte[] mechParam, byte[] data, ByteArray iv) throws IOException, CryptoServerException
	Encrypt or decrypt data. More...
byte[][]	bulkCrypt (Key key, int mech, byte[][] data) throws IOException, CryptoServerException
	Encrypt or decrypt multiple data items in one operation. More...
byte[]	sign (int flags, Key key, int mech, byte[] mechParam, byte[] data, ByteArray iv) throws IOException, CryptoServerException
	Digitally signs the given hash value (asymmetric algorithms) or calculates a Message Authentication Code (MAC) or hash based MAC (HMAC) (symmetric algorithms). More...
byte[]	sign (Key key, int mech, byte[] data) throws IOException, CryptoServerException
	Digitally signs the given hash value (asymmetric algorithms) or calculates a Message Authentication Code (MAC) or hash based MAC (HMAC) (symmetric algorithms). More...
byte[][]	bulkSign (Key key, int mech, byte[][] data) throws IOException, CryptoServerException
	Digitally signs up to 16(ECDSA)/50(RSA) hash values in one operation. More...
boolean	verify (int flags, Key key, int mech, byte[] mechParam, byte[] data, byte[] signature, ByteArray iv) throws IOException, CryptoServerException
	Verifies a digital signature, Message Authentication Code (MAC) or hash based MAC (HMAC). More...
boolean	verify (Key key, int mech, byte[] data, byte[] signature) throws IOException, CryptoServerException
	Verifies a digital signature, Message Authentication Code (MAC) or hash based MAC (HMAC). More...
byte[]	generateRandom (int length, int mech) throws IOException, CryptoServerException
	Generate random bytes. More...
byte[]	computeHash (int flags, int mech, byte[] data, byte[] info, Key key) throws IOException, CryptoServerException
	Computes a hash or hash based MAC (HMAC) over the given data. More...
byte[]	agreeSecret (int flags, Key privateKey, Key publicKey, int mech, byte[] mechParam) throws IOException, CryptoServerException
	This function calculates a shared secret from two ECDH or ECDSA keys as described in TR-03111. More...
Key	deriveKey (int flags, Key privateKey, KeyAttributes keyTemplate, int mech, byte[] mechParam) throws IOException, CryptoServerException
Key	setFIPSUsage (Key key, int usage) throws CryptoServerException, IOException
	Sets the FIPS usage/padding specifier in the attribute list of the Key. More...

Detailed Description

Function Documentation

CryptoServerCXI() [1/4]

CryptoServerCXI

(

String

device

)

throws IOException, NumberFormatException, CryptoServerException

Creates a new connection to a single CryptoServer.

Parameters

device

Address of the CryptoServer. May contain the prefix "TCP:" followed by the IP address or port number and IP address (seperated by a '@'), or the prefix "PCI:" followed by the device name of a PCI device. Examples: "TCP:192.168.4.99" "TCP:288@192.168.4.201" "PCI:0" "PCI:/dev/cs2.0".

CryptoServerCXI() [2/4]

CryptoServerCXI	(	String	device,
		int	timeout
	)		throws IOException, NumberFormatException, CryptoServerException

Creates a new connection to a single CryptoServer.

Parameters

device	Address of the CryptoServer. May contain the prefix "TCP:" followed by the IP address or port number and IP address (seperated by a '@'), or the prefix "PCI:" followed by the device name of a PCI device. Examples: "TCP:192.168.4.99" "TCP:288@192.168.4.201" "PCI:0" "PCI:/dev/cs2.0".
timeout	Timeout in milliseconds to establich the connection.

CryptoServerCXI() [3/4]

CryptoServerCXI	(	String[]	devices,
		int	timeout
	)		throws IOException, CryptoServerException

Creates a new connection to a CryptoServer cluster.

Internally only one CryptoServer is connected at a time. The API provides a failover mechanism that switches to another device in case of failure and returns as soon as one device has been successfully connected. If none of the devices in the cluster can be connected an exception will be thrown.

Parameters

devices	Array of the CryptoServer device addresses. Each address may contain the prefix "TCP:" followed by the IP address or port number and IP address (seperated by a '@'), or the prefix "PCI:" followed by the device name of a PCI device. Examples: "TCP:192.168.4.99" "TCP:288@192.168.4.201" "PCI:0" "PCI:/dev/cs2.0".
timeout	Timeout in milliseconds to establich the connection to a CryptoServer.

CryptoServerCXI() [4/4]

CryptoServerCXI

(

CryptoServerConfig

config

)

throws IOException, CryptoServerException

Creates a new connection to a CryptoServer or CryptoServer cluster.

Parameters

config

Configuration object, see CryptoServerConfig. The following key names will be recognized: Key Mandatory Default Value Description Device Yes - Device specifier of CryptoServer to be connected. Optionally multiple device specifier can be assigned in order to establish a fault-tolerant connection to a cluster of CryptoServer (failover). The values have to be separated either by a space or tab character or have to be spread over multiple lines each ended by a backslash character, see CryptoServerAPI.CryptoServerConfig. Timeout No 60000 Timeout in milliseconds the API waits for an answer on command execution ConnectionTimeout No 3000 Timeout in milliseconds the API waits on attempt to connect to a CryptoServer EndSessionOnShutdown No false Enables or disables a ShutdownHook for terminating active sessions KeepSessionAlive No false Prevents a secure messaging session from expiring after having been idle for more than 15 minutes FallbackInterval No 0 Time in seconds the API waits before it tries to reconnect to the primary device (first device in list) after having switched to another device due to a communication error

generateKey() [1/2]

Key generateKey	(	int	flags,
		KeyAttributes	keyTemplate,
		int	mech
	)		throws IOException, CryptoServerException

Generates a new keys according on the given template (key attributes).

Dependant on the given flags the key is either stored in the internal database and a key handle
is returned or the key is not stored on the CryptoServer but an MBK encrypted key backup blob is returned.

Parameters

flags	Command flags (see Command Flags), XOR combination of: FLAG_OVERWRITE: overwrite already existing key FLAG_EXTERNAL: don't store the key in the internal database but return a key backup blob (see Format of Key Blobs) FLAG_VOLATILE: don't store the key permanently (lost after restart of CryptoServer) A value of 0 can be used to set none of the above flags.
keyTemplate	Key attributes to be set for the new key (see Key Properties). The following attributes are mandatory for the key template: key algorithm specifier (see Algorithm Specifier) key size in bits. If the algoritm doesn't require a key size (e.g. EC) the key size has to be set to zero. key name (may be omitted in case of external key storage)
mech	Mechanism specifier, XOR combination of: Random mode (see Random Generation Parameter): MECH_RND_REAL : use hardware (real) random number generator (better, slower) MECH_RND_PSEUDO : use deterministic (pseudo) random number generator (faster) Key generation mechanism (see Key Generation Parameter): RSA: MECH_KEYGEN_PROB_PRIME: create 'probable' prime values according to Miller-Rabin's algorithm (default) MECH_KEYGEN_PROV_PRIME: create 'proven' prime values according to Maurer's algorithm MECH_KEYGEN_ANSI_PRIME: create prime values according to ANSI specification MECH_KEYGEN_FIPS186_4_PRIME : create prime numbers according to FIPS-186-4 ECDSA: MECH_KEYGEN_UNCOMP: public key in uncompressed form (default) MECH_KEYGEN_COMP: public key in compressed form MECH_KEYGEN_HYBRID: public key in hybrid form DSA: MECH_KEYGEN_PROB_PRIME: create 'probable' prime values according to Miller-Rabin's algorithm (default) MECH_KEYGEN_PROV_PRIME: create 'proven' prime values according to Maurer's algorithm MECH_DPGEN_DP_FIPS186_4: create DSA domain parameters conform to FIPS-186-4 A value of -1 can be used to set the default values.

Returns

Generated key object (either key handle or - in case of external key storage - key backup blob).

See also

Format of Key Blobs

Examples:

The following code illustrates how to generate an AES key with a minimum set of key attributes:

CryptoServerCXI.KeyAttributes keyTemplate = new CryptoServerCXI.KeyAttributes();
 
keyTemplate.setAlgo(CryptoServerCXI.KEY_ALGO_AES);
keyTemplate.setSize(256);
keyTemplate.setName("CXI_AES_KEY");
 
CryptoServerCXI.Key aesKey = cxi.generateKey(CryptoServerCXI.FLAG_OVERWRITE, keyTemplate, -1);

In FIPS mode the additional key attribute Mechs containing all supported mechanisms must be set prior to the key generation. It is only allowed to choose one padding but all supported hash algos must be defined explicitly. The following code illustrates how to generate an RSA key containing two different mechanisms:

CryptoServerCXI.KeyAttributes keyTemplate = new CryptoServerCXI.KeyAttributes();
int cxi_mechs[] = new int[2];
cxi_mechs[0] = (CryptoServerCXI.MECH_HASH_ALGO_SHA256 | CryptoServerCXI.MECH_PAD_PKCS1);
cxi_mechs[1] = (CryptoServerCXI.MECH_HASH_ALGO_SHA512 | CryptoServerCXI.MECH_PAD_PKCS1);
 
keyTemplate.setAlgo(CryptoServerCXI.KEY_ALGO_RSA);
keyTemplate.setSize(2048);
keyTemplate.setName("CXI_RSA_KEY");
keyTemplate.setMechs(cxi_mechs);
 
CryptoServerCXI.Key rsaKey = cxi.generateKey(CryptoServerCXI.FLAG_OVERWRITE, keyTemplate, -1);

The following code illustrates how to generate an RSA key with some optional key attributes specified:

CryptoServerCXI.KeyAttributes keyTemplate = new CryptoServerCXI.KeyAttributes();
 
keyTemplate.setAlgo(CryptoServerCXI.KEY_ALGO_RSA);
keyTemplate.setSize(2048);
keyTemplate.setExponent(new byte [] { 0x01, 0x00, 0x01 });
keyTemplate.setName("CXI_RSA_KEY");
keyTemplate.setGroup("MyKeyGroup");
keyTemplate.setExport(CryptoServerCXI.KEY_EXPORT_ALLOW);
keyTemplate.setUsage(CryptoServerCXI.KEY_USAGE_ENCRYPT | CryptoServerCXI.KEY_USAGE_DECRYPT | CryptoServerCXI.KEY_USAGE_SIGN);
keyTemplate.setGenerationDate(new Date());
keyTemplate.setExpirationDate(new SimpleDateFormat("yyyy-MM-dd HH:mm:ss").parse("2012-12-21 11:55:00"));
 
CryptoServerCXI.Key rsaKey = cxi.generateKey(CryptoServerCXI.FLAG_OVERWRITE, keyTemplate, -1);

The following code illustrates how to generate an ECDSA key:

CryptoServerCXI.KeyAttributes keyTemplate = new CryptoServerCXI.KeyAttributes();
 
keyTemplate.setAlgo(CryptoServerCXI.KEY_ALGO_ECDSA);
keyTemplate.setCurve("NIST-P256");
keyTemplate.setName("CXI_EC_KEY");
keyTemplate.setGroup("MyKeyGroup");
 
CryptoServerCXI.Key ecKey = cxi.generateKey(CryptoServerCXI.FLAG_OVERWRITE, keyTemplate, -1);

generateKey() [2/2]

Key generateKey	(	int	flags,
		KeyAttributes	keyTemplate
	)		throws IOException, CryptoServerException

Generates a new keys according on the given template (key attributes).

Dependant on the given flags the key is either stored in the internal database and a key handle
is returned or the key is not stored on the CryptoServer but an MBK encrypted key backup blob is returned.

Parameters

flags	Command flags, XOR combination of: FLAG_OVERWRITE: overwrite already existing key FLAG_EXTERNAL: don't store the key in the internal database but return a key backup blob. FLAG_VOLATILE: don't store the key permanently (lost after restart of CryptoServer) A value of 0 can be used to set none of the above flags.
keyTemplate	Key attributes to be set for the new key (see Key Properties). The following attributes are mandatory for the key template: key algorithm specifier (see Algorithm Specifier) key size in bits. If the algoritm doesn't require a key size (e.g. EC) the key size has to be set to zero. key name (may be omitted in case of external key storage)

Returns

Generated key object (either key handle or - in case of external key storage - key backup blob).

See also

Format of Key Blobs

Examples:

The following code illustrates how to generate an ECDSA key:

CryptoServerCXI.KeyAttributes keyTemplate = new CryptoServerCXI.KeyAttributes();
 
keyTemplate.setAlgo(CryptoServerCXI.KEY_ALGO_ECDSA);
keyTemplate.setCurve("NIST-P256");
keyTemplate.setName("CXI_ECDSA_KEY");
 
CryptoServerCXI.Key ecKey = cxi.generateKey(CryptoServerCXI.FLAG_OVERWRITE, keyTemplate);

generateDSADomainParam()

KeyAttributes generateDSADomainParam	(	int	psize,
		int	qsize,
		int	mech
	)		throws IOException, CryptoServerException

Creates the domain parameter (P, Q and G), needed to create a DSA key (see CryptoServerCXI.CryptoServerCXI.generateKey).

Parameters

psize	Size of prime P.
qsize	Size of prime Q.
mech	XOR combination of: Random mode (see Random Generation Parameter): MECH_RND_REAL : uses hardware (real) random number generator (better, slower) MECH_RND_PSEUDO : uses deterministic (pseudo) random number generator (faster) Key generation mechanism (see Key Generation Parameter): MECH_DPGEN_DP_FIPS186_4 : creates DSA domain parameters conform to FIPS 186-4 A value of -1 can be used to set the default values.

Returns

Generated Domain Parameter

generateDSAPQParam()

byte[] generateDSAPQParam	(	int	psize,
		int	qsize,
		int	mech,
		int	hash,
		byte[]	seed,
		int	index
	)		throws IOException, CryptoServerException

Creates the domain parameter (P and Q), needed to create a DSA key (see CryptoServerCXI.CryptoServerCXI.generateKey) as described in FIPS 186-4.

Parameters

psize	Size of prime P.
qsize	Size of prime Q.
mech	Random mode (see Random Generation Parameter): MECH_RND_REAL : uses hardware (real) random number generator (better, slower) MECH_RND_PSEUDO : uses deterministic (pseudo) random number generator (faster) (default)
hash	Hash algo MECH_HASH_ALGO_SHA1 SHA1 hash algorithm MECH_HASH_ALGO_SHA224 SHA224 hash algorithm MECH_HASH_ALGO_SHA256 SHA256 hash algorithm MECH_HASH_ALGO_SHA384 SHA384 hash algorithm MECH_HASH_ALGO_SHA512 SHA512 hash algorithm
seed	Optional seed value
index	unused (for further use)

Returns

PropertyList and Mechanism Parameter as byte array Ready to use in generateDSAGParam

generateDSAGParam()

KeyAttributes generateDSAGParam

(

byte[]

mechParamAndPropList

)

throws IOException, CryptoServerException

Creates the domain parameter G, needed to create a DSA key (see CryptoServerCXI.CryptoServerCXI.generateKey) as described in FIPS 186-4.

Parameters

mechParamAndPropList

PropertyList and Mechanism Parameter as byte array, for example generated by generateDSAPQParam

Returns

KeyAttributes with P, Q, G and KEY_ALGO_DSA as default key algorithm

findKey() [1/2]

Key findKey	(	int	flags,
		KeyAttributes	keyTemplate
	)		throws IOException, CryptoServerException

Finds a key in the internal database of the CryptoServer and returns either a key handle or a key backup blob.

On a cluster of CryptoServer the function searches on all devices and returns the first matching key.

Parameters

flags	XOR combination of: FLAG_EXTERNAL: return a key backup blob instead of a key handle. This value is recommended on a CryptoServer cluster in order to provide a seamless failover. A value of 0 can be used to set none of the above flags.
keyTemplate	Key Attributes that specify the key to be found. The key is identified by the following attributes: name (conditional, must be provided if the attribute is existing for the key to be found) group (conditional, must be provided if the attribute is existing for the key to be found) specifier (conditional, must be provided if the attribute is existing for the key to be found)

The wildcards are not supported for the attributes listed above. If name and group are using default values (i.e. empty string) they have not to (for name even must not) be set within provided key atributes (keyTemplate).

Returns

If the key was found a key object is returned, otherwise, if the key wasn't found on any CryptoServer, 'null' is returned.

Example:

The following code illustrates how to find a key on the CryptoServer:

CryptoServerCXI.KeyAttributes attr = new CryptoServerCXI.KeyAttributes();
 
attr.setGroup("MyKeyGroup");
attr.setName("CXI_AES_KEY");
 
CryptoServerCXI.Key aesKey = cxi.findKey(CryptoServerCXI.FLAG_EXTERNAL, attr);

findKey() [2/2]

Key findKey

(

KeyAttributes

keyTemplate

)

throws IOException, CryptoServerException

Finds a key in the internal database of the CryptoServer and returns a key handle.

On a cluster of CryptoServer the function searches on all devices and returns the first matching key.

Parameters

keyTemplate

Key Attributes that specify the key to be found. The key is identified by the following attributes: name (conditional, must be provided if the attribute is existing for the key to be found) group (conditional, must be provided if the attribute is existing for the key to be found) specifier (conditional, must be provided if the attribute is existing for the key to be found)

The wildcards are not supported for the attributes listed above. If name and group are using default values (i.e. empty string) they have not to (for name even must not) be set within provided key atributes (keyTemplate).

Returns

If the key was found a key handle is returned, otherwise, if the key wasn't found on any CryptoServer, 'null' is returned.

getKeyAttributes()

KeyAttributes getKeyAttributes	(	Key	key,
		boolean	all
	)		throws IOException, CryptoServerException

Inquires key attributes of a key.

Parameters

key	Key object, whose attributes are to be inquired
all	true: a comprehensive attribute list should be returned false: only a partly list with base attributes should be returned (name, algo, size, type, date)

Returns

Key Attributes

setKeyAttributes()

Key setKeyAttributes	(	Key	key,
		KeyAttributes	attr
	)		throws IOException, CryptoServerException

Sets one or more key attributes for a key.

Note

Some key attributes (e.g. size or algorithm) are set on key generation or import and can't be modified later.

Parameters

key	Key object, whose attributes are to be set
attr	List of attrubutes to be set

Returns

Updated Key

listKeys() [1/2]

KeyAttributes[] listKeys

(

KeyAttributes

keyTemplate

)

throws IOException, CryptoServerException

Enumerates the keys which are currently stored in the CXI database on the CryptoServer.

The returned key list contains those keys that

1. the user is allowed to access
2. match the given search criteria

1)
The user is allowed to access keys according to his group membership and 'global' keys without a group attribute.

2)
A attribute list may be given to specify a partial set of keys to be listed. Thereby only those keys are listed that match the given attribute values. If no attribute list is given keys are not filtered.

Parameters

keyTemplate

List of attributes that define search criteria for the keys to be listed. Keys that don't match the given criteria will not be listed.

Returns

Array of key attributes. The following attributes are returned for every key:

• algorithm
• group
• name
• specifier
• size
• type

Note

• The key list contains only keys the user is allowed to access, other keys are 'invisible'. Therefore the CryptoServer checks whether the key group matches the value of the user attribute "CXI_GROUP" of the currently authenticated user(s).
• Keys without key group attribute are listed in any case.

Example:

The folowing example illustrates how to list only RSA keys with 2048 bit:

CryptoServerCXI.KeyAttributes keyTemplate = new CryptoServerCXI.KeyAttributes();
 
keyTemplate.setAlgo(CryptoServerCXI.KEY_ALGO_RSA);
keyTemplate.setSize(2048);
 
CryptoServerCXI.KeyAttributes [] keyList = cxi.listKeys(keyTemplate)

listKeys() [2/2]

KeyAttributes[] listKeys

(

)

throws IOException, CryptoServerException

Enumerates the keys which are currently stored in the CXI database on the CryptoServer.

Returns

Array of key attributes. The following attributes are returned for every key:

• algorithm
• group
• name
• specifier
• size
• type

See also

listKeys(KeyAttributes)

backupKey()

Key backupKey

(

Key

key

)

throws IOException, CryptoServerException

Exports a key as key backup blob.

The private or secret key parts within the blob
are encrypted with the CryptoServer's Master Box Key (MBK).

Parameters

key	Key handle.

Returns

Key backup blob, see Format of Key Blobs.

restoreKey()

Key restoreKey	(	int	flags,
		Key	key,
		KeyAttributes	keyTemplate
	)		throws IOException, CryptoServerException

Restores (imports) a key from a key backup blob, see Format of Key Blobs.

Parameters

flags	XOR combination of: FLAG_OVERWRITE : overwrite already existing key FLAG_VOLATILE : don't store the key permanently (lost after restart of CryptoServer) A value of 0 can be used to set none of the above flags.
key	Key to be restored.
keyTemplate	Key attributes to be set or modified. If one or more of these attributes are already present in the key backup blob, they will be overwritten, as long as the attribute value is not read-only, e.g. it is not possible to change the algorithm or key size attribute. Optionally, if no additional attributes should be set, keyTemplate can be set to null.

Returns

Key handle

deleteKey()

void deleteKey

(

Key

key

)

throws IOException, CryptoServerException

Delete a key from the CryptoServer.

Parameters

key	Key handle of key to be deleted.

exportKey() [1/2]

byte[] exportKey	(	Key	key,
		int	type,
		Key	wrapKey,
		int	mech
	)		throws IOException, CryptoServerException

Export a key from the CryptoServer.

Parameters

key	Key to be exported
type	Key type (see Key Types): KEY_TYPE_PUBLIC KEY_TYPE_PRIVATE KEY_TYPE_SECRET
wrapKey	Key encryption key (null on clear key export)
mech	XOR combination of mechanism parameter used to encrypt key (see Mechanism Parameter): Chaining mode (see Chaining Modes): DES, AES: MECH_CHAIN_ECB : Use 'Electronic Codebook' mode (no chaining) MECH_CHAIN_CBC : Use 'Cipher Block Chaining' mode (default) MECH_CHAIN_KEY_WRAP : Use 'AES Key Wrap' mode (AES only; NIST SP800-38F) Padding mode (see Padding Modes): DES, AES: MECH_PAD_NONE : Don't apply any padding (data length has to be a multiple of algorithms block size) MECH_PAD_PKCS5 : Apply padding according to PKCS#5 (default) MECH_PAD_RANDOM : Apply random padding MECH_PAD_ISO7816 : Apply padding according to ISO 7816 MECH_PAD_KWP : Apply padding according to NIST SP800-38F RSA: MECH_PAD_NONE : Don't apply any padding (data length has to be smaller than length of modulus) MECH_PAD_PKCS1 : Apply padding according to PKCS#1-v1_5 (block type 2) A value of -1 can be used to set the default values (CBC, PKCS#5).

Returns

Key blob of type 'Simple Blob', see Format of Key Blobs

Note

Up to version 1.50 the method CryptoServerCXI.CryptoServerCXI.exportKey returned a truncated key blob without the enclosing 'KB' tag. In order to be compatible with other CXI APIs (C++, dotNET) exportKey returns the complete key blob as of version 1.51.
In addition CryptoServerCXI.CryptoServerCXI.importKey was modfied to accept both formats.

Example:

The following code illustrates how to export a key from the CryptoServer:

CryptoServerCXI.Key rsaKey = ...;  // key to be exported
CryptoServerCXI.Key aesKey = ...;  // key encryption key / wrapping key
 
byte [] keyBlob = cxi.exportKey(rsaKey, CryptoServerCXI.KEY_TYPE_PRIVATE, aesKey, CryptoServerCXI.MECH_CHAIN_CBC | CryptoServerCXI.MECH_PAD_PKCS5);

exportKey() [2/2]

byte[] exportKey	(	Key	key,
		int	type,
		Key	wrapKey
	)		throws IOException, CryptoServerException

Export a key from the CryptoServer.

Parameters

key	Key to be exported
type	Key type (see Key Types): KEY_TYPE_PUBLIC KEY_TYPE_PRIVATE KEY_TYPE_SECRET
wrapKey	Key encryption key (null on clear key export)

Returns

Key blob of type 'Simple Blob', see Format of Key Blobs

Example:

The following code illustrates how to export a key from the CryptoServer:

CryptoServerCXI.Key rsaKey = ...;  // key to be exported
CryptoServerCXI.Key aesKey = ...;  // key encryption key / wrapping key
 
byte [] keyBlob = cxi.exportKey(rsaKey, CryptoServerCXI.KEY_TYPE_PRIVATE, aesKey);

exportClearKey()

KeyAttAndComp exportClearKey	(	Key	key,
		int	type
	)		throws IOException, CryptoServerException

Export a key (cleartext) from the CryptoServer.

Parameters

key	Key
type	Key type (see Key Types): KEY_TYPE_PUBLIC KEY_TYPE_PRIVATE KEY_TYPE_SECRET

Returns

Attributes and components of the key.

importKey() [1/2]

Key importKey	(	int	flags,
		int	type,
		KeyAttributes	keyTemplate,
		byte[]	keyBlob,
		Key	wrapKey,
		int	mech
	)		throws IOException, CryptoServerException

Imports a key blob of type 'Simple Blob' (see Format of Key Blobs).

Parameters

flags	XOR combination of command flags (see Command Flags): FLAG_OVERWRITE : overwrite already existing key FLAG_EXTERNAL : don't store the key in the internal database but return a key backup blob. FLAG_VOLATILE : don't store the key permanently (lost after restart of CryptoServer) A value of 0 can be used to set none of the above flags.
type	Blob type (see Blob Types): KEY_BLOB_SIMPLE: Simple blob format (Utimaco). Other blob types are reserved for future use.
keyTemplate	Updated key attributes to be set for the new key or null.
keyBlob	Key blob to be imported
wrapKey	Key Encryption Key to be used to encrypt key. The key may be imported in plain. The value of wrapKey has to be set to 'null' in this case.
mech	XOR combination of mechanism parameter used to decrypt key or -1 to use default values: Chaining mode (see Chaining Modes): DES, AES: MECH_CHAIN_ECB : Use 'Electronic Codebook' mode (no chaining) MECH_CHAIN_CBC : Use 'Cipher Block Chaining' mode (default) MECH_CHAIN_KEY_WRAP : Use 'AES Key Wrap' mode (AES only; NIST SP800-38F) Padding mode (see Padding Modes): DES, AES: MECH_PAD_NONE : Don't apply any padding (data length has to be a multiple of algorithms block size). MECH_PAD_PKCS5 : Apply padding according to PKCS#5 (default). MECH_PAD_RANDOM : Apply random padding. MECH_PAD_ISO7816 : Apply padding according to ISO 7816 . MECH_PAD_KWP : Apply padding according to NIST SP800-38F RSA: MECH_PAD_NONE : Don't apply any padding (data length has to be smaller than length of modulus). MECH_PAD_PKCS1 : Apply padding according to PKCS#1-v1_5 (block type 2). A value of -1 can be used to set the default values.

Returns

Generated key object (either key handle or - in case of external key storage - key backup blob).

See also

Format of Key Blobs

Note

Up to version 1.50 the method CryptoServerCXI.CryptoServerCXI.exportKey returned a truncated key blob without the enclosing 'KB' tag. In order to be compatible with other CXI APIs (C++, dotNET) exportKey returns the complete key blob as of version 1.51.
In addition CryptoServerCXI.CryptoServerCXI.importKey was modfied to accept both formats.

Example:

The following code illustrates how to import a key into the CryptoServer:

CryptoServerCXI.Key aesKey = ...;  // key encryption key / wrapping key
byte [] keyBlob = ...;
CryptoServerCXI.KeyAttributes keyTemplate = new CryptoServerCXI.KeyAttributes();
keyTemplate.setName("CXI_IMPORTED_RSA_KEY");
keyTemplate.setGroup("MyKeyGroup");
 
CryptoServerCXI.Key rsaKey cxi.importKey(0, CryptoServerCXI.KEY_BLOB_SIMPLE, keyTemplate, keyBlob, aesKey, -1);

importKey() [2/2]

Key importKey	(	int	flags,
		int	type,
		KeyAttributes	keyTemplate,
		byte[]	keyBlob,
		Key	wrapKey
	)		throws IOException, CryptoServerException

Imports a key blob of type 'Simple Blob' (see Format of Key Blobs).

Parameters

flags	XOR combination of command flags (see Command Flags): FLAG_OVERWRITE : overwrite already existing key FLAG_EXTERNAL : don't store the key in the internal database but return a key backup blob. FLAG_VOLATILE : don't store the key permanently (lost after restart of CryptoServer) A value of 0 can be used to set none of the above flags.
type	Blob type (see Blob Types): KEY_BLOB_SIMPLE: Simple blob format (Utimaco). Other blob types are reserved for future use.
keyTemplate	Key attributes to be set for the new key.
keyBlob	Key blob to be imported
wrapKey	Key Encryption Key to be used to encrypt key. The key may be imported in plain. The value of wrapKey has to be set to 'null' in this case.

Returns

Generated key object (either key handle or - in case of external key storage - key backup blob).

See also

Format of Key Blobs

Example:

The following code illustrates how to import a key into the CryptoServer:

CryptoServerCXI.Key aesKey = ...;  // key encryption key / wrapping key
byte [] keyBlob = ...;
CryptoServerCXI.KeyAttributes keyTemplate = new CryptoServerCXI.KeyAttributes();
keyTemplate.setName("CXI_IMPORTED_RSA_KEY");
keyTemplate.setGroup("MyKeyGroup");
 
CryptoServerCXI.Key rsaKey cxi.importKey(0, CryptoServerCXI.KEY_BLOB_SIMPLE, keyTemplate, keyBlob, aesKey);

importClearKey()

Key importClearKey	(	int	flags,
		int	type,
		KeyAttributes	keyTemplate,
		KeyComponents	keyComponents
	)		throws IOException, CryptoServerException

Imports a clear text key.

Parameters

flags	XOR combination of: FLAG_OVERWRITE: overwrite already existing key FLAG_EXTERNAL: don't store the key in the internal database but return a key backup blob. FLAG_VOLATILE: don't store the key permanently (lost after restart of CryptoServer). A value of 0 can be used to set none of the above flags.
type	Blob type (see Blob Types): KEY_BLOB_SIMPLE Other blob types are reserved for future use
keyTemplate	Key attributes to be set for the new key.
keyComponents	Key components of the key to be imported. This parameter may be 'null' on public keys. In this case the key template has to contain the public key componets.

Returns

Generated key object (either key handle or - in case of external key storage - key backup blob).

See also

Format of Key Blobs

Example:

The following code illustrates how to import an clear text AES key:

CryptoServerCXI.KeyAttributes attr = new CryptoServerCXI.KeyAttributes();
attr.setAlgo(CryptoServerCXI.KEY_ALGO_AES);
attr.setSize(256);
attr.setGroup("test");
attr.setName("CXI_AES_TEST_KEY");
 
final byte [] aesKeyBytes = {(byte)0xB7, (byte)0xF3, (byte)0x89, (byte)0x3A, (byte)0xAB, (byte)0x15, (byte)0x0B, (byte)0xAF,
                             (byte)0xEC, (byte)0xC1, (byte)0x93, (byte)0x10, (byte)0x97, (byte)0x89, (byte)0x3C, (byte)0x38,
                             (byte)0x75, (byte)0x1A, (byte)0xD7, (byte)0x28, (byte)0xDD, (byte)0x56, (byte)0xDE, (byte)0xB8,
                             (byte)0xF1, (byte)0xA4, (byte)0x10, (byte)0x97, (byte)0x75, (byte)0x5B, (byte)0x5E, (byte)0x06 };
 
CryptoServerCXI.KeyComponents comp = new CryptoServerCXI.KeyComponents(aesKeyBytes);
 
CryptoServerCXI.Key aesKey = cxi.importClearKey(CryptoServerCXI.FLAG_OVERWRITE, CryptoServerCXI.KEY_BLOB_SIMPLE, attr, comp);

The following code illustrates how to import a clear text RSA key:

CryptoServerCXI.KeyAttributes attr = new CryptoServerCXI.KeyAttributes();
attr.setAlgo(CryptoServerCXI.KEY_ALGO_RSA);
attr.setSize(1024);
attr.setGroup("test");
attr.setName("CXI_RSA_TEST_KEY");
 
final String mod  = "B7F3893AAB150BAFECC1931097893C38751AD728DD56DEB8F1A41097755B5E0664FF32FD902B04EDCFD5E2EF8330FDF07C15F9C2229E53F71446EEDBC82BEA3D1679B2BBC07B269D0832D098B3478189CB1FD9F770ED5231EE9AA05BEBE2D0F13F4813F919EB8B3B14AEEE0EE22EDEB152CB5B5798712CDE28273B7E5AB232EB";
final String pexp = "010001";
final String sexp = "0C69C84467C01B524B5942B9D76800E2D47033BDC3B5F580A879C84ED8320AB5C6C1FBE8657EA9ADFC9CF3DBF2CFEF0AF7ECA9B6828C89A0FE42CD2292AEF7F6FB0B8BC61EAE635CE3ACAADACBB0609666266D28B2760483F169C05E672C5C88D2B5B0F66C6474AA7E75A3D526EFBD865D4CD8457DD8F9D31C4B095827C6B3AD";
final String p    = "D19916EC3E718F393467AD608813306B58F763EF6F1A8FE1251AAAE720D1A6F0E552F95DE53C0FECDFFE0ED9E541FC00F83393C9E1B26789D3A779ACA9A5C905";
final String q    = "E0ACED5548DFF0A24147FEDE87B22505DC11FBC4F080C3E17A11BA588AE2A40AFCFDF352F9031F8F344E909C2ECCD912E2BA6B864C2DE6CFB4F50E03C17F0F2F";
final String u    = "9EC636117E558F3A1C9E03E54A1FADD9F0A6728F34C5842B6F557D58C92BCB243FDB62AA9751B5AA24B4B5129B253ED97D3A69818C7AD2AA6483C2473C1E52F7";
final String dp   = "9D165DC5C5AF1AA6C70E05355A06F7BD1CBA9D5DB0297A3845B4CCEDD8FD085F77A04E60FF139AE3EFA4DBC0974072FCCF08E8F4DF80F474A9FAD50881454D79";
final String dq   = "7332D781EA1AC0A4413AAC08E7A4C4ECEB38E151CA4B0BA499D56B29A914AA2DE42845D1DE51E6A5A39940F683DC8ED4EB21D0AE0C7360AC5149710525FA830B";
 
CryptoServerCXI.KeyComponents comp = new CryptoServerCXI.KeyComponents();
comp.add(CryptoServerCXI.KeyComponents.TYPE_MOD, new BigInteger(mod,16));
comp.add(CryptoServerCXI.KeyComponents.TYPE_PEXP, new BigInteger(pexp,16));
comp.add(CryptoServerCXI.KeyComponents.TYPE_SEXP, new BigInteger(sexp,16));
comp.add(CryptoServerCXI.KeyComponents.TYPE_P, new BigInteger(p,16));
comp.add(CryptoServerCXI.KeyComponents.TYPE_Q, new BigInteger(q,16));
comp.add(CryptoServerCXI.KeyComponents.TYPE_DP, new BigInteger(dp,16));
comp.add(CryptoServerCXI.KeyComponents.TYPE_DQ, new BigInteger(dq,16));
comp.add(CryptoServerCXI.KeyComponents.TYPE_U, new BigInteger(u,16));
 
CryptoServerCXI.Key rsaKey = cxi.importClearKey(CryptoServerCXI.FLAG_OVERWRITE, CryptoServerCXI.KEY_BLOB_SIMPLE, attr, comp);

crypt() [1/2]

byte[] crypt	(	int	flags,
		Key	key,
		int	mech,
		byte[]	mechParam,
		byte[]	data,
		ByteArray	iv,
		ByteArray	tag,
		byte[]	tag_in
	)		throws IOException, CryptoServerException

Encrypt or decrypt data.

The following algorithms are supported:

• DES
• AES
• RSA
• ECC (ECIES)

Parameters

flags	Command flags: FLAG_CRYPT_FINAL: last data chunk given, finalize operation (currently used on AES GCM and CCM modes only).
key	Key to be used for encryption or decryption. The key usage property has to contain the KEY_USAGE_ENCRYPT and/or KEY_USAGE_DECRYPT value (see Usage Specifier).
mech	XOR combination of mechanisms (see Mechanism Parameter): Crypt mode (see Mode Parameter): MECH_MODE_ENCRYPT : Encrypt data MECH_MODE_DECRYPT : Decrypt data Chaining mode (see Chaining Modes): DES, AES: MECH_CHAIN_ECB : Use 'Electronic Codebook' mode (no chaining) MECH_CHAIN_CBC : Use 'Cipher Block Chaining' mode MECH_CHAIN_GCM : Use 'Galois Counter Mode Chaining' mode (AES only) MECH_CHAIN_CCM : Use 'Counter with Cipher Block Chaining-Message Authentication Code' mode (AES only) MECH_CHAIN_OFB : Use 'Output Feedback Mode' mode (AES only) MECH_CHAIN_KEY_WRAP : Use 'AES Key Wrap' mode (AES only; NIST SP800-38F) Padding mode (see Padding Modes): DES, AES: MECH_PAD_NONE : Don't apply any padding (data length has to be a multiple of algorithms block size) MECH_PAD_PKCS5 : Apply padding according to PKCS#5 MECH_PAD_RANDOM : Apply random padding MECH_PAD_ISO7816 : Apply padding according to ISO 7816 MECH_PAD_KWP : Apply padding according to NIST SP800-38F RSA: MECH_PAD_NONE : Don't apply any padding (data length has to be smaller than length of modulus) MECH_PAD_PKCS1 : Apply padding according to PKCS#1 v1_5 (block type 2) MECH_PAD_OAEP : Apply padding according to PKCS#1-v2.1 EME-OAEP. Additionally the MGF hash algorithm and a label have to be given in this case. Hash algorithm (see Hash Algorithms): RSA: MECH_HASH_ALGO_XXX : hash algorithm for OAEP ECIES: XOR combination of Key Derivation Function (see Key Derivation Parameter): MECH_KDF_ECDH_COF : include cofactor of curve into hash calculation Key Generation Parameter (see Key Generation Parameter): MECH_KEYGEN_COMP : Public key in compressed form. MECH_KEYGEN_UNCOMP : Public key in uncompressed form.
mechParam	Optional mechanism parameter (see MechanismParameter) or null if no mechanism parameter should be used: AES: CryptoServerCXI.MechParamGCM CryptoServerCXI.MechParamCCM RSA: CryptoServerCXI.MechParamOAEP ECDSA: CryptoServerCXI.MechParamECIES
data	Data to be en- or decrypted.
iv	Initialization vector used to chain cipher blocks. If no initialization vector is given (null) a null-vector is used (symmetric algorithms only). For GCM and CCM, the initialization vector is part of the mechanism parameter. iv is used for chunking purposes only and must be initialized to an empty ByteArray. When data is passed to this function in several chunks, the iv resulting of a call has to be used as input for the next call. The initialization vector has to be absent for asymmetric algorithms.
tag	Authentication tag / MAC for AES GCM / CCM or null Is needed only on encryption or if data is passed in chunks: On encryption, calculated authentication tag / MAC is returned in this ByteArray in the final call. When data is passed to this function in several chunks, the tag resulting of a call has to be used as input for the next call. If needed, it must be initialized to an empty ByteArray on the first call. Can be null otherwise.
tag_in	Authentication tag / MAC for AES GCM / CCM to check when decrypting or null.

Returns

Encrypted or decrypted data.

Example:

The following code illustrates how to encrypt and decrypt data with an AES key:

// create instance of CryptoServerCXI (opens connection to CryptoServer)
CryptoServerCXI cxi = new CryptoServerCXI("192.168.4.183", 3000);
cxi.setTimeout(60000);
 
// logon
cxi.logonPassword("CXI_HMAC", "utimaco");
 
// generate key
CryptoServerCXI.KeyAttributes attr = new CryptoServerCXI.KeyAttributes();
attr.setAlgo(CryptoServerCXI.KEY_ALGO_AES);
attr.setSize(256);
attr.setName("AES_DEMO_KEY");
attr.setGroup("MyKeyGroup");
 
CryptoServerCXI.Key aesKey = cxi.generateKey(CryptoServerCXI.FLAG_OVERWRITE, attr);
 
// encrypt data in CBC mode (demonstrates chunked encryption)
String text = "Oh, say can you see by the dawn's early light\n"
            + "What so proudly we hailed at the twilights last gleaming?\n"
            + "Whose broad stripes and brought stars thru the perilous fight,\n"
            + "O'er the ramparts we watched were so gallantly streaming?\n"
            + "And the rocket's red glare, the bombs bursting in air,\n"
            + "Gave proof through the night that our flag was still there.\n"
            + "Oh, say does that star-spangled banner yet wave\n"
            + "O'er the land of the free and the home of the brave?\n";
 
byte [] data = text.getBytes();
byte [] crypto = new byte[0];
CryptoServerCXI.ByteArray iv = new CryptoServerCXI.ByteArray();
 
int mech = CryptoServerCXI.MECH_MODE_ENCRYPT | CryptoServerCXI.MECH_CHAIN_CBC;
int rlen = data.length;
int ofs = 0;
int len = 16;
 
while (rlen > 0)
{
  if (rlen <= 16)
  {
    len = rlen;
    mech |= CryptoServerCXI.MECH_PAD_PKCS5;  // apply padding on last block
  }
 
  byte [] chunk = copyOf(data, ofs, len);
  crypto = concat(crypto, cxi.crypt(0, aesKey, mech, null, chunk, iv, null, null));
 
  rlen -= len;
  ofs += len;
}
 
// decrypt data (in one shot)
mech = CryptoServerCXI.MECH_MODE_DECRYPT | CryptoServerCXI.MECH_CHAIN_CBC | CryptoServerCXI.MECH_PAD_PKCS5;
byte [] plain = cxi.crypt(aesKey, mech, null, crypto, null);
 
System.out.println(new String(plain));
 
// compare result
if (!Arrays.equals(plain, data))
{
  CryptoServerUtil.xtrace("data", data);
  CryptoServerUtil.xtrace("encrypted data", crypto);
  CryptoServerUtil.xtrace("decrypted data", plain);
  throw new CryptoServerException(-1, "decrypted data doesn't match original data");
}
 
cxi.logoff();
cxi.close();

crypt() [2/2]

byte[] crypt	(	Key	key,
		int	mech,
		byte[]	mechParam,
		byte[]	data,
		ByteArray	iv
	)		throws IOException, CryptoServerException

Encrypt or decrypt data.

See also

crypt(int flags, Key key, int mech, byte[] mechParam, byte[] data, ByteArray iv, ByteArray tag, byte[] tag_in)

bulkCrypt()

byte[][] bulkCrypt	(	Key	key,
		int	mech,
		byte	data[][]
	)		throws IOException, CryptoServerException

Encrypt or decrypt multiple data items in one operation.

The function utilizes a cryptographic accelerator if present on the target hardware and therefore speeds up RSA calculations.

Parameters

key	RSA Key to be used for encryption or decryption. The key usage property has to contain the KEY_USAGE_ENCRYPT and/or KEY_USAGE_DECRYPT value (see Usage Specifier).
mech	XOR combination of mechanisms (see Mechanism Parameter): Crypt mode (see Mode Parameter): MECH_MODE_ENCRYPT : Encrypt data MECH_MODE_DECRYPT : Decrypt data Padding mode (see Padding Modes): MECH_PAD_NONE : Don't apply any padding (data length has to be smaller than length of modulus)
data	Array of data items to be en- or decrypted

Returns

Array of encrypted or decrypted data items

sign() [1/2]

byte[] sign	(	int	flags,
		Key	key,
		int	mech,
		byte[]	mechParam,
		byte[]	data,
		ByteArray	iv
	)		throws IOException, CryptoServerException

Digitally signs the given hash value (asymmetric algorithms) or calculates a Message Authentication Code (MAC) or hash based MAC (HMAC) (symmetric algorithms).

The function supports cipher block chaining on MACs and multipart calculation on HMACs and hashing for asymmetric algorithms.
On MAC calculation the returned MAC can be used as input IV on the next block.
On HMAC calculation and asymmetric algorithms the function can be instructed not to finalize the hash but return the intermediate digest information that can be used as input ('IV') for the next block.

Parameters

flags	Command flags (see Command Flags): FLAG_HASH_PART: don't finalize hash calculation but return intermediate digest information to continue a multipart calculation on next function call. FLAG_HASH_DATA: given data has to be hashed before getting signed (asymmetric algorithms only). FLAG_CRYPT_FINAL: Finalize CMAC or GMAC creation operation (AES-CMAC/GMAC only) A value of 0 can be used to set none of the above flags.
key	Key to be used to create the signature or calculate the MAC or HMAC. The key usage property has to contain the KEY_USAGE_SIGN value (see Usage Specifier).
mech	XOR combination of mechanism parameter (see Mechanism Parameter): Chaining mode (see Chaining Modes): DES: MECH_CHAIN_CBC : Use 'Cipher Block Chaining' mode MECH_CHAIN_CBC_RETAIL: Calculate a CBC Retail MAC according to ISO 9797 (often used in german payment systems). MECH_CHAIN_CFB_RETAIL: Calculate a CFB Retail MAC (often used in german payment systems). AES: MECH_CHAIN_CBC : Use 'Cipher Block Chaining' mode MECH_CHAIN_CMAC : Calculate a CMAC according to NIST-SP800-38B. MECH_CHAIN_GCM: Calculate Galois Counter MAC (GMAC). Padding mode (see Padding Modes): DES, AES: MECH_PAD_NONE : Don't apply any padding (data length has to be a multiple of algorithms block size) MECH_PAD_PKCS5 : Apply padding according to PKCS#5 MECH_PAD_ISO7816 : Apply padding according to ISO 7816 MECH_PAD_ZEROFILL : Pad up to <block-length> zero bytes RSA: MECH_PAD_NONE : Don't apply any padding (data length has to be smaller than length of modulus) MECH_PAD_PKCS1 : Apply padding according to PKCS#1-v1_5 (block type 1). MECH_PAD_X9_31 : Apply padding according to ANSI X9.31 MECH_PAD_PSS : Apply padding according to PKCS#1-v2.1 (RSASSA-PSS) Hash algorithm (see Hash Algorithms) HMAC mode: DES, AES: MECH_MODE_HMAC : Calculate hash based MAC
mechParam	optional mechanism parameter (see MechanismParameter) or null if no mechanism parameter should be used: AES: CryptoServerCXI.MechParamGMAC RSA: CryptoServerCXI.MechParamPSS
data	Hash value to be signed or data to be MAC'ed. The length of the data may not exceed 240 kB. Larger data has to be split into chunks by the application and every chunk has to be signed separately.
iv	Initialization vector used to chain cipher blocks or digest information to continue a multipart hash calculation. If no initialization vector is given (null) a Null-vector is used. The given value will be overwritten on return of the function. For GMAC on non-final calls, this parameter contains intermediate values. On GMAC's final signing call, if the CryptoServer generated an internal IV, that IV is returned in this parameter.

Returns

Signature (asymmetric algorithms), MAC, HMAC or digest information (in case FLAG_HASH_PART was set in the command flags) or CMAC/GMAC intermediate value (if CXI_FLAG_CRYPT_FINAL was not set).

Example:

The following code illustrates how to create and verify a digital signature with a RSA key:

// create instance of CryptoServerCXI (opens connection to CryptoServer)
CryptoServerCXI cxi = new CryptoServerCXI(device, 3000);
cxi.setTimeout(60000);
 
// logon
cxi.logonPassword("CXI_HMAC", "utimaco");
 
// generate RSA key
CryptoServerCXI.KeyAttributes attr = new CryptoServerCXI.KeyAttributes();
attr.setAlgo(CryptoServerCXI.KEY_ALGO_RSA);
attr.setSize(2048);
attr.setName("RSA_DEMO_KEY");
attr.setGroup("MyKeyGroup");
 
CryptoServerCXI.Key rsaKey = cxi.generateKey(CryptoServerCXI.FLAG_OVERWRITE, attr);
 
// hash data
MessageDigest md = MessageDigest.getInstance("SHA-512", "SUN");
md.update(data, 0, data.length);
byte [] hash = md.digest();
 
// RSA sign hash
mech = CryptoServerCXI.MECH_HASH_ALGO_SHA512 | CryptoServerCXI.MECH_PAD_PKCS1;
byte [] sign = cxi.sign(0, rsaKey, mech, hash, null);
CryptoServerUtil.xtrace("signature", sign);
 
// RSA verify signature
boolean result = cxi.verify(rsaKey, mech, hash, sign);
 
if (result != true)
  throw new CryptoServerException(-1, "signature verification failed");
 
cxi.logoff();
cxi.close();

Example:

The following code illustrates how to create and verify a digital signature with a ECDSA key:

// create instance of CryptoServerCXI (opens connection to CryptoServer)
CryptoServerCXI cxi = new CryptoServerCXI(device, 3000);
cxi.setTimeout(60000);
 
// logon
cxi.logonPassword("CXI_HMAC", "utimaco");
 
// generate ECDSA key
CryptoServerCXI.KeyAttributes attr = new CryptoServerCXI.KeyAttributes();
attr.setAlgo(CryptoServerCXI.KEY_ALGO_ECDSA);
attr.setSize(0);
attr.setCurve("NIST-P256");
attr.setName("ECC_DEMO_KEY");
attr.setGroup("MyKeyGroup");
 
CryptoServerCXI.Key ecKey = cxi.generateKey(CryptoServerCXI.FLAG_OVERWRITE, attr);
 
// create random test data to be signed
byte [] data = cxi.generateRandom(256, CryptoServerCXI.MECH_RND_PSEUDO);
 
// compute hash
MessageDigest md = MessageDigest.getInstance("SHA1");
md.update(data);
byte [] hash = md.digest();
 
// sign hash
byte [] sign = cxi.sign(ecKey, 0, hash);
CryptoServerUtil.xtrace("signature", sign);
 
// verify
boolean result = cxi.verify(ecKey, 0, hash, sign);
if (result != true)
  throw new CryptoServerException(-1, "signature verification failed");
 
cxi.logoff();
cxi.close();

sign() [2/2]

byte[] sign	(	Key	key,
		int	mech,
		byte[]	data
	)		throws IOException, CryptoServerException

Digitally signs the given hash value (asymmetric algorithms) or calculates a Message Authentication Code (MAC) or hash based MAC (HMAC) (symmetric algorithms).

See also

sign(int flags, Key key, int mech, byte [] mechParam, byte [] data, ByteArray iv)

bulkSign()

byte[][] bulkSign	(	Key	key,
		int	mech,
		byte	data[][]
	)		throws IOException, CryptoServerException

Digitally signs up to 16(ECDSA)/50(RSA) hash values in one operation.

The function utilizes a cryptographic accelerator if present on the target hardware and therefore speeds up RSA and ECDSA calculations.

Parameters

key	RSA or ECDSA Key to be used to create the signature. The key usage property has to contain the KEY_USAGE_SIGN value (see Usage Specifier).
mech	XOR combination of mechanism (see Mechanism Parameter): Padding mode (see Padding Modes): MECH_PAD_NONE : Don't apply any padding (data length has to be smaller than length of modulus) MECH_PAD_PKCS1 : Apply padding according to PKCS#1-v1_5 (block type 1). Hash algorithm (see Hash Algorithms) Output format (see Format Parameter) (Note that ECDSA bulk signing does not currently support ASN1 output!)
data	Array of hash values to be signed.

Returns

Array of signatures

verify() [1/2]

boolean verify	(	int	flags,
		Key	key,
		int	mech,
		byte[]	mechParam,
		byte[]	data,
		byte[]	signature,
		ByteArray	iv
	)		throws IOException, CryptoServerException

Verifies a digital signature, Message Authentication Code (MAC) or hash based MAC (HMAC).

The function supports cipher block chaining on MACs and multipart calculation on HMACs.
On MAC verification the returned IV can be used as input IV on the next block.
On HMAC calculation the function can be instructed not to finalize the HMAC but return the intermediate HMAC digest information that can be used as input ('IV') for the next block.

Parameters

flags	Command flags (see Command Flags): FLAG_HASH_PART: don't finalize HMAC calculation but return intermediate HMAC digest information to continue a multipart calculation on next function call. FLAG_HASH_DATA: given data has to be hashed before comparison (asymmetric algorithms only). FLAG_CRYPT_FINAL: Finalize CMAC or GMAC verification operation (AES-CMAC/GMAC only) A value of 0 can be used to set none of the above flags.
key	Key to be used to verify the signature, MAC or HMAC. The key usage property has to contain the KEY_USAGE_VERIFY value (see cxi_usage).
mech	XOR combination of mechanism (see Mechanism Parameter): Chaining mode (see Chaining Modes): DES: MECH_CHAIN_CBC : Use 'Cipher Block Chaining' mode MECH_CHAIN_CBC_RETAIL: Calculate a CBC Retail MAC according to ISO 9797 (often used in german payment systems). MECH_CHAIN_CFB_RETAIL: Calculate a CFB Retail MAC (often used in german payment systems). AES: MECH_CHAIN_CBC : Use 'Cipher Block Chaining' mode MECH_CHAIN_CMAC : Calculate a CMAC according to NIST-SP800-38B. MECH_CHAIN_GCM: Calculate Galois Counter MAC (GMAC). Padding mode (see Padding Modes): DES, AES: MECH_PAD_NONE : Don't apply any padding (data length has to be a multiple of algorithms block size) MECH_PAD_PKCS5 : Apply padding according to PKCS#5 MECH_PAD_ISO7816 : Apply padding according to ISO 7816 MECH_PAD_ZEROFILL : Pad up to <block-length> zero bytes RSA: MECH_PAD_NONE : Don't apply any padding (data length has to be smaller than length of modulus) MECH_PAD_PKCS1 : Apply padding according to PKCS#1-v1_5 (block type 1). MECH_PAD_X9_31 : Apply padding according to ANSI X9.31 MECH_PAD_PSS : Apply padding according to PKCS#1-v2.1 (RSASSA-PSS) Hash algorithm (see Hash Algorithms) HMAC mode: DES, AES: MECH_MODE_HMAC : Calculate hash based MAC
mechParam	Optional mechanism parameter (see MechanismParameter) or null if no mechanism parameter should be used: AES: CryptoServerCXI.MechParamGMAC RSA: CryptoServerCXI.MechParamPSS
data	Reference hash to be compared (asym. algorithms) or data to be MAC'ed for comparison. The length of the data may not exceed 240 kB. Larger data has to be split into chunks by the application and every chunk has to be signed separately.
signature	Signature, MAC or HMAC to be verified In case of cipher block chaining (symmetric keys), the MAC to be compared has to be given with the last chaining block. In case of a multipart HMAC calculation the HMAC to be compared has to be given with the last part. If no MAC/HMAC is given, the updated MAC/HMAC is returned but no comparison takes place.
iv	Initialization vector used to chain cipher blocks or HMAC digest information used to calculate a multipart HMAC. If no initialization vector is given (null) a Null-vector is used. The given value will be overwritten on return of the function. The initialization vector has to be absent for asymmetric algorithms. For GMAC on non-final calls, this parameter contains intermediate values.

Returns

true if verification succeeded, otherwise false

verify() [2/2]

boolean verify	(	Key	key,
		int	mech,
		byte[]	data,
		byte[]	signature
	)		throws IOException, CryptoServerException

Verifies a digital signature, Message Authentication Code (MAC) or hash based MAC (HMAC).

See also

verify(int flags, Key key, int mech, byte [] mechParam, byte [] data, byte [] signature, ByteArray iv)

generateRandom()

byte[] generateRandom	(	int	length,
		int	mech
	)		throws IOException, CryptoServerException

Generate random bytes.

Parameters

length	Number of random bytes to be generated.
mech	Generation mode (see Random Generation Parameter): MECH_RND_REAL: use hardware (real) random number generator (better, slower) MECH_RND_PSEUDO: use deterministic (pseudo) random number generator (faster) A value of -1 can be used to set the default values.

Returns

Random data

computeHash()

byte[] computeHash	(	int	flags,
		int	mech,
		byte[]	data,
		byte[]	info,
		Key	key
	)		throws IOException, CryptoServerException

Computes a hash or hash based MAC (HMAC) over the given data.

Parameters

flags	Command flags: FLAG_HASH_PART: Don't finalize hash but return hash digest information to be continued on next call (multipart hash calculation). A value of 0 can be used to set none of the above flags.
mech	XOR combination of hash mode (see Mode Parameter) and hash algorithm (see Hash Algorithms).
data	Plain data to be hashed.
info	Optional hash digest information to continue a multipart hash calculation or NULL_REF(ByteArray) to start a new hash calculation.
key	Optional key: on Hash calculation: Secret key whose key components should be hashed. on HMAC calculation: Secret key to be used for HMAC calculation.

Returns

Computed hash or HMAC value (flags == 0) or hash digest information (flags == FLAG_HASH_PART).

Example:

The following code sample illustrates how to compute a SHA256 hash:

// create instance of CryptoServerCXI (opens connection to CryptoServer)
CryptoServerCXI cxi = new CryptoServerCXI(device, 3000);
cxi.setTimeout(60000);
 
// logon
cxi.logonPassword("CXI_HMAC", "utimaco");
 
// generate random data to be hashed
int data_len = (int)(Math.random() * 1000);
byte [] data = cxi.generateRandom(data_len, -1);
 
// chunked hash calculation
int flags = CryptoServerCXI.FLAG_HASH_PART;
int mech = CryptoServerCXI.MECH_MODE_HASH | CryptoServerCXI.MECH_HASH_ALGO_SHA256;
int len = 64;
int ofs = 0;
byte [] hash = null;
 
while (data_len > 0)
{
  if (data_len <= 64)
  {
    flags = 0;
    len = data_len;
  }
 
  byte [] chunk = copyOf(data, ofs, len);
  hash = cxi.computeHash(flags, mech, chunk, hash, null);
 
  data_len -= len;
  ofs += len;
}
 
CryptoServerUtil.xtrace("hash", hash);
 
// recalculate in one shot
byte [] rhash = cxi.computeHash(0, mech, data, null, null);
CryptoServerUtil.xtrace("recalculated hash (one shot)", rhash);
 
if (!Arrays.equals(hash, rhash))
  throw new CryptoServerException(-1, "hash doesn't match reference hash");
 
// recalculate locally
MessageDigest md = MessageDigest.getInstance("SHA-256");
md.update(data);
rhash = md.digest();
 
CryptoServerUtil.xtrace("recalculated hash (local)", rhash);
 
if (!Arrays.equals(hash, rhash))
  throw new CryptoServerException(-1, "hash doesn't match reference hash");
 
cxi.logoff();
cxi.close();

agreeSecret()

byte[] agreeSecret	(	int	flags,
		Key	privateKey,
		Key	publicKey,
		int	mech,
		byte[]	mechParam
	)		throws IOException, CryptoServerException

This function calculates a shared secret from two ECDH or ECDSA keys as described in TR-03111.

The algorithm is based on a point multiplication, which takes the private part of the first key and the public part of the second key as input parameter. The returned secret consists either of the complete resulting point (x and y coordinate) or only of its x- coordinate in case CXI_MECH_FORMAT_X was given in the mechanism parameters. The function returns either the plain secret value or encrypts the secret with the CryptoServer's MBK in case CXI_FLAG_ENCRYPT_SECRET was given in the command flags.

Note

The secret value (either plain or encrypted) can be used as input to the ComputeHash function.

Parameters

flags	Command flags (see Command Flags): FLAG_ENCRYPT_SECRET: return MBK encrypted secret value (default) 0: return unencrypted secret value
privateKey	Private part of key #1. The key usage property has to contain the KEY_USAGE_DERIVE value.
publicKey	Public part of key #2. note This value may also be given in the mechanism parameters.
mech	Mechanism (see Mechanism Parameter): MECH_FORMAT_X: return only x-coordinate of secret point (default). 0: return x and y coordinate of secret point.
mechParam	Public Key: X9.42 encoded public part of key #2 (optional, if not already given in the publicKey parameter)

Returns

The secret value (either x and y coordinate or x-coordinate only). The secret value is encrypted with the CryptoServer's MBK if FLAG_ENCRYPT_SECRET was given in the command flags (tag 'SB'). Otherwise the plain secret will be returned (tag 'DA').

deriveKey()

Key deriveKey	(	int	flags,
		Key	privateKey,
		KeyAttributes	keyTemplate,
		int	mech,
		byte[]	mechParam
	)		throws IOException, CryptoServerException

Parameters

flags
privateKey
keyTemplate
mech

Returns

Exceptions

IOException
CryptoServerException

setFIPSUsage() [1/2]

Key setFIPSUsage	(	Key	key,
		int	usage
	)		throws CryptoServerException, IOException

Sets the FIPS usage/padding specifier in the attribute list of the Key.

Parameters

key	The Key for which the FIPS usage should be set.
usage	The usage/padding specifier to be set

Returns

The resulting Key with the specified usage/padding specifier set.

Key()

Key

(

byte[]

value

)

throws CryptoServerException

Creates a key object from the given data.

Parameters

value

Serialized key blob or key handle encoded in CryptoServer format

isHandle()

boolean isHandle

(

)

Inquires if the key contains a key handle.

Returns

• true if key contains a handle to a key stored on a CryptoServer
• false if the key contains a key blob (of type 'Backup Blob'), see Format of Key Blobs.

getEncoded()

byte[] getEncoded

(

)

Returns the key in its encoded (serialized) form.

Returns

Either the key handle or the key blob (see Format of Key Blobs)

getAttributes()

KeyAttributes getAttributes

(

)

throws CryptoServerException

Returns the key attributes.

Returns

key attributes of key blob.

Exceptions

CryptoServerException

if the key is a reference to an internal key (key handle).

getUName()

byte[] getUName

(

)

throws NoSuchAlgorithmException, CryptoServerException

Returns the unique key name.

Returns

Unique key name, which is the MD5 hash over group, name and specifier.

KeyAttributes() [1/2]

KeyAttributes	(	byte[]	list,
		int	ofs
	)		throws CryptoServerException

Creates a key attribute list from the given (serialized) attribute stream.

Parameters

list	Serialized attribute list.
ofs	Offset to attribute list.

KeyAttributes() [2/2]

KeyAttributes

(

byte[]

list

)

throws CryptoServerException

Creates a key attribute list from the given (serialized) attribute stream.

Parameters

list	Serialized attribute list.

clone()

KeyAttributes clone

(

)

Creates a full copy of the source object.

Returns

Cloned KeyAttributes object

toByteArray()

byte[] toByteArray

(

)

throws CryptoServerException

Serializes the attribute list and returns an attribute stream.

Attribute lists are encoded in a simple, TLV encoded key blob format. Each item is encoded as follows:

Tag	Lengh	Value
2 bytes	2 bytes	Length bytes

Note

Length fields are encoded in big endian notation.

Returns

Serialized attribute list.

setAlgo()

void setAlgo

(

int

algo

)

Sets the key algorithm attribute.

Parameters

algo	Algorithm specifier (see Algorithm Specifier).

getAlgo()

int getAlgo

(

)

Returns the key algorithm attribute.

Returns

Key algorithm (see Algorithm Specifier)

setType()

void setType

(

int

type

)

Sets the key type attribute.

Parameters

type	key type attribute (see Key Types).

setSize()

void setSize

(

int

size

)

Sets the key size.

Parameters

size	Key size in bits.

getSize()

int getSize

(

)

Returns the key size in bits.

Returns

Key size

setExport()

void setExport

(

int

exp

)

Sets the key export attribute.

Parameters

exp	Key export attribute (see Export Policy Specifier).

getExport()

int getExport

(

)

Returns the key export attribute.

Returns

Key export attribute (see Export Policy Specifier).

setUsage()

void setUsage

(

int

usage

)

Sets the key usage attribute.

Parameters

usage

Key usage attribute (see Usage Specifier).

getUsage()

int getUsage

(

)

Returns the key usage attribute.

Returns

Key usage attribute (see Usage Specifier).

setLabel()

void setLabel

(

String

label

)

throws CryptoServerException

Sets the key label attribute.

Parameters

label

Optional label to be set for the key.

getLabel()

String getLabel

(

)

throws CryptoServerException

Returns the key label attribute.

Returns

Key label attribute or null if the label was not set.

setExponent() [1/2]

void setExponent

(

byte[]

exp

)

Sets the public exponent of a RSA key.

Parameters

exp	Public exponent of the key.

setExponent() [2/2]

void setExponent

(

BigInteger

exp

)

Sets the public exponent of a RSA key.

Parameters

exp	Public exponent of the key.

getExponent()

byte[] getExponent

(

)

Returns the public exponent of a RSA key.

Returns

Public exponent

setModulus() [1/2]

void setModulus

(

byte[]

mod

)

Sets the modulus of a RSA key.

Parameters

mod	Modulus of the RSA key.

setModulus() [2/2]

void setModulus

(

BigInteger

mod

)

Sets the modulus of a RSA key.

Parameters

mod	Modulus of the RSA key.

getModulus()

byte[] getModulus

(

)

Returns the modulus of a RSA key.

Returns

Modulus

setParamP() [1/2]

void setParamP

(

byte[]

par

)

Sets the prime value P of a DSA key.

Parameters

par	Prime value P of the DSA key.

setParamP() [2/2]

void setParamP

(

BigInteger

par

)

Sets the prime value P of a DSA key.

Parameters

par	Prime value P of the DSA key.

getParamP()

byte[] getParamP

(

)

Returns the prime value P of a DSA key.

Returns

Prime P

setParamQ() [1/2]

void setParamQ

(

byte[]

par

)

Sets the prime value Q of a DSA key.

Parameters

par	Prime value Q of the DSA key.

setParamQ() [2/2]

void setParamQ

(

BigInteger

par

)

Sets the prime value Q of a DSA key.

Parameters

par	Prime value Q of the DSA key.

getParamQ()

byte[] getParamQ

(

)

Returns the prime value Q of a DSA key.

Returns

Prime Q

setParamG() [1/2]

void setParamG

(

byte[]

par

)

Sets the generator value G of a DSA key.

Parameters

par	Generator value G of the DSA key.

setParamG() [2/2]

void setParamG

(

BigInteger

par

)

Sets the generator value G of a DSA key.

Parameters

par	Generator value G of the DSA key.

setDSAPub() [1/2]

void setDSAPub

(

byte[]

par

)

Sets the public key part of a DSA key.

Parameters

par	Public key part of the DSA key.

setDSAPub() [2/2]

void setDSAPub

(

BigInteger

par

)

Sets the public key part of a DSA key.

Parameters

par	Public key part of the DSA key.

setCurve() [1/3]

void setCurve

(

String

name

)

throws CryptoServerException

Sets the domain parameter of an ECDSA key.

Parameters

name	Name of the build in curve to be set (e.g. "NIST-P256")

setCurve() [2/3]

void setCurve

(

byte[]

curve

)

Sets the domain parameter of an ECDSA key.

Parameters

curve

Curve to be set, either the object identifier for a build in curve or the ASN1 coded curve definition.

setCurve() [3/3]

void setCurve

(

ECParameterSpec

curve

)

throws CryptoServerException

Sets the domain parameter for an ECDSA key.

Parameters

curve

Encoded domain parameter to be set for the key.

getCurve()

byte[] getCurve

(

)

Returns the domain parameters for a ECDSA key.

Returns

Domain parameter of the curve as set on creation, either

• curve name
• object identifier
• ASN1 encoded curve definition

getCurveEncoded()

byte[] getCurveEncoded

(

)

throws IOException, CryptoServerException

Returns the domain parameters for a ECDSA key.

Returns

ASN1 encoded curve definition.

setECPub() [1/2]

void setECPub

(

byte[]

par

)

Sets the public key part of a ECDSA key.

Parameters

par	Public key part of the ECDSA key.

setECPub() [2/2]

void setECPub

(

BigInteger

par

)

Sets the public key part of a ECDSA key.

Parameters

par	Public key part of the ECDSA key.

getECPub()

byte[] getECPub

(

)

Returns the public key part of a ECDSA key.

Returns

Public key part in encoded format (see ANSI X9.62)

setName()

void setName

(

String

name

)

throws CryptoServerException

Sets the key name attribute.

Parameters

name	Name of the key that is used to identify the key. The key name attribute is mandatory for keys stored on the CryptoServer but optional for keys stored externally.

getName()

String getName

(

)

throws CryptoServerException

Returns the key name.

Returns

Key name or null if the key doesn't have a name attribute.

setGroup()

void setGroup

(

String

group

)

throws CryptoServerException

Sets the key group attribute.

Parameters

group

Key group of the key. The key group attribute is used to apply access restrictions on a key. If set the key can only be access by users of the corresponding user group. If no key group is set for a key, it can be accessed by everyone.

getGroup()

String getGroup

(

)

throws CryptoServerException

Returns the key group.

Returns

Key group or null if the key doesn't have a group attribute.

setSpecifier()

void setSpecifier

(

int

spec

)

Sets the key specifier attribute.

Parameters

spec	Key specifier of the key. The key specifier is an optional attribute that can be set in addition to name and group to identify the key. A value of -1 is used to mark an empty attribute and should therefor not be set.

getSpecifier()

int getSpecifier

(

)

Returns the key specifier.

Returns

Key specifier or -1 if the key doesn't have a specifier attribute.

setGenerationDate() [1/2]

void setGenerationDate

(

Date

date

)

Sets the generation date attribute of the key.

Parameters

date	Generation date to be set.

setGenerationDate() [2/2]

void setGenerationDate

(

byte[]

utcTime

)

Sets the generation date attribute of the key.

Parameters

utcTime

time string ('YYMMDDHHMMSSZ')

setExpirationDate() [1/2]

void setExpirationDate

(

Date

date

)

Sets the expiration date attribute of the key.

Parameters

date	Expiration date to be set.

setExpirationDate() [2/2]

void setExpirationDate

(

byte[]

utcTime

)

Sets the expiration date attribute of the key.

Parameters

utcTime

time string ('YYMMDDHHMMSSZ')

getGenerationDate()

Date getGenerationDate

(

)

Returns the generation date attribute or null if the data attribute was not set.

Returns

Generation date attribute

getExpirationDate()

Date getExpirationDate

(

)

Returns the expiration date attribute or null if the data attribute was not set.

Returns

Expiration date attribute

setCertificate()

void setCertificate

(

byte[]

cert

)

Sets a certificate for the key.

Parameters

cert	Optional certificate of the key.

setMechs()

void setMechs

(

int[]

mechs

)

throws CryptoServerException, UnsupportedEncodingException

Sets an int array with mechanisms for a key.

Parameters

mechs

Key mechanisms int array.

Exceptions

UnsupportedEncodingException
CryptoServerException

getMechs()

byte[] getMechs

(

)

Returns a list of key mechanisms as byte array.

Returns

Key mechanisms

setFIPSUsage() [2/2]

void setFIPSUsage

(

int

usage

)

Sets the fips key usage/padding specifier attribute.

Parameters

usage

FIPS Key usage/padding specifier attribute (see Usage / Padding Specifier for FIPS).

getFIPSUsage()

int getFIPSUsage

(

)

Returns the fips key usage/padding specifier attribute.

Returns

FIPS Key usage/padding specifier attribute (see Usage / Padding Specifier for FIPS).

Variable Documentation

CxiLog

CryptoServerLog CxiLog = new CryptoServerLog("cxi.log", CryptoServerLog.LogLevel.Warning, 0x100000)

static

Static instance of CryptoServerLog that provides unified logging.

Initially the logging is disabled (log level is set to CryptoServerAPI.CryptoServerLog.LogLevel).

The application has to call CxiLog.init(...) with appropriate values to enable logging, e.g.:

...
CxiLog.init("/tmp/cxi.log", CryptoServerLog.LogLevel.Info, 0x100000);
...