1 /* 2 * Copyright 1995-2016 The OpenSSL Project Authors. All Rights Reserved. 3 * 4 * Licensed under the OpenSSL license (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 OPENSSL_HEADER_DSA_H 11 #define OPENSSL_HEADER_DSA_H 12 13 #include <openssl/base.h> 14 15 #include <openssl/ex_data.h> 16 17 #if defined(__cplusplus) 18 extern "C" { 19 #endif 20 21 22 // DSA contains functions for signing and verifying with the Digital Signature 23 // Algorithm. 24 // 25 // This module is deprecated and retained for legacy reasons only. It is not 26 // considered a priority for performance or hardening work. Do not use it in 27 // new code. Use Ed25519, ECDSA with P-256, or RSA instead. 28 29 30 // Allocation and destruction. 31 // 32 // A |DSA| object represents a DSA key or group parameters. A given object may 33 // be used concurrently on multiple threads by non-mutating functions, provided 34 // no other thread is concurrently calling a mutating function. Unless otherwise 35 // documented, functions which take a |const| pointer are non-mutating and 36 // functions which take a non-|const| pointer are mutating. 37 38 // DSA_new returns a new, empty DSA object or NULL on error. 39 OPENSSL_EXPORT DSA *DSA_new(void); 40 41 // DSA_free decrements the reference count of |dsa| and frees it if the 42 // reference count drops to zero. 43 OPENSSL_EXPORT void DSA_free(DSA *dsa); 44 45 // DSA_up_ref increments the reference count of |dsa| and returns one. It does 46 // not mutate |dsa| for thread-safety purposes and may be used concurrently. 47 OPENSSL_EXPORT int DSA_up_ref(DSA *dsa); 48 49 50 // Properties. 51 52 // OPENSSL_DSA_MAX_MODULUS_BITS is the maximum supported DSA group modulus, in 53 // bits. 54 #define OPENSSL_DSA_MAX_MODULUS_BITS 10000 55 56 // DSA_bits returns the size of |dsa|'s group modulus, in bits. 57 OPENSSL_EXPORT unsigned DSA_bits(const DSA *dsa); 58 59 // DSA_get0_pub_key returns |dsa|'s public key. 60 OPENSSL_EXPORT const BIGNUM *DSA_get0_pub_key(const DSA *dsa); 61 62 // DSA_get0_priv_key returns |dsa|'s private key, or NULL if |dsa| is a public 63 // key. 64 OPENSSL_EXPORT const BIGNUM *DSA_get0_priv_key(const DSA *dsa); 65 66 // DSA_get0_p returns |dsa|'s group modulus. 67 OPENSSL_EXPORT const BIGNUM *DSA_get0_p(const DSA *dsa); 68 69 // DSA_get0_q returns the size of |dsa|'s subgroup. 70 OPENSSL_EXPORT const BIGNUM *DSA_get0_q(const DSA *dsa); 71 72 // DSA_get0_g returns |dsa|'s group generator. 73 OPENSSL_EXPORT const BIGNUM *DSA_get0_g(const DSA *dsa); 74 75 // DSA_get0_key sets |*out_pub_key| and |*out_priv_key|, if non-NULL, to |dsa|'s 76 // public and private key, respectively. If |dsa| is a public key, the private 77 // key will be set to NULL. 78 OPENSSL_EXPORT void DSA_get0_key(const DSA *dsa, const BIGNUM **out_pub_key, 79 const BIGNUM **out_priv_key); 80 81 // DSA_get0_pqg sets |*out_p|, |*out_q|, and |*out_g|, if non-NULL, to |dsa|'s 82 // p, q, and g parameters, respectively. 83 OPENSSL_EXPORT void DSA_get0_pqg(const DSA *dsa, const BIGNUM **out_p, 84 const BIGNUM **out_q, const BIGNUM **out_g); 85 86 // DSA_set0_key sets |dsa|'s public and private key to |pub_key| and |priv_key|, 87 // respectively, if non-NULL. On success, it takes ownership of each argument 88 // and returns one. Otherwise, it returns zero. 89 // 90 // |priv_key| may be NULL, but |pub_key| must either be non-NULL or already 91 // configured on |dsa|. 92 OPENSSL_EXPORT int DSA_set0_key(DSA *dsa, BIGNUM *pub_key, BIGNUM *priv_key); 93 94 // DSA_set0_pqg sets |dsa|'s parameters to |p|, |q|, and |g|, if non-NULL, and 95 // takes ownership of them. On success, it takes ownership of each argument and 96 // returns one. Otherwise, it returns zero. 97 // 98 // Each argument must either be non-NULL or already configured on |dsa|. 99 OPENSSL_EXPORT int DSA_set0_pqg(DSA *dsa, BIGNUM *p, BIGNUM *q, BIGNUM *g); 100 101 102 // Parameter generation. 103 104 // DSA_generate_parameters_ex generates a set of DSA parameters by following 105 // the procedure given in FIPS 186-4, appendix A. 106 // (http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf) 107 // 108 // The larger prime will have a length of |bits| (e.g. 2048). The |seed| value 109 // allows others to generate and verify the same parameters and should be 110 // random input which is kept for reference. If |out_counter| or |out_h| are 111 // not NULL then the counter and h value used in the generation are written to 112 // them. 113 // 114 // The |cb| argument is passed to |BN_generate_prime_ex| and is thus called 115 // during the generation process in order to indicate progress. See the 116 // comments for that function for details. In addition to the calls made by 117 // |BN_generate_prime_ex|, |DSA_generate_parameters_ex| will call it with 118 // |event| equal to 2 and 3 at different stages of the process. 119 // 120 // It returns one on success and zero otherwise. 121 OPENSSL_EXPORT int DSA_generate_parameters_ex(DSA *dsa, unsigned bits, 122 const uint8_t *seed, 123 size_t seed_len, int *out_counter, 124 unsigned long *out_h, 125 BN_GENCB *cb); 126 127 // DSAparams_dup returns a freshly allocated |DSA| that contains a copy of the 128 // parameters from |dsa|. It returns NULL on error. 129 OPENSSL_EXPORT DSA *DSAparams_dup(const DSA *dsa); 130 131 132 // Key generation. 133 134 // DSA_generate_key generates a public/private key pair in |dsa|, which must 135 // already have parameters setup. It returns one on success and zero on 136 // error. 137 OPENSSL_EXPORT int DSA_generate_key(DSA *dsa); 138 139 140 // Signatures. 141 142 // DSA_SIG_st (aka |DSA_SIG|) contains a DSA signature as a pair of integers. 143 struct DSA_SIG_st { 144 BIGNUM *r, *s; 145 }; 146 147 // DSA_SIG_new returns a freshly allocated, DIG_SIG structure or NULL on error. 148 // Both |r| and |s| in the signature will be NULL. 149 OPENSSL_EXPORT DSA_SIG *DSA_SIG_new(void); 150 151 // DSA_SIG_free frees the contents of |sig| and then frees |sig| itself. 152 OPENSSL_EXPORT void DSA_SIG_free(DSA_SIG *sig); 153 154 // DSA_SIG_get0 sets |*out_r| and |*out_s|, if non-NULL, to the two components 155 // of |sig|. 156 OPENSSL_EXPORT void DSA_SIG_get0(const DSA_SIG *sig, const BIGNUM **out_r, 157 const BIGNUM **out_s); 158 159 // DSA_SIG_set0 sets |sig|'s components to |r| and |s|, neither of which may be 160 // NULL. On success, it takes ownership of each argument and returns one. 161 // Otherwise, it returns zero. 162 OPENSSL_EXPORT int DSA_SIG_set0(DSA_SIG *sig, BIGNUM *r, BIGNUM *s); 163 164 // DSA_do_sign returns a signature of the hash in |digest| by the key in |dsa| 165 // and returns an allocated, DSA_SIG structure, or NULL on error. 166 OPENSSL_EXPORT DSA_SIG *DSA_do_sign(const uint8_t *digest, size_t digest_len, 167 const DSA *dsa); 168 169 // DSA_do_verify verifies that |sig| is a valid signature, by the public key in 170 // |dsa|, of the hash in |digest|. It returns one if so, zero if invalid and -1 171 // on error. 172 // 173 // WARNING: do not use. This function returns -1 for error, 0 for invalid and 1 174 // for valid. However, this is dangerously different to the usual OpenSSL 175 // convention and could be a disaster if a user did |if (DSA_do_verify(...))|. 176 // Because of this, |DSA_check_signature| is a safer version of this. 177 // 178 // TODO(fork): deprecate. 179 OPENSSL_EXPORT int DSA_do_verify(const uint8_t *digest, size_t digest_len, 180 const DSA_SIG *sig, const DSA *dsa); 181 182 // DSA_do_check_signature sets |*out_valid| to zero. Then it verifies that |sig| 183 // is a valid signature, by the public key in |dsa| of the hash in |digest| 184 // and, if so, it sets |*out_valid| to one. 185 // 186 // It returns one if it was able to verify the signature as valid or invalid, 187 // and zero on error. 188 OPENSSL_EXPORT int DSA_do_check_signature(int *out_valid, const uint8_t *digest, 189 size_t digest_len, const DSA_SIG *sig, 190 const DSA *dsa); 191 192 193 // ASN.1 signatures. 194 // 195 // These functions also perform DSA signature operations, but deal with ASN.1 196 // encoded signatures as opposed to raw |BIGNUM|s. If you don't know what 197 // encoding a DSA signature is in, it's probably ASN.1. 198 199 // DSA_sign signs |digest| with the key in |dsa| and writes the resulting 200 // signature, in ASN.1 form, to |out_sig| and the length of the signature to 201 // |*out_siglen|. There must be, at least, |DSA_size(dsa)| bytes of space in 202 // |out_sig|. It returns one on success and zero otherwise. 203 // 204 // (The |type| argument is ignored.) 205 OPENSSL_EXPORT int DSA_sign(int type, const uint8_t *digest, size_t digest_len, 206 uint8_t *out_sig, unsigned int *out_siglen, 207 const DSA *dsa); 208 209 // DSA_verify verifies that |sig| is a valid, ASN.1 signature, by the public 210 // key in |dsa|, of the hash in |digest|. It returns one if so, zero if invalid 211 // and -1 on error. 212 // 213 // (The |type| argument is ignored.) 214 // 215 // WARNING: do not use. This function returns -1 for error, 0 for invalid and 1 216 // for valid. However, this is dangerously different to the usual OpenSSL 217 // convention and could be a disaster if a user did |if (DSA_do_verify(...))|. 218 // Because of this, |DSA_check_signature| is a safer version of this. 219 // 220 // TODO(fork): deprecate. 221 OPENSSL_EXPORT int DSA_verify(int type, const uint8_t *digest, 222 size_t digest_len, const uint8_t *sig, 223 size_t sig_len, const DSA *dsa); 224 225 // DSA_check_signature sets |*out_valid| to zero. Then it verifies that |sig| 226 // is a valid, ASN.1 signature, by the public key in |dsa|, of the hash in 227 // |digest|. If so, it sets |*out_valid| to one. 228 // 229 // It returns one if it was able to verify the signature as valid or invalid, 230 // and zero on error. 231 OPENSSL_EXPORT int DSA_check_signature(int *out_valid, const uint8_t *digest, 232 size_t digest_len, const uint8_t *sig, 233 size_t sig_len, const DSA *dsa); 234 235 // DSA_size returns the size, in bytes, of an ASN.1 encoded, DSA signature 236 // generated by |dsa|. Parameters must already have been setup in |dsa|. 237 OPENSSL_EXPORT int DSA_size(const DSA *dsa); 238 239 240 // ASN.1 encoding. 241 242 // DSA_SIG_parse parses a DER-encoded DSA-Sig-Value structure from |cbs| and 243 // advances |cbs|. It returns a newly-allocated |DSA_SIG| or NULL on error. 244 OPENSSL_EXPORT DSA_SIG *DSA_SIG_parse(CBS *cbs); 245 246 // DSA_SIG_marshal marshals |sig| as a DER-encoded DSA-Sig-Value and appends the 247 // result to |cbb|. It returns one on success and zero on error. 248 OPENSSL_EXPORT int DSA_SIG_marshal(CBB *cbb, const DSA_SIG *sig); 249 250 // DSA_parse_public_key parses a DER-encoded DSA public key from |cbs| and 251 // advances |cbs|. It returns a newly-allocated |DSA| or NULL on error. 252 OPENSSL_EXPORT DSA *DSA_parse_public_key(CBS *cbs); 253 254 // DSA_marshal_public_key marshals |dsa| as a DER-encoded DSA public key and 255 // appends the result to |cbb|. It returns one on success and zero on 256 // failure. 257 OPENSSL_EXPORT int DSA_marshal_public_key(CBB *cbb, const DSA *dsa); 258 259 // DSA_parse_private_key parses a DER-encoded DSA private key from |cbs| and 260 // advances |cbs|. It returns a newly-allocated |DSA| or NULL on error. 261 OPENSSL_EXPORT DSA *DSA_parse_private_key(CBS *cbs); 262 263 // DSA_marshal_private_key marshals |dsa| as a DER-encoded DSA private key and 264 // appends the result to |cbb|. It returns one on success and zero on 265 // failure. 266 OPENSSL_EXPORT int DSA_marshal_private_key(CBB *cbb, const DSA *dsa); 267 268 // DSA_parse_parameters parses a DER-encoded Dss-Parms structure (RFC 3279) 269 // from |cbs| and advances |cbs|. It returns a newly-allocated |DSA| or NULL on 270 // error. 271 OPENSSL_EXPORT DSA *DSA_parse_parameters(CBS *cbs); 272 273 // DSA_marshal_parameters marshals |dsa| as a DER-encoded Dss-Parms structure 274 // (RFC 3279) and appends the result to |cbb|. It returns one on success and 275 // zero on failure. 276 OPENSSL_EXPORT int DSA_marshal_parameters(CBB *cbb, const DSA *dsa); 277 278 279 // Conversion. 280 281 // DSA_dup_DH returns a |DH| constructed from the parameters of |dsa|. This is 282 // sometimes needed when Diffie-Hellman parameters are stored in the form of 283 // DSA parameters. It returns an allocated |DH| on success or NULL on error. 284 OPENSSL_EXPORT DH *DSA_dup_DH(const DSA *dsa); 285 286 287 // ex_data functions. 288 // 289 // See |ex_data.h| for details. 290 291 OPENSSL_EXPORT int DSA_get_ex_new_index(long argl, void *argp, 292 CRYPTO_EX_unused *unused, 293 CRYPTO_EX_dup *dup_unused, 294 CRYPTO_EX_free *free_func); 295 OPENSSL_EXPORT int DSA_set_ex_data(DSA *dsa, int idx, void *arg); 296 OPENSSL_EXPORT void *DSA_get_ex_data(const DSA *dsa, int idx); 297 298 299 // Deprecated functions. 300 301 // d2i_DSA_SIG parses a DER-encoded DSA-Sig-Value structure from |len| bytes at 302 // |*inp|, as described in |d2i_SAMPLE|. 303 // 304 // Use |DSA_SIG_parse| instead. 305 OPENSSL_EXPORT DSA_SIG *d2i_DSA_SIG(DSA_SIG **out_sig, const uint8_t **inp, 306 long len); 307 308 // i2d_DSA_SIG marshals |in| to a DER-encoded DSA-Sig-Value structure, as 309 // described in |i2d_SAMPLE|. 310 // 311 // Use |DSA_SIG_marshal| instead. 312 OPENSSL_EXPORT int i2d_DSA_SIG(const DSA_SIG *in, uint8_t **outp); 313 314 // d2i_DSAPublicKey parses a DER-encoded DSA public key from |len| bytes at 315 // |*inp|, as described in |d2i_SAMPLE|. 316 // 317 // Use |DSA_parse_public_key| instead. 318 OPENSSL_EXPORT DSA *d2i_DSAPublicKey(DSA **out, const uint8_t **inp, long len); 319 320 // i2d_DSAPublicKey marshals |in| as a DER-encoded DSA public key, as described 321 // in |i2d_SAMPLE|. 322 // 323 // Use |DSA_marshal_public_key| instead. 324 OPENSSL_EXPORT int i2d_DSAPublicKey(const DSA *in, uint8_t **outp); 325 326 // d2i_DSAPrivateKey parses a DER-encoded DSA private key from |len| bytes at 327 // |*inp|, as described in |d2i_SAMPLE|. 328 // 329 // Use |DSA_parse_private_key| instead. 330 OPENSSL_EXPORT DSA *d2i_DSAPrivateKey(DSA **out, const uint8_t **inp, long len); 331 332 // i2d_DSAPrivateKey marshals |in| as a DER-encoded DSA private key, as 333 // described in |i2d_SAMPLE|. 334 // 335 // Use |DSA_marshal_private_key| instead. 336 OPENSSL_EXPORT int i2d_DSAPrivateKey(const DSA *in, uint8_t **outp); 337 338 // d2i_DSAparams parses a DER-encoded Dss-Parms structure (RFC 3279) from |len| 339 // bytes at |*inp|, as described in |d2i_SAMPLE|. 340 // 341 // Use |DSA_parse_parameters| instead. 342 OPENSSL_EXPORT DSA *d2i_DSAparams(DSA **out, const uint8_t **inp, long len); 343 344 // i2d_DSAparams marshals |in|'s parameters as a DER-encoded Dss-Parms structure 345 // (RFC 3279), as described in |i2d_SAMPLE|. 346 // 347 // Use |DSA_marshal_parameters| instead. 348 OPENSSL_EXPORT int i2d_DSAparams(const DSA *in, uint8_t **outp); 349 350 // DSA_generate_parameters is a deprecated version of 351 // |DSA_generate_parameters_ex| that creates and returns a |DSA*|. Don't use 352 // it. 353 OPENSSL_EXPORT DSA *DSA_generate_parameters(int bits, unsigned char *seed, 354 int seed_len, int *counter_ret, 355 unsigned long *h_ret, 356 void (*callback)(int, int, void *), 357 void *cb_arg); 358 359 360 #if defined(__cplusplus) 361 } // extern C 362 363 extern "C++" { 364 365 BSSL_NAMESPACE_BEGIN 366 367 BORINGSSL_MAKE_DELETER(DSA, DSA_free) 368 BORINGSSL_MAKE_UP_REF(DSA, DSA_up_ref) 369 BORINGSSL_MAKE_DELETER(DSA_SIG, DSA_SIG_free) 370 371 BSSL_NAMESPACE_END 372 373 } // extern C++ 374 375 #endif 376 377 #define DSA_R_BAD_Q_VALUE 100 378 #define DSA_R_MISSING_PARAMETERS 101 379 #define DSA_R_MODULUS_TOO_LARGE 102 380 #define DSA_R_NEED_NEW_SETUP_VALUES 103 381 #define DSA_R_BAD_VERSION 104 382 #define DSA_R_DECODE_ERROR 105 383 #define DSA_R_ENCODE_ERROR 106 384 #define DSA_R_INVALID_PARAMETERS 107 385 #define DSA_R_TOO_MANY_ITERATIONS 108 386 387 #endif // OPENSSL_HEADER_DSA_H 388