Upgrade to OpenSSL 0.9.8h.
[dragonfly.git] / secure / lib / libcrypto / man / pem.3
index 595e996..d1bb839 100644 (file)
@@ -1,4 +1,4 @@
-.\" Automatically generated by Pod::Man 2.12 (Pod::Simple 3.05)
+.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
 .\"
 .\" Standard preamble:
 .\" ========================================================================
 ..
 .\" 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-
+.\" double quote, and \*(R" will give a right double quote.  | will give a
+.\" real vertical bar.  \*(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-|\(bv\*(Tr
 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
 .ie n \{\
 .    ds -- \(*W-
 .    rr F
 .\}
 .\"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.hy 0
+.if n .na
+.\"
 .\" 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
 .\" ========================================================================
 .\"
 .IX Title "pem 3"
-.TH pem 3 "2007-10-24" "0.9.8g" "OpenSSL"
-.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
-.\" way too many mistakes in technical documents.
-.if n .ad l
-.nh
+.TH pem 3 "2008-09-06" "0.9.8h" "OpenSSL"
 .SH "NAME"
 PEM \- PEM routines
 .SH "SYNOPSIS"
 .IX Header "SYNOPSIS"
 .Vb 1
 \& #include <openssl/pem.h>
-\&
+.Ve
+.PP
+.Vb 2
 \& EVP_PKEY *PEM_read_bio_PrivateKey(BIO *bp, EVP_PKEY **x,
 \&                                        pem_password_cb *cb, void *u);
-\&
+.Ve
+.PP
+.Vb 2
 \& EVP_PKEY *PEM_read_PrivateKey(FILE *fp, EVP_PKEY **x,
 \&                                        pem_password_cb *cb, void *u);
-\&
+.Ve
+.PP
+.Vb 3
 \& 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);
-\&
+.Ve
+.PP
+.Vb 3
 \& int PEM_write_PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc,
 \&                                        unsigned char *kstr, int klen,
 \&                                        pem_password_cb *cb, void *u);
-\&
+.Ve
+.PP
+.Vb 3
 \& int PEM_write_bio_PKCS8PrivateKey(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc,
 \&                                        char *kstr, int klen,
 \&                                        pem_password_cb *cb, void *u);
-\&
+.Ve
+.PP
+.Vb 3
 \& int PEM_write_PKCS8PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc,
 \&                                        char *kstr, int klen,
 \&                                        pem_password_cb *cb, void *u);
-\&
+.Ve
+.PP
+.Vb 3
 \& int PEM_write_bio_PKCS8PrivateKey_nid(BIO *bp, EVP_PKEY *x, int nid,
 \&                                        char *kstr, int klen,
 \&                                        pem_password_cb *cb, void *u);
-\&
+.Ve
+.PP
+.Vb 3
 \& int PEM_write_PKCS8PrivateKey_nid(FILE *fp, EVP_PKEY *x, int nid,
 \&                                        char *kstr, int klen,
 \&                                        pem_password_cb *cb, void *u);
-\&
+.Ve
+.PP
+.Vb 2
 \& EVP_PKEY *PEM_read_bio_PUBKEY(BIO *bp, EVP_PKEY **x,
 \&                                        pem_password_cb *cb, void *u);
-\&
+.Ve
+.PP
+.Vb 2
 \& EVP_PKEY *PEM_read_PUBKEY(FILE *fp, EVP_PKEY **x,
 \&                                        pem_password_cb *cb, void *u);
-\&
+.Ve
+.PP
+.Vb 2
 \& int PEM_write_bio_PUBKEY(BIO *bp, EVP_PKEY *x);
 \& int PEM_write_PUBKEY(FILE *fp, EVP_PKEY *x);
-\&
+.Ve
+.PP
+.Vb 2
 \& RSA *PEM_read_bio_RSAPrivateKey(BIO *bp, RSA **x,
 \&                                        pem_password_cb *cb, void *u);
-\&
+.Ve
+.PP
+.Vb 2
 \& RSA *PEM_read_RSAPrivateKey(FILE *fp, RSA **x,
 \&                                        pem_password_cb *cb, void *u);
-\&
+.Ve
+.PP
+.Vb 3
 \& int PEM_write_bio_RSAPrivateKey(BIO *bp, RSA *x, const EVP_CIPHER *enc,
 \&                                        unsigned char *kstr, int klen,
 \&                                        pem_password_cb *cb, void *u);
-\&
+.Ve
+.PP
+.Vb 3
 \& int PEM_write_RSAPrivateKey(FILE *fp, RSA *x, const EVP_CIPHER *enc,
 \&                                        unsigned char *kstr, int klen,
 \&                                        pem_password_cb *cb, void *u);
-\&
+.Ve
+.PP
+.Vb 2
 \& RSA *PEM_read_bio_RSAPublicKey(BIO *bp, RSA **x,
 \&                                        pem_password_cb *cb, void *u);
-\&
+.Ve
+.PP
+.Vb 2
 \& RSA *PEM_read_RSAPublicKey(FILE *fp, RSA **x,
 \&                                        pem_password_cb *cb, void *u);
-\&
+.Ve
+.PP
+.Vb 1
 \& int PEM_write_bio_RSAPublicKey(BIO *bp, RSA *x);
-\&
+.Ve
+.PP
+.Vb 1
 \& int PEM_write_RSAPublicKey(FILE *fp, RSA *x);
-\&
+.Ve
+.PP
+.Vb 2
 \& RSA *PEM_read_bio_RSA_PUBKEY(BIO *bp, RSA **x,
 \&                                        pem_password_cb *cb, void *u);
-\&
+.Ve
+.PP
+.Vb 2
 \& RSA *PEM_read_RSA_PUBKEY(FILE *fp, RSA **x,
 \&                                        pem_password_cb *cb, void *u);
-\&
+.Ve
+.PP
+.Vb 1
 \& int PEM_write_bio_RSA_PUBKEY(BIO *bp, RSA *x);
-\&
+.Ve
+.PP
+.Vb 1
 \& int PEM_write_RSA_PUBKEY(FILE *fp, RSA *x);
-\&
+.Ve
+.PP
+.Vb 2
 \& DSA *PEM_read_bio_DSAPrivateKey(BIO *bp, DSA **x,
 \&                                        pem_password_cb *cb, void *u);
-\&
+.Ve
+.PP
+.Vb 2
 \& DSA *PEM_read_DSAPrivateKey(FILE *fp, DSA **x,
 \&                                        pem_password_cb *cb, void *u);
-\&
+.Ve
+.PP
+.Vb 3
 \& int PEM_write_bio_DSAPrivateKey(BIO *bp, DSA *x, const EVP_CIPHER *enc,
 \&                                        unsigned char *kstr, int klen,
 \&                                        pem_password_cb *cb, void *u);
-\&
+.Ve
+.PP
+.Vb 3
 \& int PEM_write_DSAPrivateKey(FILE *fp, DSA *x, const EVP_CIPHER *enc,
 \&                                        unsigned char *kstr, int klen,
 \&                                        pem_password_cb *cb, void *u);
-\&
+.Ve
+.PP
+.Vb 2
 \& DSA *PEM_read_bio_DSA_PUBKEY(BIO *bp, DSA **x,
 \&                                        pem_password_cb *cb, void *u);
-\&
+.Ve
+.PP
+.Vb 2
 \& DSA *PEM_read_DSA_PUBKEY(FILE *fp, DSA **x,
 \&                                        pem_password_cb *cb, void *u);
-\&
+.Ve
+.PP
+.Vb 1
 \& int PEM_write_bio_DSA_PUBKEY(BIO *bp, DSA *x);
-\&
+.Ve
+.PP
+.Vb 1
 \& int PEM_write_DSA_PUBKEY(FILE *fp, DSA *x);
-\&
+.Ve
+.PP
+.Vb 1
 \& DSA *PEM_read_bio_DSAparams(BIO *bp, DSA **x, pem_password_cb *cb, void *u);
-\&
+.Ve
+.PP
+.Vb 1
 \& DSA *PEM_read_DSAparams(FILE *fp, DSA **x, pem_password_cb *cb, void *u);
-\&
+.Ve
+.PP
+.Vb 1
 \& int PEM_write_bio_DSAparams(BIO *bp, DSA *x);
-\&
+.Ve
+.PP
+.Vb 1
 \& int PEM_write_DSAparams(FILE *fp, DSA *x);
-\&
+.Ve
+.PP
+.Vb 1
 \& DH *PEM_read_bio_DHparams(BIO *bp, DH **x, pem_password_cb *cb, void *u);
-\&
+.Ve
+.PP
+.Vb 1
 \& DH *PEM_read_DHparams(FILE *fp, DH **x, pem_password_cb *cb, void *u);
-\&
+.Ve
+.PP
+.Vb 1
 \& int PEM_write_bio_DHparams(BIO *bp, DH *x);
-\&
+.Ve
+.PP
+.Vb 1
 \& int PEM_write_DHparams(FILE *fp, DH *x);
-\&
+.Ve
+.PP
+.Vb 1
 \& X509 *PEM_read_bio_X509(BIO *bp, X509 **x, pem_password_cb *cb, void *u);
-\&
+.Ve
+.PP
+.Vb 1
 \& X509 *PEM_read_X509(FILE *fp, X509 **x, pem_password_cb *cb, void *u);
-\&
+.Ve
+.PP
+.Vb 1
 \& int PEM_write_bio_X509(BIO *bp, X509 *x);
-\&
+.Ve
+.PP
+.Vb 1
 \& int PEM_write_X509(FILE *fp, X509 *x);
-\&
+.Ve
+.PP
+.Vb 1
 \& X509 *PEM_read_bio_X509_AUX(BIO *bp, X509 **x, pem_password_cb *cb, void *u);
-\&
+.Ve
+.PP
+.Vb 1
 \& X509 *PEM_read_X509_AUX(FILE *fp, X509 **x, pem_password_cb *cb, void *u);
-\&
+.Ve
+.PP
+.Vb 1
 \& int PEM_write_bio_X509_AUX(BIO *bp, X509 *x);
-\&
+.Ve
+.PP
+.Vb 1
 \& int PEM_write_X509_AUX(FILE *fp, X509 *x);
-\&
+.Ve
+.PP
+.Vb 2
 \& X509_REQ *PEM_read_bio_X509_REQ(BIO *bp, X509_REQ **x,
 \&                                        pem_password_cb *cb, void *u);
-\&
+.Ve
+.PP
+.Vb 2
 \& X509_REQ *PEM_read_X509_REQ(FILE *fp, X509_REQ **x,
 \&                                        pem_password_cb *cb, void *u);
-\&
+.Ve
+.PP
+.Vb 1
 \& int PEM_write_bio_X509_REQ(BIO *bp, X509_REQ *x);
-\&
+.Ve
+.PP
+.Vb 1
 \& int PEM_write_X509_REQ(FILE *fp, X509_REQ *x);
-\&
+.Ve
+.PP
+.Vb 1
 \& int PEM_write_bio_X509_REQ_NEW(BIO *bp, X509_REQ *x);
-\&
+.Ve
+.PP
+.Vb 1
 \& int PEM_write_X509_REQ_NEW(FILE *fp, X509_REQ *x);
-\&
+.Ve
+.PP
+.Vb 6
 \& 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);
-\&
+.Ve
+.PP
+.Vb 1
 \& PKCS7 *PEM_read_bio_PKCS7(BIO *bp, PKCS7 **x, pem_password_cb *cb, void *u);
-\&
+.Ve
+.PP
+.Vb 1
 \& PKCS7 *PEM_read_PKCS7(FILE *fp, PKCS7 **x, pem_password_cb *cb, void *u);
-\&
+.Ve
+.PP
+.Vb 1
 \& int PEM_write_bio_PKCS7(BIO *bp, PKCS7 *x);
-\&
+.Ve
+.PP
+.Vb 1
 \& int PEM_write_PKCS7(FILE *fp, PKCS7 *x);
-\&
+.Ve
+.PP
+.Vb 3
 \& NETSCAPE_CERT_SEQUENCE *PEM_read_bio_NETSCAPE_CERT_SEQUENCE(BIO *bp,
 \&                                                NETSCAPE_CERT_SEQUENCE **x,
 \&                                                pem_password_cb *cb, void *u);
-\&
+.Ve
+.PP
+.Vb 3
 \& NETSCAPE_CERT_SEQUENCE *PEM_read_NETSCAPE_CERT_SEQUENCE(FILE *fp,
 \&                                                NETSCAPE_CERT_SEQUENCE **x,
 \&                                                pem_password_cb *cb, void *u);
-\&
+.Ve
+.PP
+.Vb 1
 \& int PEM_write_bio_NETSCAPE_CERT_SEQUENCE(BIO *bp, NETSCAPE_CERT_SEQUENCE *x);
-\&
+.Ve
+.PP
+.Vb 1
 \& int PEM_write_NETSCAPE_CERT_SEQUENCE(FILE *fp, NETSCAPE_CERT_SEQUENCE *x);
 .Ve
 .SH "DESCRIPTION"
@@ -378,7 +503,7 @@ 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.
+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
@@ -543,11 +668,15 @@ Skeleton pass phrase callback:
 \&        char *tmp;
 \&        /* We'd probably do something else if 'rwflag' is 1 */
 \&        printf("Enter pass phrase for \e"%s\e"\en", u);
-\&
+.Ve
+.PP
+.Vb 3
 \&        /* get pass phrase, length 'len' into 'tmp' */
 \&        tmp = "hello";
 \&        len = strlen(tmp);
-\&
+.Ve
+.PP
+.Vb 6
 \&        if (len <= 0) return 0;
 \&        /* if too long, truncate */
 \&        if (len > size) len = size;
@@ -581,15 +710,17 @@ which is an uninitialised pointer.
 .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:
+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
-\&
+\& -----BEGIN RSA PRIVATE KEY-----
+\& Proc-Type: 4,ENCRYPTED
+\& DEK-Info: DES-EDE3-CBC,3F17F5316E2BAC89
+.Ve
+.PP
+.Vb 2
 \& ...base64 encoded data...
-\& \-\-\-\-\-END RSA PRIVATE KEY\-\-\-\-\-
+\& -----END RSA PRIVATE KEY-----
 .Ve
 .PP
 The line beginning DEK-Info contains two comma separated pieces of information:
@@ -610,7 +741,7 @@ an existing structure. Therefore the following:
 \& PEM_read_bio_X509(bp, &x, 0, NULL);
 .Ve
 .PP
-where \fBx\fR already contains a valid certificate, may not work, whereas:
+where \fBx\fR already contains a valid certificate, may not work, whereas: 
 .PP
 .Vb 2
 \& X509_free(x);