Add SHA384 functions to libmd.
[dragonfly.git] / lib / libmd / sha384.3
1 .\"
2 .\" ----------------------------------------------------------------------------
3 .\" "THE BEER-WARE LICENSE" (Revision 42):
4 .\" <phk@FreeBSD.org> wrote this file.  As long as you retain this notice you
5 .\" can do whatever you want with this stuff. If we meet some day, and you think
6 .\" this stuff is worth it, you can buy me a beer in return.   Poul-Henning Kamp
7 .\" ----------------------------------------------------------------------------
8 .\"
9 .\"     From: Id: mdX.3,v 1.14 1999/02/11 20:31:49 wollman Exp
10 .\" $FreeBSD: src/lib/libmd/sha512.3,v 1.4 2005/11/17 13:00:00 ru Exp $
11 .\" $DragonFly: src/lib/libmd/sha512.3,v 1.2 2008/09/11 20:25:34 swildner Exp $
12 .\"
13 .Dd July 4, 2010
14 .Dt SHA384 3
15 .Os
16 .Sh NAME
17 .Nm SHA384_Init ,
18 .Nm SHA384_Update ,
19 .Nm SHA384_Final
20 .Nd calculate the FIPS 180-2 ``SHA-384'' message digest
21 .Sh LIBRARY
22 .Lb libmd
23 .Sh SYNOPSIS
24 .In sys/types.h
25 .In sha512.h
26 .Ft void
27 .Fn SHA384_Init "SHA384_CTX *context"
28 .Ft void
29 .Fn SHA384_Update "SHA384_CTX *context" "const u_int8_t *data" "size_t len"
30 .Ft void
31 .Fn SHA384_Final "u_int8_t digest[48]" "SHA384_CTX *context"
32 .Sh DESCRIPTION
33 The
34 .Li SHA384_
35 functions calculate a 384-bit cryptographic checksum (digest)
36 for any number of input bytes.
37 A cryptographic checksum is a one-way
38 hash function; that is, it is computationally impractical to find
39 the input corresponding to a particular output.
40 This net result is
41 a
42 .Dq fingerprint
43 of the input-data, which does not disclose the actual input.
44 .Pp
45 The
46 .Fn SHA384_Init ,
47 .Fn SHA384_Update ,
48 and
49 .Fn SHA384_Final
50 functions are the core functions.
51 Allocate an
52 .Vt SHA384_CTX ,
53 initialize it with
54 .Fn SHA384_Init ,
55 run over the data with
56 .Fn SHA384_Update ,
57 and finally extract the result using
58 .Fn SHA384_Final .
59 .Pp
60 .Sh SEE ALSO
61 .Xr md2 3 ,
62 .Xr md4 3 ,
63 .Xr md5 3 ,
64 .Xr ripemd 3 ,
65 .Xr sha 3
66 .Sh HISTORY
67 These functions appeared in
68 .Dx 2.9 .
69 .Sh AUTHORS
70 The core hash routines were implemented by Colin Percival based on
71 the published
72 .Tn FIPS 180-2
73 standard.
74 .Sh BUGS
75 No method is known to exist which finds two files having the same hash value,
76 nor to find a file with a specific hash value.
77 There is on the other hand no guarantee that such a method does not exist.