git.samba.org - gd/nettle/blob - rsa.h

   1 /* rsa.h
   2
   3    The RSA publickey algorithm.
   4
   5    Copyright (C) 2001, 2002 Niels Möller
   6
   7    This file is part of GNU Nettle.
   8
   9    GNU Nettle is free software: you can redistribute it and/or
  10    modify it under the terms of either:
  11
  12      * the GNU Lesser General Public License as published by the Free
  13        Software Foundation; either version 3 of the License, or (at your
  14        option) any later version.
  15
  16    or
  17
  18      * the GNU General Public License as published by the Free
  19        Software Foundation; either version 2 of the License, or (at your
  20        option) any later version.
  21
  22    or both in parallel, as here.
  23
  24    GNU Nettle is distributed in the hope that it will be useful,
  25    but WITHOUT ANY WARRANTY; without even the implied warranty of
  26    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  27    General Public License for more details.
  28
  29    You should have received copies of the GNU General Public License and
  30    the GNU Lesser General Public License along with this program.  If
  31    not, see http://www.gnu.org/licenses/.
  32 */
  33
  34 #ifndef NETTLE_RSA_H_INCLUDED
  35 #define NETTLE_RSA_H_INCLUDED
  36
  37 #include "nettle-types.h"
  38 #include "bignum.h"
  39
  40 #include "md5.h"
  41 #include "sha1.h"
  42 #include "sha2.h"
  43
  44 #ifdef __cplusplus
  45 extern "C" {
  46 #endif
  47
  48 /* Name mangling */
  49 #define rsa_public_key_init nettle_rsa_public_key_init
  50 #define rsa_public_key_clear nettle_rsa_public_key_clear
  51 #define rsa_public_key_prepare nettle_rsa_public_key_prepare
  52 #define rsa_private_key_init nettle_rsa_private_key_init
  53 #define rsa_private_key_clear nettle_rsa_private_key_clear
  54 #define rsa_private_key_prepare nettle_rsa_private_key_prepare
  55 #define rsa_pkcs1_verify nettle_rsa_pkcs1_verify
  56 #define rsa_pkcs1_sign nettle_rsa_pkcs1_sign
  57 #define rsa_pkcs1_sign_tr nettle_rsa_pkcs1_sign_tr
  58 #define rsa_md5_sign nettle_rsa_md5_sign
  59 #define rsa_md5_sign_tr nettle_rsa_md5_sign_tr
  60 #define rsa_md5_verify nettle_rsa_md5_verify
  61 #define rsa_sha1_sign nettle_rsa_sha1_sign
  62 #define rsa_sha1_sign_tr nettle_rsa_sha1_sign_tr
  63 #define rsa_sha1_verify nettle_rsa_sha1_verify
  64 #define rsa_sha256_sign nettle_rsa_sha256_sign
  65 #define rsa_sha256_sign_tr nettle_rsa_sha256_sign_tr
  66 #define rsa_sha256_verify nettle_rsa_sha256_verify
  67 #define rsa_sha512_sign nettle_rsa_sha512_sign
  68 #define rsa_sha512_sign_tr nettle_rsa_sha512_sign_tr
  69 #define rsa_sha512_verify nettle_rsa_sha512_verify
  70 #define rsa_md5_sign_digest nettle_rsa_md5_sign_digest
  71 #define rsa_md5_sign_digest_tr nettle_rsa_md5_sign_digest_tr
  72 #define rsa_md5_verify_digest nettle_rsa_md5_verify_digest
  73 #define rsa_sha1_sign_digest nettle_rsa_sha1_sign_digest
  74 #define rsa_sha1_sign_digest_tr nettle_rsa_sha1_sign_digest_tr
  75 #define rsa_sha1_verify_digest nettle_rsa_sha1_verify_digest
  76 #define rsa_sha256_sign_digest nettle_rsa_sha256_sign_digest
  77 #define rsa_sha256_sign_digest_tr nettle_rsa_sha256_sign_digest_tr
  78 #define rsa_sha256_verify_digest nettle_rsa_sha256_verify_digest
  79 #define rsa_sha512_sign_digest nettle_rsa_sha512_sign_digest
  80 #define rsa_sha512_sign_digest_tr nettle_rsa_sha512_sign_digest_tr
  81 #define rsa_sha512_verify_digest nettle_rsa_sha512_verify_digest
  82 #define rsa_pss_sha256_sign_digest_tr nettle_rsa_pss_sha256_sign_digest_tr
  83 #define rsa_pss_sha256_verify_digest nettle_rsa_pss_sha256_verify_digest
  84 #define rsa_pss_sha384_sign_digest_tr nettle_rsa_pss_sha384_sign_digest_tr
  85 #define rsa_pss_sha384_verify_digest nettle_rsa_pss_sha384_verify_digest
  86 #define rsa_pss_sha512_sign_digest_tr nettle_rsa_pss_sha512_sign_digest_tr
  87 #define rsa_pss_sha512_verify_digest nettle_rsa_pss_sha512_verify_digest
  88 #define rsa_encrypt nettle_rsa_encrypt
  89 #define rsa_decrypt nettle_rsa_decrypt
  90 #define rsa_decrypt_tr nettle_rsa_decrypt_tr
  91 #define rsa_sec_decrypt nettle_rsa_sec_decrypt
  92 #define rsa_compute_root nettle_rsa_compute_root
  93 #define rsa_compute_root_tr nettle_rsa_compute_root_tr
  94 #define rsa_generate_keypair nettle_rsa_generate_keypair
  95 #define rsa_keypair_to_sexp nettle_rsa_keypair_to_sexp
  96 #define rsa_keypair_from_sexp_alist nettle_rsa_keypair_from_sexp_alist
  97 #define rsa_keypair_from_sexp nettle_rsa_keypair_from_sexp
  98 #define rsa_public_key_from_der_iterator nettle_rsa_public_key_from_der_iterator
  99 #define rsa_private_key_from_der_iterator nettle_rsa_private_key_from_der_iterator
 100 #define rsa_keypair_from_der nettle_rsa_keypair_from_der
 101 #define rsa_keypair_to_openpgp nettle_rsa_keypair_to_openpgp
 102
 103 /* This limit is somewhat arbitrary. Technically, the smallest modulo
 104    which makes sense at all is 15 = 3*5, phi(15) = 8, size 4 bits. But
 105    for ridiculously small keys, not all odd e are possible (e.g., for
 106    5 bits, the only possible modulo is 3*7 = 21, phi(21) = 12, and e =
 107    3 don't work). The smallest size that makes sense with pkcs#1, and
 108    which allows RSA encryption of one byte messages, is 12 octets, 89
 109    bits. */
 110
 111 #define RSA_MINIMUM_N_OCTETS 12
 112 #define RSA_MINIMUM_N_BITS (8*RSA_MINIMUM_N_OCTETS - 7)
 113
 114 struct rsa_public_key
 115 {
 116   /* Size of the modulo, in octets. This is also the size of all
 117    * signatures that are created or verified with this key. */
 118   size_t size;
 119
 120   /* Modulo */
 121   mpz_t n;
 122
 123   /* Public exponent */
 124   mpz_t e;
 125 };
 126
 127 struct rsa_private_key
 128 {
 129   size_t size;
 130
 131   /* d is filled in by the key generation function; otherwise it's
 132    * completely unused. */
 133   mpz_t d;
 134
 135   /* The two factors */
 136   mpz_t p; mpz_t q;
 137
 138   /* d % (p-1), i.e. a e = 1 (mod (p-1)) */
 139   mpz_t a;
 140
 141   /* d % (q-1), i.e. b e = 1 (mod (q-1)) */
 142   mpz_t b;
 143
 144   /* modular inverse of q , i.e. c q = 1 (mod p) */
 145   mpz_t c;
 146 };
 147
 148 /* Signing a message works as follows:
 149  *
 150  * Store the private key in a rsa_private_key struct.
 151  *
 152  * Call rsa_private_key_prepare. This initializes the size attribute
 153  * to the length of a signature.
 154  *
 155  * Initialize a hashing context, by callling
 156  *   md5_init
 157  *
 158  * Hash the message by calling
 159  *   md5_update
 160  *
 161  * Create the signature by calling
 162  *   rsa_md5_sign
 163  *
 164  * The signature is represented as a mpz_t bignum. This call also
 165  * resets the hashing context.
 166  *
 167  * When done with the key and signature, don't forget to call
 168  * mpz_clear.
 169  */
 170
 171 /* Calls mpz_init to initialize bignum storage. */
 172 void
 173 rsa_public_key_init(struct rsa_public_key *key);
 174
 175 /* Calls mpz_clear to deallocate bignum storage. */
 176 void
 177 rsa_public_key_clear(struct rsa_public_key *key);
 178
 179 int
 180 rsa_public_key_prepare(struct rsa_public_key *key);
 181
 182 /* Calls mpz_init to initialize bignum storage. */
 183 void
 184 rsa_private_key_init(struct rsa_private_key *key);
 185
 186 /* Calls mpz_clear to deallocate bignum storage. */
 187 void
 188 rsa_private_key_clear(struct rsa_private_key *key);
 189
 190 int
 191 rsa_private_key_prepare(struct rsa_private_key *key);
 192
 193
 194 /* PKCS#1 style signatures */
 195 int
 196 rsa_pkcs1_sign(const struct rsa_private_key *key,
 197                size_t length, const uint8_t *digest_info,
 198                mpz_t s);
 199
 200 int
 201 rsa_pkcs1_sign_tr(const struct rsa_public_key *pub,
 202                   const struct rsa_private_key *key,
 203                   void *random_ctx, nettle_random_func *random,
 204                   size_t length, const uint8_t *digest_info,
 205                   mpz_t s);
 206 int
 207 rsa_pkcs1_verify(const struct rsa_public_key *key,
 208                  size_t length, const uint8_t *digest_info,
 209                  const mpz_t signature);
 210
 211 int
 212 rsa_md5_sign(const struct rsa_private_key *key,
 213              struct md5_ctx *hash,
 214              mpz_t signature);
 215
 216 int
 217 rsa_md5_sign_tr(const struct rsa_public_key *pub,
 218                 const struct rsa_private_key *key,
 219                 void *random_ctx, nettle_random_func *random,
 220                 struct md5_ctx *hash, mpz_t s);
 221
 222
 223 int
 224 rsa_md5_verify(const struct rsa_public_key *key,
 225                struct md5_ctx *hash,
 226                const mpz_t signature);
 227
 228 int
 229 rsa_sha1_sign(const struct rsa_private_key *key,
 230               struct sha1_ctx *hash,
 231               mpz_t signature);
 232
 233 int
 234 rsa_sha1_sign_tr(const struct rsa_public_key *pub,
 235                  const struct rsa_private_key *key,
 236                  void *random_ctx, nettle_random_func *random,
 237                  struct sha1_ctx *hash,
 238                  mpz_t s);
 239
 240 int
 241 rsa_sha1_verify(const struct rsa_public_key *key,
 242                 struct sha1_ctx *hash,
 243                 const mpz_t signature);
 244
 245 int
 246 rsa_sha256_sign(const struct rsa_private_key *key,
 247                 struct sha256_ctx *hash,
 248                 mpz_t signature);
 249
 250 int
 251 rsa_sha256_sign_tr(const struct rsa_public_key *pub,
 252                    const struct rsa_private_key *key,
 253                    void *random_ctx, nettle_random_func *random,
 254                    struct sha256_ctx *hash,
 255                    mpz_t s);
 256
 257 int
 258 rsa_sha256_verify(const struct rsa_public_key *key,
 259                   struct sha256_ctx *hash,
 260                   const mpz_t signature);
 261
 262 int
 263 rsa_sha512_sign(const struct rsa_private_key *key,
 264                 struct sha512_ctx *hash,
 265                 mpz_t signature);
 266
 267 int
 268 rsa_sha512_sign_tr(const struct rsa_public_key *pub,
 269                    const struct rsa_private_key *key,
 270                    void *random_ctx, nettle_random_func *random,
 271                    struct sha512_ctx *hash,
 272                    mpz_t s);
 273
 274 int
 275 rsa_sha512_verify(const struct rsa_public_key *key,
 276                   struct sha512_ctx *hash,
 277                   const mpz_t signature);
 278
 279 /* Variants taking the digest as argument. */
 280 int
 281 rsa_md5_sign_digest(const struct rsa_private_key *key,
 282                     const uint8_t *digest,
 283                     mpz_t s);
 284
 285 int
 286 rsa_md5_sign_digest_tr(const struct rsa_public_key *pub,
 287                        const struct rsa_private_key *key,
 288                        void *random_ctx, nettle_random_func *random,
 289                        const uint8_t *digest, mpz_t s);
 290
 291 int
 292 rsa_md5_verify_digest(const struct rsa_public_key *key,
 293                       const uint8_t *digest,
 294                       const mpz_t signature);
 295
 296 int
 297 rsa_sha1_sign_digest(const struct rsa_private_key *key,
 298                      const uint8_t *digest,
 299                      mpz_t s);
 300
 301 int
 302 rsa_sha1_sign_digest_tr(const struct rsa_public_key *pub,
 303                         const struct rsa_private_key *key,
 304                         void *random_ctx, nettle_random_func *random,
 305                         const uint8_t *digest,
 306                         mpz_t s);
 307
 308 int
 309 rsa_sha1_verify_digest(const struct rsa_public_key *key,
 310                        const uint8_t *digest,
 311                        const mpz_t signature);
 312
 313 int
 314 rsa_sha256_sign_digest(const struct rsa_private_key *key,
 315                        const uint8_t *digest,
 316                        mpz_t s);
 317
 318 int
 319 rsa_sha256_sign_digest_tr(const struct rsa_public_key *pub,
 320                           const struct rsa_private_key *key,
 321                           void *random_ctx, nettle_random_func *random,
 322                           const uint8_t *digest,
 323                           mpz_t s);
 324
 325 int
 326 rsa_sha256_verify_digest(const struct rsa_public_key *key,
 327                          const uint8_t *digest,
 328                          const mpz_t signature);
 329
 330 int
 331 rsa_sha512_sign_digest(const struct rsa_private_key *key,
 332                        const uint8_t *digest,
 333                        mpz_t s);
 334
 335 int
 336 rsa_sha512_sign_digest_tr(const struct rsa_public_key *pub,
 337                           const struct rsa_private_key *key,
 338                           void *random_ctx, nettle_random_func *random,
 339                           const uint8_t *digest,
 340                           mpz_t s);
 341
 342 int
 343 rsa_sha512_verify_digest(const struct rsa_public_key *key,
 344                          const uint8_t *digest,
 345                          const mpz_t signature);
 346
 347 /* PSS style signatures */
 348 int
 349 rsa_pss_sha256_sign_digest_tr(const struct rsa_public_key *pub,
 350                               const struct rsa_private_key *key,
 351                               void *random_ctx, nettle_random_func *random,
 352                               size_t salt_length, const uint8_t *salt,
 353                               const uint8_t *digest,
 354                               mpz_t s);
 355
 356 int
 357 rsa_pss_sha256_verify_digest(const struct rsa_public_key *key,
 358                              size_t salt_length,
 359                              const uint8_t *digest,
 360                              const mpz_t signature);
 361
 362 int
 363 rsa_pss_sha384_sign_digest_tr(const struct rsa_public_key *pub,
 364                               const struct rsa_private_key *key,
 365                               void *random_ctx, nettle_random_func *random,
 366                               size_t salt_length, const uint8_t *salt,
 367                               const uint8_t *digest,
 368                               mpz_t s);
 369
 370 int
 371 rsa_pss_sha384_verify_digest(const struct rsa_public_key *key,
 372                              size_t salt_length,
 373                              const uint8_t *digest,
 374                              const mpz_t signature);
 375
 376 int
 377 rsa_pss_sha512_sign_digest_tr(const struct rsa_public_key *pub,
 378                               const struct rsa_private_key *key,
 379                               void *random_ctx, nettle_random_func *random,
 380                               size_t salt_length, const uint8_t *salt,
 381                               const uint8_t *digest,
 382                               mpz_t s);
 383
 384 int
 385 rsa_pss_sha512_verify_digest(const struct rsa_public_key *key,
 386                              size_t salt_length,
 387                              const uint8_t *digest,
 388                              const mpz_t signature);
 389
 390
 391 /* RSA encryption, using PKCS#1 */
 392 /* These functions uses the v1.5 padding. What should the v2 (OAEP)
 393  * functions be called? */
 394
 395 /* Returns 1 on success, 0 on failure, which happens if the
 396  * message is too long for the key. */
 397 int
 398 rsa_encrypt(const struct rsa_public_key *key,
 399             /* For padding */
 400             void *random_ctx, nettle_random_func *random,
 401             size_t length, const uint8_t *cleartext,
 402             mpz_t cipher);
 403
 404 /* Message must point to a buffer of size *LENGTH. KEY->size is enough
 405  * for all valid messages. On success, *LENGTH is updated to reflect
 406  * the actual length of the message. Returns 1 on success, 0 on
 407  * failure, which happens if decryption failed or if the message
 408  * didn't fit. */
 409 int
 410 rsa_decrypt(const struct rsa_private_key *key,
 411             size_t *length, uint8_t *cleartext,
 412             const mpz_t ciphertext);
 413
 414 /* Timing-resistant version, using randomized RSA blinding. */
 415 int
 416 rsa_decrypt_tr(const struct rsa_public_key *pub,
 417                const struct rsa_private_key *key,
 418                void *random_ctx, nettle_random_func *random,
 419                size_t *length, uint8_t *message,
 420                const mpz_t gibberish);
 421
 422 /* like rsa_decrypt_tr but with additional side-channel resistance.
 423  * NOTE: the length of the final message must be known in advance. */
 424 int
 425 rsa_sec_decrypt(const struct rsa_public_key *pub,
 426                 const struct rsa_private_key *key,
 427                 void *random_ctx, nettle_random_func *random,
 428                 size_t length, uint8_t *message,
 429                 const mpz_t gibberish);
 430
 431 /* Compute x, the e:th root of m. Calling it with x == m is allowed. */
 432 void
 433 rsa_compute_root(const struct rsa_private_key *key,
 434                  mpz_t x, const mpz_t m);
 435
 436 /* Safer variant, using RSA blinding, and checking the result after
 437    CRT. */
 438 int
 439 rsa_compute_root_tr(const struct rsa_public_key *pub,
 440                     const struct rsa_private_key *key,
 441                     void *random_ctx, nettle_random_func *random,
 442                     mpz_t x, const mpz_t m);
 443
 444 /* Key generation */
 445
 446 /* Note that the key structs must be initialized first. */
 447 int
 448 rsa_generate_keypair(struct rsa_public_key *pub,
 449                      struct rsa_private_key *key,
 450
 451                      void *random_ctx, nettle_random_func *random,
 452                      void *progress_ctx, nettle_progress_func *progress,
 453
 454                      /* Desired size of modulo, in bits */
 455                      unsigned n_size,
 456
 457                      /* Desired size of public exponent, in bits. If
 458                       * zero, the passed in value pub->e is used. */
 459                      unsigned e_size);
 460
 461
 462 #define RSA_SIGN(key, algorithm, ctx, length, data, signature) ( \
 463   algorithm##_update(ctx, length, data), \
 464   rsa_##algorithm##_sign(key, ctx, signature) \
 465 )
 466
 467 #define RSA_VERIFY(key, algorithm, ctx, length, data, signature) ( \
 468   algorithm##_update(ctx, length, data), \
 469   rsa_##algorithm##_verify(key, ctx, signature) \
 470 )
 471
 472 \f
 473 /* Keys in sexp form. */
 474
 475 struct nettle_buffer;
 476
 477 /* Generates a public-key expression if PRIV is NULL .*/
 478 int
 479 rsa_keypair_to_sexp(struct nettle_buffer *buffer,
 480                     const char *algorithm_name, /* NULL means "rsa" */
 481                     const struct rsa_public_key *pub,
 482                     const struct rsa_private_key *priv);
 483
 484 struct sexp_iterator;
 485
 486 int
 487 rsa_keypair_from_sexp_alist(struct rsa_public_key *pub,
 488                             struct rsa_private_key *priv,
 489                             unsigned limit,
 490                             struct sexp_iterator *i);
 491
 492 /* If PRIV is NULL, expect a public-key expression. If PUB is NULL,
 493  * expect a private key expression and ignore the parts not needed for
 494  * the public key. */
 495 /* Keys must be initialized before calling this function, as usual. */
 496 int
 497 rsa_keypair_from_sexp(struct rsa_public_key *pub,
 498                       struct rsa_private_key *priv,
 499                       unsigned limit,
 500                       size_t length, const uint8_t *expr);
 501
 502
 503 /* Keys in PKCS#1 format. */
 504 struct asn1_der_iterator;
 505
 506 int
 507 rsa_public_key_from_der_iterator(struct rsa_public_key *pub,
 508                                  unsigned limit,
 509                                  struct asn1_der_iterator *i);
 510
 511 int
 512 rsa_private_key_from_der_iterator(struct rsa_public_key *pub,
 513                                   struct rsa_private_key *priv,
 514                                   unsigned limit,
 515                                   struct asn1_der_iterator *i);
 516
 517 /* For public keys, use PRIV == NULL */
 518 int
 519 rsa_keypair_from_der(struct rsa_public_key *pub,
 520                      struct rsa_private_key *priv,
 521                      unsigned limit,
 522                      size_t length, const uint8_t *data);
 523
 524 /* OpenPGP format. Experimental interface, subject to change. */
 525 int
 526 rsa_keypair_to_openpgp(struct nettle_buffer *buffer,
 527                        const struct rsa_public_key *pub,
 528                        const struct rsa_private_key *priv,
 529                        /* A single user id. NUL-terminated utf8. */
 530                        const char *userid);
 531
 532
 533 #ifdef __cplusplus
 534 }
 535 #endif
 536
 537 #endif /* NETTLE_RSA_H_INCLUDED */