gnutls_pkcs11_set_pin_function(3)

NAME
gnutls_pkcs11_set_pin_function - API function

SYNOPSIS
#include <gnutls/gnutls.h>

void gnutls_pkcs11_set_pin_function(gnutls_pkcs11_pin_callback_t fn, void * userdata);

ARGUMENTS

gnutls_pkcs11_pin_callback_t fn
    The PIN callback

void * userdata
    data to be supplied to callback

DESCRIPTION
This function will set a callback function to be used when a PIN is required for PKCS 11 operations. Callback for PKCS11 PIN entry. The callback provides the PIN code to unlock the token with label 'token_label' in the slot described by 'slot_descr'. The PIN code, as a NUL-terminated ASCII string, should be copied into the 'pin' buffer (of maximum size pin_max), and return 0 to indicate success. Alternatively, the callback may return a negative gnutls error code to indicate failure and cancel PIN entry (in which case, the contents of the 'pin' parameter are ignored). The special error code GNUTLS_E_PKCS11_PIN_SAVE can be returned to tell the caller to save the pin for future use with this token. This will only work if the token is being used with a single &gnutls_pkcs11_privkey_t structure and thread safety is not an issue. When a PIN is required, the callback will be invoked repeatedly (and indefinitely) until either the returned PIN code is correct, the callback returns failure, or the token refuses login (e.g. when the token is locked due to too many incorrect PINs!). For the first such invocation, the 'attempt' counter will have value zero; it will increase by one for each subsequent attempt.

RETURNS
On success, GNUTLS_E_SUCCESS is returned, otherwise a negative error value.

REPORTING BUGS
Report bugs to <bug-gnutls@gnu.org>. GnuTLS home page: http://www.gnu.org/software/gnutls/ General help using GNU software: http://www.gnu.org/gethelp/

COPYRIGHT
Copyright © 2008 Free Software Foundation.
Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved.

SEE ALSO
The full documentation for gnutls is maintained as a Texinfo manual. If the info and gnutls programs are properly installed at your site, the command

    info gnutls

should give you access to the complete manual.