Server : Apache System : Linux server.lienzindia.com 4.18.0-348.7.1.el8_5.x86_64 #1 SMP Wed Dec 22 13:25:12 UTC 2021 x86_64 User : plutus ( 1007) PHP Version : 7.4.33 Disable Function : NONE Directory : /usr/local/emps/share/doc/openssl/html/man3/ |
Upload 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>d2i_RSAPrivateKey</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"> <ul id="index"> <li><a href="#NAME">NAME</a></li> <li><a href="#SYNOPSIS">SYNOPSIS</a></li> <li><a href="#DESCRIPTION">DESCRIPTION</a> <ul> <li><a href="#Migration">Migration</a> <ul> <li><a href="#Migrating-i2d-functions-to-OSSL_ENCODER">Migrating i2d functions to OSSL_ENCODER</a></li> </ul> </li> </ul> </li> <li><a href="#NOTES">NOTES</a></li> <li><a href="#RETURN-VALUES">RETURN VALUES</a></li> <li><a href="#SEE-ALSO">SEE ALSO</a></li> <li><a href="#COPYRIGHT">COPYRIGHT</a></li> </ul> <h1 id="NAME">NAME</h1> <p>d2i_DSAPrivateKey, d2i_DSAPrivateKey_bio, d2i_DSAPrivateKey_fp, d2i_DSAPublicKey, d2i_DSA_PUBKEY, d2i_DSA_PUBKEY_bio, d2i_DSA_PUBKEY_fp, d2i_DSAparams, d2i_RSAPrivateKey, d2i_RSAPrivateKey_bio, d2i_RSAPrivateKey_fp, d2i_RSAPublicKey, d2i_RSAPublicKey_bio, d2i_RSAPublicKey_fp, d2i_RSA_PUBKEY, d2i_RSA_PUBKEY_bio, d2i_RSA_PUBKEY_fp, d2i_DHparams, d2i_DHparams_bio, d2i_DHparams_fp, d2i_ECPKParameters, d2i_ECParameters, d2i_ECPrivateKey, d2i_ECPrivateKey_bio, d2i_ECPrivateKey_fp, d2i_EC_PUBKEY, d2i_EC_PUBKEY_bio, d2i_EC_PUBKEY_fp, i2d_RSAPrivateKey, i2d_RSAPrivateKey_bio, i2d_RSAPrivateKey_fp, i2d_RSAPublicKey, i2d_RSAPublicKey_bio, i2d_RSAPublicKey_fp, i2d_RSA_PUBKEY, i2d_RSA_PUBKEY_bio, i2d_RSA_PUBKEY_fp, i2d_DHparams, i2d_DHparams_bio, i2d_DHparams_fp, i2d_DSAPrivateKey, i2d_DSAPrivateKey_bio, i2d_DSAPrivateKey_fp, i2d_DSAPublicKey, i2d_DSA_PUBKEY, i2d_DSA_PUBKEY_bio, i2d_DSA_PUBKEY_fp, i2d_DSAparams, i2d_ECPKParameters, i2d_ECParameters, i2d_ECPrivateKey, i2d_ECPrivateKey_bio, i2d_ECPrivateKey_fp, i2d_EC_PUBKEY, i2d_EC_PUBKEY_bio, i2d_EC_PUBKEY_fp - DEPRECATED</p> <h1 id="SYNOPSIS">SYNOPSIS</h1> <p>The following functions have been deprecated since OpenSSL 3.0, and can be hidden entirely by defining <b>OPENSSL_API_COMPAT</b> with a suitable version value, see <a href="../man7/openssl_user_macros.html">openssl_user_macros(7)</a>:</p> <pre><code> TYPE *d2i_TYPEPrivateKey(TYPE **a, const unsigned char **ppin, long length); TYPE *d2i_TYPEPrivateKey_bio(BIO *bp, TYPE **a); TYPE *d2i_TYPEPrivateKey_fp(FILE *fp, TYPE **a); TYPE *d2i_TYPEPublicKey(TYPE **a, const unsigned char **ppin, long length); TYPE *d2i_TYPEPublicKey_bio(BIO *bp, TYPE **a); TYPE *d2i_TYPEPublicKey_fp(FILE *fp, TYPE **a); TYPE *d2i_TYPEparams(TYPE **a, const unsigned char **ppin, long length); TYPE *d2i_TYPEparams_bio(BIO *bp, TYPE **a); TYPE *d2i_TYPEparams_fp(FILE *fp, TYPE **a); TYPE *d2i_TYPE_PUBKEY(TYPE **a, const unsigned char **ppin, long length); TYPE *d2i_TYPE_PUBKEY_bio(BIO *bp, TYPE **a); TYPE *d2i_TYPE_PUBKEY_fp(FILE *fp, TYPE **a); int i2d_TYPEPrivateKey(const TYPE *a, unsigned char **ppout); int i2d_TYPEPrivateKey(TYPE *a, unsigned char **ppout); int i2d_TYPEPrivateKey_fp(FILE *fp, const TYPE *a); int i2d_TYPEPrivateKey_fp(FILE *fp, TYPE *a); int i2d_TYPEPrivateKey_bio(BIO *bp, const TYPE *a); int i2d_TYPEPrivateKey_bio(BIO *bp, TYPE *a); int i2d_TYPEPublicKey(const TYPE *a, unsigned char **ppout); int i2d_TYPEPublicKey(TYPE *a, unsigned char **ppout); int i2d_TYPEPublicKey_fp(FILE *fp, const TYPE *a); int i2d_TYPEPublicKey_fp(FILE *fp, TYPE *a); int i2d_TYPEPublicKey_bio(BIO *bp, const TYPE *a); int i2d_TYPEPublicKey_bio(BIO *bp, TYPE *a); int i2d_TYPEparams(const TYPE *a, unsigned char **ppout); int i2d_TYPEparams(TYPE *a, unsigned char **ppout); int i2d_TYPEparams_fp(FILE *fp, const TYPE *a); int i2d_TYPEparams_fp(FILE *fp, TYPE *a); int i2d_TYPEparams_bio(BIO *bp, const TYPE *a); int i2d_TYPEparams_bio(BIO *bp, TYPE *a); int i2d_TYPE_PUBKEY(const TYPE *a, unsigned char **ppout); int i2d_TYPE_PUBKEY(TYPE *a, unsigned char **ppout); int i2d_TYPE_PUBKEY_fp(FILE *fp, const TYPE *a); int i2d_TYPE_PUBKEY_fp(FILE *fp, TYPE *a); int i2d_TYPE_PUBKEY_bio(BIO *bp, const TYPE *a); int i2d_TYPE_PUBKEY_bio(BIO *bp, TYPE *a);</code></pre> <h1 id="DESCRIPTION">DESCRIPTION</h1> <p>All functions described here are deprecated. Please use <a href="../man3/OSSL_DECODER.html">OSSL_DECODER(3)</a> instead of the <b>d2i</b> functions and <a href="../man3/OSSL_ENCODER.html">OSSL_ENCODER(3)</a> instead of the <b>i2d</b> functions. See <a href="#Migration">"Migration"</a> below.</p> <p>In the description here, <b><i>TYPE</i></b> is used a placeholder for any of the OpenSSL datatypes, such as <b>RSA</b>. The function parameters <i>ppin</i> and <i>ppout</i> are generally either both named <i>pp</i> in the headers, or <i>in</i> and <i>out</i>.</p> <p>All the functions here behave the way that's described in <a href="../man3/d2i_X509.html">d2i_X509(3)</a>.</p> <p>Please note that not all functions in the synopsis are available for all key types. For example, there are no d2i_RSAparams() or i2d_RSAparams(), because the PKCS#1 <b>RSA</b> structure doesn't include any key parameters.</p> <p><b>d2i_<i>TYPE</i>PrivateKey</b>() and derivates thereof decode DER encoded <b><i>TYPE</i></b> private key data organized in a type specific structure.</p> <p><b>d2i_<i>TYPE</i>PublicKey</b>() and derivates thereof decode DER encoded <b><i>TYPE</i></b> public key data organized in a type specific structure.</p> <p><b>d2i_<i>TYPE</i>params</b>() and derivates thereof decode DER encoded <b><i>TYPE</i></b> key parameters organized in a type specific structure.</p> <p><b>d2i_<i>TYPE</i>_PUBKEY</b>() and derivates thereof decode DER encoded <b><i>TYPE</i></b> public key data organized in a <b>SubjectPublicKeyInfo</b> structure.</p> <p><b>i2d_<i>TYPE</i>PrivateKey</b>() and derivates thereof encode the private key <b><i>TYPE</i></b> data into a type specific DER encoded structure.</p> <p><b>i2d_<i>TYPE</i>PublicKey</b>() and derivates thereof encode the public key <b><i>TYPE</i></b> data into a type specific DER encoded structure.</p> <p><b>i2d_<i>TYPE</i>params</b>() and derivates thereof encode the <b><i>TYPE</i></b> key parameters data into a type specific DER encoded structure.</p> <p><b>i2d_<i>TYPE</i>_PUBKEY</b>() and derivates thereof encode the public key <b><i>TYPE</i></b> data into a DER encoded <b>SubjectPublicKeyInfo</b> structure.</p> <p>For example, d2i_RSAPrivateKey() and d2i_RSAPublicKey() expects the structure defined by PKCS#1. Similarly, i2d_RSAPrivateKey() and i2d_RSAPublicKey() produce DER encoded string organized according to PKCS#1.</p> <h2 id="Migration">Migration</h2> <p>Migration from the diverse <b><i>TYPE</i></b>s requires using corresponding new OpenSSL types. For all <b><i>TYPE</i></b>s described here, the corresponding new type is <b>EVP_PKEY</b>. The rest of this section assumes that this has been done, exactly how to do that is described elsewhere.</p> <p>There are two migration paths:</p> <ul> <li><p>Replace b<d2i_<i>TYPE</i>PrivateKey()> with <a href="../man3/d2i_PrivateKey.html">d2i_PrivateKey(3)</a>, b<d2i_<i>TYPE</i>PublicKey()> with <a href="../man3/d2i_PublicKey.html">d2i_PublicKey(3)</a>, b<d2i_<i>TYPE</i>params()> with <a href="../man3/d2i_KeyParams.html">d2i_KeyParams(3)</a>, b<d2i_<i>TYPE</i>_PUBKEY()> with <a href="../man3/d2i_PUBKEY.html">d2i_PUBKEY(3)</a>, b<i2d_<i>TYPE</i>PrivateKey()> with <a href="../man3/i2d_PrivateKey.html">i2d_PrivateKey(3)</a>, b<i2d_<i>TYPE</i>PublicKey()> with <a href="../man3/i2d_PublicKey.html">i2d_PublicKey(3)</a>, b<i2d_<i>TYPE</i>params()> with <a href="../man3/i2d_KeyParams.html">i2d_KeyParams(3)</a>, b<i2d_<i>TYPE</i>_PUBKEY()> with <a href="../man3/i2d_PUBKEY.html">i2d_PUBKEY(3)</a>. A caveat is that <a href="../man3/i2d_PrivateKey.html">i2d_PrivateKey(3)</a> may output a DER encoded PKCS#8 outermost structure instead of the type specific structure, and that <a href="../man3/d2i_PrivateKey.html">d2i_PrivateKey(3)</a> recognises and unpacks a PKCS#8 structures.</p> </li> <li><p>Use <a href="../man3/OSSL_DECODER.html">OSSL_DECODER(3)</a> and <a href="../man3/OSSL_ENCODER.html">OSSL_ENCODER(3)</a>. How to migrate is described below. All those descriptions assume that the key to be encoded is in the variable <i>pkey</i>.</p> </li> </ul> <h3 id="Migrating-i2d-functions-to-OSSL_ENCODER">Migrating <b>i2d</b> functions to <b>OSSL_ENCODER</b></h3> <p>The exact <a href="../man3/OSSL_ENCODER.html">OSSL_ENCODER(3)</a> output is driven by arguments rather than by function names. The sample code to get DER encoded output in a type specific structure is uniform, the only things that vary are the selection of what part of the <b>EVP_PKEY</b> should be output, and the structure. The <b>i2d</b> functions names can therefore be translated into two variables, <i>selection</i> and <i>structure</i> as follows:</p> <dl> <dt id="i2d_TYPEPrivateKey-translates-into"><b>i2d_<i>TYPE</i>PrivateKey</b>() translates into:</dt> <dd> <pre><code> int selection = EVP_PKEY_PRIVATE_KEY; const char *structure = "type-specific";</code></pre> </dd> <dt id="i2d_TYPEPublicKey-translates-into"><b>i2d_<i>TYPE</i>PublicKey</b>() translates into:</dt> <dd> <pre><code> int selection = EVP_PKEY_PUBLIC_KEY; const char *structure = "type-specific";</code></pre> </dd> <dt id="i2d_TYPEparams-translates-into"><b>i2d_<i>TYPE</i>params</b>() translates into:</dt> <dd> <pre><code> int selection = EVP_PKEY_PARAMETERS; const char *structure = "type-specific";</code></pre> </dd> <dt id="i2d_TYPE_PUBKEY-translates-into"><b>i2d_<i>TYPE</i>_PUBKEY</b>() translates into:</dt> <dd> <pre><code> int selection = EVP_PKEY_PUBLIC_KEY; const char *structure = "SubjectPublicKeyInfo";</code></pre> </dd> </dl> <p>The following sample code does the rest of the work:</p> <pre><code> unsigned char *p = buffer; /* |buffer| is supplied by the caller */ size_t len = buffer_size; /* assumed be the size of |buffer| */ OSSL_ENCODER_CTX *ctx = OSSL_ENCODER_CTX_new_for_pkey(pkey, selection, "DER", structure, NULL, NULL); if (ctx == NULL) { /* fatal error handling */ } if (OSSL_ENCODER_CTX_get_num_encoders(ctx) == 0) { OSSL_ENCODER_CTX_free(ctx); /* non-fatal error handling */ } if (!OSSL_ENCODER_to_data(ctx, &p, &len)) { OSSL_ENCODER_CTX_free(ctx); /* error handling */ } OSSL_ENCODER_CTX_free(ctx);</code></pre> <h1 id="NOTES">NOTES</h1> <p>The letters <b>i</b> and <b>d</b> in <b>i2d_<i>TYPE</i></b>() stand for "internal" (that is, an internal C structure) and "DER" respectively. So <b>i2d_<i>TYPE</i></b>() converts from internal to DER.</p> <p>The functions can also understand <b>BER</b> forms.</p> <p>The actual TYPE structure passed to <b>i2d_<i>TYPE</i></b>() must be a valid populated <b><i>TYPE</i></b> structure -- it <b>cannot</b> simply be fed with an empty structure such as that returned by TYPE_new().</p> <p>The encoded data is in binary form and may contain embedded zeros. Therefore, any FILE pointers or BIOs should be opened in binary mode. Functions such as strlen() will <b>not</b> return the correct length of the encoded structure.</p> <p>The ways that <i>*ppin</i> and <i>*ppout</i> are incremented after the operation can trap the unwary. See the <b>WARNINGS</b> section in <a href="../man3/d2i_X509.html">d2i_X509(3)</a> for some common errors. The reason for this-auto increment behaviour is to reflect a typical usage of ASN1 functions: after one structure is encoded or decoded another will be processed after it.</p> <p>The following points about the data types might be useful:</p> <dl> <dt id="DSA_PUBKEY"><b>DSA_PUBKEY</b></dt> <dd> <p>Represents a DSA public key using a <b>SubjectPublicKeyInfo</b> structure.</p> </dd> <dt id="DSAPublicKey-DSAPrivateKey"><b>DSAPublicKey</b>, <b>DSAPrivateKey</b></dt> <dd> <p>Use a non-standard OpenSSL format and should be avoided; use <b>DSA_PUBKEY</b>, <a href="../man3/PEM_write_PrivateKey.html">PEM_write_PrivateKey(3)</a>, or similar instead.</p> </dd> </dl> <h1 id="RETURN-VALUES">RETURN VALUES</h1> <p><b>d2i_<i>TYPE</i></b>(), <b>d2i_<i>TYPE</i>_bio</b>() and <b>d2i_<i>TYPE</i>_fp</b>() return a valid <b><i>TYPE</i></b> structure or NULL if an error occurs. If the "reuse" capability has been used with a valid structure being passed in via <i>a</i>, then the object is freed in the event of error and <i>*a</i> is set to NULL.</p> <p><b>i2d_<i>TYPE</i></b>() returns the number of bytes successfully encoded or a negative value if an error occurs.</p> <p><b>i2d_<i>TYPE</i>_bio</b>() and <b>i2d_<i>TYPE</i>_fp</b>() return 1 for success and 0 if an error occurs.</p> <h1 id="SEE-ALSO">SEE ALSO</h1> <p><a href="../man3/OSSL_ENCODER.html">OSSL_ENCODER(3)</a>, <a href="../man3/OSSL_DECODER.html">OSSL_DECODER(3)</a>, <a href="../man3/d2i_PrivateKey.html">d2i_PrivateKey(3)</a>, <a href="../man3/d2i_PublicKey.html">d2i_PublicKey(3)</a>, <a href="../man3/d2i_KeyParams.html">d2i_KeyParams(3)</a>, <a href="../man3/d2i_PUBKEY.html">d2i_PUBKEY(3)</a>, <a href="../man3/i2d_PrivateKey.html">i2d_PrivateKey(3)</a>, <a href="../man3/i2d_PublicKey.html">i2d_PublicKey(3)</a>, <a href="../man3/i2d_KeyParams.html">i2d_KeyParams(3)</a>, <a href="../man3/i2d_PUBKEY.html">i2d_PUBKEY(3)</a></p> <h1 id="COPYRIGHT">COPYRIGHT</h1> <p>Copyright 2020-2021 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>