diff options
author | Nikos Mavrogiannopoulos <nmav@gnutls.org> | 2012-07-21 18:58:51 +0200 |
---|---|---|
committer | Nikos Mavrogiannopoulos <nmav@gnutls.org> | 2012-07-21 18:58:51 +0200 |
commit | b0a1222324dead25954b30f35ef0599523fd1e07 (patch) | |
tree | 2d5d83bc504046feb02d750511ca03865b0942d5 /doc/cha-tokens.texi | |
parent | 52c7cfc6e06c42a48cd4507f42b070df9a5c26ed (diff) | |
download | gnutls-b0a1222324dead25954b30f35ef0599523fd1e07.tar.gz |
more elaborate PIN documentation
Diffstat (limited to 'doc/cha-tokens.texi')
-rw-r--r-- | doc/cha-tokens.texi | 50 |
1 files changed, 41 insertions, 9 deletions
diff --git a/doc/cha-tokens.texi b/doc/cha-tokens.texi index b353a59533..2f2dc19de7 100644 --- a/doc/cha-tokens.texi +++ b/doc/cha-tokens.texi @@ -175,6 +175,7 @@ system, being the @acronym{Gnome Keyring}. @menu * PKCS11 Initialization:: +* Accessing objects that require a PIN:: * Reading objects:: * Writing objects:: * Using a PKCS11 token with TLS:: @@ -194,13 +195,47 @@ module: /usr/lib/opensc-pkcs11.so @end example If you use this file, then there is no need for other initialization in -@acronym{GnuTLS}, except for the PIN and token functions. Those allow retrieving a PIN -when accessing a protected object, such as a private key, as well as probe -the user to insert the token. All the initialization functions are below. +@acronym{GnuTLS}, except for the PIN and token functions (see next section). +However, you may manually initialize the PKCS #11 subsystem if the default +settings are not desirable. @showfuncdesc{gnutls_pkcs11_init} + +Note that PKCS #11 modules must be reinitialized on the child processes +after a @funcintref{fork}. @acronym{GnuTLS} provides @funcref{gnutls_pkcs11_reinit} +to be called for this purpose. + +@showfuncdesc{gnutls_pkcs11_reinit} + +@node Accessing objects that require a PIN +@subsection Accessing objects that require a PIN + +Objects stored in token such as a private keys are typically protected +from access by a PIN or password. This PIN may be required to either read +the object (if allowed) or to perform operations with it. To allow obtaining +the PIN when accessing a protected object, as well as probe +the user to insert the token the following functions allow to set a callback. + @showfuncD{gnutls_pkcs11_set_token_function,gnutls_pkcs11_set_pin_function,gnutls_pkcs11_add_provider,gnutls_pkcs11_get_pin_function} +The callback is of type @funcintref{gnutls_pin_callback_t} and will have as +input the provided userdata, the PIN attempt number, a URL describing the +token, a label describing the object and flags. The PIN must be at most +of @code{pin_max} size and must be copied to pin variable. The function must +return 0 on success or a negative error code otherwise. + +@verbatim +typedef int (*gnutls_pin_callback_t) (void *userdata, int attempt, + const char *token_url, + const char *token_label, + unsigned int flags, + char *pin, size_t pin_max); +@end verbatim + +The flags are of @code{gnutls_pin_flag_t} type and are explained below. + +@showenumdesc{gnutls_pin_flag_t,The @code{gnutls_pin_@-flag_t} enumeration.} + Note that due to limitations of @acronym{PKCS} #11 there are issues when multiple libraries are sharing a module. To avoid this problem GnuTLS uses @acronym{p11-kit} that provides a middleware to control access to resources over the @@ -213,12 +248,6 @@ using functions below. @showfuncE{gnutls_certificate_set_pin_function,gnutls_pubkey_set_pin_function,gnutls_privkey_set_pin_function,gnutls_pkcs11_obj_set_pin_function,gnutls_x509_crt_set_pin_function} -Moreover PKCS #11 modules must be reinitialized on the child processes -after a @funcintref{fork}. @acronym{GnuTLS} provides @funcref{gnutls_pkcs11_reinit} -to be called for this purpose. - -@showfuncdesc{gnutls_pkcs11_reinit} - @node Reading objects @subsection Reading objects @@ -357,6 +386,9 @@ identified by a URL of the form: tpmkey:file=/path/to/file @end verbatim +When objects require a PIN to be accessed the same callbacks as with PKCS #11 +objects are expected (see @ref{Accessing objects that require a PIN}). + @node Key generation @subsection Key generation |