providers/common/include/prov/provider_util.h

   1 /*
   2  * Copyright 2019-2022 The OpenSSL Project Authors. All Rights Reserved.
   3  *
   4  * Licensed under the Apache License 2.0 (the "License").  You may not use
   5  * this file except in compliance with the License.  You can obtain a copy
   6  * in the file LICENSE in the source distribution or at
   7  * https://www.openssl.org/source/license.html
   8  */
   9
  10 #include <openssl/provider.h>
  11 #include <openssl/types.h>
  12
  13 typedef struct {
  14     /*
  15      * References to the underlying cipher implementation.  |cipher| caches
  16      * the cipher, always.  |alloc_cipher| only holds a reference to an
  17      * explicitly fetched cipher.
  18      */
  19     const EVP_CIPHER *cipher;   /* cipher */
  20     EVP_CIPHER *alloc_cipher;   /* fetched cipher */
  21
  22     /* Conditions for legacy EVP_CIPHER uses */
  23     ENGINE *engine;             /* cipher engine */
  24 } PROV_CIPHER;
  25
  26 typedef struct {
  27     /*
  28      * References to the underlying digest implementation.  |md| caches
  29      * the digest, always.  |alloc_md| only holds a reference to an explicitly
  30      * fetched digest.
  31      */
  32     const EVP_MD *md;           /* digest */
  33     EVP_MD *alloc_md;           /* fetched digest */
  34
  35     /* Conditions for legacy EVP_MD uses */
  36     ENGINE *engine;             /* digest engine */
  37 } PROV_DIGEST;
  38
  39 /* Cipher functions */
  40 /*
  41  * Load a cipher from the specified parameters with the specified context.
  42  * The params "properties", "engine" and "cipher" are used to determine the
  43  * implementation used.  If a provider cannot be found, it falls back to trying
  44  * non-provider based implementations.
  45  */
  46 int ossl_prov_cipher_load_from_params(PROV_CIPHER *pc,
  47                                       const OSSL_PARAM params[],
  48                                       OSSL_LIB_CTX *ctx);
  49
  50 /* Reset the PROV_CIPHER fields and free any allocated cipher reference */
  51 void ossl_prov_cipher_reset(PROV_CIPHER *pc);
  52
  53 /* Clone a PROV_CIPHER structure into a second */
  54 int ossl_prov_cipher_copy(PROV_CIPHER *dst, const PROV_CIPHER *src);
  55
  56 /* Query the cipher and associated engine (if any) */
  57 const EVP_CIPHER *ossl_prov_cipher_cipher(const PROV_CIPHER *pc);
  58 ENGINE *ossl_prov_cipher_engine(const PROV_CIPHER *pc);
  59
  60 /* Digest functions */
  61
  62 /*
  63  * Fetch a digest from the specified libctx using the provided mdname and
  64  * propquery. Store the result in the PROV_DIGEST and return the fetched md.
  65  */
  66 const EVP_MD *ossl_prov_digest_fetch(PROV_DIGEST *pd, OSSL_LIB_CTX *libctx,
  67                                      const char *mdname, const char *propquery);
  68
  69 /*
  70  * Load a digest from the specified parameters with the specified context.
  71  * The params "properties", "engine" and "digest" are used to determine the
  72  * implementation used.  If a provider cannot be found, it falls back to trying
  73  * non-provider based implementations.
  74  */
  75 int ossl_prov_digest_load_from_params(PROV_DIGEST *pd,
  76                                       const OSSL_PARAM params[],
  77                                       OSSL_LIB_CTX *ctx);
  78
  79 /* Reset the PROV_DIGEST fields and free any allocated digest reference */
  80 void ossl_prov_digest_reset(PROV_DIGEST *pd);
  81
  82 /* Clone a PROV_DIGEST structure into a second */
  83 int ossl_prov_digest_copy(PROV_DIGEST *dst, const PROV_DIGEST *src);
  84
  85 /* Query the digest and associated engine (if any) */
  86 const EVP_MD *ossl_prov_digest_md(const PROV_DIGEST *pd);
  87 ENGINE *ossl_prov_digest_engine(const PROV_DIGEST *pd);
  88
  89
  90 /*
  91  * Set the various parameters on an EVP_MAC_CTX from the supplied arguments.
  92  * If any of the supplied ciphername/mdname etc are NULL then the values
  93  * from the supplied params (if non NULL) are used instead.
  94  */
  95 int ossl_prov_set_macctx(EVP_MAC_CTX *macctx,
  96                          const OSSL_PARAM params[],
  97                          const char *ciphername,
  98                          const char *mdname,
  99                          const char *engine,
 100                          const char *properties,
 101                          const unsigned char *key,
 102                          size_t keylen);
 103
 104 /* MAC functions */
 105 /*
 106  * Load an EVP_MAC_CTX* from the specified parameters with the specified
 107  * library context.
 108  * The params "mac" and "properties" are used to determine the implementation
 109  * used, and the parameters "digest", "cipher", "engine" and "properties" are
 110  * passed to the MAC via the created MAC context if they are given.
 111  * If there is already a created MAC context, it will be replaced if the "mac"
 112  * parameter is found, otherwise it will simply be used as is, and passed the
 113  * parameters to pilfer as it sees fit.
 114  *
 115  * As an option, a MAC name may be explicitly given, and if it is, the "mac"
 116  * parameter will be ignored.
 117  * Similarly, as an option, a cipher name or a digest name may be explicitly
 118  * given, and if any of them is, the "digest" and "cipher" parameters are
 119  * ignored.
 120  */
 121 int ossl_prov_macctx_load_from_params(EVP_MAC_CTX **macctx,
 122                                       const OSSL_PARAM params[],
 123                                       const char *macname,
 124                                       const char *ciphername,
 125                                       const char *mdname,
 126                                       OSSL_LIB_CTX *ctx);
 127
 128 typedef struct ag_capable_st {
 129     OSSL_ALGORITHM alg;
 130     int (*capable)(void);
 131 } OSSL_ALGORITHM_CAPABLE;
 132
 133 /*
 134  * Dynamically select algorithms by calling a capable() method.
 135  * If this method is NULL or the method returns 1 then the algorithm is added.
 136  */
 137 void ossl_prov_cache_exported_algorithms(const OSSL_ALGORITHM_CAPABLE *in,
 138                                          OSSL_ALGORITHM *out);
 139
 140 /* Duplicate a lump of memory safely */
 141 int ossl_prov_memdup(const void *src, size_t src_len,
 142                      unsigned char **dest, size_t *dest_len);