»Home
»News
»Download
»Documentation
     »oathtool(1)
     »pskctool(1)
     »Liboath API
     »Libpskc Quickstart
     »Libpskc API
     »pam_oath
»Contribute
     »Code
     »Bug tracker
OATH Toolkit
One-time password components

keypackage

keypackage — PSKC keypackage handling.

Functions

const char * pskc_get_device_manufacturer ()
void pskc_set_device_manufacturer ()
const char * pskc_get_device_serialno ()
void pskc_set_device_serialno ()
const char * pskc_get_device_model ()
void pskc_set_device_model ()
const char * pskc_get_device_issueno ()
void pskc_set_device_issueno ()
const char * pskc_get_device_devicebinding ()
void pskc_set_device_devicebinding ()
const struct tm * pskc_get_device_startdate ()
void pskc_set_device_startdate ()
const struct tm * pskc_get_device_expirydate ()
void pskc_set_device_expirydate ()
const char * pskc_get_device_userid ()
void pskc_set_device_userid ()
const char * pskc_get_cryptomodule_id ()
void pskc_set_cryptomodule_id ()
const char * pskc_get_key_id ()
void pskc_set_key_id ()
const char * pskc_get_key_algorithm ()
void pskc_set_key_algorithm ()
const char * pskc_get_key_issuer ()
void pskc_set_key_issuer ()
const char * pskc_get_key_algparm_suite ()
void pskc_set_key_algparm_suite ()
pskc_valueformat pskc_get_key_algparm_chall_encoding ()
void pskc_set_key_algparm_chall_encoding ()
uint32_t pskc_get_key_algparm_chall_min ()
void pskc_set_key_algparm_chall_min ()
uint32_t pskc_get_key_algparm_chall_max ()
void pskc_set_key_algparm_chall_max ()
int pskc_get_key_algparm_chall_checkdigits ()
void pskc_set_key_algparm_chall_checkdigits ()
pskc_valueformat pskc_get_key_algparm_resp_encoding ()
void pskc_set_key_algparm_resp_encoding ()
uint32_t pskc_get_key_algparm_resp_length ()
void pskc_set_key_algparm_resp_length ()
int pskc_get_key_algparm_resp_checkdigits ()
void pskc_set_key_algparm_resp_checkdigits ()
const char * pskc_get_key_profileid ()
void pskc_set_key_profileid ()
const char * pskc_get_key_reference ()
void pskc_set_key_reference ()
const char * pskc_get_key_friendlyname ()
void pskc_set_key_friendlyname ()
const char * pskc_get_key_userid ()
void pskc_set_key_userid ()
const char * pskc_get_key_data_secret ()
int pskc_set_key_data_secret ()
const char * pskc_get_key_data_b64secret ()
int pskc_set_key_data_b64secret ()
uint64_t pskc_get_key_data_counter ()
void pskc_set_key_data_counter ()
uint32_t pskc_get_key_data_time ()
void pskc_set_key_data_time ()
uint32_t pskc_get_key_data_timeinterval ()
void pskc_set_key_data_timeinterval ()
uint32_t pskc_get_key_data_timedrift ()
void pskc_set_key_data_timedrift ()
const struct tm * pskc_get_key_policy_startdate ()
void pskc_set_key_policy_startdate ()
const struct tm * pskc_get_key_policy_expirydate ()
void pskc_set_key_policy_expirydate ()
const char * pskc_get_key_policy_pinkeyid ()
void pskc_set_key_policy_pinkeyid ()
pskc_pinusagemode pskc_get_key_policy_pinusagemode ()
void pskc_set_key_policy_pinusagemode ()
uint32_t pskc_get_key_policy_pinmaxfailedattempts ()
void pskc_set_key_policy_pinmaxfailedattempts ()
uint32_t pskc_get_key_policy_pinminlength ()
void pskc_set_key_policy_pinminlength ()
uint32_t pskc_get_key_policy_pinmaxlength ()
void pskc_set_key_policy_pinmaxlength ()
pskc_valueformat pskc_get_key_policy_pinencoding ()
void pskc_set_key_policy_pinencoding ()
int pskc_get_key_policy_keyusages ()
void pskc_set_key_policy_keyusages ()
uint64_t pskc_get_key_policy_numberoftransactions ()
void pskc_set_key_policy_numberoftransactions ()

Description

The pskc_key_t structure hold data for one key package in a high-level PSKC pskc_t structure. The pskc_get_keypackage() and pskc_add_keypackage() functions can be used to get a pskc_key_t handle, which is always related to one pskc_t structure. This section describes all the functions that are used to access and modify information stored in pskc_key_t PSKC key packages.

Functions

pskc_get_device_manufacturer ()

const char *
pskc_get_device_manufacturer (pskc_key_t *key);

Get the PSKC KeyPackage DeviceInfo Manufacturer value. This element indicates the manufacturer of the device.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

Returns

a constant string (must not be deallocated) holding the content, or NULL if not set.


pskc_set_device_manufacturer ()

void
pskc_set_device_manufacturer (pskc_key_t *key,
                              const char *devmfr);

Set the PSKC KeyPackage DeviceInfo Manufacturer value. This element indicates the manufacturer of the device.

The pointer is stored in container , not a copy of the data, so you must not deallocate the data before another call to this function or the last call to any function using container .

Parameters

key

a pskc_key_t handle from, e.g., pskc_add_keypackage().

 

devmfr

string with device manufacturer name to set.

 

Since 2.2.0


pskc_get_device_serialno ()

const char *
pskc_get_device_serialno (pskc_key_t *key);

Get the PSKC KeyPackage DeviceInfo SerialNo value. This element contains the serial number of the device.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

Returns

a constant string (must not be deallocated) holding the content, or NULL if not set.


pskc_set_device_serialno ()

void
pskc_set_device_serialno (pskc_key_t *key,
                          const char *serialno);

Set the PSKC KeyPackage DeviceInfo SerialNo value. This element indicates the serial number of the device.

The pointer is stored in container , not a copy of the data, so you must not deallocate the data before another call to this function or the last call to any function using container .

Parameters

key

a pskc_key_t handle from, e.g., pskc_add_keypackage().

 

serialno

string with serial number to set.

 

Since 2.2.0


pskc_get_device_model ()

const char *
pskc_get_device_model (pskc_key_t *key);

Get the PSKC KeyPackage DeviceInfo Model value. This element describes the model of the device (e.g., "one-button-HOTP-token-V1").

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

Returns

a constant string (must not be deallocated) holding the content, or NULL if not set.


pskc_set_device_model ()

void
pskc_set_device_model (pskc_key_t *key,
                       const char *model);

Set the PSKC KeyPackage DeviceInfo Model value. This element describes the model of the device (e.g., "one-button-HOTP-token-V1").

The pointer is stored in container , not a copy of the data, so you must not deallocate the data before another call to this function or the last call to any function using container .

Parameters

key

a pskc_key_t handle from, e.g., pskc_add_keypackage().

 

model

a string with model name to set.

 

Since 2.2.0


pskc_get_device_issueno ()

const char *
pskc_get_device_issueno (pskc_key_t *key);

Get the PSKC KeyPackage DeviceInfo IssueNo value. This element contains the issue number in case there are devices with the same serial number so that they can be distinguished by different issue numbers.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

Returns

a constant string (must not be deallocated) holding the content, or NULL if not set.


pskc_set_device_issueno ()

void
pskc_set_device_issueno (pskc_key_t *key,
                         const char *issueno);

Set the PSKC KeyPackage DeviceInfo IssueNo value. This element contains the issue number in case there are devices with the same serial number so that they can be distinguished by different issue numbers.

The pointer is stored in container , not a copy of the data, so you must not deallocate the data before another call to this function or the last call to any function using container .

Parameters

key

a pskc_key_t handle from, e.g., pskc_add_keypackage().

 

issueno

a string with issue number to set.

 

Since 2.2.0


pskc_get_device_devicebinding ()

const char *
pskc_get_device_devicebinding (pskc_key_t *key);

Get the PSKC KeyPackage DeviceInfo DeviceBinding value. This element allows a provisioning server to ensure that the key is going to be loaded into the device for which the key provisioning request was approved. The device is bound to the request using a device identifier, e.g., an International Mobile Equipment Identity (IMEI) for the phone, or an identifier for a class of identifiers, e.g., those for which the keys are protected by a Trusted Platform Module (TPM).

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

Returns

a constant string (must not be deallocated) holding the content, or NULL if not set.


pskc_set_device_devicebinding ()

void
pskc_set_device_devicebinding (pskc_key_t *key,
                               const char *devbind);

Set the PSKC KeyPackage DeviceInfo DeviceBinding value. This element allows a provisioning server to ensure that the key is going to be loaded into the device for which the key provisioning request was approved. The device is bound to the request using a device identifier, e.g., an International Mobile Equipment Identity (IMEI) for the phone, or an identifier for a class of identifiers, e.g., those for which the keys are protected by a Trusted Platform Module (TPM).

The pointer is stored in container , not a copy of the data, so you must not deallocate the data before another call to this function or the last call to any function using container .

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

devbind

a string with device binding to set.

 

Since 2.2.0


pskc_get_device_startdate ()

const struct tm *
pskc_get_device_startdate (pskc_key_t *key);

Get the PSKC KeyPackage DeviceInfo StartDate. This element denote the start date of a device (such as the one on a payment card, used when issue numbers are not printed on cards).

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

Returns

a constant struct (must not be deallocated) holding the content, or NULL if not set.


pskc_set_device_startdate ()

void
pskc_set_device_startdate (pskc_key_t *key,
                           const struct tm *startdate);

Set the PSKC KeyPackage DeviceInfo StartDate. This element denote the start date of a device (such as the one on a payment card, used when issue numbers are not printed on cards).

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

startdate

pointer to a tm struct with device starting date to set.

 

Since 2.2.0


pskc_get_device_expirydate ()

const struct tm *
pskc_get_device_expirydate (pskc_key_t *key);

Get the PSKC KeyPackage DeviceInfo ExpiryDate. This element denote the end date of a device (such as the one on a payment card, used when issue numbers are not printed on cards).

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

Returns

a constant struct (must not be deallocated) holding the content, or NULL if not set.


pskc_set_device_expirydate ()

void
pskc_set_device_expirydate (pskc_key_t *key,
                            const struct tm *expirydate);

Set the PSKC KeyPackage DeviceInfo ExpiryDate. This element denote the end date of a device (such as the one on a payment card, used when issue numbers are not printed on cards).

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

expirydate

pointer to a tm struct with device expiry date to set.

 

Since 2.2.0


pskc_get_device_userid ()

const char *
pskc_get_device_userid (pskc_key_t *key);

Get the PSKC KeyPackage DeviceInfo Userid value. This indicates the user with whom the device is associated.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

Returns

a constant string (must not be deallocated) holding the content, or NULL if not set.


pskc_set_device_userid ()

void
pskc_set_device_userid (pskc_key_t *key,
                        const char *userid);

Set the PSKC KeyPackage DeviceInfo Userid value. This indicates the user with whom the device is associated.

The pointer is stored in container , not a copy of the data, so you must not deallocate the data before another call to this function or the last call to any function using container .

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

userid

a string with user identity to set.

 

Since 2.2.0


pskc_get_cryptomodule_id ()

const char *
pskc_get_cryptomodule_id (pskc_key_t *key);

Get the PSKC KeyPackage CryptoModule Id value. This element carries a unique identifier for the CryptoModule and is implementation specific. As such, it helps to identify a specific CryptoModule to which the key is being or was provisioned.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

Returns

a constant string (must not be deallocated) holding the content, or NULL if not set.


pskc_set_cryptomodule_id ()

void
pskc_set_cryptomodule_id (pskc_key_t *key,
                          const char *cid);

Set the PSKC KeyPackage CryptoModule Id value. This element carries a unique identifier for the CryptoModule and is implementation specific. As such, it helps to identify a specific CryptoModule to which the key is being or was provisioned.

The pointer is stored in container , not a copy of the data, so you must not deallocate the data before another call to this function or the last call to any function using container .

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

cid

the cryptomodule id to set

 

Since 2.2.0


pskc_get_key_id ()

const char *
pskc_get_key_id (pskc_key_t *key);

Get the PSKC KeyPackage Key Id attribute value. It is a syntax error for this attribute to not be available.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

Returns

a constant string (must not be deallocated) holding the content, or NULL if not set.


pskc_set_key_id ()

void
pskc_set_key_id (pskc_key_t *key,
                 const char *keyid);

Set the PSKC KeyPackage Key Id attribute value. It is a syntax error for this attribute to not be available.

The pointer is stored in container , not a copy of the data, so you must not deallocate the data before another call to this function or the last call to any function using container .

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

keyid

the key identity string to set.

 

Since 2.2.0


pskc_get_key_algorithm ()

const char *
pskc_get_key_algorithm (pskc_key_t *key);

Get the PSKC KeyPackage Key Algorithm attribute value. This may be an URN, for example "urn:ietf:params:xml:ns:keyprov:pskc:hotp".

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

Returns

a constant string (must not be deallocated) holding the content, or NULL if not set.


pskc_set_key_algorithm ()

void
pskc_set_key_algorithm (pskc_key_t *key,
                        const char *keyalg);

Set the PSKC KeyPackage Key Algorithm attribute value. This may be an URN, for example "urn:ietf:params:xml:ns:keyprov:pskc:hotp".

The pointer is stored in container , not a copy of the data, so you must not deallocate the data before another call to this function or the last call to any function using container .

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

keyalg

the key algorithm string to set.

 

Since 2.2.0


pskc_get_key_issuer ()

const char *
pskc_get_key_issuer (pskc_key_t *key);

Get the PSKC KeyPackage Key Issuer value.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

Returns

a constant string (must not be deallocated) holding the content, or NULL if not set.


pskc_set_key_issuer ()

void
pskc_set_key_issuer (pskc_key_t *key,
                     const char *keyissuer);

Set the PSKC KeyPackage Key Issuer value.

The pointer is stored in container , not a copy of the data, so you must not deallocate the data before another call to this function or the last call to any function using container .

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

keyissuer

a key issuer string to set.

 

Since 2.2.0


pskc_get_key_algparm_suite ()

const char *
pskc_get_key_algparm_suite (pskc_key_t *key);

Get the PSKC KeyPackage Key AlgorithmParameters Suite value.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

Returns

a constant string (must not be deallocated) holding the content, or NULL if not set.


pskc_set_key_algparm_suite ()

void
pskc_set_key_algparm_suite (pskc_key_t *key,
                            const char *keyalgparmsuite);

Set the PSKC KeyPackage Key AlgorithmParameters Suite value.

The pointer is stored in container , not a copy of the data, so you must not deallocate the data before another call to this function or the last call to any function using container .

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

keyalgparmsuite

the key algorithm parameter suite string to set.

 

Since 2.2.0


pskc_get_key_algparm_chall_encoding ()

pskc_valueformat
pskc_get_key_algparm_chall_encoding (pskc_key_t *key,
                                     int *present);

Get the PSKC KeyPackage Key AlgorithmParameters ChallengeFormat Encoding value. This attribute defines the encoding of the challenge accepted by the device.

If present is non-NULL, it will be 0 if the field is not present or 1 if it was present.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

present

output variable indicating whether data was provided or not.

 

Returns

an pskc_valueformat value


pskc_set_key_algparm_chall_encoding ()

void
pskc_set_key_algparm_chall_encoding (pskc_key_t *key,
                                     pskc_valueformat vf);

Set the PSKC KeyPackage Key AlgorithmParameters ChallengeFormat Encoding value. This attribute defines the encoding of the challenge accepted by the device.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

vf

the pskc_valueformat encoding type to set.

 

Since 2.2.0


pskc_get_key_algparm_chall_min ()

uint32_t
pskc_get_key_algparm_chall_min (pskc_key_t *key,
                                int *present);

Get the PSKC KeyPackage Key AlgorithmParameters ChallengeFormat Min value. This attribute defines the minimum size of the challenge accepted by the device for CR mode and MUST be included. If the 'Encoding' attribute is set to 'DECIMAL', 'HEXADECIMAL', or 'ALPHANUMERIC', this value indicates the minimum number of digits/characters. If the 'Encoding' attribute is set to 'BASE64' or 'BINARY', this value indicates the minimum number of bytes of the unencoded value.

If present is non-NULL, it will be 0 if the field is not present or 1 if it was present.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

present

output variable indicating whether data was provided or not.

 

Returns

an integer holding the content.


pskc_set_key_algparm_chall_min ()

void
pskc_set_key_algparm_chall_min (pskc_key_t *key,
                                uint32_t challmin);

Set the PSKC KeyPackage Key AlgorithmParameters ChallengeFormat Min value. This attribute defines the minimum size of the challenge accepted by the device for CR mode and MUST be included. If the 'Encoding' attribute is set to 'DECIMAL', 'HEXADECIMAL', or 'ALPHANUMERIC', this value indicates the minimum number of digits/characters. If the 'Encoding' attribute is set to 'BASE64' or 'BINARY', this value indicates the minimum number of bytes of the unencoded value.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

challmin

the minimum challenge length to set.

 

Since 2.2.0


pskc_get_key_algparm_chall_max ()

uint32_t
pskc_get_key_algparm_chall_max (pskc_key_t *key,
                                int *present);

Get the PSKC KeyPackage Key AlgorithmParameters ChallengeFormat Max value. This attribute defines the maximum size of the challenge accepted by the device for CR mode and MUST be included. If the 'Encoding' attribute is set to 'DECIMAL', 'HEXADECIMAL', or 'ALPHANUMERIC', this value indicates the maximum number of digits/characters. If the 'Encoding' attribute is set to 'BASE64' or 'BINARY', this value indicates the maximum number of bytes of the unencoded value.

If present is non-NULL, it will be 0 if the field is not present or 1 if it was present.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

present

output variable indicating whether data was provided or not.

 

Returns

an integer holding the content.


pskc_set_key_algparm_chall_max ()

void
pskc_set_key_algparm_chall_max (pskc_key_t *key,
                                uint32_t challmax);

Set the PSKC KeyPackage Key AlgorithmParameters ChallengeFormat Max value. This attribute defines the maximum size of the challenge accepted by the device for CR mode and MUST be included. If the 'Encoding' attribute is set to 'DECIMAL', 'HEXADECIMAL', or 'ALPHANUMERIC', this value indicates the maximum number of digits/characters. If the 'Encoding' attribute is set to 'BASE64' or 'BINARY', this value indicates the maximum number of bytes of the unencoded value.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

challmax

the maximum challenge length to set.

 

Since 2.2.0


pskc_get_key_algparm_chall_checkdigits ()

int
pskc_get_key_algparm_chall_checkdigits
                               (pskc_key_t *key,
                                int *present);

Get the PSKC KeyPackage Key AlgorithmParameters ChallengeFormat CheckDigits value. This attribute indicates whether a device needs to check the appended Luhn check digit, as defined in [ISOIEC7812], contained in a challenge. This is only valid if the 'Encoding' attribute is set to 'DECIMAL'. A value of TRUE indicates that the device will check the appended Luhn check digit in a provided challenge. A value of FALSE indicates that the device will not check the appended Luhn check digit in the challenge.

If present is non-NULL, it will be 0 if the field is not present or 1 if it was present.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

present

output variable indicating whether data was provided or not.

 

Returns

1 to indicate a CheckDigits value of true, or 0 to indicate false.


pskc_set_key_algparm_chall_checkdigits ()

void
pskc_set_key_algparm_chall_checkdigits
                               (pskc_key_t *key,
                                int checkdigit);

Set the PSKC KeyPackage Key AlgorithmParameters ChallengeFormat CheckDigits value. This attribute indicates whether a device needs to check the appended Luhn check digit, as defined in [ISOIEC7812], contained in a challenge. This is only valid if the 'Encoding' attribute is set to 'DECIMAL'. A value of TRUE indicates that the device will check the appended Luhn check digit in a provided challenge. A value of FALSE indicates that the device will not check the appended Luhn check digit in the challenge.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

checkdigit

non-zero to indicate setting true CheckDigit, 0 otherwise.

 

Since 2.2.0


pskc_get_key_algparm_resp_encoding ()

pskc_valueformat
pskc_get_key_algparm_resp_encoding (pskc_key_t *key,
                                    int *present);

Get the PSKC KeyPackage Key AlgorithmParameters ResponseFormat Encoding value. This attribute defines the encoding of the response generated by the device, it MUST be included.

If present is non-NULL, it will be 0 if the field is not present or 1 if it was present.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

present

output variable indicating whether data was provided or not.

 

Returns

an pskc_valueformat value


pskc_set_key_algparm_resp_encoding ()

void
pskc_set_key_algparm_resp_encoding (pskc_key_t *key,
                                    pskc_valueformat vf);

Set the PSKC KeyPackage Key AlgorithmParameters ResponseFormat Encoding value. This attribute defines the encoding of the response generated by the device, it MUST be included.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

vf

the pskc_valueformat encoding type to set.

 

Since 2.2.0


pskc_get_key_algparm_resp_length ()

uint32_t
pskc_get_key_algparm_resp_length (pskc_key_t *key,
                                  int *present);

Get the PSKC KeyPackage Key AlgorithmParameters ResponseFormat Length value. This attribute defines the length of the response generated by the device and MUST be included. If the 'Encoding' attribute is set to 'DECIMAL', 'HEXADECIMAL', or ALPHANUMERIC, this value indicates the number of digits/characters. If the 'Encoding' attribute is set to 'BASE64' or 'BINARY', this value indicates the number of bytes of the unencoded value.

If present is non-NULL, it will be 0 if the field is not present or 1 if it was present.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

present

output variable indicating whether data was provided or not.

 

Returns

an integer holding the content.


pskc_set_key_algparm_resp_length ()

void
pskc_set_key_algparm_resp_length (pskc_key_t *key,
                                  uint32_t length);

Set the PSKC KeyPackage Key AlgorithmParameters ResponseFormat Length value. This attribute defines the length of the response generated by the device and MUST be included. If the 'Encoding' attribute is set to 'DECIMAL', 'HEXADECIMAL', or ALPHANUMERIC, this value indicates the number of digits/characters. If the 'Encoding' attribute is set to 'BASE64' or 'BINARY', this value indicates the number of bytes of the unencoded value.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

length

length of response to set.

 

Since 2.2.0


pskc_get_key_algparm_resp_checkdigits ()

int
pskc_get_key_algparm_resp_checkdigits (pskc_key_t *key,
                                       int *present);

Get the PSKC KeyPackage Key AlgorithmParameters ResponseFormat CheckDigits value. This attribute indicates whether the device needs to append a Luhn check digit, as defined in [ISOIEC7812], to the response. This is only valid if the 'Encoding' attribute is set to 'DECIMAL'. If the value is TRUE, then the device will append a Luhn check digit to the response. If the value is FALSE, then the device will not append a Luhn check digit to the response.

If present is non-NULL, it will be 0 if the field is not present or 1 if it was present.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

present

output variable indicating whether data was provided or not.

 

Returns

1 to indicate a CheckDigits value of true, or 0 to indicate false.


pskc_set_key_algparm_resp_checkdigits ()

void
pskc_set_key_algparm_resp_checkdigits (pskc_key_t *key,
                                       int checkdigit);

Set the PSKC KeyPackage Key AlgorithmParameters ResponseFormat CheckDigits value. This attribute indicates whether the device needs to append a Luhn check digit, as defined in [ISOIEC7812], to the response. This is only valid if the 'Encoding' attribute is set to 'DECIMAL'. If the value is TRUE, then the device will append a Luhn check digit to the response. If the value is FALSE, then the device will not append a Luhn check digit to the response.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

checkdigit

non-zero to indicate setting true CheckDigit, 0 otherwise.

 

Since 2.2.0


pskc_get_key_profileid ()

const char *
pskc_get_key_profileid (pskc_key_t *key);

Get the PSKC KeyPackage Key KeyProfileId value.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

Returns

a constant string (must not be deallocated) holding the content, or NULL if not set.


pskc_set_key_profileid ()

void
pskc_set_key_profileid (pskc_key_t *key,
                        const char *profileid);

Set the PSKC KeyPackage Key KeyProfileId value.

The pointer is stored in container , not a copy of the data, so you must not deallocate the data before another call to this function or the last call to any function using container .

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

profileid

pointer to profileid string to set.

 

Since 2.2.0


pskc_get_key_reference ()

const char *
pskc_get_key_reference (pskc_key_t *key);

Get the PSKC KeyPackage Key KeyReference value.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

Returns

a constant string (must not be deallocated) holding the content, or NULL if not set.


pskc_set_key_reference ()

void
pskc_set_key_reference (pskc_key_t *key,
                        const char *keyref);

Set the PSKC KeyPackage Key KeyReference value.

The pointer is stored in container , not a copy of the data, so you must not deallocate the data before another call to this function or the last call to any function using container .

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

keyref

pointer to key reference string to set.

 

Since 2.2.0


pskc_get_key_friendlyname ()

const char *
pskc_get_key_friendlyname (pskc_key_t *key);

Get the PSKC KeyPackage Key Friendlyname value.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

Returns

a constant string (must not be deallocated) holding the content, or NULL if not set.


pskc_set_key_friendlyname ()

void
pskc_set_key_friendlyname (pskc_key_t *key,
                           const char *fname);

Set the PSKC KeyPackage Key Friendlyname value.

The pointer is stored in container , not a copy of the data, so you must not deallocate the data before another call to this function or the last call to any function using container .

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

fname

pointer to friendly name string to set.

 

Since 2.2.0


pskc_get_key_userid ()

const char *
pskc_get_key_userid (pskc_key_t *key);

Get the PSKC KeyPackage Key Userid value.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

Returns

a constant string (must not be deallocated) holding the content, or NULL if not set.


pskc_set_key_userid ()

void
pskc_set_key_userid (pskc_key_t *key,
                     const char *keyuserid);

Set the PSKC KeyPackage Key Userid value.

The pointer is stored in container , not a copy of the data, so you must not deallocate the data before another call to this function or the last call to any function using container .

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

keyuserid

pointer to key userid string to set.

 

Since 2.2.0


pskc_get_key_data_secret ()

const char *
pskc_get_key_data_secret (pskc_key_t *key,
                          size_t *len);

Get the PSKC KeyPackage Key Data Secret value. If len is not set, the caller can only use the returned value for comparison against NULL to check whether the field is present or not.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

len

pointer to output variable with length of returned data.

 

Returns

a constant string (must not be deallocated) holding the content of length *len , or NULL if not set.


pskc_set_key_data_secret ()

int
pskc_set_key_data_secret (pskc_key_t *key,
                          const char *data,
                          size_t len);

Set the PSKC KeyPackage Key Data Secret value. The data data is copied into the key handle, so you may modify or deallocate the data pointer after calling this function. The data is base64 encoded by this function. On errors, the old secret is not modified.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

data

the byte array with the key to set, of len length.

 

len

length of data byte array.

 

Returns

PSKC_BASE64_ERROR on base64 encoding errors, PSKC_MALLOC_ERROR on memory allocation errors, or PSKC_OK on success.

Since 2.2.0


pskc_get_key_data_b64secret ()

const char *
pskc_get_key_data_b64secret (pskc_key_t *key);

Get the PSKC KeyPackage Key Data Secret value in base64 as a zero-terminated string.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

Returns

a constant string (must not be deallocated) holding the content of length *len , or NULL if not set.


pskc_set_key_data_b64secret ()

int
pskc_set_key_data_b64secret (pskc_key_t *key,
                             const char *b64secret);

Set the PSKC KeyPackage Key Data Secret value in base64 as a zero-terminated string. The b64secret data is copied into the key handle, so you may modify or deallocate the b64secret pointer after calling this function. The data is base64 decoded by this function to verify data validity. On errors, the old secret is not modified.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

b64secret

the base64 encoded secret to set.

 

Returns

PSKC_BASE64_ERROR on base64 decoding errors, PSKC_MALLOC_ERROR on memory allocation errors, or PSKC_OK on success.

Since 2.2.0


pskc_get_key_data_counter ()

uint64_t
pskc_get_key_data_counter (pskc_key_t *key,
                           int *present);

Get the PSKC KeyPackage Key Data Counter value. This element contains the event counter for event-based OTP algorithms.

If present is non-NULL, it will be 0 if the Counter field is not present or 1 if it was present.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

present

output variable indicating whether data was provided or not.

 

Returns

an integer holding the content.


pskc_set_key_data_counter ()

void
pskc_set_key_data_counter (pskc_key_t *key,
                           uint64_t counter);

Set the PSKC KeyPackage Key Data Counter value. This element contains the event counter for event-based OTP algorithms.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

counter

counter value to set.

 

Since 2.2.0


pskc_get_key_data_time ()

uint32_t
pskc_get_key_data_time (pskc_key_t *key,
                        int *present);

Get the PSKC KeyPackage Key Data Time value. This element contains the time for time-based OTP algorithms. (If time intervals are used, this element carries the number of time intervals passed from a specific start point, normally it is algorithm dependent).

If present is non-NULL, it will be 0 if the field is not present or 1 if it was present.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

present

output variable indicating whether data was provided or not.

 

Returns

an integer holding the content.


pskc_set_key_data_time ()

void
pskc_set_key_data_time (pskc_key_t *key,
                        uint32_t datatime);

Set the PSKC KeyPackage Key Data Time value. This element contains the time for time-based OTP algorithms. (If time intervals are used, this element carries the number of time intervals passed from a specific start point, normally it is algorithm dependent).

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

datatime

the data time value to set.

 

Since 2.2.0


pskc_get_key_data_timeinterval ()

uint32_t
pskc_get_key_data_timeinterval (pskc_key_t *key,
                                int *present);

Get the PSKC KeyPackage Key Data TimeInterval value. This element carries the time interval value for time-based OTP algorithms in seconds (a typical value for this would be 30, indicating a time interval of 30 seconds).

If present is non-NULL, it will be 0 if the field is not present or 1 if it was present.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

present

output variable indicating whether data was provided or not.

 

Returns

an integer holding the content.


pskc_set_key_data_timeinterval ()

void
pskc_set_key_data_timeinterval (pskc_key_t *key,
                                uint32_t timeinterval);

Set the PSKC KeyPackage Key Data TimeInterval value. This element carries the time interval value for time-based OTP algorithms in seconds (a typical value for this would be 30, indicating a time interval of 30 seconds).

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

timeinterval

time interval value to set.

 

Since 2.2.0


pskc_get_key_data_timedrift ()

uint32_t
pskc_get_key_data_timedrift (pskc_key_t *key,
                             int *present);

Get the PSKC KeyPackage Key Data TimeDrift value. This element contains the device clock drift value for time-based OTP algorithms. The integer value (positive or negative drift) that indicates the number of time intervals that a validation server has established the device clock drifted after the last successful authentication. So, for example, if the last successful authentication established a device time value of 8 intervals from a specific start date but the validation server determines the time value at 9 intervals, the server SHOULD record the drift as -1.

If present is non-NULL, it will be 0 if the field is not present or 1 if it was present.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

present

output variable indicating whether data was provided or not.

 

Returns

an integer holding the content.


pskc_set_key_data_timedrift ()

void
pskc_set_key_data_timedrift (pskc_key_t *key,
                             uint32_t timedrift);

Set the PSKC KeyPackage Key Data TimeDrift value. This element contains the device clock drift value for time-based OTP algorithms. The integer value (positive or negative drift) that indicates the number of time intervals that a validation server has established the device clock drifted after the last successful authentication. So, for example, if the last successful authentication established a device time value of 8 intervals from a specific start date but the validation server determines the time value at 9 intervals, the server SHOULD record the drift as -1.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

timedrift

the time drift value to set.

 

Since 2.2.0


pskc_get_key_policy_startdate ()

const struct tm *
pskc_get_key_policy_startdate (pskc_key_t *key);

Get the PSKC KeyPackage Key Policy StartDate. This element denote the start of the validity period of a key.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

Returns

a constant struct (must not be deallocated) holding the content, or NULL if not set.


pskc_set_key_policy_startdate ()

void
pskc_set_key_policy_startdate (pskc_key_t *key,
                               const struct tm *startdate);

Set the PSKC KeyPackage Key Policy StartDate. This element denote the start of the validity period of a key.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

startdate

pointer to a tm struct with key policy starting date to set.

 

Since 2.2.0


pskc_get_key_policy_expirydate ()

const struct tm *
pskc_get_key_policy_expirydate (pskc_key_t *key);

Get the PSKC KeyPackage Key Policy ExpiryDate. This element denote the expiry of the validity period of a key.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

Returns

a constant struct (must not be deallocated) holding the content, or NULL if not set.


pskc_set_key_policy_expirydate ()

void
pskc_set_key_policy_expirydate (pskc_key_t *key,
                                const struct tm *expirydate);

Set the PSKC KeyPackage Key Policy ExpiryDate. This element denote the expiry of the validity period of a key.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

expirydate

pointer to a tm struct with key policy expiry date to set.

 

Since 2.2.0


pskc_get_key_policy_pinkeyid ()

const char *
pskc_get_key_policy_pinkeyid (pskc_key_t *key);

Get the PSKC KeyPackage Key Policy PINPolicy PINKeyId value. This attribute carries the unique 'Id' attribute vale of the "Key" element held within this "KeyContainer" that contains the value of the PIN that protects the key.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

Returns

a constant string (must not be deallocated) holding the content, or NULL if not set.


pskc_set_key_policy_pinkeyid ()

void
pskc_set_key_policy_pinkeyid (pskc_key_t *key,
                              const char *pinkeyid);

Set the PSKC KeyPackage Key Policy PINPolicy PINKeyId value. This attribute carries the unique 'Id' attribute vale of the "Key" element held within this "KeyContainer" that contains the value of the PIN that protects the key.

The pointer is stored in container , not a copy of the data, so you must not deallocate the data before another call to this function or the last call to any function using container .

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

pinkeyid

pin key id value to set.

 

Since 2.2.0


pskc_get_key_policy_pinusagemode ()

pskc_pinusagemode
pskc_get_key_policy_pinusagemode (pskc_key_t *key,
                                  int *present);

Get the PSKC KeyPackage Key Policy PINPolicy PINUsageMode value. This mandatory attribute indicates the way the PIN is used during the usage of the key.

If present is non-NULL, it will be 0 if the field is not present or 1 if it was present.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

present

output variable indicating whether data was provided or not.

 

Returns

an pskc_pinusagemode value


pskc_set_key_policy_pinusagemode ()

void
pskc_set_key_policy_pinusagemode (pskc_key_t *key,
                                  pskc_pinusagemode pinusagemode);

Set the PSKC KeyPackage Key Policy PINPolicy PINUsageMode value. This mandatory attribute indicates the way the PIN is used during the usage of the key.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

pinusagemode

the pskc_pinusagemode value to set

 

Since 2.2.0


pskc_get_key_policy_pinmaxfailedattempts ()

uint32_t
pskc_get_key_policy_pinmaxfailedattempts
                               (pskc_key_t *key,
                                int *present);

Get the PSKC KeyPackage Key Policy PINPolicy MaxFailedAttempts value. This attribute indicates the maximum number of times the PIN may be entered wrongly before it MUST NOT be possible to use the key anymore (typical reasonable values are in the positive integer range of at least 2 and no more than 10).

If present is non-NULL, it will be 0 if the field is not present or 1 if it was present.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

present

output variable indicating whether data was provided or not.

 

Returns

an integer holding the content.


pskc_set_key_policy_pinmaxfailedattempts ()

void
pskc_set_key_policy_pinmaxfailedattempts
                               (pskc_key_t *key,
                                uint32_t attempts);

Set the PSKC KeyPackage Key Policy PINPolicy MaxFailedAttempts value. This attribute indicates the maximum number of times the PIN may be entered wrongly before it MUST NOT be possible to use the key anymore (typical reasonable values are in the positive integer range of at least 2 and no more than 10).

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

attempts

number of attempts to set.

 

Since 2.2.0


pskc_get_key_policy_pinminlength ()

uint32_t
pskc_get_key_policy_pinminlength (pskc_key_t *key,
                                  int *present);

Get the PSKC KeyPackage Key Policy PINPolicy MinLength value. This attribute indicates the minimum length of a PIN that can be set to protect the associated key. It MUST NOT be possible to set a PIN shorter than this value. If the 'PINFormat' attribute is set to 'DECIMAL', 'HEXADECIMAL', or 'ALPHANUMERIC', this value indicates the number of digits/ characters. If the 'PINFormat' attribute is set to 'BASE64' or 'BINARY', this value indicates the number of bytes of the unencoded value.

If present is non-NULL, it will be 0 if the field is not present or 1 if it was present.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

present

output variable indicating whether data was provided or not.

 

Returns

an integer holding the content.


pskc_set_key_policy_pinminlength ()

void
pskc_set_key_policy_pinminlength (pskc_key_t *key,
                                  uint32_t minlength);

Set the PSKC KeyPackage Key Policy PINPolicy MinLength value. This attribute indicates the minimum length of a PIN that can be set to protect the associated key. It MUST NOT be possible to set a PIN shorter than this value. If the 'PINFormat' attribute is set to 'DECIMAL', 'HEXADECIMAL', or 'ALPHANUMERIC', this value indicates the number of digits/ characters. If the 'PINFormat' attribute is set to 'BASE64' or 'BINARY', this value indicates the number of bytes of the unencoded value.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

minlength

the length to set.

 

Since 2.2.0


pskc_get_key_policy_pinmaxlength ()

uint32_t
pskc_get_key_policy_pinmaxlength (pskc_key_t *key,
                                  int *present);

Get the PSKC KeyPackage Key Policy PINPolicy MaxLength value. This attribute indicates the maximum length of a PIN that can be set to protect this key. It MUST NOT be possible to set a PIN longer than this value. If the 'PINFormat' attribute is set to 'DECIMAL', 'HEXADECIMAL', or 'ALPHANUMERIC', this value indicates the number of digits/ characters. If the 'PINFormat' attribute is set to 'BASE64' or 'BINARY', this value indicates the number of bytes of the unencoded value.

If present is non-NULL, it will be 0 if the field is not present or 1 if it was present.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

present

output variable indicating whether data was provided or not.

 

Returns

an integer holding the content.


pskc_set_key_policy_pinmaxlength ()

void
pskc_set_key_policy_pinmaxlength (pskc_key_t *key,
                                  uint32_t maxlength);

Set the PSKC KeyPackage Key Policy PINPolicy MaxLength value. This attribute indicates the maximum length of a PIN that can be set to protect this key. It MUST NOT be possible to set a PIN longer than this value. If the 'PINFormat' attribute is set to 'DECIMAL', 'HEXADECIMAL', or 'ALPHANUMERIC', this value indicates the number of digits/ characters. If the 'PINFormat' attribute is set to 'BASE64' or 'BINARY', this value indicates the number of bytes of the unencoded value.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

maxlength

the length to set.

 

Since 2.2.0


pskc_get_key_policy_pinencoding ()

pskc_valueformat
pskc_get_key_policy_pinencoding (pskc_key_t *key,
                                 int *present);

Get the PSKC KeyPackage Key Policy PINPolicy PINEncoding value. This attribute indicates the encoding of the PIN and MUST be one of the pskc_valueformat values.

If present is non-NULL, it will be 0 if the field is not present or 1 if it was present.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

present

output variable indicating whether data was provided or not.

 

Returns

an pskc_valueformat value


pskc_set_key_policy_pinencoding ()

void
pskc_set_key_policy_pinencoding (pskc_key_t *key,
                                 pskc_valueformat pinencoding);

Set the PSKC KeyPackage Key Policy PINPolicy PINEncoding value. This attribute indicates the encoding of the PIN and MUST be one of the pskc_valueformat values.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

pinencoding

the pskc_valueformat encoding to set.

 

Since 2.2.0


pskc_get_key_policy_keyusages ()

int
pskc_get_key_policy_keyusages (pskc_key_t *key,
                               int *present);

Get the PSKC KeyPackage Key Policy KeyUsage values. The element puts constraints on the intended usage of the key. The recipient of the PSKC document MUST enforce the key usage.

If present is non-NULL, it will be 0 if the field is not present or 1 if it was present.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

present

output variable indicating whether data was provided or not.

 

Returns

an integer holding a set of pskc_keyusage values ORed together.


pskc_set_key_policy_keyusages ()

void
pskc_set_key_policy_keyusages (pskc_key_t *key,
                               int keyusages);

Set the PSKC KeyPackage Key Policy KeyUsage values. The element puts constraints on the intended usage of the key. The recipient of the PSKC document MUST enforce the key usage.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

keyusages

integer with pskc_keyusage values ORed together.

 

Since 2.2.0


pskc_get_key_policy_numberoftransactions ()

uint64_t
pskc_get_key_policy_numberoftransactions
                               (pskc_key_t *key,
                                int *present);

Get the PSKC KeyPackage Key Policy NumberOfTransactions value. The value in this element indicates the maximum number of times a key carried within the PSKC document can be used by an application after having received it. When this element is omitted, there is no restriction regarding the number of times a key can be used.

Note that while the PSKC specification uses the XML data type "nonNegativeInteger" for this variable, this implementation restricts the size of the value to 64-bit integers.

If present is non-NULL, it will be 0 if the Counter field is not present or 1 if it was present.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

present

output variable indicating whether data was provided or not.

 

Returns

an integer holding the content.


pskc_set_key_policy_numberoftransactions ()

void
pskc_set_key_policy_numberoftransactions
                               (pskc_key_t *key,
                                uint64_t uses);

Set the PSKC KeyPackage Key Policy NumberOfTransactions value. The value in this element indicates the maximum number of times a key carried within the PSKC document can be used by an application after having received it. When this element is omitted, there is no restriction regarding the number of times a key can be used.

Note that while the PSKC specification uses the XML data type "nonNegativeInteger" for this variable, this implementation restricts the size of the value to 64-bit integers.

Parameters

key

a pskc_key_t handle, from pskc_get_keypackage().

 

uses

the number of transactions to set.

 

Since 2.2.0

Types and Values