From: schwarze Date: Tue, 19 Sep 2023 08:18:13 +0000 (+0000) Subject: Remove the duplicate documentation of pem_password_cb(3). X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=911218781d39ba8797246725888491bb8b8a3bc4;p=openbsd Remove the duplicate documentation of pem_password_cb(3). While here, also: * Avoid the misleading term "default password callback" because none of the functions in SSL_CTX_use_certificate(3) support overriding it. * Do not talk about "storing", "writing", and "encryption" since the cb passed to SSL_CTX_set_default_passwd_cb(3) is never used for any of that. * List the functions using cb. * Document what happens by default. * Remove the misleading words "which must be provided by the application" because all this is actually optional. * Make several wordings more precise. * Below EXAMPLES, fix argument naming to agree with pem_password_cb(3), clarify the description of what the example does, and, as suggested by tb@, use strlcpy(3). OK tb@ --- diff --git a/lib/libssl/man/SSL_CTX_set_default_passwd_cb.3 b/lib/libssl/man/SSL_CTX_set_default_passwd_cb.3 index 7ab9633f5c1..4e119132b2e 100644 --- a/lib/libssl/man/SSL_CTX_set_default_passwd_cb.3 +++ b/lib/libssl/man/SSL_CTX_set_default_passwd_cb.3 @@ -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.8 2023/09/19 08:18:13 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 +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2023 Ingo Schwarze +.\" +.\" 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 .\" and Christian Heimes . .\" 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,23 @@ 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 . +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