← Back to branch summary

~ubuntu-branches/ubuntu/vivid/nettle/vivid-proposed

« back to all changes in this revision

Viewing changes to nettle.texinfo

  • Committer: Package Import Robot
  • Author(s): Magnus Holmgren
  • Date: 2013-03-24 11:38:21 UTC
  • mfrom: (1.5.2)
  • mto: (8.1.7 sid)
  • mto: This revision was merged to the branch mainline in revision 14.
  • Revision ID: package-import@ubuntu.com-20130324113821-47kc1q7ojsxmuevv
Tags: 2.6-1
New upstream release.

Show diffs side-by-side

added added

removed removed

Lines of Context:
nettle.texinfo
7
7
@syncodeindex fn cp
8
8
@c %**end of header
9
9
 
10
 
@set UPDATED-FOR 2.5
 
10
@set UPDATED-FOR 2.6
11
11
@set AUTHOR Niels Möller
12
12
 
13
13
@copying
14
14
This manual is for the Nettle library (version @value{UPDATED-FOR}), a
15
15
low-level cryptographic library.
16
16
 
17
 
Originally written 2001 by @value{AUTHOR}, updated 2011.
 
17
Originally written 2001 by @value{AUTHOR}, updated 2012.
18
18
 
19
19
@quotation
20
20
This manual is placed in the public domain. You may freely copy it, in
70
70
* Cipher functions::            
71
71
* Cipher modes::                
72
72
* Keyed hash functions::        
 
73
* Key derivation functions::    
73
74
* Public-key algorithms::       
74
75
* Randomness::                  
75
76
* Ascii encoding::              
199
200
Josefsson, and heavily modified by Niels Möller. Assembly for x86_64 by
200
201
Niels Möller. Released under the LGPL.
201
202
 
 
203
@item PBKDF2
 
204
The C implementation of PBKDF2 is based on earlier work for Shishi and
 
205
GnuTLS by Simon Josefsson.  Released under the LGPL.
 
206
 
202
207
@item SERPENT
203
208
The implementation of the SERPENT cipher is based on the code in libgcrypt,
204
209
copyright owned by the Free Software Foundation. Adapted to Nettle by
211
216
Released into the public domain. Assembler for x86 by @value{AUTHOR},
212
217
released under the LGPL.
213
218
 
214
 
@item SHA224, SHA256, SHA384, and SHA512
 
219
@item SHA2
215
220
Written by @value{AUTHOR}, using Peter Gutmann's SHA1 code as a model. 
216
221
Released under the LGPL.
217
222
 
 
223
@item SHA3
 
224
Written by @value{AUTHOR}. Released under the LGPL.
 
225
 
 
226
@item GOSTHASH94
 
227
The C implementation of the GOST94 message digest is written by 
 
228
Aleksey Kravchenko and was ported from the rhash library by Nikos
 
229
Mavrogiannopoulos. It is released under the MIT license.
 
230
 
218
231
@item TWOFISH
219
232
The implementation of the TWOFISH cipher is written by Ruud de Rooij.
220
233
Released under the LGPL.
284
297
On a typical Unix system, this program can be compiled and linked with
285
298
the command line 
286
299
@example
287
 
cc sha-example.c -o sha-example -lnettle
 
300
gcc sha-example.c -o sha-example -lnettle
288
301
@end example
289
302
 
290
303
@node Linking, Reference, Example, Top
316
329
* Cipher functions::            
317
330
* Cipher modes::                
318
331
* Keyed hash functions::        
 
332
* Key derivation functions::    
319
333
* Public-key algorithms::       
320
334
* Randomness::                  
321
335
* Ascii encoding::              
325
339
 
326
340
@node Hash functions, Cipher functions, Reference, Reference
327
341
@comment  node-name,  next,  previous,  up
 
342
 
328
343
@section Hash functions
329
344
@cindex Hash function
330
345
A cryptographic @dfn{hash function} is a function that takes variable
354
369
 
355
370
The most commonly used hash functions are MD5 and SHA1. Unfortunately,
356
371
both these fail the collision-resistance requirement; cryptologists have
357
 
found ways to construct colliding inputs. The recommended hash function
358
 
for new applications is SHA256, even though it uses a structure similar
359
 
to MD5 and SHA1. Constructing better hash functions is an urgent research
360
 
problem.
361
 
 
362
 
@subsection @acronym{MD5}
 
372
found ways to construct colliding inputs. The recommended hash functions
 
373
for new applications are SHA2 (with main variants SHA256 and SHA512). At
 
374
the time of this writing (December 2012), the winner of the NIST SHA3
 
375
competition has recently been announced, and the new SHA3 (earlier known
 
376
as Keccak) and other top SHA3 candidates may also be reasonable
 
377
alternatives.
 
378
 
 
379
@menu
 
380
* Recommended hash functions::
 
381
* Legacy hash functions::
 
382
* nettle_hash abstraction::
 
383
@end menu
 
384
 
 
385
@node Recommended hash functions, Legacy hash functions,, Hash functions
 
386
@comment  node-name,  next,  previous,  up
 
387
@subsection Recommended hash functions
 
388
 
 
389
The following hash functions have no known weaknesses, and are suitable
 
390
for new applications. The SHA2 family of hash functions were specified
 
391
by @dfn{NIST}, intended as a replacement for @acronym{SHA1}.
 
392
 
 
393
@subsubsection @acronym{SHA256}
 
394
 
 
395
SHA256 is a member of the SHA2 family. It outputs hash values of 256
 
396
bits, or 32 octets. Nettle defines SHA256 in @file{<nettle/sha2.h>}.
 
397
 
 
398
@deftp {Context struct} {struct sha256_ctx}
 
399
@end deftp
 
400
 
 
401
@defvr Constant SHA256_DIGEST_SIZE
 
402
The size of a SHA256 digest, i.e. 32.
 
403
@end defvr
 
404
 
 
405
@defvr Constant SHA256_DATA_SIZE
 
406
The internal block size of SHA256. Useful for some special constructions,
 
407
in particular HMAC-SHA256.
 
408
@end defvr
 
409
 
 
410
@deftypefun void sha256_init (struct sha256_ctx *@var{ctx})
 
411
Initialize the SHA256 state.
 
412
@end deftypefun
 
413
 
 
414
@deftypefun void sha256_update (struct sha256_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{data})
 
415
Hash some more data.
 
416
@end deftypefun
 
417
 
 
418
@deftypefun void sha256_digest (struct sha256_ctx *@var{ctx}, unsigned @var{length}, uint8_t *@var{digest})
 
419
Performs final processing and extracts the message digest, writing it
 
420
to @var{digest}. @var{length} may be smaller than
 
421
@code{SHA256_DIGEST_SIZE}, in which case only the first @var{length}
 
422
octets of the digest are written.
 
423
 
 
424
This function also resets the context in the same way as
 
425
@code{sha256_init}.
 
426
@end deftypefun
 
427
 
 
428
Earlier versions of nettle defined SHA256 in the header file
 
429
@file{<nettle/sha.h>}, which is now deprecated, but kept for
 
430
compatibility.
 
431
 
 
432
@subsubsection @acronym{SHA224}
 
433
 
 
434
SHA224 is a variant of SHA256, with a different initial state, and with
 
435
the output truncated to 224 bits, or 28 octets. Nettle defines SHA224 in
 
436
@file{<nettle/sha2.h>} (and in @file{<nettle/sha.h>}, for backwards
 
437
compatibility).
 
438
 
 
439
@deftp {Context struct} {struct sha224_ctx}
 
440
@end deftp
 
441
 
 
442
@defvr Constant SHA224_DIGEST_SIZE
 
443
The size of a SHA224 digest, i.e. 28.
 
444
@end defvr
 
445
 
 
446
@defvr Constant SHA224_DATA_SIZE
 
447
The internal block size of SHA224. Useful for some special constructions,
 
448
in particular HMAC-SHA224.
 
449
@end defvr
 
450
 
 
451
@deftypefun void sha224_init (struct sha224_ctx *@var{ctx})
 
452
Initialize the SHA224 state.
 
453
@end deftypefun
 
454
 
 
455
@deftypefun void sha224_update (struct sha224_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{data})
 
456
Hash some more data.
 
457
@end deftypefun
 
458
 
 
459
@deftypefun void sha224_digest (struct sha224_ctx *@var{ctx}, unsigned @var{length}, uint8_t *@var{digest})
 
460
Performs final processing and extracts the message digest, writing it
 
461
to @var{digest}. @var{length} may be smaller than
 
462
@code{SHA224_DIGEST_SIZE}, in which case only the first @var{length}
 
463
octets of the digest are written.
 
464
 
 
465
This function also resets the context in the same way as
 
466
@code{sha224_init}.
 
467
@end deftypefun
 
468
 
 
469
@subsubsection @acronym{SHA512}
 
470
 
 
471
SHA512 is a larger sibling to SHA256, with a very similar structure but
 
472
with both the output and the internal variables of twice the size. The
 
473
internal variables are 64 bits rather than 32, making it significantly
 
474
slower on 32-bit computers. It outputs hash values of 512 bits, or 64
 
475
octets. Nettle defines SHA512 in @file{<nettle/sha2.h>} (and in
 
476
@file{<nettle/sha.h>}, for backwards compatibility).
 
477
 
 
478
@deftp {Context struct} {struct sha512_ctx}
 
479
@end deftp
 
480
 
 
481
@defvr Constant SHA512_DIGEST_SIZE
 
482
The size of a SHA512 digest, i.e. 64.
 
483
@end defvr
 
484
 
 
485
@defvr Constant SHA512_DATA_SIZE
 
486
The internal block size of SHA512. Useful for some special constructions,
 
487
in particular HMAC-SHA512.
 
488
@end defvr
 
489
 
 
490
@deftypefun void sha512_init (struct sha512_ctx *@var{ctx})
 
491
Initialize the SHA512 state.
 
492
@end deftypefun
 
493
 
 
494
@deftypefun void sha512_update (struct sha512_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{data})
 
495
Hash some more data.
 
496
@end deftypefun
 
497
 
 
498
@deftypefun void sha512_digest (struct sha512_ctx *@var{ctx}, unsigned @var{length}, uint8_t *@var{digest})
 
499
Performs final processing and extracts the message digest, writing it
 
500
to @var{digest}. @var{length} may be smaller than
 
501
@code{SHA512_DIGEST_SIZE}, in which case only the first @var{length}
 
502
octets of the digest are written.
 
503
 
 
504
This function also resets the context in the same way as
 
505
@code{sha512_init}.
 
506
@end deftypefun
 
507
 
 
508
@subsubsection @acronym{SHA384}
 
509
 
 
510
SHA384 is a variant of SHA512, with a different initial state, and with
 
511
the output truncated to 384 bits, or 48 octets. Nettle defines SHA384 in
 
512
@file{<nettle/sha2.h>} (and in @file{<nettle/sha.h>}, for backwards
 
513
compatibility).
 
514
 
 
515
@deftp {Context struct} {struct sha384_ctx}
 
516
@end deftp
 
517
 
 
518
@defvr Constant SHA384_DIGEST_SIZE
 
519
The size of a SHA384 digest, i.e. 48.
 
520
@end defvr
 
521
 
 
522
@defvr Constant SHA384_DATA_SIZE
 
523
The internal block size of SHA384. Useful for some special constructions,
 
524
in particular HMAC-SHA384.
 
525
@end defvr
 
526
 
 
527
@deftypefun void sha384_init (struct sha384_ctx *@var{ctx})
 
528
Initialize the SHA384 state.
 
529
@end deftypefun
 
530
 
 
531
@deftypefun void sha384_update (struct sha384_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{data})
 
532
Hash some more data.
 
533
@end deftypefun
 
534
 
 
535
@deftypefun void sha384_digest (struct sha384_ctx *@var{ctx}, unsigned @var{length}, uint8_t *@var{digest})
 
536
Performs final processing and extracts the message digest, writing it
 
537
to @var{digest}. @var{length} may be smaller than
 
538
@code{SHA384_DIGEST_SIZE}, in which case only the first @var{length}
 
539
octets of the digest are written.
 
540
 
 
541
This function also resets the context in the same way as
 
542
@code{sha384_init}.
 
543
@end deftypefun
 
544
 
 
545
@subsubsection @acronym{SHA3-224}
 
546
 
 
547
The SHA3 hash functions were specified by NIST in repsonse to weaknesses
 
548
in SHA1, and doubts about SHA2 hash functions which structurally are
 
549
very similar to SHA1. The standard is a result of a competition, where
 
550
the winner, also known as Keccak, was designed by Guido Bertoni, Joan
 
551
Daemen, Michaël Peeters and Gilles Van Assche. It is structurally very
 
552
different from all widely used earlier hash functions. Like SHA2, there
 
553
are several variants, with output sizes of 224, 256, 384 and 512 bits
 
554
(28, 32, 48 and 64 octets, respectively).
 
555
 
 
556
Nettle defines SHA3-224 in @file{<nettle/sha3.h>}.
 
557
 
 
558
@deftp {Context struct} {struct sha3_224_ctx}
 
559
@end deftp
 
560
 
 
561
@defvr Constant SHA3_224_DIGEST_SIZE
 
562
The size of a SHA3_224 digest, i.e., 28.
 
563
@end defvr
 
564
 
 
565
@defvr Constant SHA3_224_DATA_SIZE
 
566
The internal block size of SHA3_224.
 
567
@end defvr
 
568
 
 
569
@deftypefun void sha3_224_init (struct sha3_224_ctx *@var{ctx})
 
570
Initialize the SHA3-224 state.
 
571
@end deftypefun
 
572
 
 
573
@deftypefun void sha3_224_update (struct sha3_224_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{data})
 
574
Hash some more data.
 
575
@end deftypefun
 
576
 
 
577
@deftypefun void sha3_224_digest (struct sha3_224_ctx *@var{ctx}, unsigned @var{length}, uint8_t *@var{digest})
 
578
Performs final processing and extracts the message digest, writing it
 
579
to @var{digest}. @var{length} may be smaller than
 
580
@code{SHA3_224_DIGEST_SIZE}, in which case only the first @var{length}
 
581
octets of the digest are written.
 
582
 
 
583
This function also resets the context.
 
584
@end deftypefun
 
585
 
 
586
@subsubsection @acronym{SHA3-256}
 
587
 
 
588
This is SHA3 with 256-bit output size, and possibly the most useful
 
589
of the SHA3 hash functions.
 
590
 
 
591
Nettle defines SHA3-256 in @file{<nettle/sha3.h>}.
 
592
 
 
593
@deftp {Context struct} {struct sha3_256_ctx}
 
594
@end deftp
 
595
 
 
596
@defvr Constant SHA3_256_DIGEST_SIZE
 
597
The size of a SHA3_256 digest, i.e., 32.
 
598
@end defvr
 
599
 
 
600
@defvr Constant SHA3_256_DATA_SIZE
 
601
The internal block size of SHA3_256.
 
602
@end defvr
 
603
 
 
604
@deftypefun void sha3_256_init (struct sha3_256_ctx *@var{ctx})
 
605
Initialize the SHA3-256 state.
 
606
@end deftypefun
 
607
 
 
608
@deftypefun void sha3_256_update (struct sha3_256_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{data})
 
609
Hash some more data.
 
610
@end deftypefun
 
611
 
 
612
@deftypefun void sha3_256_digest (struct sha3_256_ctx *@var{ctx}, unsigned @var{length}, uint8_t *@var{digest})
 
613
Performs final processing and extracts the message digest, writing it
 
614
to @var{digest}. @var{length} may be smaller than
 
615
@code{SHA3_256_DIGEST_SIZE}, in which case only the first @var{length}
 
616
octets of the digest are written.
 
617
 
 
618
This function also resets the context.
 
619
@end deftypefun
 
620
 
 
621
@subsubsection @acronym{SHA3-384}
 
622
 
 
623
This is SHA3 with 384-bit output size.
 
624
 
 
625
Nettle defines SHA3-384 in @file{<nettle/sha3.h>}.
 
626
 
 
627
@deftp {Context struct} {struct sha3_384_ctx}
 
628
@end deftp
 
629
 
 
630
@defvr Constant SHA3_384_DIGEST_SIZE
 
631
The size of a SHA3_384 digest, i.e., 48.
 
632
@end defvr
 
633
 
 
634
@defvr Constant SHA3_384_DATA_SIZE
 
635
The internal block size of SHA3_384.
 
636
@end defvr
 
637
 
 
638
@deftypefun void sha3_384_init (struct sha3_384_ctx *@var{ctx})
 
639
Initialize the SHA3-384 state.
 
640
@end deftypefun
 
641
 
 
642
@deftypefun void sha3_384_update (struct sha3_384_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{data})
 
643
Hash some more data.
 
644
@end deftypefun
 
645
 
 
646
@deftypefun void sha3_384_digest (struct sha3_384_ctx *@var{ctx}, unsigned @var{length}, uint8_t *@var{digest})
 
647
Performs final processing and extracts the message digest, writing it
 
648
to @var{digest}. @var{length} may be smaller than
 
649
@code{SHA3_384_DIGEST_SIZE}, in which case only the first @var{length}
 
650
octets of the digest are written.
 
651
 
 
652
This function also resets the context.
 
653
@end deftypefun
 
654
 
 
655
@subsubsection @acronym{SHA3-512}
 
656
 
 
657
This is SHA3 with 512-bit output size.
 
658
 
 
659
Nettle defines SHA3-512 in @file{<nettle/sha3.h>}.
 
660
 
 
661
@deftp {Context struct} {struct sha3_512_ctx}
 
662
@end deftp
 
663
 
 
664
@defvr Constant SHA3_512_DIGEST_SIZE
 
665
The size of a SHA3_512 digest, i.e. 64.
 
666
@end defvr
 
667
 
 
668
@defvr Constant SHA3_512_DATA_SIZE
 
669
The internal block size of SHA3_512.
 
670
@end defvr
 
671
 
 
672
@deftypefun void sha3_512_init (struct sha3_512_ctx *@var{ctx})
 
673
Initialize the SHA3-512 state.
 
674
@end deftypefun
 
675
 
 
676
@deftypefun void sha3_512_update (struct sha3_512_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{data})
 
677
Hash some more data.
 
678
@end deftypefun
 
679
 
 
680
@deftypefun void sha3_512_digest (struct sha3_512_ctx *@var{ctx}, unsigned @var{length}, uint8_t *@var{digest})
 
681
Performs final processing and extracts the message digest, writing it
 
682
to @var{digest}. @var{length} may be smaller than
 
683
@code{SHA3_512_DIGEST_SIZE}, in which case only the first @var{length}
 
684
octets of the digest are written.
 
685
 
 
686
This function also resets the context.
 
687
@end deftypefun
 
688
 
 
689
@node Legacy hash functions, nettle_hash abstraction, Recommended hash functions, Hash functions
 
690
@comment  node-name,  next,  previous,  up
 
691
@subsection Legacy hash functions
 
692
 
 
693
The hash functions in this section all have some known weaknesses, and
 
694
should be avoided for new applications. These hash functions are mainly
 
695
useful for compatibility with old applications and protocols. Some are
 
696
still considered safe as building blocks for particular constructions,
 
697
e.g., there seems to be no known attacks against HMAC-SHA1 or even
 
698
HMAC-MD5. In some important cases, use of a ``legacy'' hash function
 
699
does not in itself make the application insecure; if a known weakness is
 
700
relevant depends on how the hash function is used, and on the threat
 
701
model.
 
702
 
 
703
@subsubsection @acronym{MD5}
363
704
 
364
705
MD5 is a message digest function constructed by Ronald Rivest, and
365
706
described in @cite{RFC 1321}. It outputs message digests of 128 bits, or
403
744
 
404
745
To start over, you can call @code{md5_init} at any time.
405
746
 
406
 
@subsection @acronym{MD2}
 
747
@subsubsection @acronym{MD2}
407
748
 
408
749
MD2 is another hash function of Ronald Rivest's, described in
409
750
@cite{RFC 1319}. It outputs message digests of 128 bits, or 16 octets.
438
779
@code{md2_init}.
439
780
@end deftypefun
440
781
 
441
 
@subsection @acronym{MD4}
 
782
@subsubsection @acronym{MD4}
442
783
 
443
784
MD4 is a predecessor of MD5, described in @cite{RFC 1320}. Like MD5, it
444
785
is constructed by Ronald Rivest. It outputs message digests of 128 bits,
475
816
@code{md4_init}.
476
817
@end deftypefun
477
818
 
478
 
@subsection @acronym{RIPEMD160}
 
819
@subsubsection @acronym{RIPEMD160}
479
820
 
480
821
RIPEMD160 is a hash function designed by Hans Dobbertin, Antoon
481
822
Bosselaers, and Bart Preneel, as a strengthened version of RIPEMD
487
828
@end deftp
488
829
 
489
830
@defvr Constant RIPEMD160_DIGEST_SIZE
490
 
The size of an RIPEMD160 digest, i.e. 20.
 
831
The size of a RIPEMD160 digest, i.e. 20.
491
832
@end defvr
492
833
 
493
834
@defvr Constant RIPEMD160_DATA_SIZE
512
853
@code{ripemd160_init}.
513
854
@end deftypefun
514
855
 
515
 
@subsection @acronym{SHA1}
516
 
 
517
 
SHA1 is a hash function specified by @dfn{NIST} (The U.S. National Institute
518
 
for Standards and Technology). It outputs hash values of 160 bits, or 20
519
 
octets. Nettle defines SHA1 in @file{<nettle/sha.h>}.
520
 
 
521
 
The functions are analogous to the MD5 ones.
 
856
@subsubsection @acronym{SHA1}
 
857
 
 
858
SHA1 is a hash function specified by @dfn{NIST} (The U.S. National
 
859
Institute for Standards and Technology). It outputs hash values of 160
 
860
bits, or 20 octets. Nettle defines SHA1 in @file{<nettle/sha1.h>} (and
 
861
in @file{<nettle/sha.h>}, for backwards compatibility).
522
862
 
523
863
@deftp {Context struct} {struct sha1_ctx}
524
864
@end deftp
525
865
 
526
866
@defvr Constant SHA1_DIGEST_SIZE
527
 
The size of an SHA1 digest, i.e. 20.
 
867
The size of a SHA1 digest, i.e. 20.
528
868
@end defvr
529
869
 
530
870
@defvr Constant SHA1_DATA_SIZE
550
890
@code{sha1_init}.
551
891
@end deftypefun
552
892
 
553
 
@subsection @acronym{SHA256}
554
 
 
555
 
SHA256 is another hash function specified by @dfn{NIST}, intended as a
556
 
replacement for @acronym{SHA1}, generating larger digests. It outputs
557
 
hash values of 256 bits, or 32 octets. Nettle defines SHA256 in
558
 
@file{<nettle/sha.h>}.
559
 
 
560
 
The functions are analogous to the MD5 ones.
561
 
 
562
 
@deftp {Context struct} {struct sha256_ctx}
563
 
@end deftp
564
 
 
565
 
@defvr Constant SHA256_DIGEST_SIZE
566
 
The size of an SHA256 digest, i.e. 32.
567
 
@end defvr
568
 
 
569
 
@defvr Constant SHA256_DATA_SIZE
570
 
The internal block size of SHA256. Useful for some special constructions,
571
 
in particular HMAC-SHA256.
572
 
@end defvr
573
 
 
574
 
@deftypefun void sha256_init (struct sha256_ctx *@var{ctx})
575
 
Initialize the SHA256 state.
576
 
@end deftypefun
577
 
 
578
 
@deftypefun void sha256_update (struct sha256_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{data})
579
 
Hash some more data.
580
 
@end deftypefun
581
 
 
582
 
@deftypefun void sha256_digest (struct sha256_ctx *@var{ctx}, unsigned @var{length}, uint8_t *@var{digest})
583
 
Performs final processing and extracts the message digest, writing it
584
 
to @var{digest}. @var{length} may be smaller than
585
 
@code{SHA256_DIGEST_SIZE}, in which case only the first @var{length}
586
 
octets of the digest are written.
587
 
 
588
 
This function also resets the context in the same way as
589
 
@code{sha256_init}.
590
 
@end deftypefun
591
 
 
592
 
@subsection @acronym{SHA224}
593
 
 
594
 
SHA224 is a variant of SHA256, with a different initial state, and with
595
 
the output truncated to 224 bits, or 28 octets. Nettle defines SHA224 in
596
 
@file{<nettle/sha.h>}.
597
 
 
598
 
The functions are analogous to the MD5 ones.
599
 
 
600
 
@deftp {Context struct} {struct sha224_ctx}
601
 
@end deftp
602
 
 
603
 
@defvr Constant SHA224_DIGEST_SIZE
604
 
The size of an SHA224 digest, i.e. 28.
605
 
@end defvr
606
 
 
607
 
@defvr Constant SHA224_DATA_SIZE
608
 
The internal block size of SHA224. Useful for some special constructions,
609
 
in particular HMAC-SHA224.
610
 
@end defvr
611
 
 
612
 
@deftypefun void sha224_init (struct sha224_ctx *@var{ctx})
613
 
Initialize the SHA224 state.
614
 
@end deftypefun
615
 
 
616
 
@deftypefun void sha224_update (struct sha224_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{data})
617
 
Hash some more data.
618
 
@end deftypefun
619
 
 
620
 
@deftypefun void sha224_digest (struct sha224_ctx *@var{ctx}, unsigned @var{length}, uint8_t *@var{digest})
621
 
Performs final processing and extracts the message digest, writing it
622
 
to @var{digest}. @var{length} may be smaller than
623
 
@code{SHA224_DIGEST_SIZE}, in which case only the first @var{length}
624
 
octets of the digest are written.
625
 
 
626
 
This function also resets the context in the same way as
627
 
@code{sha224_init}.
628
 
@end deftypefun
629
 
 
630
 
@subsection @acronym{SHA512}
631
 
 
632
 
SHA512 is a larger sibling to SHA256, with a very similar structure but
633
 
with both the output and the internal variables of twice the size. The
634
 
internal variables are 64 bits rather than 32, making it significantly
635
 
slower on 32-bit computers. It outputs hash values of 512 bits, or 64
636
 
octets. Nettle defines SHA512 in @file{<nettle/sha.h>}.
637
 
 
638
 
The functions are analogous to the MD5 ones.
639
 
 
640
 
@deftp {Context struct} {struct sha512_ctx}
641
 
@end deftp
642
 
 
643
 
@defvr Constant SHA512_DIGEST_SIZE
644
 
The size of an SHA512 digest, i.e. 64.
645
 
@end defvr
646
 
 
647
 
@defvr Constant SHA512_DATA_SIZE
648
 
The internal block size of SHA512. Useful for some special constructions,
649
 
in particular HMAC-SHA512.
650
 
@end defvr
651
 
 
652
 
@deftypefun void sha512_init (struct sha512_ctx *@var{ctx})
653
 
Initialize the SHA512 state.
654
 
@end deftypefun
655
 
 
656
 
@deftypefun void sha512_update (struct sha512_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{data})
657
 
Hash some more data.
658
 
@end deftypefun
659
 
 
660
 
@deftypefun void sha512_digest (struct sha512_ctx *@var{ctx}, unsigned @var{length}, uint8_t *@var{digest})
661
 
Performs final processing and extracts the message digest, writing it
662
 
to @var{digest}. @var{length} may be smaller than
663
 
@code{SHA512_DIGEST_SIZE}, in which case only the first @var{length}
664
 
octets of the digest are written.
665
 
 
666
 
This function also resets the context in the same way as
667
 
@code{sha512_init}.
668
 
@end deftypefun
669
 
 
670
 
@subsection @acronym{SHA384}
671
 
 
672
 
SHA384 is a variant of SHA512, with a different initial state, and with
673
 
the output truncated to 384 bits, or 48 octets. Nettle defines SHA384 in
674
 
@file{<nettle/sha.h>}.
675
 
 
676
 
The functions are analogous to the MD5 ones.
677
 
 
678
 
@deftp {Context struct} {struct sha384_ctx}
679
 
@end deftp
680
 
 
681
 
@defvr Constant SHA384_DIGEST_SIZE
682
 
The size of an SHA384 digest, i.e. 48.
683
 
@end defvr
684
 
 
685
 
@defvr Constant SHA384_DATA_SIZE
686
 
The internal block size of SHA384. Useful for some special constructions,
687
 
in particular HMAC-SHA384.
688
 
@end defvr
689
 
 
690
 
@deftypefun void sha384_init (struct sha384_ctx *@var{ctx})
691
 
Initialize the SHA384 state.
692
 
@end deftypefun
693
 
 
694
 
@deftypefun void sha384_update (struct sha384_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{data})
695
 
Hash some more data.
696
 
@end deftypefun
697
 
 
698
 
@deftypefun void sha384_digest (struct sha384_ctx *@var{ctx}, unsigned @var{length}, uint8_t *@var{digest})
699
 
Performs final processing and extracts the message digest, writing it
700
 
to @var{digest}. @var{length} may be smaller than
701
 
@code{SHA384_DIGEST_SIZE}, in which case only the first @var{length}
702
 
octets of the digest are written.
703
 
 
704
 
This function also resets the context in the same way as
705
 
@code{sha384_init}.
706
 
@end deftypefun
707
 
 
708
 
@subsection @code{struct nettle_hash}
 
893
 
 
894
@subsubsection @acronym{GOSTHASH94}
 
895
 
 
896
The GOST94 or GOST R 34.11-94 hash algorithm is a Soviet-era algorithm 
 
897
used in Russian government standards (see @cite{RFC 4357}).
 
898
It outputs message digests of 256 bits, or 32 octets.
 
899
Nettle defines GOSTHASH94 in @file{<nettle/gosthash94.h>}.
 
900
 
 
901
@deftp {Context struct} {struct gosthash94_ctx}
 
902
@end deftp
 
903
 
 
904
@defvr Constant GOSTHASH94_DIGEST_SIZE
 
905
The size of a GOSTHASH94 digest, i.e. 32.
 
906
@end defvr
 
907
 
 
908
@defvr Constant GOSTHASH94_DATA_SIZE
 
909
The internal block size of GOSTHASH94, i.e., 32.
 
910
@end defvr
 
911
 
 
912
@deftypefun void gosthash94_init (struct gosthash94_ctx *@var{ctx})
 
913
Initialize the GOSTHASH94 state.
 
914
@end deftypefun
 
915
 
 
916
@deftypefun void gosthash94_update (struct gosthash94_ctx *@var{ctx}, unsigned @var{length}, const uint8_t *@var{data})
 
917
Hash some more data.
 
918
@end deftypefun
 
919
 
 
920
@deftypefun void gosthash94_digest (struct gosthash94_ctx *@var{ctx}, unsigned @var{length}, uint8_t *@var{digest})
 
921
Performs final processing and extracts the message digest, writing it
 
922
to @var{digest}. @var{length} may be smaller than
 
923
@code{GOSTHASH94_DIGEST_SIZE}, in which case only the first @var{length}
 
924
octets of the digest are written.
 
925
 
 
926
This function also resets the context in the same way as
 
927
@code{gosthash94_init}.
 
928
@end deftypefun
 
929
 
 
930
@node nettle_hash abstraction,, Legacy hash functions, Hash functions
 
931
@comment  node-name,  next,  previous,  up
 
932
@subsection The nettle_hash abstraction
709
933
 
710
934
Nettle includes a struct including information about the supported hash
711
935
functions. It is defined in @file{<nettle/nettle-meta.h>}, and is used
729
953
@deftypevrx {Constant Struct} {struct nettle_hash} nettle_sha256
730
954
@deftypevrx {Constant Struct} {struct nettle_hash} nettle_sha384
731
955
@deftypevrx {Constant Struct} {struct nettle_hash} nettle_sha512
732
 
 
 
956
@deftypevrx {Constant Struct} {struct nettle_hash} nettle_sha3_256
 
957
@deftypevrx {Constant Struct} {struct nettle_hash} nettle_gosthash94
733
958
These are all the hash functions that Nettle implements.
734
 
 
735
 
Nettle also exports a list of all these hashes.  This list can be used
736
 
to dynamically enumerate or search the supported algorithms:
737
 
 
738
 
@deftypevrx {Constant Struct} {struct nettle_hash **} nettle_hashes
739
 
 
 
959
@end deftypevr
 
960
 
 
961
Nettle also exports a list of all these hashes.
 
962
 
 
963
@deftypevr {Constant Array} {struct nettle_hash **} nettle_hashes
 
964
This list can be used to dynamically enumerate or search the supported
 
965
algorithms. NULL-terminated.
740
966
@end deftypevr
741
967
 
742
968
@node Cipher functions, Cipher modes, Hash functions, Reference
1269
1495
functions as nice and harmless, but ciphers as dangerous munitions.
1270
1496
 
1271
1497
Salsa20 uses the same idea, but with a new specialized hash function to
1272
 
mix key, block counter, and a couple of constants (input and output are
1273
 
the same size, making it not directly applicable for use as a general
1274
 
hash function). It's also designed for speed; on x86_64, it is currently
1275
 
the fastest cipher offered by nettle. It uses a block size of 512 bits
1276
 
(64 octets) and there are two specified key sizes, 128 and 256 bits (16
1277
 
and 32 octets).
 
1498
mix key, block counter, and a couple of constants. It's also designed
 
1499
for speed; on x86_64, it is currently the fastest cipher offered by
 
1500
nettle. It uses a block size of 512 bits (64 octets) and there are two
 
1501
specified key sizes, 128 and 256 bits (16 and 32 octets).
 
1502
 
 
1503
@strong{Caution:} The hash function used in Salsa20 is @emph{not}
 
1504
directly applicable for use as a general hash function. It's @emph{not}
 
1505
collision resistant if arbitrary inputs are allowed, and furthermore,
 
1506
the input and output is of fixed size.
1278
1507
 
1279
1508
When using Salsa20 to process a message, one specifies both a key and a
1280
1509
@dfn{nonce}, the latter playing a similar rôle to the initialization
1429
1658
@deftypevrx {Constant Struct} {struct nettle_cipher} nettle_aes192
1430
1659
@deftypevrx {Constant Struct} {struct nettle_cipher} nettle_aes256
1431
1660
 
1432
 
@deftypevrx {Constant Struct} {struct nettle_cipher} nettle_arctwo40;
1433
 
@deftypevrx {Constant Struct} {struct nettle_cipher} nettle_arctwo64;
1434
 
@deftypevrx {Constant Struct} {struct nettle_cipher} nettle_arctwo128;
1435
 
@deftypevrx {Constant Struct} {struct nettle_cipher} nettle_arctwo_gutmann128;
 
1661
@deftypevrx {Constant Struct} {struct nettle_cipher} nettle_arctwo40
 
1662
@deftypevrx {Constant Struct} {struct nettle_cipher} nettle_arctwo64
 
1663
@deftypevrx {Constant Struct} {struct nettle_cipher} nettle_arctwo128
 
1664
@deftypevrx {Constant Struct} {struct nettle_cipher} nettle_arctwo_gutmann128
1436
1665
 
1437
1666
@deftypevrx {Constant Struct} {struct nettle_cipher} nettle_arcfour128
1438
1667
 
1449
1678
@deftypevrx {Constant Struct} {struct nettle_cipher} nettle_twofish128
1450
1679
@deftypevrx {Constant Struct} {struct nettle_cipher} nettle_twofish192
1451
1680
@deftypevrx {Constant Struct} {struct nettle_cipher} nettle_twofish256
1452
 
 
1453
1681
Nettle includes such structs for all the @emph{regular} ciphers, i.e.
1454
1682
ones without weak keys or other oddities.
 
1683
@end deftypevr
1455
1684
 
1456
1685
Nettle also exports a list of all these ciphers without weak keys or
1457
 
other oddities.  This list can be used to dynamically enumerate or
1458
 
search the supported algorithms:
1459
 
 
1460
 
@deftypevrx {Constant Struct} {struct nettle_cipher **} nettle_ciphers
1461
 
 
 
1686
other oddities.
 
1687
 
 
1688
@deftypevr {Constant Array} {struct nettle_cipher **} nettle_ciphers
 
1689
This list can be used to dynamically enumerate or search the supported
 
1690
algorithms. NULL-terminated.
1462
1691
@end deftypevr
1463
1692
 
1464
1693
@node Cipher modes, Keyed hash functions, Cipher functions, Reference
1472
1701
Book mode, @acronym{ECB}) leaks information. Besides @acronym{ECB},
1473
1702
Nettle provides three other modes of operation: Cipher Block Chaining
1474
1703
(@acronym{CBC}), Counter mode (@acronym{CTR}), and Galois/Counter mode
1475
 
(@acronym{gcm}). @acronym{CBC} is widely used, but there are a few
 
1704
(@acronym{GCM}). @acronym{CBC} is widely used, but there are a few
1476
1705
subtle issues of information leakage, see, e.g.,
1477
1706
@uref{http://www.kb.cert.org/vuls/id/958563, @acronym{SSH} @acronym{CBC}
1478
1707
vulnerability}. @acronym{CTR} and @acronym{GCM}
1852
2081
 
1853
2082
 
1854
2083
 
1855
 
@node Keyed hash functions, Public-key algorithms, Cipher modes, Reference
 
2084
@node Keyed hash functions, Key derivation functions, Cipher modes, Reference
1856
2085
@comment  node-name,  next,  previous,  up
1857
2086
@section Keyed Hash Functions
1858
2087
 
2102
2331
the same key.
2103
2332
@end deftypefun
2104
2333
 
2105
 
@node Public-key algorithms, Randomness, Keyed hash functions, Reference
 
2334
@node Key derivation functions, Public-key algorithms, Keyed hash functions, Reference
 
2335
@comment  node-name,  next,  previous,  up
 
2336
@section Key derivation Functions
 
2337
 
 
2338
@cindex Key Derivation Function
 
2339
@cindex Password Based Key Derivation Function
 
2340
@cindex PKCS #5
 
2341
@cindex KDF
 
2342
@cindex PBKDF
 
2343
 
 
2344
A @dfn{key derivation function} (@acronym{KDF}) is a function that from
 
2345
a given symmetric key derives other symmetric keys.  A sub-class of KDFs
 
2346
is the @dfn{password-based key derivation functions} (@acronym{PBKDFs}),
 
2347
which take as input a password or passphrase, and its purpose is
 
2348
typically to strengthen it and protect against certain pre-computation
 
2349
attacks by using salting and expensive computation.
 
2350
 
 
2351
@subsection @acronym{PBKDF2}
 
2352
The most well known PBKDF is the @code{PKCS #5 PBKDF2} described in
 
2353
@cite{RFC 2898} which uses a pseudorandom function such as
 
2354
@acronym{HMAC-SHA1}.
 
2355
 
 
2356
Nettle's @acronym{PBKDF2} functions are defined in
 
2357
@file{<nettle/pbkdf2.h>}.  There is an abstract function that operate on
 
2358
any PRF implemented via the @code{nettle_hash_update_func},
 
2359
@code{nettle_hash_digest_func} interfaces.  There is also helper macros
 
2360
and concrete functions PBKDF2-HMAC-SHA1 and PBKDF2-HMAC-SHA256.  First,
 
2361
the abstract function:
 
2362
 
 
2363
@deftypefun void pbkdf2 (void *mac_ctx, nettle_hash_update_func *update, nettle_hash_digest_func *digest, unsigned digest_size, unsigned iterations, unsigned salt_length, const uint8_t *salt, unsigned length, uint8_t *dst)
 
2364
Derive symmetric key from a password according to PKCS #5 PBKDF2.  The
 
2365
PRF is assumed to have been initialized and this function will call the
 
2366
@var{update} and @var{digest} functions passing the @var{mac_ctx}
 
2367
context parameter as an argument in order to compute digest of size
 
2368
@var{digest_size}.  Inputs are the salt @var{salt} of length
 
2369
@var{salt_length}, the iteration counter @var{iterations} (> 0), and the
 
2370
desired derived output length @var{length}.  The output buffer is
 
2371
@var{dst} which must have room for at least @var{length} octets.
 
2372
@end deftypefun
 
2373
 
 
2374
Like for CBC and HMAC, there is a macro to help use the function
 
2375
correctly.
 
2376
 
 
2377
@deffn Macro PBKDF2 (@var{ctx}, @var{update}, @var{digest}, @var{digest_size}, @var{iterations}, @var{salt_length}, @var{salt}, @var{length}, @var{dst})
 
2378
@var{ctx} is a pointer to a context struct passed to the @var{update}
 
2379
and @var{digest} functions (of the types @code{nettle_hash_update_func}
 
2380
and @code{nettle_hash_digest_func} respectively) to implement the
 
2381
underlying PRF with digest size of @var{digest_size}.  Inputs are the
 
2382
salt @var{salt} of length @var{salt_length}, the iteration counter
 
2383
@var{iterations} (> 0), and the desired derived output length
 
2384
@var{length}.  The output buffer is @var{dst} which must have room for
 
2385
at least @var{length} octets.
 
2386
@end deffn
 
2387
 
 
2388
@subsection Concrete @acronym{PBKDF2} functions
 
2389
Now we come to the specialized @acronym{PBKDF2} functions, which are
 
2390
easier to use than the general @acronym{PBKDF2} function.
 
2391
 
 
2392
@subsubsection @acronym{PBKDF2-HMAC-SHA1}
 
2393
 
 
2394
@deftypefun void pbkdf2_hmac_sha1 (unsigned @var{key_length}, const uint8_t *@var{key}, unsigned @var{iterations}, unsigned @var{salt_length}, const uint8_t *@var{salt}, unsigned @var{length}, uint8_t *@var{dst})
 
2395
PBKDF2 with HMAC-SHA1.  Derive @var{length} bytes of key into buffer
 
2396
@var{dst} using the password @var{key} of length @var{key_length} and
 
2397
salt @var{salt} of length @var{salt_length}, with iteration counter
 
2398
@var{iterations} (> 0).  The output buffer is @var{dst} which must have
 
2399
room for at least @var{length} octets.
 
2400
@end deftypefun
 
2401
 
 
2402
@subsubsection @acronym{PBKDF2-HMAC-SHA256}
 
2403
 
 
2404
@deftypefun void pbkdf2_hmac_sha256 (unsigned @var{key_length}, const uint8_t *@var{key}, unsigned @var{iterations}, unsigned @var{salt_length}, const uint8_t *@var{salt}, unsigned @var{length}, uint8_t *@var{dst})
 
2405
PBKDF2 with HMAC-SHA256.  Derive @var{length} bytes of key into buffer
 
2406
@var{dst} using the password @var{key} of length @var{key_length} and
 
2407
salt @var{salt} of length @var{salt_length}, with iteration counter
 
2408
@var{iterations} (> 0).  The output buffer is @var{dst} which must have
 
2409
room for at least @var{length} octets.
 
2410
@end deftypefun
 
2411
 
 
2412
@node Public-key algorithms, Randomness, Key derivation functions, Reference
2106
2413
@comment  node-name,  next,  previous,  up
2107
2414
@section Public-key algorithms
2108
2415
 
2398
2705
 
2399
2706
@node DSA,  , RSA, Public-key algorithms
2400
2707
@comment  node-name,  next,  previous,  up
2401
 
@subsection Nettle's @acronym{DSA} support
 
2708
@subsection @acronym{DSA}
2402
2709
 
2403
2710
The @acronym{DSA} digital signature algorithm is more complex than
2404
2711
@acronym{RSA}. It was specified during the early 1990s, and in 1994 NIST