Document PEM_def_callback(3).

Move pem_password_cb(3) to the file PEM_read(3) and rewrite
its description from scratch for precision and conciseness.
Plus some minor improvements in the vicinity.
Tweaks and OK tb@.

1 files changed, 12 insertions, 70 deletions

diff --git a/src/lib/libcrypto/man/PEM_read_bio_PrivateKey.3 b/src/lib/libcrypto/man/PEM_read_bio_PrivateKey.3
index 3799baa040..cc58640b1c 100644
--- a/src/lib/libcrypto/man/PEM_read_bio_PrivateKey.3
+++ b/src/lib/libcrypto/man/PEM_read_bio_PrivateKey.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: PEM_read_bio_PrivateKey.3,v 1.17 2020/06/12 11:37:42 schwarze Exp $
+.\" $OpenBSD: PEM_read_bio_PrivateKey.3,v 1.18 2020/06/15 14:13:14 schwarze Exp $
 .\" full merge up to:
 .\" OpenSSL man3/PEM_read_bio_PrivateKey.pod 18bad535 Apr 9 15:13:55 2019 +0100
 .\" OpenSSL man3/PEM_read_CMS.pod 83cf7abf May 29 13:07:08 2018 +0100
@@ -51,11 +51,10 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: June 12 2020 $
+.Dd $Mdocdate: June 15 2020 $
 .Dt PEM_READ_BIO_PRIVATEKEY 3
 .Os
 .Sh NAME
-.Nm pem_password_cb ,
 .Nm PEM_read_bio_PrivateKey ,
 .Nm PEM_read_PrivateKey ,
 .Nm PEM_write_bio_PrivateKey ,
@@ -149,13 +148,6 @@
 .Nd PEM routines
 .Sh SYNOPSIS
 .In openssl/pem.h
-.Ft typedef int
-.Fo pem_password_cb
-.Fa "char *buf"
-.Fa "int size"
-.Fa "int rwflag"
-.Fa "void *u"
-.Fc
 .Ft EVP_PKEY *
 .Fo PEM_read_bio_PrivateKey
 .Fa "BIO *bp"
@@ -754,7 +746,9 @@
 .Sh DESCRIPTION
 The PEM functions read or write structures in PEM format.
 In this sense PEM format is simply base64-encoded data surrounded by
-header lines.
+header lines; see
+.Xr PEM_read 3
+for more details.
 .Pp
 For more details about the meaning of arguments see the
 .Sx PEM function arguments
@@ -1050,10 +1044,14 @@ If this parameter is set to
 .Dv NULL ,
 then the private key is written in unencrypted form.
 .Pp
-The
+The optional arguments
+.Fa u
+and
 .Fa cb
-argument is the callback to use when querying for the passphrase used
-for encrypted PEM structures (normally only private keys).
+are a passphrase used for encrypting a PEM structure
+or a callback to obtain the passphrase; see
+.Xr pem_password_cb 3
+for details.
 .Pp
 For the PEM write routines, if the
 .Fa kstr
@@ -1066,62 +1064,6 @@ bytes at
 are used as the passphrase and
 .Fa cb
 is ignored.
-.Pp
-If the
-.Fa cb
-parameter is set to
-.Dv NULL
-and the
-.Fa u
-parameter is not
-.Dv NULL ,
-then the
-.Fa u
-parameter is interpreted as a null terminated string to use as the
-passphrase.
-If both
-.Fa cb
-and
-.Fa u
-are
-.Dv NULL ,
-then the default callback routine is used, which will typically
-prompt for the passphrase on the current terminal with echoing
-turned off.
-.Pp
-The default passphrase callback is sometimes inappropriate (for example
-in a GUI application) so an alternative can be supplied.
-The callback routine has the following form:
-.Bd -filled -offset inset
-.Ft int
-.Fo cb
-.Fa "char *buf"
-.Fa "int size"
-.Fa "int rwflag"
-.Fa "void *u"
-.Fc
-.Ed
-.Pp
-.Fa buf
-is the buffer to write the passphrase to.
-.Fa size
-is the maximum length of the passphrase, i.e. the size of
-.Fa buf .
-.Fa rwflag
-is a flag which is set to 0 when reading and 1 when writing.
-A typical routine will ask the user to verify the passphrase (for
-example by prompting for it twice) if
-.Fa rwflag
-is 1.
-The
-.Fa u
-parameter has the same value as the
-.Fa u
-parameter passed to the PEM routine.
-It allows arbitrary data to be passed to the callback by the application
-(for example a window handle in a GUI application).
-The callback must return the number of characters in the passphrase
-or -1 if an error occurred.
 .Ss PEM encryption format
 This old
 .Sy PrivateKey