keypackage: PSKC Library (libpskc) Manual

## 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