convert PEM and PKCS manuals from pod to mdoc

1 files changed, 997 insertions, 0 deletions

diff --git a/src/lib/libcrypto/man/PEM_read_bio_PrivateKey.3 b/src/lib/libcrypto/man/PEM_read_bio_PrivateKey.3
new file mode 100644
index 0000000000..7dcea6dbe1
--- /dev/null
+++ b/src/lib/libcrypto/man/PEM_read_bio_PrivateKey.3
@@ -0,0 +1,997 @@
+.Dd $Mdocdate: November 3 2016 $
+.Dt PEM_READ_BIO_PRIVATEKEY 3
+.Os
+.Sh NAME
+.Nm PEM ,
+.Nm PEM_read_bio_PrivateKey ,
+.Nm PEM_read_PrivateKey ,
+.Nm PEM_write_bio_PrivateKey ,
+.Nm PEM_write_PrivateKey ,
+.Nm PEM_write_bio_PKCS8PrivateKey ,
+.Nm PEM_write_PKCS8PrivateKey ,
+.Nm PEM_write_bio_PKCS8PrivateKey_nid ,
+.Nm PEM_write_PKCS8PrivateKey_nid ,
+.Nm PEM_read_bio_PUBKEY ,
+.Nm PEM_read_PUBKEY ,
+.Nm PEM_write_bio_PUBKEY ,
+.Nm PEM_write_PUBKEY ,
+.Nm PEM_read_bio_RSAPrivateKey ,
+.Nm PEM_read_RSAPrivateKey ,
+.Nm PEM_write_bio_RSAPrivateKey ,
+.Nm PEM_write_RSAPrivateKey ,
+.Nm PEM_read_bio_RSAPublicKey ,
+.Nm PEM_read_RSAPublicKey ,
+.Nm PEM_write_bio_RSAPublicKey ,
+.Nm PEM_write_RSAPublicKey ,
+.Nm PEM_read_bio_RSA_PUBKEY ,
+.Nm PEM_read_RSA_PUBKEY ,
+.Nm PEM_write_bio_RSA_PUBKEY ,
+.Nm PEM_write_RSA_PUBKEY ,
+.Nm PEM_read_bio_DSAPrivateKey ,
+.Nm PEM_read_DSAPrivateKey ,
+.Nm PEM_write_bio_DSAPrivateKey ,
+.Nm PEM_write_DSAPrivateKey ,
+.Nm PEM_read_bio_DSA_PUBKEY ,
+.Nm PEM_read_DSA_PUBKEY ,
+.Nm PEM_write_bio_DSA_PUBKEY ,
+.Nm PEM_write_DSA_PUBKEY ,
+.Nm PEM_read_bio_DSAparams ,
+.Nm PEM_read_DSAparams ,
+.Nm PEM_write_bio_DSAparams ,
+.Nm PEM_write_DSAparams ,
+.Nm PEM_read_bio_DHparams ,
+.Nm PEM_read_DHparams ,
+.Nm PEM_write_bio_DHparams ,
+.Nm PEM_write_DHparams ,
+.Nm PEM_read_bio_X509 ,
+.Nm PEM_read_X509 ,
+.Nm PEM_write_bio_X509 ,
+.Nm PEM_write_X509 ,
+.Nm PEM_read_bio_X509_AUX ,
+.Nm PEM_read_X509_AUX ,
+.Nm PEM_write_bio_X509_AUX ,
+.Nm PEM_write_X509_AUX ,
+.Nm PEM_read_bio_X509_REQ ,
+.Nm PEM_read_X509_REQ ,
+.Nm PEM_write_bio_X509_REQ ,
+.Nm PEM_write_X509_REQ ,
+.Nm PEM_write_bio_X509_REQ_NEW ,
+.Nm PEM_write_X509_REQ_NEW ,
+.Nm PEM_read_bio_X509_CRL ,
+.Nm PEM_read_X509_CRL ,
+.Nm PEM_write_bio_X509_CRL ,
+.Nm PEM_write_X509_CRL ,
+.Nm PEM_read_bio_PKCS7 ,
+.Nm PEM_read_PKCS7 ,
+.Nm PEM_write_bio_PKCS7 ,
+.Nm PEM_write_PKCS7 ,
+.Nm PEM_read_bio_NETSCAPE_CERT_SEQUENCE ,
+.Nm PEM_read_NETSCAPE_CERT_SEQUENCE ,
+.Nm PEM_write_bio_NETSCAPE_CERT_SEQUENCE ,
+.Nm PEM_write_NETSCAPE_CERT_SEQUENCE
+.Nd PEM routines
+.Sh SYNOPSIS
+.In openssl/pem.h
+.Ft EVP_PKEY *
+.Fo PEM_read_bio_PrivateKey
+.Fa "BIO *bp"
+.Fa "EVP_PKEY **x"
+.Fa "pem_password_cb *cb"
+.Fa "void *u"
+.Fc
+.Ft EVP_PKEY *
+.Fo PEM_read_PrivateKey
+.Fa "FILE *fp"
+.Fa "EVP_PKEY **x"
+.Fa "pem_password_cb *cb"
+.Fa "void *u"
+.Fc
+.Ft int
+.Fo PEM_write_bio_PrivateKey
+.Fa "BIO *bp"
+.Fa "EVP_PKEY *x"
+.Fa "const EVP_CIPHER *enc"
+.Fa "unsigned char *kstr"
+.Fa "int klen"
+.Fa "pem_password_cb *cb"
+.Fa "void *u"
+.Fc
+.Ft int
+.Fo PEM_write_PrivateKey
+.Fa "FILE *fp"
+.Fa "EVP_PKEY *x"
+.Fa "const EVP_CIPHER *enc"
+.Fa "unsigned char *kstr"
+.Fa "int klen"
+.Fa "pem_password_cb *cb"
+.Fa "void *u"
+.Fc
+.Ft int
+.Fo PEM_write_bio_PKCS8PrivateKey
+.Fa "BIO *bp"
+.Fa "EVP_PKEY *x"
+.Fa "const EVP_CIPHER *enc"
+.Fa "char *kstr"
+.Fa "int klen"
+.Fa "pem_password_cb *cb"
+.Fa "void *u"
+.Fc
+.Ft int
+.Fo PEM_write_PKCS8PrivateKey
+.Fa "FILE *fp"
+.Fa "EVP_PKEY *x"
+.Fa "const EVP_CIPHER *enc"
+.Fa "char *kstr"
+.Fa "int klen"
+.Fa "pem_password_cb *cb"
+.Fa "void *u"
+.Fc
+.Ft int
+.Fo PEM_write_bio_PKCS8PrivateKey_nid
+.Fa "BIO *bp"
+.Fa "EVP_PKEY *x"
+.Fa "int nid"
+.Fa "char *kstr"
+.Fa "int klen"
+.Fa "pem_password_cb *cb"
+.Fa "void *u"
+.Fc
+.Ft int
+.Fo PEM_write_PKCS8PrivateKey_nid
+.Fa "FILE *fp"
+.Fa "EVP_PKEY *x"
+.Fa "int nid"
+.Fa "char *kstr"
+.Fa "int klen"
+.Fa "pem_password_cb *cb"
+.Fa "void *u"
+.Fc
+.Ft EVP_PKEY *
+.Fo PEM_read_bio_PUBKEY
+.Fa "BIO *bp"
+.Fa "EVP_PKEY **x"
+.Fa "pem_password_cb *cb"
+.Fa "void *u"
+.Fc
+.Ft EVP_PKEY *
+.Fo PEM_read_PUBKEY
+.Fa "FILE *fp"
+.Fa "EVP_PKEY **x"
+.Fa "pem_password_cb *cb"
+.Fa "void *u"
+.Fc
+.Ft int
+.Fo PEM_write_bio_PUBKEY
+.Fa "BIO *bp"
+.Fa "EVP_PKEY *x"
+.Fc
+.Ft int
+.Fo PEM_write_PUBKEY
+.Fa "FILE *fp"
+.Fa "EVP_PKEY *x"
+.Fc
+.Ft RSA *
+.Fo PEM_read_bio_RSAPrivateKey
+.Fa "BIO *bp"
+.Fa "RSA **x"
+.Fa "pem_password_cb *cb"
+.Fa "void *u"
+.Fc
+.Ft RSA *
+.Fo PEM_read_RSAPrivateKey
+.Fa "FILE *fp"
+.Fa "RSA **x"
+.Fa "pem_password_cb *cb"
+.Fa "void *u"
+.Fc
+.Ft int
+.Fo PEM_write_bio_RSAPrivateKey
+.Fa "BIO *bp"
+.Fa "RSA *x"
+.Fa "const EVP_CIPHER *enc"
+.Fa "unsigned char *kstr"
+.Fa "int klen"
+.Fa "pem_password_cb *cb"
+.Fa "void *u"
+.Fc
+.Ft int
+.Fo PEM_write_RSAPrivateKey
+.Fa "FILE *fp"
+.Fa "RSA *x"
+.Fa "const EVP_CIPHER *enc"
+.Fa "unsigned char *kstr"
+.Fa "int klen"
+.Fa "pem_password_cb *cb"
+.Fa "void *u"
+.Fc
+.Ft RSA *
+.Fo PEM_read_bio_RSAPublicKey
+.Fa "BIO *bp"
+.Fa "RSA **x"
+.Fa "pem_password_cb *cb"
+.Fa "void *u"
+.Fc
+.Ft RSA *
+.Fo PEM_read_RSAPublicKey
+.Fa "FILE *fp"
+.Fa "RSA **x"
+.Fa "pem_password_cb *cb"
+.Fa "void *u"
+.Fc
+.Ft int
+.Fo PEM_write_bio_RSAPublicKey
+.Fa "BIO *bp"
+.Fa "RSA *x"
+.Fc
+.Ft int
+.Fo PEM_write_RSAPublicKey
+.Fa "FILE *fp"
+.Fa "RSA *x"
+.Fc
+.Ft RSA *
+.Fo PEM_read_bio_RSA_PUBKEY
+.Fa "BIO *bp"
+.Fa "RSA **x"
+.Fa "pem_password_cb *cb"
+.Fa "void *u"
+.Fc
+.Ft RSA *
+.Fo PEM_read_RSA_PUBKEY
+.Fa "FILE *fp"
+.Fa "RSA **x"
+.Fa "pem_password_cb *cb"
+.Fa "void *u"
+.Fc
+.Ft int
+.Fo PEM_write_bio_RSA_PUBKEY
+.Fa "BIO *bp"
+.Fa "RSA *x"
+.Fc
+.Ft int
+.Fo PEM_write_RSA_PUBKEY
+.Fa "FILE *fp"
+.Fa "RSA *x"
+.Fc
+.Ft DSA *
+.Fo PEM_read_bio_DSAPrivateKey
+.Fa "BIO *bp"
+.Fa "DSA **x"
+.Fa "pem_password_cb *cb"
+.Fa "void *u"
+.Fc
+.Ft DSA *
+.Fo PEM_read_DSAPrivateKey
+.Fa "FILE *fp"
+.Fa "DSA **x"
+.Fa "pem_password_cb *cb"
+.Fa "void *u"
+.Fc
+.Ft int
+.Fo PEM_write_bio_DSAPrivateKey
+.Fa "BIO *bp"
+.Fa "DSA *x"
+.Fa "const EVP_CIPHER *enc"
+.Fa "unsigned char *kstr"
+.Fa "int klen"
+.Fa "pem_password_cb *cb"
+.Fa "void *u"
+.Fc
+.Ft int
+.Fo PEM_write_DSAPrivateKey
+.Fa "FILE *fp"
+.Fa "DSA *x"
+.Fa "const EVP_CIPHER *enc"
+.Fa "unsigned char *kstr"
+.Fa "int klen"
+.Fa "pem_password_cb *cb"
+.Fa "void *u"
+.Fc
+.Ft DSA *
+.Fo PEM_read_bio_DSA_PUBKEY
+.Fa "BIO *bp"
+.Fa "DSA **x"
+.Fa "pem_password_cb *cb"
+.Fa "void *u"
+.Fc
+.Ft DSA *
+.Fo PEM_read_DSA_PUBKEY
+.Fa "FILE *fp"
+.Fa "DSA **x"
+.Fa "pem_password_cb *cb"
+.Fa "void *u"
+.Fc
+.Ft int
+.Fo PEM_write_bio_DSA_PUBKEY
+.Fa "BIO *bp"
+.Fa "DSA *x"
+.Fc
+.Ft int
+.Fo PEM_write_DSA_PUBKEY
+.Fa "FILE *fp"
+.Fa "DSA *x"
+.Fc
+.Ft DSA *
+.Fo PEM_read_bio_DSAparams
+.Fa "BIO *bp"
+.Fa "DSA **x"
+.Fa "pem_password_cb *cb"
+.Fa "void *u"
+.Fc
+.Ft DSA *
+.Fo PEM_read_DSAparams
+.Fa "FILE *fp"
+.Fa "DSA **x"
+.Fa "pem_password_cb *cb"
+.Fa "void *u"
+.Fc
+.Ft int
+.Fo PEM_write_bio_DSAparams
+.Fa "BIO *bp"
+.Fa "DSA *x"
+.Fc
+.Ft int
+.Fo PEM_write_DSAparams
+.Fa "FILE *fp"
+.Fa "DSA *x"
+.Fc
+.Ft DH *
+.Fo PEM_read_bio_DHparams
+.Fa "BIO *bp"
+.Fa "DH **x"
+.Fa "pem_password_cb *cb"
+.Fa "void *u"
+.Fc
+.Ft DH *
+.Fo PEM_read_DHparams
+.Fa "FILE *fp"
+.Fa "DH **x"
+.Fa "pem_password_cb *cb"
+.Fa "void *u"
+.Fc
+.Ft int
+.Fo PEM_write_bio_DHparams
+.Fa "BIO *bp"
+.Fa "DH *x"
+.Fc
+.Ft int
+.Fo PEM_write_DHparams
+.Fa "FILE *fp"
+.Fa "DH *x"
+.Fc
+.Ft X509 *
+.Fo PEM_read_bio_X509
+.Fa "BIO *bp"
+.Fa "X509 **x"
+.Fa "pem_password_cb *cb"
+.Fa "void *u"
+.Fc
+.Ft X509 *
+.Fo PEM_read_X509
+.Fa "FILE *fp"
+.Fa "X509 **x"
+.Fa "pem_password_cb *cb"
+.Fa "void *u"
+.Fc
+.Ft int
+.Fo PEM_write_bio_X509
+.Fa "BIO *bp"
+.Fa "X509 *x"
+.Fc
+.Ft int
+.Fo PEM_write_X509
+.Fa "FILE *fp"
+.Fa "X509 *x"
+.Fc
+.Ft X509 *
+.Fo PEM_read_bio_X509_AUX
+.Fa "BIO *bp"
+.Fa "X509 **x"
+.Fa "pem_password_cb *cb"
+.Fa "void *u"
+.Fc
+.Ft X509 *
+.Fo PEM_read_X509_AUX
+.Fa "FILE *fp"
+.Fa "X509 **x"
+.Fa "pem_password_cb *cb"
+.Fa "void *u"
+.Fc
+.Ft int
+.Fo PEM_write_bio_X509_AUX
+.Fa "BIO *bp"
+.Fa "X509 *x"
+.Fc
+.Ft int
+.Fo PEM_write_X509_AUX
+.Fa "FILE *fp"
+.Fa "X509 *x"
+.Fc
+.Ft X509_REQ *
+.Fo PEM_read_bio_X509_REQ
+.Fa "BIO *bp"
+.Fa "X509_REQ **x"
+.Fa "pem_password_cb *cb"
+.Fa "void *u"
+.Fc
+.Ft X509_REQ *
+.Fo PEM_read_X509_REQ
+.Fa "FILE *fp"
+.Fa "X509_REQ **x"
+.Fa "pem_password_cb *cb"
+.Fa "void *u"
+.Fc
+.Ft int
+.Fo PEM_write_bio_X509_REQ
+.Fa "BIO *bp"
+.Fa "X509_REQ *x"
+.Fc
+.Ft int
+.Fo PEM_write_X509_REQ
+.Fa "FILE *fp"
+.Fa "X509_REQ *x"
+.Fc
+.Ft int
+.Fo PEM_write_bio_X509_REQ_NEW
+.Fa "BIO *bp"
+.Fa "X509_REQ *x"
+.Fc
+.Ft int
+.Fo PEM_write_X509_REQ_NEW
+.Fa "FILE *fp"
+.Fa "X509_REQ *x"
+.Fc
+.Ft X509_CRL *
+.Fo PEM_read_bio_X509_CRL
+.Fa "BIO *bp"
+.Fa "X509_CRL **x"
+.Fa "pem_password_cb *cb"
+.Fa "void *u"
+.Fc
+.Ft X509_CRL *
+.Fo PEM_read_X509_CRL
+.Fa "FILE *fp"
+.Fa "X509_CRL **x"
+.Fa "pem_password_cb *cb"
+.Fa "void *u"
+.Fc
+.Ft int
+.Fo PEM_write_bio_X509_CRL
+.Fa "BIO *bp"
+.Fa "X509_CRL *x"
+.Fc
+.Ft int
+.Fo PEM_write_X509_CRL
+.Fa "FILE *fp"
+.Fa "X509_CRL *x"
+.Fc
+.Ft PKCS7 *
+.Fo PEM_read_bio_PKCS7
+.Fa "BIO *bp"
+.Fa "PKCS7 **x"
+.Fa "pem_password_cb *cb"
+.Fa "void *u"
+.Fc
+.Ft PKCS7 *
+.Fo PEM_read_PKCS7
+.Fa "FILE *fp"
+.Fa "PKCS7 **x"
+.Fa "pem_password_cb *cb"
+.Fa "void *u"
+.Fc
+.Ft int
+.Fo PEM_write_bio_PKCS7
+.Fa "BIO *bp"
+.Fa "PKCS7 *x"
+.Fc
+.Ft int
+.Fo PEM_write_PKCS7
+.Fa "FILE *fp"
+.Fa "PKCS7 *x"
+.Fc
+.Ft NETSCAPE_CERT_SEQUENCE *
+.Fo PEM_read_bio_NETSCAPE_CERT_SEQUENCE
+.Fa "BIO *bp"
+.Fa "NETSCAPE_CERT_SEQUENCE **x"
+.Fa "pem_password_cb *cb"
+.Fa "void *u"
+.Fc
+.Ft NETSCAPE_CERT_SEQUENCE *
+.Fo PEM_read_NETSCAPE_CERT_SEQUENCE
+.Fa "FILE *fp"
+.Fa "NETSCAPE_CERT_SEQUENCE **x"
+.Fa "pem_password_cb *cb"
+.Fa "void *u"
+.Fc
+.Ft int
+.Fo PEM_write_bio_NETSCAPE_CERT_SEQUENCE
+.Fa "BIO *bp"
+.Fa "NETSCAPE_CERT_SEQUENCE *x"
+.Fc
+.Ft int
+.Fo PEM_write_NETSCAPE_CERT_SEQUENCE
+.Fa "FILE *fp"
+.Fa "NETSCAPE_CERT_SEQUENCE *x"
+.Fc
+.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.
+.Pp
+For more details about the meaning of arguments see the
+.Sx PEM function arguments
+section.
+.Pp
+Each operation has four functions associated with it.
+For clarity the term
+.Dq Sy foobar No functions
+will be used to collectively refer to the
+.Fn PEM_read_bio_foobar ,
+.Fn PEM_read_foobar ,
+.Fn PEM_write_bio_foobar ,
+and
+.Fn PEM_write_foobar
+functions.
+.Pp
+The
+.Sy PrivateKey
+functions read or write a private key in PEM format using an
+.Vt EVP_PKEY
+structure.
+The write routines use "traditional" private key format and can handle
+both RSA and DSA private keys.
+The read functions can additionally transparently handle PKCS#8 format
+encrypted and unencrypted keys, too.
+.Pp
+.Fn PEM_write_bio_PKCS8PrivateKey
+and
+.Fn PEM_write_PKCS8PrivateKey
+write a private key in an
+.Vt EVP_PKEY
+structure in PKCS#8 EncryptedPrivateKeyInfo format using PKCS#5
+v2.0 password based encryption algorithms.
+The
+.Fa enc
+argument specifies the encryption algorithm to use: unlike all other PEM
+routines, the encryption is applied at the PKCS#8 level and not in the
+PEM headers.
+If
+.Fa enc
+is
+.Dv NULL ,
+then no encryption is used and a PKCS#8 PrivateKeyInfo structure
+is used instead.
+.Pp
+.Fn PEM_write_bio_PKCS8PrivateKey_nid
+and
+.Fn PEM_write_PKCS8PrivateKey_nid
+also write out a private key as a PKCS#8 EncryptedPrivateKeyInfo.
+However they use PKCS#5 v1.5 or PKCS#12 encryption algorithms instead.
+The algorithm to use is specified in the
+.Fa nid
+parameter and should be the NID of the corresponding OBJECT IDENTIFIER
+(see NOTES section).
+.Pp
+The
+.Sy PUBKEY
+functions process a public key using an
+.Vt EVP_PKEY
+structure.
+The public key is encoded as a SubjectPublicKeyInfo structure.
+.Pp
+The
+.Sy RSAPrivateKey
+functions process an RSA private key using an
+.Vt RSA
+structure.
+They handle the same formats as the
+.Sy PrivateKey
+functions, but an error occurs if the private key is not RSA.
+.Pp
+The
+.Sy RSAPublicKey
+functions process an RSA public key using an
+.Vt RSA
+structure.
+The public key is encoded using a PKCS#1 RSAPublicKey structure.
+.Pp
+The
+.Sy RSA_PUBKEY
+functions also process an RSA public key using an
+.Vt RSA
+structure.
+However the public key is encoded using a SubjectPublicKeyInfo structure
+and an error occurs if the public key is not RSA.
+.Pp
+The
+.Sy DSAPrivateKey
+functions process a DSA private key using a
+.Vt DSA
+structure.
+They handle the same formats as the
+.Sy PrivateKey
+functions but an error occurs if the private key is not DSA.
+.Pp
+The
+.Sy DSA_PUBKEY
+functions process a DSA public key using a
+.Vt DSA
+structure.
+The public key is encoded using a SubjectPublicKeyInfo structure and an
+error occurs if the public key is not DSA.
+.Pp
+The
+.Sy DSAparams
+functions process DSA parameters using a
+.Vt DSA
+structure.
+The parameters are encoded using a Dss-Parms structure as defined in RFC 2459.
+.Pp
+The
+.Sy DHparams
+functions process DH parameters using a
+.Vt DH
+structure.
+The parameters are encoded using a PKCS#3 DHparameter structure.
+.Pp
+The
+.Sy X509
+functions process an X509 certificate using an
+.Vt X509
+structure.
+They will also process a trusted X509 certificate but any trust settings
+are discarded.
+.Pp
+The
+.Sy X509_AUX
+functions process a trusted X509 certificate using an
+.Vt X509
+structure.
+.Pp
+The
+.Sy X509_REQ
+and
+.Sy X509_REQ_NEW
+functions process a PKCS#10 certificate request using an
+.Vt X509_REQ
+structure.
+The
+.Sy X509_REQ
+write functions use CERTIFICATE REQUEST in the header whereas the
+.Sy X509_REQ_NEW
+functions use NEW CERTIFICATE REQUEST (as required by some CAs).
+The
+.Sy X509_REQ
+read functions will handle either form so there are no
+.Sy X509_REQ_NEW
+read functions.
+.Pp
+The
+.Sy X509_CRL
+functions process an X509 CRL using an
+.Vt X509_CRL
+structure.
+.Pp
+The
+.Sy PKCS7
+functions process a PKCS#7 ContentInfo using a
+.Vt PKCS7
+structure.
+.Pp
+The
+.Sy NETSCAPE_CERT_SEQUENCE
+functions process a Netscape Certificate Sequence using a
+.Vt NETSCAPE_CERT_SEQUENCE
+structure.
+.Pp
+The old
+.Sy PrivateKey
+write routines are retained for compatibility.
+New applications should write private keys using the
+.Fn PEM_write_bio_PKCS8PrivateKey
+or
+.Fn PEM_write_PKCS8PrivateKey
+routines because they are more secure (they use an iteration count of
+2048 whereas the traditional routines use a count of 1) unless
+compatibility with older versions of OpenSSL is important.
+.Pp
+The
+.Sy PrivateKey
+read routines can be used in all applications because they handle all
+formats transparently.
+.Ss PEM function arguments
+The PEM functions have many common arguments.
+.Pp
+The
+.Fa bp
+parameter specifies the
+.Vt BIO
+to read from or write to.
+.Pp
+The
+.Fa fp
+parameter specifies the
+.Vt FILE
+pointer to read from or write to.
+.Pp
+The PEM read functions all take a pointer to pointer argument
+.Fa x
+and return a pointer of the same type.
+If
+.Fa x
+is
+.Dv NULL ,
+then the parameter is ignored.
+If
+.Fa x
+is not
+.Dv NULL
+but
+.Pf * Fa x
+is
+.Dv NULL ,
+then the structure returned will be written to
+.Pf * Fa x .
+If neither
+.Fa x
+nor
+.Pf * Fa x
+are
+.Dv NULL ,
+then an attempt is made to reuse the structure at
+.Pf * Fa x ,
+but see the
+.Sx BUGS
+and
+.Sx EXAMPLES
+sections.
+Irrespective of the value of
+.Fa x ,
+a pointer to the structure is always returned, or
+.Dv NULL
+if an error occurred.
+.Pp
+The PEM functions which write private keys take an
+.Fa enc
+parameter which specifies the encryption algorithm to use.
+Encryption is done at the PEM level.
+If this parameter is set to
+.Dv NULL ,
+then the private key is written in unencrypted form.
+.Pp
+The
+.Fa cb
+argument is the callback to use when querying for the passphrase used
+for encrypted PEM structures (normally only private keys).
+.Pp
+For the PEM write routines, if the
+.Fa kstr
+parameter is not
+.Dv NULL ,
+then
+.Fa klen
+bytes at
+.Fa kstr
+are used as the passphrase and
+.Fa cb
+is ignored.
+.Pp
+If the
+.Fa cb
+parameters 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 0 if an error occurred.
+.Ss PEM encryption format
+This old
+.Sy PrivateKey
+routines use a non standard technique for encryption.
+.Pp
+The private key (or other data) takes the following form:
+.Bd -literal -offset indent
+-----BEGIN RSA PRIVATE KEY-----
+Proc-Type: 4,ENCRYPTED
+DEK-Info: DES-EDE3-CBC,3F17F5316E2BAC89
+
+\&...base64 encoded data...
+-----END RSA PRIVATE KEY-----
+.Ed
+.Pp
+The line beginning with
+.Dq DEK-Info
+contains two comma separated pieces of information:
+the encryption algorithm name as used by
+.Xr EVP_get_cipherbyname 3
+and an 8 byte salt encoded as a set of hexadecimal digits.
+.Pp
+After this is the base64 encoded encrypted data.
+.Pp
+The encryption key is determined using
+.Xr EVP_BytesToKey 3 ,
+using the salt and an iteration count of 1.
+The IV used is the value of the salt and *not* the IV returned by
+.Xr EVP_BytesToKey 3 .
+.Sh RETURN VALUES
+The read routines return either a pointer to the structure read or
+.Dv NULL
+if an error occurred.
+.Pp
+The write routines return 1 for success or 0 for failure.
+.Sh EXAMPLES
+Although the PEM routines take several arguments, in almost all
+applications most of them are set to 0 or
+.Dv NULL .
+.Pp
+Read a certificate in PEM format from a
+.Vt BIO :
+.Bd -literal
+X509 *x;
+x = PEM_read_bio_X509(bp, NULL, 0, NULL);
+if (x == NULL) {
+        /* Error */
+}
+.Ed
+.Pp
+Alternative method:
+.Bd -literal
+X509 *x = NULL;
+if (!PEM_read_bio_X509(bp, &x, 0, NULL)) {
+        /* Error */
+}
+.Ed
+.Pp
+Write a certificate to a
+.Vt BIO :
+.Bd -literal
+if (!PEM_write_bio_X509(bp, x)) {
+        /* Error */
+}
+.Ed
+.Pp
+Write an unencrypted private key to a
+.Vt FILE :
+.Bd -literal
+if (!PEM_write_PrivateKey(fp, key, NULL, NULL, 0, 0, NULL)) {
+        /* Error */
+}
+.Ed
+.Pp
+Write a private key (using traditional format) to a
+.Vt BIO
+using triple DES encryption, the pass phrase is prompted for:
+.Bd -literal
+if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(),
+    NULL, 0, 0, NULL)) {
+        /* Error */
+}
+.Ed
+.Pp
+Write a private key (using PKCS#8 format) to a
+.Vt BIO
+using triple DES encryption, using the pass phrase "hello":
+.Bd -literal
+if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(),
+    NULL, 0, 0, "hello")) {
+        /* Error */
+}
+.Ed
+.Pp
+Read a private key from a
+.Vt BIO
+using the pass phrase "hello":
+.Bd -literal
+key = PEM_read_bio_PrivateKey(bp, NULL, 0, "hello");
+if (key == NULL) {
+        /* Error */
+}
+.Ed
+.Pp
+Read a private key from a
+.Vt BIO
+using a pass phrase callback:
+.Bd -literal
+key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key");
+if (key == NULL) {
+        /* Error */
+}
+.Ed
+.Pp
+Skeleton pass phrase callback:
+.Bd -literal
+int
+pass_cb(char *buf, int size, int rwflag, void *u)
+{
+        int len;
+        char *tmp;
+
+        /* We'd probably do something else if 'rwflag' is 1 */
+        printf("Enter pass phrase for \e"%s\e"\en", u);
+
+        /* get pass phrase, length 'len' into 'tmp' */
+        tmp = "hello";
+        len = strlen(tmp);
+
+        if (len == 0)
+                return 0;
+        /* if too long, truncate */
+        if (len > size)
+                len = size;
+        memcpy(buf, tmp, len);
+        return len;
+}
+.Ed
+.Sh CAVEATS
+A frequent cause of problems is attempting to use the PEM routines like
+this:
+.Bd -literal
+X509 *x;
+PEM_read_bio_X509(bp, &x, 0, NULL);
+.Ed
+.Pp
+This is a bug because an attempt will be made to reuse the data at
+.Fa x
+which is an uninitialised pointer.
+.Sh BUGS
+The PEM read routines in some versions of OpenSSL will not correctly
+reuse an existing structure.
+Therefore
+.Pp
+.Dl PEM_read_bio_X509(bp, &x, 0, NULL);
+.Pp
+where
+.Fa x
+already contains a valid certificate may not work, whereas
+.Bd -literal -offset indent
+X509_free(x);
+x = PEM_read_bio_X509(bp, NULL, 0, NULL);
+.Ed
+.Pp
+is guaranteed to work.