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