doc/man3/d2i_RSAPrivateKey.pod

   1 =pod
   2
   3 =begin comment
   4
   5 Any deprecated keypair/params d2i or i2d functions are collected on this page.
   6
   7 =end comment
   8
   9 =head1 NAME
  10
  11 d2i_DSAPrivateKey,
  12 d2i_DSAPrivateKey_bio,
  13 d2i_DSAPrivateKey_fp,
  14 d2i_DSAPublicKey,
  15 d2i_DSA_PUBKEY,
  16 d2i_DSA_PUBKEY_bio,
  17 d2i_DSA_PUBKEY_fp,
  18 d2i_DSAparams,
  19 d2i_RSAPrivateKey,
  20 d2i_RSAPrivateKey_bio,
  21 d2i_RSAPrivateKey_fp,
  22 d2i_RSAPublicKey,
  23 d2i_RSAPublicKey_bio,
  24 d2i_RSAPublicKey_fp,
  25 d2i_RSA_PUBKEY,
  26 d2i_RSA_PUBKEY_bio,
  27 d2i_RSA_PUBKEY_fp,
  28 d2i_DHparams,
  29 d2i_DHparams_bio,
  30 d2i_DHparams_fp,
  31 d2i_ECPKParameters,
  32 d2i_ECParameters,
  33 d2i_ECPrivateKey,
  34 d2i_ECPrivateKey_bio,
  35 d2i_ECPrivateKey_fp,
  36 d2i_EC_PUBKEY,
  37 d2i_EC_PUBKEY_bio,
  38 d2i_EC_PUBKEY_fp,
  39 i2d_RSAPrivateKey,
  40 i2d_RSAPrivateKey_bio,
  41 i2d_RSAPrivateKey_fp,
  42 i2d_RSAPublicKey,
  43 i2d_RSAPublicKey_bio,
  44 i2d_RSAPublicKey_fp,
  45 i2d_RSA_PUBKEY,
  46 i2d_RSA_PUBKEY_bio,
  47 i2d_RSA_PUBKEY_fp,
  48 i2d_DHparams,
  49 i2d_DHparams_bio,
  50 i2d_DHparams_fp,
  51 i2d_ECPKParameters,
  52 i2d_ECParameters,
  53 i2d_ECPrivateKey,
  54 i2d_ECPrivateKey_bio,
  55 i2d_ECPrivateKey_fp,
  56 i2d_EC_PUBKEY,
  57 i2d_EC_PUBKEY_bio,
  58 i2d_EC_PUBKEY_fp
  59 - DEPRECATED
  60
  61 =head1 SYNOPSIS
  62
  63 =for openssl generic
  64
  65 Deprecated since OpenSSL 3.0, can be hidden entirely by defining
  66 B<OPENSSL_API_COMPAT> with a suitable version value, see
  67 L<openssl_user_macros(7)>:
  68
  69  TYPE *d2i_TYPEPrivateKey(TYPE **a, const unsigned char **ppin, long length);
  70  TYPE *d2i_TYPEPrivateKey_bio(BIO *bp, TYPE **a);
  71  TYPE *d2i_TYPEPrivateKey_fp(FILE *fp, TYPE **a);
  72  TYPE *d2i_TYPEPublicKey(TYPE **a, const unsigned char **ppin, long length);
  73  TYPE *d2i_TYPEPublicKey_bio(BIO *bp, TYPE **a);
  74  TYPE *d2i_TYPEPublicKey_fp(FILE *fp, TYPE **a);
  75  TYPE *d2i_TYPEparams(TYPE **a, const unsigned char **ppin, long length);
  76  TYPE *d2i_TYPEparams_bio(BIO *bp, TYPE **a);
  77  TYPE *d2i_TYPEparams_fp(FILE *fp, TYPE **a);
  78  TYPE *d2i_TYPE_PUBKEY(TYPE **a, const unsigned char **ppin, long length);
  79  TYPE *d2i_TYPE_PUBKEY_bio(BIO *bp, TYPE **a);
  80  TYPE *d2i_TYPE_PUBKEY_fp(FILE *fp, TYPE **a);
  81
  82  int i2d_TYPEPrivateKey(const TYPE *a, unsigned char **ppout);
  83  int i2d_TYPEPrivateKey(TYPE *a, unsigned char **ppout);
  84  int i2d_TYPEPrivateKey_fp(FILE *fp, const TYPE *a);
  85  int i2d_TYPEPrivateKey_fp(FILE *fp, TYPE *a);
  86  int i2d_TYPEPrivateKey_bio(BIO *bp, const TYPE *a);
  87  int i2d_TYPEPrivateKey_bio(BIO *bp, TYPE *a);
  88  int i2d_TYPEPublicKey(const TYPE *a, unsigned char **ppout);
  89  int i2d_TYPEPublicKey(TYPE *a, unsigned char **ppout);
  90  int i2d_TYPEPublicKey_fp(FILE *fp, const TYPE *a);
  91  int i2d_TYPEPublicKey_fp(FILE *fp, TYPE *a);
  92  int i2d_TYPEPublicKey_bio(BIO *bp, const TYPE *a);
  93  int i2d_TYPEPublicKey_bio(BIO *bp, TYPE *a);
  94  int i2d_TYPEparams(const TYPE *a, unsigned char **ppout);
  95  int i2d_TYPEparams(TYPE *a, unsigned char **ppout);
  96  int i2d_TYPEparams_fp(FILE *fp, const TYPE *a);
  97  int i2d_TYPEparams_fp(FILE *fp, TYPE *a);
  98  int i2d_TYPEparams_bio(BIO *bp, const TYPE *a);
  99  int i2d_TYPEparams_bio(BIO *bp, TYPE *a);
 100  int i2d_TYPE_PUBKEY(const TYPE *a, unsigned char **ppout);
 101  int i2d_TYPE_PUBKEY(TYPE *a, unsigned char **ppout);
 102  int i2d_TYPE_PUBKEY_fp(FILE *fp, const TYPE *a);
 103  int i2d_TYPE_PUBKEY_fp(FILE *fp, TYPE *a);
 104  int i2d_TYPE_PUBKEY_bio(BIO *bp, const TYPE *a);
 105  int i2d_TYPE_PUBKEY_bio(BIO *bp, TYPE *a);
 106
 107 =head1 DESCRIPTION
 108
 109 All functions described here are deprecated.  Please use L<OSSL_DECODER(3)>
 110 instead of the B<d2i> functions and L<OSSL_ENCODER(3)> instead of the B<i2d>
 111 functions.  See L</Migration> below.
 112
 113 In the description here, B<I<TYPE>> is used a placeholder for any of the
 114 OpenSSL datatypes, such as B<RSA>.
 115 The function parameters I<ppin> and I<ppout> are generally either both named
 116 I<pp> in the headers, or I<in> and I<out>.
 117
 118 All the functions here behave the way that's described in L<d2i_X509(3)>.
 119
 120 Please note that not all functions in the synopsis are available for all key
 121 types.  For example, there are no d2i_RSAparams() or i2d_RSAparams(),
 122 because the PKCS#1 B<RSA> structure doesn't include any key parameters.
 123
 124 B<d2i_I<TYPE>PrivateKey>() and derivates thereof decode DER encoded
 125 B<I<TYPE>> private key data organized in a type specific structure.
 126
 127 B<d2i_I<TYPE>PublicKey>() and derivates thereof decode DER encoded
 128 B<I<TYPE>> public key data organized in a type specific structure.
 129
 130 B<d2i_I<TYPE>params>() and derivates thereof decode DER encoded B<I<TYPE>>
 131 key parameters organized in a type specific structure.
 132
 133 B<d2i_I<TYPE>_PUBKEY>() and derivates thereof decode DER encoded B<I<TYPE>>
 134 public key data organized in a B<SubjectPublicKeyInfo> structure.
 135
 136 B<i2d_I<TYPE>PrivateKey>() and derivates thereof encode the private key
 137 B<I<TYPE>> data into a type specific DER encoded structure.
 138
 139 B<i2d_I<TYPE>PublicKey>() and derivates thereof encode the public key
 140 B<I<TYPE>> data into a type specific DER encoded structure.
 141
 142 B<i2d_I<TYPE>params>() and derivates thereof encode the B<I<TYPE>> key
 143 parameters data into a type specific DER encoded structure.
 144
 145 B<i2d_I<TYPE>_PUBKEY>() and derivates thereof encode the public key
 146 B<I<TYPE>> data into a DER encoded B<SubjectPublicKeyInfo> structure.
 147
 148 For example, d2i_RSAPrivateKey() and d2i_RSAPublicKey() expects the
 149 structure defined by PKCS#1.
 150 Similarly, i2d_RSAPrivateKey() and  i2d_RSAPublicKey() produce DER encoded
 151 string organized according to PKCS#1.
 152
 153 =head2 Migration
 154
 155 Migration from the diverse B<I<TYPE>>s requires using corresponding new
 156 OpenSSL types.  For all B<I<TYPE>>s described here, the corresponding new
 157 type is B<EVP_PKEY>.  The rest of this section assumes that this has been
 158 done, exactly how to do that is described elsewhere.
 159
 160 There are two migration paths:
 161
 162 =over 4
 163
 164 =item *
 165
 166 Replace
 167 b<d2i_I<TYPE>PrivateKey()> with L<d2i_PrivateKey(3)>,
 168 b<d2i_I<TYPE>PublicKey()> with L<d2i_PublicKey(3)>,
 169 b<d2i_I<TYPE>params()> with L<d2i_KeyParams(3)>,
 170 b<d2i_I<TYPE>_PUBKEY()> with L<d2i_PUBKEY(3)>,
 171 b<i2d_I<TYPE>PrivateKey()> with L<i2d_PrivateKey(3)>,
 172 b<i2d_I<TYPE>PublicKey()> with L<i2d_PublicKey(3)>,
 173 b<i2d_I<TYPE>params()> with L<i2d_KeyParams(3)>,
 174 b<i2d_I<TYPE>_PUBKEY()> with L<i2d_PUBKEY(3)>.
 175 A caveat is that L<i2d_PrivateKey(3)> may output a DER encoded PKCS#8
 176 outermost structure instead of the type specific structure, and that
 177 L<d2i_PrivateKey(3)> recognises and unpacks a PKCS#8 structures.
 178
 179 =item *
 180
 181 Use L<OSSL_DECODER(3)> and L<OSSL_ENCODER(3)>.  How to migrate is described
 182 below.  All those descriptions assume that the key to be encoded is in the
 183 variable I<pkey>.
 184
 185 =back
 186
 187 =head3 Migrating B<i2d> functions to B<OSSL_ENCODER>
 188
 189 The exact L<OSSL_ENCODER(3)> output is driven by arguments rather than by
 190 function names.  The sample code to get DER encoded output in a type
 191 specific structure is uniform, the only things that vary are the selection
 192 of what part of the B<EVP_PKEY> should be output, and the structure.  The
 193 B<i2d> functions names can therefore be translated into two variables,
 194 I<selection> and I<structure> as follows:
 195
 196 =over 4
 197
 198 =item B<i2d_I<TYPE>PrivateKey>() translates into:
 199
 200  int selection = EVP_PKEY_PRIVATE_KEY;
 201  const char *structure = "type-specific";
 202
 203 =item B<i2d_I<TYPE>PublicKey>() translates into:
 204
 205  int selection = EVP_PKEY_PUBLIC_KEY;
 206  const char *structure = "type-specific";
 207
 208 =item B<i2d_I<TYPE>params>() translates into:
 209
 210  int selection = EVP_PKEY_PARAMETERS;
 211  const char *structure = "type-specific";
 212
 213 =item B<i2d_I<TYPE>_PUBKEY>() translates into:
 214
 215  int selection = EVP_PKEY_PUBLIC_KEY;
 216  const char *structure = "SubjectPublicKeyInfo";
 217
 218 =back
 219
 220 The following sample code does the rest of the work:
 221
 222  unsigned char *p = buffer;     /* |buffer| is supplied by the caller */
 223  size_t len = buffer_size;      /* assumed be the size of |buffer| */
 224  OSSL_ENCODER_CTX *ctx =
 225      OSSL_ENCODER_CTX_new_by_EVP_PKEY(pkey, selection, "DER", structure,
 226                                       NULL, NULL);
 227  if (ctx == NULL) {
 228      /* fatal error handling */
 229  }
 230  if (OSSL_ENCODER_CTX_get_num_encoders(ctx) == 0) {
 231      OSSL_ENCODER_CTX_free(ctx);
 232      /* non-fatal error handling */
 233  }
 234  if (!OSSL_ENCODER_to_data(ctx, &p, &len)) {
 235      OSSL_ENCODER_CTX_free(ctx);
 236      /* error handling */
 237  }
 238  OSSL_ENCODER_CTX_free(ctx);
 239
 240 =for comment TODO: a similar section on OSSL_DECODER is to be added
 241
 242 =head1 NOTES
 243
 244 The letters B<i> and B<d> in B<i2d_I<TYPE>>() stand for
 245 "internal" (that is, an internal C structure) and "DER" respectively.
 246 So B<i2d_I<TYPE>>() converts from internal to DER.
 247
 248 The functions can also understand B<BER> forms.
 249
 250 The actual TYPE structure passed to B<i2d_I<TYPE>>() must be a valid
 251 populated B<I<TYPE>> structure -- it B<cannot> simply be fed with an
 252 empty structure such as that returned by TYPE_new().
 253
 254 The encoded data is in binary form and may contain embedded zeros.
 255 Therefore, any FILE pointers or BIOs should be opened in binary mode.
 256 Functions such as strlen() will B<not> return the correct length
 257 of the encoded structure.
 258
 259 The ways that I<*ppin> and I<*ppout> are incremented after the operation
 260 can trap the unwary. See the B<WARNINGS> section for some common
 261 errors.
 262 The reason for this-auto increment behaviour is to reflect a typical
 263 usage of ASN1 functions: after one structure is encoded or decoded
 264 another will be processed after it.
 265
 266 The following points about the data types might be useful:
 267
 268 =over 4
 269
 270 =item B<DSA_PUBKEY>
 271
 272 Represents a DSA public key using a B<SubjectPublicKeyInfo> structure.
 273
 274 =item B<DSAPublicKey>, B<DSAPrivateKey>
 275
 276 Use a non-standard OpenSSL format and should be avoided; use B<DSA_PUBKEY>,
 277 L<PEM_write_PrivateKey(3)>, or similar instead.
 278
 279 =back
 280
 281 =head1 RETURN VALUES
 282
 283 B<d2i_I<TYPE>>(), B<d2i_I<TYPE>_bio>() and B<d2i_I<TYPE>_fp>() return a valid
 284 B<I<TYPE>> structure or NULL if an error occurs.  If the "reuse" capability has
 285 been used with a valid structure being passed in via I<a>, then the object is
 286 freed in the event of error and I<*a> is set to NULL.
 287
 288 B<i2d_I<TYPE>>() returns the number of bytes successfully encoded or a negative
 289 value if an error occurs.
 290
 291 B<i2d_I<TYPE>_bio>() and B<i2d_I<TYPE>_fp>() return 1 for success and 0 if an
 292 error occurs.
 293
 294 =head1 SEE ALSO
 295
 296 L<OSSL_ENCODER(3)>, L<OSSL_DECODER(3)>,
 297 L<d2i_PrivateKey(3)>, L<d2i_PublicKey(3)>, L<d2i_KeyParams(3)>,
 298 L<d2i_PUBKEY(3)>,
 299 L<i2d_PrivateKey(3)>, L<i2d_PublicKey(3)>, L<i2d_KeyParams(3)>,
 300 L<i2d_PUBKEY(3)>
 301
 302 =head1 COPYRIGHT
 303
 304 Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
 305
 306 Licensed under the Apache License 2.0 (the "License").  You may not use
 307 this file except in compliance with the License.  You can obtain a copy
 308 in the file LICENSE in the source distribution or at
 309 L<https://www.openssl.org/source/license.html>.
 310
 311 =cut