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