1: =pod
    2: 
    3: =head1 NAME
    4: 
    5: SSL_CTX_set_default_passwd_cb, SSL_CTX_set_default_passwd_cb_userdata - set passwd callback for encrypted PEM file handling
    6: 
    7: =head1 SYNOPSIS
    8: 
    9:  #include <openssl/ssl.h>
   10: 
   11:  void SSL_CTX_set_default_passwd_cb(SSL_CTX *ctx, pem_password_cb *cb);
   12:  void SSL_CTX_set_default_passwd_cb_userdata(SSL_CTX *ctx, void *u);
   13: 
   14:  int pem_passwd_cb(char *buf, int size, int rwflag, void *userdata);
   15: 
   16: =head1 DESCRIPTION
   17: 
   18: SSL_CTX_set_default_passwd_cb() sets the default password callback called
   19: when loading/storing a PEM certificate with encryption.
   20: 
   21: SSL_CTX_set_default_passwd_cb_userdata() sets a pointer to B<userdata> which
   22: will be provided to the password callback on invocation.
   23: 
   24: The pem_passwd_cb(), which must be provided by the application, hands back the
   25: password to be used during decryption. On invocation a pointer to B<userdata>
   26: is provided. The pem_passwd_cb must write the password into the provided buffer
   27: B<buf> which is of size B<size>. The actual length of the password must
   28: be returned to the calling function. B<rwflag> indicates whether the
   29: callback is used for reading/decryption (rwflag=0) or writing/encryption
   30: (rwflag=1).
   31: 
   32: =head1 NOTES
   33: 
   34: When loading or storing private keys, a password might be supplied to
   35: protect the private key. The way this password can be supplied may depend
   36: on the application. If only one private key is handled, it can be practical
   37: to have pem_passwd_cb() handle the password dialog interactively. If several
   38: keys have to be handled, it can be practical to ask for the password once,
   39: then keep it in memory and use it several times. In the last case, the
   40: password could be stored into the B<userdata> storage and the
   41: pem_passwd_cb() only returns the password already stored.
   42: 
   43: When asking for the password interactively, pem_passwd_cb() can use
   44: B<rwflag> to check, whether an item shall be encrypted (rwflag=1).
   45: In this case the password dialog may ask for the same password twice
   46: for comparison in order to catch typos, that would make decryption
   47: impossible.
   48: 
   49: Other items in PEM formatting (certificates) can also be encrypted, it is
   50: however not usual, as certificate information is considered public.
   51: 
   52: =head1 RETURN VALUES
   53: 
   54: SSL_CTX_set_default_passwd_cb() and SSL_CTX_set_default_passwd_cb_userdata()
   55: do not provide diagnostic information.
   56: 
   57: =head1 EXAMPLES
   58: 
   59: The following example returns the password provided as B<userdata> to the
   60: calling function. The password is considered to be a '\0' terminated
   61: string. If the password does not fit into the buffer, the password is
   62: truncated.
   63: 
   64:  int pem_passwd_cb(char *buf, int size, int rwflag, void *password)
   65:  {
   66:   strncpy(buf, (char *)(password), size);
   67:   buf[size - 1] = '\0';
   68:   return(strlen(buf));
   69:  }
   70: 
   71: =head1 SEE ALSO
   72: 
   73: L<ssl(3)|ssl(3)>,
   74: L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>
   75: 
   76: =cut