Home | History | Annotate | Download | only in openssl
      1 /* Copyright (C) 1995-1998 Eric Young (eay (at) cryptsoft.com)
      2  * All rights reserved.
      3  *
      4  * This package is an SSL implementation written
      5  * by Eric Young (eay (at) 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 (at) 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 (at) 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 (at) 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 (at) 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 #include <openssl/thread.h>
     68 
     69 #if defined(__cplusplus)
     70 extern "C" {
     71 #endif
     72 
     73 
     74 // DSA contains functions for signing and verifying with the Digital Signature
     75 // Algorithm.
     76 
     77 
     78 // Allocation and destruction.
     79 
     80 // DSA_new returns a new, empty DSA object or NULL on error.
     81 OPENSSL_EXPORT DSA *DSA_new(void);
     82 
     83 // DSA_free decrements the reference count of |dsa| and frees it if the
     84 // reference count drops to zero.
     85 OPENSSL_EXPORT void DSA_free(DSA *dsa);
     86 
     87 // DSA_up_ref increments the reference count of |dsa| and returns one.
     88 OPENSSL_EXPORT int DSA_up_ref(DSA *dsa);
     89 
     90 
     91 // Properties.
     92 
     93 // DSA_get0_key sets |*out_pub_key| and |*out_priv_key|, if non-NULL, to |dsa|'s
     94 // public and private key, respectively. If |dsa| is a public key, the private
     95 // key will be set to NULL.
     96 OPENSSL_EXPORT void DSA_get0_key(const DSA *dsa, const BIGNUM **out_pub_key,
     97                                  const BIGNUM **out_priv_key);
     98 
     99 // DSA_get0_pqg sets |*out_p|, |*out_q|, and |*out_g|, if non-NULL, to |dsa|'s
    100 // p, q, and g parameters, respectively.
    101 OPENSSL_EXPORT void DSA_get0_pqg(const DSA *dsa, const BIGNUM **out_p,
    102                                  const BIGNUM **out_q, const BIGNUM **out_g);
    103 
    104 // DSA_set0_key sets |dsa|'s public and private key to |pub_key| and |priv_key|,
    105 // respectively, if non-NULL. On success, it takes ownership of each argument
    106 // and returns one. Otherwise, it returns zero.
    107 //
    108 // |priv_key| may be NULL, but |pub_key| must either be non-NULL or already
    109 // configured on |dsa|.
    110 OPENSSL_EXPORT int DSA_set0_key(DSA *dsa, BIGNUM *pub_key, BIGNUM *priv_key);
    111 
    112 // DSA_set0_pqg sets |dsa|'s parameters to |p|, |q|, and |g|, if non-NULL, and
    113 // takes ownership of them. On success, it takes ownership of each argument and
    114 // returns one. Otherwise, it returns zero.
    115 //
    116 // Each argument must either be non-NULL or already configured on |dsa|.
    117 OPENSSL_EXPORT int DSA_set0_pqg(DSA *dsa, BIGNUM *p, BIGNUM *q, BIGNUM *g);
    118 
    119 
    120 // Parameter generation.
    121 
    122 // DSA_generate_parameters_ex generates a set of DSA parameters by following
    123 // the procedure given in FIPS 186-4, appendix A.
    124 // (http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf)
    125 //
    126 // The larger prime will have a length of |bits| (e.g. 2048). The |seed| value
    127 // allows others to generate and verify the same parameters and should be
    128 // random input which is kept for reference. If |out_counter| or |out_h| are
    129 // not NULL then the counter and h value used in the generation are written to
    130 // them.
    131 //
    132 // The |cb| argument is passed to |BN_generate_prime_ex| and is thus called
    133 // during the generation process in order to indicate progress. See the
    134 // comments for that function for details. In addition to the calls made by
    135 // |BN_generate_prime_ex|, |DSA_generate_parameters_ex| will call it with
    136 // |event| equal to 2 and 3 at different stages of the process.
    137 //
    138 // It returns one on success and zero otherwise.
    139 OPENSSL_EXPORT int DSA_generate_parameters_ex(DSA *dsa, unsigned bits,
    140                                               const uint8_t *seed,
    141                                               size_t seed_len, int *out_counter,
    142                                               unsigned long *out_h,
    143                                               BN_GENCB *cb);
    144 
    145 // DSAparams_dup returns a freshly allocated |DSA| that contains a copy of the
    146 // parameters from |dsa|. It returns NULL on error.
    147 OPENSSL_EXPORT DSA *DSAparams_dup(const DSA *dsa);
    148 
    149 
    150 // Key generation.
    151 
    152 // DSA_generate_key generates a public/private key pair in |dsa|, which must
    153 // already have parameters setup. It returns one on success and zero on
    154 // error.
    155 OPENSSL_EXPORT int DSA_generate_key(DSA *dsa);
    156 
    157 
    158 // Signatures.
    159 
    160 // DSA_SIG_st (aka |DSA_SIG|) contains a DSA signature as a pair of integers.
    161 struct DSA_SIG_st {
    162   BIGNUM *r, *s;
    163 };
    164 
    165 // DSA_SIG_new returns a freshly allocated, DIG_SIG structure or NULL on error.
    166 // Both |r| and |s| in the signature will be NULL.
    167 OPENSSL_EXPORT DSA_SIG *DSA_SIG_new(void);
    168 
    169 // DSA_SIG_free frees the contents of |sig| and then frees |sig| itself.
    170 OPENSSL_EXPORT void DSA_SIG_free(DSA_SIG *sig);
    171 
    172 // DSA_do_sign returns a signature of the hash in |digest| by the key in |dsa|
    173 // and returns an allocated, DSA_SIG structure, or NULL on error.
    174 OPENSSL_EXPORT DSA_SIG *DSA_do_sign(const uint8_t *digest, size_t digest_len,
    175                                     const DSA *dsa);
    176 
    177 // DSA_do_verify verifies that |sig| is a valid signature, by the public key in
    178 // |dsa|, of the hash in |digest|. It returns one if so, zero if invalid and -1
    179 // on error.
    180 //
    181 // WARNING: do not use. This function returns -1 for error, 0 for invalid and 1
    182 // for valid. However, this is dangerously different to the usual OpenSSL
    183 // convention and could be a disaster if a user did |if (DSA_do_verify(...))|.
    184 // Because of this, |DSA_check_signature| is a safer version of this.
    185 //
    186 // TODO(fork): deprecate.
    187 OPENSSL_EXPORT int DSA_do_verify(const uint8_t *digest, size_t digest_len,
    188                                  DSA_SIG *sig, const DSA *dsa);
    189 
    190 // DSA_do_check_signature sets |*out_valid| to zero. Then it verifies that |sig|
    191 // is a valid signature, by the public key in |dsa| of the hash in |digest|
    192 // and, if so, it sets |*out_valid| to one.
    193 //
    194 // It returns one if it was able to verify the signature as valid or invalid,
    195 // and zero on error.
    196 OPENSSL_EXPORT int DSA_do_check_signature(int *out_valid, const uint8_t *digest,
    197                                           size_t digest_len, DSA_SIG *sig,
    198                                           const DSA *dsa);
    199 
    200 
    201 // ASN.1 signatures.
    202 //
    203 // These functions also perform DSA signature operations, but deal with ASN.1
    204 // encoded signatures as opposed to raw |BIGNUM|s. If you don't know what
    205 // encoding a DSA signature is in, it's probably ASN.1.
    206 
    207 // DSA_sign signs |digest| with the key in |dsa| and writes the resulting
    208 // signature, in ASN.1 form, to |out_sig| and the length of the signature to
    209 // |*out_siglen|. There must be, at least, |DSA_size(dsa)| bytes of space in
    210 // |out_sig|. It returns one on success and zero otherwise.
    211 //
    212 // (The |type| argument is ignored.)
    213 OPENSSL_EXPORT int DSA_sign(int type, const uint8_t *digest, size_t digest_len,
    214                             uint8_t *out_sig, unsigned int *out_siglen,
    215                             const DSA *dsa);
    216 
    217 // DSA_verify verifies that |sig| is a valid, ASN.1 signature, by the public
    218 // key in |dsa|, of the hash in |digest|. It returns one if so, zero if invalid
    219 // and -1 on error.
    220 //
    221 // (The |type| argument is ignored.)
    222 //
    223 // WARNING: do not use. This function returns -1 for error, 0 for invalid and 1
    224 // for valid. However, this is dangerously different to the usual OpenSSL
    225 // convention and could be a disaster if a user did |if (DSA_do_verify(...))|.
    226 // Because of this, |DSA_check_signature| is a safer version of this.
    227 //
    228 // TODO(fork): deprecate.
    229 OPENSSL_EXPORT int DSA_verify(int type, const uint8_t *digest,
    230                               size_t digest_len, const uint8_t *sig,
    231                               size_t sig_len, const DSA *dsa);
    232 
    233 // DSA_check_signature sets |*out_valid| to zero. Then it verifies that |sig|
    234 // is a valid, ASN.1 signature, by the public key in |dsa|, of the hash in
    235 // |digest|. If so, it sets |*out_valid| to one.
    236 //
    237 // It returns one if it was able to verify the signature as valid or invalid,
    238 // and zero on error.
    239 OPENSSL_EXPORT int DSA_check_signature(int *out_valid, const uint8_t *digest,
    240                                        size_t digest_len, const uint8_t *sig,
    241                                        size_t sig_len, const DSA *dsa);
    242 
    243 // DSA_size returns the size, in bytes, of an ASN.1 encoded, DSA signature
    244 // generated by |dsa|. Parameters must already have been setup in |dsa|.
    245 OPENSSL_EXPORT int DSA_size(const DSA *dsa);
    246 
    247 
    248 // ASN.1 encoding.
    249 
    250 // DSA_SIG_parse parses a DER-encoded DSA-Sig-Value structure from |cbs| and
    251 // advances |cbs|. It returns a newly-allocated |DSA_SIG| or NULL on error.
    252 OPENSSL_EXPORT DSA_SIG *DSA_SIG_parse(CBS *cbs);
    253 
    254 // DSA_SIG_marshal marshals |sig| as a DER-encoded DSA-Sig-Value and appends the
    255 // result to |cbb|. It returns one on success and zero on error.
    256 OPENSSL_EXPORT int DSA_SIG_marshal(CBB *cbb, const DSA_SIG *sig);
    257 
    258 // DSA_parse_public_key parses a DER-encoded DSA public key from |cbs| and
    259 // advances |cbs|. It returns a newly-allocated |DSA| or NULL on error.
    260 OPENSSL_EXPORT DSA *DSA_parse_public_key(CBS *cbs);
    261 
    262 // DSA_marshal_public_key marshals |dsa| as a DER-encoded DSA public key and
    263 // appends the result to |cbb|. It returns one on success and zero on
    264 // failure.
    265 OPENSSL_EXPORT int DSA_marshal_public_key(CBB *cbb, const DSA *dsa);
    266 
    267 // DSA_parse_private_key parses a DER-encoded DSA private key from |cbs| and
    268 // advances |cbs|. It returns a newly-allocated |DSA| or NULL on error.
    269 OPENSSL_EXPORT DSA *DSA_parse_private_key(CBS *cbs);
    270 
    271 // DSA_marshal_private_key marshals |dsa| as a DER-encoded DSA private key and
    272 // appends the result to |cbb|. It returns one on success and zero on
    273 // failure.
    274 OPENSSL_EXPORT int DSA_marshal_private_key(CBB *cbb, const DSA *dsa);
    275 
    276 // DSA_parse_parameters parses a DER-encoded Dss-Parms structure (RFC 3279)
    277 // from |cbs| and advances |cbs|. It returns a newly-allocated |DSA| or NULL on
    278 // error.
    279 OPENSSL_EXPORT DSA *DSA_parse_parameters(CBS *cbs);
    280 
    281 // DSA_marshal_parameters marshals |dsa| as a DER-encoded Dss-Parms structure
    282 // (RFC 3447) and appends the result to |cbb|. It returns one on success and
    283 // zero on failure.
    284 OPENSSL_EXPORT int DSA_marshal_parameters(CBB *cbb, const DSA *dsa);
    285 
    286 
    287 // Conversion.
    288 
    289 // DSA_dup_DH returns a |DH| constructed from the parameters of |dsa|. This is
    290 // sometimes needed when Diffie-Hellman parameters are stored in the form of
    291 // DSA parameters. It returns an allocated |DH| on success or NULL on error.
    292 OPENSSL_EXPORT DH *DSA_dup_DH(const DSA *dsa);
    293 
    294 
    295 // ex_data functions.
    296 //
    297 // See |ex_data.h| for details.
    298 
    299 OPENSSL_EXPORT int DSA_get_ex_new_index(long argl, void *argp,
    300                                         CRYPTO_EX_unused *unused,
    301                                         CRYPTO_EX_dup *dup_unused,
    302                                         CRYPTO_EX_free *free_func);
    303 OPENSSL_EXPORT int DSA_set_ex_data(DSA *dsa, int idx, void *arg);
    304 OPENSSL_EXPORT void *DSA_get_ex_data(const DSA *dsa, int idx);
    305 
    306 
    307 // Deprecated functions.
    308 
    309 // d2i_DSA_SIG parses an ASN.1, DER-encoded, DSA signature from |len| bytes at
    310 // |*inp|. If |out_sig| is not NULL then, on exit, a pointer to the result is
    311 // in |*out_sig|. Note that, even if |*out_sig| is already non-NULL on entry, it
    312 // will not be written to. Rather, a fresh |DSA_SIG| is allocated and the
    313 // previous one is freed. On successful exit, |*inp| is advanced past the DER
    314 // structure. It returns the result or NULL on error.
    315 //
    316 // Use |DSA_SIG_parse| instead.
    317 OPENSSL_EXPORT DSA_SIG *d2i_DSA_SIG(DSA_SIG **out_sig, const uint8_t **inp,
    318                                     long len);
    319 
    320 // i2d_DSA_SIG marshals |in| to an ASN.1, DER structure. If |outp| is not NULL
    321 // then the result is written to |*outp| and |*outp| is advanced just past the
    322 // output. It returns the number of bytes in the result, whether written or not,
    323 // or a negative value on error.
    324 //
    325 // Use |DSA_SIG_marshal| instead.
    326 OPENSSL_EXPORT int i2d_DSA_SIG(const DSA_SIG *in, uint8_t **outp);
    327 
    328 // d2i_DSAPublicKey parses an ASN.1, DER-encoded, DSA public key from |len|
    329 // bytes at |*inp|. If |out| is not NULL then, on exit, a pointer to the result
    330 // is in |*out|. Note that, even if |*ou| is already non-NULL on entry, it will
    331 // not be written to. Rather, a fresh |DSA| is allocated and the previous one is
    332 // freed. On successful exit, |*inp| is advanced past the DER structure. It
    333 // returns the result or NULL on error.
    334 //
    335 // Use |DSA_parse_public_key| instead.
    336 OPENSSL_EXPORT DSA *d2i_DSAPublicKey(DSA **out, const uint8_t **inp, long len);
    337 
    338 // i2d_DSAPublicKey marshals a public key from |in| to an ASN.1, DER structure.
    339 // If |outp| is not NULL then the result is written to |*outp| and |*outp| is
    340 // advanced just past the output. It returns the number of bytes in the result,
    341 // whether written or not, or a negative value on error.
    342 //
    343 // Use |DSA_marshal_public_key| instead.
    344 OPENSSL_EXPORT int i2d_DSAPublicKey(const DSA *in, uint8_t **outp);
    345 
    346 // d2i_DSAPrivateKey parses an ASN.1, DER-encoded, DSA private key from |len|
    347 // bytes at |*inp|. If |out| is not NULL then, on exit, a pointer to the result
    348 // is in |*out|. Note that, even if |*out| is already non-NULL on entry, it will
    349 // not be written to. Rather, a fresh |DSA| is allocated and the previous one is
    350 // freed. On successful exit, |*inp| is advanced past the DER structure. It
    351 // returns the result or NULL on error.
    352 //
    353 // Use |DSA_parse_private_key| instead.
    354 OPENSSL_EXPORT DSA *d2i_DSAPrivateKey(DSA **out, const uint8_t **inp, long len);
    355 
    356 // i2d_DSAPrivateKey marshals a private key from |in| to an ASN.1, DER
    357 // structure. If |outp| is not NULL then the result is written to |*outp| and
    358 // |*outp| is advanced just past the output. It returns the number of bytes in
    359 // the result, whether written or not, or a negative value on error.
    360 //
    361 // Use |DSA_marshal_private_key| instead.
    362 OPENSSL_EXPORT int i2d_DSAPrivateKey(const DSA *in, uint8_t **outp);
    363 
    364 // d2i_DSAparams parses ASN.1, DER-encoded, DSA parameters from |len| bytes at
    365 // |*inp|. If |out| is not NULL then, on exit, a pointer to the result is in
    366 // |*out|. Note that, even if |*out| is already non-NULL on entry, it will not
    367 // be written to. Rather, a fresh |DSA| is allocated and the previous one is
    368 // freed. On successful exit, |*inp| is advanced past the DER structure. It
    369 // returns the result or NULL on error.
    370 //
    371 // Use |DSA_parse_parameters| instead.
    372 OPENSSL_EXPORT DSA *d2i_DSAparams(DSA **out, const uint8_t **inp, long len);
    373 
    374 // i2d_DSAparams marshals DSA parameters from |in| to an ASN.1, DER structure.
    375 // If |outp| is not NULL then the result is written to |*outp| and |*outp| is
    376 // advanced just past the output. It returns the number of bytes in the result,
    377 // whether written or not, or a negative value on error.
    378 //
    379 // Use |DSA_marshal_parameters| instead.
    380 OPENSSL_EXPORT int i2d_DSAparams(const DSA *in, uint8_t **outp);
    381 
    382 // DSA_generate_parameters is a deprecated version of
    383 // |DSA_generate_parameters_ex| that creates and returns a |DSA*|. Don't use
    384 // it.
    385 OPENSSL_EXPORT DSA *DSA_generate_parameters(int bits, unsigned char *seed,
    386                                             int seed_len, int *counter_ret,
    387                                             unsigned long *h_ret,
    388                                             void (*callback)(int, int, void *),
    389                                             void *cb_arg);
    390 
    391 
    392 struct dsa_st {
    393   long version;
    394   BIGNUM *p;
    395   BIGNUM *q;  // == 20
    396   BIGNUM *g;
    397 
    398   BIGNUM *pub_key;   // y public key
    399   BIGNUM *priv_key;  // x private key
    400 
    401   int flags;
    402   // Normally used to cache montgomery values
    403   CRYPTO_MUTEX method_mont_lock;
    404   BN_MONT_CTX *method_mont_p;
    405   BN_MONT_CTX *method_mont_q;
    406   CRYPTO_refcount_t references;
    407   CRYPTO_EX_DATA ex_data;
    408 };
    409 
    410 
    411 #if defined(__cplusplus)
    412 }  // extern C
    413 
    414 extern "C++" {
    415 
    416 namespace bssl {
    417 
    418 BORINGSSL_MAKE_DELETER(DSA, DSA_free)
    419 BORINGSSL_MAKE_DELETER(DSA_SIG, DSA_SIG_free)
    420 
    421 }  // namespace bssl
    422 
    423 }  // extern C++
    424 
    425 #endif
    426 
    427 #define DSA_R_BAD_Q_VALUE 100
    428 #define DSA_R_MISSING_PARAMETERS 101
    429 #define DSA_R_MODULUS_TOO_LARGE 102
    430 #define DSA_R_NEED_NEW_SETUP_VALUES 103
    431 #define DSA_R_BAD_VERSION 104
    432 #define DSA_R_DECODE_ERROR 105
    433 #define DSA_R_ENCODE_ERROR 106
    434 
    435 #endif  // OPENSSL_HEADER_DSA_H
    436