Fix a typo in the i2d_TYPE_fp documentation
[openssl.git] / include / internal / ffc.h
1 /*
2  * Copyright 2019-2020 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
13 # include <openssl/core.h>
14 # include <openssl/bn.h>
15 # include <openssl/evp.h>
16 # include <openssl/dh.h> /* Uses Error codes from DH */
17 # include <openssl/params.h>
18 # include <openssl/param_build.h>
19
20 /* Default value for gindex when canonical generation of g is not used */
21 # define FFC_UNVERIFIABLE_GINDEX -1
22
23 /* The different types of FFC keys */
24 # define FFC_PARAM_TYPE_DSA  0
25 # define FFC_PARAM_TYPE_DH   1
26
27 /* Return codes for generation and validation of FFC parameters */
28 #define FFC_PARAMS_RET_STATUS_FAILED         0
29 #define FFC_PARAMS_RET_STATUS_SUCCESS        1
30 /* Returned if validating and g is only partially verifiable */
31 #define FFC_PARAMS_RET_STATUS_UNVERIFIABLE_G 2
32
33 /* Validation flags */
34 # define FFC_PARAMS_GENERATE     0x00
35 # define FFC_PARAMS_VALIDATE_PQ  0x01
36 # define FFC_PARAMS_VALIDATE_G   0x02
37 # define FFC_PARAMS_VALIDATE_ALL (FFC_PARAMS_VALIDATE_PQ | FFC_PARAMS_VALIDATE_G)
38
39 /*
40  * NB: These values must align with the equivalently named macros in
41  * openssl/dh.h. We cannot use those macros here in case DH has been disabled.
42  */
43 # define FFC_CHECK_P_NOT_PRIME                0x00001
44 # define FFC_CHECK_P_NOT_SAFE_PRIME           0x00002
45 # define FFC_CHECK_UNKNOWN_GENERATOR          0x00004
46 # define FFC_CHECK_NOT_SUITABLE_GENERATOR     0x00008
47 # define FFC_CHECK_Q_NOT_PRIME                0x00010
48 # define FFC_CHECK_INVALID_Q_VALUE            0x00020
49 # define FFC_CHECK_INVALID_J_VALUE            0x00040
50
51 # define FFC_CHECK_BAD_LN_PAIR                0x00080
52 # define FFC_CHECK_INVALID_SEED_SIZE          0x00100
53 # define FFC_CHECK_MISSING_SEED_OR_COUNTER    0x00200
54 # define FFC_CHECK_INVALID_G                  0x00400
55 # define FFC_CHECK_INVALID_PQ                 0x00800
56 # define FFC_CHECK_INVALID_COUNTER            0x01000
57 # define FFC_CHECK_P_MISMATCH                 0x02000
58 # define FFC_CHECK_Q_MISMATCH                 0x04000
59 # define FFC_CHECK_G_MISMATCH                 0x08000
60 # define FFC_CHECK_COUNTER_MISMATCH           0x10000
61
62 /* Validation Return codes */
63 # define FFC_ERROR_PUBKEY_TOO_SMALL       0x01
64 # define FFC_ERROR_PUBKEY_TOO_LARGE       0x02
65 # define FFC_ERROR_PUBKEY_INVALID         0x04
66 # define FFC_ERROR_NOT_SUITABLE_GENERATOR 0x08
67 # define FFC_ERROR_PRIVKEY_TOO_SMALL      0x10
68 # define FFC_ERROR_PRIVKEY_TOO_LARGE      0x20
69
70 /*
71  * Finite field cryptography (FFC) domain parameters are used by DH and DSA.
72  * Refer to FIPS186_4 Appendix A & B.
73  */
74 typedef struct ffc_params_st {
75     /* Primes */
76     BIGNUM *p;
77     BIGNUM *q;
78     /* Generator */
79     BIGNUM *g;
80     /* DH X9.42 Optional Subgroup factor j >= 2 where p = j * q + 1 */
81     BIGNUM *j;
82
83     /* Required for FIPS186_4 validation of p, q and optionally canonical g */
84     unsigned char *seed;
85     /* If this value is zero the hash size is used as the seed length */
86     size_t seedlen;
87     /* Required for FIPS186_4 validation of p and q */
88     int pcounter;
89     int nid; /* The identity of a named group */
90
91     /*
92      * Required for FIPS186_4 generation & validation of canonical g.
93      * It uses unverifiable g if this value is -1.
94      */
95     int gindex;
96     int h; /* loop counter for unverifiable g */
97 } FFC_PARAMS;
98
99 void ffc_params_init(FFC_PARAMS *params);
100 void ffc_params_cleanup(FFC_PARAMS *params);
101 void ffc_params_set0_pqg(FFC_PARAMS *params, BIGNUM *p, BIGNUM *q, BIGNUM *g);
102 void ffc_params_get0_pqg(const FFC_PARAMS *params, const BIGNUM **p,
103                          const BIGNUM **q, const BIGNUM **g);
104 void ffc_params_set0_j(FFC_PARAMS *d, BIGNUM *j);
105 int ffc_params_set_seed(FFC_PARAMS *params,
106                         const unsigned char *seed, size_t seedlen);
107 void ffc_params_set_gindex(FFC_PARAMS *params, int index);
108 void ffc_params_set_pcounter(FFC_PARAMS *params, int index);
109 void ffc_params_set_h(FFC_PARAMS *params, int index);
110
111 int ffc_params_set_validate_params(FFC_PARAMS *params,
112                                    const unsigned char *seed, size_t seedlen,
113                                    int counter);
114 void ffc_params_get_validate_params(const FFC_PARAMS *params,
115                                     unsigned char **seed, size_t *seedlen,
116                                     int *pcounter);
117
118 int ffc_params_copy(FFC_PARAMS *dst, const FFC_PARAMS *src);
119 int ffc_params_cmp(const FFC_PARAMS *a, const FFC_PARAMS *b, int ignore_q);
120
121 #ifndef FIPS_MODULE
122 int ffc_params_print(BIO *bp, const FFC_PARAMS *ffc, int indent);
123 #endif /* FIPS_MODULE */
124
125
126 int ffc_params_FIPS186_4_generate(OPENSSL_CTX *libctx, FFC_PARAMS *params,
127                                   int type, size_t L, size_t N,
128                                   const EVP_MD *evpmd, int *res, BN_GENCB *cb);
129 int ffc_params_FIPS186_2_generate(OPENSSL_CTX *libctx, FFC_PARAMS *params,
130                                   int type, size_t L, size_t N,
131                                   const EVP_MD *evpmd, int *res, BN_GENCB *cb);
132
133 int ffc_params_FIPS186_4_gen_verify(OPENSSL_CTX *libctx, FFC_PARAMS *params,
134                                     int type, size_t L, size_t N,
135                                     const EVP_MD *evpmd, int validate_flags,
136                                     int *res, BN_GENCB *cb);
137 int ffc_params_FIPS186_2_gen_verify(OPENSSL_CTX *libctx, FFC_PARAMS *params,
138                                     int type, size_t L, size_t N,
139                                     const EVP_MD *evpmd, int validate_flags,
140                                     int *res, BN_GENCB *cb);
141
142 int ffc_params_FIPS186_4_validate(const FFC_PARAMS *params, int type,
143                                   const EVP_MD *evpmd, int validate_flags,
144                                   int *res, BN_GENCB *cb);
145 int ffc_params_FIPS186_2_validate(const FFC_PARAMS *params, int type,
146                                   const EVP_MD *evpmd, int validate_flags,
147                                   int *res, BN_GENCB *cb);
148
149
150 int ffc_generate_private_key(BN_CTX *ctx, const FFC_PARAMS *params,
151                              int N, int s, BIGNUM *priv);
152
153 int ffc_params_validate_unverifiable_g(BN_CTX *ctx, BN_MONT_CTX *mont,
154                                        const BIGNUM *p, const BIGNUM *q,
155                                        const BIGNUM *g, BIGNUM *tmp, int *ret);
156
157 int ffc_validate_public_key(const FFC_PARAMS *params, const BIGNUM *pub_key,
158                             int *ret);
159 int ffc_validate_public_key_partial(const FFC_PARAMS *params,
160                                     const BIGNUM *pub_key, int *ret);
161 int ffc_validate_private_key(const BIGNUM *upper, const BIGNUM *priv_key,
162                              int *ret);
163
164 int ffc_params_todata(const FFC_PARAMS *ffc, OSSL_PARAM_BLD *tmpl,
165                       OSSL_PARAM params[]);
166 int ffc_params_fromdata(FFC_PARAMS *ffc, const OSSL_PARAM params[]);
167 int ffc_set_group_pqg(FFC_PARAMS *ffc, const char *group_name);
168 int ffc_named_group_to_uid(const char *name);
169 const char *ffc_named_group_from_uid(int nid);
170 int ffc_set_group_pqg(FFC_PARAMS *ffc, const char *group_name);
171
172 #endif /* OSSL_INTERNAL_FFC_H */