diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/pkcs11-api.texi | 1247 |
1 files changed, 1247 insertions, 0 deletions
diff --git a/doc/pkcs11-api.texi b/doc/pkcs11-api.texi new file mode 100644 index 0000000..d40c615 --- /dev/null +++ b/doc/pkcs11-api.texi @@ -0,0 +1,1247 @@ + +@subheading gnutls_pkcs11_add_provider +@anchor{gnutls_pkcs11_add_provider} +@deftypefun {int} {gnutls_pkcs11_add_provider} (const char * @var{name}, const char * @var{params}) +@var{name}: The filename of the module + +@var{params}: should be NULL or a known string (see description) + +This function will load and add a PKCS 11 module to the module +list used in gnutls. After this function is called the module will +be used for PKCS 11 operations. + +When loading a module to be used for certificate verification, +use the string 'trusted' as @code{params} . + +Note that this function is not thread safe. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 2.12.0 +@end deftypefun + +@subheading gnutls_pkcs11_copy_attached_extension +@anchor{gnutls_pkcs11_copy_attached_extension} +@deftypefun {int} {gnutls_pkcs11_copy_attached_extension} (const char * @var{token_url}, gnutls_x509_crt_t @var{crt}, gnutls_datum_t * @var{data}, const char * @var{label}, unsigned int @var{flags}) +@var{token_url}: A PKCS @code{11} URL specifying a token + +@var{crt}: An X.509 certificate object + +@var{data}: the attached extension + +@var{label}: A name to be used for the attached extension (may be @code{NULL} ) + +@var{flags}: One of GNUTLS_PKCS11_OBJ_FLAG_* + +This function will copy an the attached extension in @code{data} for +the certificate provided in @code{crt} in the PKCS @code{11} token specified +by the URL (typically a trust module). The extension must be in +RFC5280 Extension format. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.3.8 +@end deftypefun + +@subheading gnutls_pkcs11_copy_pubkey +@anchor{gnutls_pkcs11_copy_pubkey} +@deftypefun {int} {gnutls_pkcs11_copy_pubkey} (const char * @var{token_url}, gnutls_pubkey_t @var{pubkey}, const char * @var{label}, const gnutls_datum_t * @var{cid}, unsigned int @var{key_usage}, unsigned int @var{flags}) +@var{token_url}: A PKCS @code{11} URL specifying a token + +@var{pubkey}: The public key to copy + +@var{label}: The name to be used for the stored data + +@var{cid}: The CKA_ID to set for the object -if NULL, the ID will be derived from the public key + +@var{key_usage}: One of GNUTLS_KEY_* + +@var{flags}: One of GNUTLS_PKCS11_OBJ_FLAG_* + +This function will copy a public key object into a PKCS @code{11} token specified by +a URL. Valid flags to mark the key: @code{GNUTLS_PKCS11_OBJ_FLAG_MARK_TRUSTED} , +@code{GNUTLS_PKCS11_OBJ_FLAG_MARK_PRIVATE} , @code{GNUTLS_PKCS11_OBJ_FLAG_MARK_CA} , +@code{GNUTLS_PKCS11_OBJ_FLAG_MARK_ALWAYS_AUTH} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.4.6 +@end deftypefun + +@subheading gnutls_pkcs11_copy_secret_key +@anchor{gnutls_pkcs11_copy_secret_key} +@deftypefun {int} {gnutls_pkcs11_copy_secret_key} (const char * @var{token_url}, gnutls_datum_t * @var{key}, const char * @var{label}, unsigned int @var{key_usage}, unsigned int @var{flags}) +@var{token_url}: A PKCS @code{11} URL specifying a token + +@var{key}: The raw key + +@var{label}: A name to be used for the stored data + +@var{key_usage}: One of GNUTLS_KEY_* + +@var{flags}: One of GNUTLS_PKCS11_OBJ_FLAG_* + +This function will copy a raw secret (symmetric) key into a PKCS @code{11} +token specified by a URL. The key can be marked as sensitive or not. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 2.12.0 +@end deftypefun + +@subheading gnutls_pkcs11_copy_x509_crt +@anchor{gnutls_pkcs11_copy_x509_crt} +@deftypefun {int} {gnutls_pkcs11_copy_x509_crt} (const char * @var{token_url}, gnutls_x509_crt_t @var{crt}, const char * @var{label}, unsigned int @var{flags}) +@var{token_url}: A PKCS @code{11} URL specifying a token + +@var{crt}: A certificate + +@var{label}: A name to be used for the stored data + +@var{flags}: One of GNUTLS_PKCS11_OBJ_FLAG_* + +This function will copy a certificate into a PKCS @code{11} token specified by +a URL. The certificate can be marked as trusted or not. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 2.12.0 +@end deftypefun + +@subheading gnutls_pkcs11_copy_x509_crt2 +@anchor{gnutls_pkcs11_copy_x509_crt2} +@deftypefun {int} {gnutls_pkcs11_copy_x509_crt2} (const char * @var{token_url}, gnutls_x509_crt_t @var{crt}, const char * @var{label}, const gnutls_datum_t * @var{cid}, unsigned int @var{flags}) +@var{token_url}: A PKCS @code{11} URL specifying a token + +@var{crt}: The certificate to copy + +@var{label}: The name to be used for the stored data + +@var{cid}: The CKA_ID to set for the object -if NULL, the ID will be derived from the public key + +@var{flags}: One of GNUTLS_PKCS11_OBJ_FLAG_* + +This function will copy a certificate into a PKCS @code{11} token specified by +a URL. Valid flags to mark the certificate: @code{GNUTLS_PKCS11_OBJ_FLAG_MARK_TRUSTED} , +@code{GNUTLS_PKCS11_OBJ_FLAG_MARK_PRIVATE} , @code{GNUTLS_PKCS11_OBJ_FLAG_MARK_CA} , +@code{GNUTLS_PKCS11_OBJ_FLAG_MARK_ALWAYS_AUTH} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.4.0 +@end deftypefun + +@subheading gnutls_pkcs11_copy_x509_privkey +@anchor{gnutls_pkcs11_copy_x509_privkey} +@deftypefun {int} {gnutls_pkcs11_copy_x509_privkey} (const char * @var{token_url}, gnutls_x509_privkey_t @var{key}, const char * @var{label}, unsigned int @var{key_usage}, unsigned int @var{flags}) +@var{token_url}: A PKCS @code{11} URL specifying a token + +@var{key}: A private key + +@var{label}: A name to be used for the stored data + +@var{key_usage}: One of GNUTLS_KEY_* + +@var{flags}: One of GNUTLS_PKCS11_OBJ_* flags + +This function will copy a private key into a PKCS @code{11} token specified by +a URL. + +Since 3.6.3 the objects are marked as sensitive by default unless +@code{GNUTLS_PKCS11_OBJ_FLAG_MARK_NOT_SENSITIVE} is specified. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 2.12.0 +@end deftypefun + +@subheading gnutls_pkcs11_copy_x509_privkey2 +@anchor{gnutls_pkcs11_copy_x509_privkey2} +@deftypefun {int} {gnutls_pkcs11_copy_x509_privkey2} (const char * @var{token_url}, gnutls_x509_privkey_t @var{key}, const char * @var{label}, const gnutls_datum_t * @var{cid}, unsigned int @var{key_usage}, unsigned int @var{flags}) +@var{token_url}: A PKCS @code{11} URL specifying a token + +@var{key}: A private key + +@var{label}: A name to be used for the stored data + +@var{cid}: The CKA_ID to set for the object -if NULL, the ID will be derived from the public key + +@var{key_usage}: One of GNUTLS_KEY_* + +@var{flags}: One of GNUTLS_PKCS11_OBJ_* flags + +This function will copy a private key into a PKCS @code{11} token specified by +a URL. + +Since 3.6.3 the objects are marked as sensitive by default unless +@code{GNUTLS_PKCS11_OBJ_FLAG_MARK_NOT_SENSITIVE} is specified. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.4.0 +@end deftypefun + +@subheading gnutls_pkcs11_crt_is_known +@anchor{gnutls_pkcs11_crt_is_known} +@deftypefun {unsigned} {gnutls_pkcs11_crt_is_known} (const char * @var{url}, gnutls_x509_crt_t @var{cert}, unsigned int @var{flags}) +@var{url}: A PKCS 11 url identifying a token + +@var{cert}: is the certificate to find issuer for + +@var{flags}: Use zero or flags from @code{GNUTLS_PKCS11_OBJ_FLAG} . + +This function will check whether the provided certificate is stored +in the specified token. This is useful in combination with +@code{GNUTLS_PKCS11_OBJ_FLAG_RETRIEVE_TRUSTED} or +@code{GNUTLS_PKCS11_OBJ_FLAG_RETRIEVE_DISTRUSTED} , +to check whether a CA is present or a certificate is blacklisted in +a trust PKCS @code{11} module. + +This function can be used with a @code{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 @code{GNUTLS_PKCS11_OBJ_FLAG_PRESENT_IN_TRUSTED_MODULE} flag. + +Note that the flag @code{GNUTLS_PKCS11_OBJ_FLAG_RETRIEVE_DISTRUSTED} is +specific to p11-kit trust modules. + +@strong{Returns:} If the certificate exists non-zero is returned, otherwise zero. + +@strong{Since:} 3.3.0 +@end deftypefun + +@subheading gnutls_pkcs11_deinit +@anchor{gnutls_pkcs11_deinit} +@deftypefun {void} {gnutls_pkcs11_deinit} ( @var{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 @code{gnutls_global_deinit()} . + +@strong{Since:} 2.12.0 +@end deftypefun + +@subheading gnutls_pkcs11_delete_url +@anchor{gnutls_pkcs11_delete_url} +@deftypefun {int} {gnutls_pkcs11_delete_url} (const char * @var{object_url}, unsigned int @var{flags}) +@var{object_url}: The URL of the object to delete. + +@var{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. + +@strong{Returns:} On success, the number of objects deleted is returned, otherwise a +negative error value. + +@strong{Since:} 2.12.0 +@end deftypefun + +@subheading gnutls_pkcs11_get_pin_function +@anchor{gnutls_pkcs11_get_pin_function} +@deftypefun {gnutls_pin_callback_t} {gnutls_pkcs11_get_pin_function} (void ** @var{userdata}) +@var{userdata}: data to be supplied to callback + +This function will return the callback function set using +@code{gnutls_pkcs11_set_pin_function()} . + +@strong{Returns:} The function set or NULL otherwise. + +@strong{Since:} 3.1.0 +@end deftypefun + +@subheading gnutls_pkcs11_get_raw_issuer +@anchor{gnutls_pkcs11_get_raw_issuer} +@deftypefun {int} {gnutls_pkcs11_get_raw_issuer} (const char * @var{url}, gnutls_x509_crt_t @var{cert}, gnutls_datum_t * @var{issuer}, gnutls_x509_crt_fmt_t @var{fmt}, unsigned int @var{flags}) +@var{url}: A PKCS 11 url identifying a token + +@var{cert}: is the certificate to find issuer for + +@var{issuer}: Will hold the issuer if any in an allocated buffer. + +@var{fmt}: The format of the exported issuer. + +@var{flags}: Use zero or flags from @code{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 +@code{GNUTLS_PKCS11_OBJ_FLAG_RETRIEVE_ANY} in @code{flags} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.2.7 +@end deftypefun + +@subheading gnutls_pkcs11_get_raw_issuer_by_dn +@anchor{gnutls_pkcs11_get_raw_issuer_by_dn} +@deftypefun {int} {gnutls_pkcs11_get_raw_issuer_by_dn} (const char * @var{url}, const gnutls_datum_t * @var{dn}, gnutls_datum_t * @var{issuer}, gnutls_x509_crt_fmt_t @var{fmt}, unsigned int @var{flags}) +@var{url}: A PKCS 11 url identifying a token + +@var{dn}: is the DN to search for + +@var{issuer}: Will hold the issuer if any in an allocated buffer. + +@var{fmt}: The format of the exported issuer. + +@var{flags}: Use zero or flags from @code{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 +@code{GNUTLS_PKCS11_OBJ_FLAG_RETRIEVE_ANY} in @code{flags} . + +The name of the function includes issuer because it can +be used to discover issuers of certificates. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.4.0 +@end deftypefun + +@subheading gnutls_pkcs11_get_raw_issuer_by_subject_key_id +@anchor{gnutls_pkcs11_get_raw_issuer_by_subject_key_id} +@deftypefun {int} {gnutls_pkcs11_get_raw_issuer_by_subject_key_id} (const char * @var{url}, const gnutls_datum_t * @var{dn}, const gnutls_datum_t * @var{spki}, gnutls_datum_t * @var{issuer}, gnutls_x509_crt_fmt_t @var{fmt}, unsigned int @var{flags}) +@var{url}: A PKCS 11 url identifying a token + +@var{dn}: is the DN to search for (may be @code{NULL} ) + +@var{spki}: is the subject key ID to search for + +@var{issuer}: Will hold the issuer if any in an allocated buffer. + +@var{fmt}: The format of the exported issuer. + +@var{flags}: Use zero or flags from @code{GNUTLS_PKCS11_OBJ_FLAG} . + +This function will return the certificate with the given DN and @code{spki} , if it +is stored in the token. By default only marked as trusted issuers +are returned. If any issuer should be returned specify +@code{GNUTLS_PKCS11_OBJ_FLAG_RETRIEVE_ANY} in @code{flags} . + +The name of the function includes issuer because it can +be used to discover issuers of certificates. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.4.2 +@end deftypefun + +@subheading gnutls_pkcs11_init +@anchor{gnutls_pkcs11_init} +@deftypefun {int} {gnutls_pkcs11_init} (unsigned int @var{flags}, const char * @var{deprecated_config_file}) +@var{flags}: An ORed sequence of @code{GNUTLS_PKCS11_FLAG_} * + +@var{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 @code{GNUTLS_PKCS11_FLAG_AUTO} is used or allow +you to independently load PKCS 11 modules using @code{gnutls_pkcs11_add_provider()} +if @code{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 @code{GNUTLS_PKCS11_FLAG_AUTO} +flag. If another flags are required then it must be called independently +prior to any PKCS 11 operation. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 2.12.0 +@end deftypefun + +@subheading gnutls_pkcs11_obj_deinit +@anchor{gnutls_pkcs11_obj_deinit} +@deftypefun {void} {gnutls_pkcs11_obj_deinit} (gnutls_pkcs11_obj_t @var{obj}) +@var{obj}: The type to be deinitialized + +This function will deinitialize a certificate structure. + +@strong{Since:} 2.12.0 +@end deftypefun + +@subheading gnutls_pkcs11_obj_export +@anchor{gnutls_pkcs11_obj_export} +@deftypefun {int} {gnutls_pkcs11_obj_export} (gnutls_pkcs11_obj_t @var{obj}, void * @var{output_data}, size_t * @var{output_data_size}) +@var{obj}: Holds the object + +@var{output_data}: will contain the object data + +@var{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 @code{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. + +@strong{Returns:} In case of failure a negative error code will be +returned, and @code{GNUTLS_E_SUCCESS} (0) on success. + +@strong{Since:} 2.12.0 +@end deftypefun + +@subheading gnutls_pkcs11_obj_export2 +@anchor{gnutls_pkcs11_obj_export2} +@deftypefun {int} {gnutls_pkcs11_obj_export2} (gnutls_pkcs11_obj_t @var{obj}, gnutls_datum_t * @var{out}) +@var{obj}: Holds the object + +@var{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 @code{GNUTLS_E_INVALID_REQUEST} +will be returned. + +The output buffer is allocated using @code{gnutls_malloc()} . + +@strong{Returns:} In case of failure a negative error code will be +returned, and @code{GNUTLS_E_SUCCESS} (0) on success. + +@strong{Since:} 3.1.3 +@end deftypefun + +@subheading gnutls_pkcs11_obj_export3 +@anchor{gnutls_pkcs11_obj_export3} +@deftypefun {int} {gnutls_pkcs11_obj_export3} (gnutls_pkcs11_obj_t @var{obj}, gnutls_x509_crt_fmt_t @var{fmt}, gnutls_datum_t * @var{out}) +@var{obj}: Holds the object + +@var{fmt}: The format of the exported data + +@var{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 @code{GNUTLS_E_INVALID_REQUEST} +will be returned. + +The output buffer is allocated using @code{gnutls_malloc()} . + +@strong{Returns:} In case of failure a negative error code will be +returned, and @code{GNUTLS_E_SUCCESS} (0) on success. + +@strong{Since:} 3.2.7 +@end deftypefun + +@subheading gnutls_pkcs11_obj_export_url +@anchor{gnutls_pkcs11_obj_export_url} +@deftypefun {int} {gnutls_pkcs11_obj_export_url} (gnutls_pkcs11_obj_t @var{obj}, gnutls_pkcs11_url_type_t @var{detailed}, char ** @var{url}) +@var{obj}: Holds the PKCS 11 certificate + +@var{detailed}: non zero if a detailed URL is required + +@var{url}: will contain an allocated url + +This function will export a URL identifying the given object. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 2.12.0 +@end deftypefun + +@subheading gnutls_pkcs11_obj_flags_get_str +@anchor{gnutls_pkcs11_obj_flags_get_str} +@deftypefun {char *} {gnutls_pkcs11_obj_flags_get_str} (unsigned int @var{flags}) +@var{flags}: holds the flags + +This function given an or-sequence of @code{GNUTLS_PKCS11_OBJ_FLAG_MARK} , +will return an allocated string with its description. The string +needs to be deallocated using @code{gnutls_free()} . + +@strong{Returns:} If flags is zero @code{NULL} is returned, otherwise an allocated string. + +@strong{Since:} 3.3.7 +@end deftypefun + +@subheading gnutls_pkcs11_obj_get_exts +@anchor{gnutls_pkcs11_obj_get_exts} +@deftypefun {int} {gnutls_pkcs11_obj_get_exts} (gnutls_pkcs11_obj_t @var{obj}, gnutls_x509_ext_st ** @var{exts}, unsigned int * @var{exts_size}, unsigned int @var{flags}) +@var{obj}: should contain a @code{gnutls_pkcs11_obj_t} type + +@var{exts}: a pointer to a @code{gnutls_x509_ext_st} pointer + +@var{exts_size}: will be updated with the number of @code{exts} + +@var{flags}: Or sequence of @code{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 @code{exts} must be deinitialized using @code{gnutls_x509_ext_deinit()} +while @code{exts} should be deallocated using @code{gnutls_free()} . + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} (0) on success or a negative error code on error. + +@strong{Since:} 3.3.8 +@end deftypefun + +@subheading gnutls_pkcs11_obj_get_flags +@anchor{gnutls_pkcs11_obj_get_flags} +@deftypefun {int} {gnutls_pkcs11_obj_get_flags} (gnutls_pkcs11_obj_t @var{obj}, unsigned int * @var{oflags}) +@var{obj}: The pkcs11 object + +@var{oflags}: Will hold the output flags + +This function will return the flags of the object. +The @code{oflags} will be flags from @code{gnutls_pkcs11_obj_flags} . That is, +the @code{GNUTLS_PKCS11_OBJ_FLAG_MARK_} * flags. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.3.7 +@end deftypefun + +@subheading gnutls_pkcs11_obj_get_info +@anchor{gnutls_pkcs11_obj_get_info} +@deftypefun {int} {gnutls_pkcs11_obj_get_info} (gnutls_pkcs11_obj_t @var{obj}, gnutls_pkcs11_obj_info_t @var{itype}, void * @var{output}, size_t * @var{output_size}) +@var{obj}: should contain a @code{gnutls_pkcs11_obj_t} type + +@var{itype}: Denotes the type of information requested + +@var{output}: where output will be stored + +@var{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 @code{output} and its +string length is written to @code{output_size} (without null terminator). If the +buffer is too small, @code{output_size} will contain the expected buffer size +(with null terminator for text) and return @code{GNUTLS_E_SHORT_MEMORY_BUFFER} . + +In versions previously to 3.6.0 this function included the null terminator +to @code{output_size} . After 3.6.0 the output size doesn't include the terminator character. + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} (0) on success or a negative error code on error. + +@strong{Since:} 2.12.0 +@end deftypefun + +@subheading gnutls_pkcs11_obj_get_ptr +@anchor{gnutls_pkcs11_obj_get_ptr} +@deftypefun {int} {gnutls_pkcs11_obj_get_ptr} (gnutls_pkcs11_obj_t @var{obj}, void ** @var{ptr}, void ** @var{session}, void ** @var{ohandle}, unsigned long * @var{slot_id}, unsigned int @var{flags}) +@var{obj}: should contain a @code{gnutls_pkcs11_obj_t} type + +@var{ptr}: will contain the CK_FUNCTION_LIST_PTR pointer (may be @code{NULL} ) + +@var{session}: will contain the CK_SESSION_HANDLE of the object + +@var{ohandle}: will contain the CK_OBJECT_HANDLE of the object + +@var{slot_id}: the identifier of the slot (may be @code{NULL} ) + +@var{flags}: Or sequence of GNUTLS_PKCS11_OBJ_* flags + +Obtains the PKCS@code{11} session handles of an object. @code{session} and @code{ohandle} must be deinitialized by the caller. The returned pointers are +independent of the @code{obj} lifetime. + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} (0) on success or a negative error code +on error. + +@strong{Since:} 3.6.3 +@end deftypefun + +@subheading gnutls_pkcs11_obj_get_type +@anchor{gnutls_pkcs11_obj_get_type} +@deftypefun {gnutls_pkcs11_obj_type_t} {gnutls_pkcs11_obj_get_type} (gnutls_pkcs11_obj_t @var{obj}) +@var{obj}: Holds the PKCS 11 object + +This function will return the type of the object being +stored in the structure. + +@strong{Returns:} The type of the object + +@strong{Since:} 2.12.0 +@end deftypefun + +@subheading gnutls_pkcs11_obj_import_url +@anchor{gnutls_pkcs11_obj_import_url} +@deftypefun {int} {gnutls_pkcs11_obj_import_url} (gnutls_pkcs11_obj_t @var{obj}, const char * @var{url}, unsigned int @var{flags}) +@var{obj}: The structure to store the object + +@var{url}: a PKCS 11 url identifying the key + +@var{flags}: Or sequence of GNUTLS_PKCS11_OBJ_* flags + +This function will "import" a PKCS 11 URL identifying an object (e.g. certificate) +to the @code{gnutls_pkcs11_obj_t} type. This does not involve any +parsing (such as X.509 or OpenPGP) since the @code{gnutls_pkcs11_obj_t} is +format agnostic. Only data are transferred. + +If the flag @code{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. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 2.12.0 +@end deftypefun + +@subheading gnutls_pkcs11_obj_init +@anchor{gnutls_pkcs11_obj_init} +@deftypefun {int} {gnutls_pkcs11_obj_init} (gnutls_pkcs11_obj_t * @var{obj}) +@var{obj}: A pointer to the type to be initialized + +This function will initialize a pkcs11 certificate structure. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 2.12.0 +@end deftypefun + +@subheading gnutls_pkcs11_obj_list_import_url3 +@anchor{gnutls_pkcs11_obj_list_import_url3} +@deftypefun {int} {gnutls_pkcs11_obj_list_import_url3} (gnutls_pkcs11_obj_t * @var{p_list}, unsigned int * @var{n_list}, const char * @var{url}, unsigned int @var{flags}) +@var{p_list}: An uninitialized object list (may be @code{NULL} ) + +@var{n_list}: Initially should hold the maximum size of the list. Will contain the actual size. + +@var{url}: A PKCS 11 url identifying a set of objects + +@var{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@code{11} URL +provided. It expects an already allocated @code{p_list} which has * @code{n_list} elements, +and that value will be updated to the actual number of present objects. The + @code{p_list} objects will be initialized and set by this function. +To obtain a list of all available objects use a @code{url} of 'pkcs11:'. + +All returned objects must be deinitialized using @code{gnutls_pkcs11_obj_deinit()} . + +The supported in this function @code{flags} are @code{GNUTLS_PKCS11_OBJ_FLAG_LOGIN} , +@code{GNUTLS_PKCS11_OBJ_FLAG_LOGIN_SO} , @code{GNUTLS_PKCS11_OBJ_FLAG_PRESENT_IN_TRUSTED_MODULE} , +@code{GNUTLS_PKCS11_OBJ_FLAG_CRT} , @code{GNUTLS_PKCS11_OBJ_FLAG_PUBKEY} , @code{GNUTLS_PKCS11_OBJ_FLAG_PRIVKEY} , +@code{GNUTLS_PKCS11_OBJ_FLAG_WITH_PRIVKEY} , @code{GNUTLS_PKCS11_OBJ_FLAG_MARK_CA} , +@code{GNUTLS_PKCS11_OBJ_FLAG_MARK_TRUSTED} , and since 3.5.1 the @code{GNUTLS_PKCS11_OBJ_FLAG_OVERWRITE_TRUSTMOD_EXT} . + +On versions of GnuTLS prior to 3.4.0 the equivalent function was +@code{gnutls_pkcs11_obj_list_import_url()} . That is also available on this version +as a macro which maps to this function. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.4.0 +@end deftypefun + +@subheading gnutls_pkcs11_obj_list_import_url4 +@anchor{gnutls_pkcs11_obj_list_import_url4} +@deftypefun {int} {gnutls_pkcs11_obj_list_import_url4} (gnutls_pkcs11_obj_t ** @var{p_list}, unsigned int * @var{n_list}, const char * @var{url}, unsigned int @var{flags}) +@var{p_list}: An uninitialized object list (may be NULL) + +@var{n_list}: It will contain the size of the list. + +@var{url}: A PKCS 11 url identifying a set of objects + +@var{flags}: Or sequence of GNUTLS_PKCS11_OBJ_* flags + +This function will enumerate all the objects specified by the PKCS@code{11} URL +provided. It will initialize and set values to the object pointer list ( @code{p_list} ) +provided. To obtain a list of all available objects use a @code{url} of 'pkcs11:'. + +All returned objects must be deinitialized using @code{gnutls_pkcs11_obj_deinit()} , +and @code{p_list} must be deinitialized using @code{gnutls_free()} . + +The supported in this function @code{flags} are @code{GNUTLS_PKCS11_OBJ_FLAG_LOGIN} , +@code{GNUTLS_PKCS11_OBJ_FLAG_LOGIN_SO} , @code{GNUTLS_PKCS11_OBJ_FLAG_PRESENT_IN_TRUSTED_MODULE} , +@code{GNUTLS_PKCS11_OBJ_FLAG_CRT} , @code{GNUTLS_PKCS11_OBJ_FLAG_PUBKEY} , @code{GNUTLS_PKCS11_OBJ_FLAG_PRIVKEY} , +@code{GNUTLS_PKCS11_OBJ_FLAG_WITH_PRIVKEY} , @code{GNUTLS_PKCS11_OBJ_FLAG_MARK_CA} , +@code{GNUTLS_PKCS11_OBJ_FLAG_MARK_TRUSTED} , and since 3.5.1 the @code{GNUTLS_PKCS11_OBJ_FLAG_OVERWRITE_TRUSTMOD_EXT} . + +On versions of GnuTLS prior to 3.4.0 the equivalent function was +@code{gnutls_pkcs11_obj_list_import_url2()} . That is also available on this version +as a macro which maps to this function. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.4.0 +@end deftypefun + +@subheading gnutls_pkcs11_obj_set_info +@anchor{gnutls_pkcs11_obj_set_info} +@deftypefun {int} {gnutls_pkcs11_obj_set_info} (gnutls_pkcs11_obj_t @var{obj}, gnutls_pkcs11_obj_info_t @var{itype}, const void * @var{data}, size_t @var{data_size}, unsigned @var{flags}) +@var{obj}: should contain a @code{gnutls_pkcs11_obj_t} type + +@var{itype}: Denotes the type of information to be set + +@var{data}: the data to set + +@var{data_size}: the size of data + +@var{flags}: Or sequence of GNUTLS_PKCS11_OBJ_* flags + +This function will set attributes on the provided object. +Available options for @code{itype} are @code{GNUTLS_PKCS11_OBJ_LABEL} , +@code{GNUTLS_PKCS11_OBJ_ID_HEX} , and @code{GNUTLS_PKCS11_OBJ_ID} . + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} (0) on success or a negative error code on error. + +@strong{Since:} 3.4.0 +@end deftypefun + +@subheading gnutls_pkcs11_obj_set_pin_function +@anchor{gnutls_pkcs11_obj_set_pin_function} +@deftypefun {void} {gnutls_pkcs11_obj_set_pin_function} (gnutls_pkcs11_obj_t @var{obj}, gnutls_pin_callback_t @var{fn}, void * @var{userdata}) +@var{obj}: The object structure + +@var{fn}: the callback + +@var{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 @code{gnutls_pkcs11_set_pin_function()} . + +@strong{Since:} 3.1.0 +@end deftypefun + +@subheading gnutls_pkcs11_privkey_cpy +@anchor{gnutls_pkcs11_privkey_cpy} +@deftypefun {int} {gnutls_pkcs11_privkey_cpy} (gnutls_pkcs11_privkey_t @var{dst}, gnutls_pkcs11_privkey_t @var{src}) +@var{dst}: The destination key, which should be initialized. + +@var{src}: The source key + +This function will copy a private key from source to destination +key. Destination has to be initialized. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.4.0 +@end deftypefun + +@subheading gnutls_pkcs11_privkey_deinit +@anchor{gnutls_pkcs11_privkey_deinit} +@deftypefun {void} {gnutls_pkcs11_privkey_deinit} (gnutls_pkcs11_privkey_t @var{key}) +@var{key}: the key to be deinitialized + +This function will deinitialize a private key structure. +@end deftypefun + +@subheading gnutls_pkcs11_privkey_export_pubkey +@anchor{gnutls_pkcs11_privkey_export_pubkey} +@deftypefun {int} {gnutls_pkcs11_privkey_export_pubkey} (gnutls_pkcs11_privkey_t @var{pkey}, gnutls_x509_crt_fmt_t @var{fmt}, gnutls_datum_t * @var{data}, unsigned int @var{flags}) +@var{pkey}: The private key + +@var{fmt}: the format of output params. PEM or DER. + +@var{data}: will hold the public key + +@var{flags}: should be zero + +This function will extract the public key (modulus and public +exponent) from the private key specified by the @code{url} private key. +This public key will be stored in @code{pubkey} in the format specified +by @code{fmt} . @code{pubkey} should be deinitialized using @code{gnutls_free()} . + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.3.7 +@end deftypefun + +@subheading gnutls_pkcs11_privkey_export_url +@anchor{gnutls_pkcs11_privkey_export_url} +@deftypefun {int} {gnutls_pkcs11_privkey_export_url} (gnutls_pkcs11_privkey_t @var{key}, gnutls_pkcs11_url_type_t @var{detailed}, char ** @var{url}) +@var{key}: Holds the PKCS 11 key + +@var{detailed}: non zero if a detailed URL is required + +@var{url}: will contain an allocated url + +This function will export a URL identifying the given key. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_pkcs11_privkey_generate +@anchor{gnutls_pkcs11_privkey_generate} +@deftypefun {int} {gnutls_pkcs11_privkey_generate} (const char * @var{url}, gnutls_pk_algorithm_t @var{pk}, unsigned int @var{bits}, const char * @var{label}, unsigned int @var{flags}) +@var{url}: a token URL + +@var{pk}: the public key algorithm + +@var{bits}: the security bits + +@var{label}: a label + +@var{flags}: should be zero + +This function will generate a private key in the specified +by the @code{url} token. The private key will be generate within +the token and will not be exportable. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.0 +@end deftypefun + +@subheading gnutls_pkcs11_privkey_generate2 +@anchor{gnutls_pkcs11_privkey_generate2} +@deftypefun {int} {gnutls_pkcs11_privkey_generate2} (const char * @var{url}, gnutls_pk_algorithm_t @var{pk}, unsigned int @var{bits}, const char * @var{label}, gnutls_x509_crt_fmt_t @var{fmt}, gnutls_datum_t * @var{pubkey}, unsigned int @var{flags}) +@var{url}: a token URL + +@var{pk}: the public key algorithm + +@var{bits}: the security bits + +@var{label}: a label + +@var{fmt}: the format of output params. PEM or DER + +@var{pubkey}: will hold the public key (may be @code{NULL} ) + +@var{flags}: zero or an OR'ed sequence of @code{GNUTLS_PKCS11_OBJ_FLAGs} + +This function will generate a private key in the specified +by the @code{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 @code{pubkey} . The @code{pubkey} should be deinitialized using @code{gnutls_free()} . + +Note that when generating an elliptic curve key, the curve +can be substituted in the place of the bits parameter using the +@code{GNUTLS_CURVE_TO_BITS()} macro. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.1.5 +@end deftypefun + +@subheading gnutls_pkcs11_privkey_generate3 +@anchor{gnutls_pkcs11_privkey_generate3} +@deftypefun {int} {gnutls_pkcs11_privkey_generate3} (const char * @var{url}, gnutls_pk_algorithm_t @var{pk}, unsigned int @var{bits}, const char * @var{label}, const gnutls_datum_t * @var{cid}, gnutls_x509_crt_fmt_t @var{fmt}, gnutls_datum_t * @var{pubkey}, unsigned int @var{key_usage}, unsigned int @var{flags}) +@var{url}: a token URL + +@var{pk}: the public key algorithm + +@var{bits}: the security bits + +@var{label}: a label + +@var{cid}: The CKA_ID to use for the new object + +@var{fmt}: the format of output params. PEM or DER + +@var{pubkey}: will hold the public key (may be @code{NULL} ) + +@var{key_usage}: One of GNUTLS_KEY_* + +@var{flags}: zero or an OR'ed sequence of @code{GNUTLS_PKCS11_OBJ_FLAGs} + +This function will generate a private key in the specified +by the @code{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 @code{pubkey} . The @code{pubkey} should be deinitialized using @code{gnutls_free()} . + +Note that when generating an elliptic curve key, the curve +can be substituted in the place of the bits parameter using the +@code{GNUTLS_CURVE_TO_BITS()} macro. + +Since 3.6.3 the objects are marked as sensitive by default unless +@code{GNUTLS_PKCS11_OBJ_FLAG_MARK_NOT_SENSITIVE} is specified. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.4.0 +@end deftypefun + +@subheading gnutls_pkcs11_privkey_get_info +@anchor{gnutls_pkcs11_privkey_get_info} +@deftypefun {int} {gnutls_pkcs11_privkey_get_info} (gnutls_pkcs11_privkey_t @var{pkey}, gnutls_pkcs11_obj_info_t @var{itype}, void * @var{output}, size_t * @var{output_size}) +@var{pkey}: should contain a @code{gnutls_pkcs11_privkey_t} type + +@var{itype}: Denotes the type of information requested + +@var{output}: where output will be stored + +@var{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 @code{output_size} contains +the size of the actual data only. + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} (0) on success or a negative error code on error. +@end deftypefun + +@subheading gnutls_pkcs11_privkey_get_pk_algorithm +@anchor{gnutls_pkcs11_privkey_get_pk_algorithm} +@deftypefun {int} {gnutls_pkcs11_privkey_get_pk_algorithm} (gnutls_pkcs11_privkey_t @var{key}, unsigned int * @var{bits}) +@var{key}: should contain a @code{gnutls_pkcs11_privkey_t} type + +@var{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. + +@strong{Returns:} a member of the @code{gnutls_pk_algorithm_t} enumeration on +success, or a negative error code on error. +@end deftypefun + +@subheading gnutls_pkcs11_privkey_import_url +@anchor{gnutls_pkcs11_privkey_import_url} +@deftypefun {int} {gnutls_pkcs11_privkey_import_url} (gnutls_pkcs11_privkey_t @var{pkey}, const char * @var{url}, unsigned int @var{flags}) +@var{pkey}: The private key + +@var{url}: a PKCS 11 url identifying the key + +@var{flags}: Or sequence of GNUTLS_PKCS11_OBJ_* flags + +This function will "import" a PKCS 11 URL identifying a private +key to the @code{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. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_pkcs11_privkey_init +@anchor{gnutls_pkcs11_privkey_init} +@deftypefun {int} {gnutls_pkcs11_privkey_init} (gnutls_pkcs11_privkey_t * @var{key}) +@var{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@code{11} object. + +In versions of GnuTLS later than 3.5.11 the object is protected +using locks and a single @code{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. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_pkcs11_privkey_set_pin_function +@anchor{gnutls_pkcs11_privkey_set_pin_function} +@deftypefun {void} {gnutls_pkcs11_privkey_set_pin_function} (gnutls_pkcs11_privkey_t @var{key}, gnutls_pin_callback_t @var{fn}, void * @var{userdata}) +@var{key}: The private key + +@var{fn}: the callback + +@var{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 @code{gnutls_pkcs11_set_pin_function()} . + +@strong{Since:} 3.1.0 +@end deftypefun + +@subheading gnutls_pkcs11_privkey_status +@anchor{gnutls_pkcs11_privkey_status} +@deftypefun {unsigned} {gnutls_pkcs11_privkey_status} (gnutls_pkcs11_privkey_t @var{key}) +@var{key}: Holds the key + +Checks the status of the private key token. + +@strong{Returns:} this function will return non-zero if the token +holding the private key is still available (inserted), and zero otherwise. + +@strong{Since:} 3.1.9 +@end deftypefun + +@subheading gnutls_pkcs11_reinit +@anchor{gnutls_pkcs11_reinit} +@deftypefun {int} {gnutls_pkcs11_reinit} ( @var{void}) + +This function will reinitialize the PKCS 11 subsystem in gnutls. +This is required by PKCS 11 when an application uses @code{fork()} . The +reinitialization function must be called on the child. + +Note that since GnuTLS 3.3.0, the reinitialization of the PKCS @code{11} +subsystem occurs automatically after fork. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 3.0 +@end deftypefun + +@subheading gnutls_pkcs11_set_pin_function +@anchor{gnutls_pkcs11_set_pin_function} +@deftypefun {void} {gnutls_pkcs11_set_pin_function} (gnutls_pin_callback_t @var{fn}, void * @var{userdata}) +@var{fn}: The PIN callback, a @code{gnutls_pin_callback_t()} function. + +@var{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 +@code{gnutls_pin_callback_t()} on how the callback should behave. + +@strong{Since:} 2.12.0 +@end deftypefun + +@subheading gnutls_pkcs11_set_token_function +@anchor{gnutls_pkcs11_set_token_function} +@deftypefun {void} {gnutls_pkcs11_set_token_function} (gnutls_pkcs11_token_callback_t @var{fn}, void * @var{userdata}) +@var{fn}: The token callback + +@var{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. + +@strong{Since:} 2.12.0 +@end deftypefun + +@subheading gnutls_pkcs11_token_check_mechanism +@anchor{gnutls_pkcs11_token_check_mechanism} +@deftypefun {unsigned} {gnutls_pkcs11_token_check_mechanism} (const char * @var{url}, unsigned long @var{mechanism}, void * @var{ptr}, unsigned @var{psize}, unsigned @var{flags}) +@var{url}: should contain a PKCS 11 URL + +@var{mechanism}: The PKCS @code{11} mechanism ID + +@var{ptr}: if set it should point to a CK_MECHANISM_INFO struct + +@var{psize}: the size of CK_MECHANISM_INFO struct (for safety) + +@var{flags}: must be zero + +This function will return whether a mechanism is supported +by the given token. If the mechanism is supported and + @code{ptr} is set, it will be updated with the token information. + +@strong{Returns:} Non-zero if the mechanism is supported or zero otherwise. + +@strong{Since:} 3.6.0 +@end deftypefun + +@subheading gnutls_pkcs11_token_get_flags +@anchor{gnutls_pkcs11_token_get_flags} +@deftypefun {int} {gnutls_pkcs11_token_get_flags} (const char * @var{url}, unsigned int * @var{flags}) +@var{url}: should contain a PKCS 11 URL + +@var{flags}: The output flags (GNUTLS_PKCS11_TOKEN_*) + +This function will return information about the PKCS 11 token flags. + +The supported flags are: @code{GNUTLS_PKCS11_TOKEN_HW} and @code{GNUTLS_PKCS11_TOKEN_TRUSTED} . + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} (0) on success or a negative error code on error. + +@strong{Since:} 2.12.0 +@end deftypefun + +@subheading gnutls_pkcs11_token_get_info +@anchor{gnutls_pkcs11_token_get_info} +@deftypefun {int} {gnutls_pkcs11_token_get_info} (const char * @var{url}, gnutls_pkcs11_token_info_t @var{ttype}, void * @var{output}, size_t * @var{output_size}) +@var{url}: should contain a PKCS 11 URL + +@var{ttype}: Denotes the type of information requested + +@var{output}: where output will be stored + +@var{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 @code{output} and its +string length is written to @code{output_size} (without null terminator). If the +buffer is too small, @code{output_size} will contain the expected buffer size +(with null terminator for text) and return @code{GNUTLS_E_SHORT_MEMORY_BUFFER} . + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} (0) on success or a negative error code +on error. + +@strong{Since:} 2.12.0 +@end deftypefun + +@subheading gnutls_pkcs11_token_get_mechanism +@anchor{gnutls_pkcs11_token_get_mechanism} +@deftypefun {int} {gnutls_pkcs11_token_get_mechanism} (const char * @var{url}, unsigned int @var{idx}, unsigned long * @var{mechanism}) +@var{url}: should contain a PKCS 11 URL + +@var{idx}: The index of the mechanism + +@var{mechanism}: The PKCS @code{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. + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} (0) on success or a negative error code on error. + +@strong{Since:} 2.12.0 +@end deftypefun + +@subheading gnutls_pkcs11_token_get_ptr +@anchor{gnutls_pkcs11_token_get_ptr} +@deftypefun {int} {gnutls_pkcs11_token_get_ptr} (const char * @var{url}, void ** @var{ptr}, unsigned long * @var{slot_id}, unsigned int @var{flags}) +@var{url}: should contain a PKCS@code{11} URL identifying a token + +@var{ptr}: will contain the CK_FUNCTION_LIST_PTR pointer + +@var{slot_id}: will contain the slot_id (may be @code{NULL} ) + +@var{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. @code{_global_deinit()} . + +@strong{Returns:} @code{GNUTLS_E_SUCCESS} (0) on success or a negative error code +on error. + +@strong{Since:} 3.6.3 +@end deftypefun + +@subheading gnutls_pkcs11_token_get_random +@anchor{gnutls_pkcs11_token_get_random} +@deftypefun {int} {gnutls_pkcs11_token_get_random} (const char * @var{token_url}, void * @var{rnddata}, size_t @var{len}) +@var{token_url}: A PKCS @code{11} URL specifying a token + +@var{rnddata}: A pointer to the memory area to be filled with random data + +@var{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. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_pkcs11_token_get_url +@anchor{gnutls_pkcs11_token_get_url} +@deftypefun {int} {gnutls_pkcs11_token_get_url} (unsigned int @var{seq}, gnutls_pkcs11_url_type_t @var{detailed}, char ** @var{url}) +@var{seq}: sequence number starting from 0 + +@var{detailed}: non zero if a detailed URL is required + +@var{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 @code{gnutls_free()} + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, +@code{GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE} if the sequence number +exceeds the available tokens, otherwise a negative error value. + +@strong{Since:} 2.12.0 +@end deftypefun + +@subheading gnutls_pkcs11_token_init +@anchor{gnutls_pkcs11_token_init} +@deftypefun {int} {gnutls_pkcs11_token_init} (const char * @var{token_url}, const char * @var{so_pin}, const char * @var{label}) +@var{token_url}: A PKCS @code{11} URL specifying a token + +@var{so_pin}: Security Officer's PIN + +@var{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. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_pkcs11_token_set_pin +@anchor{gnutls_pkcs11_token_set_pin} +@deftypefun {int} {gnutls_pkcs11_token_set_pin} (const char * @var{token_url}, const char * @var{oldpin}, const char * @var{newpin}, unsigned int @var{flags}) +@var{token_url}: A PKCS @code{11} URL specifying a token + +@var{oldpin}: old user's PIN + +@var{newpin}: new user's PIN + +@var{flags}: one of @code{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 @code{NULL} . When setting the admin's PIN with the +@code{GNUTLS_PIN_SO} flag, the @code{oldpin} value must be provided (this requirement +is relaxed after GnuTLS 3.6.5 since which the PIN will be requested if missing). + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. +@end deftypefun + +@subheading gnutls_pkcs11_type_get_name +@anchor{gnutls_pkcs11_type_get_name} +@deftypefun {const char *} {gnutls_pkcs11_type_get_name} (gnutls_pkcs11_obj_type_t @var{type}) +@var{type}: Holds the PKCS 11 object type, a @code{gnutls_pkcs11_obj_type_t} . + +This function will return a human readable description of the +PKCS11 object type @code{obj} . It will return "Unknown" for unknown +types. + +@strong{Returns:} human readable string labeling the PKCS11 object type + @code{type} . + +@strong{Since:} 2.12.0 +@end deftypefun + +@subheading gnutls_x509_crt_import_pkcs11 +@anchor{gnutls_x509_crt_import_pkcs11} +@deftypefun {int} {gnutls_x509_crt_import_pkcs11} (gnutls_x509_crt_t @var{crt}, gnutls_pkcs11_obj_t @var{pkcs11_crt}) +@var{crt}: A certificate of type @code{gnutls_x509_crt_t} + +@var{pkcs11_crt}: A PKCS 11 object that contains a certificate + +This function will import a PKCS 11 certificate to a @code{gnutls_x509_crt_t} +structure. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 2.12.0 +@end deftypefun + +@subheading gnutls_x509_crt_list_import_pkcs11 +@anchor{gnutls_x509_crt_list_import_pkcs11} +@deftypefun {int} {gnutls_x509_crt_list_import_pkcs11} (gnutls_x509_crt_t * @var{certs}, unsigned int @var{cert_max}, gnutls_pkcs11_obj_t * const @var{objs}, unsigned int @var{flags}) +@var{certs}: A list of certificates of type @code{gnutls_x509_crt_t} + +@var{cert_max}: The maximum size of the list + +@var{objs}: A list of PKCS 11 objects + +@var{flags}: 0 for now + +This function will import a PKCS 11 certificate list to a list of +@code{gnutls_x509_crt_t} type. These must not be initialized. + +@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS} (0) is returned, otherwise a +negative error value. + +@strong{Since:} 2.12.0 +@end deftypefun + |