Cxi Class Reference

Command interface to CXI firmware module. Handles all communication with the CryptoServer. More...

Classes
struct	CLUSTER_ERROR
	Defines an additional error code/mask that causes the cluster to switch to another device instead of returning to the caller. More...

Construction / Destruction
	Cxi (std::vector< std::string > devices, int timeout, int ctimeout, int fallback_interval, cxi::ByteArray *vendorCert, cxi::ByteArray *operatorCert, cxi::ByteArray *customerCert)
	Opens a connection to a CryptoServer cluster. More...
	Cxi (const char *device, int timeout=60000, int ctimeout=5000)
	Cxi (const char **devices, int ndevs, int timeout=60000, int ctimeout=5000, int fallback_interval=0)
	Cxi (std::vector< std::string > devices, int timeout=60000, int ctimeout=5000, int fallback_interval=0)
	Cxi (Config &config)
virtual	~Cxi (void)
void	set_msg_handler (void(*p_msg_func)(unsigned char *p_msg, int l_msg))
void	close (void)
	Cxi (std::vector< std::string > devices, int timeout, int ctimeout, int fallback_interval, cxi::ByteArray *vendorCert, cxi::ByteArray *operatorCert, cxi::ByteArray *customerCert)
	Cxi (const char *device, int timeout=60000, int ctimeout=5000)
	Cxi (const char **devices, int ndevs, int timeout=60000, int ctimeout=5000, int fallback_interval=0)
	Cxi (std::vector< std::string > devices, int timeout=60000, int ctimeout=5000, int fallback_interval=0)
	Cxi (Config &config)
virtual	~Cxi (void)
void	set_msg_handler (void(*p_msg_func)(unsigned char *p_msg, int l_msg))
void	close (void)

Miscellaneous Functions
void	exec (unsigned int fc, unsigned int sfc, unsigned char *p_cmd, unsigned int l_cmd, unsigned char **pp_answ, unsigned int *p_l_answ, CLUSTER_ERROR *errlist=NULL, unsigned int err_ct=0)
void	free_answ (unsigned char *&p_answ)
int	get_fw_version (void)
void	exec (unsigned int fc, unsigned int sfc, unsigned char *p_cmd, unsigned int l_cmd, unsigned char **pp_answ, unsigned int *p_l_answ, CLUSTER_ERROR *errlist=NULL, unsigned int err_ct=0)
void	free_answ (unsigned char *&p_answ)
int	get_fw_version (void)
static int	get_version (void)
static int	get_version (void)

Authentication
void	logon_sign (const char *user, const char *key, const char *password=0, bool keep_alive=false)
void	logon_pass (const char *user, const char *password, bool keep_alive=false)
void	logoff (void)
int	get_auth_state (void)
int	get_auth_state (const std::string &group)
void	logon_sign (const char *user, const char *key, const char *password=0, bool keep_alive=false)
void	logon_pass (const char *user, const char *password, bool keep_alive=false)
void	logoff (void)
int	get_auth_state (void)
int	get_auth_state (const std::string &group)

Key Management
KeyList	key_list (PropertyList *keyTemplate=NULL)
KeyList	key_list (PropertyList &keyTemplate)
Key	key_generate (int flags, const PropertyList &keyTemplate)
Key	key_generate (int flags, const PropertyList &keyTemplate, int mech)
Key	key_open (int flags, PropertyList &keyTemplate)
void	key_delete (const PropertyList &keyTemplate)
void	key_delete (Key &key)
PropertyList	key_prop_get (const Key &key, int properties[], int nprops)
Key	key_prop_set (const Key &key, const PropertyList &propList)
Key	key_set_fips_usage (const Key &key, unsigned int usage)
ByteArray	key_export (int type, Key &key, Key *exportKey, int mech=-1)
ByteArray	key_export (int type, Key &key, Key &exportKey, int mech=-1)
Key	key_import (int flags, int type, const PropertyList &keyTemplate, const ByteArray &keyBlob, Key *importKey, int mech=-1)
Key	key_import (int flags, int type, const PropertyList &keyTemplate, const ByteArray &keyBlob, Key &importKey, int mech=-1)
PropertyList	key_dsa_xgen (int psize, int qsize=160, int mech=-1)
PropertyList	key_dsa_pqgen (MechanismParameter &mechParam)
PropertyList	key_dsa_ggen (PropertyList &propList, const MechanismParameter &mechParam)
Key	key_backup (Key &key)
Key	key_restore (int flags, Key &key, PropertyList *keyTemplate=NULL)
Key	key_restore (int flags, Key &key, PropertyList &keyTemplate)
std::vector< ByteArray >	keystore_find (KeyStore &store, PropertyList *key_template=NULL)
Key	keystore_get (KeyStore &store, ByteArray &index)
void	keystore_insert (KeyStore &store, int flags, ByteArray *index, const Key *key)
void	keystore_delete (KeyStore &store, const ByteArray &index)
KeyList	key_list (PropertyList *keyTemplate=NULL)
KeyList	key_list (PropertyList &keyTemplate)
Key	key_generate (int flags, const PropertyList &keyTemplate)
Key	key_generate (int flags, const PropertyList &keyTemplate, int mech)
Key	key_open (int flags, PropertyList &keyTemplate)
void	key_delete (const PropertyList &keyTemplate)
void	key_delete (Key &key)
PropertyList	key_prop_get (const Key &key, int properties[], int nprops)
Key	key_prop_set (const Key &key, const PropertyList &propList)
Key	key_set_fips_usage (const Key &key, unsigned int usage)
ByteArray	key_export (int type, Key &key, Key *exportKey, int mech=-1)
ByteArray	key_export (int type, Key &key, Key &exportKey, int mech=-1)
Key	key_import (int flags, int type, const PropertyList &keyTemplate, const ByteArray &keyBlob, Key *importKey, int mech=-1)
Key	key_import (int flags, int type, const PropertyList &keyTemplate, const ByteArray &keyBlob, Key &importKey, int mech=-1)
PropertyList	key_dsa_xgen (int psize, int qsize=160, int mech=-1)
PropertyList	key_dsa_pqgen (MechanismParameter &mechParam)
PropertyList	key_dsa_ggen (PropertyList &propList, const MechanismParameter &mechParam)
Key	key_backup (Key &key)
Key	key_restore (int flags, Key &key, PropertyList *keyTemplate=NULL)
Key	key_restore (int flags, Key &key, PropertyList &keyTemplate)
std::vector< ByteArray >	keystore_find (KeyStore &store, PropertyList *key_template=NULL)
Key	keystore_get (KeyStore &store, ByteArray &index)
void	keystore_insert (KeyStore &store, int flags, ByteArray *index, const Key *key)
void	keystore_delete (KeyStore &store, const ByteArray &index)

Cryptography
ByteArray	crypt (int flags, const Key &key, const MechanismParameter &mechParam, const ByteArray &data, ByteArray *iv=NULL, ByteArray *tag=NULL, const ByteArray *tag_in=NULL)
ByteArray	crypt (int flags, const Key &key, const MechanismParameter &mechParam, const ByteArray &data, ByteArray &iv, ByteArray &tag, const ByteArray &tag_in)
ByteArray	crypt (int flags, const Key &key, const MechanismParameter &mechParam, const ByteArray &data, ByteArray &iv, ByteArray &tag)
ByteArray	crypt (int flags, const Key &key, const MechanismParameter &mechParam, const ByteArray &data, ByteArray &iv)
unsigned int	getBufferedDataSize (const ByteArray &iv)
std::vector< ByteArray >	bulk_crypt (const Key &key, const MechanismParameter &mechParam, const std::vector< ByteArray > &data)
ByteArray	sign (int flags, Key &key, const MechanismParameter &mechParam, const ByteArray &data, ByteArray *iv=NULL)
ByteArray	sign (int flags, Key &key, const MechanismParameter &mechParam, const ByteArray &data, ByteArray &iv)
std::vector< ByteArray >	bulk_sign (Key &key, const MechanismParameter &mechParam, const std::vector< ByteArray > &data)
bool	verify (int flags, Key &key, const MechanismParameter &mechParam, ByteArray &data, const ByteArray *signature, ByteArray *iv=NULL)
bool	verify (int flags, Key &key, const MechanismParameter &mechParam, ByteArray &data, const ByteArray &signature, ByteArray *iv=NULL)
bool	verify (int flags, Key &key, const MechanismParameter &mechParam, ByteArray &data, const ByteArray &signature, ByteArray &iv)
bool	verify (int flags, Key &key, const MechanismParameter &mechParam, ByteArray &data, const ByteArray *signature, ByteArray &iv)
ByteArray	rnd_gen (int len, int mech=-1)
ByteArray	hash_compute (int flags, const MechanismParameter &mechParam, const ByteArray *data, const ByteArray *info=NULL, const Key *key=NULL)
ByteArray	hash_compute (int flags, const MechanismParameter &mechParam, const ByteArray &data, const ByteArray &info, const Key &key)
ByteArray	hash_compute (int flags, const MechanismParameter &mechParam, const ByteArray &data, const ByteArray *info, const Key &key)
ByteArray	hash_compute (int flags, const MechanismParameter &mechParam, const ByteArray &data, const ByteArray &info)
ByteArray	hash_compute (int flags, const MechanismParameter &mechParam, const ByteArray *data, const ByteArray &info)
ByteArray	hash_compute (int flags, const MechanismParameter &mechParam, const ByteArray &data)
ByteArray	secret_agree (int flags, const Key &privateKey, const Key &publicKey, const MechanismParameter *mechParam=NULL)
ByteArray	secret_agree (int flags, const Key &privateKey, const Key &publicKey, const MechanismParameter &mechParam)
ByteArray	crypt (int flags, const Key &key, const MechanismParameter &mechParam, const ByteArray &data, ByteArray *iv=NULL, ByteArray *tag=NULL, const ByteArray *tag_in=NULL)
ByteArray	crypt (int flags, const Key &key, const MechanismParameter &mechParam, const ByteArray &data, ByteArray &iv, ByteArray &tag, const ByteArray &tag_in)
ByteArray	crypt (int flags, const Key &key, const MechanismParameter &mechParam, const ByteArray &data, ByteArray &iv, ByteArray &tag)
ByteArray	crypt (int flags, const Key &key, const MechanismParameter &mechParam, const ByteArray &data, ByteArray &iv)
unsigned int	getBufferedDataSize (const ByteArray &iv)
std::vector< ByteArray >	bulk_crypt (const Key &key, const MechanismParameter &mechParam, const std::vector< ByteArray > &data)
ByteArray	sign (int flags, Key &key, const MechanismParameter &mechParam, const ByteArray &data, ByteArray *iv=NULL)
ByteArray	sign (int flags, Key &key, const MechanismParameter &mechParam, const ByteArray &data, ByteArray &iv)
std::vector< ByteArray >	bulk_sign (Key &key, const MechanismParameter &mechParam, const std::vector< ByteArray > &data)
bool	verify (int flags, Key &key, const MechanismParameter &mechParam, ByteArray &data, const ByteArray *signature, ByteArray *iv=NULL)
bool	verify (int flags, Key &key, const MechanismParameter &mechParam, ByteArray &data, const ByteArray &signature, ByteArray *iv=NULL)
bool	verify (int flags, Key &key, const MechanismParameter &mechParam, ByteArray &data, const ByteArray &signature, ByteArray &iv)
bool	verify (int flags, Key &key, const MechanismParameter &mechParam, ByteArray &data, const ByteArray *signature, ByteArray &iv)
ByteArray	rnd_gen (int len, int mech=-1)
ByteArray	hash_compute (int flags, const MechanismParameter &mechParam, const ByteArray *data, const ByteArray *info=NULL, const Key *key=NULL)
ByteArray	hash_compute (int flags, const MechanismParameter &mechParam, const ByteArray &data, const ByteArray &info, const Key &key)
ByteArray	hash_compute (int flags, const MechanismParameter &mechParam, const ByteArray &data, const ByteArray *info, const Key &key)
ByteArray	hash_compute (int flags, const MechanismParameter &mechParam, const ByteArray &data, const ByteArray &info)
ByteArray	hash_compute (int flags, const MechanismParameter &mechParam, const ByteArray *data, const ByteArray &info)
ByteArray	hash_compute (int flags, const MechanismParameter &mechParam, const ByteArray &data)
ByteArray	secret_agree (int flags, const Key &privateKey, const Key &publicKey, const MechanismParameter *mechParam=NULL)
ByteArray	secret_agree (int flags, const Key &privateKey, const Key &publicKey, const MechanismParameter &mechParam)

Detailed Description

Command interface to CXI firmware module. Handles all communication with the CryptoServer.

The following example illustrates the usage of the Cxi class:

// open connection to CryptoServer (command timeout: 20 sec, connection timeout: 5 sec.)
cxi = new Cxi("192.168.4.1", 20000, 5000);
 
// logon to CryptoServer (user: CXI, password: utimaco, keep session alive: yes)
cxi->logon_pass("CXI", "utimaco", true);
 
// logon a second user with smartcard
cxi->logon_sign("CXI", ":cs2:cyb:USB0", NULL, true);
 
// create an AES key
PropertyList keyTemplate;
 
keyTemplate.setAlgo(CXI_KEY_ALGO_AES);
keyTemplate.setSize(256);
keyTemplate.setGroup("test");
keyTemplate.setName("AES test key");
 
Key aesKey = cxi->key_generate(CXI_KEY_FLAG_OVERWRITE, keyTemplate, CXI_MECH_RND_REAL);
 
// encrypt data with AES key
ByteArray data = ByteArray("---secure message---");
ByteArray iv;
MechanismParameter mechParam = MechanismParameter();
mechParam.set(CXI_MECH_MODE_ENCRYPT|CXI_MECH_CHAIN_CBC|CXI_MECH_PAD_PKCS5);
 
ByteArray crypt = cxi->crypt(0, aesKey, mechParam, data, iv);
crypt.xtrace("encrypted data");
iv.xtrace("iv");
 
// create a RSA key
keyTemplate.clear();
keyTemplate.setAlgo(CXI_KEY_ALGO_RSA);
keyTemplate.setSize(2048);
keyTemplate.setGroup("test");
keyTemplate.setName("RSA test key");
Key rsaKey = cxi->key_generate(CXI_KEY_FLAG_OVERWRITE, keyTemplate);
 
// create hash
Hash hash;
hash.init(CXI_MECH_HASH_ALGO_SHA512);
hash.update("We are what we ", 15);
hash.update("were waiting for", 16);
hash.final();
hash.xtrace("hash");
 
// sign data
mechParam = MechanismParameter(CXI_MECH_PAD_PKCS1|CXI_MECH_HASH_ALGO_SHA512);
 
ByteArray sign = cxi->sign(0, rsaKey, mechParam, hash);
sign.xtrace("sign");
 
// verify signature
cxi->verify(0, rsaKey, mechParam, hash, sign);
 
// list keys
KeyList keys = cxi->key_list();
 
//... other commands
 
// close connection
delete cxi;

Constructor & Destructor Documentation

Cxi() [1/5]

Cxi	(	std::vector< std::string >	devices,
		int	timeout,
		int	ctimeout,
		int	fallback_interval,
		cxi::ByteArray *	vendorCert,
		cxi::ByteArray *	operatorCert,
		cxi::ByteArray *	customerCert
	)

Opens a connection to a CryptoServer cluster.

Parameters

devices	list of device specifier of CryptoServer, e.g.: "PCI:0": first PCI board "TCP:288@192.168.1.1": CryptoServer LAN on TCP port 288 "288@192.168.1.1": CryptoServer LAN on TCP port 288 (TCP protocol is default and may be omitted) "192.168.1.1": CryptoServer LAN on TCP port 288 (port 288 is default and may be ommited) "3001@127.0.0.1": CryptoServer Simulator on TCP port 3001
timeout	timeout in milliseconds the API waits for an answer on command execution
ctimeout	timeout the API waits on attempt to connect to a Cryptoserver
fallback_interval	time in seconds the API waits before it tries to reconnect to the primary device (first device in the list) after having switched to another device due to a communication error.
vendorCert	path to the vendor certificate
operatorCert	path to the operator certificate
customerCert	path to the customer certificate

Exceptions

cxi::Exception

if no connection to any device can be established.

Cxi() [2/5]

Cxi	(	const char *	device,
		int	timeout = 60000,
		int	ctimeout = 5000
	)

Opens a connection to the CryptoServer.

Parameters

device	device specifier of CryptoServer, e.g.: "PCI:0": first PCI board "TCP:288@192.168.1.1": CryptoServer LAN on TCP port 288 "288@192.168.1.1": CryptoServer LAN on TCP port 288 (TCP protocol is default and may be omitted) "192.168.1.1": CryptoServer LAN on TCP port 288 (port 288 is default and may be ommited) "3001@127.0.0.1": CryptoServer Simulator on TCP port 3001
timeout	timeout in milliseconds the API waits for an answer on command execution
ctimeout	timeout the API waits on attempt to connect to a Cryptoserver

Exceptions

cxi::Exception

if connection can't be established.

Cxi() [3/5]

Cxi	(	const char **	devices,
		int	ndevs,
		int	timeout = 60000,
		int	ctimeout = 5000,
		int	fallback_interval = 0
	)

Opens a connection to a CryptoServer cluster.

Parameters

devices	array of device specifier of CryptoServer, e.g.: "PCI:0": first PCI board "TCP:288@192.168.1.1": CryptoServer LAN on TCP port 288 "288@192.168.1.1": CryptoServer LAN on TCP port 288 (TCP protocol is default and may be omitted) "192.168.1.1": CryptoServer LAN on TCP port 288 (port 288 is default and may be ommited) "3001@127.0.0.1": CryptoServer Simulator on TCP port 3001
ndevs	number of devices in given array
timeout	timeout in milliseconds the API waits for an answer on command execution
ctimeout	timeout the API waits on attempt to connect to a Cryptoserver
fallback_interval	time in seconds the API waits before it tries to reconnect to the primary device (first device in the list) after having switched to another device due to a communication error.

Exceptions

cxi::Exception

if no connection to any device can be established.

Cxi() [4/5]

Cxi	(	std::vector< std::string >	devices,
		int	timeout = 60000,
		int	ctimeout = 5000,
		int	fallback_interval = 0
	)

Opens a connection to a CryptoServer cluster.

Parameters

devices	list of device specifier of CryptoServer, e.g.: "PCI:0": first PCI board "TCP:288@192.168.1.1": CryptoServer LAN on TCP port 288 "288@192.168.1.1": CryptoServer LAN on TCP port 288 (TCP protocol is default and may be omitted) "192.168.1.1": CryptoServer LAN on TCP port 288 (port 288 is default and may be ommited) "3001@127.0.0.1": CryptoServer Simulator on TCP port 3001
timeout	timeout in milliseconds the API waits for an answer on command execution
ctimeout	timeout the API waits on attempt to connect to a Cryptoserver
fallback_interval	time in seconds the API waits before it tries to reconnect to the primary device (first device in the list) after having switched to another device due to a communication error.

Exceptions

cxi::Exception

if no connection to any device can be established.

Cxi() [5/5]

Cxi

(

Config &

config

)

Opens a connection to a CryptoServer cluster according to the given configuration object.

Parameters

config

Configuration object. 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 CryptoServers (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 cxi::Config. 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

Exceptions

cxi::Exception

if configuration doesn't contain a device entry or if no connection to any device can be established.

~Cxi()

~Cxi ( void  )

virtual

Terminates secure messaging and closes connection to the Cryptoserver

Member Function Documentation

exec()

void exec	(	unsigned int	fc,
		unsigned int	sfc,
		unsigned char *	p_cmd,
		unsigned int	l_cmd,
		unsigned char **	pp_answ,
		unsigned int *	p_l_answ,
		CLUSTER_ERROR *	errlist = NULL,
		unsigned int	err_ct = 0
	)

Sends a generic command to the CryptoServer and receives the answer.

Parameters

fc	Function Code (==Module ID) of the target firmware module
sfc	Sub Function Code of the function to be called
p_cmd	pointer to command to be send
l_cmd	length of command to be send
pp_answ	pointer to answer buffer (memory allocation)
p_l_answ	pointer to length of answer data
errlist	additional list of error codes the cluster should not reply to the API but switch to another device or 'NULL'
err_ct	dimension of error list or zero

Exceptions

cxi::Exception

Note

At first the API tries to execute the command on the current device. In case of a communication error or if the error is member of the additional list of error codes (CLUSTER_ERROR) the API switches to the next device and tries to execute the command on that device. If all devices were tried without success the API gives up, throws an exeption and returns to the caller.

free_answ()

void free_answ

(

unsigned char *&

p_answ

)

Frees answer buffer allocated by a call to Cxi::exec.

Parameters

p_answ

pointer to buffer to be freed

get_version()

int get_version ( void  )

static

Inquires version of CXI API library.

Returns

version, e.g. 0x01010000

get_fw_version()

int get_fw_version

(

void

)

Inquires version of CXI firmware modul

Returns

version, e.g. 0x01020300

Exceptions

cxi::Exception

logon_sign()

void logon_sign	(	const char *	user,
		const char *	key,
		const char *	password = 0,
		bool	keep_alive = false
	)

Authenticates to the CryptoServer and creates an encrypted messaging tunnel to the CryptoServer (secure messaging).

Parameters

user	name (C-string) of user to be logged on
key	key token (C-string) to be used for signature creation: name of key file (opptionally being password encrypted) smartcard specifier: ":<smartcard>:<reader>:<port>" smartcard: "cs2": CryptoServer administration smartcard reader: "cyb": ReinerSCT, modell cyberJack "cp8": Xiring, modell XIMax1MB or Bull, modell CP8 "pcsc": generic PC/SC compatible reader port: "COM<n>": serial port n on a Windows system "/dev/ttyS<n>": serial port n on a Unix system "USB<n>": n-th device in the USB enumeration "<n>": n-th device in the PC/SC enumeration
password	password (C-string) of the key file
keep_alive	keep current session alive and prevent it from expiring after 15 minutes idle time.

Exceptions

cxi::Exception

logon_pass()

void logon_pass	(	const char *	user,
		const char *	password,
		bool	keep_alive = false
	)

Authenticates to the CryptoServer and creates an encrypted messaging tunnel to the CryptoServer (secure messaging).

Parameters

user	name (C-string) of user to be logged on
password	password (C-string)
keep_alive	keep current session alive and prevent it from expiring after 15 minutes idle time.

Exceptions

cxi::Exception

logoff()

void logoff

(

void

)

Terminates secure messaging.

get_auth_state()

int get_auth_state

(

void

)

Inquires the resulting authentication state of the current secure messaging session.
This value is evaluated as the sum of all users currently logged on to the secure messaging session.

Returns

authentciation state, e.g. 0x00000002

Exceptions

cxi::Exception

key_list()

KeyList key_list

(

PropertyList *

keyTemplate = NULL

)

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 property.

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

Parameters

keyTemplate

List of properties that define search criteria for the keys to be listed. Keys that dont match the given criteria will not be listed. The following example illustrates how to list only RSA keys with 2048 bits: Property List := { CXI_PROP_KEY_ALGO := CXI_KEY_ALGO_RSA CXI_PROP_KEY_SIZE := 2048 }

Returns

Key list. The following properties are returned for every key:

• CXI_PROP_KEY_ALGO
• CXI_PROP_KEY_GROUP
• CXI_PROP_KEY_NAME
• CXI_PROP_KEY_SPEC
• CXI_PROP_KEY_SIZE
• CXI_PROP_KEY_TYPE
  Note:
• The key list contains only such keys the user is allowed to access, other keys are 'invisible'. Therefore the CryptoServer checks whether the key group matches with the value of the user attribute "CXI_GROUP" of the currently authenticated user(s).
• Keys without key group property are listed in any case.

Exceptions

cxi::Exception

key_generate()

Key key_generate	(	int	flags,
		const PropertyList &	keyTemplate
	)

Generates new keys or domain parameters according on the given template (property list).
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 in the database but a MBK encrypted key backup blob is returned.

Parameters

flags	XOR combination of: CXI_KEY_FLAG_OVERWRITE : overwrite already existing key CXI_KEY_FLAG_EXTERNAL : don't store the key in the internal database but return a key backup blob. CXI_KEY_FLAG_VOLATILE : don't store the key permanently (lost after restart of CryptoServer)
keyTemplate	Key properties to be set for the new key (see Key Properties). The following properties are mandatory for the key template: CXI_PROP_KEY_ALGO : key algorithm specifier (see Algorithm Specifier) CXI_PROP_KEY_SIZE : 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. CXI_PROP_KEY_NAME : key name (may be omitted in case of external key storage)
mech	XOR combination of: Random mode (see Random Generation Parameter): CXI_MECH_RND_REAL : use hardware (real) random number generator (better, slower) CXI_MECH_RND_PSEUDO : use deterministic (pseudo) random number generator (faster) Key generation mechanism (see Key Generation Parameter): RSA: CXI_MECH_KEYGEN_PROB_PRIME : create 'probable' prime values according to Miller-Rabin's algorithm (default) CXI_MECH_KEYGEN_PROV_PRIME : create 'proven' prime values according to Maurer's algorithm CXI_MECH_KEYGEN_ANSI_PRIME : create prime values according to ANSI specification CXI_MECH_KEYGEN_FIPS186_4_PRIME : create prime numbers according to FIPS-186-4 ECDSA: CXI_MECH_KEYGEN_UNCOMP : public key in uncompressed form (default) CXI_MECH_KEYGEN_COMP : public key in compressed form CXI_MECH_KEYGEN_HYBRID: public key in hybrid form DSA: CXI_MECH_KEYGEN_PROB_PRIME : create 'probable' prime values according to Miller-Rabin's algorithm (default) CXI_MECH_KEYGEN_PROV_PRIME : create 'proven' prime values according to Maurer's algorithm CXI_MECH_DPGEN_DP_FIPS186_4 : create DSA domain parameters conform to FIPS 186-4

Returns

Key Object (either key handle or - in case of external key storage - key backup blob).

See also

Format of Key Blobs

Exceptions

cxi::Exception

FIPS:

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:

const int mechs_num = 2;
int mechs[mechs_num];
mechs[0] = ( CXI_MECH_HASH_ALGO_SHA384 | CXI_MECH_PAD_PKCS1 );
mechs[1] = ( CXI_MECH_HASH_ALGO_SHA512 | CXI_MECH_PAD_PKCS1 );
 
PropertyList keyTemplate;
keyTemplate.setAlgo(CXI_KEY_ALGO_RSA);
keyTemplate.setSize(2048);
keyTemplate.setName("RSA_DEMO_KEY");
keyTemplate.setMechs(mechs, mechs_num);
 
Key rsaKey = cxi->key_generate(CXI_FLAG_KEY_EXTERNAL, keyTemplate);

key_open()

Key key_open	(	int	flags,
		PropertyList &	keyTemplate
	)

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

Parameters

flags	Command flags: CXI_KEY_FLAG_EXTERNAL: return a key blob instead of a key handle.
keyTemplate	Property list, which specifies the key to be opened. The key is identified by the following properties: 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 be set within provided property list (keyTemplate).

Returns

Key Object (either key handle or - in case of external key storage - key backup blob).

See also

Format of Key Blobs

Exceptions

cxi::Exception

Note

On a cluster the desired key is returned if it exists on at least one CryptoServer.

Setting flags to CXI_KEY_FLAG_EXTERNAL implicitly executes Cxi::key_open and Cxi::key_backup in one atomic operation and is therefore recommended to provide seamless fail-over.

key_delete() [1/2]

void key_delete

(

const PropertyList &

keyTemplate

)

Deletes the given key.

Parameters

keyTemplate

property list, which specifies the key to be opened. The key is identified by the following properties: name (mandatory) group (optional) specifier (optional)

Exceptions

cxi::Exception

key_delete() [2/2]

void key_delete

(

Key &

key

)

Deletes the given key.

Parameters

key	key to be deleted

Exceptions

cxi::Exception

key_prop_get()

PropertyList key_prop_get	(	const Key &	key,
		int	properties[],
		int	nprops
	)

Inquires one or more key property values.

Parameters

key	key, whose properties are to be inquired
properties	integer-array of property specifier, see Key Properties
nprops	number of property specifier

Returns

PropertyList containing the desired values.

Exceptions

cxi::Exception

key_prop_set()

Key key_prop_set	(	const Key &	key,
		const PropertyList &	propList
	)

Sets or modifies one or more properties of the given key.

Parameters

key	key whose properties are to be set
propList	list of property values to be set

Returns

Key object

• If a key blob was given, the modified blob is returned
• If a key handle was given, the database record is updated and a key handle is returned

Note:

• Read-only property values (e.g. key type) are not allowed to be set.

  Exceptions

  cxi::Exception

key_set_fips_usage()

Key key_set_fips_usage	(	const Key &	key,
		unsigned int	usage
	)

Sets fips specific usage and padding flag

Parameters

usage

signature calculation/verification w/ specific padding or other operation

Returns

Key object

• If a key blob was given, the modified blob is returned
• If a key handle was given, the database record is updated and a key handle is returned

key_export()

ByteArray key_export	(	int	type,
		Key &	key,
		Key *	exportKey,
		int	mech = -1
	)

Exports the given key and returns a key blob of type 'Simple Blob' (see Format of Key Blobs).

Parameters

type	XOR combination of: Blob type (see Blob Types): CXI_KEY_BLOB_SIMPLE: Generic blob format of the CXI module Key type (see Key Types): DES, AES: CXI_KEY_TYPE_SECRET : Export secret key RSA, ECDSA, DSA: CXI_KEY_TYPE_PUBLIC : Export public key CXI_KEY_TYPE_PRIVATE : Export private key
key	Key to be exported
exportKey	Key Encryption Key to be used to encrypt key. If permitted by the key export property, the key may be exported in plain. The value of exportKey has to be set to 'NULL' in this case
mech	XOR combination of mechanism parameter used to encrypt key (see cxi::MechanismParameter): Chaining mode (see Chaining Modes): DES, AES: CXI_MECH_CHAIN_ECB : Use 'Electronic Codebook' mode (no chaining) CXI_MECH_CHAIN_CBC : Use 'Cipher Block Chaining' mode (default) Padding mode (see Padding Modes): DES, AES: CXI_MECH_PAD_NONE : Don't apply any padding (data length has to be a multiple of algorithms block size) CXI_MECH_PAD_PKCS5 : Apply padding according to PKCS#5 (default) CXI_MECH_PAD_RANDOM : Apply random padding CXI_MECH_PAD_ISO7816 : Apply padding according to ISO 7816 RSA: CXI_MECH_PAD_NONE : Don't apply any padding (data length has to be smaller than length of modulus) CXI_MECH_PAD_PKCS1 : Apply padding according to PKCS#1 v1_5 (block type 2)

Returns

Byte array containing key blob

See also

Format of Key Blobs

Exceptions

cxi::Exception

key_import()

Key key_import	(	int	flags,
		int	type,
		const PropertyList &	keyTemplate,
		const ByteArray &	keyBlob,
		Key *	importKey,
		int	mech = -1
	)

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

Parameters

flags	XOR combination of: CXI_KEY_FLAG_OVERWRITE : overwrite already existing key CXI_KEY_FLAG_EXTERNAL : don't store the key in the internal database but return a key backup blob. CXI_KEY_FLAG_VOLATILE : don't store the key permanently (lost after restart of CryptoServer)
type	Blob type (see Blob Types): CXI_KEY_BLOB_SIMPLE Other blob types are reserved for future use
keyTemplate	Key properties to be set for the new key. The following properties are mandatory for the key template (see Key Properties): CXI_PROP_KEY_NAME : key name (may be omitted in case of external key storage) The following properties have to be absent from the key template: CXI_PROP_KEY_BLEN CXI_PROP_KEY_UNAME CXI_PROP_KEY_XXX_PUBKEY
keyBlob	Key blob to be imported
importKey	Key Encryption Key to be used to encrypt key. The key may be imported in plain. The value of importKey has to be set to 'NULL' in this case
mech	XOR combination of mechanism parameter used to decrypt key (see cxi::MechanismParameter): Chaining mode (see Chaining Modes): DES, AES: CXI_MECH_CHAIN_ECB : Use 'Electronic Codebook' mode (no chaining) CXI_MECH_CHAIN_CBC : Use 'Cipher Block Chaining' mode (default) Padding mode (see Padding Modes): DES, AES: CXI_MECH_PAD_NONE : Don't apply any padding (data length has to be a multiple of algorithms block size) CXI_MECH_PAD_PKCS5 : Apply padding according to PKCS#5 (default) CXI_MECH_PAD_RANDOM : Apply random padding CXI_MECH_PAD_ISO7816 : Apply padding according to ISO 7816 RSA: CXI_MECH_PAD_NONE : Don't apply any padding (data length has to be smaller than length of modulus) CXI_MECH_PAD_PKCS1 : Apply padding according to PKCS#1 v1_5 (block type 2)

Returns

Key Object (either key handle or - in case of external key storage - key backup blob).

See also

Format of Key Blobs

Exceptions

cxi::Exception

key_dsa_xgen()

PropertyList key_dsa_xgen	(	int	psize,
		int	qsize = 160,
		int	mech = -1
	)

Creates the domain parameter (P, Q and G), needed to create a DSA key (see Cxi::key_generate).

Parameters

psize	size in bits of the prime P
qsize	size in bits of the prime Q
mech	XOR combination of: Random mode (see Random Generation Parameter): CXI_MECH_RND_REAL : use hardware (real) random number generator (better, slower) CXI_MECH_RND_PSEUDO : use deterministic (pseudo) random number generator (faster) Key generation mechanism (see Key Generation Parameter): CXI_MECH_DPGEN_DP_FIPS186_4 : create DSA domain parameters conform to FIPS 186-4 Hash: CXI_MECH_HASH_ALGO_SHA1 : SHA1 CXI_MECH_HASH_ALGO_RMD160 : RipeMD 160 (not supported in FIPS mode) CXI_MECH_HASH_ALGO_SHA224 : SHA224 CXI_MECH_HASH_ALGO_SHA256 : SHA256 CXI_MECH_HASH_ALGO_MD5 : MD5 (not supported in FIPS mode) CXI_MECH_HASH_ALGO_SHA384 : SHA384 CXI_MECH_HASH_ALGO_SHA512 : SHA512 CXI_MECH_HASH_ALGO_SHA3_224 : SHA3-224 CXI_MECH_HASH_ALGO_SHA3_256 : SHA3-256 CXI_MECH_HASH_ALGO_SHA3_384 : SHA3-384 CXI_MECH_HASH_ALGO_SHA3_512 : SHA3-512

Exceptions

cxi::Exception

key_dsa_pqgen()

PropertyList key_dsa_pqgen

(

MechanismParameter &

mechParam

)

Creates the domain parameters (P and Q), needed to create a DSA key (see Cxi::key_generate) as described in FIPS 186-4.

Parameters

&mechParam

psize size in bits of the prime P qsize size in bits of the prime Q rnd Random mode (see Random Generation Parameter): CXI_MECH_RND_REAL : use hardware (real) random number generator (better, slower) CXI_MECH_RND_PSEUDO : use deterministic (pseudo) random number generator (faster) hash_algo CXI_MECH_HASH_ALGO_SHA1 : SHA1 CXI_MECH_HASH_ALGO_RMD160 : RipeMD 160 (not supported in FIPS mode) CXI_MECH_HASH_ALGO_SHA224 : SHA224 CXI_MECH_HASH_ALGO_SHA256 : SHA256 CXI_MECH_HASH_ALGO_MD5 : MD5 (not supported in FIPS mode) CXI_MECH_HASH_ALGO_SHA384 : SHA384 CXI_MECH_HASH_ALGO_SHA512 : SHA512 CXI_MECH_HASH_ALGO_SHA3_224 : SHA3-224 CXI_MECH_HASH_ALGO_SHA3_256 : SHA3-256 CXI_MECH_HASH_ALGO_SHA3_384 : SHA3-384 CXI_MECH_HASH_ALGO_SHA3_512 : SHA3-512 l_seed length of optional seed value p_seed optional seed value index unused

Returns

| Property List ("PL") | Mechanism Parameter ("MP") |

• PL: p, q
• MP: | l_seed | p_seed |

key_dsa_ggen()

PropertyList key_dsa_ggen	(	PropertyList &	propList,
		const MechanismParameter &	mechParam
	)

Creates the domain parameter G using the domain parameters (P and Q), needed to create a DSA key (see Cxi::key_generate), as described in FIPS 186-4.

Parameters

&propList

PL: p, q

&mechParam

hash_algo CXI_MECH_HASH_ALGO_SHA1 : SHA1 CXI_MECH_HASH_ALGO_RMD160 : RipeMD 160 (not supported in FIPS mode) CXI_MECH_HASH_ALGO_SHA224 : SHA224 CXI_MECH_HASH_ALGO_SHA256 : SHA256 CXI_MECH_HASH_ALGO_MD5 : MD5 (not supported in FIPS mode) CXI_MECH_HASH_ALGO_SHA384 : SHA384 CXI_MECH_HASH_ALGO_SHA512 : SHA512 CXI_MECH_HASH_ALGO_SHA3_224 : SHA3-224 CXI_MECH_HASH_ALGO_SHA3_256 : SHA3-256 CXI_MECH_HASH_ALGO_SHA3_384 : SHA3-384 CXI_MECH_HASH_ALGO_SHA3_512 : SHA3-512 l_seed length of optional seed value p_seed optional seed value index optional tag to differentiate between possible generation processes. See FIPS 186-4. Must be smaller than 256.

Returns

| Property List ("PL") |

• PL: g

key_backup()

Key key_backup

(

Key &

key

)

Exports a key as key backup blob. The private or secret key parts within the blob
are encrypted with the CryptoServers Master Backup key (MBK).

Parameters

key	Key to be backed up

Returns

Key blob

See also

Format of Key Blobs

Exceptions

cxi::Exception

key_restore()

Key key_restore	(	int	flags,
		Key &	key,
		PropertyList *	keyTemplate = NULL
	)

Restores a key from a key backup blob.

Parameters

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

Returns

Key handle

See also

Format of Key Blobs

Exceptions

cxi::Exception

crypt()

ByteArray crypt	(	int	flags,
		const Key &	key,
		const MechanismParameter &	mechParam,
		const ByteArray &	data,
		ByteArray *	iv = NULL,
		ByteArray *	tag = NULL,
		const ByteArray *	tag_in = NULL
	)

Encrypt or decrypt data.

The following algorithms are supported:

• DES
• AES
• RSA
• ECC (ECIES)

On symmetric algorithms the function may be called multiple times, each time with a different data chunk.
The following specifics have to be regarded on chunked operation:

• The length of intermediate data chunks has to be a multiple of the algoritms block length (DES: 8 bytes, AES: 16 bytes).
• If padding is required the padding mode (see Padding Modes) has to be set only with the last block.
• The authenticated encryption modes AES-GCM and AES-CCM do not return plain data immediately when decrypting. Instead, they wait for the final call to verify the authentication tag and then return the plain data all at once.

Parameters

flags	Command flags: CXI_FLAG_CRYPT_INIT: initialize operation (currently used for AES-CCM mode only). CXI_FLAG_CRYPT_FINAL: last data chunk given, finalize operation (currently used for AES-GCM and AES-CCM modes).
key	Key to be used for encryption or decryption
mechParam	XOR combination of mechanisms (see cxi::MechanismParameter): Crypt mode (see Mode Parameter): CXI_MECH_MODE_ENCRYPT : Encrypt data CXI_MECH_MODE_DECRYPT : Decrypt data Chaining mode (see Chaining Modes): DES, AES: CXI_MECH_CHAIN_ECB : Use 'Electronic Codebook' mode (no chaining) CXI_MECH_CHAIN_CBC : Use 'Cipher Block Chaining' mode CXI_MECH_CHAIN_GCM : Use 'Galois Counter Mode' mode (AES only) CXI_MECH_CHAIN_OFB : Use 'Output Feedback Mode' mode (AES only) CXI_MECH_CHAIN_CCM : Use 'Counter Chaining' mode with CBC-MAC (AES only) CXI_MECH_CHAIN_KEY_WRAP : Use 'AES Key Wrap' mode (AES only; NIST SP800-38F) Padding mode (see Padding Modes): DES, AES: CXI_MECH_PAD_NONE : Don't apply any padding (data length has to be a multiple of algorithms block size) CXI_MECH_PAD_PKCS5 : Apply padding according to PKCS#5 CXI_MECH_PAD_RANDOM : Apply random padding CXI_MECH_PAD_ISO7816 : Apply padding according to ISO 7816 CXI_MECH_PAD_KWP : Apply padding according to NIST SP800-38F RSA: CXI_MECH_PAD_NONE : Don't apply any padding (data length has to be smaller than length of modulus) CXI_MECH_PAD_PKCS1 : Apply padding according to PKCS#1 v1_5 (block type 2) CXI_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: CXI_MECH_HASH_ALGO_XXX : hash algorithm for OAEP
data	Data to be en- or decrypted.
iv	Initialization vector used to chain cipher blocks. The given value will be overwritten on return of the function. In the case of AES-GCM and AES-CCM, iv should be an empty ByteArray for the initial call. If, in AES-GCM mode, an IV has been generated by the CryptoServer, it will be returned in this parameter by the final call. If no initialization vector is given (NULL) a Null-vector is used (symmetric algorithms only) The initialization vector has to be absent for asymmetric algorithms
tag	Authentication Tag (used in AES-GCM and AES-CCM modes) The given value will be overwritten on return of the function. Feed an empty ByteArray on first call of the method. Feed returned tag on subsequent calls.
tag_in	Verification Tag (used in AES-GCM and AES-CCM modes when decrypting) Only needed for the final call. Feed the tag parameter returned by the final encryption call.

Returns

Encrypted or decrypted data.

Exceptions

cxi::Exception

Examples:

Encrypt data in DES CBC mode with PKCS5 padding applied:

ByteArray iv = ByteArray("12345678", 8);
ByteArray data = ...;
ByteArray crypt;
MechanismParameter mechParam = MechanismParameter(CXI_MECH_MODE_ENCRYPT | CXI_MECH_CHAIN_CBC);
 
int rlen = data.length();
int clen = 256;
int ofs = 0;
 
while (rlen > 0)
{
  if (rlen < clen)
  {
    clen = rlen;
    mechParam = MechanismParameter(CXI_MECH_MODE_ENCRYPT | CXI_MECH_CHAIN_CBC | CXI_MECH_PAD_PKCS5);
  }
 
  chunk = data.sub(ofs, clen);
  crypt += cxi->crypt(0, desKey, mechParam, chunk, iv);
 
  ofs += clen;
  rlen -= clen;
}

Encrypt and decrypt data in AES GCM mode:

ByteArray iv;
ByteArray tag;
ByteArray ad = "My Little Secret";
ByteArray data = ...;
ByteArray cipher;
ByteArray plain;
ByteArray veri_tag;
ByteArray internal_iv;
MechanismParameter mechParam;
int tag_bits = 128;
 
int rlen = data.length();
int clen = 32;  // must be a multiple of 16
int ofs = 0;
int flags = 0;
 
while (rlen > 0)
{
  if (clen > rlen) clen = rlen;
  rlen -= clen;
 
  if (ofs == 0)
  {
    // first block (may also be final block)
    mechParam.setGCM(CXI_MECH_MODE_ENCRYPT,
                     NULL, 0,
                     ad.get(), ad.length(),
                     tag_bits);
  }
  else
  {
    // subsequent blocks (including final block)
    mechParam.setGCM(CXI_MECH_MODE_ENCRYPT,
                     NULL, 0,
                     NULL, 0,
                     tag_bits);
  }
 
  flags = (rlen == 0) ? CXI_FLAG_CRYPT_FINAL : 0;
 
  chunk = data.sub(ofs, clen);
  cipher += cxi->crypt(flags, key, mechParam, chunk, iv, tag);
 
  ofs += clen;
}
 
internal_iv = iv;
veri_tag = tag;
 
// decryption
iv.clear();
tag.clear();
ofs = 0;
rlen = cipher.length();
clen = 32;
 
while (rlen > 0)
{
  if (clen > rlen) clen = rlen;
  rlen -= clen;
 
  if (ofs == 0)
  {
    // first block (may also be final block)
    mechParam.setGCM(CXI_MECH_MODE_DECRYPT,
                     internal_iv.get(), internal_iv.length(),
                     ad.get(), ad.length(),
                     tag_bits);
  }
  else
  {
    // subsequent blocks (including final block)
    mechParam.setGCM(CXI_MECH_MODE_DECRYPT,
                     NULL, 0,
                     NULL, 0,
                     tag_bits);
  }
 
  chunk = cipher.sub(ofs, clen);
 
  if (rlen == 0)
  {
    // final call, this verifies the tag and returns the plain data
    plain = cxi->crypt(CXI_FLAG_CRYPT_FINAL, key, mechParam, chunk, iv, tag, veri_tag);
  }
  else
  {
    cxi->crypt(0, key, mechParam, chunk, iv, tag);
  }
 
  ofs += clen;
}

getBufferedDataSize()

unsigned int getBufferedDataSize

(

const ByteArray &

iv

)

Returns the size of the buffered data for GCM and CCM decryption. There, data is not returned immediately, but only with the final crypt() call and is buffered in-between in the IV.

Parameters

iv	IV as returned by the last crypt() call.

bulk_crypt()

std::vector< ByteArray > bulk_crypt	(	const Key &	key,
		const MechanismParameter &	mechParam,
		const std::vector< ByteArray > &	data
	)

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	Key to be used for encryption or decryption
mechParam	XOR combination of mechanisms (see cxi::MechanismParameter): Crypt mode (see Mode Parameter): CXI_MECH_MODE_ENCRYPT : Encrypt data CXI_MECH_MODE_DECRYPT : Decrypt data
data	Array (vector) of data items to be en- or decrypted

Returns

Array (vector) of encrypted or decrypted data items

Exceptions

cxi::Exception

sign()

ByteArray sign	(	int	flags,
		Key &	key,
		const MechanismParameter &	mechParam,
		const ByteArray &	data,
		ByteArray *	iv = NULL
	)

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 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 intermediate digest information that can be used as input ('IV') for the next block.

Parameters

flags	Command flags: CXI_FLAG_HASH_PART: Don't finalize hash calculation but return intermediate digest information to continue a multipart calculation on next function call. CXI_FLAG_HASH_DATA: Given data has to be hashed before getting signed (asymmetric algorithms only). CXI_FLAG_CRYPT_FINAL: Finalize CMAC or GMAC calculation and return the resulting MAC (AES-CMAC/GMAC only).
key	Key to be used to create the signature or calculate the MAC or HMAC. The key usage property has to contain the CXI_KEY_USAGE_SIGN value.
mechParam	XOR combination of mechanism parameter (see cxi::MechanismParameter): Chaining mode (see Chaining Modes): DES: CXI_MECH_CHAIN_CBC : Use 'Cipher Block Chaining' mode. CXI_MECH_CHAIN_CBC_RETAIL: Calculate a CBC Retail MAC according to ISO 9797 (often used in german payment systems). CXI_MECH_CHAIN_CFB_RETAIL: Calculate a CFB Retail MAC (often used in german payment systems). AES: CXI_MECH_CHAIN_CBC : Use 'Cipher Block Chaining' mode. CXI_MECH_CHAIN_CMAC : Calculate a CMAC according to NIST-SP800-38B. CXI_MECH_CHAIN_GCM: Calculate Galois Counter MAC (GMAC). Padding mode (see Padding Modes): DES, AES: CXI_MECH_PAD_NONE : Don't apply any padding (data length has to be a multiple of algorithms block size). CXI_MECH_PAD_PKCS5 : Apply padding according to PKCS#5. CXI_MECH_PAD_RANDOM : Apply random padding. CXI_MECH_PAD_ISO7816 : Apply padding according to ISO 7816. CXI_MECH_PAD_ZERO : Pad with zeros up to block length. RSA: CXI_MECH_PAD_NONE : Don't apply any padding (data length has to be smaller than length of modulus). CXI_MECH_PAD_PKCS1 : Apply padding according to PKCS#1-v1_5 (block type 1). CXI_MECH_PAD_X9_31 : Apply padding according to ANSI X9.31. CXI_MECH_PAD_PSS : Apply padding according to PKCS#1-v2.1 (RSASSA-PSS). Hash algorithm (see Hash Algorithms) HMAC mode: DES, AES: CXI_MECH_MODE_HMAC : Calculate hash based MAC.
data	Hash value to be signed or data to be MAC'ed.
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 vector of zeroized bytes is used. 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, digest information (in case CXI_FLAG_HASH_PART was set in the command flags) or CMAC/GMAC intermediate value (if CXI_FLAG_CRYPT_FINAL was not set).

Exceptions

cxi::Exception

Example:

The following example illustrates how to create and verify a ECDSA signature with locally computed hash:

...
 
// create ECDSA key
PropertyList keyTemplate;
keyTemplate.setAlgo(CXI_KEY_ALGO_ECDSA);
keyTemplate.set(CXI_PROP_KEY_EC_CURVE, Property("NIST-P192"));
keyTemplate.setGroup("MyGroup");
keyTemplate.setName("EC_DEMO_KEY");
 
Key ecKey = cxi->key_generate(CXI_FLAG_KEY_OVERWRITE, keyTemplate, 0);
 
// export public key
Blob keyBlob = cxi->key_export(CXI_KEY_BLOB_SIMPLE|CXI_KEY_TYPE_PUBLIC, ecKey, NULL, 0);
keyBlob.getPublic().xtrace("Public Key");
 
ByteArray data = "Hope!Progress!";
 
// compute hash
Hash hash;
hash.init(CXI_MECH_HASH_ALGO_SHA256);
hash.update(data);
hash.final();
hash.xtrace("hash");
 
// sign hash
MechanismParameter mechParam = MechanismParameter(0);
ByteArray sign = cxi->sign(0, ecKey, mechParam, hash);
sign.xtrace("sign");
 
// verify signature
cxi->verify(0, ecKey, mechParam, hash, sign);
 
...

Example:

The following example illustrates how to create and verify a ECDSA signature over data that is hashed on the CryptoServer:

...
 
// create ECDSA key
PropertyList keyTemplate;
keyTemplate.setAlgo(CXI_KEY_ALGO_ECDSA);
keyTemplate.set(CXI_PROP_KEY_EC_CURVE, Property("NIST-P192"));
keyTemplate.setGroup("MyGroup");
keyTemplate.setName("EC_DEMO_KEY");
 
Key ecKey = cxi->key_generate(CXI_FLAG_KEY_OVERWRITE, keyTemplate, 0);
 
ByteArray data = "Hope!Progress!";
 
// create signature
MechanismParameter mechParam = MechanismParameter(CXI_MECH_HASH_ALGO_SHA256);
ByteArray sign = cxi->sign(CXI_FLAG_HASH_DATA, ecKey, mechParam, data);
sign.xtrace("sign");
 
// verify signature
bool result = cxi->verify(CXI_FLAG_HASH_DATA, ecKey, mechParam, data, sign);
 
if (result == false)
  printf("signature verification failed\n");
 
...

bulk_sign()

std::vector< ByteArray > bulk_sign	(	Key &	key,
		const MechanismParameter &	mechParam,
		const std::vector< ByteArray > &	data
	)

Digitally signs up to 16 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
mechParam	XOR combination of mechanism parameter (see Mechanism Parameter): Padding mode (see Padding Modes) Hash algorithm (see Hash Algorithms) Output format (see Format Parameter) (Note that ECDSA bulk signing does not currently support ASN1 output!)
data	Array (vector) of hash values to be signed

Returns

Array (vector) of signatures

Exceptions

cxi::Exception

verify()

bool verify	(	int	flags,
		Key &	key,
		const MechanismParameter &	mechParam,
		ByteArray &	data,
		const ByteArray *	signature,
		ByteArray *	iv = NULL
	)

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: CXI_FLAG_HASH_PART: don't finalize HMAC calculation but return intermediate HMAC digest information to continue a multipart calculation on next function call. CXI_FLAG_HASH_DATA: given data has to be hashed before comparison (asymmetric algorithms only). CXI_FLAG_CRYPT_FINAL: Finalize CMAC or GMAC calculation and return the resulting MAC (AES-CMAC/GMAC only).
key	Key to be used to verify the signature, MAC or HMAC. The key usage property has to contain the CXI_KEY_USAGE_VERIFY value.
mechParam	XOR combination of mechanism parameter (see cxi::MechanismParameter): Chaining mode (see Chaining Modes): DES: CXI_MECH_CHAIN_CBC : Use 'Cipher Block Chaining' mode. CXI_MECH_CHAIN_CBC_RETAIL: Calculate a CBC Retail MAC according to ISO 9797 (often used in german payment systems). CXI_MECH_CHAIN_CFB_RETAIL: Calculate a CFB Retail MAC (often used in german payment systems). AES: CXI_MECH_CHAIN_CBC : Use 'Cipher Block Chaining' mode. CXI_MECH_CHAIN_CMAC : Calculate a CMAC according to NIST-SP800-38B. CXI_MECH_CHAIN_GCM: Calculate Galois Counter MAC (GMAC). Padding mode (see Padding Modes): DES, AES: CXI_MECH_PAD_NONE : Don't apply any padding (data length has to be a multiple of algorithms block size). CXI_MECH_PAD_PKCS5 : Apply padding according to PKCS#5. CXI_MECH_PAD_RANDOM : Apply random padding. CXI_MECH_PAD_ISO7816 : Apply padding according to ISO 7816. CXI_MECH_PAD_ZERO : Pad with zeros up to block length. RSA: CXI_MECH_PAD_NONE : Don't apply any padding (data length has to be smaller than length of modulus). CXI_MECH_PAD_PKCS1 : Apply padding according to PKCS#1-v1_5 (block type 1). CXI_MECH_PAD_X9_31 : Apply padding according to ANSI X9.31. CXI_MECH_PAD_PSS : Apply padding according to PKCS#1-v2.1 (RSASSA-PSS). Hash algorithm (see Hash Algorithms) HMAC mode: DES, AES: CXI_MECH_MODE_HMAC : Calculate hash based MAC.
data	Reference hash to be compared (asym. algorithms) or data to be MAC'ed for comparison.
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 vector of zeroized bytes 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

Exceptions

cxi::Exception

in case of any other error than verification failure.

rnd_gen()

ByteArray rnd_gen	(	int	len,
		int	mech = -1
	)

Generates random bytes

Parameters

len	Number of random bytes to be generated
mech	Generation mode: CXI_MECH_RND_REAL : use hardware (real) random number generator (better, slower) CXI_MECH_RND_PSEUDO : use deterministic (pseudo) random number generator (faster)

Returns

byte Array with random bytes

Exceptions

cxi::Exception

hash_compute()

ByteArray hash_compute	(	int	flags,
		const MechanismParameter &	mechParam,
		const ByteArray *	data,
		const ByteArray *	info = NULL,
		const Key *	key = NULL
	)

This function computes a hash or hash based MAC (HMAC) over the given data.

Note

In contrast to the Hash class, which calculates the hash locally, the hash computation takes place on the CryptoServer.

Parameters

flags	Command flags: CXI_FLAG_HASH_PART: Don't finalize hash but return hash digest information to be continued on next call (multipart hash calculation).
mechParam	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 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 == CXI_FLAG_HASH_PART).

Exceptions

cxi::Exception

secret_agree()

ByteArray secret_agree	(	int	flags,
		const Key &	privateKey,
		const Key &	publicKey,
		const MechanismParameter *	mechParam = NULL
	)

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: CXI_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 CXI_KEY_USAGE_DERIVE value.
publicKey	Public part of key #2. note This value may also be given in the mechanism parameters.
mechParam	Mechanism Parameters: Mechanism: CXI_MECH_FORMAT_X: return only x-coordinate of secret point (default). 0: return x and y coordinate of secret point. Public Key: X9.42 encoded public part of key #2 (optional, if not 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 CXI_FLAG_ENCRYPT_SECRET was given in the command flags (tag 'SB'). Otherwise the plain secret will be returned (tag 'DA').

Exceptions

cxi::Exception