doc/manpages/gnutls_pkcs11_set_pin_function.3

   1 .\" DO NOT MODIFY THIS FILE!  It was generated by gdoc.
   2 .TH "gnutls_pkcs11_set_pin_function" 3 "2.12.6.1" "gnutls" "gnutls"
   3 .SH NAME
   4 gnutls_pkcs11_set_pin_function \- API function
   5 .SH SYNOPSIS
   6 .B #include <gnutls/gnutls.h>
   7 .sp
   8 .BI "void gnutls_pkcs11_set_pin_function(gnutls_pkcs11_pin_callback_t " fn ", void * " userdata ");"
   9 .SH ARGUMENTS
  10 .IP "gnutls_pkcs11_pin_callback_t fn" 12
  11 The PIN callback
  12 .IP "void * userdata" 12
  13 data to be supplied to callback
  14 .SH "DESCRIPTION"
  15 This function will set a callback function to be used when a PIN
  16 is required for PKCS 11 operations.
  17
  18 Callback for PKCS\fB11\fP PIN entry.  The callback provides the PIN code
  19 to unlock the token with label 'token_label', specified by the URL
  20 'token_url'.
  21
  22 The PIN code, as a NUL\-terminated ASCII string, should be copied
  23 into the 'pin' buffer (of maximum size pin_max), and
  24 return 0 to indicate success. Alternatively, the callback may
  25 return a negative gnutls error code to indicate failure and cancel
  26 PIN entry (in which case, the contents of the 'pin' parameter are ignored).
  27
  28 When a PIN is required, the callback will be invoked repeatedly
  29 (and indefinitely) until either the returned PIN code is correct,
  30 the callback returns failure, or the token refuses login (e.g. when
  31 the token is locked due to too many incorrect PINs!).  For the
  32 first such invocation, the 'attempt' counter will have value zero;
  33 it will increase by one for each subsequent attempt.
  34 .SH "RETURNS"
  35 On success, \fBGNUTLS_E_SUCCESS\fP is returned, otherwise a
  36 negative error value.
  37 .SH "REPORTING BUGS"
  38 Report bugs to <bug-gnutls@gnu.org>.
  39 GnuTLS home page: http://www.gnu.org/software/gnutls/
  40 General help using GNU software: http://www.gnu.org/gethelp/
  41 .SH COPYRIGHT
  42 Copyright \(co 2008 Free Software Foundation.
  43 .br
  44 Copying and distribution of this file, with or without modification,
  45 are permitted in any medium without royalty provided the copyright
  46 notice and this notice are preserved.
  47 .SH "SEE ALSO"
  48 The full documentation for
  49 .B gnutls
  50 is maintained as a Texinfo manual.  If the
  51 .B info
  52 and
  53 .B gnutls
  54 programs are properly installed at your site, the command
  55 .IP
  56 .B info gnutls
  57 .PP
  58 should give you access to the complete manual.