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 */
90typedef 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
125void ossl_ffc_params_init(FFC_PARAMS *params);
126void ossl_ffc_params_cleanup(FFC_PARAMS *params);
127void ossl_ffc_params_set0_pqg(FFC_PARAMS *params, BIGNUM *p, BIGNUM *q,
128                              BIGNUM *g);
129void ossl_ffc_params_get0_pqg(const FFC_PARAMS *params, const BIGNUM **p,
130                              const BIGNUM **q, const BIGNUM **g);
131void ossl_ffc_params_set0_j(FFC_PARAMS *d, BIGNUM *j);
132int ossl_ffc_params_set_seed(FFC_PARAMS *params,
133                             const unsigned char *seed, size_t seedlen);
134void ossl_ffc_params_set_gindex(FFC_PARAMS *params, int index);
135void ossl_ffc_params_set_pcounter(FFC_PARAMS *params, int index);
136void ossl_ffc_params_set_h(FFC_PARAMS *params, int index);
137void ossl_ffc_params_set_flags(FFC_PARAMS *params, unsigned int flags);
138void ossl_ffc_params_enable_flags(FFC_PARAMS *params, unsigned int flags,
139                                  int enable);
140int ossl_ffc_set_digest(FFC_PARAMS *params, const char *alg, const char *props);
141
142int ossl_ffc_params_set_validate_params(FFC_PARAMS *params,
143                                        const unsigned char *seed,
144                                        size_t seedlen, int counter);
145void ossl_ffc_params_get_validate_params(const FFC_PARAMS *params,
146                                         unsigned char **seed, size_t *seedlen,
147                                         int *pcounter);
148
149int ossl_ffc_params_copy(FFC_PARAMS *dst, const FFC_PARAMS *src);
150int ossl_ffc_params_cmp(const FFC_PARAMS *a, const FFC_PARAMS *b, int ignore_q);
151
152#ifndef FIPS_MODULE
153int ossl_ffc_params_print(BIO *bp, const FFC_PARAMS *ffc, int indent);
154#endif /* FIPS_MODULE */
155
156
157int 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);
160int 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
164int 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);
168int 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
173int ossl_ffc_params_simple_validate(OSSL_LIB_CTX *libctx,
174                                    const FFC_PARAMS *params,
175                                    int paramstype, int *res);
176int ossl_ffc_params_full_validate(OSSL_LIB_CTX *libctx,
177                                  const FFC_PARAMS *params,
178                                  int paramstype, int *res);
179int ossl_ffc_params_FIPS186_4_validate(OSSL_LIB_CTX *libctx,
180                                       const FFC_PARAMS *params,
181                                       int type, int *res, BN_GENCB *cb);
182int ossl_ffc_params_FIPS186_2_validate(OSSL_LIB_CTX *libctx,
183                                       const FFC_PARAMS *params,
184                                       int type, int *res, BN_GENCB *cb);
185
186int ossl_ffc_generate_private_key(BN_CTX *ctx, const FFC_PARAMS *params,
187                                  int N, int s, BIGNUM *priv);
188
189int 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
194int ossl_ffc_validate_public_key(const FFC_PARAMS *params,
195                                 const BIGNUM *pub_key, int *ret);
196int ossl_ffc_validate_public_key_partial(const FFC_PARAMS *params,
197                                         const BIGNUM *pub_key, int *ret);
198int ossl_ffc_validate_private_key(const BIGNUM *upper, const BIGNUM *priv_key,
199                                 int *ret);
200
201int ossl_ffc_params_todata(const FFC_PARAMS *ffc, OSSL_PARAM_BLD *tmpl,
202                           OSSL_PARAM params[]);
203int ossl_ffc_params_fromdata(FFC_PARAMS *ffc, const OSSL_PARAM params[]);
204
205typedef struct dh_named_group_st DH_NAMED_GROUP;
206const DH_NAMED_GROUP *ossl_ffc_name_to_dh_named_group(const char *name);
207const DH_NAMED_GROUP *ossl_ffc_uid_to_dh_named_group(int uid);
208#ifndef OPENSSL_NO_DH
209const DH_NAMED_GROUP *ossl_ffc_numbers_to_dh_named_group(const BIGNUM *p,
210                                                         const BIGNUM *q,
211                                                         const BIGNUM *g);
212#endif
213int ossl_ffc_named_group_get_uid(const DH_NAMED_GROUP *group);
214const char *ossl_ffc_named_group_get_name(const DH_NAMED_GROUP *);
215#ifndef OPENSSL_NO_DH
216int ossl_ffc_named_group_get_keylength(const DH_NAMED_GROUP *group);
217const BIGNUM *ossl_ffc_named_group_get_q(const DH_NAMED_GROUP *group);
218int ossl_ffc_named_group_set(FFC_PARAMS *ffc, const DH_NAMED_GROUP *group);
219#endif
220
221#endif /* OSSL_INTERNAL_FFC_H */
222