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

   1 /* rsa.h
   2  *
   3  * The RSA publickey algorithm.
   4  */
   5
   6 /* nettle, low-level cryptographics library
   7  *
   8  * Copyright (C) 2001, 2002 Niels Möller
   9  *
  10  * The nettle library is free software; you can redistribute it and/or modify
  11  * it under the terms of the GNU Lesser General Public License as published by
  12  * the Free Software Foundation; either version 2.1 of the License, or (at your
  13  * option) any later version.
  14  *
  15  * The nettle library is distributed in the hope that it will be useful, but
  16  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  17  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
  18  * License for more details.
  19  *
  20  * You should have received a copy of the GNU Lesser General Public License
  21  * along with the nettle library; see the file COPYING.LIB.  If not, write to
  22  * the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
  23  * MA 02111-1307, USA.
  24  */
  25
  26 #ifndef NETTLE_RSA_H_INCLUDED
  27 #define NETTLE_RSA_H_INCLUDED
  28
  29 #include <inttypes.h>
  30 #include <gmp.h>
  31
  32 #include "md5.h"
  33 #include "sha.h"
  34
  35 /* For nettle_random_func */
  36 #include "nettle-meta.h"
  37
  38 /* Name mangling */
  39 #define rsa_public_key_init nettle_rsa_public_key_init
  40 #define rsa_public_key_clear nettle_rsa_public_key_clear
  41 #define rsa_public_key_prepare nettle_rsa_public_key_prepare
  42 #define rsa_private_key_init nettle_rsa_private_key_init
  43 #define rsa_private_key_clear nettle_rsa_private_key_clear
  44 #define rsa_private_key_prepare nettle_rsa_private_key_prepare
  45 #define rsa_md5_sign nettle_rsa_md5_sign
  46 #define rsa_md5_verify nettle_rsa_md5_verify
  47 #define rsa_sha1_sign nettle_rsa_sha1_sign
  48 #define rsa_sha1_verify nettle_rsa_sha1_verify
  49 #define rsa_md5_sign_digest nettle_rsa_md5_sign_digest
  50 #define rsa_md5_verify_digest nettle_rsa_md5_verify_digest
  51 #define rsa_sha1_sign_digest nettle_rsa_sha1_sign_digest
  52 #define rsa_sha1_verify_digest nettle_rsa_sha1_verify_digest
  53 #define rsa_encrypt nettle_rsa_encrypt
  54 #define rsa_decrypt nettle_rsa_decrypt
  55 #define rsa_compute_root nettle_rsa_compute_root
  56 #define rsa_generate_keypair nettle_rsa_generate_keypair
  57 #define rsa_keypair_to_sexp nettle_rsa_keypair_to_sexp
  58 #define rsa_keypair_from_sexp_alist nettle_rsa_keypair_from_sexp_alist
  59 #define rsa_keypair_from_sexp nettle_rsa_keypair_from_sexp
  60 #define rsa_keypair_to_openpgp nettle_rsa_keypair_to_openpgp
  61 #define _rsa_verify _nettle_rsa_verify
  62 #define _rsa_check_size _nettle_rsa_check_size
  63
  64 /* For PKCS#1 to make sense, the size of the modulo, in octets, must
  65  * be at least 11 + the length of the DER-encoded Digest Info.
  66  *
  67  * And a DigestInfo is 34 octets for md5, and 35 octets for sha1. 46
  68  * octets is 368 bits, and as the upper 7 bits may be zero, the
  69  * smallest useful size of n is 361 bits. */
  70
  71 #define RSA_MINIMUM_N_OCTETS 46
  72 #define RSA_MINIMUM_N_BITS 361
  73
  74 struct rsa_public_key
  75 {
  76   /* Size of the modulo, in octets. This is also the size of all
  77    * signatures that are created or verified with this key. */
  78   unsigned size;
  79
  80   /* Modulo */
  81   mpz_t n;
  82
  83   /* Public exponent */
  84   mpz_t e;
  85 };
  86
  87 struct rsa_private_key
  88 {
  89   unsigned size;
  90
  91   /* d is filled in by the key generation function; otherwise it's
  92    * completely unused. */
  93   mpz_t d;
  94
  95   /* The two factors */
  96   mpz_t p; mpz_t q;
  97
  98   /* d % (p-1), i.e. a e = 1 (mod (p-1)) */
  99   mpz_t a;
 100
 101   /* d % (q-1), i.e. b e = 1 (mod (q-1)) */
 102   mpz_t b;
 103
 104   /* modular inverse of q , i.e. c q = 1 (mod p) */
 105   mpz_t c;
 106 };
 107
 108 /* Signing a message works as follows:
 109  *
 110  * Store the private key in a rsa_private_key struct.
 111  *
 112  * Call rsa_private_key_prepare. This initializes the size attribute
 113  * to the length of a signature.
 114  *
 115  * Initialize a hashing context, by callling
 116  *   md5_init
 117  *
 118  * Hash the message by calling
 119  *   md5_update
 120  *
 121  * Create the signature by calling
 122  *   rsa_md5_sign
 123  *
 124  * The signature is represented as a mpz_t bignum. This call also
 125  * resets the hashing context.
 126  *
 127  * When done with the key and signature, don't forget to call
 128  * mpz_clear.
 129  */
 130
 131 /* Calls mpz_init to initialize bignum storage. */
 132 void
 133 rsa_public_key_init(struct rsa_public_key *key);
 134
 135 /* Calls mpz_clear to deallocate bignum storage. */
 136 void
 137 rsa_public_key_clear(struct rsa_public_key *key);
 138
 139 int
 140 rsa_public_key_prepare(struct rsa_public_key *key);
 141
 142 /* Calls mpz_init to initialize bignum storage. */
 143 void
 144 rsa_private_key_init(struct rsa_private_key *key);
 145
 146 /* Calls mpz_clear to deallocate bignum storage. */
 147 void
 148 rsa_private_key_clear(struct rsa_private_key *key);
 149
 150 int
 151 rsa_private_key_prepare(struct rsa_private_key *key);
 152
 153
 154 /* PKCS#1 style signatures */
 155 void
 156 rsa_md5_sign(const struct rsa_private_key *key,
 157              struct md5_ctx *hash,
 158              mpz_t signature);
 159
 160
 161 int
 162 rsa_md5_verify(const struct rsa_public_key *key,
 163                struct md5_ctx *hash,
 164                const mpz_t signature);
 165
 166 void
 167 rsa_sha1_sign(const struct rsa_private_key *key,
 168               struct sha1_ctx *hash,
 169               mpz_t signature);
 170
 171 int
 172 rsa_sha1_verify(const struct rsa_public_key *key,
 173                 struct sha1_ctx *hash,
 174                 const mpz_t signature);
 175
 176 /* Variants taking the digest as argument. */
 177 void
 178 rsa_md5_sign_digest(const struct rsa_private_key *key,
 179                     const uint8_t *digest,
 180                     mpz_t s);
 181
 182 int
 183 rsa_md5_verify_digest(const struct rsa_public_key *key,
 184                       const uint8_t *digest,
 185                       const mpz_t signature);
 186
 187 void
 188 rsa_sha1_sign_digest(const struct rsa_private_key *key,
 189                      const uint8_t *digest,
 190                      mpz_t s);
 191
 192 int
 193 rsa_sha1_verify_digest(const struct rsa_public_key *key,
 194                        const uint8_t *digest,
 195                        const mpz_t signature);
 196
 197
 198 /* RSA encryption, using PKCS#1 */
 199 /* FIXME: These functions uses the v1.5 padding. What should the v2
 200  * (OAEP) functions be called? */
 201
 202 /* Returns 1 on success, 0 on failure, which happens if the
 203  * message is too long for the key. */
 204 int
 205 rsa_encrypt(const struct rsa_public_key *key,
 206             /* For padding */
 207             void *random_ctx, nettle_random_func random,
 208             unsigned length, const uint8_t *cleartext,
 209             mpz_t cipher);
 210
 211 /* Message must point to a buffer of size *LENGTH. KEY->size is enough
 212  * for all valid messages. On success, *LENGTH is updated to reflect
 213  * the actual length of the message. Returns 1 on success, 0 on
 214  * failure, which happens if decryption failed or if the message
 215  * didn't fit. */
 216 int
 217 rsa_decrypt(const struct rsa_private_key *key,
 218             unsigned *length, uint8_t *cleartext,
 219             const mpz_t ciphertext);
 220
 221 /* Compute x, the e:th root of m. Calling it with x == m is allowed. */
 222 void
 223 rsa_compute_root(const struct rsa_private_key *key,
 224                  mpz_t x, const mpz_t m);
 225
 226
 227 /* Key generation */
 228
 229 /* Note that the key structs must be initialized first. */
 230 int
 231 rsa_generate_keypair(struct rsa_public_key *pub,
 232                      struct rsa_private_key *key,
 233
 234                      void *random_ctx, nettle_random_func random,
 235                      void *progress_ctx, nettle_progress_func progress,
 236
 237                      /* Desired size of modulo, in bits */
 238                      unsigned n_size,
 239
 240                      /* Desired size of public exponent, in bits. If
 241                       * zero, the passed in value pub->e is used. */
 242                      unsigned e_size);
 243
 244
 245 #define RSA_SIGN(key, algorithm, ctx, length, data, signature) ( \
 246   algorithm##_update(ctx, length, data), \
 247   rsa_##algorithm##_sign(key, ctx, signature) \
 248 )
 249
 250 #define RSA_VERIFY(key, algorithm, ctx, length, data, signature) ( \
 251   algorithm##_update(ctx, length, data), \
 252   rsa_##algorithm##_verify(key, ctx, signature) \
 253 )
 254
 255 \f
 256 /* Keys in sexp form. */
 257
 258 struct nettle_buffer;
 259
 260 /* Generates a public-key expression if PRIV is NULL .*/
 261 int
 262 rsa_keypair_to_sexp(struct nettle_buffer *buffer,
 263                     const char *algorithm_name, /* NULL means "rsa" */
 264                     const struct rsa_public_key *pub,
 265                     const struct rsa_private_key *priv);
 266
 267 struct sexp_iterator;
 268
 269 int
 270 rsa_keypair_from_sexp_alist(struct rsa_public_key *pub,
 271                             struct rsa_private_key *priv,
 272                             unsigned limit,
 273                             struct sexp_iterator *i);
 274
 275 /* If PRIV is NULL, expect a public-key expression. If PUB is NULL,
 276  * expect a private key expression and ignore the parts not needed for
 277  * the public key. */
 278 /* Keys must be initialized before calling this function, as usual. */
 279 int
 280 rsa_keypair_from_sexp(struct rsa_public_key *pub,
 281                       struct rsa_private_key *priv,
 282                       unsigned limit,
 283                       unsigned length, const uint8_t *expr);
 284
 285
 286 /* OpenPGP format. Experimental interface, subject to change. */
 287 int
 288 rsa_keypair_to_openpgp(struct nettle_buffer *buffer,
 289                        const struct rsa_public_key *pub,
 290                        const struct rsa_private_key *priv,
 291                        /* A single user id. NUL-terminated utf8. */
 292                        const char *userid);
 293
 294 /* Internal functions. */
 295 int
 296 _rsa_verify(const struct rsa_public_key *key,
 297             const mpz_t m,
 298             const mpz_t s);
 299
 300 unsigned
 301 _rsa_check_size(mpz_t n);
 302
 303 #endif /* NETTLE_RSA_H_INCLUDED */