doc/man3/EVP_PKEY_fromdata.pod

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