doc/man3/OSSL_PARAM_construct_from_text.pod

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