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