Convert libssl manpages from pod to mdoc(7).

libcrypto has not been started yet.

ok schwarze@ miod@

1 files changed, 92 insertions, 0 deletions

diff --git a/src/lib/libssl/doc/SSL_CTX_set_default_passwd_cb.3 b/src/lib/libssl/doc/SSL_CTX_set_default_passwd_cb.3
new file mode 100644
index 0000000000..2c35ed501c
--- /dev/null
+++ b/src/lib/libssl/doc/SSL_CTX_set_default_passwd_cb.3
@@ -0,0 +1,92 @@
+.Dd $Mdocdate: October 12 2014 $
+.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
+.Nd set 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"
+.Ft int
+.Fn pem_passwd_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.
+.Pp
+.Fn SSL_CTX_set_default_passwd_cb_userdata
+sets a pointer to userdata
+.Fa u
+which will be provided to the password callback on invocation.
+.Pp
+The
+.Fn pem_passwd_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 pem_passwd_cb 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 .
+.Sh NOTES
+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
+.Fn pem_passwd_cb
+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
+.Fa userdata
+storage and the
+.Fn pem_passwd_cb
+only returns the password already stored.
+.Pp
+When asking for the password interactively,
+.Fn pem_passwd_cb
+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.
+.Pp
+Other items in PEM formatting (certificates) can also be encrypted; it is
+however atypical, as certificate information is considered public.
+.Sh RETURN VALUES
+.Fn SSL_CTX_set_default_passwd_cb
+and
+.Fn SSL_CTX_set_default_passwd_cb_userdata
+do not provide diagnostic information.
+.Sh EXAMPLES
+The following example returns the password provided as
+.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.
+.Bd -literal
+int pem_passwd_cb(char *buf, int size, int rwflag, void *password)
+{
+        strncpy(buf, (char *)password, size);
+        buf[size - 1] = '\e0';
+        return strlen(buf);
+}
+.Ed
+.Sh SEE ALSO
+.Xr ssl 3 ,
+.Xr SSL_CTX_use_certificate 3