doc/man3/d2i_RSAPrivateKey.pod

   1 =pod
   2
   3 =begin comment
   4
   5 Any deprecated keypair function from d2i_X509.pod are collected in this file.
   6
   7 =end comment
   8
   9 =head1 NAME
  10
  11 d2i_RSAPrivateKey,
  12 d2i_RSAPrivateKey_bio,
  13 d2i_RSAPrivateKey_fp,
  14 d2i_RSAPublicKey,
  15 d2i_RSAPublicKey_bio,
  16 d2i_RSAPublicKey_fp,
  17 d2i_RSA_PUBKEY,
  18 d2i_RSA_PUBKEY_bio,
  19 d2i_RSA_PUBKEY_fp,
  20 i2d_RSAPrivateKey,
  21 i2d_RSAPrivateKey_bio,
  22 i2d_RSAPrivateKey_fp,
  23 i2d_RSAPublicKey,
  24 i2d_RSAPublicKey_bio,
  25 i2d_RSAPublicKey_fp,
  26 i2d_RSA_PUBKEY,
  27 i2d_RSA_PUBKEY_bio,
  28 i2d_RSA_PUBKEY_fp
  29 - DEPRECATED
  30
  31 =head1 SYNOPSIS
  32
  33 =for openssl generic
  34
  35 Deprecated since OpenSSL 3.0, can be hidden entirely by defining
  36 B<OPENSSL_API_COMPAT> with a suitable version value, see
  37 L<openssl_user_macros(7)>:
  38
  39  TYPE *d2i_TYPEPrivateKey(TYPE **a, const unsigned char **ppin, long length);
  40  TYPE *d2i_TYPEPrivateKey_bio(BIO *bp, TYPE **a);
  41  TYPE *d2i_TYPEPrivateKey_fp(FILE *fp, TYPE **a);
  42  TYPE *d2i_TYPEPublicKey(TYPE **a, const unsigned char **ppin, long length);
  43  TYPE *d2i_TYPEPublicKey_bio(BIO *bp, TYPE **a);
  44  TYPE *d2i_TYPEPublicKey_fp(FILE *fp, TYPE **a);
  45  TYPE *d2i_TYPEparams(TYPE **a, const unsigned char **ppin, long length);
  46  TYPE *d2i_TYPEparams_bio(BIO *bp, TYPE **a);
  47  TYPE *d2i_TYPEparams_fp(FILE *fp, TYPE **a);
  48  TYPE *d2i_TYPE_PUBKEY(TYPE **a, const unsigned char **ppin, long length);
  49  TYPE *d2i_TYPE_PUBKEY_bio(BIO *bp, TYPE **a);
  50  TYPE *d2i_TYPE_PUBKEY_fp(FILE *fp, TYPE **a);
  51
  52  int i2d_TYPEPrivateKey(const TYPE *a, unsigned char **ppout);
  53  int i2d_TYPEPrivateKey(TYPE *a, unsigned char **ppout);
  54  int i2d_TYPEPrivateKey_fp(FILE *fp, const TYPE *a);
  55  int i2d_TYPEPrivateKey_fp(FILE *fp, TYPE *a);
  56  int i2d_TYPEPrivateKey_bio(BIO *bp, const TYPE *a);
  57  int i2d_TYPEPrivateKey_bio(BIO *bp, TYPE *a);
  58  int i2d_TYPEPublicKey(const TYPE *a, unsigned char **ppout);
  59  int i2d_TYPEPublicKey(TYPE *a, unsigned char **ppout);
  60  int i2d_TYPEPublicKey_fp(FILE *fp, const TYPE *a);
  61  int i2d_TYPEPublicKey_fp(FILE *fp, TYPE *a);
  62  int i2d_TYPEPublicKey_bio(BIO *bp, const TYPE *a);
  63  int i2d_TYPEPublicKey_bio(BIO *bp, TYPE *a);
  64  int i2d_TYPEparams(const TYPE *a, unsigned char **ppout);
  65  int i2d_TYPEparams(TYPE *a, unsigned char **ppout);
  66  int i2d_TYPEparams_fp(FILE *fp, const TYPE *a);
  67  int i2d_TYPEparams_fp(FILE *fp, TYPE *a);
  68  int i2d_TYPEparams_bio(BIO *bp, const TYPE *a);
  69  int i2d_TYPEparams_bio(BIO *bp, TYPE *a);
  70  int i2d_TYPE_PUBKEY(const TYPE *a, unsigned char **ppout);
  71  int i2d_TYPE_PUBKEY(TYPE *a, unsigned char **ppout);
  72  int i2d_TYPE_PUBKEY_fp(FILE *fp, const TYPE *a);
  73  int i2d_TYPE_PUBKEY_fp(FILE *fp, TYPE *a);
  74  int i2d_TYPE_PUBKEY_bio(BIO *bp, const TYPE *a);
  75  int i2d_TYPE_PUBKEY_bio(BIO *bp, TYPE *a);
  76
  77 =head1 DESCRIPTION
  78
  79 All functions described here are deprecated.  Please use L<OSSL_DECODER(3)>
  80 instead of the B<d2i> functions and L<OSSL_ENCODER(3)> instead of the B<i2d>
  81 functions.  See L</Migration> below.
  82
  83 In the description here, B<I<TYPE>> is used a placeholder for any of the
  84 OpenSSL datatypes, such as B<RSA>.
  85 The function parameters I<ppin> and I<ppout> are generally either both named
  86 I<pp> in the headers, or I<in> and I<out>.
  87
  88 All the functions here behave the way that's described in L<d2i_X509(3)>.
  89
  90 Please note that not all functions in the synopsis are available for all key
  91 types.  For example, there are no d2i_RSAparams() or i2d_RSAparams(),
  92 because the PKCS#1 B<RSA> structure doesn't include any key parameters.
  93
  94 B<d2i_I<TYPE>PrivateKey>() and derivates thereof decode DER encoded
  95 B<I<TYPE>> private key data organized in a type specific structure.
  96
  97 B<d2i_I<TYPE>PublicKey>() and derivates thereof decode DER encoded
  98 B<I<TYPE>> public key data organized in a type specific structure.
  99
 100 B<d2i_I<TYPE>params>() and derivates thereof decode DER encoded B<I<TYPE>>
 101 key parameters organized in a type specific structure.
 102
 103 B<d2i_I<TYPE>_PUBKEY>() and derivates thereof decode DER encoded B<I<TYPE>>
 104 public key data organized in a B<SubjectPublicKeyInfo> structure.
 105
 106 B<i2d_I<TYPE>PrivateKey>() and derivates thereof encode the private key
 107 B<I<TYPE>> data into a type specific DER encoded structure.
 108
 109 B<i2d_I<TYPE>PublicKey>() and derivates thereof encode the public key
 110 B<I<TYPE>> data into a type specific DER encoded structure.
 111
 112 B<i2d_I<TYPE>params>() and derivates thereof encode the B<I<TYPE>> key
 113 parameters data into a type specific DER encoded structure.
 114
 115 B<i2d_I<TYPE>_PUBKEY>() and derivates thereof encode the public key
 116 B<I<TYPE>> data into a DER encoded B<SubjectPublicKeyInfo> structure.
 117
 118 For example, d2i_RSAPrivateKey() and d2i_RSAPublicKey() expects the
 119 structure defined by PKCS#1.
 120 Similarly, i2d_RSAPrivateKey() and  i2d_RSAPublicKey() produce DER encoded
 121 string organized according to PKCS#1.
 122
 123 =head2 Migration
 124
 125 Migration from the diverse B<I<TYPE>>s requires using corresponding new
 126 OpenSSL types.  For all B<I<TYPE>>s described here, the corresponding new
 127 type is B<EVP_PKEY>.  The rest of this section assumes that this has been
 128 done, exactly how to do that is described elsewhere.
 129
 130 There are two migration paths:
 131
 132 =over 4
 133
 134 =item *
 135
 136 Replace
 137 b<d2i_I<TYPE>PrivateKey()> with L<d2i_PrivateKey(3)>,
 138 b<d2i_I<TYPE>PublicKey()> with L<d2i_PublicKey(3)>,
 139 b<d2i_I<TYPE>params()> with L<d2i_KeyParams(3)>,
 140 b<d2i_I<TYPE>_PUBKEY()> with L<d2i_PUBKEY(3)>,
 141 b<i2d_I<TYPE>PrivateKey()> with L<i2d_PrivateKey(3)>,
 142 b<i2d_I<TYPE>PublicKey()> with L<i2d_PublicKey(3)>,
 143 b<i2d_I<TYPE>params()> with L<i2d_KeyParams(3)>,
 144 b<i2d_I<TYPE>_PUBKEY()> with L<i2d_PUBKEY(3)>.
 145 A caveat is that L<i2d_PrivateKey(3)> may output a DER encoded PKCS#8
 146 outermost structure instead of the type specific structure, and that
 147 L<d2i_PrivateKey(3)> recognises and unpacks a PKCS#8 structures.
 148
 149 =item *
 150
 151 Use L<OSSL_DECODER(3)> and L<OSSL_ENCODER(3)>.  How to migrate is described
 152 below.  All those descriptions assume that the key to be encoded is in the
 153 variable I<pkey>.
 154
 155 =back
 156
 157 =head3 Migrating B<i2d> functions to B<OSSL_ENCODER>
 158
 159 The exact L<OSSL_ENCODER(3)> output is driven by arguments rather than by
 160 function names.  The sample code to get DER encoded output in a type
 161 specific structure is uniform, the only things that vary are the selection
 162 of what part of the B<EVP_PKEY> should be output, and the structure.  The
 163 B<i2d> functions names can therefore be translated into two variables,
 164 I<selection> and I<structure> as follows:
 165
 166 =over 4
 167
 168 =item B<i2d_I<TYPE>PrivateKey>() translates into:
 169
 170  int selection = EVP_PKEY_PRIVATE_KEY;
 171  const char *structure = "type-specific";
 172
 173 =item B<i2d_I<TYPE>PublicKey>() translates into:
 174
 175  int selection = EVP_PKEY_PUBLIC_KEY;
 176  const char *structure = "type-specific";
 177
 178 =item B<i2d_I<TYPE>params>() translates into:
 179
 180  int selection = EVP_PKEY_PARAMETERS;
 181  const char *structure = "type-specific";
 182
 183 =item B<i2d_I<TYPE>_PUBKEY>() translates into:
 184
 185  int selection = EVP_PKEY_PUBLIC_KEY;
 186  const char *structure = "SubjectPublicKeyInfo";
 187
 188 =back
 189
 190 The following sample code does the rest of the work:
 191
 192  unsigned char *p = buffer;     /* |buffer| is supplied by the caller */
 193  size_t len = buffer_size;      /* assumed be the size of |buffer| */
 194  OSSL_ENCODER_CTX *ctx =
 195      OSSL_ENCODER_CTX_new_by_EVP_PKEY(pkey, selection, "DER", structure,
 196                                       NULL, NULL);
 197  if (ctx == NULL) {
 198      /* fatal error handling */
 199  }
 200  if (OSSL_ENCODER_CTX_get_num_encoders(ctx) == 0) {
 201      OSSL_ENCODER_CTX_free(ctx);
 202      /* non-fatal error handling */
 203  }
 204  if (!OSSL_ENCODER_to_data(ctx, &p, &len)) {
 205      OSSL_ENCODER_CTX_free(ctx);
 206      /* error handling */
 207  }
 208  OSSL_ENCODER_CTX_free(ctx);
 209
 210 =for comment TODO: a similar section on OSSL_DECODER is to be added
 211
 212 =head1 RETURN VALUES
 213
 214 B<d2i_I<TYPE>>(), B<d2i_I<TYPE>_bio>() and B<d2i_I<TYPE>_fp>() return a valid
 215 B<I<TYPE>> structure or NULL if an error occurs.  If the "reuse" capability has
 216 been used with a valid structure being passed in via I<a>, then the object is
 217 freed in the event of error and I<*a> is set to NULL.
 218
 219 B<i2d_I<TYPE>>() returns the number of bytes successfully encoded or a negative
 220 value if an error occurs.
 221
 222 B<i2d_I<TYPE>_bio>() and B<i2d_I<TYPE>_fp>() return 1 for success and 0 if an
 223 error occurs.
 224
 225 =head1 SEE ALSO
 226
 227 L<OSSL_ENCODER(3)>, L<OSSL_DECODER(3)>,
 228 L<d2i_PrivateKey(3)>, L<d2i_PublicKey(3)>, L<d2i_KeyParams(3)>,
 229 L<d2i_PUBKEY(3)>,
 230 L<i2d_PrivateKey(3)>, L<i2d_PublicKey(3)>, L<i2d_KeyParams(3)>,
 231 L<i2d_PUBKEY(3)>
 232
 233 =head1 COPYRIGHT
 234
 235 Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
 236
 237 Licensed under the Apache License 2.0 (the "License").  You may not use
 238 this file except in compliance with the License.  You can obtain a copy
 239 in the file LICENSE in the source distribution or at
 240 L<https://www.openssl.org/source/license.html>.
 241
 242 =cut