summaryrefslogtreecommitdiffstats
path: root/secure/lib/libcrypto/man/pem.3
diff options
context:
space:
mode:
Diffstat (limited to 'secure/lib/libcrypto/man/pem.3')
-rw-r--r--secure/lib/libcrypto/man/pem.3626
1 files changed, 626 insertions, 0 deletions
diff --git a/secure/lib/libcrypto/man/pem.3 b/secure/lib/libcrypto/man/pem.3
new file mode 100644
index 0000000..0cab0d3
--- /dev/null
+++ b/secure/lib/libcrypto/man/pem.3
@@ -0,0 +1,626 @@
+.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.23)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings. \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote. \*(C+ will
+.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+. ds -- \(*W-
+. ds PI pi
+. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
+. ds L" ""
+. ds R" ""
+. ds C` ""
+. ds C' ""
+'br\}
+.el\{\
+. ds -- \|\(em\|
+. ds PI \(*p
+. ds L" ``
+. ds R" ''
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD. Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.ie \nF \{\
+. de IX
+. tm Index:\\$1\t\\n%\t"\\$2"
+..
+. nr % 0
+. rr F
+.\}
+.el \{\
+. de IX
+..
+.\}
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear. Run. Save yourself. No user-serviceable parts.
+. \" fudge factors for nroff and troff
+.if n \{\
+. ds #H 0
+. ds #V .8m
+. ds #F .3m
+. ds #[ \f1
+. ds #] \fP
+.\}
+.if t \{\
+. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+. ds #V .6m
+. ds #F 0
+. ds #[ \&
+. ds #] \&
+.\}
+. \" simple accents for nroff and troff
+.if n \{\
+. ds ' \&
+. ds ` \&
+. ds ^ \&
+. ds , \&
+. ds ~ ~
+. ds /
+.\}
+.if t \{\
+. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+. \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+. \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+. \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+. ds : e
+. ds 8 ss
+. ds o a
+. ds d- d\h'-1'\(ga
+. ds D- D\h'-1'\(hy
+. ds th \o'bp'
+. ds Th \o'LP'
+. ds ae ae
+. ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "pem 3"
+.TH pem 3 "2013-02-11" "1.0.1e" "OpenSSL"
+.\" For nroff, turn off justification. Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH "NAME"
+PEM, PEM_read_bio_PrivateKey, PEM_read_PrivateKey, PEM_write_bio_PrivateKey, PEM_write_PrivateKey, PEM_write_bio_PKCS8PrivateKey, PEM_write_PKCS8PrivateKey, PEM_write_bio_PKCS8PrivateKey_nid, PEM_write_PKCS8PrivateKey_nid, PEM_read_bio_PUBKEY, PEM_read_PUBKEY, PEM_write_bio_PUBKEY, PEM_write_PUBKEY, PEM_read_bio_RSAPrivateKey, PEM_read_RSAPrivateKey, PEM_write_bio_RSAPrivateKey, PEM_write_RSAPrivateKey, PEM_read_bio_RSAPublicKey, PEM_read_RSAPublicKey, PEM_write_bio_RSAPublicKey, PEM_write_RSAPublicKey, PEM_read_bio_RSA_PUBKEY, PEM_read_RSA_PUBKEY, PEM_write_bio_RSA_PUBKEY, PEM_write_RSA_PUBKEY, PEM_read_bio_DSAPrivateKey, PEM_read_DSAPrivateKey, PEM_write_bio_DSAPrivateKey, PEM_write_DSAPrivateKey, PEM_read_bio_DSA_PUBKEY, PEM_read_DSA_PUBKEY, PEM_write_bio_DSA_PUBKEY, PEM_write_DSA_PUBKEY, PEM_read_bio_DSAparams, PEM_read_DSAparams, PEM_write_bio_DSAparams, PEM_write_DSAparams, PEM_read_bio_DHparams, PEM_read_DHparams, PEM_write_bio_DHparams, PEM_write_DHparams, PEM_read_bio_X509, PEM_read_X509, PEM_write_bio_X509, PEM_write_X509, PEM_read_bio_X509_AUX, PEM_read_X509_AUX, PEM_write_bio_X509_AUX, PEM_write_X509_AUX, PEM_read_bio_X509_REQ, PEM_read_X509_REQ, PEM_write_bio_X509_REQ, PEM_write_X509_REQ, PEM_write_bio_X509_REQ_NEW, PEM_write_X509_REQ_NEW, PEM_read_bio_X509_CRL, PEM_read_X509_CRL, PEM_write_bio_X509_CRL, PEM_write_X509_CRL, PEM_read_bio_PKCS7, PEM_read_PKCS7, PEM_write_bio_PKCS7, PEM_write_PKCS7, PEM_read_bio_NETSCAPE_CERT_SEQUENCE, PEM_read_NETSCAPE_CERT_SEQUENCE, PEM_write_bio_NETSCAPE_CERT_SEQUENCE, PEM_write_NETSCAPE_CERT_SEQUENCE \- PEM routines
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+.Vb 1
+\& #include <openssl/pem.h>
+\&
+\& EVP_PKEY *PEM_read_bio_PrivateKey(BIO *bp, EVP_PKEY **x,
+\& pem_password_cb *cb, void *u);
+\&
+\& EVP_PKEY *PEM_read_PrivateKey(FILE *fp, EVP_PKEY **x,
+\& pem_password_cb *cb, void *u);
+\&
+\& int PEM_write_bio_PrivateKey(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc,
+\& unsigned char *kstr, int klen,
+\& pem_password_cb *cb, void *u);
+\&
+\& int PEM_write_PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc,
+\& unsigned char *kstr, int klen,
+\& pem_password_cb *cb, void *u);
+\&
+\& int PEM_write_bio_PKCS8PrivateKey(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc,
+\& char *kstr, int klen,
+\& pem_password_cb *cb, void *u);
+\&
+\& int PEM_write_PKCS8PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc,
+\& char *kstr, int klen,
+\& pem_password_cb *cb, void *u);
+\&
+\& int PEM_write_bio_PKCS8PrivateKey_nid(BIO *bp, EVP_PKEY *x, int nid,
+\& char *kstr, int klen,
+\& pem_password_cb *cb, void *u);
+\&
+\& int PEM_write_PKCS8PrivateKey_nid(FILE *fp, EVP_PKEY *x, int nid,
+\& char *kstr, int klen,
+\& pem_password_cb *cb, void *u);
+\&
+\& EVP_PKEY *PEM_read_bio_PUBKEY(BIO *bp, EVP_PKEY **x,
+\& pem_password_cb *cb, void *u);
+\&
+\& EVP_PKEY *PEM_read_PUBKEY(FILE *fp, EVP_PKEY **x,
+\& pem_password_cb *cb, void *u);
+\&
+\& int PEM_write_bio_PUBKEY(BIO *bp, EVP_PKEY *x);
+\& int PEM_write_PUBKEY(FILE *fp, EVP_PKEY *x);
+\&
+\& RSA *PEM_read_bio_RSAPrivateKey(BIO *bp, RSA **x,
+\& pem_password_cb *cb, void *u);
+\&
+\& RSA *PEM_read_RSAPrivateKey(FILE *fp, RSA **x,
+\& pem_password_cb *cb, void *u);
+\&
+\& int PEM_write_bio_RSAPrivateKey(BIO *bp, RSA *x, const EVP_CIPHER *enc,
+\& unsigned char *kstr, int klen,
+\& pem_password_cb *cb, void *u);
+\&
+\& int PEM_write_RSAPrivateKey(FILE *fp, RSA *x, const EVP_CIPHER *enc,
+\& unsigned char *kstr, int klen,
+\& pem_password_cb *cb, void *u);
+\&
+\& RSA *PEM_read_bio_RSAPublicKey(BIO *bp, RSA **x,
+\& pem_password_cb *cb, void *u);
+\&
+\& RSA *PEM_read_RSAPublicKey(FILE *fp, RSA **x,
+\& pem_password_cb *cb, void *u);
+\&
+\& int PEM_write_bio_RSAPublicKey(BIO *bp, RSA *x);
+\&
+\& int PEM_write_RSAPublicKey(FILE *fp, RSA *x);
+\&
+\& RSA *PEM_read_bio_RSA_PUBKEY(BIO *bp, RSA **x,
+\& pem_password_cb *cb, void *u);
+\&
+\& RSA *PEM_read_RSA_PUBKEY(FILE *fp, RSA **x,
+\& pem_password_cb *cb, void *u);
+\&
+\& int PEM_write_bio_RSA_PUBKEY(BIO *bp, RSA *x);
+\&
+\& int PEM_write_RSA_PUBKEY(FILE *fp, RSA *x);
+\&
+\& DSA *PEM_read_bio_DSAPrivateKey(BIO *bp, DSA **x,
+\& pem_password_cb *cb, void *u);
+\&
+\& DSA *PEM_read_DSAPrivateKey(FILE *fp, DSA **x,
+\& pem_password_cb *cb, void *u);
+\&
+\& int PEM_write_bio_DSAPrivateKey(BIO *bp, DSA *x, const EVP_CIPHER *enc,
+\& unsigned char *kstr, int klen,
+\& pem_password_cb *cb, void *u);
+\&
+\& int PEM_write_DSAPrivateKey(FILE *fp, DSA *x, const EVP_CIPHER *enc,
+\& unsigned char *kstr, int klen,
+\& pem_password_cb *cb, void *u);
+\&
+\& DSA *PEM_read_bio_DSA_PUBKEY(BIO *bp, DSA **x,
+\& pem_password_cb *cb, void *u);
+\&
+\& DSA *PEM_read_DSA_PUBKEY(FILE *fp, DSA **x,
+\& pem_password_cb *cb, void *u);
+\&
+\& int PEM_write_bio_DSA_PUBKEY(BIO *bp, DSA *x);
+\&
+\& int PEM_write_DSA_PUBKEY(FILE *fp, DSA *x);
+\&
+\& DSA *PEM_read_bio_DSAparams(BIO *bp, DSA **x, pem_password_cb *cb, void *u);
+\&
+\& DSA *PEM_read_DSAparams(FILE *fp, DSA **x, pem_password_cb *cb, void *u);
+\&
+\& int PEM_write_bio_DSAparams(BIO *bp, DSA *x);
+\&
+\& int PEM_write_DSAparams(FILE *fp, DSA *x);
+\&
+\& DH *PEM_read_bio_DHparams(BIO *bp, DH **x, pem_password_cb *cb, void *u);
+\&
+\& DH *PEM_read_DHparams(FILE *fp, DH **x, pem_password_cb *cb, void *u);
+\&
+\& int PEM_write_bio_DHparams(BIO *bp, DH *x);
+\&
+\& int PEM_write_DHparams(FILE *fp, DH *x);
+\&
+\& X509 *PEM_read_bio_X509(BIO *bp, X509 **x, pem_password_cb *cb, void *u);
+\&
+\& X509 *PEM_read_X509(FILE *fp, X509 **x, pem_password_cb *cb, void *u);
+\&
+\& int PEM_write_bio_X509(BIO *bp, X509 *x);
+\&
+\& int PEM_write_X509(FILE *fp, X509 *x);
+\&
+\& X509 *PEM_read_bio_X509_AUX(BIO *bp, X509 **x, pem_password_cb *cb, void *u);
+\&
+\& X509 *PEM_read_X509_AUX(FILE *fp, X509 **x, pem_password_cb *cb, void *u);
+\&
+\& int PEM_write_bio_X509_AUX(BIO *bp, X509 *x);
+\&
+\& int PEM_write_X509_AUX(FILE *fp, X509 *x);
+\&
+\& X509_REQ *PEM_read_bio_X509_REQ(BIO *bp, X509_REQ **x,
+\& pem_password_cb *cb, void *u);
+\&
+\& X509_REQ *PEM_read_X509_REQ(FILE *fp, X509_REQ **x,
+\& pem_password_cb *cb, void *u);
+\&
+\& int PEM_write_bio_X509_REQ(BIO *bp, X509_REQ *x);
+\&
+\& int PEM_write_X509_REQ(FILE *fp, X509_REQ *x);
+\&
+\& int PEM_write_bio_X509_REQ_NEW(BIO *bp, X509_REQ *x);
+\&
+\& int PEM_write_X509_REQ_NEW(FILE *fp, X509_REQ *x);
+\&
+\& X509_CRL *PEM_read_bio_X509_CRL(BIO *bp, X509_CRL **x,
+\& pem_password_cb *cb, void *u);
+\& X509_CRL *PEM_read_X509_CRL(FILE *fp, X509_CRL **x,
+\& pem_password_cb *cb, void *u);
+\& int PEM_write_bio_X509_CRL(BIO *bp, X509_CRL *x);
+\& int PEM_write_X509_CRL(FILE *fp, X509_CRL *x);
+\&
+\& PKCS7 *PEM_read_bio_PKCS7(BIO *bp, PKCS7 **x, pem_password_cb *cb, void *u);
+\&
+\& PKCS7 *PEM_read_PKCS7(FILE *fp, PKCS7 **x, pem_password_cb *cb, void *u);
+\&
+\& int PEM_write_bio_PKCS7(BIO *bp, PKCS7 *x);
+\&
+\& int PEM_write_PKCS7(FILE *fp, PKCS7 *x);
+\&
+\& NETSCAPE_CERT_SEQUENCE *PEM_read_bio_NETSCAPE_CERT_SEQUENCE(BIO *bp,
+\& NETSCAPE_CERT_SEQUENCE **x,
+\& pem_password_cb *cb, void *u);
+\&
+\& NETSCAPE_CERT_SEQUENCE *PEM_read_NETSCAPE_CERT_SEQUENCE(FILE *fp,
+\& NETSCAPE_CERT_SEQUENCE **x,
+\& pem_password_cb *cb, void *u);
+\&
+\& int PEM_write_bio_NETSCAPE_CERT_SEQUENCE(BIO *bp, NETSCAPE_CERT_SEQUENCE *x);
+\&
+\& int PEM_write_NETSCAPE_CERT_SEQUENCE(FILE *fp, NETSCAPE_CERT_SEQUENCE *x);
+.Ve
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+The \s-1PEM\s0 functions read or write structures in \s-1PEM\s0 format. In
+this sense \s-1PEM\s0 format is simply base64 encoded data surrounded
+by header lines.
+.PP
+For more details about the meaning of arguments see the
+\&\fB\s-1PEM\s0 \s-1FUNCTION\s0 \s-1ARGUMENTS\s0\fR section.
+.PP
+Each operation has four functions associated with it. For
+clarity the term "\fBfoobar\fR functions" will be used to collectively
+refer to the \fIPEM_read_bio_foobar()\fR, \fIPEM_read_foobar()\fR,
+\&\fIPEM_write_bio_foobar()\fR and \fIPEM_write_foobar()\fR functions.
+.PP
+The \fBPrivateKey\fR functions read or write a private key in
+\&\s-1PEM\s0 format using an \s-1EVP_PKEY\s0 structure. The write routines use
+\&\*(L"traditional\*(R" private key format and can handle both \s-1RSA\s0 and \s-1DSA\s0
+private keys. The read functions can additionally transparently
+handle PKCS#8 format encrypted and unencrypted keys too.
+.PP
+\&\fIPEM_write_bio_PKCS8PrivateKey()\fR and \fIPEM_write_PKCS8PrivateKey()\fR
+write a private key in an \s-1EVP_PKEY\s0 structure in PKCS#8
+EncryptedPrivateKeyInfo format using PKCS#5 v2.0 password based encryption
+algorithms. The \fBcipher\fR argument specifies the encryption algoritm to
+use: unlike all other \s-1PEM\s0 routines the encryption is applied at the
+PKCS#8 level and not in the \s-1PEM\s0 headers. If \fBcipher\fR is \s-1NULL\s0 then no
+encryption is used and a PKCS#8 PrivateKeyInfo structure is used instead.
+.PP
+\&\fIPEM_write_bio_PKCS8PrivateKey_nid()\fR and \fIPEM_write_PKCS8PrivateKey_nid()\fR
+also write out a private key as a PKCS#8 EncryptedPrivateKeyInfo however
+it uses PKCS#5 v1.5 or PKCS#12 encryption algorithms instead. The algorithm
+to use is specified in the \fBnid\fR parameter and should be the \s-1NID\s0 of the
+corresponding \s-1OBJECT\s0 \s-1IDENTIFIER\s0 (see \s-1NOTES\s0 section).
+.PP
+The \fB\s-1PUBKEY\s0\fR functions process a public key using an \s-1EVP_PKEY\s0
+structure. The public key is encoded as a SubjectPublicKeyInfo
+structure.
+.PP
+The \fBRSAPrivateKey\fR functions process an \s-1RSA\s0 private key using an
+\&\s-1RSA\s0 structure. It handles the same formats as the \fBPrivateKey\fR
+functions but an error occurs if the private key is not \s-1RSA\s0.
+.PP
+The \fBRSAPublicKey\fR functions process an \s-1RSA\s0 public key using an
+\&\s-1RSA\s0 structure. The public key is encoded using a PKCS#1 RSAPublicKey
+structure.
+.PP
+The \fB\s-1RSA_PUBKEY\s0\fR functions also process an \s-1RSA\s0 public key using
+an \s-1RSA\s0 structure. However the public key is encoded using a
+SubjectPublicKeyInfo structure and an error occurs if the public
+key is not \s-1RSA\s0.
+.PP
+The \fBDSAPrivateKey\fR functions process a \s-1DSA\s0 private key using a
+\&\s-1DSA\s0 structure. It handles the same formats as the \fBPrivateKey\fR
+functions but an error occurs if the private key is not \s-1DSA\s0.
+.PP
+The \fB\s-1DSA_PUBKEY\s0\fR functions process a \s-1DSA\s0 public key using
+a \s-1DSA\s0 structure. The public key is encoded using a
+SubjectPublicKeyInfo structure and an error occurs if the public
+key is not \s-1DSA\s0.
+.PP
+The \fBDSAparams\fR functions process \s-1DSA\s0 parameters using a \s-1DSA\s0
+structure. The parameters are encoded using a foobar structure.
+.PP
+The \fBDHparams\fR functions process \s-1DH\s0 parameters using a \s-1DH\s0
+structure. The parameters are encoded using a PKCS#3 DHparameter
+structure.
+.PP
+The \fBX509\fR functions process an X509 certificate using an X509
+structure. They will also process a trusted X509 certificate but
+any trust settings are discarded.
+.PP
+The \fBX509_AUX\fR functions process a trusted X509 certificate using
+an X509 structure.
+.PP
+The \fBX509_REQ\fR and \fBX509_REQ_NEW\fR functions process a PKCS#10
+certificate request using an X509_REQ structure. The \fBX509_REQ\fR
+write functions use \fB\s-1CERTIFICATE\s0 \s-1REQUEST\s0\fR in the header whereas
+the \fBX509_REQ_NEW\fR functions use \fB\s-1NEW\s0 \s-1CERTIFICATE\s0 \s-1REQUEST\s0\fR
+(as required by some CAs). The \fBX509_REQ\fR read functions will
+handle either form so there are no \fBX509_REQ_NEW\fR read functions.
+.PP
+The \fBX509_CRL\fR functions process an X509 \s-1CRL\s0 using an X509_CRL
+structure.
+.PP
+The \fB\s-1PKCS7\s0\fR functions process a PKCS#7 ContentInfo using a \s-1PKCS7\s0
+structure.
+.PP
+The \fB\s-1NETSCAPE_CERT_SEQUENCE\s0\fR functions process a Netscape Certificate
+Sequence using a \s-1NETSCAPE_CERT_SEQUENCE\s0 structure.
+.SH "PEM FUNCTION ARGUMENTS"
+.IX Header "PEM FUNCTION ARGUMENTS"
+The \s-1PEM\s0 functions have many common arguments.
+.PP
+The \fBbp\fR \s-1BIO\s0 parameter (if present) specifies the \s-1BIO\s0 to read from
+or write to.
+.PP
+The \fBfp\fR \s-1FILE\s0 parameter (if present) specifies the \s-1FILE\s0 pointer to
+read from or write to.
+.PP
+The \s-1PEM\s0 read functions all take an argument \fB\s-1TYPE\s0 **x\fR and return
+a \fB\s-1TYPE\s0 *\fR pointer. Where \fB\s-1TYPE\s0\fR is whatever structure the function
+uses. If \fBx\fR is \s-1NULL\s0 then the parameter is ignored. If \fBx\fR is not
+\&\s-1NULL\s0 but \fB*x\fR is \s-1NULL\s0 then the structure returned will be written
+to \fB*x\fR. If neither \fBx\fR nor \fB*x\fR is \s-1NULL\s0 then an attempt is made
+to reuse the structure at \fB*x\fR (but see \s-1BUGS\s0 and \s-1EXAMPLES\s0 sections).
+Irrespective of the value of \fBx\fR a pointer to the structure is always
+returned (or \s-1NULL\s0 if an error occurred).
+.PP
+The \s-1PEM\s0 functions which write private keys take an \fBenc\fR parameter
+which specifies the encryption algorithm to use, encryption is done
+at the \s-1PEM\s0 level. If this parameter is set to \s-1NULL\s0 then the private
+key is written in unencrypted form.
+.PP
+The \fBcb\fR argument is the callback to use when querying for the pass
+phrase used for encrypted \s-1PEM\s0 structures (normally only private keys).
+.PP
+For the \s-1PEM\s0 write routines if the \fBkstr\fR parameter is not \s-1NULL\s0 then
+\&\fBklen\fR bytes at \fBkstr\fR are used as the passphrase and \fBcb\fR is
+ignored.
+.PP
+If the \fBcb\fR parameters is set to \s-1NULL\s0 and the \fBu\fR parameter is not
+\&\s-1NULL\s0 then the \fBu\fR parameter is interpreted as a null terminated string
+to use as the passphrase. If both \fBcb\fR and \fBu\fR are \s-1NULL\s0 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 \s-1GUI\s0 application) so an alternative can be supplied. The callback
+routine has the following form:
+.PP
+.Vb 1
+\& int cb(char *buf, int size, int rwflag, void *u);
+.Ve
+.PP
+\&\fBbuf\fR is the buffer to write the passphrase to. \fBsize\fR is the maximum
+length of the passphrase (i.e. the size of buf). \fBrwflag\fR 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 \fBrwflag\fR is 1. The \fBu\fR parameter has the same
+value as the \fBu\fR parameter passed to the \s-1PEM\s0 routine. It allows
+arbitrary data to be passed to the callback by the application
+(for example a window handle in a \s-1GUI\s0 application). The callback
+\&\fBmust\fR return the number of characters in the passphrase or 0 if
+an error occurred.
+.SH "EXAMPLES"
+.IX Header "EXAMPLES"
+Although the \s-1PEM\s0 routines take several arguments in almost all applications
+most of them are set to 0 or \s-1NULL\s0.
+.PP
+Read a certificate in \s-1PEM\s0 format from a \s-1BIO:\s0
+.PP
+.Vb 6
+\& X509 *x;
+\& x = PEM_read_bio_X509(bp, NULL, 0, NULL);
+\& if (x == NULL)
+\& {
+\& /* Error */
+\& }
+.Ve
+.PP
+Alternative method:
+.PP
+.Vb 5
+\& X509 *x = NULL;
+\& if (!PEM_read_bio_X509(bp, &x, 0, NULL))
+\& {
+\& /* Error */
+\& }
+.Ve
+.PP
+Write a certificate to a \s-1BIO:\s0
+.PP
+.Vb 4
+\& if (!PEM_write_bio_X509(bp, x))
+\& {
+\& /* Error */
+\& }
+.Ve
+.PP
+Write an unencrypted private key to a \s-1FILE\s0 pointer:
+.PP
+.Vb 4
+\& if (!PEM_write_PrivateKey(fp, key, NULL, NULL, 0, 0, NULL))
+\& {
+\& /* Error */
+\& }
+.Ve
+.PP
+Write a private key (using traditional format) to a \s-1BIO\s0 using
+triple \s-1DES\s0 encryption, the pass phrase is prompted for:
+.PP
+.Vb 4
+\& if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, NULL))
+\& {
+\& /* Error */
+\& }
+.Ve
+.PP
+Write a private key (using PKCS#8 format) to a \s-1BIO\s0 using triple
+\&\s-1DES\s0 encryption, using the pass phrase \*(L"hello\*(R":
+.PP
+.Vb 4
+\& if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, "hello"))
+\& {
+\& /* Error */
+\& }
+.Ve
+.PP
+Read a private key from a \s-1BIO\s0 using the pass phrase \*(L"hello\*(R":
+.PP
+.Vb 5
+\& key = PEM_read_bio_PrivateKey(bp, NULL, 0, "hello");
+\& if (key == NULL)
+\& {
+\& /* Error */
+\& }
+.Ve
+.PP
+Read a private key from a \s-1BIO\s0 using a pass phrase callback:
+.PP
+.Vb 5
+\& key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key");
+\& if (key == NULL)
+\& {
+\& /* Error */
+\& }
+.Ve
+.PP
+Skeleton pass phrase callback:
+.PP
+.Vb 6
+\& int pass_cb(char *buf, int size, int rwflag, void *u);
+\& {
+\& int len;
+\& char *tmp;
+\& /* We\*(Aqd probably do something else if \*(Aqrwflag\*(Aq is 1 */
+\& printf("Enter pass phrase for \e"%s\e"\en", u);
+\&
+\& /* get pass phrase, length \*(Aqlen\*(Aq into \*(Aqtmp\*(Aq */
+\& 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;
+\& }
+.Ve
+.SH "NOTES"
+.IX Header "NOTES"
+The old \fBPrivateKey\fR write routines are retained for compatibility.
+New applications should write private keys using the
+\&\fIPEM_write_bio_PKCS8PrivateKey()\fR or \fIPEM_write_PKCS8PrivateKey()\fR 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 \fBPrivateKey\fR read routines can be used in all applications because
+they handle all formats transparently.
+.PP
+A frequent cause of problems is attempting to use the \s-1PEM\s0 routines like
+this:
+.PP
+.Vb 2
+\& X509 *x;
+\& PEM_read_bio_X509(bp, &x, 0, NULL);
+.Ve
+.PP
+this is a bug because an attempt will be made to reuse the data at \fBx\fR
+which is an uninitialised pointer.
+.SH "PEM ENCRYPTION FORMAT"
+.IX Header "PEM ENCRYPTION FORMAT"
+This old \fBPrivateKey\fR routines use a non standard technique for encryption.
+.PP
+The private key (or other data) takes the following form:
+.PP
+.Vb 3
+\& \-\-\-\-\-BEGIN RSA PRIVATE KEY\-\-\-\-\-
+\& Proc\-Type: 4,ENCRYPTED
+\& DEK\-Info: DES\-EDE3\-CBC,3F17F5316E2BAC89
+\&
+\& ...base64 encoded data...
+\& \-\-\-\-\-END RSA PRIVATE KEY\-\-\-\-\-
+.Ve
+.PP
+The line beginning DEK-Info contains two comma separated pieces of information:
+the encryption algorithm name as used by \fIEVP_get_cipherbyname()\fR and an 8
+byte \fBsalt\fR encoded as a set of hexadecimal digits.
+.PP
+After this is the base64 encoded encrypted data.
+.PP
+The encryption key is determined using \fIEVP_bytestokey()\fR, using \fBsalt\fR and an
+iteration count of 1. The \s-1IV\s0 used is the value of \fBsalt\fR and *not* the \s-1IV\s0
+returned by \fIEVP_bytestokey()\fR.
+.SH "BUGS"
+.IX Header "BUGS"
+The \s-1PEM\s0 read routines in some versions of OpenSSL will not correctly reuse
+an existing structure. Therefore the following:
+.PP
+.Vb 1
+\& PEM_read_bio_X509(bp, &x, 0, NULL);
+.Ve
+.PP
+where \fBx\fR already contains a valid certificate, may not work, whereas:
+.PP
+.Vb 2
+\& X509_free(x);
+\& x = PEM_read_bio_X509(bp, NULL, 0, NULL);
+.Ve
+.PP
+is guaranteed to work.
+.SH "RETURN CODES"
+.IX Header "RETURN CODES"
+The read routines return either a pointer to the structure read or \s-1NULL\s0
+if an error occurred.
+.PP
+The write routines return 1 for success or 0 for failure.
OpenPOWER on IntegriCloud