rsa.h 11.4 KB
Newer Older
Niels Möller's avatar
Niels Möller committed
1 2 3 4 5 6 7
/* rsa.h
 *
 * The RSA publickey algorithm.
 */

/* nettle, low-level cryptographics library
 *
Niels Möller's avatar
Niels Möller committed
8
 * Copyright (C) 2001, 2002 Niels Möller
Niels Möller's avatar
Niels Möller committed
9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29
 *  
 * The nettle library is free software; you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation; either version 2.1 of the License, or (at your
 * option) any later version.
 * 
 * The nettle library is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
 * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
 * License for more details.
 * 
 * You should have received a copy of the GNU Lesser General Public License
 * along with the nettle library; see the file COPYING.LIB.  If not, write to
 * the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
 * MA 02111-1307, USA.
 */
 
#ifndef NETTLE_RSA_H_INCLUDED
#define NETTLE_RSA_H_INCLUDED

#include <gmp.h>
30
#include "nettle-types.h"
Niels Möller's avatar
Niels Möller committed
31

Niels Möller's avatar
Niels Möller committed
32 33 34
#include "md5.h"
#include "sha.h"

Niels Möller's avatar
Niels Möller committed
35 36 37 38
#ifdef __cplusplus
extern "C" {
#endif

39 40 41 42 43 44 45 46 47 48 49
/* Name mangling */
#define rsa_public_key_init nettle_rsa_public_key_init
#define rsa_public_key_clear nettle_rsa_public_key_clear
#define rsa_public_key_prepare nettle_rsa_public_key_prepare
#define rsa_private_key_init nettle_rsa_private_key_init
#define rsa_private_key_clear nettle_rsa_private_key_clear
#define rsa_private_key_prepare nettle_rsa_private_key_prepare
#define rsa_md5_sign nettle_rsa_md5_sign
#define rsa_md5_verify nettle_rsa_md5_verify
#define rsa_sha1_sign nettle_rsa_sha1_sign
#define rsa_sha1_verify nettle_rsa_sha1_verify
50 51
#define rsa_sha256_sign nettle_rsa_sha256_sign
#define rsa_sha256_verify nettle_rsa_sha256_verify
52 53
#define rsa_sha512_sign nettle_rsa_sha512_sign
#define rsa_sha512_verify nettle_rsa_sha512_verify
54 55 56 57
#define rsa_md5_sign_digest nettle_rsa_md5_sign_digest
#define rsa_md5_verify_digest nettle_rsa_md5_verify_digest
#define rsa_sha1_sign_digest nettle_rsa_sha1_sign_digest
#define rsa_sha1_verify_digest nettle_rsa_sha1_verify_digest
58 59
#define rsa_sha256_sign_digest nettle_rsa_sha256_sign_digest
#define rsa_sha256_verify_digest nettle_rsa_sha256_verify_digest
60 61
#define rsa_sha512_sign_digest nettle_rsa_sha512_sign_digest
#define rsa_sha512_verify_digest nettle_rsa_sha512_verify_digest
62 63
#define rsa_encrypt nettle_rsa_encrypt
#define rsa_decrypt nettle_rsa_decrypt
64
#define rsa_decrypt_tr nettle_rsa_decrypt_tr
65 66 67 68 69
#define rsa_compute_root nettle_rsa_compute_root
#define rsa_generate_keypair nettle_rsa_generate_keypair
#define rsa_keypair_to_sexp nettle_rsa_keypair_to_sexp
#define rsa_keypair_from_sexp_alist nettle_rsa_keypair_from_sexp_alist
#define rsa_keypair_from_sexp nettle_rsa_keypair_from_sexp
70 71 72
#define rsa_public_key_from_der_iterator nettle_rsa_public_key_from_der_iterator
#define rsa_private_key_from_der_iterator nettle_rsa_private_key_from_der_iterator
#define rsa_keypair_from_der nettle_rsa_keypair_from_der
73 74 75
#define rsa_keypair_to_openpgp nettle_rsa_keypair_to_openpgp
#define _rsa_verify _nettle_rsa_verify
#define _rsa_check_size _nettle_rsa_check_size
76 77
#define _rsa_blind _nettle_rsa_blind
#define _rsa_unblind _nettle_rsa_unblind
Niels Möller's avatar
Niels Möller committed
78

Niels Möller's avatar
Niels Möller committed
79 80 81 82 83 84 85
/* This limit is somewhat arbitrary. Technically, the smallest modulo
   which makes sense at all is 15 = 3*5, phi(15) = 8, size 4 bits. But
   for ridiculously small keys, not all odd e are possible (e.g., for
   5 bits, the only possible modulo is 3*7 = 21, phi(21) = 12, and e =
   3 don't work). The smallest size that makes sense with pkcs#1, and
   which allows RSA encryption of one byte messages, is 12 octets, 89
   bits. */
86 87

#define RSA_MINIMUM_N_OCTETS 12
88
#define RSA_MINIMUM_N_BITS (8*RSA_MINIMUM_N_OCTETS - 7)
89

Niels Möller's avatar
Niels Möller committed
90 91
struct rsa_public_key
{
Niels Möller's avatar
Niels Möller committed
92 93 94 95 96
  /* Size of the modulo, in octets. This is also the size of all
   * signatures that are created or verified with this key. */
  unsigned size;
  
  /* Modulo */
Niels Möller's avatar
Niels Möller committed
97
  mpz_t n;
Niels Möller's avatar
Niels Möller committed
98 99

  /* Public exponent */
Niels Möller's avatar
Niels Möller committed
100 101 102 103 104
  mpz_t e;
};

struct rsa_private_key
{
105
  unsigned size;
106 107 108 109

  /* d is filled in by the key generation function; otherwise it's
   * completely unused. */
  mpz_t d;
Niels Möller's avatar
Niels Möller committed
110
  
Niels Möller's avatar
Niels Möller committed
111 112 113 114 115 116 117 118 119 120 121
  /* The two factors */
  mpz_t p; mpz_t q;

  /* d % (p-1), i.e. a e = 1 (mod (p-1)) */
  mpz_t a;

  /* d % (q-1), i.e. b e = 1 (mod (q-1)) */
  mpz_t b;

  /* modular inverse of q , i.e. c q = 1 (mod p) */
  mpz_t c;
Niels Möller's avatar
Niels Möller committed
122 123
};

Niels Möller's avatar
Niels Möller committed
124 125 126 127
/* Signing a message works as follows:
 *
 * Store the private key in a rsa_private_key struct.
 *
Niels Möller's avatar
Niels Möller committed
128
 * Call rsa_private_key_prepare. This initializes the size attribute
Niels Möller's avatar
Niels Möller committed
129 130 131 132 133 134 135 136
 * to the length of a signature.
 *
 * Initialize a hashing context, by callling
 *   md5_init
 *
 * Hash the message by calling
 *   md5_update
 *
137
 * Create the signature by calling
Niels Möller's avatar
Niels Möller committed
138 139
 *   rsa_md5_sign
 *
140 141 142
 * The signature is represented as a mpz_t bignum. This call also
 * resets the hashing context.
 *
143 144
 * When done with the key and signature, don't forget to call
 * mpz_clear.
Niels Möller's avatar
Niels Möller committed
145
 */
146
 
147 148
/* Calls mpz_init to initialize bignum storage. */
void
149
rsa_public_key_init(struct rsa_public_key *key);
150 151 152

/* Calls mpz_clear to deallocate bignum storage. */
void
153
rsa_public_key_clear(struct rsa_public_key *key);
154

Niels Möller's avatar
Niels Möller committed
155
int
156
rsa_public_key_prepare(struct rsa_public_key *key);
Niels Möller's avatar
Niels Möller committed
157

158 159
/* Calls mpz_init to initialize bignum storage. */
void
160
rsa_private_key_init(struct rsa_private_key *key);
161 162 163

/* Calls mpz_clear to deallocate bignum storage. */
void
164
rsa_private_key_clear(struct rsa_private_key *key);
165

Niels Möller's avatar
Niels Möller committed
166
int
167
rsa_private_key_prepare(struct rsa_private_key *key);
Niels Möller's avatar
Niels Möller committed
168

169

Niels Möller's avatar
Niels Möller committed
170
/* PKCS#1 style signatures */
171
int
172
rsa_md5_sign(const struct rsa_private_key *key,
Niels Möller's avatar
Niels Möller committed
173
             struct md5_ctx *hash,
174
             mpz_t signature);
Niels Möller's avatar
Niels Möller committed
175 176 177


int
178
rsa_md5_verify(const struct rsa_public_key *key,
Niels Möller's avatar
Niels Möller committed
179
               struct md5_ctx *hash,
180
	       const mpz_t signature);
Niels Möller's avatar
Niels Möller committed
181

182
int
183
rsa_sha1_sign(const struct rsa_private_key *key,
Niels Möller's avatar
Niels Möller committed
184
              struct sha1_ctx *hash,
185
              mpz_t signature);
Niels Möller's avatar
Niels Möller committed
186 187

int
188
rsa_sha1_verify(const struct rsa_public_key *key,
Niels Möller's avatar
Niels Möller committed
189
                struct sha1_ctx *hash,
190
		const mpz_t signature);
Niels Möller's avatar
Niels Möller committed
191

192
int
193 194 195 196 197 198 199 200 201
rsa_sha256_sign(const struct rsa_private_key *key,
		struct sha256_ctx *hash,
		mpz_t signature);

int
rsa_sha256_verify(const struct rsa_public_key *key,
		  struct sha256_ctx *hash,
		  const mpz_t signature);

202
int
203 204 205 206 207 208 209 210 211
rsa_sha512_sign(const struct rsa_private_key *key,
		struct sha512_ctx *hash,
		mpz_t signature);

int
rsa_sha512_verify(const struct rsa_public_key *key,
		  struct sha512_ctx *hash,
		  const mpz_t signature);

212
/* Variants taking the digest as argument. */
213
int
214 215 216 217 218 219 220 221 222
rsa_md5_sign_digest(const struct rsa_private_key *key,
		    const uint8_t *digest,
		    mpz_t s);

int
rsa_md5_verify_digest(const struct rsa_public_key *key,
		      const uint8_t *digest,
		      const mpz_t signature);

223
int
224 225 226 227 228 229 230 231 232
rsa_sha1_sign_digest(const struct rsa_private_key *key,
		     const uint8_t *digest,
		     mpz_t s);

int
rsa_sha1_verify_digest(const struct rsa_public_key *key,
		       const uint8_t *digest,
		       const mpz_t signature);

233
int
234 235 236 237 238 239 240 241 242
rsa_sha256_sign_digest(const struct rsa_private_key *key,
		       const uint8_t *digest,
		       mpz_t s);

int
rsa_sha256_verify_digest(const struct rsa_public_key *key,
			 const uint8_t *digest,
			 const mpz_t signature);

243
int
244 245 246 247 248 249 250 251 252
rsa_sha512_sign_digest(const struct rsa_private_key *key,
		       const uint8_t *digest,
		       mpz_t s);

int
rsa_sha512_verify_digest(const struct rsa_public_key *key,
			 const uint8_t *digest,
			 const mpz_t signature);

Niels Möller's avatar
Niels Möller committed
253 254

/* RSA encryption, using PKCS#1 */
Niels Möller's avatar
Niels Möller committed
255 256
/* These functions uses the v1.5 padding. What should the v2 (OAEP)
 * functions be called? */
Niels Möller's avatar
Niels Möller committed
257 258 259 260

/* Returns 1 on success, 0 on failure, which happens if the
 * message is too long for the key. */
int
261
rsa_encrypt(const struct rsa_public_key *key,
Niels Möller's avatar
Niels Möller committed
262
	    /* For padding */
263
	    void *random_ctx, nettle_random_func *random,
Niels Möller's avatar
Niels Möller committed
264 265
	    unsigned length, const uint8_t *cleartext,
	    mpz_t cipher);
Niels Möller's avatar
Niels Möller committed
266 267 268 269 270 271 272

/* Message must point to a buffer of size *LENGTH. KEY->size is enough
 * for all valid messages. On success, *LENGTH is updated to reflect
 * the actual length of the message. Returns 1 on success, 0 on
 * failure, which happens if decryption failed or if the message
 * didn't fit. */
int
273
rsa_decrypt(const struct rsa_private_key *key,
Niels Möller's avatar
Niels Möller committed
274 275
	    unsigned *length, uint8_t *cleartext,
	    const mpz_t ciphertext);
Niels Möller's avatar
Niels Möller committed
276

277 278 279 280 281 282 283 284
/* Timing-resistant version, using randomized RSA blinding. */
int
rsa_decrypt_tr(const struct rsa_public_key *pub,
	       const struct rsa_private_key *key,
	       void *random_ctx, nettle_random_func *random,	       
	       unsigned *length, uint8_t *message,
	       const mpz_t gibberish);

Niels Möller's avatar
Niels Möller committed
285
/* Compute x, the e:th root of m. Calling it with x == m is allowed. */
Niels Möller's avatar
Niels Möller committed
286
void
287 288
rsa_compute_root(const struct rsa_private_key *key,
		 mpz_t x, const mpz_t m);
Niels Möller's avatar
Niels Möller committed
289

290 291

/* Key generation */
292 293

/* Note that the key structs must be initialized first. */
294 295
int
rsa_generate_keypair(struct rsa_public_key *pub,
296 297
		     struct rsa_private_key *key,

298 299
		     void *random_ctx, nettle_random_func *random,
		     void *progress_ctx, nettle_progress_func *progress,
300

301 302 303 304 305 306 307
		     /* Desired size of modulo, in bits */
		     unsigned n_size,
		     
		     /* Desired size of public exponent, in bits. If
		      * zero, the passed in value pub->e is used. */
		     unsigned e_size);

308

Niels Möller's avatar
Niels Möller committed
309 310 311 312 313 314 315 316 317
#define RSA_SIGN(key, algorithm, ctx, length, data, signature) ( \
  algorithm##_update(ctx, length, data), \
  rsa_##algorithm##_sign(key, ctx, signature) \
)

#define RSA_VERIFY(key, algorithm, ctx, length, data, signature) ( \
  algorithm##_update(ctx, length, data), \
  rsa_##algorithm##_verify(key, ctx, signature) \
)
Niels Möller's avatar
Niels Möller committed
318

319 320 321 322 323 324 325 326

/* Keys in sexp form. */

struct nettle_buffer;

/* Generates a public-key expression if PRIV is NULL .*/
int
rsa_keypair_to_sexp(struct nettle_buffer *buffer,
327
		    const char *algorithm_name, /* NULL means "rsa" */
328 329 330
		    const struct rsa_public_key *pub,
		    const struct rsa_private_key *priv);

331 332 333 334 335
struct sexp_iterator;

int
rsa_keypair_from_sexp_alist(struct rsa_public_key *pub,
			    struct rsa_private_key *priv,
336
			    unsigned limit,
337 338
			    struct sexp_iterator *i);

339 340 341 342 343 344 345
/* If PRIV is NULL, expect a public-key expression. If PUB is NULL,
 * expect a private key expression and ignore the parts not needed for
 * the public key. */
/* Keys must be initialized before calling this function, as usual. */
int
rsa_keypair_from_sexp(struct rsa_public_key *pub,
		      struct rsa_private_key *priv,
346
		      unsigned limit,
347 348 349
		      unsigned length, const uint8_t *expr);


350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370
/* Keys in PKCS#1 format. */
struct asn1_der_iterator;

int
rsa_public_key_from_der_iterator(struct rsa_public_key *pub,
				 unsigned limit,
				 struct asn1_der_iterator *i);

int
rsa_private_key_from_der_iterator(struct rsa_public_key *pub,
				  struct rsa_private_key *priv,
				  unsigned limit,
				  struct asn1_der_iterator *i);

/* For public keys, use PRIV == NULL */ 
int
rsa_keypair_from_der(struct rsa_public_key *pub,
		     struct rsa_private_key *priv,
		     unsigned limit, 
		     unsigned length, const uint8_t *data);

371 372 373 374 375 376
/* OpenPGP format. Experimental interface, subject to change. */
int
rsa_keypair_to_openpgp(struct nettle_buffer *buffer,
		       const struct rsa_public_key *pub,
		       const struct rsa_private_key *priv,
		       /* A single user id. NUL-terminated utf8. */
377
		       const char *userid);
378

379 380 381 382 383 384 385 386 387
/* Internal functions. */
int
_rsa_verify(const struct rsa_public_key *key,
	    const mpz_t m,
	    const mpz_t s);

unsigned
_rsa_check_size(mpz_t n);

388 389 390 391 392 393 394
void
_rsa_blind (const struct rsa_public_key *pub,
	    void *random_ctx, nettle_random_func random,
	    mpz_t c, mpz_t ri);
void
_rsa_unblind (const struct rsa_public_key *pub, mpz_t c, const mpz_t ri);

Niels Möller's avatar
Niels Möller committed
395 396 397 398
#ifdef __cplusplus
}
#endif

Niels Möller's avatar
Niels Möller committed
399
#endif /* NETTLE_RSA_H_INCLUDED */