oken specified by a URL. Since 3.6.3 the objects are marked as sensitive by default unless ‘GNUTLS_PKCS11_OBJ_FLAG_MARK_NOT_SENSITIVE’ is specified. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 2.12.0 gnutls_pkcs11_copy_x509_privkey2 -------------------------------- -- Function: int gnutls_pkcs11_copy_x509_privkey2 (const char * TOKEN_URL, gnutls_x509_privkey_t KEY, const char * LABEL, const gnutls_datum_t * CID, unsigned int KEY_USAGE, unsigned int FLAGS) TOKEN_URL: A PKCS ‘11’ URL specifying a token KEY: A private key LABEL: A name to be used for the stored data CID: The CKA_ID to set for the object -if NULL, the ID will be derived from the public key KEY_USAGE: One of GNUTLS_KEY_* FLAGS: One of GNUTLS_PKCS11_OBJ_* flags This function will copy a private key into a PKCS ‘11’ token specified by a URL. Since 3.6.3 the objects are marked as sensitive by default unless ‘GNUTLS_PKCS11_OBJ_FLAG_MARK_NOT_SENSITIVE’ is specified. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.4.0 gnutls_pkcs11_crt_is_known -------------------------- -- Function: unsigned gnutls_pkcs11_crt_is_known (const char * URL, gnutls_x509_crt_t CERT, unsigned int FLAGS) URL: A PKCS 11 url identifying a token CERT: is the certificate to find issuer for FLAGS: Use zero or flags from ‘GNUTLS_PKCS11_OBJ_FLAG’ . This function will check whether the provided certificate is stored in the specified token. This is useful in combination with ‘GNUTLS_PKCS11_OBJ_FLAG_RETRIEVE_TRUSTED’ or ‘GNUTLS_PKCS11_OBJ_FLAG_RETRIEVE_DISTRUSTED’ , to check whether a CA is present or a certificate is distrusted in a trust PKCS ‘11’ module. This function can be used with a ‘url’ of "pkcs11:", and in that case all modules will be searched. To restrict the modules to the marked as trusted in p11-kit use the ‘GNUTLS_PKCS11_OBJ_FLAG_PRESENT_IN_TRUSTED_MODULE’ flag. Note that the flag ‘GNUTLS_PKCS11_OBJ_FLAG_RETRIEVE_DISTRUSTED’ is specific to p11-kit trust modules. *Returns:* If the certificate exists non-zero is returned, otherwise zero. *Since:* 3.3.0 gnutls_pkcs11_deinit -------------------- -- Function: void gnutls_pkcs11_deinit ( VOID) This function will deinitialize the PKCS 11 subsystem in gnutls. This function is only needed if you need to deinitialize the subsystem without calling ‘gnutls_global_deinit()’ . *Since:* 2.12.0 gnutls_pkcs11_delete_url ------------------------ -- Function: int gnutls_pkcs11_delete_url (const char * OBJECT_URL, unsigned int FLAGS) OBJECT_URL: The URL of the object to delete. FLAGS: One of GNUTLS_PKCS11_OBJ_* flags This function will delete objects matching the given URL. Note that not all tokens support the delete operation. *Returns:* On success, the number of objects deleted is returned, otherwise a negative error value. *Since:* 2.12.0 gnutls_pkcs11_get_pin_function ------------------------------ -- Function: gnutls_pin_callback_t gnutls_pkcs11_get_pin_function (void ** USERDATA) USERDATA: data to be supplied to callback This function will return the callback function set using ‘gnutls_pkcs11_set_pin_function()’ . *Returns:* The function set or NULL otherwise. *Since:* 3.1.0 gnutls_pkcs11_get_raw_issuer ---------------------------- -- Function: int gnutls_pkcs11_get_raw_issuer (const char * URL, gnutls_x509_crt_t CERT, gnutls_datum_t * ISSUER, gnutls_x509_crt_fmt_t FMT, unsigned int FLAGS) URL: A PKCS 11 url identifying a token CERT: is the certificate to find issuer for ISSUER: Will hold the issuer if any in an allocated buffer. FMT: The format of the exported issuer. FLAGS: Use zero or flags from ‘GNUTLS_PKCS11_OBJ_FLAG’ . This function will return the issuer of a given certificate, if it is stored in the token. By default only marked as trusted issuers are returned. If any issuer should be returned specify ‘GNUTLS_PKCS11_OBJ_FLAG_RETRIEVE_ANY’ in ‘flags’ . *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.2.7 gnutls_pkcs11_get_raw_issuer_by_dn ---------------------------------- -- Function: int gnutls_pkcs11_get_raw_issuer_by_dn (const char * URL, const gnutls_datum_t * DN, gnutls_datum_t * ISSUER, gnutls_x509_crt_fmt_t FMT, unsigned int FLAGS) URL: A PKCS 11 url identifying a token DN: is the DN to search for ISSUER: Will hold the issuer if any in an allocated buffer. FMT: The format of the exported issuer. FLAGS: Use zero or flags from ‘GNUTLS_PKCS11_OBJ_FLAG’ . This function will return the certificate with the given DN, if it is stored in the token. By default only marked as trusted issuers are returned. If any issuer should be returned specify ‘GNUTLS_PKCS11_OBJ_FLAG_RETRIEVE_ANY’ in ‘flags’ . The name of the function includes issuer because it can be used to discover issuers of certificates. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.4.0 gnutls_pkcs11_get_raw_issuer_by_subject_key_id ---------------------------------------------- -- Function: int gnutls_pkcs11_get_raw_issuer_by_subject_key_id (const char * URL, const gnutls_datum_t * DN, const gnutls_datum_t * SPKI, gnutls_datum_t * ISSUER, gnutls_x509_crt_fmt_t FMT, unsigned int FLAGS) URL: A PKCS 11 url identifying a token DN: is the DN to search for (may be ‘NULL’ ) SPKI: is the subject key ID to search for ISSUER: Will hold the issuer if any in an allocated buffer. FMT: The format of the exported issuer. FLAGS: Use zero or flags from ‘GNUTLS_PKCS11_OBJ_FLAG’ . This function will return the certificate with the given DN and ‘spki’ , if it is stored in the token. By default only marked as trusted issuers are returned. If any issuer should be returned specify ‘GNUTLS_PKCS11_OBJ_FLAG_RETRIEVE_ANY’ in ‘flags’ . The name of the function includes issuer because it can be used to discover issuers of certificates. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.4.2 gnutls_pkcs11_init ------------------ -- Function: int gnutls_pkcs11_init (unsigned int FLAGS, const char * DEPRECATED_CONFIG_FILE) FLAGS: An ORed sequence of ‘GNUTLS_PKCS11_FLAG_’ * DEPRECATED_CONFIG_FILE: either NULL or the location of a deprecated configuration file This function will initialize the PKCS 11 subsystem in gnutls. It will read configuration files if ‘GNUTLS_PKCS11_FLAG_AUTO’ is used or allow you to independently load PKCS 11 modules using ‘gnutls_pkcs11_add_provider()’ if ‘GNUTLS_PKCS11_FLAG_MANUAL’ is specified. You don't need to call this function since GnuTLS 3.3.0 because it is being called during the first request PKCS 11 operation. That call will assume the ‘GNUTLS_PKCS11_FLAG_AUTO’ flag. If another flags are required then it must be called independently prior to any PKCS 11 operation. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 2.12.0 gnutls_pkcs11_obj_deinit ------------------------ -- Function: void gnutls_pkcs11_obj_deinit (gnutls_pkcs11_obj_t OBJ) OBJ: The type to be deinitialized This function will deinitialize a certificate structure. *Since:* 2.12.0 gnutls_pkcs11_obj_export ------------------------ -- Function: int gnutls_pkcs11_obj_export (gnutls_pkcs11_obj_t OBJ, void * OUTPUT_DATA, size_t * OUTPUT_DATA_SIZE) OBJ: Holds the object OUTPUT_DATA: will contain the object data OUTPUT_DATA_SIZE: holds the size of output_data (and will be replaced by the actual size of parameters) This function will export the PKCS11 object data. It is normal for data to be inaccessible and in that case ‘GNUTLS_E_INVALID_REQUEST’ will be returned. If the buffer provided is not long enough to hold the output, then *output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will be returned. *Returns:* In case of failure a negative error code will be returned, and ‘GNUTLS_E_SUCCESS’ (0) on success. *Since:* 2.12.0 gnutls_pkcs11_obj_export2 ------------------------- -- Function: int gnutls_pkcs11_obj_export2 (gnutls_pkcs11_obj_t OBJ, gnutls_datum_t * OUT) OBJ: Holds the object OUT: will contain the object data This function will export the PKCS11 object data. It is normal for data to be inaccessible and in that case ‘GNUTLS_E_INVALID_REQUEST’ will be returned. The output buffer is allocated using ‘gnutls_malloc()’ . *Returns:* In case of failure a negative error code will be returned, and ‘GNUTLS_E_SUCCESS’ (0) on success. *Since:* 3.1.3 gnutls_pkcs11_obj_export3 ------------------------- -- Function: int gnutls_pkcs11_obj_export3 (gnutls_pkcs11_obj_t OBJ, gnutls_x509_crt_fmt_t FMT, gnutls_datum_t * OUT) OBJ: Holds the object FMT: The format of the exported data OUT: will contain the object data This function will export the PKCS11 object data. It is normal for data to be inaccessible and in that case ‘GNUTLS_E_INVALID_REQUEST’ will be returned. The output buffer is allocated using ‘gnutls_malloc()’ . *Returns:* In case of failure a negative error code will be returned, and ‘GNUTLS_E_SUCCESS’ (0) on success. *Since:* 3.2.7 gnutls_pkcs11_obj_export_url ---------------------------- -- Function: int gnutls_pkcs11_obj_export_url (gnutls_pkcs11_obj_t OBJ, gnutls_pkcs11_url_type_t DETAILED, char ** URL) OBJ: Holds the PKCS 11 certificate DETAILED: non zero if a detailed URL is required URL: will contain an allocated url This function will export a URL identifying the given object. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 2.12.0 gnutls_pkcs11_obj_flags_get_str ------------------------------- -- Function: char * gnutls_pkcs11_obj_flags_get_str (unsigned int FLAGS) FLAGS: holds the flags This function given an or-sequence of ‘GNUTLS_PKCS11_OBJ_FLAG_MARK’ , will return an allocated string with its description. The string needs to be deallocated using ‘gnutls_free()’ . *Returns:* If flags is zero ‘NULL’ is returned, otherwise an allocated string. *Since:* 3.3.7 gnutls_pkcs11_obj_get_exts -------------------------- -- Function: int gnutls_pkcs11_obj_get_exts (gnutls_pkcs11_obj_t OBJ, gnutls_x509_ext_st ** EXTS, unsigned int * EXTS_SIZE, unsigned int FLAGS) OBJ: should contain a ‘gnutls_pkcs11_obj_t’ type EXTS: a pointer to a ‘gnutls_x509_ext_st’ pointer EXTS_SIZE: will be updated with the number of ‘exts’ FLAGS: Or sequence of ‘GNUTLS_PKCS11_OBJ_’ * flags This function will return information about attached extensions that associate to the provided object (which should be a certificate). The extensions are the attached p11-kit trust module extensions. Each element of ‘exts’ must be deinitialized using ‘gnutls_x509_ext_deinit()’ while ‘exts’ should be deallocated using ‘gnutls_free()’ . *Returns:* ‘GNUTLS_E_SUCCESS’ (0) on success or a negative error code on error. *Since:* 3.3.8 gnutls_pkcs11_obj_get_flags --------------------------- -- Function: int gnutls_pkcs11_obj_get_flags (gnutls_pkcs11_obj_t OBJ, unsigned int * OFLAGS) OBJ: The pkcs11 object OFLAGS: Will hold the output flags This function will return the flags of the object. The ‘oflags’ will be flags from ‘gnutls_pkcs11_obj_flags’ . That is, the ‘GNUTLS_PKCS11_OBJ_FLAG_MARK_’ * flags. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.3.7 gnutls_pkcs11_obj_get_info -------------------------- -- Function: int gnutls_pkcs11_obj_get_info (gnutls_pkcs11_obj_t OBJ, gnutls_pkcs11_obj_info_t ITYPE, void * OUTPUT, size_t * OUTPUT_SIZE) OBJ: should contain a ‘gnutls_pkcs11_obj_t’ type ITYPE: Denotes the type of information requested OUTPUT: where output will be stored OUTPUT_SIZE: contains the maximum size of the output buffer and will be overwritten with the actual size. This function will return information about the PKCS11 certificate such as the label, id as well as token information where the key is stored. When output is text, a null terminated string is written to ‘output’ and its string length is written to ‘output_size’ (without null terminator). If the buffer is too small, ‘output_size’ will contain the expected buffer size (with null terminator for text) and return ‘GNUTLS_E_SHORT_MEMORY_BUFFER’ . In versions previously to 3.6.0 this function included the null terminator to ‘output_size’ . After 3.6.0 the output size doesn't include the terminator character. *Returns:* ‘GNUTLS_E_SUCCESS’ (0) on success or a negative error code on error. *Since:* 2.12.0 gnutls_pkcs11_obj_get_ptr ------------------------- -- Function: int gnutls_pkcs11_obj_get_ptr (gnutls_pkcs11_obj_t OBJ, void ** PTR, void ** SESSION, void ** OHANDLE, unsigned long * SLOT_ID, unsigned int FLAGS) OBJ: should contain a ‘gnutls_pkcs11_obj_t’ type PTR: will contain the CK_FUNCTION_LIST_PTR pointer (may be ‘NULL’ ) SESSION: will contain the CK_SESSION_HANDLE of the object OHANDLE: will contain the CK_OBJECT_HANDLE of the object SLOT_ID: the identifier of the slot (may be ‘NULL’ ) FLAGS: Or sequence of GNUTLS_PKCS11_OBJ_* flags Obtains the PKCS‘11’ session handles of an object. ‘session’ and ‘ohandle’ must be deinitialized by the caller. The returned pointers are independent of the ‘obj’ lifetime. *Returns:* ‘GNUTLS_E_SUCCESS’ (0) on success or a negative error code on error. *Since:* 3.6.3 gnutls_pkcs11_obj_get_type -------------------------- -- Function: gnutls_pkcs11_obj_type_t gnutls_pkcs11_obj_get_type (gnutls_pkcs11_obj_t OBJ) OBJ: Holds the PKCS 11 object This function will return the type of the object being stored in the structure. *Returns:* The type of the object *Since:* 2.12.0 gnutls_pkcs11_obj_import_url ---------------------------- -- Function: int gnutls_pkcs11_obj_import_url (gnutls_pkcs11_obj_t OBJ, const char * URL, unsigned int FLAGS) OBJ: The structure to store the object URL: a PKCS 11 url identifying the key FLAGS: Or sequence of GNUTLS_PKCS11_OBJ_* flags This function will "import" a PKCS 11 URL identifying an object (e.g. certificate) to the ‘gnutls_pkcs11_obj_t’ type. This does not involve any parsing (such as X.509 or OpenPGP) since the ‘gnutls_pkcs11_obj_t’ is format agnostic. Only data are transferred. If the flag ‘GNUTLS_PKCS11_OBJ_FLAG_OVERWRITE_TRUSTMOD_EXT’ is specified any certificate read, will have its extensions overwritten by any stapled extensions in the trust module. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 2.12.0 gnutls_pkcs11_obj_init ---------------------- -- Function: int gnutls_pkcs11_obj_init (gnutls_pkcs11_obj_t * OBJ) OBJ: A pointer to the type to be initialized This function will initialize a pkcs11 certificate structure. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 2.12.0 gnutls_pkcs11_obj_list_import_url3 ---------------------------------- -- Function: int gnutls_pkcs11_obj_list_import_url3 (gnutls_pkcs11_obj_t * P_LIST, unsigned int * N_LIST, const char * URL, unsigned int FLAGS) P_LIST: An uninitialized object list (may be ‘NULL’ ) N_LIST: Initially should hold the maximum size of the list. Will contain the actual size. URL: A PKCS 11 url identifying a set of objects FLAGS: Or sequence of GNUTLS_PKCS11_OBJ_* flags This function will initialize and set values to an object list by using all objects identified by a PKCS 11 URL. This function will enumerate all the objects specified by the PKCS‘11’ URL provided. It expects an already allocated ‘p_list’ which has * ‘n_list’ elements, and that value will be updated to the actual number of present objects. The ‘p_list’ objects will be initialized and set by this function. To obtain a list of all available objects use a ‘url’ of 'pkcs11:'. All returned objects must be deinitialized using ‘gnutls_pkcs11_obj_deinit()’ . The supported in this function ‘flags’ are ‘GNUTLS_PKCS11_OBJ_FLAG_LOGIN’ , ‘GNUTLS_PKCS11_OBJ_FLAG_LOGIN_SO’ , ‘GNUTLS_PKCS11_OBJ_FLAG_PRESENT_IN_TRUSTED_MODULE’ , ‘GNUTLS_PKCS11_OBJ_FLAG_CRT’ , ‘GNUTLS_PKCS11_OBJ_FLAG_PUBKEY’ , ‘GNUTLS_PKCS11_OBJ_FLAG_PRIVKEY’ , ‘GNUTLS_PKCS11_OBJ_FLAG_WITH_PRIVKEY’ , ‘GNUTLS_PKCS11_OBJ_FLAG_MARK_CA’ , ‘GNUTLS_PKCS11_OBJ_FLAG_MARK_TRUSTED’ , and since 3.5.1 the ‘GNUTLS_PKCS11_OBJ_FLAG_OVERWRITE_TRUSTMOD_EXT’ . On versions of GnuTLS prior to 3.4.0 the equivalent function was ‘gnutls_pkcs11_obj_list_import_url()’ . That is also available on this version as a macro which maps to this function. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.4.0 gnutls_pkcs11_obj_list_import_url4 ---------------------------------- -- Function: int gnutls_pkcs11_obj_list_import_url4 (gnutls_pkcs11_obj_t ** P_LIST, unsigned int * N_LIST, const char * URL, unsigned int FLAGS) P_LIST: An uninitialized object list (may be NULL) N_LIST: It will contain the size of the list. URL: A PKCS 11 url identifying a set of objects FLAGS: Or sequence of GNUTLS_PKCS11_OBJ_* flags This function will enumerate all the objects specified by the PKCS‘11’ URL provided. It will initialize and set values to the object pointer list ( ‘p_list’ ) provided. To obtain a list of all available objects use a ‘url’ of 'pkcs11:'. All returned objects must be deinitialized using ‘gnutls_pkcs11_obj_deinit()’ , and ‘p_list’ must be deinitialized using ‘gnutls_free()’ . The supported in this function ‘flags’ are ‘GNUTLS_PKCS11_OBJ_FLAG_LOGIN’ , ‘GNUTLS_PKCS11_OBJ_FLAG_LOGIN_SO’ , ‘GNUTLS_PKCS11_OBJ_FLAG_PRESENT_IN_TRUSTED_MODULE’ , ‘GNUTLS_PKCS11_OBJ_FLAG_CRT’ , ‘GNUTLS_PKCS11_OBJ_FLAG_PUBKEY’ , ‘GNUTLS_PKCS11_OBJ_FLAG_PRIVKEY’ , ‘GNUTLS_PKCS11_OBJ_FLAG_WITH_PRIVKEY’ , ‘GNUTLS_PKCS11_OBJ_FLAG_MARK_CA’ , ‘GNUTLS_PKCS11_OBJ_FLAG_MARK_TRUSTED’ , and since 3.5.1 the ‘GNUTLS_PKCS11_OBJ_FLAG_OVERWRITE_TRUSTMOD_EXT’ . On versions of GnuTLS prior to 3.4.0 the equivalent function was ‘gnutls_pkcs11_obj_list_import_url2()’ . That is also available on this version as a macro which maps to this function. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.4.0 gnutls_pkcs11_obj_set_info -------------------------- -- Function: int gnutls_pkcs11_obj_set_info (gnutls_pkcs11_obj_t OBJ, gnutls_pkcs11_obj_info_t ITYPE, const void * DATA, size_t DATA_SIZE, unsigned FLAGS) OBJ: should contain a ‘gnutls_pkcs11_obj_t’ type ITYPE: Denotes the type of information to be set DATA: the data to set DATA_SIZE: the size of data FLAGS: Or sequence of GNUTLS_PKCS11_OBJ_* flags This function will set attributes on the provided object. Available options for ‘itype’ are ‘GNUTLS_PKCS11_OBJ_LABEL’ , ‘GNUTLS_PKCS11_OBJ_ID_HEX’ , and ‘GNUTLS_PKCS11_OBJ_ID’ . *Returns:* ‘GNUTLS_E_SUCCESS’ (0) on success or a negative error code on error. *Since:* 3.4.0 gnutls_pkcs11_obj_set_pin_function ---------------------------------- -- Function: void gnutls_pkcs11_obj_set_pin_function (gnutls_pkcs11_obj_t OBJ, gnutls_pin_callback_t FN, void * USERDATA) OBJ: The object structure FN: the callback USERDATA: data associated with the callback This function will set a callback function to be used when required to access the object. This function overrides the global set using ‘gnutls_pkcs11_set_pin_function()’ . *Since:* 3.1.0 gnutls_pkcs11_privkey_cpy ------------------------- -- Function: int gnutls_pkcs11_privkey_cpy (gnutls_pkcs11_privkey_t DST, gnutls_pkcs11_privkey_t SRC) DST: The destination key, which should be initialized. SRC: The source key This function will copy a private key from source to destination key. Destination has to be initialized. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.4.0 gnutls_pkcs11_privkey_deinit ---------------------------- -- Function: void gnutls_pkcs11_privkey_deinit (gnutls_pkcs11_privkey_t KEY) KEY: the key to be deinitialized This function will deinitialize a private key structure. gnutls_pkcs11_privkey_export_pubkey ----------------------------------- -- Function: int gnutls_pkcs11_privkey_export_pubkey (gnutls_pkcs11_privkey_t PKEY, gnutls_x509_crt_fmt_t FMT, gnutls_datum_t * DATA, unsigned int FLAGS) PKEY: The private key FMT: the format of output params. PEM or DER. DATA: will hold the public key FLAGS: should be zero This function will extract the public key (modulus and public exponent) from the private key specified by the ‘url’ private key. This public key will be stored in ‘pubkey’ in the format specified by ‘fmt’ . ‘pubkey’ should be deinitialized using ‘gnutls_free()’ . *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.3.7 gnutls_pkcs11_privkey_export_url -------------------------------- -- Function: int gnutls_pkcs11_privkey_export_url (gnutls_pkcs11_privkey_t KEY, gnutls_pkcs11_url_type_t DETAILED, char ** URL) KEY: Holds the PKCS 11 key DETAILED: non zero if a detailed URL is required URL: will contain an allocated url This function will export a URL identifying the given key. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. gnutls_pkcs11_privkey_generate ------------------------------ -- Function: int gnutls_pkcs11_privkey_generate (const char * URL, gnutls_pk_algorithm_t PK, unsigned int BITS, const char * LABEL, unsigned int FLAGS) URL: a token URL PK: the public key algorithm BITS: the security bits LABEL: a label FLAGS: should be zero This function will generate a private key in the specified by the ‘url’ token. The private key will be generate within the token and will not be exportable. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.0 gnutls_pkcs11_privkey_generate2 ------------------------------- -- Function: int gnutls_pkcs11_privkey_generate2 (const char * URL, gnutls_pk_algorithm_t PK, unsigned int BITS, const char * LABEL, gnutls_x509_crt_fmt_t FMT, gnutls_datum_t * PUBKEY, unsigned int FLAGS) URL: a token URL PK: the public key algorithm BITS: the security bits LABEL: a label FMT: the format of output params. PEM or DER PUBKEY: will hold the public key (may be ‘NULL’ ) FLAGS: zero or an OR'ed sequence of ‘GNUTLS_PKCS11_OBJ_FLAGs’ This function will generate a private key in the specified by the ‘url’ token. The private key will be generate within the token and will not be exportable. This function will store the DER-encoded public key in the SubjectPublicKeyInfo format in ‘pubkey’ . The ‘pubkey’ should be deinitialized using ‘gnutls_free()’ . Note that when generating an elliptic curve key, the curve can be substituted in the place of the bits parameter using the ‘GNUTLS_CURVE_TO_BITS()’ macro. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.1.5 gnutls_pkcs11_privkey_generate3 ------------------------------- -- Function: int gnutls_pkcs11_privkey_generate3 (const char * URL, gnutls_pk_algorithm_t PK, unsigned int BITS, const char * LABEL, const gnutls_datum_t * CID, gnutls_x509_crt_fmt_t FMT, gnutls_datum_t * PUBKEY, unsigned int KEY_USAGE, unsigned int FLAGS) URL: a token URL PK: the public key algorithm BITS: the security bits LABEL: a label CID: The CKA_ID to use for the new object FMT: the format of output params. PEM or DER PUBKEY: will hold the public key (may be ‘NULL’ ) KEY_USAGE: One of GNUTLS_KEY_* FLAGS: zero or an OR'ed sequence of ‘GNUTLS_PKCS11_OBJ_FLAGs’ This function will generate a private key in the specified by the ‘url’ token. The private key will be generate within the token and will not be exportable. This function will store the DER-encoded public key in the SubjectPublicKeyInfo format in ‘pubkey’ . The ‘pubkey’ should be deinitialized using ‘gnutls_free()’ . Note that when generating an elliptic curve key, the curve can be substituted in the place of the bits parameter using the ‘GNUTLS_CURVE_TO_BITS()’ macro. Since 3.6.3 the objects are marked as sensitive by default unless ‘GNUTLS_PKCS11_OBJ_FLAG_MARK_NOT_SENSITIVE’ is specified. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.4.0 gnutls_pkcs11_privkey_get_info ------------------------------ -- Function: int gnutls_pkcs11_privkey_get_info (gnutls_pkcs11_privkey_t PKEY, gnutls_pkcs11_obj_info_t ITYPE, void * OUTPUT, size_t * OUTPUT_SIZE) PKEY: should contain a ‘gnutls_pkcs11_privkey_t’ type ITYPE: Denotes the type of information requested OUTPUT: where output will be stored OUTPUT_SIZE: contains the maximum size of the output and will be overwritten with actual This function will return information about the PKCS 11 private key such as the label, id as well as token information where the key is stored. When output is text it returns null terminated string although ‘output_size’ contains the size of the actual data only. *Returns:* ‘GNUTLS_E_SUCCESS’ (0) on success or a negative error code on error. gnutls_pkcs11_privkey_get_pk_algorithm -------------------------------------- -- Function: int gnutls_pkcs11_privkey_get_pk_algorithm (gnutls_pkcs11_privkey_t KEY, unsigned int * BITS) KEY: should contain a ‘gnutls_pkcs11_privkey_t’ type BITS: if bits is non null it will hold the size of the parameters' in bits This function will return the public key algorithm of a private key. *Returns:* a member of the ‘gnutls_pk_algorithm_t’ enumeration on success, or a negative error code on error. gnutls_pkcs11_privkey_import_url -------------------------------- -- Function: int gnutls_pkcs11_privkey_import_url (gnutls_pkcs11_privkey_t PKEY, const char * URL, unsigned int FLAGS) PKEY: The private key URL: a PKCS 11 url identifying the key FLAGS: Or sequence of GNUTLS_PKCS11_OBJ_* flags This function will "import" a PKCS 11 URL identifying a private key to the ‘gnutls_pkcs11_privkey_t’ type. In reality since in most cases keys cannot be exported, the private key structure is being associated with the available operations on the token. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. gnutls_pkcs11_privkey_init -------------------------- -- Function: int gnutls_pkcs11_privkey_init (gnutls_pkcs11_privkey_t * KEY) KEY: A pointer to the type to be initialized This function will initialize an private key structure. This structure can be used for accessing an underlying PKCS‘11’ object. In versions of GnuTLS later than 3.5.11 the object is protected using locks and a single ‘gnutls_pkcs11_privkey_t’ can be re-used by many threads. However, for performance it is recommended to utilize one object per key per thread. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. gnutls_pkcs11_privkey_set_pin_function -------------------------------------- -- Function: void gnutls_pkcs11_privkey_set_pin_function (gnutls_pkcs11_privkey_t KEY, gnutls_pin_callback_t FN, void * USERDATA) KEY: The private key FN: the callback USERDATA: data associated with the callback This function will set a callback function to be used when required to access the object. This function overrides the global set using ‘gnutls_pkcs11_set_pin_function()’ . *Since:* 3.1.0 gnutls_pkcs11_privkey_status ---------------------------- -- Function: unsigned gnutls_pkcs11_privkey_status (gnutls_pkcs11_privkey_t KEY) KEY: Holds the key Checks the status of the private key token. *Returns:* this function will return non-zero if the token holding the private key is still available (inserted), and zero otherwise. *Since:* 3.1.9 gnutls_pkcs11_reinit -------------------- -- Function: int gnutls_pkcs11_reinit ( VOID) This function will reinitialize the PKCS 11 subsystem in gnutls. This is required by PKCS 11 when an application uses ‘fork()’ . The reinitialization function must be called on the child. Note that since GnuTLS 3.3.0, the reinitialization of the PKCS ‘11’ subsystem occurs automatically after fork. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 3.0 gnutls_pkcs11_set_pin_function ------------------------------ -- Function: void gnutls_pkcs11_set_pin_function (gnutls_pin_callback_t FN, void * USERDATA) FN: The PIN callback, a ‘gnutls_pin_callback_t()’ function. USERDATA: data to be supplied to callback This function will set a callback function to be used when a PIN is required for PKCS 11 operations. See ‘gnutls_pin_callback_t()’ on how the callback should behave. *Since:* 2.12.0 gnutls_pkcs11_set_token_function -------------------------------- -- Function: void gnutls_pkcs11_set_token_function (gnutls_pkcs11_token_callback_t FN, void * USERDATA) FN: The token callback USERDATA: data to be supplied to callback This function will set a callback function to be used when a token needs to be inserted to continue PKCS 11 operations. *Since:* 2.12.0 gnutls_pkcs11_token_check_mechanism ----------------------------------- -- Function: unsigned gnutls_pkcs11_token_check_mechanism (const char * URL, unsigned long MECHANISM, void * PTR, unsigned PSIZE, unsigned FLAGS) URL: should contain a PKCS 11 URL MECHANISM: The PKCS ‘11’ mechanism ID PTR: if set it should point to a CK_MECHANISM_INFO struct PSIZE: the size of CK_MECHANISM_INFO struct (for safety) FLAGS: must be zero This function will return whether a mechanism is supported by the given token. If the mechanism is supported and ‘ptr’ is set, it will be updated with the token information. *Returns:* Non-zero if the mechanism is supported or zero otherwise. *Since:* 3.6.0 gnutls_pkcs11_token_get_flags ----------------------------- -- Function: int gnutls_pkcs11_token_get_flags (const char * URL, unsigned int * FLAGS) URL: should contain a PKCS 11 URL FLAGS: The output flags (GNUTLS_PKCS11_TOKEN_*) This function will return information about the PKCS 11 token flags. The supported flags are: ‘GNUTLS_PKCS11_TOKEN_HW’ and ‘GNUTLS_PKCS11_TOKEN_TRUSTED’ . *Returns:* ‘GNUTLS_E_SUCCESS’ (0) on success or a negative error code on error. *Since:* 2.12.0 gnutls_pkcs11_token_get_info ---------------------------- -- Function: int gnutls_pkcs11_token_get_info (const char * URL, gnutls_pkcs11_token_info_t TTYPE, void * OUTPUT, size_t * OUTPUT_SIZE) URL: should contain a PKCS 11 URL TTYPE: Denotes the type of information requested OUTPUT: where output will be stored OUTPUT_SIZE: contains the maximum size of the output buffer and will be overwritten with the actual size. This function will return information about the PKCS 11 token such as the label, id, etc. When output is text, a null terminated string is written to ‘output’ and its string length is written to ‘output_size’ (without null terminator). If the buffer is too small, ‘output_size’ will contain the expected buffer size (with null terminator for text) and return ‘GNUTLS_E_SHORT_MEMORY_BUFFER’ . *Returns:* ‘GNUTLS_E_SUCCESS’ (0) on success or a negative error code on error. *Since:* 2.12.0 gnutls_pkcs11_token_get_mechanism --------------------------------- -- Function: int gnutls_pkcs11_token_get_mechanism (const char * URL, unsigned int IDX, unsigned long * MECHANISM) URL: should contain a PKCS 11 URL IDX: The index of the mechanism MECHANISM: The PKCS ‘11’ mechanism ID This function will return the names of the supported mechanisms by the token. It should be called with an increasing index until it return GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE. *Returns:* ‘GNUTLS_E_SUCCESS’ (0) on success or a negative error code on error. *Since:* 2.12.0 gnutls_pkcs11_token_get_ptr --------------------------- -- Function: int gnutls_pkcs11_token_get_ptr (const char * URL, void ** PTR, unsigned long * SLOT_ID, unsigned int FLAGS) URL: should contain a PKCS‘11’ URL identifying a token PTR: will contain the CK_FUNCTION_LIST_PTR pointer SLOT_ID: will contain the slot_id (may be ‘NULL’ ) FLAGS: should be zero This function will return the function pointer of the specified token by the URL. The returned pointers are valid until gnutls is deinitialized, c.f. ‘_global_deinit()’ . *Returns:* ‘GNUTLS_E_SUCCESS’ (0) on success or a negative error code on error. *Since:* 3.6.3 gnutls_pkcs11_token_get_random ------------------------------ -- Function: int gnutls_pkcs11_token_get_random (const char * TOKEN_URL, void * RNDDATA, size_t LEN) TOKEN_URL: A PKCS ‘11’ URL specifying a token RNDDATA: A pointer to the memory area to be filled with random data LEN: The number of bytes of randomness to request This function will get random data from the given token. It will store rnddata and fill the memory pointed to by rnddata with len random bytes from the token. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. gnutls_pkcs11_token_get_url --------------------------- -- Function: int gnutls_pkcs11_token_get_url (unsigned int SEQ, gnutls_pkcs11_url_type_t DETAILED, char ** URL) SEQ: sequence number starting from 0 DETAILED: non zero if a detailed URL is required URL: will contain an allocated url This function will return the URL for each token available in system. The url has to be released using ‘gnutls_free()’ *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, ‘GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE’ if the sequence number exceeds the available tokens, otherwise a negative error value. *Since:* 2.12.0 gnutls_pkcs11_token_init ------------------------ -- Function: int gnutls_pkcs11_token_init (const char * TOKEN_URL, const char * SO_PIN, const char * LABEL) TOKEN_URL: A PKCS ‘11’ URL specifying a token SO_PIN: Security Officer's PIN LABEL: A name to be used for the token This function will initialize (format) a token. If the token is at a factory defaults state the security officer's PIN given will be set to be the default. Otherwise it should match the officer's PIN. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. gnutls_pkcs11_token_set_pin --------------------------- -- Function: int gnutls_pkcs11_token_set_pin (const char * TOKEN_URL, const char * OLDPIN, const char * NEWPIN, unsigned int FLAGS) TOKEN_URL: A PKCS ‘11’ URL specifying a token OLDPIN: old user's PIN NEWPIN: new user's PIN FLAGS: one of ‘gnutls_pin_flag_t’ . This function will modify or set a user or administrator's PIN for the given token. If it is called to set a PIN for first time the oldpin must be ‘NULL’ . When setting the admin's PIN with the ‘GNUTLS_PIN_SO’ flag, the ‘oldpin’ value must be provided (this requirement is relaxed after GnuTLS 3.6.5 since which the PIN will be requested if missing). *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. gnutls_pkcs11_type_get_name --------------------------- -- Function: const char * gnutls_pkcs11_type_get_name (gnutls_pkcs11_obj_type_t TYPE) TYPE: Holds the PKCS 11 object type, a ‘gnutls_pkcs11_obj_type_t’ . This function will return a human readable description of the PKCS11 object type ‘obj’ . It will return "Unknown" for unknown types. *Returns:* human readable string labeling the PKCS11 object type ‘type’ . *Since:* 2.12.0 gnutls_x509_crt_import_pkcs11 ----------------------------- -- Function: int gnutls_x509_crt_import_pkcs11 (gnutls_x509_crt_t CRT, gnutls_pkcs11_obj_t PKCS11_CRT) CRT: A certificate of type ‘gnutls_x509_crt_t’ PKCS11_CRT: A PKCS 11 object that contains a certificate This function will import a PKCS 11 certificate to a ‘gnutls_x509_crt_t’ structure. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 2.12.0 gnutls_x509_crt_list_import_pkcs11 ---------------------------------- -- Function: int gnutls_x509_crt_list_import_pkcs11 (gnutls_x509_crt_t * CERTS, unsigned int CERT_MAX, gnutls_pkcs11_obj_t *const OBJS, unsigned int FLAGS) CERTS: A list of certificates of type ‘gnutls_x509_crt_t’ CERT_MAX: The maximum size of the list OBJS: A list of PKCS 11 objects FLAGS: 0 for now This function will import a PKCS 11 certificate list to a list of ‘gnutls_x509_crt_t’ type. These must not be initialized. *Returns:* On success, ‘GNUTLS_E_SUCCESS’ (0) is returned, otherwise a negative error value. *Since:* 2.12.0