@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_SENSITIVE} , @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_SENSITIVE} , @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. It is highly recommended flags to contain @code{GNUTLS_PKCS11_OBJ_FLAG_MARK_SENSITIVE} 

unless there is a strong reason not to.

@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. It is highly recommended flags to contain @code{GNUTLS_PKCS11_OBJ_FLAG_MARK_SENSITIVE} 

unless there is a strong reason not to.

@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 retuned. 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 retuned. 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 retuned. 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 inaccesible 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 inaccesible 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 inaccesible 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 and will be overwritten with actual

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 it returns null terminated string

although  @code{output_size} contains the size of the actual data only.

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_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.

It is highly recommended flags to contain @code{GNUTLS_PKCS11_OBJ_FLAG_MARK_SENSITIVE} 

unless there is a strong reason not to.

@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}