sync code with last improvements from OpenBSD
This commit is contained in:
parent
0726fd4247
commit
ba37adff3d
GPG key ID:
F42C07F07E2E35B7
22 changed files with 251 additions and 150 deletions
|
|
@ -1,8 +1,25 @@
|
|||
.\" $OpenBSD: SSL_CTX_set_default_passwd_cb.3,v 1.7 2018/04/02 02:06:14 schwarze Exp $
|
||||
.\" $OpenBSD: SSL_CTX_set_default_passwd_cb.3,v 1.9 2023/09/19 09:40:35 schwarze Exp $
|
||||
.\" full merge up to: OpenSSL 9b86974e Aug 17 15:21:33 2015 -0400
|
||||
.\" selective merge up to: OpenSSL 2947af32 Nov 19 00:10:05 2016 +0100
|
||||
.\" selective merge up to: OpenSSL 18bad535 Apr 9 15:13:55 2019 +0100
|
||||
.\"
|
||||
.\" This file was written by Lutz Jaenicke <jaenicke@openssl.org>
|
||||
.\" This file is a derived work.
|
||||
.\" The changes are covered by the following Copyright and license:
|
||||
.\"
|
||||
.\" Copyright (c) 2023 Ingo Schwarze <schwarze@openbsd.org>
|
||||
.\"
|
||||
.\" Permission to use, copy, modify, and distribute this software for any
|
||||
.\" purpose with or without fee is hereby granted, provided that the above
|
||||
.\" copyright notice and this permission notice appear in all copies.
|
||||
.\"
|
||||
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
|
||||
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
|
||||
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
|
||||
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
||||
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
||||
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
|
||||
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
.\"
|
||||
.\" The original file was written by Lutz Jaenicke <jaenicke@openssl.org>
|
||||
.\" and Christian Heimes <cheimes@redhat.com>.
|
||||
.\" Copyright (c) 2000, 2001, 2016 The OpenSSL Project. All rights reserved.
|
||||
.\"
|
||||
|
|
@ -50,75 +67,95 @@
|
|||
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
|
||||
.\" OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||
.\"
|
||||
.Dd $Mdocdate: April 2 2018 $
|
||||
.Dd $Mdocdate: September 19 2023 $
|
||||
.Dt SSL_CTX_SET_DEFAULT_PASSWD_CB 3
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm SSL_CTX_set_default_passwd_cb ,
|
||||
.Nm SSL_CTX_set_default_passwd_cb_userdata ,
|
||||
.Nm SSL_CTX_get_default_passwd_cb ,
|
||||
.Nm SSL_CTX_get_default_passwd_cb_userdata ,
|
||||
.Nm pem_password_cb
|
||||
.Nm SSL_CTX_get_default_passwd_cb_userdata
|
||||
.Nd set or get passwd callback for encrypted PEM file handling
|
||||
.Sh SYNOPSIS
|
||||
.In openssl/ssl.h
|
||||
.Ft void
|
||||
.Fn SSL_CTX_set_default_passwd_cb "SSL_CTX *ctx" "pem_password_cb *cb"
|
||||
.Ft void
|
||||
.Fn SSL_CTX_set_default_passwd_cb_userdata "SSL_CTX *ctx" "void *u"
|
||||
.Fn SSL_CTX_set_default_passwd_cb_userdata "SSL_CTX *ctx" "void *userdata"
|
||||
.Ft pem_password_cb *
|
||||
.Fn SSL_CTX_get_default_passwd_cb "SSL_CTX *ctx"
|
||||
.Ft void *
|
||||
.Fn SSL_CTX_get_default_passwd_cb_userdata "SSL_CTX *ctx"
|
||||
.In openssl/pem.h
|
||||
.Ft typedef int
|
||||
.Fn pem_password_cb "char *buf" "int size" "int rwflag" "void *userdata"
|
||||
.Sh DESCRIPTION
|
||||
.Fn SSL_CTX_set_default_passwd_cb
|
||||
sets the default password callback called when loading/storing a PEM
|
||||
certificate with encryption.
|
||||
sets the password callback for loading a certificate or private key
|
||||
from encrypted PEM format.
|
||||
In particular, the callback is used by
|
||||
.Xr SSL_CTX_use_certificate_file 3 ,
|
||||
.Xr SSL_use_certificate_file 3 ,
|
||||
.Xr SSL_CTX_use_certificate_chain_file 3 ,
|
||||
.Xr SSL_use_certificate_chain_file 3 ,
|
||||
.Xr SSL_CTX_use_certificate_chain_mem 3 ,
|
||||
.Xr SSL_CTX_use_PrivateKey_file 3 ,
|
||||
.Xr SSL_use_PrivateKey_file 3 ,
|
||||
.Xr SSL_CTX_use_RSAPrivateKey_file 3 ,
|
||||
and
|
||||
.Xr SSL_use_RSAPrivateKey_file 3 .
|
||||
.Pp
|
||||
The function pointer type of the
|
||||
.Fa cb
|
||||
argument is documented in the
|
||||
.Xr pem_password_cb 3
|
||||
manual page.
|
||||
If
|
||||
.Fn SSL_CTX_set_default_passwd_cb
|
||||
is not called on
|
||||
.Fa ctx
|
||||
or if it is called with a
|
||||
.Fa cb
|
||||
argument of
|
||||
.Dv NULL ,
|
||||
.Xr PEM_def_callback 3
|
||||
is used instead.
|
||||
.Pp
|
||||
.Fn SSL_CTX_set_default_passwd_cb_userdata
|
||||
sets a pointer to userdata
|
||||
.Fa u
|
||||
sets a pointer to the
|
||||
.Fa userdata
|
||||
which will be provided to the password callback on invocation.
|
||||
.Pp
|
||||
The
|
||||
password callback
|
||||
.Fa cb ,
|
||||
which must be provided by the application,
|
||||
hands back the password to be used during decryption.
|
||||
On invocation a pointer to
|
||||
.Fa userdata
|
||||
is provided.
|
||||
The password callback must write the password into the provided buffer
|
||||
.Fa buf
|
||||
which is of size
|
||||
.Fa size .
|
||||
The actual length of the password must be returned to the calling function.
|
||||
.Fa rwflag
|
||||
indicates whether the callback is used for reading/decryption
|
||||
.Pq Fa rwflag No = 0
|
||||
or writing/encryption
|
||||
.Pq Fa rwflag No = 1 .
|
||||
Since the
|
||||
.Fa cb
|
||||
passed to
|
||||
.Fn SSL_CTX_set_default_passwd_cb
|
||||
will only be used for reading and decryption and not for writing and
|
||||
encryption, the library will only call it with a
|
||||
.Fa verify
|
||||
argument of 0.
|
||||
.Pp
|
||||
When loading or storing private keys, a password might be supplied to protect
|
||||
the private key.
|
||||
The way this password can be supplied may depend on the application.
|
||||
If only one private key is handled, it can be practical to have the
|
||||
If an application program only needs to read and decrypt
|
||||
one single private key, it can be practical to have the
|
||||
callback handle the password dialog interactively.
|
||||
If several keys have to be handled, it can be practical to ask for the password
|
||||
once, then keep it in memory and use it several times.
|
||||
In the last case, the password could be stored into the
|
||||
This happens by default if neither
|
||||
.Fn SSL_CTX_set_default_passwd_cb
|
||||
nor
|
||||
.Fn SSL_CTX_set_default_passwd_cb_userdata
|
||||
is called.
|
||||
In that case, the library uses
|
||||
.Xr PEM_def_callback 3
|
||||
with a
|
||||
.Fa userdata
|
||||
storage and the callback only returns the password already stored.
|
||||
argument of
|
||||
.Dv NULL .
|
||||
.Pp
|
||||
When asking for the password interactively, the callback can use
|
||||
.Fa rwflag
|
||||
to check whether an item shall be encrypted
|
||||
.Pq Fa rwflag No = 1 .
|
||||
In this case the password dialog may ask for the same password twice for
|
||||
comparison in order to catch typos which would make decryption impossible.
|
||||
If several keys have to be handled, it can be practical
|
||||
to ask for the password once, for example using
|
||||
.Xr UI_UTIL_read_pw_string 3 ,
|
||||
then keep it in memory and use it several times by passing a pointer to it to
|
||||
.Fn SSL_CTX_set_default_passwd_cb_userdata .
|
||||
.Xr PEM_def_callback 3
|
||||
is able to handle this case, too, so calling
|
||||
.Fn SSL_CTX_set_default_passwd_cb
|
||||
is not needed in this case either.
|
||||
.Pp
|
||||
Other items in PEM formatting (certificates) can also be encrypted; it is
|
||||
however atypical, as certificate information is considered public.
|
||||
|
|
@ -137,22 +174,30 @@ or
|
|||
.Dv NULL
|
||||
if none is set.
|
||||
.Sh EXAMPLES
|
||||
The following example returns the password provided as
|
||||
The following example provides a subset of the functionality of
|
||||
.Xr PEM_def_callback 3 ,
|
||||
except that
|
||||
.Xr PEM_def_callback 3
|
||||
does not NUL-terminate and copies up to
|
||||
.Fa size
|
||||
rather than
|
||||
.Fa size No \- 1
|
||||
bytes.
|
||||
It interprets
|
||||
.Fa userdata
|
||||
to the calling function.
|
||||
The password is considered to be a
|
||||
.Sq \e0
|
||||
terminated string.
|
||||
If the password does not fit into the buffer, the password is truncated.
|
||||
as a NUL-terminated string and copies it to the
|
||||
.Fa password
|
||||
buffer, truncating the copy if it does not fit.
|
||||
.Bd -literal
|
||||
int pem_passwd_cb(char *buf, int size, int rwflag, void *password)
|
||||
int
|
||||
trivial_passwd_cb(char *password, int size, int verify, void *userdata)
|
||||
{
|
||||
strncpy(buf, (char *)password, size);
|
||||
buf[size - 1] = '\e0';
|
||||
return strlen(buf);
|
||||
strlcpy(password, userdata, size);
|
||||
return strlen(password);
|
||||
}
|
||||
.Ed
|
||||
.Sh SEE ALSO
|
||||
.Xr pem_password_cb 3 ,
|
||||
.Xr ssl 3 ,
|
||||
.Xr SSL_CTX_use_certificate 3
|
||||
.Sh HISTORY
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue