aboutsummaryrefslogtreecommitdiff
path: root/vendor/doc/html/crypto_hmac_sha512_final.html
blob: 3d92390b95687f9e5644b4fe4963c30d61c28f2b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8"/>
  <style>
    table.head, table.foot { width: 100%; }
    td.head-rtitle, td.foot-os { text-align: right; }
    td.head-vol { text-align: center; }
    div.Pp { margin: 1ex 0ex; }
  </style>
  <link rel="stylesheet" href="style.css" type="text/css" media="all"/>
  <title>CRYPTO_HMAC_SHA512(3MONOCYPHER)</title>
</head>
<body>
<table class="head">
  <tr>
    <td class="head-ltitle">CRYPTO_HMAC_SHA512(3MONOCYPHER)</td>
    <td class="head-vol">3MONOCYPHER</td>
    <td class="head-rtitle">CRYPTO_HMAC_SHA512(3MONOCYPHER)</td>
  </tr>
</table>
<div class="manual-text">
<h1 class="Sh" title="Sh" id="NAME"><a class="selflink" href="#NAME">NAME</a></h1>
<b class="Nm" title="Nm">crypto_hmac_sha512</b>,
  <b class="Nm" title="Nm">crypto_hmac_sha512_init</b>,
  <b class="Nm" title="Nm">crypto_hmac_sha512_update</b>,
  <b class="Nm" title="Nm">crypto_hmac_sha512_final</b> &#x2014;
  <span class="Nd" title="Nd">cryptographic hash-based message authentication
  code with SHA-512</span>
<h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="selflink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<b class="In" title="In">#include
  &lt;<a class="In" title="In">monocypher-ed25519.h</a>&gt;</b>
<div class="Pp"></div>
<var class="Ft" title="Ft">void</var>
<br/>
<b class="Fn" title="Fn">crypto_hmac_sha512</b>(<var class="Fa" title="Fa">uint8_t
  hmac[64]</var>, <var class="Fa" title="Fa">const uint8_t *key</var>,
  <var class="Fa" title="Fa">size_t key_size</var>,
  <var class="Fa" title="Fa">const uint8_t *message</var>,
  <var class="Fa" title="Fa">size_t message_size</var>);
<div class="Pp"></div>
<var class="Ft" title="Ft">void</var>
<br/>
<b class="Fn" title="Fn">crypto_hmac_sha512_init</b>(<var class="Fa" title="Fa">crypto_hmac_sha512_ctx
  *ctx</var>, <var class="Fa" title="Fa">const uint8_t *key</var>,
  <var class="Fa" title="Fa">size_t key_size</var>);
<div class="Pp"></div>
<var class="Ft" title="Ft">void</var>
<br/>
<b class="Fn" title="Fn">crypto_hmac_sha512_update</b>(<var class="Fa" title="Fa">crypto_hmac_sha512_ctx
  *ctx</var>, <var class="Fa" title="Fa">const uint8_t *message</var>,
  <var class="Fa" title="Fa">size_t message_size</var>);
<div class="Pp"></div>
<var class="Ft" title="Ft">void</var>
<br/>
<b class="Fn" title="Fn">crypto_hmac_sha512_final</b>(<var class="Fa" title="Fa">crypto_hmac_sha512_ctx
  *ctx</var>, <var class="Fa" title="Fa">uint8_t hmac[64]</var>);
<h1 class="Sh" title="Sh" id="DESCRIPTION"><a class="selflink" href="#DESCRIPTION">DESCRIPTION</a></h1>
HMAC with SHA-512 is a cryptographically secure message authentication code
  (MAC), provided to enable compatibility with other cryptographic systems. It
  is generally recommended to use
  <a class="Xr" title="Xr" href="crypto_blake2b_general.html">crypto_blake2b_general(3monocypher)</a>
  instead, as it performs faster on x86_64 CPUs.
<div class="Pp"></div>
The arguments are:
<dl class="Bl-tag">
  <dt class="It-tag">&#x00A0;</dt>
  <dd class="It-tag">&#x00A0;</dd>
  <dt class="It-tag"><var class="Fa" title="Fa">hmac</var></dt>
  <dd class="It-tag">The output MAC, which is always 64 bytes long.</dd>
  <dt class="It-tag">&#x00A0;</dt>
  <dd class="It-tag">&#x00A0;</dd>
  <dt class="It-tag"><var class="Fa" title="Fa">key</var></dt>
  <dd class="It-tag">Some secret key. One cannot predict the final hash without
      it. Users may want to wipe the key with
      <a class="Xr" title="Xr" href="crypto_wipe.html">crypto_wipe(3monocypher)</a>
      once they are done with it.</dd>
  <dt class="It-tag">&#x00A0;</dt>
  <dd class="It-tag">&#x00A0;</dd>
  <dt class="It-tag"><var class="Fa" title="Fa">key_size</var></dt>
  <dd class="It-tag">Length of <var class="Fa" title="Fa">key</var>, in bytes.
      32 is a good default. Keys longer than 128 bytes will be reduced to 64
      bytes by hashing the key with SHA-512.</dd>
  <dt class="It-tag">&#x00A0;</dt>
  <dd class="It-tag">&#x00A0;</dd>
  <dt class="It-tag"><var class="Fa" title="Fa">message</var></dt>
  <dd class="It-tag">The message to compute the HMAC for. May overlap with
      <var class="Fa" title="Fa">hmac</var>. May be
      <code class="Dv" title="Dv">NULL</code> if
      <var class="Fa" title="Fa">message_size</var> is 0.</dd>
  <dt class="It-tag">&#x00A0;</dt>
  <dd class="It-tag">&#x00A0;</dd>
  <dt class="It-tag"><var class="Fa" title="Fa">message_size</var></dt>
  <dd class="It-tag">Length of <var class="Fa" title="Fa">message</var>, in
      bytes.</dd>
</dl>
<div class="Pp"></div>
An incremental interface is provided. It is useful for handling streams of data
  or large files without using too much memory. This interface uses three steps:
<ul class="Bl-bullet">
  <li class="It-bullet">initialisation with
      <b class="Fn" title="Fn">crypto_hmac_sha512_init</b>(), which sets up a
      context with the hashing parameters;</li>
  <li class="It-bullet">update with
      <b class="Fn" title="Fn">crypto_hmac_sha512_update</b>(), which hashes the
      message chunk by chunk, and keep the intermediary result in the
    context;</li>
  <li class="It-bullet">and finalisation with
      <b class="Fn" title="Fn">crypto_hmac_sha512_final</b>(), which produces
      the final hash. The
      <var class="Ft" title="Ft">crypto_hmac_sha512_ctx</var> is automatically
      wiped upon finalisation.</li>
</ul>
<div class="Pp"></div>
<b class="Fn" title="Fn">crypto_hmac_sha512</b>() is a convenience function that
  performs <b class="Fn" title="Fn">crypto_hmac_sha512_init</b>(),
  <b class="Fn" title="Fn">crypto_hmac_sha512_update</b>(), and
  <b class="Fn" title="Fn">crypto_hmac_sha512_final</b>().
<div class="Pp"></div>
MACs may be truncated safely down to at most 16 bytes; the
  <a class="Xr" title="Xr" href="crypto_verify64.html">crypto_verify64(3monocypher)</a>,
  <a class="Xr" title="Xr" href="crypto_verify32.html">crypto_verify32(3monocypher)</a>,
  and
  <a class="Xr" title="Xr" href="crypto_verify16.html">crypto_verify16(3monocypher)</a>
  functions can be used to to compare (possibly truncated) MACs.
<h1 class="Sh" title="Sh" id="RETURN_VALUES"><a class="selflink" href="#RETURN_VALUES">RETURN
  VALUES</a></h1>
These functions return nothing.
<h1 class="Sh" title="Sh" id="EXAMPLES"><a class="selflink" href="#EXAMPLES">EXAMPLES</a></h1>
The following examples assume the existence of
  <b class="Fn" title="Fn">arc4random_buf</b>(), which fills the given buffer
  with cryptographically secure random bytes. If
  <b class="Fn" title="Fn">arc4random_buf</b>() does not exist on your system,
  see <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a> for
  advice about how to generate cryptographically secure random bytes.
<div class="Pp"></div>
Computing a message authentication code all at once:
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
uint8_t hash   [64]; /* Output hash  (between 1 and 64 bytes)  */ 
uint8_t key    [32]; /* Key          (at least 1 byte)         */ 
uint8_t message[10] = &quot;Lorem ipsu&quot;; /* Message to authenticate */ 
arc4random_buf(key, 32); 
crypto_hmac_sha512(hash, key, 32, message, 500); 
/* Wipe secrets if they are no longer needed */ 
crypto_wipe(message, 500); 
crypto_wipe(key, 32);
</pre>
</div>
<div class="Pp"></div>
Computing a message authentication code incrementally:
<div class="Pp"></div>
<div class="Bd" style="margin-left: 5.00ex;">
<pre class="Li">
uint8_t hash   [64]; /* Output hash  (between 1 and 64 bytes)  */ 
uint8_t key    [32]; /* Key          (at least 1 byte)         */ 
uint8_t message[500] = {1}; /* Message to authenticate         */ 
crypto_hmac_sha512_ctx ctx; 
arc4random_buf(key, 32); 
crypto_hmac_sha512_init(&amp;ctx, key, 32); 
/* Wipe the key */ 
crypto_wipe(key, 32); 
for (size_t i = 0; i &lt; 500; i += 100) { 
    crypto_hmac_sha512_update(&amp;ctx, message + i, 100); 
    /* Wipe secrets if they are no longer needed */ 
    crypto_wipe(message + i, 100); 
} 
crypto_hmac_sha512_final(&amp;ctx, hash);
</pre>
</div>
<h1 class="Sh" title="Sh" id="SEE_ALSO"><a class="selflink" href="#SEE_ALSO">SEE
  ALSO</a></h1>
<a class="Xr" title="Xr" href="crypto_blake2b.html">crypto_blake2b(3monocypher)</a>,
  <a class="Xr" title="Xr" href="crypto_lock.html">crypto_lock(3monocypher)</a>,
  <a class="Xr" title="Xr" href="crypto_poly1305.html">crypto_poly1305(3monocypher)</a>,
  <a class="Xr" title="Xr" href="crypto_sha512.html">crypto_sha512(3monocypher)</a>,
  <a class="Xr" title="Xr" href="intro.html">intro(3monocypher)</a>
<h1 class="Sh" title="Sh" id="STANDARDS"><a class="selflink" href="#STANDARDS">STANDARDS</a></h1>
These functions implement HMAC with SHA-512. HMAC and SHA-512 itself are
  described in RFC 6234; SHA-512 is also described in the Federal Information
  Processing Standard (FIPS) 180-4; HMAC is also described in FIPS 198-1.
<h1 class="Sh" title="Sh" id="HISTORY"><a class="selflink" href="#HISTORY">HISTORY</a></h1>
The <b class="Fn" title="Fn">crypto_hmac_sha512</b>(),
  <b class="Fn" title="Fn">crypto_hmac_sha512_init</b>(),
  <b class="Fn" title="Fn">crypto_hmac_sha512_update</b>(), and
  <b class="Fn" title="Fn">crypto_hmac_sha512_final</b>() functions first
  appeared in Monocypher 3.0.0.</div>
<table class="foot">
  <tr>
    <td class="foot-date">March 2, 2020</td>
    <td class="foot-os">Linux 4.15.0-106-generic</td>
  </tr>
</table>
</body>
</html>