494 lines
24 KiB
HTML
Executable File
494 lines
24 KiB
HTML
Executable File
<?xml version="1.0" ?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<title>PEM_read_bio_PrivateKey</title>
|
|
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
|
|
<link rev="made" href="mailto:root@localhost" />
|
|
</head>
|
|
|
|
<body style="background-color: white">
|
|
|
|
|
|
<!-- INDEX BEGIN -->
|
|
<div name="index">
|
|
<p><a name="__index__"></a></p>
|
|
|
|
<ul>
|
|
|
|
<li><a href="#name">NAME</a></li>
|
|
<li><a href="#synopsis">SYNOPSIS</a></li>
|
|
<li><a href="#description">DESCRIPTION</a></li>
|
|
<li><a href="#pem_function_arguments">PEM FUNCTION ARGUMENTS</a></li>
|
|
<li><a href="#notes">NOTES</a></li>
|
|
<li><a href="#pem_encryption_format">PEM ENCRYPTION FORMAT</a></li>
|
|
<li><a href="#bugs">BUGS</a></li>
|
|
<li><a href="#return_values">RETURN VALUES</a></li>
|
|
<li><a href="#examples">EXAMPLES</a></li>
|
|
<li><a href="#see_also">SEE ALSO</a></li>
|
|
<li><a href="#history">HISTORY</a></li>
|
|
<li><a href="#copyright">COPYRIGHT</a></li>
|
|
</ul>
|
|
|
|
<hr name="index" />
|
|
</div>
|
|
<!-- INDEX END -->
|
|
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="name">NAME</a></h1>
|
|
<p>pem_password_cb,
|
|
PEM_read_bio_PrivateKey, PEM_read_PrivateKey, PEM_write_bio_PrivateKey,
|
|
PEM_write_bio_PrivateKey_traditional, 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_Parameters, PEM_write_bio_Parameters,
|
|
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 routines</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="synopsis">SYNOPSIS</a></h1>
|
|
<pre>
|
|
#include <openssl/pem.h></pre>
|
|
<pre>
|
|
typedef int pem_password_cb(char *buf, int size, int rwflag, void *u);</pre>
|
|
<pre>
|
|
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, const EVP_PKEY *x, const EVP_CIPHER *enc,
|
|
unsigned char *kstr, int klen,
|
|
pem_password_cb *cb, void *u);
|
|
int PEM_write_bio_PrivateKey_traditional(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, const EVP_PKEY *x, int nid,
|
|
char *kstr, int klen,
|
|
pem_password_cb *cb, void *u);
|
|
int PEM_write_PKCS8PrivateKey_nid(FILE *fp, const EVP_PKEY *x, int nid,
|
|
char *kstr, int klen,
|
|
pem_password_cb *cb, void *u);</pre>
|
|
<pre>
|
|
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);</pre>
|
|
<pre>
|
|
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);</pre>
|
|
<pre>
|
|
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);</pre>
|
|
<pre>
|
|
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);</pre>
|
|
<pre>
|
|
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);</pre>
|
|
<pre>
|
|
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);</pre>
|
|
<pre>
|
|
EVP_PKEY *PEM_read_bio_Parameters(BIO *bp, EVP_PKEY **x);
|
|
int PEM_write_bio_Parameters(BIO *bp, const EVP_PKEY *x);</pre>
|
|
<pre>
|
|
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);</pre>
|
|
<pre>
|
|
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);</pre>
|
|
<pre>
|
|
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);</pre>
|
|
<pre>
|
|
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);</pre>
|
|
<pre>
|
|
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);</pre>
|
|
<pre>
|
|
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);</pre>
|
|
<pre>
|
|
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);</pre>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="description">DESCRIPTION</a></h1>
|
|
<p>The PEM functions read or write structures in PEM format. In
|
|
this sense PEM format is simply base64 encoded data surrounded
|
|
by header lines.</p>
|
|
<p>For more details about the meaning of arguments see the
|
|
<strong>PEM FUNCTION ARGUMENTS</strong> section.</p>
|
|
<p>Each operation has four functions associated with it. For
|
|
brevity the term "<strong><em>TYPE</em></strong> functions" will be used below to collectively
|
|
refer to the <strong>PEM_read_bio_<em>TYPE</em></strong>(), <strong>PEM_read_<em>TYPE</em></strong>(),
|
|
<strong>PEM_write_bio_<em>TYPE</em></strong>(), and <strong>PEM_write_<em>TYPE</em></strong>() functions.</p>
|
|
<p>The <strong>PrivateKey</strong> functions read or write a private key in PEM format using an
|
|
EVP_PKEY structure. The write routines use PKCS#8 private key format and are
|
|
equivalent to PEM_write_bio_PKCS8PrivateKey().The read functions transparently
|
|
handle traditional and PKCS#8 format encrypted and unencrypted keys.</p>
|
|
<p><code>PEM_write_bio_PrivateKey_traditional()</code> writes out a private key in the
|
|
"traditional" format with a simple private key marker and should only
|
|
be used for compatibility with legacy programs.</p>
|
|
<p>PEM_write_bio_PKCS8PrivateKey() and PEM_write_PKCS8PrivateKey() write a private
|
|
key in an EVP_PKEY structure in PKCS#8 EncryptedPrivateKeyInfo format using
|
|
PKCS#5 v2.0 password based encryption algorithms. The <em>cipher</em> argument
|
|
specifies the encryption algorithm to use: unlike some other PEM routines the
|
|
encryption is applied at the PKCS#8 level and not in the PEM headers. If
|
|
<em>cipher</em> is NULL then no encryption is used and a PKCS#8 PrivateKeyInfo
|
|
structure is used instead.</p>
|
|
<p>PEM_write_bio_PKCS8PrivateKey_nid() and PEM_write_PKCS8PrivateKey_nid()
|
|
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 <em>nid</em> parameter and should be the NID of the
|
|
corresponding OBJECT IDENTIFIER (see NOTES section).</p>
|
|
<p>The <strong>PUBKEY</strong> functions process a public key using an EVP_PKEY
|
|
structure. The public key is encoded as a SubjectPublicKeyInfo
|
|
structure.</p>
|
|
<p>The <strong>RSAPrivateKey</strong> functions process an RSA private key using an
|
|
RSA structure. The write routines uses traditional format. The read
|
|
routines handles the same formats as the <strong>PrivateKey</strong>
|
|
functions but an error occurs if the private key is not RSA.</p>
|
|
<p>The <strong>RSAPublicKey</strong> functions process an RSA public key using an
|
|
RSA structure. The public key is encoded using a PKCS#1 RSAPublicKey
|
|
structure.</p>
|
|
<p>The <strong>RSA_PUBKEY</strong> functions also process an RSA public key using
|
|
an RSA structure. However the public key is encoded using a
|
|
SubjectPublicKeyInfo structure and an error occurs if the public
|
|
key is not RSA.</p>
|
|
<p>The <strong>DSAPrivateKey</strong> functions process a DSA private key using a
|
|
DSA structure. The write routines uses traditional format. The read
|
|
routines handles the same formats as the <strong>PrivateKey</strong>
|
|
functions but an error occurs if the private key is not DSA.</p>
|
|
<p>The <strong>DSA_PUBKEY</strong> functions process a DSA public key using
|
|
a DSA structure. The public key is encoded using a
|
|
SubjectPublicKeyInfo structure and an error occurs if the public
|
|
key is not DSA.</p>
|
|
<p>The <strong>Parameters</strong> functions read or write key parameters in PEM format using
|
|
an EVP_PKEY structure. The encoding depends on the type of key; for DSA key
|
|
parameters, it will be a Dss-Parms structure as defined in <a href="http://www.ietf.org/rfc/rfc2459.txt" class="rfc">RFC2459</a>, and for DH
|
|
key parameters, it will be a PKCS#3 DHparameter structure. <em>These functions
|
|
only exist for the <strong>BIO</strong> type</em>.</p>
|
|
<p>The <strong>DSAparams</strong> functions process DSA parameters using a DSA
|
|
structure. The parameters are encoded using a Dss-Parms structure
|
|
as defined in <a href="http://www.ietf.org/rfc/rfc2459.txt" class="rfc">RFC2459</a>.</p>
|
|
<p>The <strong>DHparams</strong> functions process DH parameters using a DH
|
|
structure. The parameters are encoded using a PKCS#3 DHparameter
|
|
structure.</p>
|
|
<p>The <strong>X509</strong> functions process an X509 certificate using an X509
|
|
structure. They will also process a trusted X509 certificate but
|
|
any trust settings are discarded.</p>
|
|
<p>The <strong>X509_AUX</strong> functions process a trusted X509 certificate using
|
|
an X509 structure.</p>
|
|
<p>The <strong>X509_REQ</strong> and <strong>X509_REQ_NEW</strong> functions process a PKCS#10
|
|
certificate request using an X509_REQ structure. The <strong>X509_REQ</strong>
|
|
write functions use <strong>CERTIFICATE REQUEST</strong> in the header whereas
|
|
the <strong>X509_REQ_NEW</strong> functions use <strong>NEW CERTIFICATE REQUEST</strong>
|
|
(as required by some CAs). The <strong>X509_REQ</strong> read functions will
|
|
handle either form so there are no <strong>X509_REQ_NEW</strong> read functions.</p>
|
|
<p>The <strong>X509_CRL</strong> functions process an X509 CRL using an X509_CRL
|
|
structure.</p>
|
|
<p>The <strong>PKCS7</strong> functions process a PKCS#7 ContentInfo using a PKCS7
|
|
structure.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="pem_function_arguments">PEM FUNCTION ARGUMENTS</a></h1>
|
|
<p>The PEM functions have many common arguments.</p>
|
|
<p>The <em>bp</em> BIO parameter (if present) specifies the BIO to read from
|
|
or write to.</p>
|
|
<p>The <em>fp</em> FILE parameter (if present) specifies the FILE pointer to
|
|
read from or write to.</p>
|
|
<p>The PEM read functions all take an argument <em><strong>TYPE</strong> **x</em> and return
|
|
a <em><strong>TYPE</strong> *</em> pointer. Where <em><strong>TYPE</strong></em> is whatever structure the function
|
|
uses. If <em>x</em> is NULL then the parameter is ignored. If <em>x</em> is not
|
|
NULL but <em>*x</em> is NULL then the structure returned will be written
|
|
to <em>*x</em>. If neither <em>x</em> nor <em>*x</em> is NULL then an attempt is made
|
|
to reuse the structure at <em>*x</em> (but see BUGS and EXAMPLES sections).
|
|
Irrespective of the value of <em>x</em> a pointer to the structure is always
|
|
returned (or NULL if an error occurred).</p>
|
|
<p>The PEM functions which write private keys take an <em>enc</em> parameter
|
|
which specifies the encryption algorithm to use, encryption is done
|
|
at the PEM level. If this parameter is set to NULL then the private
|
|
key is written in unencrypted form.</p>
|
|
<p>The <em>cb</em> argument is the callback to use when querying for the pass
|
|
phrase used for encrypted PEM structures (normally only private keys).</p>
|
|
<p>For the PEM write routines if the <em>kstr</em> parameter is not NULL then
|
|
<em>klen</em> bytes at <em>kstr</em> are used as the passphrase and <em>cb</em> is
|
|
ignored.</p>
|
|
<p>If the <em>cb</em> parameters is set to NULL and the <em>u</em> parameter is not
|
|
NULL then the <em>u</em> parameter is interpreted as a null terminated string
|
|
to use as the passphrase. If both <em>cb</em> and <em>u</em> are NULL then the
|
|
default callback routine is used which will typically prompt for the
|
|
passphrase on the current terminal with echoing turned off.</p>
|
|
<p>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:</p>
|
|
<pre>
|
|
int cb(char *buf, int size, int rwflag, void *u);</pre>
|
|
<p><em>buf</em> is the buffer to write the passphrase to. <em>size</em> is the maximum
|
|
length of the passphrase (i.e. the size of buf). <em>rwflag</em> 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 <em>rwflag</em> is 1. The <em>u</em> parameter has the same
|
|
value as the <em>u</em> 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
|
|
<em>must</em> return the number of characters in the passphrase or -1 if
|
|
an error occurred.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="notes">NOTES</a></h1>
|
|
<p>The old <strong>PrivateKey</strong> write routines are retained for compatibility.
|
|
New applications should write private keys using the
|
|
PEM_write_bio_PKCS8PrivateKey() or 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.</p>
|
|
<p>The <strong>PrivateKey</strong> read routines can be used in all applications because
|
|
they handle all formats transparently.</p>
|
|
<p>A frequent cause of problems is attempting to use the PEM routines like
|
|
this:</p>
|
|
<pre>
|
|
X509 *x;</pre>
|
|
<pre>
|
|
PEM_read_bio_X509(bp, &x, 0, NULL);</pre>
|
|
<p>this is a bug because an attempt will be made to reuse the data at <em>x</em>
|
|
which is an uninitialised pointer.</p>
|
|
<p>These functions make no assumption regarding the pass phrase received from the
|
|
password callback.
|
|
It will simply be treated as a byte sequence.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="pem_encryption_format">PEM ENCRYPTION FORMAT</a></h1>
|
|
<p>These old <strong>PrivateKey</strong> routines use a non standard technique for encryption.</p>
|
|
<p>The private key (or other data) takes the following form:</p>
|
|
<pre>
|
|
-----BEGIN RSA PRIVATE KEY-----
|
|
Proc-Type: 4,ENCRYPTED
|
|
DEK-Info: DES-EDE3-CBC,3F17F5316E2BAC89</pre>
|
|
<pre>
|
|
...base64 encoded data...
|
|
-----END RSA PRIVATE KEY-----</pre>
|
|
<p>The line beginning with <em>Proc-Type</em> contains the version and the
|
|
protection on the encapsulated data. The line beginning <em>DEK-Info</em>
|
|
contains two comma separated values: the encryption algorithm name as
|
|
used by <code>EVP_get_cipherbyname()</code> and an initialization vector used by the
|
|
cipher encoded as a set of hexadecimal digits. After those two lines is
|
|
the base64-encoded encrypted data.</p>
|
|
<p>The encryption key is derived using <code>EVP_BytesToKey()</code>. The cipher's
|
|
initialization vector is passed to <code>EVP_BytesToKey()</code> as the <em>salt</em>
|
|
parameter. Internally, <strong>PKCS5_SALT_LEN</strong> bytes of the salt are used
|
|
(regardless of the size of the initialization vector). The user's
|
|
password is passed to <code>EVP_BytesToKey()</code> using the <em>data</em> and <em>datal</em>
|
|
parameters. Finally, the library uses an iteration count of 1 for
|
|
<code>EVP_BytesToKey()</code>.</p>
|
|
<p>The <em>key</em> derived by <code>EVP_BytesToKey()</code> along with the original initialization
|
|
vector is then used to decrypt the encrypted data. The <em>iv</em> produced by
|
|
<code>EVP_BytesToKey()</code> is not utilized or needed, and NULL should be passed to
|
|
the function.</p>
|
|
<p>The pseudo code to derive the key would look similar to:</p>
|
|
<pre>
|
|
EVP_CIPHER* cipher = EVP_des_ede3_cbc();
|
|
EVP_MD* md = EVP_md5();</pre>
|
|
<pre>
|
|
unsigned int nkey = EVP_CIPHER_key_length(cipher);
|
|
unsigned int niv = EVP_CIPHER_iv_length(cipher);
|
|
unsigned char key[nkey];
|
|
unsigned char iv[niv];</pre>
|
|
<pre>
|
|
memcpy(iv, HexToBin("3F17F5316E2BAC89"), niv);
|
|
rc = EVP_BytesToKey(cipher, md, iv /*salt*/, pword, plen, 1, key, NULL /*iv*/);
|
|
if (rc != nkey)
|
|
/* Error */</pre>
|
|
<pre>
|
|
/* On success, use key and iv to initialize the cipher */</pre>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="bugs">BUGS</a></h1>
|
|
<p>The PEM read routines in some versions of OpenSSL will not correctly reuse
|
|
an existing structure. Therefore the following:</p>
|
|
<pre>
|
|
PEM_read_bio_X509(bp, &x, 0, NULL);</pre>
|
|
<p>where <em>x</em> already contains a valid certificate, may not work, whereas:</p>
|
|
<pre>
|
|
X509_free(x);
|
|
x = PEM_read_bio_X509(bp, NULL, 0, NULL);</pre>
|
|
<p>is guaranteed to work.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="return_values">RETURN VALUES</a></h1>
|
|
<p>The read routines return either a pointer to the structure read or NULL
|
|
if an error occurred.</p>
|
|
<p>The write routines return 1 for success or 0 for failure.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="examples">EXAMPLES</a></h1>
|
|
<p>Although the PEM routines take several arguments in almost all applications
|
|
most of them are set to 0 or NULL.</p>
|
|
<p>Read a certificate in PEM format from a BIO:</p>
|
|
<pre>
|
|
X509 *x;</pre>
|
|
<pre>
|
|
x = PEM_read_bio_X509(bp, NULL, 0, NULL);
|
|
if (x == NULL)
|
|
/* Error */</pre>
|
|
<p>Alternative method:</p>
|
|
<pre>
|
|
X509 *x = NULL;</pre>
|
|
<pre>
|
|
if (!PEM_read_bio_X509(bp, &x, 0, NULL))
|
|
/* Error */</pre>
|
|
<p>Write a certificate to a BIO:</p>
|
|
<pre>
|
|
if (!PEM_write_bio_X509(bp, x))
|
|
/* Error */</pre>
|
|
<p>Write a private key (using traditional format) to a BIO using
|
|
triple DES encryption, the pass phrase is prompted for:</p>
|
|
<pre>
|
|
if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, NULL))
|
|
/* Error */</pre>
|
|
<p>Write a private key (using PKCS#8 format) to a BIO using triple
|
|
DES encryption, using the pass phrase "hello":</p>
|
|
<pre>
|
|
if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(),
|
|
NULL, 0, 0, "hello"))
|
|
/* Error */</pre>
|
|
<p>Read a private key from a BIO using a pass phrase callback:</p>
|
|
<pre>
|
|
key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key");
|
|
if (key == NULL)
|
|
/* Error */</pre>
|
|
<p>Skeleton pass phrase callback:</p>
|
|
<pre>
|
|
int pass_cb(char *buf, int size, int rwflag, void *u)
|
|
{</pre>
|
|
<pre>
|
|
/* We'd probably do something else if 'rwflag' is 1 */
|
|
printf("Enter pass phrase for \"%s\"\n", (char *)u);</pre>
|
|
<pre>
|
|
/* get pass phrase, length 'len' into 'tmp' */
|
|
char *tmp = "hello";
|
|
if (tmp == NULL) /* An error occurred */
|
|
return -1;</pre>
|
|
<pre>
|
|
size_t len = strlen(tmp);</pre>
|
|
<pre>
|
|
if (len > size)
|
|
len = size;
|
|
memcpy(buf, tmp, len);
|
|
return len;
|
|
}</pre>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="see_also">SEE ALSO</a></h1>
|
|
<p><em>EVP_EncryptInit(3)</em>, <em>EVP_BytesToKey(3)</em>,
|
|
<em>passphrase-encoding(7)</em></p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="history">HISTORY</a></h1>
|
|
<p>The old Netscape certificate sequences were no longer documented
|
|
in OpenSSL 1.1.0; applications should use the PKCS7 standard instead
|
|
as they will be formally deprecated in a future releases.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="copyright">COPYRIGHT</a></h1>
|
|
<p>Copyright 2001-2019 The OpenSSL Project Authors. All Rights Reserved.</p>
|
|
<p>Licensed under the Apache License 2.0 (the "License"). You may not use
|
|
this file except in compliance with the License. You can obtain a copy
|
|
in the file LICENSE in the source distribution or at
|
|
<a href="https://www.openssl.org/source/license.html">https://www.openssl.org/source/license.html</a>.</p>
|
|
|
|
</body>
|
|
|
|
</html>
|