doc/man3/OSSL_PARAM_allocate_from_text.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 OSSL_PARAM_allocate_from_text
   6 - OSSL_PARAM construction utilities
   7
   8 =head1 SYNOPSIS
   9
  10  #include <openssl/params.h>
  11
  12  int OSSL_PARAM_allocate_from_text(OSSL_PARAM *to,
  13                                    const OSSL_PARAM *paramdefs,
  14                                    const char *key, const char *value,
  15                                    size_t value_n,
  16                                    int *found);
  17
  18 =head1 DESCRIPTION
  19
  20 With OpenSSL before version 3.0, parameters were passed down to or
  21 retrieved from algorithm implementations via control functions.
  22 Some of these control functions existed in variants that took string
  23 parameters, for example L<EVP_PKEY_CTX_ctrl_str(3)>.
  24
  25 OpenSSL 3.0 introduces a new mechanism to do the same thing with an
  26 array of parameters that contain name, value, value type and value
  27 size (see L<OSSL_PARAM(3)> for more information).
  28
  29 OSSL_PARAM_allocate_from_text() takes a control I<key>, I<value> and
  30 value size I<value_n>, and given a parameter descriptor array
  31 I<paramdefs>, it converts the value to something suitable for
  32 L<OSSL_PARAM(3)> and stores that in the buffer I<buf>, and modifies
  33 the parameter I<to> to match.
  34 I<buf_n>, if not NULL, will be assigned the number of bytes used in
  35 I<buf>.
  36 If I<buf> is NULL, only I<buf_n> will be modified, everything else is
  37 left untouched, allowing a caller to find out how large the buffer
  38 should be.
  39 I<buf> needs to be correctly aligned for the type of the B<OSSL_PARAM>
  40 I<key>.
  41 If <found> is not NULL, it is set to 1 if the parameter can be located and
  42 to 0 otherwise.
  43
  44 The caller must remember to free the data of I<to> when it's not
  45 useful any more.
  46
  47 For parameters having the type B<OSSL_PARAM_INTEGER>,
  48 B<OSSL_PARAM_UNSIGNED_INTEGER>, or B<OSSL_PARAM_OCTET_STRING>, both
  49 functions will interpret the I<value> differently if the key starts
  50 with "hex".
  51 In that case, the value is decoded first, and the result will be used
  52 as parameter value.
  53
  54 =head1 RETURN VALUES
  55
  56 OSSL_PARAM_allocate_from_text() returns 1 on success, and 0 on error.
  57
  58 =head1 NOTES
  59
  60 The parameter descriptor array comes from functions dedicated to
  61 return them.
  62 The following B<OSSL_PARAM> attributes are used:
  63
  64 =over 4
  65
  66 =item I<key>
  67
  68 =item I<data>
  69
  70 =item I<data_size>
  71
  72 =back
  73
  74 All other attributes are ignored.
  75
  76 The I<data_size> attribute can be zero, meaning that the parameter it
  77 describes expects arbitrary length data.
  78
  79 =head1 EXAMPLES
  80
  81 Code that looked like this:
  82
  83   int mac_ctrl_string(EVP_PKEY_CTX *ctx, const char *value)
  84   {
  85       int rv;
  86       char *stmp, *vtmp = NULL;
  87
  88       stmp = OPENSSL_strdup(value);
  89       if (stmp == NULL)
  90           return -1;
  91       vtmp = strchr(stmp, ':');
  92       if (vtmp != NULL)
  93           *vtmp++ = '\0';
  94       rv = EVP_MAC_ctrl_str(ctx, stmp, vtmp);
  95       OPENSSL_free(stmp);
  96       return rv;
  97   }
  98
  99   ...
 100
 101
 102   for (i = 0; i < sk_OPENSSL_STRING_num(macopts); i++) {
 103       char *macopt = sk_OPENSSL_STRING_value(macopts, i);
 104
 105       if (pkey_ctrl_string(mac_ctx, macopt) <= 0) {
 106           BIO_printf(bio_err,
 107                      "MAC parameter error \"%s\"\n", macopt);
 108           ERR_print_errors(bio_err);
 109           goto mac_end;
 110       }
 111   }
 112
 113 Can be written like this instead:
 114
 115   OSSL_PARAM *params =
 116       OPENSSL_zalloc(sizeof(*params)
 117                      * (sk_OPENSSL_STRING_num(opts) + 1));
 118   const OSSL_PARAM *paramdefs = EVP_MAC_settable_ctx_params(mac);
 119   size_t params_n;
 120   char *opt = "<unknown>";
 121
 122   for (params_n = 0; params_n < (size_t)sk_OPENSSL_STRING_num(opts);
 123        params_n++) {
 124       char *stmp, *vtmp = NULL;
 125
 126       opt = sk_OPENSSL_STRING_value(opts, (int)params_n);
 127       if ((stmp = OPENSSL_strdup(opt)) == NULL
 128               || (vtmp = strchr(stmp, ':')) == NULL)
 129           goto err;
 130
 131       *vtmp++ = '\0';
 132       if (!OSSL_PARAM_allocate_from_text(&params[params_n],
 133                                          paramdefs, stmp,
 134                                          vtmp, strlen(vtmp), NULL))
 135           goto err;
 136   }
 137   params[params_n] = OSSL_PARAM_construct_end();
 138   if (!EVP_MAC_CTX_set_params(ctx, params))
 139       goto err;
 140   while (params_n-- > 0)
 141       OPENSSL_free(params[params_n].data);
 142   OPENSSL_free(params);
 143   /* ... */
 144   return;
 145
 146  err:
 147   BIO_printf(bio_err, "MAC parameter error '%s'\n", opt);
 148   ERR_print_errors(bio_err);
 149
 150
 151 =head1 SEE ALSO
 152
 153 L<OSSL_PARAM(3)>, L<OSSL_PARAM_int(3)>
 154
 155 =head1 COPYRIGHT
 156
 157 Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
 158
 159 Licensed under the Apache License 2.0 (the "License").  You may not use
 160 this file except in compliance with the License.  You can obtain a copy
 161 in the file LICENSE in the source distribution or at
 162 L<https://www.openssl.org/source/license.html>.
 163
 164 =cut