doc/man3/EVP_PKEY_fromdata.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 EVP_PKEY_fromdata_init, EVP_PKEY_fromdata, EVP_PKEY_fromdata_settable
   6 - functions to create keys and key parameters from user data
   7
   8 =head1 SYNOPSIS
   9
  10  #include <openssl/evp.h>
  11
  12  int EVP_PKEY_fromdata_init(EVP_PKEY_CTX *ctx);
  13  int EVP_PKEY_fromdata(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey, int selection,
  14                        OSSL_PARAM params[]);
  15  const OSSL_PARAM *EVP_PKEY_fromdata_settable(EVP_PKEY_CTX *ctx, int selection);
  16
  17 =head1 DESCRIPTION
  18
  19 The functions described here are used to create new keys from user
  20 provided key data, such as I<n>, I<e> and I<d> for a minimal RSA
  21 keypair.
  22
  23 These functions use an B<EVP_PKEY_CTX> context, which should primarily
  24 be created with L<EVP_PKEY_CTX_new_from_name(3)> or
  25 L<EVP_PKEY_CTX_new_id(3)>.
  26
  27 The exact key data that the user can pass depends on the key type.
  28 These are passed as an L<OSSL_PARAM(3)> array.
  29
  30 EVP_PKEY_fromdata_init() initializes a public key algorithm context
  31 for creating a key or key parameters from user data.
  32
  33 EVP_PKEY_fromdata() creates the structure to store a key or key parameters,
  34 given data from I<params>, I<selection> and a context that's been initialized
  35 with EVP_PKEY_fromdata_init().  The result is written to I<*ppkey>.
  36 I<selection> is described in L</Selections>.
  37 The parameters that can be used for various types of key are as described by the
  38 diverse "Common parameters" sections of the
  39 L<B<EVP_PKEY-RSA>(7)|EVP_PKEY-RSA(7)/Common RSA parameters>,
  40 L<B<EVP_PKEY-DSA>(7)|EVP_PKEY-DSA(7)/Common DSA & DH parameters>,
  41 L<B<EVP_PKEY-DH>(7)|EVP_PKEY-DH(7)/Common DH parameters>,
  42 L<B<EVP_PKEY-EC>(7)|EVP_PKEY-EC(7)/Common EC parameters>,
  43 L<B<EVP_PKEY-ED448>(7)|EVP_PKEY-ED448(7)/Common X25519, X448, ED25519 and ED448 parameters>,
  44 L<B<EVP_PKEY-X25519>(7)|EVP_PKEY-X25519(7)/Common X25519, X448, ED25519 and ED448 parameters>,
  45 L<B<EVP_PKEY-X448>(7)|EVP_PKEY-X448(7)/Common X25519, X448, ED25519 and ED448 parameters>,
  46 and L<B<EVP_PKEY-ED25519>(7)|EVP_PKEY-ED25519(7)/Common X25519, X448, ED25519 and ED448 parameters> pages.
  47
  48 =for comment the awful list of links above is made this way so we get nice
  49 rendering as a man-page while still getting proper links in HTML
  50
  51 EVP_PKEY_fromdata_settable() gets a constant B<OSSL_PARAM> array that describes
  52 the settable parameters that can be used with EVP_PKEY_fromdata().
  53 I<selection> is described in L</Selections>.
  54 See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor.
  55
  56 =head2 Selections
  57
  58 The following constants can be used for I<selection>:
  59
  60 =over 4
  61
  62 =item B<EVP_PKEY_KEY_PARAMETERS>
  63
  64 Only key parameters will be selected.
  65
  66 =item B<EVP_PKEY_PUBLIC_KEY>
  67
  68 Only public key components will be selected. This includes optional key
  69 parameters.
  70
  71 =item B<EVP_PKEY_KEYPAIR>
  72
  73 Any keypair components will be selected. This includes the private key,
  74 public key and key parameters.
  75
  76 =back
  77
  78 =head1 NOTES
  79
  80 These functions only work with key management methods coming from a provider.
  81
  82 =for comment We may choose to make this available for legacy methods too...
  83
  84 =head1 RETURN VALUES
  85
  86 EVP_PKEY_fromdata_init() and EVP_PKEY_fromdata() return 1 for success and 0 or
  87 a negative value for failure.  In particular a return value of -2 indicates the
  88 operation is not supported by the public key algorithm.
  89
  90 =head1 EXAMPLES
  91
  92 These examples are very terse for the sake of staying on topic, which
  93 is the EVP_PKEY_fromdata() set of functions.  In real applications,
  94 BIGNUMs would be handled and converted to byte arrays with
  95 BN_bn2nativepad(), but that's off topic here.
  96
  97 =begin comment
  98
  99 TODO Write a set of cookbook documents and link to them.
 100
 101 =end comment
 102
 103 =head2 Creating an RSA keypair using raw key data
 104
 105  #include <openssl/evp.h>
 106
 107  /*
 108   * These are extremely small to make this example simple.  A real
 109   * and secure application will not use such small numbers.  A real
 110   * and secure application is expected to use BIGNUMs, and to build
 111   * this array dynamically.
 112   */
 113  unsigned long rsa_n = 0xbc747fc5;
 114  unsigned long rsa_e = 0x10001;
 115  unsigned long rsa_d = 0x7b133399;
 116  OSSL_PARAM params[] = {
 117      OSSL_PARAM_ulong("n", &rsa_n),
 118      OSSL_PARAM_ulong("e", &rsa_e),
 119      OSSL_PARAM_ulong("d", &rsa_d),
 120      OSSL_PARAM_END
 121  };
 122
 123  int main()
 124  {
 125      EVP_PKEY_CTX *ctx = EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL);
 126      EVP_PKEY *pkey = NULL;
 127
 128      if (ctx == NULL
 129          || EVP_PKEY_fromdata_init(ctx) <= 0
 130          || EVP_PKEY_fromdata(ctx, &pkey, EVP_PKEY_KEYPAIR, params) <= 0)
 131          exit(1);
 132
 133      /* Do what you want with |pkey| */
 134  }
 135
 136 =head2 Creating an ECC keypair using raw key data
 137
 138  #include <openssl/evp.h>
 139  #include <openssl/param_build.h>
 140
 141  /*
 142   * Fixed data to represent the private and public key.
 143   */
 144  const unsigned char priv_data[] = {
 145      0xb9, 0x2f, 0x3c, 0xe6, 0x2f, 0xfb, 0x45, 0x68,
 146      0x39, 0x96, 0xf0, 0x2a, 0xaf, 0x6c, 0xda, 0xf2,
 147      0x89, 0x8a, 0x27, 0xbf, 0x39, 0x9b, 0x7e, 0x54,
 148      0x21, 0xc2, 0xa1, 0xe5, 0x36, 0x12, 0x48, 0x5d
 149  };
 150  /* UNCOMPRESSED FORMAT */
 151  const unsigned char pub_data[] = {
 152      POINT_CONVERSION_UNCOMPRESSED,
 153      0xcf, 0x20, 0xfb, 0x9a, 0x1d, 0x11, 0x6c, 0x5e,
 154      0x9f, 0xec, 0x38, 0x87, 0x6c, 0x1d, 0x2f, 0x58,
 155      0x47, 0xab, 0xa3, 0x9b, 0x79, 0x23, 0xe6, 0xeb,
 156      0x94, 0x6f, 0x97, 0xdb, 0xa3, 0x7d, 0xbd, 0xe5,
 157      0x26, 0xca, 0x07, 0x17, 0x8d, 0x26, 0x75, 0xff,
 158      0xcb, 0x8e, 0xb6, 0x84, 0xd0, 0x24, 0x02, 0x25,
 159      0x8f, 0xb9, 0x33, 0x6e, 0xcf, 0x12, 0x16, 0x2f,
 160      0x5c, 0xcd, 0x86, 0x71, 0xa8, 0xbf, 0x1a, 0x47
 161  };
 162  const OSSL_PARAM params[] = {
 163      OSSL_PARAM_utf8_string("group", "prime256v1"),
 164      OSSL_PARAM_BN("priv", priv, sizeof(priv)),
 165      OSSL_PARAM_BN("pub", pub, sizeof(pub)),
 166      OSSL_PARAM_END
 167  };
 168
 169  int main()
 170  {
 171      EVP_PKEY_CTX *ctx;
 172      EVP_PKEY *pkey = NULL;
 173      BIGNUM *priv;
 174      OSSL_PARAM_BLD *param_bld;
 175      OSSL_PARAM *params = NULL;
 176      int exitcode = 0;
 177
 178      priv = BN_bin2bn(priv_data, sizeof(priv_data), NULL);
 179
 180      param_bld = OSSL_PARAM_BLD_new();
 181      if (priv != NULL && param_bld != NULL
 182          && OSSL_PARAM_BLD_push_utf8_string(param_bld, "group",
 183                                             "prime256v1", 0);
 184          && OSSL_PARAM_BLD_push_BN(param_bld, "priv", priv);
 185          && OSSL_PARAM_BLD_push_octet_string(param_bld, "pub",
 186                                              pub_data, sizeof(pub_data)))
 187          params = OSSL_PARAM_BLD_to_param(param_bld);
 188
 189      ctx = EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
 190      if (ctx == NULL
 191          || params != NULL
 192          || EVP_PKEY_fromdata_init(ctx) <= 0
 193          || EVP_PKEY_fromdata(ctx, &pkey, EVP_PKEY_KEYPAIR, params) <= 0) {
 194          exitcode = 1;
 195      } else {
 196          /* Do what you want with |pkey| */
 197      }
 198
 199      EVP_PKEY_free(pkey);
 200      EVP_PKEY_CTX_free(ctx);
 201      OSSL_PARAM_BLD_free_params(params);
 202      OSSL_PARAM_BLD_free(param_bld);
 203      BN_free(priv);
 204
 205      exit(exitcode);
 206  }
 207
 208 =head2 Finding out params for an unknown key type
 209
 210  #include <openssl/evp.h>
 211
 212  /* Program expects a key type as first argument */
 213  int main(int argc, char *argv[])
 214  {
 215      EVP_PKEY_CTX *ctx = EVP_PKEY_CTX_new_from_name(NULL, argv[1], NULL);
 216      const *OSSL_PARAM *settable_params = NULL;
 217
 218      if (ctx == NULL)
 219         exit(1);
 220     settable_params = EVP_PKEY_fromdata_settable(ctx, EVP_PKEY_KEYPAIR);
 221     if (settable_params == NULL)
 222          exit(1);
 223
 224      for (; settable_params->key != NULL; settable_params++) {
 225          const char *datatype = NULL;
 226
 227          switch (settable_params->data_type) {
 228          case OSSL_PARAM_INTEGER:
 229              datatype = "integer";
 230              break;
 231          case OSSL_PARAM_UNSIGNED_INTEGER:
 232              datatype = "unsigned integer";
 233              break;
 234          case OSSL_PARAM_UTF8_STRING:
 235              datatype = "printable string (utf-8 encoding expected)";
 236              break;
 237          case OSSL_PARAM_UTF8_PTR:
 238              datatype = "printable string pointer (utf-8 encoding expected)";
 239              break;
 240          case OSSL_PARAM_OCTET_STRING:
 241              datatype = "octet string";
 242              break;
 243          case OSSL_PARAM_OCTET_PTR:
 244              datatype = "octet string pointer";
 245              break;
 246          }
 247          printf("%s : %s ", settable_params->key, datatype);
 248          if (settable_params->data_size == 0)
 249              printf("(unlimited size)");
 250          else
 251              printf("(maximum size %zu)", settable_params->data_size);
 252      }
 253  }
 254
 255 The descriptor L<OSSL_PARAM(3)> returned by
 256 EVP_PKEY_fromdata_settable() may also be used programmatically, for
 257 example with L<OSSL_PARAM_allocate_from_text(3)>.
 258
 259 =head1 SEE ALSO
 260
 261 L<EVP_PKEY_CTX_new(3)>, L<provider(7)>, L<EVP_PKEY_gettable_params(3)>,
 262 L<OSSL_PARAM(3)>,
 263 L<EVP_PKEY-RSA(7)>, L<EVP_PKEY-DSA(7)>, L<EVP_PKEY-DH(7)>, L<EVP_PKEY-EC(7)>,
 264 L<EVP_PKEY-ED448(7)>, L<EVP_PKEY-X25519(7)>, L<EVP_PKEY-X448(7)>,
 265 L<EVP_PKEY-ED25519(7)>
 266
 267 =head1 HISTORY
 268
 269 These functions were added in OpenSSL 3.0.
 270
 271 =head1 COPYRIGHT
 272
 273 Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.
 274
 275 Licensed under the Apache License 2.0 (the "License").  You may not use
 276 this file except in compliance with the License.  You can obtain a copy
 277 in the file LICENSE in the source distribution or at
 278 L<https://www.openssl.org/source/license.html>.
 279
 280 =cut
 281