DOC: Modify one example in EVP_PKEY_fromdata(3)

The example to create an EC key from user data didn't show what one
could expect and application to do, especially with regard to how it's
done with raw EC functions.  We therefore refactor it to make proper
use of a BIGNUM where expected, and also use OSSL_PARAM_BLD(3) for
easier handling of the OSSL_PARAM array.

Fixes #12388

Reviewed-by: Paul Dale <paul.dale@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/12389)

diff --git a/doc/man3/EVP_PKEY_fromdata.pod b/doc/man3/EVP_PKEY_fromdata.pod
index e3e6d89f8c42295b6b759b04e4c90088b3508130..f488441b93c3e8507b3728336ca341fc5a5d8119 100644 (file)
--- a/doc/man3/EVP_PKEY_fromdata.pod
+++ b/doc/man3/EVP_PKEY_fromdata.pod
@@ -120,33 +120,28 @@ TODO Write a set of cookbook documents and link to them.
 =head2 Creating an ECC keypair using raw key data
 
  #include <openssl/evp.h>
+ #include <openssl/param_build.h>
 
  /*
-  * These arrays represent large numbers, big endian organization.
-  * In a real application, these would probably be bignums that get
-  * converted to the native integer organization with BN_bn2nativepad().
-  * We're not doing that here, since this is not an example of BIGNUM
-  * functionality, but an example of EVP_PKEY_fromdata().
+  * Fixed data to represent the private and public key.
   */
- #ifndef B_ENDIAN
- # error "We haven't prepared little endian arrays"
- #endif
- const unsigned char priv[] = {
+ const unsigned char priv_data[] = {
      0xb9, 0x2f, 0x3c, 0xe6, 0x2f, 0xfb, 0x45, 0x68,
      0x39, 0x96, 0xf0, 0x2a, 0xaf, 0x6c, 0xda, 0xf2,
      0x89, 0x8a, 0x27, 0xbf, 0x39, 0x9b, 0x7e, 0x54,
      0x21, 0xc2, 0xa1, 0xe5, 0x36, 0x12, 0x48, 0x5d
  };
- const unsigned char pub[] = {
-     0x04, 0xcf, 0x20, 0xfb, 0x9a, 0x1d, 0x11, 0x6c,
-     0x5e, 0x9f, 0xec, 0x38, 0x87, 0x6c, 0x1d, 0x2f,
-     0x58, 0x47, 0xab, 0xa3, 0x9b, 0x79, 0x23, 0xe6,
-     0xeb, 0x94, 0x6f, 0x97, 0xdb, 0xa3, 0x7d, 0xbd,
-     0xe5, 0x26, 0xca, 0x07, 0x17, 0x8d, 0x26, 0x75,
-     0xff, 0xcb, 0x8e, 0xb6, 0x84, 0xd0, 0x24, 0x02,
-     0x25, 0x8f, 0xb9, 0x33, 0x6e, 0xcf, 0x12, 0x16,
-     0x2f, 0x5c, 0xcd, 0x86, 0x71, 0xa8, 0xbf, 0x1a,
-     0x47
+ /* UNCOMPRESSED FORMAT */
+ const unsigned char pub_data[] = {
+     POINT_CONVERSION_UNCOMPRESSED,
+     0xcf, 0x20, 0xfb, 0x9a, 0x1d, 0x11, 0x6c, 0x5e,
+     0x9f, 0xec, 0x38, 0x87, 0x6c, 0x1d, 0x2f, 0x58,
+     0x47, 0xab, 0xa3, 0x9b, 0x79, 0x23, 0xe6, 0xeb,
+     0x94, 0x6f, 0x97, 0xdb, 0xa3, 0x7d, 0xbd, 0xe5,
+     0x26, 0xca, 0x07, 0x17, 0x8d, 0x26, 0x75, 0xff,
+     0xcb, 0x8e, 0xb6, 0x84, 0xd0, 0x24, 0x02, 0x25,
+     0x8f, 0xb9, 0x33, 0x6e, 0xcf, 0x12, 0x16, 0x2f,
+     0x5c, 0xcd, 0x86, 0x71, 0xa8, 0xbf, 0x1a, 0x47
  };
  const OSSL_PARAM params[] = {
      OSSL_PARAM_utf8_string("group", "prime256v1"),
@@ -157,15 +152,41 @@ TODO Write a set of cookbook documents and link to them.
 
  int main()
  {
-     EVP_PKEY_CTX *ctx = EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
+     EVP_PKEY_CTX *ctx;
      EVP_PKEY *pkey = NULL;
-
+     BIGNUM *priv;
+     OSSL_PARAM_BLD *param_bld;
+     OSSL_PARAM *params = NULL;
+     int exitcode = 0;
+
+     priv = BN_bin2bn(priv_data, sizeof(priv_data), NULL);
+
+     param_bld = OSSL_PARAM_BLD_new();
+     if (priv != NULL && param_bld != NULL
+         && OSSL_PARAM_BLD_push_utf8_string(param_bld, "group",
+                                            "prime256v1", 0);
+         && OSSL_PARAM_BLD_push_BN(param_bld, "priv", priv);
+         && OSSL_PARAM_BLD_push_octet_string(param_bld, "pub",
+                                             pub_data, sizeof(pub_data)))
+         params = OSSL_PARAM_BLD_to_param(param_bld);
+
+     ctx = EVP_PKEY_CTX_new_from_name(NULL, "EC", NULL);
      if (ctx == NULL
+         || params != NULL
          || !EVP_PKEY_key_fromdata_init(ctx)
-         || !EVP_PKEY_fromdata(ctx, &pkey, params))
-         exit(1);
+         || !EVP_PKEY_fromdata(ctx, &pkey, params)) {
+         exitcode = 1;
+     } else {
+         /* Do what you want with |pkey| */
+     }
 
-     /* Do what you want with |pkey| */
+     EVP_PKEY_free(pkey);
+     EVP_PKEY_CTX_free(ctx);
+     OSSL_PARAM_BLD_free_params(params);
+     OSSL_PARAM_BLD_free(param_bld);
+     BN_free(priv);
+
+     exit(exitcode);
  }
 
 =head2 Finding out params for an unknown key type