GnuTLS API Reference Manual | ||||
---|---|---|---|---|
Top | Description |
#define GNUTLS_PKCS11_MAX_PIN_LEN int (*gnutls_pkcs11_token_callback_t) (void *const userdata
,const char *const label
,unsigned retry
); #define GNUTLS_PKCS11_PIN_FINAL_TRY #define GNUTLS_PKCS11_PIN_COUNT_LOW struct gnutls_pkcs11_obj_st; typedef gnutls_pkcs11_obj_t; #define GNUTLS_PKCS11_FLAG_MANUAL #define GNUTLS_PKCS11_FLAG_AUTO int gnutls_pkcs11_init (unsigned int flags
,const char *deprecated_config_file
); void gnutls_pkcs11_deinit (void
); void gnutls_pkcs11_set_token_function (gnutls_pkcs11_token_callback_t fn
,void *userdata
); void gnutls_pkcs11_set_pin_function (gnutls_pin_callback_t fn
,void *userdata
); int gnutls_pkcs11_add_provider (const char *name
,const char *params
); int gnutls_pkcs11_obj_init (gnutls_pkcs11_obj_t *obj
); #define GNUTLS_PKCS11_OBJ_FLAG_LOGIN #define GNUTLS_PKCS11_OBJ_FLAG_MARK_TRUSTED #define GNUTLS_PKCS11_OBJ_FLAG_MARK_SENSITIVE int gnutls_pkcs11_obj_import_url (gnutls_pkcs11_obj_t obj
,const char *url
,unsigned int flags
); int gnutls_pkcs11_obj_export_url (gnutls_pkcs11_obj_t obj
,gnutls_pkcs11_url_type_t detailed
,char **url
); void gnutls_pkcs11_obj_deinit (gnutls_pkcs11_obj_t obj
); int gnutls_pkcs11_obj_export (gnutls_pkcs11_obj_t obj
,void *output_data
,size_t *output_data_size
); int gnutls_pkcs11_copy_x509_crt (const char *token_url
,gnutls_x509_crt_t crt
,const char *label
,unsigned int flags
); int gnutls_pkcs11_copy_x509_privkey (const char *token_url
,gnutls_x509_privkey_t key
,const char *label
,unsigned int key_usage
,unsigned int flags
); int gnutls_pkcs11_delete_url (const char *object_url
,unsigned int flags
); enum gnutls_pkcs11_obj_info_t; int gnutls_pkcs11_obj_get_info (gnutls_pkcs11_obj_t crt
,gnutls_pkcs11_obj_info_t itype
,void *output
,size_t *output_size
); enum gnutls_pkcs11_obj_attr_t; enum gnutls_pkcs11_token_info_t; enum gnutls_pkcs11_obj_type_t; int gnutls_pkcs11_token_get_url (unsigned int seq
,gnutls_pkcs11_url_type_t detailed
,char **url
); int gnutls_pkcs11_token_get_info (const char *url
,gnutls_pkcs11_token_info_t ttype
,void *output
,size_t *output_size
); #define GNUTLS_PKCS11_TOKEN_HW int gnutls_pkcs11_token_get_flags (const char *url
,unsigned int *flags
); int gnutls_pkcs11_obj_list_import_url (gnutls_pkcs11_obj_t *p_list
,unsigned int *const n_list
,const char *url
,gnutls_pkcs11_obj_attr_t attrs
,unsigned int flags
); int gnutls_x509_crt_import_pkcs11 (gnutls_x509_crt_t crt
,gnutls_pkcs11_obj_t pkcs11_crt
); int gnutls_x509_crt_import_pkcs11_url (gnutls_x509_crt_t crt
,const char *url
,unsigned int flags
); gnutls_pkcs11_obj_type_t gnutls_pkcs11_obj_get_type (gnutls_pkcs11_obj_t obj
); const char * gnutls_pkcs11_type_get_name (gnutls_pkcs11_obj_type_t type
); int gnutls_x509_crt_list_import_pkcs11 (gnutls_x509_crt_t *certs
,unsigned int cert_max
,gnutls_pkcs11_obj_t * const objs
,unsigned int flags
); int gnutls_pkcs11_privkey_init (gnutls_pkcs11_privkey_t *key
); void gnutls_pkcs11_privkey_deinit (gnutls_pkcs11_privkey_t key
); int gnutls_pkcs11_privkey_get_pk_algorithm (gnutls_pkcs11_privkey_t key
,unsigned int *bits
); int gnutls_pkcs11_privkey_get_info (gnutls_pkcs11_privkey_t pkey
,gnutls_pkcs11_obj_info_t itype
,void *output
,size_t *output_size
); int gnutls_pkcs11_privkey_import_url (gnutls_pkcs11_privkey_t pkey
,const char *url
,unsigned int flags
); int gnutls_pkcs11_privkey_export_url (gnutls_pkcs11_privkey_t key
,gnutls_pkcs11_url_type_t detailed
,char **url
);
int (*gnutls_pkcs11_token_callback_t) (void *const userdata
,const char *const label
,unsigned retry
);
Token callback function. The callback will be used to ask the user to re-insert the token with given (null terminated) label. The callback should return zero if token has been inserted by user and a negative error code otherwise. It might be called multiple times if the token is not detected and the retry counter will be increased.
|
user-controlled data from gnutls_pkcs11_set_token_function() . |
|
token label. |
|
retry counter, initially 0. |
Returns : |
GNUTLS_E_SUCCESS (0) on success or a negative error code
on error. |
Since 2.12.0
#define GNUTLS_PKCS11_FLAG_AUTO 1 /* Automatically load libraries by reading /etc/gnutls/pkcs11.conf */
int gnutls_pkcs11_init (unsigned int flags
,const char *deprecated_config_file
);
This function will initialize the PKCS 11 subsystem in gnutls. It will
read configuration files if GNUTLS_PKCS11_FLAG_AUTO
is used or allow
you to independently load PKCS 11 modules using gnutls_pkcs11_add_provider()
if GNUTLS_PKCS11_FLAG_MANUAL
is specified.
Normally you don't need to call this function since it is being called
by gnutls_global_init()
using the GNUTLS_PKCS11_FLAG_AUTO
. If other option
is required then it must be called before it.
|
GNUTLS_PKCS11_FLAG_MANUAL or GNUTLS_PKCS11_FLAG_AUTO
|
|
either NULL or the location of a deprecated configuration file |
Returns : |
On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a
negative error value. |
Since 2.12.0
void gnutls_pkcs11_deinit (void
);
This function will deinitialize the PKCS 11 subsystem in gnutls.
Since 2.12.0
void gnutls_pkcs11_set_token_function (gnutls_pkcs11_token_callback_t fn
,void *userdata
);
This function will set a callback function to be used when a token needs to be inserted to continue PKCS 11 operations.
|
The token callback |
|
data to be supplied to callback |
Since 2.12.0
void gnutls_pkcs11_set_pin_function (gnutls_pin_callback_t fn
,void *userdata
);
This function will set a callback function to be used when a PIN is
required for PKCS 11 operations. See
gnutls_pin_callback_t()
on how the callback should behave.
|
The PIN callback, a gnutls_pin_callback_t() function. |
|
data to be supplied to callback |
Since 2.12.0
int gnutls_pkcs11_add_provider (const char *name
,const char *params
);
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.
|
The filename of the module |
|
should be NULL |
Returns : |
On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a
negative error value. |
Since 2.12.0
int gnutls_pkcs11_obj_init (gnutls_pkcs11_obj_t *obj
);
This function will initialize a pkcs11 certificate structure.
|
The structure to be initialized |
Returns : |
On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a
negative error value. |
Since 2.12.0
#define GNUTLS_PKCS11_OBJ_FLAG_LOGIN (1<<0) /* force login in the token for the operation */
#define GNUTLS_PKCS11_OBJ_FLAG_MARK_TRUSTED (1<<1) /* object marked as trusted */
#define GNUTLS_PKCS11_OBJ_FLAG_MARK_SENSITIVE (1<<2) /* object marked as sensitive (unexportable) */
int gnutls_pkcs11_obj_import_url (gnutls_pkcs11_obj_t obj
,const char *url
,unsigned int flags
);
This function will "import" a PKCS 11 URL identifying an object (e.g. certificate) to the gnutls_pkcs11_obj_t structure. This does not involve any parsing (such as X.509 or OpenPGP) since the gnutls_pkcs11_obj_t is format agnostic. Only data are transferred.
|
The structure to store the object |
|
a PKCS 11 url identifying the key |
|
One of GNUTLS_PKCS11_OBJ_* flags |
Returns : |
On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a
negative error value. |
Since 2.12.0
int gnutls_pkcs11_obj_export_url (gnutls_pkcs11_obj_t obj
,gnutls_pkcs11_url_type_t detailed
,char **url
);
This function will export a URL identifying the given certificate.
|
Holds the PKCS 11 certificate |
|
non zero if a detailed URL is required |
|
will contain an allocated url |
Returns : |
On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a
negative error value. |
Since 2.12.0
void gnutls_pkcs11_obj_deinit (gnutls_pkcs11_obj_t obj
);
This function will deinitialize a certificate structure.
|
The structure to be initialized |
Since 2.12.0
int gnutls_pkcs11_obj_export (gnutls_pkcs11_obj_t obj
,void *output_data
,size_t *output_data_size
);
This function will export the PKCS11 object data. It is normal for
data to be inaccesible and in that case GNUTLS_E_INVALID_REQUEST
will be returned.
If the buffer provided is not long enough to hold the output, then *output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will be returned.
If the structure is PEM encoded, it will have a header of "BEGIN CERTIFICATE".
|
Holds the object |
|
will contain a certificate PEM or DER encoded |
|
holds the size of output_data (and will be replaced by the actual size of parameters) |
Returns : |
In case of failure a negative error code will be
returned, and GNUTLS_E_SUCCESS (0) on success. |
Since 2.12.0
int gnutls_pkcs11_copy_x509_crt (const char *token_url
,gnutls_x509_crt_t crt
,const char *label
,unsigned int flags
);
This function will copy a certificate into a PKCS 11 token specified by a URL. The certificate can be marked as trusted or not.
|
A PKCS 11 URL specifying a token |
|
A certificate |
|
A name to be used for the stored data |
|
One of GNUTLS_PKCS11_OBJ_FLAG_* |
Returns : |
On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a
negative error value. |
Since 2.12.0
int gnutls_pkcs11_copy_x509_privkey (const char *token_url
,gnutls_x509_privkey_t key
,const char *label
,unsigned int key_usage
,unsigned int flags
);
This function will copy a private key into a PKCS 11 token specified by
a URL. It is highly recommended flags to contain GNUTLS_PKCS11_OBJ_FLAG_MARK_SENSITIVE
unless there is a strong reason not to.
|
A PKCS 11 URL specifying a token |
|
A private key |
|
A name to be used for the stored data |
|
One of GNUTLS_KEY_* |
|
One of GNUTLS_PKCS11_OBJ_* flags |
Returns : |
On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a
negative error value. |
Since 2.12.0
int gnutls_pkcs11_delete_url (const char *object_url
,unsigned int flags
);
This function will delete objects matching the given URL. Note that not all tokens support the delete operation.
|
The URL of the object to delete. |
|
One of GNUTLS_PKCS11_OBJ_* flags |
Returns : |
On success, the number of objects deleted is returned, otherwise a negative error value. |
Since 2.12.0
typedef enum { GNUTLS_PKCS11_OBJ_ID_HEX = 1, GNUTLS_PKCS11_OBJ_LABEL, GNUTLS_PKCS11_OBJ_TOKEN_LABEL, GNUTLS_PKCS11_OBJ_TOKEN_SERIAL, GNUTLS_PKCS11_OBJ_TOKEN_MANUFACTURER, GNUTLS_PKCS11_OBJ_TOKEN_MODEL, GNUTLS_PKCS11_OBJ_ID, /* the pkcs11 provider library info */ GNUTLS_PKCS11_OBJ_LIBRARY_VERSION, GNUTLS_PKCS11_OBJ_LIBRARY_DESCRIPTION, GNUTLS_PKCS11_OBJ_LIBRARY_MANUFACTURER } gnutls_pkcs11_obj_info_t;
Enumeration of several object information types.
The object ID in hex. | |
The object label. | |
The token's label. | |
The token's serial number. | |
The token's manufacturer. | |
The token's model. | |
The object ID. | |
The library's used to access the object version. | |
The library's used to access the object description (name). | |
The library's used to access the object manufacturer name. |
int gnutls_pkcs11_obj_get_info (gnutls_pkcs11_obj_t crt
,gnutls_pkcs11_obj_info_t itype
,void *output
,size_t *output_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 it returns null terminated string
although output_size
contains the size of the actual data only.
|
should contain a gnutls_pkcs11_obj_t structure |
|
Denotes the type of information requested |
|
where output will be stored |
|
contains the maximum size of the output and will be overwritten with actual |
Returns : |
GNUTLS_E_SUCCESS (0) on success or a negative error code on error. |
Since 2.12.0
typedef enum { GNUTLS_PKCS11_OBJ_ATTR_CRT_ALL = 1, /* all certificates */ GNUTLS_PKCS11_OBJ_ATTR_CRT_TRUSTED, /* certificates marked as trusted */ GNUTLS_PKCS11_OBJ_ATTR_CRT_WITH_PRIVKEY, /* certificates with corresponding private key */ GNUTLS_PKCS11_OBJ_ATTR_PUBKEY, /* public keys */ GNUTLS_PKCS11_OBJ_ATTR_PRIVKEY, /* private keys */ GNUTLS_PKCS11_OBJ_ATTR_ALL /* everything! */ } gnutls_pkcs11_obj_attr_t;
Enumeration of several attributes for object enumeration.
Specify all certificates. | |
Specify all certificates marked as trusted. | |
Specify all certificates with a corresponding private key. | |
Specify all public keys. | |
Specify all private keys. | |
Specify all objects. |
typedef enum { GNUTLS_PKCS11_TOKEN_LABEL, GNUTLS_PKCS11_TOKEN_SERIAL, GNUTLS_PKCS11_TOKEN_MANUFACTURER, GNUTLS_PKCS11_TOKEN_MODEL } gnutls_pkcs11_token_info_t;
Enumeration of types for retrieving token information.
typedef enum { GNUTLS_PKCS11_OBJ_UNKNOWN, GNUTLS_PKCS11_OBJ_X509_CRT, GNUTLS_PKCS11_OBJ_PUBKEY, GNUTLS_PKCS11_OBJ_PRIVKEY, GNUTLS_PKCS11_OBJ_SECRET_KEY, GNUTLS_PKCS11_OBJ_DATA } gnutls_pkcs11_obj_type_t;
Enumeration of object types.
int gnutls_pkcs11_token_get_url (unsigned int seq
,gnutls_pkcs11_url_type_t detailed
,char **url
);
This function will return the URL for each token available
in system. The url has to be released using gnutls_free()
|
sequence number starting from 0 |
|
non zero if a detailed URL is required |
|
will contain an allocated url |
Returns : |
On success, GNUTLS_E_SUCCESS (0) is returned,
GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE if the sequence number
exceeds the available tokens, otherwise a negative error value. |
Since 2.12.0
int gnutls_pkcs11_token_get_info (const char *url
,gnutls_pkcs11_token_info_t ttype
,void *output
,size_t *output_size
);
This function will return information about the PKCS 11 token such as the label, id, etc.
|
should contain a PKCS 11 URL |
|
Denotes the type of information requested |
|
where output will be stored |
|
contains the maximum size of the output and will be overwritten with actual |
Returns : |
GNUTLS_E_SUCCESS (0) on success or a negative error code
on error. |
Since 2.12.0
int gnutls_pkcs11_token_get_flags (const char *url
,unsigned int *flags
);
This function will return information about the PKCS 11 token flags.
The flags from the gnutls_pkcs11_token_info_t
enumeration.
|
should contain a PKCS 11 URL |
|
The output flags (GNUTLS_PKCS11_TOKEN_*) |
Returns : |
GNUTLS_E_SUCCESS (0) on success or a negative error code on error. |
Since 2.12.0
int gnutls_pkcs11_obj_list_import_url (gnutls_pkcs11_obj_t *p_list
,unsigned int *const n_list
,const char *url
,gnutls_pkcs11_obj_attr_t attrs
,unsigned int flags
);
This function will initialize and set values to an object list by using all objects identified by a PKCS 11 URL.
|
An uninitialized object list (may be NULL) |
|
initially should hold the maximum size of the list. Will contain the actual size. |
|
A PKCS 11 url identifying a set of objects |
|
Attributes of type gnutls_pkcs11_obj_attr_t that can be used to limit output |
|
One of GNUTLS_PKCS11_OBJ_* flags |
Returns : |
On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a
negative error value. |
Since 2.12.0
int gnutls_x509_crt_import_pkcs11 (gnutls_x509_crt_t crt
,gnutls_pkcs11_obj_t pkcs11_crt
);
This function will import a PKCS 11 certificate to a gnutls_x509_crt_t structure.
|
A certificate of type gnutls_x509_crt_t |
|
A PKCS 11 object that contains a certificate |
Returns : |
On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a
negative error value. |
Since 2.12.0
int gnutls_x509_crt_import_pkcs11_url (gnutls_x509_crt_t crt
,const char *url
,unsigned int flags
);
This function will import a PKCS 11 certificate directly from a token without involving the gnutls_pkcs11_obj_t structure. This function will fail if the certificate stored is not of X.509 type.
|
A certificate of type gnutls_x509_crt_t |
|
A PKCS 11 url |
|
One of GNUTLS_PKCS11_OBJ_* flags |
Returns : |
On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a
negative error value. |
Since 2.12.0
gnutls_pkcs11_obj_type_t gnutls_pkcs11_obj_get_type (gnutls_pkcs11_obj_t obj
);
This function will return the type of the certificate being stored in the structure.
|
Holds the PKCS 11 object |
Returns : |
The type of the certificate. |
Since 2.12.0
const char * gnutls_pkcs11_type_get_name (gnutls_pkcs11_obj_type_t type
);
This function will return a human readable description of the
PKCS11 object type obj
. It will return "Unknown" for unknown
types.
|
Holds the PKCS 11 object type, a gnutls_pkcs11_obj_type_t. |
Returns : |
human readable string labeling the PKCS11 object type
type . |
Since 2.12.0
int gnutls_x509_crt_list_import_pkcs11 (gnutls_x509_crt_t *certs
,unsigned int cert_max
,gnutls_pkcs11_obj_t * const objs
,unsigned int flags
);
This function will import a PKCS 11 certificate list to a list of gnutls_x509_crt_t structure. These must not be initialized.
|
A list of certificates of type gnutls_x509_crt_t |
|
The maximum size of the list |
|
A list of PKCS 11 objects |
|
0 for now |
Returns : |
On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a
negative error value. |
Since 2.12.0
int gnutls_pkcs11_privkey_init (gnutls_pkcs11_privkey_t *key
);
This function will initialize an private key structure.
|
The structure to be initialized |
Returns : |
On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a
negative error value. |
void gnutls_pkcs11_privkey_deinit (gnutls_pkcs11_privkey_t key
);
This function will deinitialize a private key structure.
|
The structure to be initialized |
int gnutls_pkcs11_privkey_get_pk_algorithm (gnutls_pkcs11_privkey_t key
,unsigned int *bits
);
This function will return the public key algorithm of a private key.
|
should contain a gnutls_pkcs11_privkey_t structure |
|
if bits is non null it will hold the size of the parameters' in bits |
Returns : |
a member of the gnutls_pk_algorithm_t enumeration on success, or a negative error code on error. |
int gnutls_pkcs11_privkey_get_info (gnutls_pkcs11_privkey_t pkey
,gnutls_pkcs11_obj_info_t itype
,void *output
,size_t *output_size
);
This function will return information about the PKCS 11 private key such as the label, id as well as token information where the key is stored. When output is text it returns null terminated string although output_size contains the size of the actual data only.
|
should contain a gnutls_pkcs11_privkey_t structure |
|
Denotes the type of information requested |
|
where output will be stored |
|
contains the maximum size of the output and will be overwritten with actual |
Returns : |
GNUTLS_E_SUCCESS (0) on success or a negative error code on error. |
int gnutls_pkcs11_privkey_import_url (gnutls_pkcs11_privkey_t pkey
,const char *url
,unsigned int flags
);
This function will "import" a PKCS 11 URL identifying a private key to the gnutls_pkcs11_privkey_t structure. In reality since in most cases keys cannot be exported, the private key structure is being associated with the available operations on the token.
|
The structure to store the parsed key |
|
a PKCS 11 url identifying the key |
|
sequence of GNUTLS_PKCS_PRIVKEY_* |
Returns : |
On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a
negative error value. |
int gnutls_pkcs11_privkey_export_url (gnutls_pkcs11_privkey_t key
,gnutls_pkcs11_url_type_t detailed
,char **url
);
This function will export a URL identifying the given key.
|
Holds the PKCS 11 key |
|
non zero if a detailed URL is required |
|
will contain an allocated url |
Returns : |
On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a
negative error value. |