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  #include <openssl/ec.h>
 142
 143  /*
 144   * Fixed data to represent the private and public key.
 145   */
 146  const unsigned char priv_data[] = {
 147      0xb9, 0x2f, 0x3c, 0xe6, 0x2f, 0xfb, 0x45, 0x68,
 148      0x39, 0x96, 0xf0, 0x2a, 0xaf, 0x6c, 0xda, 0xf2,
 149      0x89, 0x8a, 0x27, 0xbf, 0x39, 0x9b, 0x7e, 0x54,
 150      0x21, 0xc2, 0xa1, 0xe5, 0x36, 0x12, 0x48, 0x5d
 151  };
 152  /* UNCOMPRESSED FORMAT */
 153  const unsigned char pub_data[] = {
 154      POINT_CONVERSION_UNCOMPRESSED,
 155      0xcf, 0x20, 0xfb, 0x9a, 0x1d, 0x11, 0x6c, 0x5e,
 156      0x9f, 0xec, 0x38, 0x87, 0x6c, 0x1d, 0x2f, 0x58,
 157      0x47, 0xab, 0xa3, 0x9b, 0x79, 0x23, 0xe6, 0xeb,
 158      0x94, 0x6f, 0x97, 0xdb, 0xa3, 0x7d, 0xbd, 0xe5,
 159      0x26, 0xca, 0x07, 0x17, 0x8d, 0x26, 0x75, 0xff,
 160      0xcb, 0x8e, 0xb6, 0x84, 0xd0, 0x24, 0x02, 0x25,
 161      0x8f, 0xb9, 0x33, 0x6e, 0xcf, 0x12, 0x16, 0x2f,
 162      0x5c, 0xcd, 0x86, 0x71, 0xa8, 0xbf, 0x1a, 0x47
 163  };
 164
 165  int main()
 166  {
 167      EVP_PKEY_CTX *ctx;
 168      EVP_PKEY *pkey = NULL;
 169      BIGNUM *priv;
 170      OSSL_PARAM_BLD *param_bld;
 171      OSSL_PARAM *params = NULL;
 172      int exitcode = 0;
 173
 174      priv = BN_bin2bn(priv_data, sizeof(priv_data), NULL);
 175
 176      param_bld = OSSL_PARAM_BLD_new();
 177      if (priv != NULL && param_bld != NULL
 178          && OSSL_PARAM_BLD_push_utf8_string(param_bld, "group",
 179                                             "prime256v1", 0)
 180          && OSSL_PARAM_BLD_push_BN(param_bld, "priv", priv)
 181          && OSSL_PARAM_BLD_push_octet_string(param_bld, "pub",
 182                                              pub_data, sizeof(pub_data)))
 183          params = OSSL_PARAM_BLD_to_param(param_bld);
 184
 185      ctx = EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
 186      if (ctx == NULL
 187          || params == NULL
 188          || EVP_PKEY_fromdata_init(ctx) <= 0
 189          || EVP_PKEY_fromdata(ctx, &pkey, EVP_PKEY_KEYPAIR, params) <= 0) {
 190          exitcode = 1;
 191      } else {
 192          /* Do what you want with |pkey| */
 193      }
 194
 195      EVP_PKEY_free(pkey);
 196      EVP_PKEY_CTX_free(ctx);
 197      OSSL_PARAM_free(params);
 198      OSSL_PARAM_BLD_free(param_bld);
 199      BN_free(priv);
 200
 201      exit(exitcode);
 202  }
 203
 204 =head2 Finding out params for an unknown key type
 205
 206  #include <openssl/evp.h>
 207  #include <openssl/core.h>
 208
 209  /* Program expects a key type as first argument */
 210  int main(int argc, char *argv[])
 211  {
 212      EVP_PKEY_CTX *ctx = EVP_PKEY_CTX_new_from_name(NULL, argv[1], NULL);
 213      const OSSL_PARAM *settable_params = NULL;
 214
 215      if (ctx == NULL)
 216         exit(1);
 217     settable_params = EVP_PKEY_fromdata_settable(ctx, EVP_PKEY_KEYPAIR);
 218     if (settable_params == NULL)
 219          exit(1);
 220
 221      for (; settable_params->key != NULL; settable_params++) {
 222          const char *datatype = NULL;
 223
 224          switch (settable_params->data_type) {
 225          case OSSL_PARAM_INTEGER:
 226              datatype = "integer";
 227              break;
 228          case OSSL_PARAM_UNSIGNED_INTEGER:
 229              datatype = "unsigned integer";
 230              break;
 231          case OSSL_PARAM_UTF8_STRING:
 232              datatype = "printable string (utf-8 encoding expected)";
 233              break;
 234          case OSSL_PARAM_UTF8_PTR:
 235              datatype = "printable string pointer (utf-8 encoding expected)";
 236              break;
 237          case OSSL_PARAM_OCTET_STRING:
 238              datatype = "octet string";
 239              break;
 240          case OSSL_PARAM_OCTET_PTR:
 241              datatype = "octet string pointer";
 242              break;
 243          }
 244          printf("%s : %s ", settable_params->key, datatype);
 245          if (settable_params->data_size == 0)
 246              printf("(unlimited size)\n");
 247          else
 248              printf("(maximum size %zu)\n", settable_params->data_size);
 249      }
 250  }
 251
 252 The descriptor L<OSSL_PARAM(3)> returned by
 253 EVP_PKEY_fromdata_settable() may also be used programmatically, for
 254 example with L<OSSL_PARAM_allocate_from_text(3)>.
 255
 256 =head1 SEE ALSO
 257
 258 L<EVP_PKEY_CTX_new(3)>, L<provider(7)>, L<EVP_PKEY_gettable_params(3)>,
 259 L<OSSL_PARAM(3)>, L<EVP_PKEY_todata(3)>,
 260 L<EVP_PKEY-RSA(7)>, L<EVP_PKEY-DSA(7)>, L<EVP_PKEY-DH(7)>, L<EVP_PKEY-EC(7)>,
 261 L<EVP_PKEY-ED448(7)>, L<EVP_PKEY-X25519(7)>, L<EVP_PKEY-X448(7)>,
 262 L<EVP_PKEY-ED25519(7)>
 263
 264 =head1 HISTORY
 265
 266 These functions were added in OpenSSL 3.0.
 267
 268 =head1 COPYRIGHT
 269
 270 Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.
 271
 272 Licensed under the Apache License 2.0 (the "License").  You may not use
 273 this file except in compliance with the License.  You can obtain a copy
 274 in the file LICENSE in the source distribution or at
 275 L<https://www.openssl.org/source/license.html>.
 276
 277 =cut
 278