Adding upstream version 3.7.9.upstream/3.7.9upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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
+