security/nss/lib/freebl/blapit.h

   1 /*
   2  * blapit.h - public data structures for the freebl library
   3  *
   4  * This Source Code Form is subject to the terms of the Mozilla Public
   5  * License, v. 2.0. If a copy of the MPL was not distributed with this
   6  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   7
   8 #ifndef _BLAPIT_H_
   9 #define _BLAPIT_H_
  10
  11 #include "seccomon.h"
  12 #include "prlink.h"
  13 #include "plarena.h"
  14 #include "ecl-exp.h"
  15
  16 /* RC2 operation modes */
  17 #define NSS_RC2 0
  18 #define NSS_RC2_CBC 1
  19
  20 /* RC5 operation modes */
  21 #define NSS_RC5 0
  22 #define NSS_RC5_CBC 1
  23
  24 /* DES operation modes */
  25 #define NSS_DES 0
  26 #define NSS_DES_CBC 1
  27 #define NSS_DES_EDE3 2
  28 #define NSS_DES_EDE3_CBC 3
  29
  30 #define DES_KEY_LENGTH 8 /* Bytes */
  31
  32 /* AES operation modes */
  33 #define NSS_AES 0
  34 #define NSS_AES_CBC 1
  35 #define NSS_AES_CTS 2
  36 #define NSS_AES_CTR 3
  37 #define NSS_AES_GCM 4
  38
  39 /* Camellia operation modes */
  40 #define NSS_CAMELLIA 0
  41 #define NSS_CAMELLIA_CBC 1
  42
  43 /* SEED operation modes */
  44 #define NSS_SEED 0
  45 #define NSS_SEED_CBC 1
  46
  47 #define DSA1_SUBPRIME_LEN 20                             /* Bytes */
  48 #define DSA1_SIGNATURE_LEN (DSA1_SUBPRIME_LEN * 2)       /* Bytes */
  49 #define DSA_MAX_SUBPRIME_LEN 32                          /* Bytes */
  50 #define DSA_MAX_SIGNATURE_LEN (DSA_MAX_SUBPRIME_LEN * 2) /* Bytes */
  51
  52 /*
  53  * Mark the old defines as deprecated. This will warn code that expected
  54  * DSA1 only that they need to change if the are to support DSA2.
  55  */
  56 #if defined(__GNUC__) && (__GNUC__ > 3)
  57 /* make GCC warn when we use these #defines */
  58 typedef int __BLAPI_DEPRECATED __attribute__((deprecated));
  59 #define DSA_SUBPRIME_LEN ((__BLAPI_DEPRECATED)DSA1_SUBPRIME_LEN)
  60 #define DSA_SIGNATURE_LEN ((__BLAPI_DEPRECATED)DSA1_SIGNATURE_LEN)
  61 #define DSA_Q_BITS ((__BLAPI_DEPRECATED)(DSA1_SUBPRIME_LEN * 8))
  62 #else
  63 #ifdef _WIN32
  64 /* This magic gets the windows compiler to give us a deprecation
  65  * warning */
  66 #pragma deprecated(DSA_SUBPRIME_LEN, DSA_SIGNATURE_LEN, DSA_QBITS)
  67 #endif
  68 #define DSA_SUBPRIME_LEN DSA1_SUBPRIME_LEN
  69 #define DSA_SIGNATURE_LEN DSA1_SIGNATURE_LEN
  70 #define DSA_Q_BITS (DSA1_SUBPRIME_LEN * 8)
  71 #endif
  72
  73 /* XXX We shouldn't have to hard code this limit. For
  74  * now, this is the quickest way to support ECDSA signature
  75  * processing (ECDSA signature lengths depend on curve
  76  * size). This limit is sufficient for curves upto
  77  * 576 bits.
  78  */
  79 #define MAX_ECKEY_LEN 72 /* Bytes */
  80
  81 #define EC_MAX_KEY_BITS 521 /* in bits */
  82 #define EC_MIN_KEY_BITS 256 /* in bits */
  83
  84 /* EC point compression format */
  85 #define EC_POINT_FORM_COMPRESSED_Y0 0x02
  86 #define EC_POINT_FORM_COMPRESSED_Y1 0x03
  87 #define EC_POINT_FORM_UNCOMPRESSED 0x04
  88 #define EC_POINT_FORM_HYBRID_Y0 0x06
  89 #define EC_POINT_FORM_HYBRID_Y1 0x07
  90
  91 /*
  92  * Number of bytes each hash algorithm produces
  93  */
  94 #define MD2_LENGTH 16        /* Bytes */
  95 #define MD5_LENGTH 16        /* Bytes */
  96 #define SHA1_LENGTH 20       /* Bytes */
  97 #define SHA256_LENGTH 32     /* bytes */
  98 #define SHA384_LENGTH 48     /* bytes */
  99 #define SHA512_LENGTH 64     /* bytes */
 100 #define SHA3_224_LENGTH 28   /* bytes */
 101 #define SHA3_256_LENGTH 32   /* bytes */
 102 #define SHA3_384_LENGTH 48   /* bytes */
 103 #define SHA3_512_LENGTH 64   /* bytes */
 104 #define BLAKE2B512_LENGTH 64 /* Bytes */
 105 #define HASH_LENGTH_MAX SHA512_LENGTH
 106
 107 /*
 108  * Input block size for each hash algorithm.
 109  */
 110
 111 #define MD2_BLOCK_LENGTH 64       /* bytes */
 112 #define MD5_BLOCK_LENGTH 64       /* bytes */
 113 #define SHA1_BLOCK_LENGTH 64      /* bytes */
 114 #define SHA224_BLOCK_LENGTH 64    /* bytes */
 115 #define SHA256_BLOCK_LENGTH 64    /* bytes */
 116 #define SHA384_BLOCK_LENGTH 128   /* bytes */
 117 #define SHA512_BLOCK_LENGTH 128   /* bytes */
 118 #define SHA3_224_BLOCK_LENGTH 144 /* bytes */
 119 #define SHA3_256_BLOCK_LENGTH 136 /* bytes */
 120 #define SHA3_384_BLOCK_LENGTH 104 /* bytes */
 121 #define SHA3_512_BLOCK_LENGTH 72  /* bytes */
 122 #define BLAKE2B_BLOCK_LENGTH 128  /* Bytes */
 123 #define HASH_BLOCK_LENGTH_MAX SHA3_224_BLOCK_LENGTH
 124
 125 #define AES_BLOCK_SIZE 16 /* bytes */
 126 #define AES_KEY_WRAP_BLOCK_SIZE (AES_BLOCK_SIZE / 2)
 127 #define AES_KEY_WRAP_IV_BYTES AES_KEY_WRAP_BLOCK_SIZE
 128
 129 #define AES_128_KEY_LENGTH 16 /* bytes */
 130 #define AES_192_KEY_LENGTH 24 /* bytes */
 131 #define AES_256_KEY_LENGTH 32 /* bytes */
 132
 133 #define CAMELLIA_BLOCK_SIZE 16 /* bytes */
 134
 135 #define SEED_BLOCK_SIZE 16 /* bytes */
 136 #define SEED_KEY_LENGTH 16 /* bytes */
 137
 138 #define NSS_FREEBL_DEFAULT_CHUNKSIZE 2048
 139
 140 #define BLAKE2B_KEY_SIZE 64
 141
 142 /*
 143  * These values come from the initial key size limits from the PKCS #11
 144  * module. They may be arbitrarily adjusted to any value freebl supports.
 145  */
 146 #define RSA_MIN_MODULUS_BITS 128
 147 #define RSA_MAX_MODULUS_BITS 16384
 148 #define RSA_MAX_EXPONENT_BITS 64
 149 #define DH_MIN_P_BITS 128
 150 #define DH_MAX_P_BITS 16384
 151
 152 /*
 153  * The FIPS 186-1 algorithm for generating primes P and Q allows only 9
 154  * distinct values for the length of P, and only one value for the
 155  * length of Q.
 156  * The algorithm uses a variable j to indicate which of the 9 lengths
 157  * of P is to be used.
 158  * The following table relates j to the lengths of P and Q in bits.
 159  *
 160  *  j   bits in P   bits in Q
 161  *  _   _________   _________
 162  *  0    512        160
 163  *  1    576        160
 164  *  2    640        160
 165  *  3    704        160
 166  *  4    768        160
 167  *  5    832        160
 168  *  6    896        160
 169  *  7    960        160
 170  *  8   1024        160
 171  *
 172  * The FIPS-186-1 compliant PQG generator takes j as an input parameter.
 173  *
 174  * FIPS 186-3 algorithm specifies 4 distinct P and Q sizes:
 175  *
 176  *     bits in P       bits in Q
 177  *     _________       _________
 178  *      1024           160
 179  *      2048           224
 180  *      2048           256
 181  *      3072           256
 182  *
 183  * The FIPS-186-3 complaiant PQG generator (PQG V2) takes arbitrary p and q
 184  * lengths as input and returns an error if they aren't in this list.
 185  */
 186
 187 #define DSA1_Q_BITS 160
 188 #define DSA_MAX_P_BITS 3072
 189 #define DSA_MIN_P_BITS 512
 190 #define DSA_MAX_Q_BITS 256
 191 #define DSA_MIN_Q_BITS 160
 192
 193 #if DSA_MAX_Q_BITS != DSA_MAX_SUBPRIME_LEN * 8
 194 #error "Inconsistent declaration of DSA SUBPRIME/Q parameters in blapit.h"
 195 #endif
 196
 197 /*
 198  * function takes desired number of bits in P,
 199  * returns index (0..8) or -1 if number of bits is invalid.
 200  */
 201 #define PQG_PBITS_TO_INDEX(bits) \
 202     (((bits) < 512 || (bits) > 1024 || (bits) % 64) ? -1 : (int)((bits)-512) / 64)
 203
 204 /*
 205  * function takes index (0-8)
 206  * returns number of bits in P for that index, or -1 if index is invalid.
 207  */
 208 #define PQG_INDEX_TO_PBITS(j) (((unsigned)(j) > 8) ? -1 : (512 + 64 * (j)))
 209
 210 /* When we are generating a gcm iv from a random number, we need to calculate
 211  * an acceptable iteration count to avoid birthday attacks. (randomly
 212  * generating the same IV twice).
 213  *
 214  * We use the approximation n = sqrt(2*m*p) to find an acceptable n given m
 215  * and p.
 216  * where n is the number of iterations.
 217  *       m is the number of possible random values.
 218  *       p is the probability of collision (0-1).
 219  *
 220  * We want to calculate the constant number GCM_IV_RANDOM_BIRTHDAY_BITS, which
 221  * is the number of bits we subtract off of the length of the iv (in bits) to
 222  * get a safe count value (log2).
 223  *
 224  * Since we do the calculation in bits, so we need to take the whole
 225  * equation log2:
 226  *       log2 n = (1+(log2 m)+(log2 p))/2
 227  * Since p < 1, log2 p is negative. Also note that the length of the iv in
 228  * bits is log2 m, so if we set GCMIV_RANDOM_BIRTHDAY_BITS =- log2 p - 1.
 229  * then we can calculate a safe counter value with:
 230  *        n = 2^((ivLenBits - GCMIV_RANDOM_BIRTHDAY_BITS)/2)
 231  *
 232  * If we arbitrarily set p = 10^-18 (1 chance in trillion trillion operation)
 233  * we get GCMIV_RANDOM_BIRTHDAY_BITS = -(-18)/.301 -1 = 59 (.301 = log10 2)
 234  * GCMIV_RANDOM_BIRTHDAY_BITS should be at least 59, call it a round 64. NOTE:
 235  * the variable IV size for TLS is 64 bits, which explains why it's not safe
 236  * to use a random value for the nonce in TLS. */
 237 #define GCMIV_RANDOM_BIRTHDAY_BITS 64
 238
 239 /* flag to tell BLAPI_Verify* to rerun the post and integrity tests */
 240 #define BLAPI_FIPS_RERUN_FLAG '\377'        /* 0xff, 255 invalide code for UFT8/ASCII */
 241 #define BLAPI_FIPS_RERUN_FLAG_STRING "\377" /* The above as a C string */
 242
 243 /***************************************************************************
 244 ** Opaque objects
 245 */
 246
 247 struct DESContextStr;
 248 struct RC2ContextStr;
 249 struct RC4ContextStr;
 250 struct RC5ContextStr;
 251 struct AESContextStr;
 252 struct CamelliaContextStr;
 253 struct MD2ContextStr;
 254 struct MD5ContextStr;
 255 struct SHA1ContextStr;
 256 struct SHA256ContextStr;
 257 struct SHA512ContextStr;
 258 struct SHA3ContextStr;
 259 struct SHAKEContextStr;
 260 struct AESKeyWrapContextStr;
 261 struct SEEDContextStr;
 262 struct ChaCha20ContextStr;
 263 struct ChaCha20Poly1305ContextStr;
 264 struct Blake2bContextStr;
 265
 266 typedef struct DESContextStr DESContext;
 267 typedef struct RC2ContextStr RC2Context;
 268 typedef struct RC4ContextStr RC4Context;
 269 typedef struct RC5ContextStr RC5Context;
 270 typedef struct AESContextStr AESContext;
 271 typedef struct CamelliaContextStr CamelliaContext;
 272 typedef struct MD2ContextStr MD2Context;
 273 typedef struct MD5ContextStr MD5Context;
 274 typedef struct SHA1ContextStr SHA1Context;
 275 typedef struct SHA256ContextStr SHA256Context;
 276 /* SHA224Context is really a SHA256ContextStr.  This is not a mistake. */
 277 typedef struct SHA256ContextStr SHA224Context;
 278 typedef struct SHA512ContextStr SHA512Context;
 279 /* SHA384Context is really a SHA512ContextStr.  This is not a mistake. */
 280 typedef struct SHA512ContextStr SHA384Context;
 281 /* All SHA3_*Contexts are the same.  This is not a mistake. */
 282 typedef struct SHA3ContextStr SHA3_224Context;
 283 typedef struct SHA3ContextStr SHA3_256Context;
 284 typedef struct SHA3ContextStr SHA3_384Context;
 285 typedef struct SHA3ContextStr SHA3_512Context;
 286 typedef struct SHAKEContextStr SHAKE_128Context;
 287 typedef struct SHAKEContextStr SHAKE_256Context;
 288 typedef struct AESKeyWrapContextStr AESKeyWrapContext;
 289 typedef struct SEEDContextStr SEEDContext;
 290 typedef struct ChaCha20ContextStr ChaCha20Context;
 291 typedef struct ChaCha20Poly1305ContextStr ChaCha20Poly1305Context;
 292 typedef struct Blake2bContextStr BLAKE2BContext;
 293
 294 /***************************************************************************
 295 ** RSA Public and Private Key structures
 296 */
 297
 298 /* member names from PKCS#1, section 7.1 */
 299 struct RSAPublicKeyStr {
 300     PLArenaPool *arena;
 301     SECItem modulus;
 302     SECItem publicExponent;
 303 };
 304 typedef struct RSAPublicKeyStr RSAPublicKey;
 305
 306 /* member names from PKCS#1, section 7.2 */
 307 struct RSAPrivateKeyStr {
 308     PLArenaPool *arena;
 309     SECItem version;
 310     SECItem modulus;
 311     SECItem publicExponent;
 312     SECItem privateExponent;
 313     SECItem prime1;
 314     SECItem prime2;
 315     SECItem exponent1;
 316     SECItem exponent2;
 317     SECItem coefficient;
 318 };
 319 typedef struct RSAPrivateKeyStr RSAPrivateKey;
 320
 321 /***************************************************************************
 322 ** DSA Public and Private Key and related structures
 323 */
 324
 325 struct PQGParamsStr {
 326     PLArenaPool *arena;
 327     SECItem prime;    /* p */
 328     SECItem subPrime; /* q */
 329     SECItem base;     /* g */
 330     /* XXX chrisk: this needs to be expanded to hold j and validationParms (RFC2459 7.3.2) */
 331 };
 332 typedef struct PQGParamsStr PQGParams;
 333
 334 struct PQGVerifyStr {
 335     PLArenaPool *arena; /* includes this struct, seed, & h. */
 336     unsigned int counter;
 337     SECItem seed;
 338     SECItem h;
 339 };
 340 typedef struct PQGVerifyStr PQGVerify;
 341
 342 struct DSAPublicKeyStr {
 343     PQGParams params;
 344     SECItem publicValue;
 345 };
 346 typedef struct DSAPublicKeyStr DSAPublicKey;
 347
 348 struct DSAPrivateKeyStr {
 349     PQGParams params;
 350     SECItem publicValue;
 351     SECItem privateValue;
 352 };
 353 typedef struct DSAPrivateKeyStr DSAPrivateKey;
 354
 355 /***************************************************************************
 356 ** Diffie-Hellman Public and Private Key and related structures
 357 ** Structure member names suggested by PKCS#3.
 358 */
 359
 360 struct DHParamsStr {
 361     PLArenaPool *arena;
 362     SECItem prime; /* p */
 363     SECItem base;  /* g */
 364 };
 365 typedef struct DHParamsStr DHParams;
 366
 367 struct DHPublicKeyStr {
 368     PLArenaPool *arena;
 369     SECItem prime;
 370     SECItem base;
 371     SECItem publicValue;
 372 };
 373 typedef struct DHPublicKeyStr DHPublicKey;
 374
 375 struct DHPrivateKeyStr {
 376     PLArenaPool *arena;
 377     SECItem prime;
 378     SECItem base;
 379     SECItem publicValue;
 380     SECItem privateValue;
 381 };
 382 typedef struct DHPrivateKeyStr DHPrivateKey;
 383
 384 /***************************************************************************
 385 ** Data structures used for elliptic curve parameters and
 386 ** public and private keys.
 387 */
 388
 389 /*
 390 ** The ECParams data structures can encode elliptic curve
 391 ** parameters for both GFp and GF2m curves.
 392 */
 393
 394 typedef enum { ec_params_explicit,
 395                ec_params_named
 396 } ECParamsType;
 397
 398 typedef enum { ec_field_GFp = 1,
 399                ec_field_GF2m,
 400                ec_field_plain
 401 } ECFieldType;
 402
 403 struct ECFieldIDStr {
 404     int size; /* field size in bits */
 405     ECFieldType type;
 406     union {
 407         SECItem prime; /* prime p for (GFp) */
 408         SECItem poly;  /* irreducible binary polynomial for (GF2m) */
 409     } u;
 410     int k1; /* first coefficient of pentanomial or
 411                          * the only coefficient of trinomial
 412                          */
 413     int k2; /* two remaining coefficients of pentanomial */
 414     int k3;
 415 };
 416 typedef struct ECFieldIDStr ECFieldID;
 417
 418 struct ECCurveStr {
 419     SECItem a; /* contains octet stream encoding of
 420                          * field element (X9.62 section 4.3.3)
 421              */
 422     SECItem b;
 423     SECItem seed;
 424 };
 425 typedef struct ECCurveStr ECCurve;
 426
 427 struct ECParamsStr {
 428     PLArenaPool *arena;
 429     ECParamsType type;
 430     ECFieldID fieldID;
 431     ECCurve curve;
 432     SECItem base;
 433     SECItem order;
 434     int cofactor;
 435     SECItem DEREncoding;
 436     ECCurveName name;
 437     SECItem curveOID;
 438 };
 439 typedef struct ECParamsStr ECParams;
 440
 441 struct ECPublicKeyStr {
 442     ECParams ecParams;
 443     SECItem publicValue; /* elliptic curve point encoded as
 444                 * octet stream.
 445                 */
 446 };
 447 typedef struct ECPublicKeyStr ECPublicKey;
 448
 449 struct ECPrivateKeyStr {
 450     ECParams ecParams;
 451     SECItem publicValue;  /* encoded ec point */
 452     SECItem privateValue; /* private big integer */
 453     SECItem version;      /* As per SEC 1, Appendix C, Section C.4 */
 454 };
 455 typedef struct ECPrivateKeyStr ECPrivateKey;
 456
 457 typedef void *(*BLapiAllocateFunc)(void);
 458 typedef void (*BLapiDestroyContextFunc)(void *cx, PRBool freeit);
 459 typedef SECStatus (*BLapiInitContextFunc)(void *cx,
 460                                           const unsigned char *key,
 461                                           unsigned int keylen,
 462                                           const unsigned char *,
 463                                           int,
 464                                           unsigned int,
 465                                           unsigned int);
 466 typedef SECStatus (*BLapiEncrypt)(void *cx, unsigned char *output,
 467                                   unsigned int *outputLen,
 468                                   unsigned int maxOutputLen,
 469                                   const unsigned char *input,
 470                                   unsigned int inputLen);
 471
 472 #endif /* _BLAPIT_H_ */