src/third_party/boringssl/src/include/openssl/dsa.h

   1 /* Copyright (C) 1995-1998 Eric Young (eay@cryptsoft.com)
   2  * All rights reserved.
   3  *
   4  * This package is an SSL implementation written
   5  * by Eric Young (eay@cryptsoft.com).
   6  * The implementation was written so as to conform with Netscapes SSL.
   7  *
   8  * This library is free for commercial and non-commercial use as long as
   9  * the following conditions are aheared to.  The following conditions
  10  * apply to all code found in this distribution, be it the RC4, RSA,
  11  * lhash, DES, etc., code; not just the SSL code.  The SSL documentation
  12  * included with this distribution is covered by the same copyright terms
  13  * except that the holder is Tim Hudson (tjh@cryptsoft.com).
  14  *
  15  * Copyright remains Eric Young's, and as such any Copyright notices in
  16  * the code are not to be removed.
  17  * If this package is used in a product, Eric Young should be given attribution
  18  * as the author of the parts of the library used.
  19  * This can be in the form of a textual message at program startup or
  20  * in documentation (online or textual) provided with the package.
  21  *
  22  * Redistribution and use in source and binary forms, with or without
  23  * modification, are permitted provided that the following conditions
  24  * are met:
  25  * 1. Redistributions of source code must retain the copyright
  26  *    notice, this list of conditions and the following disclaimer.
  27  * 2. Redistributions in binary form must reproduce the above copyright
  28  *    notice, this list of conditions and the following disclaimer in the
  29  *    documentation and/or other materials provided with the distribution.
  30  * 3. All advertising materials mentioning features or use of this software
  31  *    must display the following acknowledgement:
  32  *    "This product includes cryptographic software written by
  33  *     Eric Young (eay@cryptsoft.com)"
  34  *    The word 'cryptographic' can be left out if the rouines from the library
  35  *    being used are not cryptographic related :-).
  36  * 4. If you include any Windows specific code (or a derivative thereof) from
  37  *    the apps directory (application code) you must include an acknowledgement:
  38  *    "This product includes software written by Tim Hudson (tjh@cryptsoft.com)"
  39  *
  40  * THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``AS IS'' AND
  41  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  42  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  43  * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  44  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  45  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  46  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  47  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  48  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  49  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  50  * SUCH DAMAGE.
  51  *
  52  * The licence and distribution terms for any publically available version or
  53  * derivative of this code cannot be changed.  i.e. this code cannot simply be
  54  * copied and put under another distribution licence
  55  * [including the GNU Public Licence.]
  56  *
  57  * The DSS routines are based on patches supplied by
  58  * Steven Schoch <schoch@sheba.arc.nasa.gov>. */
  59
  60 #ifndef OPENSSL_HEADER_DSA_H
  61 #define OPENSSL_HEADER_DSA_H
  62
  63 #include <openssl/base.h>
  64
  65 #include <openssl/engine.h>
  66 #include <openssl/ex_data.h>
  67
  68 #if defined(__cplusplus)
  69 extern "C" {
  70 #endif
  71
  72
  73 /* DSA contains functions for signing and verifing with the Digital Signature
  74  * Algorithm. */
  75
  76
  77 /* Allocation and destruction. */
  78
  79 /* DSA_new returns a new, empty DSA object or NULL on error. */
  80 OPENSSL_EXPORT DSA *DSA_new(void);
  81
  82 /* DSA_new_method acts the same as |DH_new| but takes an explicit |ENGINE|. */
  83 OPENSSL_EXPORT DSA *DSA_new_method(const ENGINE *engine);
  84
  85 /* DSA_free decrements the reference count of |dsa| and frees it if the
  86  * reference count drops to zero. */
  87 OPENSSL_EXPORT void DSA_free(DSA *dsa);
  88
  89 /* DSA_up_ref increments the reference count of |dsa|. */
  90 OPENSSL_EXPORT int DSA_up_ref(DSA *dsa);
  91
  92
  93 /* Parameter generation. */
  94
  95 /* DSA_generate_parameters_ex generates a set of DSA parameters by following
  96  * the procedure given in FIPS 186-4, appendix A.
  97  * (http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf)
  98  *
  99  * The larger prime will have a length of |bits| (e.g. 2048). The |seed| value
 100  * allows others to generate and verify the same parameters and should be
 101  * random input which is kept for reference. If |out_counter| or |out_h| are
 102  * not NULL then the counter and h value used in the generation are written to
 103  * them.
 104  *
 105  * The |cb| argument is passed to |BN_generate_prime_ex| and is thus called
 106  * during the generation process in order to indicate progress. See the
 107  * comments for that function for details. In addition to the calls made by
 108  * |BN_generate_prime_ex|, |DSA_generate_parameters_ex| will call it with
 109  * |event| equal to 2 and 3 at different stages of the process.
 110  *
 111  * It returns one on success and zero otherwise. */
 112 OPENSSL_EXPORT int DSA_generate_parameters_ex(DSA *dsa, unsigned bits,
 113                                               const uint8_t *seed,
 114                                               size_t seed_len, int *out_counter,
 115                                               unsigned long *out_h,
 116                                               BN_GENCB *cb);
 117
 118 /* DSAparams_dup returns a freshly allocated |DSA| that contains a copy of the
 119  * parameters from |dsa|. It returns NULL on error. */
 120 OPENSSL_EXPORT DSA *DSAparams_dup(const DSA *dsa);
 121
 122
 123 /* Key generation. */
 124
 125 /* DSA_generate_key generates a public/private key pair in |dsa|, which must
 126  * already have parameters setup. It returns one on success and zero on
 127  * error. */
 128 OPENSSL_EXPORT int DSA_generate_key(DSA *dsa);
 129
 130
 131 /* Signatures. */
 132
 133 /* DSA_SIG contains a DSA signature as a pair of integers. */
 134 typedef struct DSA_SIG_st {
 135   BIGNUM *r, *s;
 136 } DSA_SIG;
 137
 138 /* DSA_SIG_new returns a freshly allocated, DIG_SIG structure or NULL on error.
 139  * Both |r| and |s| in the signature will be NULL. */
 140 OPENSSL_EXPORT DSA_SIG *DSA_SIG_new(void);
 141
 142 /* DSA_SIG_free frees the contents of |sig| and then frees |sig| itself. */
 143 OPENSSL_EXPORT void DSA_SIG_free(DSA_SIG *sig);
 144
 145 /* DSA_do_sign returns a signature of the hash in |digest| by the key in |dsa|
 146  * and returns an allocated, DSA_SIG structure, or NULL on error. */
 147 OPENSSL_EXPORT DSA_SIG *DSA_do_sign(const uint8_t *digest, size_t digest_len,
 148                                     DSA *dsa);
 149
 150 /* DSA_do_verify verifies that |sig| is a valid signature, by the public key in
 151  * |dsa|, of the hash in |digest|. It returns one if so, zero if invalid and -1
 152  * on error.
 153  *
 154  * WARNING: do not use. This function returns -1 for error, 0 for invalid and 1
 155  * for valid. However, this is dangerously different to the usual OpenSSL
 156  * convention and could be a disaster if a user did |if (DSA_do_verify(...))|.
 157  * Because of this, |DSA_check_signature| is a safer version of this.
 158  *
 159  * TODO(fork): deprecate. */
 160 OPENSSL_EXPORT int DSA_do_verify(const uint8_t *digest, size_t digest_len,
 161                                  DSA_SIG *sig, const DSA *dsa);
 162
 163 /* DSA_check_signature sets |*out_valid| to zero. Then it verifies that |sig|
 164  * is a valid signature, by the public key in |dsa| of the hash in |digest|
 165  * and, if so, it sets |*out_valid| to one.
 166  *
 167  * It returns one if it was able to verify the signature as valid or invalid,
 168  * and zero on error. */
 169 OPENSSL_EXPORT int DSA_do_check_signature(int *out_valid, const uint8_t *digest,
 170                                           size_t digest_len, DSA_SIG *sig,
 171                                           const DSA *dsa);
 172
 173
 174 /* ASN.1 signatures.
 175  *
 176  * These functions also perform DSA signature operations, but deal with ASN.1
 177  * encoded signatures as opposed to raw |BIGNUM|s. If you don't know what
 178  * encoding a DSA signature is in, it's probably ASN.1. */
 179
 180 /* DSA_sign signs |digest| with the key in |dsa| and writes the resulting
 181  * signature, in ASN.1 form, to |out_sig| and the length of the signature to
 182  * |*out_siglen|. There must be, at least, |DSA_size(dsa)| bytes of space in
 183  * |out_sig|. It returns one on success and zero otherwise.
 184  *
 185  * (The |type| argument is ignored.) */
 186 OPENSSL_EXPORT int DSA_sign(int type, const uint8_t *digest, size_t digest_len,
 187                             uint8_t *out_sig, unsigned int *out_siglen,
 188                             DSA *dsa);
 189
 190 /* DSA_verify verifies that |sig| is a valid, ASN.1 signature, by the public
 191  * key in |dsa|, of the hash in |digest|. It returns one if so, zero if invalid
 192  * and -1 on error.
 193  *
 194  * (The |type| argument is ignored.)
 195  *
 196  * WARNING: do not use. This function returns -1 for error, 0 for invalid and 1
 197  * for valid. However, this is dangerously different to the usual OpenSSL
 198  * convention and could be a disaster if a user did |if (DSA_do_verify(...))|.
 199  * Because of this, |DSA_check_signature| is a safer version of this.
 200  *
 201  * TODO(fork): deprecate. */
 202 OPENSSL_EXPORT int DSA_verify(int type, const uint8_t *digest,
 203                               size_t digest_len, const uint8_t *sig,
 204                               size_t sig_len, const DSA *dsa);
 205
 206 /* DSA_check_signature sets |*out_valid| to zero. Then it verifies that |sig|
 207  * is a valid, ASN.1 signature, by the public key in |dsa|, of the hash in
 208  * |digest|. If so, it sets |*out_valid| to one.
 209  *
 210  * It returns one if it was able to verify the signature as valid or invalid,
 211  * and zero on error. */
 212 OPENSSL_EXPORT int DSA_check_signature(int *out_valid, const uint8_t *digest,
 213                                        size_t digest_len, const uint8_t *sig,
 214                                        size_t sig_len, const DSA *dsa);
 215
 216 /* DSA_size returns the size, in bytes, of an ASN.1 encoded, DSA signature
 217  * generated by |dsa|. Parameters must already have been setup in |dsa|. */
 218 OPENSSL_EXPORT int DSA_size(const DSA *dsa);
 219
 220
 221 /* ASN.1 encoding. */
 222
 223 /* d2i_DSA_SIG parses an ASN.1, DER-encoded, DSA signature from |len| bytes at
 224  * |*inp|. If |out_sig| is not NULL then, on exit, a pointer to the result is
 225  * in |*out_sig|. If |*out_sig| is already non-NULL on entry then the result is
 226  * written directly into |*out_sig|, otherwise a fresh |DSA_SIG| is allocated.
 227  * On successful exit, |*inp| is advanced past the DER structure. It returns
 228  * the result or NULL on error. */
 229 OPENSSL_EXPORT DSA_SIG *d2i_DSA_SIG(DSA_SIG **out_sig, const uint8_t **inp,
 230                                     long len);
 231
 232 /* i2d_DSA_SIG marshals |in| to an ASN.1, DER structure. If |outp| is not NULL
 233  * then the result is written to |*outp| and |*outp| is advanced just past the
 234  * output. It returns the number of bytes in the result, whether written or not,
 235  * or a negative value on error. */
 236 OPENSSL_EXPORT int i2d_DSA_SIG(const DSA_SIG *in, uint8_t **outp);
 237
 238 /* d2i_DSAPublicKey parses an ASN.1, DER-encoded, DSA public key from |len|
 239  * bytes at |*inp|. If |out| is not NULL then, on exit, a pointer to the result
 240  * is in |*out|. If |*out| is already non-NULL on entry then the result is
 241  * written directly into |*out|, otherwise a fresh |DSA| is allocated. On
 242  * successful exit, |*inp| is advanced past the DER structure. It returns the
 243  * result or NULL on error. */
 244 OPENSSL_EXPORT DSA *d2i_DSAPublicKey(DSA **out, const uint8_t **inp, long len);
 245
 246 /* i2d_DSAPublicKey marshals a public key from |in| to an ASN.1, DER structure.
 247  * If |outp| is not NULL then the result is written to |*outp| and |*outp| is
 248  * advanced just past the output. It returns the number of bytes in the result,
 249  * whether written or not, or a negative value on error. */
 250 OPENSSL_EXPORT int i2d_DSAPublicKey(const DSA *in, unsigned char **outp);
 251
 252 /* d2i_DSAPrivateKey parses an ASN.1, DER-encoded, DSA private key from |len|
 253  * bytes at |*inp|. If |out| is not NULL then, on exit, a pointer to the result
 254  * is in |*out|. If |*out| is already non-NULL on entry then the result is
 255  * written directly into |*out|, otherwise a fresh |DSA| is allocated. On
 256  * successful exit, |*inp| is advanced past the DER structure. It returns the
 257  * result or NULL on error. */
 258 OPENSSL_EXPORT DSA *d2i_DSAPrivateKey(DSA **out, const uint8_t **inp, long len);
 259
 260 /* i2d_DSAPrivateKey marshals a private key from |in| to an ASN.1, DER structure.
 261  * If |outp| is not NULL then the result is written to |*outp| and |*outp| is
 262  * advanced just past the output. It returns the number of bytes in the result,
 263  * whether written or not, or a negative value on error. */
 264 OPENSSL_EXPORT int i2d_DSAPrivateKey(const DSA *in, unsigned char **outp);
 265
 266 /* d2i_DSAparams parses ASN.1, DER-encoded, DSA parameters from |len| bytes at
 267  * |*inp|. If |out| is not NULL then, on exit, a pointer to the result is in
 268  * |*out|. If |*out| is already non-NULL on entry then the result is written
 269  * directly into |*out|, otherwise a fresh |DSA| is allocated. On successful
 270  * exit, |*inp| is advanced past the DER structure. It returns the result or
 271  * NULL on error. */
 272 OPENSSL_EXPORT DSA *d2i_DSAparams(DSA **out, const uint8_t **inp, long len);
 273
 274 /* i2d_DSAparams marshals DSA parameters from |in| to an ASN.1, DER structure.
 275  * If |outp| is not NULL then the result is written to |*outp| and |*outp| is
 276  * advanced just past the output. It returns the number of bytes in the result,
 277  * whether written or not, or a negative value on error. */
 278 OPENSSL_EXPORT int i2d_DSAparams(const DSA *in, unsigned char **outp);
 279
 280
 281 /* Precomputation. */
 282
 283 /* DSA_sign_setup precomputes the message independent part of the DSA signature
 284  * and writes them to |*out_kinv| and |*out_r|. Returns one on success, zero on
 285  * error.
 286  *
 287  * TODO(fork): decide what to do with this. Since making DSA* opaque there's no
 288  * way for the user to install them. Also, it forces the DSA* not to be const
 289  * when passing to the signing function. */
 290 OPENSSL_EXPORT int DSA_sign_setup(const DSA *dsa, BN_CTX *ctx,
 291                                   BIGNUM **out_kinv, BIGNUM **out_r);
 292
 293
 294 /* ex_data functions.
 295  *
 296  * These functions are wrappers. See |ex_data.h| for details. */
 297
 298 OPENSSL_EXPORT int DSA_get_ex_new_index(long argl, void *argp,
 299                                         CRYPTO_EX_new *new_func,
 300                                         CRYPTO_EX_dup *dup_func,
 301                                         CRYPTO_EX_free *free_func);
 302 OPENSSL_EXPORT int DSA_set_ex_data(DSA *d, int idx, void *arg);
 303 OPENSSL_EXPORT void *DSA_get_ex_data(const DSA *d, int idx);
 304
 305
 306 struct dsa_method {
 307   struct openssl_method_common_st common;
 308
 309   void *app_data;
 310
 311   int (*init)(DSA *dsa);
 312   int (*finish)(DSA *dsa);
 313
 314   DSA_SIG *(*sign)(const uint8_t *digest, size_t digest_len, DSA *dsa);
 315
 316   int (*sign_setup)(const DSA *dsa, BN_CTX *ctx_in, BIGNUM **kinvp, BIGNUM **rp,
 317                     const uint8_t *digest, size_t digest_len);
 318
 319   int (*verify)(int *out_valid, const uint8_t *digest, size_t digest_len,
 320                 DSA_SIG *sig, const DSA *dsa);
 321
 322   /* generate_parameters, if non-NULL, is used to generate DSA parameters. */
 323   int (*generate_parameters)(DSA *dsa, unsigned bits, const uint8_t *seed,
 324                              size_t seed_len, int *counter_ret,
 325                              unsigned long *h_ret, BN_GENCB *cb);
 326
 327   /* keygen, if non-NULL, is used to generate DSA keys. */
 328   int (*keygen)(DSA *dsa);
 329 };
 330
 331 struct dsa_st {
 332   long version;
 333   int write_params;
 334   BIGNUM *p;
 335   BIGNUM *q; /* == 20 */
 336   BIGNUM *g;
 337
 338   BIGNUM *pub_key;  /* y public key */
 339   BIGNUM *priv_key; /* x private key */
 340
 341   BIGNUM *kinv; /* Signing pre-calc */
 342   BIGNUM *r;    /* Signing pre-calc */
 343
 344   int flags;
 345   /* Normally used to cache montgomery values */
 346   BN_MONT_CTX *method_mont_p;
 347   int references;
 348   CRYPTO_EX_DATA ex_data;
 349   DSA_METHOD *meth;
 350   /* functional reference if 'meth' is ENGINE-provided */
 351   ENGINE *engine;
 352 };
 353
 354
 355 #if defined(__cplusplus)
 356 }  /* extern C */
 357 #endif
 358
 359 #define DSA_F_sign 100
 360 #define DSA_F_verify 101
 361 #define DSA_F_dsa_sig_cb 102
 362 #define DSA_F_DSA_new_method 103
 363 #define DSA_F_sign_setup 104
 364 #define DSA_R_NEED_NEW_SETUP_VALUES 100
 365 #define DSA_R_BAD_Q_VALUE 101
 366 #define DSA_R_MODULUS_TOO_LARGE 102
 367 #define DSA_R_MISSING_PARAMETERS 103
 368
 369 #endif  /* OPENSSL_HEADER_DSA_H */