## Utilities

Utilities — PKCS#11 utilities

## Functions

const char * | p11_kit_strerror ()
const char * | p11_kit_message ()
char * | p11_kit_space_strdup ()
size_t | p11_kit_space_strlen ()
void | p11_kit_be_quiet ()
void | p11_kit_be_loud ()

## Description

Utility functions for working with PKCS#11.

## Functions

### p11_kit_strerror ()

    const char *
    p11_kit_strerror (CK_RV rv);

Get a message for a PKCS#11 return value or error code. Do not pass CKR_OK or other such non errors to this function.

#### Parameters

rv | The code to get a message for. |

#### Returns

The user readable and localized message.

### p11_kit_message ()

    const char *
    p11_kit_message (void);

Gets the failure message for a recently called p11-kit function, which returned a failure code on this thread. Not all functions set this message. Each function that does so, will note it in its documentation.

If the most recent p11-kit function did not fail, then this will return NULL. The string is owned by the p11-kit library and is only valid on the same thread that the failed function executed on.

#### Returns

The last failure message, or `NULL`.

### p11_kit_space_strdup ()

    char *
    p11_kit_space_strdup (const unsigned char *string,
                          size_t max_length);

In PKCS#11 structures many strings are encoded in a strange way. The string is placed in a fixed length buffer and then padded with spaces.

This function copies the space padded string into a normal null-terminated string. The result is owned by the caller.

    1
    2
    3
    4

    CK_INFO info;
    char *description;
       ...
    description = p11_kit_space_strdup (info->libraryDescription, sizeof (info->libraryDescription));

#### Parameters

string | Pointer to string block |
max_length | Maximum length of string block |

#### Returns

The newly allocated string, or `NULL` if memory could not be allocated.

### p11_kit_space_strlen ()

    size_t
    p11_kit_space_strlen (const unsigned char *string,
                          size_t max_length);

In PKCS#11 structures many strings are encoded in a strange way. The string is placed in a fixed length buffer and then padded with spaces.

This function determines the actual length of the string. Since the string is not null-terminated you need to pass in the size of buffer as max_length. The string will never be longer than this buffer.

    1
    2
    3
    4

    CK_INFO info;
    size_t length;
       ...
    length = p11_kit_space_strlen (info->libraryDescription, sizeof (info->libraryDescription));

#### Parameters

string | Pointer to string block |
max_length | Maximum length of string block |

#### Returns

The length of the space padded string.

### p11_kit_be_quiet ()

    void
    p11_kit_be_quiet (void);

Once this function is called, the p11-kit library will no longer print failure or warning messages to stderr.

### p11_kit_be_loud ()

    void
    p11_kit_be_loud (void);

Tell the p11-kit library will print failure or warning messages to stderr. This is the default behavior, but can be changed using `p11_kit_be_quiet()`.