nettle  3.7.3
About: Nettle is a low-level cryptographic library.
  Fossies Dox: nettle-3.7.3.tar.gz  ("unofficial" and yet experimental doxygen-generated source code documentation)  

rsa.h
Go to the documentation of this file.
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 
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 */
122 
123  /* Public exponent */
125 };
126 
128 {
129  size_t size;
130 
131  /* d is filled in by the key generation function; otherwise it's
132  * completely unused. */
134 
135  /* The two factors */
137 
138  /* d % (p-1), i.e. a e = 1 (mod (p-1)) */
140 
141  /* d % (q-1), i.e. b e = 1 (mod (q-1)) */
143 
144  /* modular inverse of q , i.e. c q = 1 (mod p) */
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
174 
175 /* Calls mpz_clear to deallocate bignum storage. */
176 void
178 
179 int
181 
182 /* Calls mpz_init to initialize bignum storage. */
183 void
185 
186 /* Calls mpz_clear to deallocate bignum storage. */
187 void
189 
190 int
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
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
358  size_t salt_length,
359  const uint8_t *digest,
360  const mpz_t signature);
361 
362 int
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
372  size_t salt_length,
373  const uint8_t *digest,
374  const mpz_t signature);
375 
376 int
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
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  It is required that 0 <= m < n. */
433 void
434 rsa_compute_root(const struct rsa_private_key *key,
435  mpz_t x, const mpz_t m);
436 
437 /* Safer variant, using RSA blinding, and checking the result after
438  CRT. It is required that 0 <= m < n. */
439 int
440 rsa_compute_root_tr(const struct rsa_public_key *pub,
441  const struct rsa_private_key *key,
442  void *random_ctx, nettle_random_func *random,
443  mpz_t x, const mpz_t m);
444 
445 /* Key generation */
446 
447 /* Note that the key structs must be initialized first. */
448 int
450  struct rsa_private_key *key,
451 
452  void *random_ctx, nettle_random_func *random,
453  void *progress_ctx, nettle_progress_func *progress,
454 
455  /* Desired size of modulo, in bits */
456  unsigned n_size,
457 
458  /* Desired size of public exponent, in bits. If
459  * zero, the passed in value pub->e is used. */
460  unsigned e_size);
461 
462 
463 #define RSA_SIGN(key, algorithm, ctx, length, data, signature) ( \
464  algorithm##_update(ctx, length, data), \
465  rsa_##algorithm##_sign(key, ctx, signature) \
466 )
467 
468 #define RSA_VERIFY(key, algorithm, ctx, length, data, signature) ( \
469  algorithm##_update(ctx, length, data), \
470  rsa_##algorithm##_verify(key, ctx, signature) \
471 )
472 
473 ␌
474 /* Keys in sexp form. */
475 
476 struct nettle_buffer;
477 
478 /* Generates a public-key expression if PRIV is NULL .*/
479 int
480 rsa_keypair_to_sexp(struct nettle_buffer *buffer,
481  const char *algorithm_name, /* NULL means "rsa" */
482  const struct rsa_public_key *pub,
483  const struct rsa_private_key *priv);
484 
485 struct sexp_iterator;
486 
487 int
489  struct rsa_private_key *priv,
490  unsigned limit,
491  struct sexp_iterator *i);
492 
493 /* If PRIV is NULL, expect a public-key expression. If PUB is NULL,
494  * expect a private key expression and ignore the parts not needed for
495  * the public key. */
496 /* Keys must be initialized before calling this function, as usual. */
497 int
499  struct rsa_private_key *priv,
500  unsigned limit,
501  size_t length, const uint8_t *expr);
502 
503 
504 /* Keys in PKCS#1 format. */
505 struct asn1_der_iterator;
506 
507 int
509  unsigned limit,
510  struct asn1_der_iterator *i);
511 
512 int
514  struct rsa_private_key *priv,
515  unsigned limit,
516  struct asn1_der_iterator *i);
517 
518 /* For public keys, use PRIV == NULL */
519 int
521  struct rsa_private_key *priv,
522  unsigned limit,
523  size_t length, const uint8_t *data);
524 
525 /* OpenPGP format. Experimental interface, subject to change. */
526 int
528  const struct rsa_public_key *pub,
529  const struct rsa_private_key *priv,
530  /* A single user id. NUL-terminated utf8. */
531  const char *userid);
532 
533 
534 #ifdef __cplusplus
535 }
536 #endif
537 
538 #endif /* NETTLE_RSA_H_INCLUDED */
#define x
#define i
#define hash
__mpz_struct mpz_t[1]
Definition: mini-gmp.h:77
void nettle_random_func(void *ctx, size_t length, uint8_t *dst)
Definition: nettle-types.h:75
void nettle_progress_func(void *ctx, int c)
Definition: nettle-types.h:79
#define rsa_sha1_sign_digest
Definition: rsa.h:73
#define rsa_pkcs1_sign
Definition: rsa.h:56
#define rsa_private_key_clear
Definition: rsa.h:53
#define rsa_sha512_verify
Definition: rsa.h:69
#define rsa_keypair_to_openpgp
Definition: rsa.h:101
#define rsa_sha256_verify
Definition: rsa.h:66
#define rsa_pss_sha512_verify_digest
Definition: rsa.h:87
#define rsa_md5_sign_digest
Definition: rsa.h:70
#define rsa_sha256_sign_digest_tr
Definition: rsa.h:77
#define rsa_sha512_sign_tr
Definition: rsa.h:68
#define rsa_encrypt
Definition: rsa.h:88
#define rsa_keypair_from_sexp_alist
Definition: rsa.h:96
#define rsa_sec_decrypt
Definition: rsa.h:91
#define rsa_keypair_from_sexp
Definition: rsa.h:97
#define rsa_sha512_sign_digest
Definition: rsa.h:79
#define rsa_sha512_sign
Definition: rsa.h:67
#define rsa_private_key_init
Definition: rsa.h:52
#define rsa_pss_sha384_sign_digest_tr
Definition: rsa.h:84
#define rsa_pkcs1_verify
Definition: rsa.h:55
#define rsa_private_key_prepare
Definition: rsa.h:54
#define rsa_pkcs1_sign_tr
Definition: rsa.h:57
#define rsa_sha256_sign_digest
Definition: rsa.h:76
#define rsa_sha512_sign_digest_tr
Definition: rsa.h:80
#define rsa_compute_root
Definition: rsa.h:92
#define rsa_sha256_sign_tr
Definition: rsa.h:65
#define rsa_md5_verify_digest
Definition: rsa.h:72
#define rsa_md5_sign
Definition: rsa.h:58
#define rsa_md5_sign_digest_tr
Definition: rsa.h:71
#define rsa_private_key_from_der_iterator
Definition: rsa.h:99
#define rsa_pss_sha256_sign_digest_tr
Definition: rsa.h:82
#define rsa_sha1_sign
Definition: rsa.h:61
#define rsa_sha512_verify_digest
Definition: rsa.h:81
#define rsa_sha1_sign_tr
Definition: rsa.h:62
#define rsa_pss_sha512_sign_digest_tr
Definition: rsa.h:86
#define rsa_sha1_verify_digest
Definition: rsa.h:75
#define rsa_sha1_verify
Definition: rsa.h:63
#define rsa_decrypt_tr
Definition: rsa.h:90
#define rsa_decrypt
Definition: rsa.h:89
#define rsa_md5_sign_tr
Definition: rsa.h:59
#define rsa_pss_sha256_verify_digest
Definition: rsa.h:83
#define rsa_generate_keypair
Definition: rsa.h:94
#define rsa_pss_sha384_verify_digest
Definition: rsa.h:85
#define rsa_keypair_from_der
Definition: rsa.h:100
#define rsa_md5_verify
Definition: rsa.h:60
#define rsa_sha256_verify_digest
Definition: rsa.h:78
#define rsa_sha256_sign
Definition: rsa.h:64
#define rsa_public_key_prepare
Definition: rsa.h:51
#define rsa_public_key_clear
Definition: rsa.h:50
#define rsa_sha1_sign_digest_tr
Definition: rsa.h:74
#define rsa_keypair_to_sexp
Definition: rsa.h:95
#define rsa_public_key_from_der_iterator
Definition: rsa.h:98
#define rsa_compute_root_tr
Definition: rsa.h:93
#define rsa_public_key_init
Definition: rsa.h:49
size_t length
Definition: asn1.h:113
const uint8_t * data
Definition: asn1.h:114
const uint8_t * buffer
Definition: asn1.h:105
Definition: md5.h:57
mpz_t p
Definition: rsa.h:136
mpz_t d
Definition: rsa.h:133
mpz_t c
Definition: rsa.h:145
size_t size
Definition: rsa.h:129
mpz_t a
Definition: rsa.h:139
mpz_t q
Definition: rsa.h:136
mpz_t b
Definition: rsa.h:142
size_t size
Definition: rsa.h:118
mpz_t e
Definition: rsa.h:124
mpz_t n
Definition: rsa.h:121
size_t length
Definition: sexp.h:65
Definition: sha1.h:59