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