rsa.h 6.75 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
 *
8
 * Copyright (C) 2001, 2002 Niels Mller
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 30 31
 *  
 * 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 <inttypes.h>
#include <gmp.h>

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

35 36
/* For nettle_random_func */
#include "nettle-meta.h"
Niels Möller's avatar
Niels Möller committed
37 38


39 40 41 42 43 44 45 46 47 48
/* For PKCS#1 to make sense, the size of the modulo, in octets, must
 * be at least 11 + the length of the DER-encoded Digest Info.
 *
 * And a DigestInfo is 34 octets for md5, and 35 octets for sha1. 46
 * octets is 368 bits, and as the upper 7 bits may be zero, the
 * smallest useful size of n is 361 bits. */

#define RSA_MINIMUM_N_OCTETS 46
#define RSA_MINIMUM_N_BITS 361

Niels Möller's avatar
Niels Möller committed
49 50
struct rsa_public_key
{
Niels Möller's avatar
Niels Möller committed
51 52 53 54 55
  /* 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
56
  mpz_t n;
Niels Möller's avatar
Niels Möller committed
57 58

  /* Public exponent */
Niels Möller's avatar
Niels Möller committed
59 60 61 62 63
  mpz_t e;
};

struct rsa_private_key
{
64
  unsigned size;
65 66 67 68

  /* 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
69
  
Niels Möller's avatar
Niels Möller committed
70 71 72 73 74 75 76 77 78 79 80
  /* 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
81 82
};

Niels Möller's avatar
Niels Möller committed
83 84 85 86
/* Signing a message works as follows:
 *
 * Store the private key in a rsa_private_key struct.
 *
87
 * Call rsa_prepare_private_key. This initializes the size attribute
Niels Möller's avatar
Niels Möller committed
88 89 90 91 92 93 94 95
 * to the length of a signature.
 *
 * Initialize a hashing context, by callling
 *   md5_init
 *
 * Hash the message by calling
 *   md5_update
 *
96
 * Create the signature by calling
Niels Möller's avatar
Niels Möller committed
97 98
 *   rsa_md5_sign
 *
99 100 101
 * The signature is represented as a mpz_t bignum. This call also
 * resets the hashing context.
 *
102 103
 * When done with the key and signature, don't forget to call
 * mpz_clear.
Niels Möller's avatar
Niels Möller committed
104 105
 */

106 107 108 109 110
/* FIXME: For consistency, these functions ought to be renamed to
 * rsa_public_key_init, rsa_public_key_clear, rsa_private_key_init,
 * rsa_private_key_clear. Perhaps the prepare functions should be
 * renamed too. Do this for nettle-2.0? */
 
111 112 113 114 115 116 117 118
/* Calls mpz_init to initialize bignum storage. */
void
rsa_init_public_key(struct rsa_public_key *key);

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

Niels Möller's avatar
Niels Möller committed
119
int
120
rsa_prepare_public_key(struct rsa_public_key *key);
Niels Möller's avatar
Niels Möller committed
121

122 123 124 125 126 127 128 129
/* Calls mpz_init to initialize bignum storage. */
void
rsa_init_private_key(struct rsa_private_key *key);

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

Niels Möller's avatar
Niels Möller committed
130
int
131
rsa_prepare_private_key(struct rsa_private_key *key);
Niels Möller's avatar
Niels Möller committed
132

133

Niels Möller's avatar
Niels Möller committed
134 135
/* PKCS#1 style signatures */
void
136
rsa_md5_sign(const struct rsa_private_key *key,
Niels Möller's avatar
Niels Möller committed
137
             struct md5_ctx *hash,
138
             mpz_t signature);
Niels Möller's avatar
Niels Möller committed
139 140 141


int
142
rsa_md5_verify(const struct rsa_public_key *key,
Niels Möller's avatar
Niels Möller committed
143
               struct md5_ctx *hash,
144
	       const mpz_t signature);
Niels Möller's avatar
Niels Möller committed
145 146

void
147
rsa_sha1_sign(const struct rsa_private_key *key,
Niels Möller's avatar
Niels Möller committed
148
              struct sha1_ctx *hash,
149
              mpz_t signature);
Niels Möller's avatar
Niels Möller committed
150 151

int
152
rsa_sha1_verify(const struct rsa_public_key *key,
Niels Möller's avatar
Niels Möller committed
153
                struct sha1_ctx *hash,
154
		const mpz_t signature);
Niels Möller's avatar
Niels Möller committed
155

Niels Möller's avatar
Niels Möller committed
156 157 158 159 160 161 162 163

/* RSA encryption, using PKCS#1 */
/* FIXME: These functions uses the v1.5 padding. What should the v2
 * (OAEP) functions be called? */

/* Returns 1 on success, 0 on failure, which happens if the
 * message is too long for the key. */
int
164
rsa_encrypt(const struct rsa_public_key *key,
Niels Möller's avatar
Niels Möller committed
165 166
	    /* For padding */
	    void *random_ctx, nettle_random_func random,
Niels Möller's avatar
Niels Möller committed
167 168
	    unsigned length, const uint8_t *cleartext,
	    mpz_t cipher);
Niels Möller's avatar
Niels Möller committed
169 170 171 172 173 174 175

/* 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
176
rsa_decrypt(const struct rsa_private_key *key,
Niels Möller's avatar
Niels Möller committed
177 178
	    unsigned *length, uint8_t *cleartext,
	    const mpz_t ciphertext);
Niels Möller's avatar
Niels Möller committed
179 180


Niels Möller's avatar
Niels Möller committed
181
/* Compute x, the e:th root of m. Calling it with x == m is allowed. */
Niels Möller's avatar
Niels Möller committed
182
void
183 184
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
185

186 187

/* Key generation */
188 189

/* Note that the key structs must be initialized first. */
190 191
int
rsa_generate_keypair(struct rsa_public_key *pub,
192 193 194 195 196
		     struct rsa_private_key *key,

		     void *random_ctx, nettle_random_func random,
		     void *progress_ctx, nettle_progress_func progress,

197 198 199 200 201 202 203
		     /* 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);

204

Niels Möller's avatar
Niels Möller committed
205 206 207 208 209 210 211 212 213
#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
214

215 216 217 218 219 220 221 222 223 224 225

/* 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,
		    const struct rsa_public_key *pub,
		    const struct rsa_private_key *priv);

226 227 228 229 230 231 232
struct sexp_iterator;

int
rsa_keypair_from_sexp_alist(struct rsa_public_key *pub,
			    struct rsa_private_key *priv,
			    struct sexp_iterator *i);

233 234 235 236 237 238 239 240 241 242
/* 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,
		      unsigned length, const uint8_t *expr);


243 244 245 246 247 248 249 250
/* 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. */
		       const char userid);

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