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 This is the mirror function to L<EVP_PKEY_todata(3)>.
  82
  83 =for comment We may choose to make this available for legacy methods too...
  84
  85 =head1 RETURN VALUES
  86
  87 EVP_PKEY_fromdata_init() and EVP_PKEY_fromdata() return 1 for success and 0 or
  88 a negative value for failure.  In particular a return value of -2 indicates the
  89 operation is not supported by the public key algorithm.
  90
  91 =head1 EXAMPLES
  92
  93 These examples are very terse for the sake of staying on topic, which
  94 is the EVP_PKEY_fromdata() set of functions.  In real applications,
  95 BIGNUMs would be handled and converted to byte arrays with
  96 BN_bn2nativepad(), but that's off topic here.
  97
  98 =begin comment
  99
 100 TODO Write a set of cookbook documents and link to them.
 101
 102 =end comment
 103
 104 =head2 Creating an RSA keypair using raw key data
 105
 106  #include <openssl/evp.h>
 107
 108  /*
 109   * These are extremely small to make this example simple.  A real
 110   * and secure application will not use such small numbers.  A real
 111   * and secure application is expected to use BIGNUMs, and to build
 112   * this array dynamically.
 113   */
 114  unsigned long rsa_n = 0xbc747fc5;
 115  unsigned long rsa_e = 0x10001;
 116  unsigned long rsa_d = 0x7b133399;
 117  OSSL_PARAM params[] = {
 118      OSSL_PARAM_ulong("n", &rsa_n),
 119      OSSL_PARAM_ulong("e", &rsa_e),
 120      OSSL_PARAM_ulong("d", &rsa_d),
 121      OSSL_PARAM_END
 122  };
 123
 124  int main()
 125  {
 126      EVP_PKEY_CTX *ctx = EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL);
 127      EVP_PKEY *pkey = NULL;
 128
 129      if (ctx == NULL
 130          || EVP_PKEY_fromdata_init(ctx) <= 0
 131          || EVP_PKEY_fromdata(ctx, &pkey, EVP_PKEY_KEYPAIR, params) <= 0)
 132          exit(1);
 133
 134      /* Do what you want with |pkey| */
 135  }
 136
 137 =head2 Creating an ECC keypair using raw key data
 138
 139  #include <openssl/evp.h>
 140  #include <openssl/param_build.h>
 141
 142  /*
 143   * Fixed data to represent the private and public key.
 144   */
 145  const unsigned char priv_data[] = {
 146      0xb9, 0x2f, 0x3c, 0xe6, 0x2f, 0xfb, 0x45, 0x68,
 147      0x39, 0x96, 0xf0, 0x2a, 0xaf, 0x6c, 0xda, 0xf2,
 148      0x89, 0x8a, 0x27, 0xbf, 0x39, 0x9b, 0x7e, 0x54,
 149      0x21, 0xc2, 0xa1, 0xe5, 0x36, 0x12, 0x48, 0x5d
 150  };
 151  /* UNCOMPRESSED FORMAT */
 152  const unsigned char pub_data[] = {
 153      POINT_CONVERSION_UNCOMPRESSED,
 154      0xcf, 0x20, 0xfb, 0x9a, 0x1d, 0x11, 0x6c, 0x5e,
 155      0x9f, 0xec, 0x38, 0x87, 0x6c, 0x1d, 0x2f, 0x58,
 156      0x47, 0xab, 0xa3, 0x9b, 0x79, 0x23, 0xe6, 0xeb,
 157      0x94, 0x6f, 0x97, 0xdb, 0xa3, 0x7d, 0xbd, 0xe5,
 158      0x26, 0xca, 0x07, 0x17, 0x8d, 0x26, 0x75, 0xff,
 159      0xcb, 0x8e, 0xb6, 0x84, 0xd0, 0x24, 0x02, 0x25,
 160      0x8f, 0xb9, 0x33, 0x6e, 0xcf, 0x12, 0x16, 0x2f,
 161      0x5c, 0xcd, 0x86, 0x71, 0xa8, 0xbf, 0x1a, 0x47
 162  };
 163  const OSSL_PARAM params[] = {
 164      OSSL_PARAM_utf8_string("group", "prime256v1"),
 165      OSSL_PARAM_BN("priv", priv, sizeof(priv)),
 166      OSSL_PARAM_BN("pub", pub, sizeof(pub)),
 167      OSSL_PARAM_END
 168  };
 169
 170  int main()
 171  {
 172      EVP_PKEY_CTX *ctx;
 173      EVP_PKEY *pkey = NULL;
 174      BIGNUM *priv;
 175      OSSL_PARAM_BLD *param_bld;
 176      OSSL_PARAM *params = NULL;
 177      int exitcode = 0;
 178
 179      priv = BN_bin2bn(priv_data, sizeof(priv_data), NULL);
 180
 181      param_bld = OSSL_PARAM_BLD_new();
 182      if (priv != NULL && param_bld != NULL
 183          && OSSL_PARAM_BLD_push_utf8_string(param_bld, "group",
 184                                             "prime256v1", 0);
 185          && OSSL_PARAM_BLD_push_BN(param_bld, "priv", priv);
 186          && OSSL_PARAM_BLD_push_octet_string(param_bld, "pub",
 187                                              pub_data, sizeof(pub_data)))
 188          params = OSSL_PARAM_BLD_to_param(param_bld);
 189
 190      ctx = EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
 191      if (ctx == NULL
 192          || params != NULL
 193          || EVP_PKEY_fromdata_init(ctx) <= 0
 194          || EVP_PKEY_fromdata(ctx, &pkey, EVP_PKEY_KEYPAIR, params) <= 0) {
 195          exitcode = 1;
 196      } else {
 197          /* Do what you want with |pkey| */
 198      }
 199
 200      EVP_PKEY_free(pkey);
 201      EVP_PKEY_CTX_free(ctx);
 202      OSSL_PARAM_free(params);
 203      OSSL_PARAM_BLD_free(param_bld);
 204      BN_free(priv);
 205
 206      exit(exitcode);
 207  }
 208
 209 =head2 Finding out params for an unknown key type
 210
 211  #include <openssl/evp.h>
 212
 213  /* Program expects a key type as first argument */
 214  int main(int argc, char *argv[])
 215  {
 216      EVP_PKEY_CTX *ctx = EVP_PKEY_CTX_new_from_name(NULL, argv[1], NULL);
 217      const *OSSL_PARAM *settable_params = NULL;
 218
 219      if (ctx == NULL)
 220         exit(1);
 221     settable_params = EVP_PKEY_fromdata_settable(ctx, EVP_PKEY_KEYPAIR);
 222     if (settable_params == NULL)
 223          exit(1);
 224
 225      for (; settable_params->key != NULL; settable_params++) {
 226          const char *datatype = NULL;
 227
 228          switch (settable_params->data_type) {
 229          case OSSL_PARAM_INTEGER:
 230              datatype = "integer";
 231              break;
 232          case OSSL_PARAM_UNSIGNED_INTEGER:
 233              datatype = "unsigned integer";
 234              break;
 235          case OSSL_PARAM_UTF8_STRING:
 236              datatype = "printable string (utf-8 encoding expected)";
 237              break;
 238          case OSSL_PARAM_UTF8_PTR:
 239              datatype = "printable string pointer (utf-8 encoding expected)";
 240              break;
 241          case OSSL_PARAM_OCTET_STRING:
 242              datatype = "octet string";
 243              break;
 244          case OSSL_PARAM_OCTET_PTR:
 245              datatype = "octet string pointer";
 246              break;
 247          }
 248          printf("%s : %s ", settable_params->key, datatype);
 249          if (settable_params->data_size == 0)
 250              printf("(unlimited size)");
 251          else
 252              printf("(maximum size %zu)", settable_params->data_size);
 253      }
 254  }
 255
 256 The descriptor L<OSSL_PARAM(3)> returned by
 257 EVP_PKEY_fromdata_settable() may also be used programmatically, for
 258 example with L<OSSL_PARAM_allocate_from_text(3)>.
 259
 260 =head1 SEE ALSO
 261
 262 L<EVP_PKEY_CTX_new(3)>, L<provider(7)>, L<EVP_PKEY_gettable_params(3)>,
 263 L<OSSL_PARAM(3)>, L<EVP_PKEY_todata(3)>,
 264 L<EVP_PKEY-RSA(7)>, L<EVP_PKEY-DSA(7)>, L<EVP_PKEY-DH(7)>, L<EVP_PKEY-EC(7)>,
 265 L<EVP_PKEY-ED448(7)>, L<EVP_PKEY-X25519(7)>, L<EVP_PKEY-X448(7)>,
 266 L<EVP_PKEY-ED25519(7)>
 267
 268 =head1 HISTORY
 269
 270 These functions were added in OpenSSL 3.0.
 271
 272 =head1 COPYRIGHT
 273
 274 Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.
 275
 276 Licensed under the Apache License 2.0 (the "License").  You may not use
 277 this file except in compliance with the License.  You can obtain a copy
 278 in the file LICENSE in the source distribution or at
 279 L<https://www.openssl.org/source/license.html>.
 280
 281 =cut
 282