lib/libssl/man/SSL_CTX_set_default_passwd_cb.3

   1 .\" $OpenBSD: SSL_CTX_set_default_passwd_cb.3,v 1.7 2018/04/02 02:06:14 schwarze Exp $
   2 .\" full merge up to: OpenSSL 9b86974e Aug 17 15:21:33 2015 -0400
   3 .\" selective merge up to: OpenSSL 2947af32 Nov 19 00:10:05 2016 +0100
   4 .\"
   5 .\" This file was written by Lutz Jaenicke <jaenicke@openssl.org>
   6 .\" and Christian Heimes <cheimes@redhat.com>.
   7 .\" Copyright (c) 2000, 2001, 2016 The OpenSSL Project.  All rights reserved.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\"
  13 .\" 1. Redistributions of source code must retain the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer.
  15 .\"
  16 .\" 2. Redistributions in binary form must reproduce the above copyright
  17 .\"    notice, this list of conditions and the following disclaimer in
  18 .\"    the documentation and/or other materials provided with the
  19 .\"    distribution.
  20 .\"
  21 .\" 3. All advertising materials mentioning features or use of this
  22 .\"    software must display the following acknowledgment:
  23 .\"    "This product includes software developed by the OpenSSL Project
  24 .\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
  25 .\"
  26 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
  27 .\"    endorse or promote products derived from this software without
  28 .\"    prior written permission. For written permission, please contact
  29 .\"    openssl-core@openssl.org.
  30 .\"
  31 .\" 5. Products derived from this software may not be called "OpenSSL"
  32 .\"    nor may "OpenSSL" appear in their names without prior written
  33 .\"    permission of the OpenSSL Project.
  34 .\"
  35 .\" 6. Redistributions of any form whatsoever must retain the following
  36 .\"    acknowledgment:
  37 .\"    "This product includes software developed by the OpenSSL Project
  38 .\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
  39 .\"
  40 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
  41 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  42 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  43 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
  44 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  45 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  46 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  47 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  48 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  49 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  50 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  51 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
  52 .\"
  53 .Dd $Mdocdate: April 2 2018 $
  54 .Dt SSL_CTX_SET_DEFAULT_PASSWD_CB 3
  55 .Os
  56 .Sh NAME
  57 .Nm SSL_CTX_set_default_passwd_cb ,
  58 .Nm SSL_CTX_set_default_passwd_cb_userdata ,
  59 .Nm SSL_CTX_get_default_passwd_cb ,
  60 .Nm SSL_CTX_get_default_passwd_cb_userdata ,
  61 .Nm pem_password_cb
  62 .Nd set or get passwd callback for encrypted PEM file handling
  63 .Sh SYNOPSIS
  64 .In openssl/ssl.h
  65 .Ft void
  66 .Fn SSL_CTX_set_default_passwd_cb "SSL_CTX *ctx" "pem_password_cb *cb"
  67 .Ft void
  68 .Fn SSL_CTX_set_default_passwd_cb_userdata "SSL_CTX *ctx" "void *u"
  69 .Ft pem_password_cb *
  70 .Fn SSL_CTX_get_default_passwd_cb "SSL_CTX *ctx"
  71 .Ft void *
  72 .Fn SSL_CTX_get_default_passwd_cb_userdata "SSL_CTX *ctx"
  73 .In openssl/pem.h
  74 .Ft typedef int
  75 .Fn pem_password_cb "char *buf" "int size" "int rwflag" "void *userdata"
  76 .Sh DESCRIPTION
  77 .Fn SSL_CTX_set_default_passwd_cb
  78 sets the default password callback called when loading/storing a PEM
  79 certificate with encryption.
  80 .Pp
  81 .Fn SSL_CTX_set_default_passwd_cb_userdata
  82 sets a pointer to userdata
  83 .Fa u
  84 which will be provided to the password callback on invocation.
  85 .Pp
  86 The
  87 password callback
  88 .Fa cb ,
  89 which must be provided by the application,
  90 hands back the password to be used during decryption.
  91 On invocation a pointer to
  92 .Fa userdata
  93 is provided.
  94 The password callback must write the password into the provided buffer
  95 .Fa buf
  96 which is of size
  97 .Fa size .
  98 The actual length of the password must be returned to the calling function.
  99 .Fa rwflag
 100 indicates whether the callback is used for reading/decryption
 101 .Pq Fa rwflag No = 0
 102 or writing/encryption
 103 .Pq Fa rwflag No = 1 .
 104 .Pp
 105 When loading or storing private keys, a password might be supplied to protect
 106 the private key.
 107 The way this password can be supplied may depend on the application.
 108 If only one private key is handled, it can be practical to have the
 109 callback handle the password dialog interactively.
 110 If several keys have to be handled, it can be practical to ask for the password
 111 once, then keep it in memory and use it several times.
 112 In the last case, the password could be stored into the
 113 .Fa userdata
 114 storage and the callback only returns the password already stored.
 115 .Pp
 116 When asking for the password interactively, the callback can use
 117 .Fa rwflag
 118 to check whether an item shall be encrypted
 119 .Pq Fa rwflag No = 1 .
 120 In this case the password dialog may ask for the same password twice for
 121 comparison in order to catch typos which would make decryption impossible.
 122 .Pp
 123 Other items in PEM formatting (certificates) can also be encrypted; it is
 124 however atypical, as certificate information is considered public.
 125 .Sh RETURN VALUES
 126 .Fn SSL_CTX_get_default_passwd_cb
 127 returns a function pointer to the password callback currently set in
 128 .Fa ctx ,
 129 or
 130 .Dv NULL
 131 if none is set.
 132 .Pp
 133 .Fn SSL_CTX_get_default_passwd_cb_userdata
 134 returns a pointer to the userdata currently set in
 135 .Fa ctx ,
 136 or
 137 .Dv NULL
 138 if none is set.
 139 .Sh EXAMPLES
 140 The following example returns the password provided as
 141 .Fa userdata
 142 to the calling function.
 143 The password is considered to be a
 144 .Sq \e0
 145 terminated string.
 146 If the password does not fit into the buffer, the password is truncated.
 147 .Bd -literal
 148 int pem_passwd_cb(char *buf, int size, int rwflag, void *password)
 149 {
 150         strncpy(buf, (char *)password, size);
 151         buf[size - 1] = '\e0';
 152         return strlen(buf);
 153 }
 154 .Ed
 155 .Sh SEE ALSO
 156 .Xr ssl 3 ,
 157 .Xr SSL_CTX_use_certificate 3
 158 .Sh HISTORY
 159 .Fn SSL_CTX_set_default_passwd_cb
 160 first appeared in SSLeay 0.6.2 and has been available since
 161 .Ox 2.4 .
 162 .Pp
 163 .Fn SSL_CTX_set_default_passwd_cb_userdata
 164 first appeared in OpenSSL 0.9.4 and has been available since
 165 .Ox 2.6 .
 166 .Pp
 167 .Fn SSL_CTX_get_default_passwd_cb
 168 and
 169 .Fn SSL_CTX_get_default_passwd_cb_userdata
 170 first appeared in OpenSSL 1.1.0 and have been available since
 171 .Ox 6.3 .