include/internal/ffc.h

   1 /*
   2  * Copyright 2019-2023 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 #ifndef OSSL_INTERNAL_FFC_H
  11 # define OSSL_INTERNAL_FFC_H
  12 # pragma once
  13
  14 # include <openssl/core.h>
  15 # include <openssl/bn.h>
  16 # include <openssl/evp.h>
  17 # include <openssl/dh.h> /* Uses Error codes from DH */
  18 # include <openssl/params.h>
  19 # include <openssl/param_build.h>
  20 # include "internal/sizes.h"
  21
  22 /* Default value for gindex when canonical generation of g is not used */
  23 # define FFC_UNVERIFIABLE_GINDEX -1
  24
  25 /* The different types of FFC keys */
  26 # define FFC_PARAM_TYPE_DSA  0
  27 # define FFC_PARAM_TYPE_DH   1
  28
  29 /*
  30  * The mode used by functions that share code for both generation and
  31  * verification. See ossl_ffc_params_FIPS186_4_gen_verify().
  32  */
  33 #define FFC_PARAM_MODE_VERIFY   0
  34 #define FFC_PARAM_MODE_GENERATE 1
  35
  36 /* Return codes for generation and validation of FFC parameters */
  37 #define FFC_PARAM_RET_STATUS_FAILED         0
  38 #define FFC_PARAM_RET_STATUS_SUCCESS        1
  39 /* Returned if validating and g is only partially verifiable */
  40 #define FFC_PARAM_RET_STATUS_UNVERIFIABLE_G 2
  41
  42 /* Validation flags */
  43 # define FFC_PARAM_FLAG_VALIDATE_PQ    0x01
  44 # define FFC_PARAM_FLAG_VALIDATE_G     0x02
  45 # define FFC_PARAM_FLAG_VALIDATE_PQG                                           \
  46     (FFC_PARAM_FLAG_VALIDATE_PQ | FFC_PARAM_FLAG_VALIDATE_G)
  47 #define FFC_PARAM_FLAG_VALIDATE_LEGACY 0x04
  48
  49 /*
  50  * NB: These values must align with the equivalently named macros in
  51  * openssl/dh.h. We cannot use those macros here in case DH has been disabled.
  52  */
  53 # define FFC_CHECK_P_NOT_PRIME                0x00001
  54 # define FFC_CHECK_P_NOT_SAFE_PRIME           0x00002
  55 # define FFC_CHECK_UNKNOWN_GENERATOR          0x00004
  56 # define FFC_CHECK_NOT_SUITABLE_GENERATOR     0x00008
  57 # define FFC_CHECK_Q_NOT_PRIME                0x00010
  58 # define FFC_CHECK_INVALID_Q_VALUE            0x00020
  59 # define FFC_CHECK_INVALID_J_VALUE            0x00040
  60
  61 /*
  62  * 0x80, 0x100 reserved by include/openssl/dh.h with check bits that are not
  63  * relevant for FFC.
  64  */
  65
  66 # define FFC_CHECK_MISSING_SEED_OR_COUNTER    0x00200
  67 # define FFC_CHECK_INVALID_G                  0x00400
  68 # define FFC_CHECK_INVALID_PQ                 0x00800
  69 # define FFC_CHECK_INVALID_COUNTER            0x01000
  70 # define FFC_CHECK_P_MISMATCH                 0x02000
  71 # define FFC_CHECK_Q_MISMATCH                 0x04000
  72 # define FFC_CHECK_G_MISMATCH                 0x08000
  73 # define FFC_CHECK_COUNTER_MISMATCH           0x10000
  74 # define FFC_CHECK_BAD_LN_PAIR                0x20000
  75 # define FFC_CHECK_INVALID_SEED_SIZE          0x40000
  76
  77 /* Validation Return codes */
  78 # define FFC_ERROR_PUBKEY_TOO_SMALL       0x01
  79 # define FFC_ERROR_PUBKEY_TOO_LARGE       0x02
  80 # define FFC_ERROR_PUBKEY_INVALID         0x04
  81 # define FFC_ERROR_NOT_SUITABLE_GENERATOR 0x08
  82 # define FFC_ERROR_PRIVKEY_TOO_SMALL      0x10
  83 # define FFC_ERROR_PRIVKEY_TOO_LARGE      0x20
  84 # define FFC_ERROR_PASSED_NULL_PARAM      0x40
  85
  86 /*
  87  * Finite field cryptography (FFC) domain parameters are used by DH and DSA.
  88  * Refer to FIPS186_4 Appendix A & B.
  89  */
  90 typedef struct ffc_params_st {
  91     /* Primes */
  92     BIGNUM *p;
  93     BIGNUM *q;
  94     /* Generator */
  95     BIGNUM *g;
  96     /* DH X9.42 Optional Subgroup factor j >= 2 where p = j * q + 1 */
  97     BIGNUM *j;
  98
  99     /* Required for FIPS186_4 validation of p, q and optionally canonical g */
 100     unsigned char *seed;
 101     /* If this value is zero the hash size is used as the seed length */
 102     size_t seedlen;
 103     /* Required for FIPS186_4 validation of p and q */
 104     int pcounter;
 105     int nid; /* The identity of a named group */
 106
 107     /*
 108      * Required for FIPS186_4 generation & validation of canonical g.
 109      * It uses unverifiable g if this value is -1.
 110      */
 111     int gindex;
 112     int h; /* loop counter for unverifiable g */
 113
 114     unsigned int flags;
 115     /*
 116      * The digest to use for generation or validation. If this value is NULL,
 117      * then the digest is chosen using the value of N.
 118      */
 119     const char *mdname;
 120     const char *mdprops;
 121     /* Default key length for known named groups according to RFC7919 */
 122     int keylength;
 123 } FFC_PARAMS;
 124
 125 void ossl_ffc_params_init(FFC_PARAMS *params);
 126 void ossl_ffc_params_cleanup(FFC_PARAMS *params);
 127 void ossl_ffc_params_set0_pqg(FFC_PARAMS *params, BIGNUM *p, BIGNUM *q,
 128                               BIGNUM *g);
 129 void ossl_ffc_params_get0_pqg(const FFC_PARAMS *params, const BIGNUM **p,
 130                               const BIGNUM **q, const BIGNUM **g);
 131 void ossl_ffc_params_set0_j(FFC_PARAMS *d, BIGNUM *j);
 132 int ossl_ffc_params_set_seed(FFC_PARAMS *params,
 133                              const unsigned char *seed, size_t seedlen);
 134 void ossl_ffc_params_set_gindex(FFC_PARAMS *params, int index);
 135 void ossl_ffc_params_set_pcounter(FFC_PARAMS *params, int index);
 136 void ossl_ffc_params_set_h(FFC_PARAMS *params, int index);
 137 void ossl_ffc_params_set_flags(FFC_PARAMS *params, unsigned int flags);
 138 void ossl_ffc_params_enable_flags(FFC_PARAMS *params, unsigned int flags,
 139                                   int enable);
 140 void ossl_ffc_set_digest(FFC_PARAMS *params, const char *alg, const char *props);
 141
 142 int ossl_ffc_params_set_validate_params(FFC_PARAMS *params,
 143                                         const unsigned char *seed,
 144                                         size_t seedlen, int counter);
 145 void ossl_ffc_params_get_validate_params(const FFC_PARAMS *params,
 146                                          unsigned char **seed, size_t *seedlen,
 147                                          int *pcounter);
 148
 149 int ossl_ffc_params_copy(FFC_PARAMS *dst, const FFC_PARAMS *src);
 150 int ossl_ffc_params_cmp(const FFC_PARAMS *a, const FFC_PARAMS *b, int ignore_q);
 151
 152 #ifndef FIPS_MODULE
 153 int ossl_ffc_params_print(BIO *bp, const FFC_PARAMS *ffc, int indent);
 154 #endif /* FIPS_MODULE */
 155
 156
 157 int ossl_ffc_params_FIPS186_4_generate(OSSL_LIB_CTX *libctx, FFC_PARAMS *params,
 158                                        int type, size_t L, size_t N,
 159                                        int *res, BN_GENCB *cb);
 160 int ossl_ffc_params_FIPS186_2_generate(OSSL_LIB_CTX *libctx, FFC_PARAMS *params,
 161                                        int type, size_t L, size_t N,
 162                                        int *res, BN_GENCB *cb);
 163
 164 int ossl_ffc_params_FIPS186_4_gen_verify(OSSL_LIB_CTX *libctx,
 165                                          FFC_PARAMS *params, int mode, int type,
 166                                          size_t L, size_t N, int *res,
 167                                          BN_GENCB *cb);
 168 int ossl_ffc_params_FIPS186_2_gen_verify(OSSL_LIB_CTX *libctx,
 169                                          FFC_PARAMS *params, int mode, int type,
 170                                          size_t L, size_t N, int *res,
 171                                          BN_GENCB *cb);
 172
 173 int ossl_ffc_params_simple_validate(OSSL_LIB_CTX *libctx,
 174                                     const FFC_PARAMS *params,
 175                                     int paramstype, int *res);
 176 int ossl_ffc_params_full_validate(OSSL_LIB_CTX *libctx,
 177                                   const FFC_PARAMS *params,
 178                                   int paramstype, int *res);
 179 int ossl_ffc_params_FIPS186_4_validate(OSSL_LIB_CTX *libctx,
 180                                        const FFC_PARAMS *params,
 181                                        int type, int *res, BN_GENCB *cb);
 182 int ossl_ffc_params_FIPS186_2_validate(OSSL_LIB_CTX *libctx,
 183                                        const FFC_PARAMS *params,
 184                                        int type, int *res, BN_GENCB *cb);
 185
 186 int ossl_ffc_generate_private_key(BN_CTX *ctx, const FFC_PARAMS *params,
 187                                   int N, int s, BIGNUM *priv);
 188
 189 int ossl_ffc_params_validate_unverifiable_g(BN_CTX *ctx, BN_MONT_CTX *mont,
 190                                             const BIGNUM *p, const BIGNUM *q,
 191                                             const BIGNUM *g, BIGNUM *tmp,
 192                                             int *ret);
 193
 194 int ossl_ffc_validate_public_key(const FFC_PARAMS *params,
 195                                  const BIGNUM *pub_key, int *ret);
 196 int ossl_ffc_validate_public_key_partial(const FFC_PARAMS *params,
 197                                          const BIGNUM *pub_key, int *ret);
 198 int ossl_ffc_validate_private_key(const BIGNUM *upper, const BIGNUM *priv_key,
 199                                  int *ret);
 200
 201 int ossl_ffc_params_todata(const FFC_PARAMS *ffc, OSSL_PARAM_BLD *tmpl,
 202                            OSSL_PARAM params[]);
 203 int ossl_ffc_params_fromdata(FFC_PARAMS *ffc, const OSSL_PARAM params[]);
 204
 205 typedef struct dh_named_group_st DH_NAMED_GROUP;
 206 const DH_NAMED_GROUP *ossl_ffc_name_to_dh_named_group(const char *name);
 207 const DH_NAMED_GROUP *ossl_ffc_uid_to_dh_named_group(int uid);
 208 #ifndef OPENSSL_NO_DH
 209 const DH_NAMED_GROUP *ossl_ffc_numbers_to_dh_named_group(const BIGNUM *p,
 210                                                          const BIGNUM *q,
 211                                                          const BIGNUM *g);
 212 #endif
 213 int ossl_ffc_named_group_get_uid(const DH_NAMED_GROUP *group);
 214 const char *ossl_ffc_named_group_get_name(const DH_NAMED_GROUP *);
 215 #ifndef OPENSSL_NO_DH
 216 int ossl_ffc_named_group_get_keylength(const DH_NAMED_GROUP *group);
 217 const BIGNUM *ossl_ffc_named_group_get_q(const DH_NAMED_GROUP *group);
 218 int ossl_ffc_named_group_set(FFC_PARAMS *ffc, const DH_NAMED_GROUP *group);
 219 #endif
 220
 221 #endif /* OSSL_INTERNAL_FFC_H */