2 * Argon2 reference source code package - reference C implementations
5 * Daniel Dinu, Dmitry Khovratovich, Jean-Philippe Aumasson, and Samuel Neves
7 * You may use this work under the terms of a Creative Commons CC0 1.0
8 * License/Waiver or the Apache Public License 2.0, at your option. The terms of
9 * these licenses can be found at:
11 * - CC0 1.0 Universal : http://creativecommons.org/publicdomain/zero/1.0
12 * - Apache 2.0 : http://www.apache.org/licenses/LICENSE-2.0
14 * You should have received a copy of both of these licenses along with this
15 * software. If not, they may be obtained at the above URLs.
26 * Example code for a decoder and encoder of "hash strings", with Argon2
29 * This code comprises three sections:
31 * -- The first section contains generic Base64 encoding and decoding
32 * functions. It is conceptually applicable to any hash function
33 * implementation that uses Base64 to encode and decode parameters,
34 * salts and outputs. It could be made into a library, provided that
35 * the relevant functions are made public (non-static) and be given
36 * reasonable names to avoid collisions with other functions.
38 * -- The second section is specific to Argon2. It encodes and decodes
39 * the parameters, salts and outputs. It does not compute the hash
42 * The code was originally written by Thomas Pornin <pornin@bolet.org>,
43 * to whom comments and remarks may be sent. It is released under what
44 * should amount to Public Domain or its closest equivalent; the
45 * following mantra is supposed to incarnate that fact with all the
46 * proper legal rituals:
48 * ---------------------------------------------------------------------
49 * This file is provided under the terms of Creative Commons CC0 1.0
50 * Public Domain Dedication. To the extent possible under law, the
51 * author (Thomas Pornin) has waived all copyright and related or
52 * neighboring rights to this file. This work is published from: Canada.
53 * ---------------------------------------------------------------------
55 * Copyright (c) 2015 Thomas Pornin
58 /* ==================================================================== */
60 * Common code; could be shared between different hash functions.
62 * Note: the Base64 functions below assume that uppercase letters (resp.
63 * lowercase letters) have consecutive numerical codes, that fit on 8
64 * bits. All modern systems use ASCII-compatible charsets, where these
65 * properties are true. If you are stuck with a dinosaur of a system
66 * that still defaults to EBCDIC then you already have much bigger
67 * interoperability issues to deal with.
71 * Some macros for constant-time comparisons. These work over values in
72 * the 0..255 range. Returned value is 0x00 on "false", 0xFF on "true".
74 #define EQ(x, y) ((((0U - ((unsigned)(x) ^ (unsigned)(y))) >> 8) & 0xFF) ^ 0xFF)
75 #define GT(x, y) ((((unsigned)(y) - (unsigned)(x)) >> 8) & 0xFF)
76 #define GE(x, y) (GT(y, x) ^ 0xFF)
77 #define LT(x, y) GT(y, x)
78 #define LE(x, y) GE(y, x)
81 * Convert value x (0..63) to corresponding Base64 character.
83 static int b64_byte_to_char(unsigned x) {
84 return (LT(x, 26) & (x + 'A')) |
85 (GE(x, 26) & LT(x, 52) & (x + ('a' - 26))) |
86 (GE(x, 52) & LT(x, 62) & (x + ('0' - 52))) | (EQ(x, 62) & '+') |
91 * Convert character c to the corresponding 6-bit value. If character c
92 * is not a Base64 character, then 0xFF (255) is returned.
94 static unsigned b64_char_to_byte(int c) {
97 x = (GE(c, 'A') & LE(c, 'Z') & (c - 'A')) |
98 (GE(c, 'a') & LE(c, 'z') & (c - ('a' - 26))) |
99 (GE(c, '0') & LE(c, '9') & (c - ('0' - 52))) | (EQ(c, '+') & 62) |
101 return x | (EQ(x, 0) & (EQ(c, 'A') ^ 0xFF));
105 * Convert some bytes to Base64. 'dst_len' is the length (in characters)
106 * of the output buffer 'dst'; if that buffer is not large enough to
107 * receive the result (including the terminating 0), then (size_t)-1
108 * is returned. Otherwise, the zero-terminated Base64 string is written
109 * in the buffer, and the output length (counted WITHOUT the terminating
112 static size_t to_base64(char *dst, size_t dst_len, const void *src,
115 const unsigned char *buf;
116 unsigned acc, acc_len;
118 olen = (src_len / 3) << 2;
119 switch (src_len % 3) {
127 if (dst_len <= olen) {
132 buf = (const unsigned char *)src;
133 while (src_len-- > 0) {
134 acc = (acc << 8) + (*buf++);
136 while (acc_len >= 6) {
138 *dst++ = (char)b64_byte_to_char((acc >> acc_len) & 0x3F);
142 *dst++ = (char)b64_byte_to_char((acc << (6 - acc_len)) & 0x3F);
149 * Decode Base64 chars into bytes. The '*dst_len' value must initially
150 * contain the length of the output buffer '*dst'; when the decoding
151 * ends, the actual number of decoded bytes is written back in
154 * Decoding stops when a non-Base64 character is encountered, or when
155 * the output buffer capacity is exceeded. If an error occurred (output
156 * buffer is too small, invalid last characters leading to unprocessed
157 * buffered bits), then NULL is returned; otherwise, the returned value
158 * points to the first non-Base64 character in the source stream, which
159 * may be the terminating zero.
161 static const char *from_base64(void *dst, size_t *dst_len, const char *src) {
164 unsigned acc, acc_len;
166 buf = (unsigned char *)dst;
173 d = b64_char_to_byte(*src);
178 acc = (acc << 6) + d;
182 if ((len++) >= *dst_len) {
185 *buf++ = (acc >> acc_len) & 0xFF;
190 * If the input length is equal to 1 modulo 4 (which is
191 * invalid), then there will remain 6 unprocessed bits;
192 * otherwise, only 0, 2 or 4 bits are buffered. The buffered
193 * bits must also all be zero.
195 if (acc_len > 4 || (acc & (((unsigned)1 << acc_len) - 1)) != 0) {
203 * Decode decimal integer from 'str'; the value is written in '*v'.
204 * Returned value is a pointer to the next non-decimal character in the
205 * string. If there is no digit at all, or the value encoding is not
206 * minimal (extra leading zeros), or the value does not fit in an
207 * 'unsigned long', then NULL is returned.
209 static const char *decode_decimal(const char *str, unsigned long *v) {
214 for (orig = str;; str++) {
218 if (c < '0' || c > '9') {
222 if (acc > (ULONG_MAX / 10)) {
226 if ((unsigned long)c > (ULONG_MAX - acc)) {
229 acc += (unsigned long)c;
231 if (str == orig || (*orig == '0' && str != (orig + 1))) {
238 /* ==================================================================== */
240 * Code specific to Argon2.
242 * The code below applies the following format:
244 * $argon2<T>[$v=<num>]$m=<num>,t=<num>,p=<num>$<bin>$<bin>
246 * where <T> is either 'd', 'id', or 'i', <num> is a decimal integer (positive,
247 * fits in an 'unsigned long'), and <bin> is Base64-encoded data (no '=' padding
248 * characters, no newline or whitespace).
250 * The last two binary chunks (encoded in Base64) are, in that order,
251 * the salt and the output. Both are required. The binary salt length and the
252 * output length must be in the allowed ranges defined in argon2.h.
254 * The ctx struct must contain buffers large enough to hold the salt and pwd
255 * when it is fed into decode_string.
258 int decode_string(argon2_context *ctx, const char *str, argon2_type type) {
260 /* check for prefix */
263 size_t cc_len = strlen(prefix); \
264 if (strncmp(str, prefix, cc_len) != 0) { \
265 return ARGON2_DECODING_FAIL; \
270 /* optional prefix checking with supplied code */
271 #define CC_opt(prefix, code) \
273 size_t cc_len = strlen(prefix); \
274 if (strncmp(str, prefix, cc_len) == 0) { \
280 /* Decoding prefix into decimal */
283 unsigned long dec_x; \
284 str = decode_decimal(str, &dec_x); \
286 return ARGON2_DECODING_FAIL; \
292 /* Decoding prefix into uint32_t decimal */
293 #define DECIMAL_U32(x) \
295 unsigned long dec_x; \
296 str = decode_decimal(str, &dec_x); \
297 if (str == NULL || dec_x > UINT32_MAX) { \
298 return ARGON2_DECODING_FAIL; \
300 (x) = (uint32_t)dec_x; \
304 /* Decoding base64 into a binary buffer */
305 #define BIN(buf, max_len, len) \
307 size_t bin_len = (max_len); \
308 str = from_base64(buf, &bin_len, str); \
309 if (str == NULL || bin_len > UINT32_MAX) { \
310 return ARGON2_DECODING_FAIL; \
312 (len) = (uint32_t)bin_len; \
315 size_t maxsaltlen = ctx->saltlen;
316 size_t maxoutlen = ctx->outlen;
317 int validation_result;
318 const char* type_string;
320 /* We should start with the argon2_type we are using */
321 type_string = argon2_type2string(type, 0);
323 return ARGON2_INCORRECT_TYPE;
329 /* Reading the version number if the default is suppressed */
330 ctx->version = ARGON2_VERSION_10;
331 CC_opt("$v=", DECIMAL_U32(ctx->version));
334 DECIMAL_U32(ctx->m_cost);
336 DECIMAL_U32(ctx->t_cost);
338 DECIMAL_U32(ctx->lanes);
339 ctx->threads = ctx->lanes;
342 BIN(ctx->salt, maxsaltlen, ctx->saltlen);
344 BIN(ctx->out, maxoutlen, ctx->outlen);
346 /* The rest of the fields get the default values */
351 ctx->allocate_cbk = NULL;
352 ctx->free_cbk = NULL;
353 ctx->flags = ARGON2_DEFAULT_FLAGS;
355 /* On return, must have valid context */
356 validation_result = validate_inputs(ctx);
357 if (validation_result != ARGON2_OK) {
358 return validation_result;
361 /* Can't have any additional characters */
365 return ARGON2_DECODING_FAIL;
373 int encode_string(char *dst, size_t dst_len, argon2_context *ctx,
377 size_t pp_len = strlen(str); \
378 if (pp_len >= dst_len) { \
379 return ARGON2_ENCODING_FAIL; \
381 memcpy(dst, str, pp_len + 1); \
389 sprintf(tmp, "%lu", (unsigned long)(x)); \
393 #define SB(buf, len) \
395 size_t sb_len = to_base64(dst, dst_len, buf, len); \
396 if (sb_len == (size_t)-1) { \
397 return ARGON2_ENCODING_FAIL; \
403 const char* type_string = argon2_type2string(type, 0);
404 int validation_result = validate_inputs(ctx);
407 return ARGON2_ENCODING_FAIL;
410 if (validation_result != ARGON2_OK) {
411 return validation_result;
429 SB(ctx->salt, ctx->saltlen);
432 SB(ctx->out, ctx->outlen);
440 size_t b64len(uint32_t len) {
441 size_t olen = ((size_t)len / 3) << 2;
455 size_t numlen(uint32_t num) {