gsk_modify_pkcs11_key

Return a gsk_buffer that adds or removes the equals sign (=) from the first position of an input TKDS key token label.

Format

   #include <gskcms.h>

   gsk_status gsk_modify_pkcs11_key_label (
                                          gsk_buffer *             in_buffer,
                                          gsk_boolean              add_preface,
                                          gsk_buffer *             out_buffer)

Parameters

in_buffer: Specifies the gsk_buffer containing the TKDS key token label.
add_preface: Specify TRUE if you want an equal sign (=) prefaced at the beginning of the TKDS key token label. This shifts the original string to the right one position.
Specify FALSE if you want the equal sign (=) removed from the beginning of the TKDS key token label. This shifts the original string to the left one position.
out_buffer: Returns a new gsk_buffer with the TKDS key token label in its new form.

Results

The function return value is 0 (GSK_OK) if no error is detected. Otherwise, it is one of the return codes that are listed in the gskcms.h include file. These are some possible errors:

[CMSERR_NO_MEMORY]: Insufficient storage is available.
[CMSERR_PKCS11_LABEL_INVALID]: The input did not have a label.
If add_preface is FALSE and the calculated length of the output string minus the equal sign (=) is zero.

Usage

The gsk_modify_pkcs11_key_label() routine creates gsk_buffer of the TKDS key label either with or without the equal sign (=) in the first position of the string.

A TKDS key label without the equals sign is always 44 characters long.
A TKDS key label with an equal sign is always 45 characters long.
The caller is responsible for freeing the storage that is allocated to create the returned out_buffer.
- If the returned out_buffer does not become the keyToken field of structure pkcs_private_key_info, call gsk_free_buffer() to free out_buffer.
- If the returned out_buffer is used as the keyToken field of structure pkcs_private_key_info, the returned out_buffer is freed when calling gsk_free_private_key_info().
If the supplied TKDS key token label already has the equal sign in the first position and add_preface is TRUE, a copy of the original string is returned.
If the supplied TKDS key token label already does not have the equal sign in the first position and add_preface is FALSE, a copy of the original string is returned.