Add libar2simplified_recommendation1.0

Signed-off-by: Mattias Andrée <maandree@kth.se>

9 files changed, 145 insertions, 4 deletions

diff --git a/Makefile b/Makefile
index 92cdb58..ab4c9ad 100644
--- a/Makefile
+++ b/Makefile
@@ -21,7 +21,8 @@ OBJ =\
 	libar2simplified_decode.o\
 	libar2simplified_encode.o\
 	libar2simplified_encode_hash.o\
-	libar2simplified_hash.o
+	libar2simplified_hash.o\
+	libar2simplified_recommendation.o
 
 HDR =\
 	libar2simplified.h\
diff --git a/common.h b/common.h
index cb6a5fe..bd97175 100644
--- a/common.h
+++ b/common.h
@@ -31,3 +31,11 @@
 #ifndef FALLBACK_NPROC
 # define FALLBACK_NPROC 4
 #endif
+
+
+#ifndef RECOMMENDATION_SIDE_CHANNEL_ENVIRONMENT
+# define RECOMMENDATION_SIDE_CHANNEL_ENVIRONMENT "$argon2id$v=19$m=3072,t=32,p=4$*16$*48"
+#endif
+#ifndef RECOMMENDATION_SIDE_CHANNEL_FREE_ENVIRONMENT
+# define RECOMMENDATION_SIDE_CHANNEL_FREE_ENVIRONMENT "$argon2d$v=19$m=3072,t=32,p=4$*16$*48"
+#endif
diff --git a/libar2simplified.7 b/libar2simplified.7
index bc03fff..ef7584c 100644
--- a/libar2simplified.7
+++ b/libar2simplified.7
@@ -45,4 +45,5 @@ the parameters.
 .BR libar2simplified_decode (3),
 .BR libar2simplified_encode (3),
 .BR libar2simplified_encode_hash (3),
-.BR libar2simplified_hash (3)
+.BR libar2simplified_hash (3),
+.BR libar2simplified_recommendation (3)
diff --git a/libar2simplified.h b/libar2simplified.h
index cd784d4..e1233e2 100644
--- a/libar2simplified.h
+++ b/libar2simplified.h
@@ -4,6 +4,24 @@
 
 #include <libar2.h>
 
+/**
+ * Get a recommended set of hashing parameter
+ * 
+ * These shall not be taken too seriously, they are
+ * just for getting you up and running. You should
+ * tweak the them to your requirements.
+ * 
+ * @param   side_channel_free  Whether the environment is considered safe
+ *                             enought against side-channel attacks, use 0 if
+ *                             you don't know (it is very unlikely that it is)
+ * @return                     Hashing parameters than can be used for
+ *                             `libar2simplified_crypt` or `libar2simplified_decode`
+ */
+#if defined(__GNUC__)
+__attribute__((const))
+#endif
+const char *libar2simplified_recommendation(int side_channel_free);
+
 /* These are useful when the database stores parameters and
  * hash separately, when the application uses a pepper, or
  * when composing multiple hash functions: */
diff --git a/libar2simplified_crypt.3 b/libar2simplified_crypt.3
index 6b6a0e4..b2851e5 100644
--- a/libar2simplified_crypt.3
+++ b/libar2simplified_crypt.3
@@ -125,6 +125,7 @@ A thread terminated unexpectedly.
 
 .SH SEE ALSO
 .BR libar2simplified (7),
+.BR libar2simplified_recommendation (3),
 .BR libar2simplified_encode (3),
 .BR libar2simplified_hash (3),
 .BR libar2_hash (3),
diff --git a/libar2simplified_decode.3 b/libar2simplified_decode.3
index eaf8388..8de6ddf 100644
--- a/libar2simplified_decode.3
+++ b/libar2simplified_decode.3
@@ -32,7 +32,7 @@ parameter; or if
 .I random_byte_generator
 is
 .IR NULL ,
-a function built into the libary itself. If the parameter
+a function built into the library itself. If the parameter
 string specifies a tag (hash result), a pointer to it
 is stored in
 .IR *tagp ,
@@ -135,6 +135,7 @@ deallocated.
 .BR libar2simplified (7),
 .BR libar2simplified_encode (3),
 .BR libar2simplified_encode_hash (3),
+.BR libar2simplified_recommendation (3),
 .BR libar2simplified_hash (3),
 .BR libar2_decode_params (3),
 .BR libar2_validate_params (3),
diff --git a/libar2simplified_recommendation.3 b/libar2simplified_recommendation.3
new file mode 100644
index 0000000..842af40
--- /dev/null
+++ b/libar2simplified_recommendation.3
@@ -0,0 +1,50 @@
+.TH LIBAR2SIMPLIFIED_RECOMMENDATION 3 LIBAR2SIMPLIFIED
+.SH NAME
+libar2simplified_recommendation - Get recommended hashing parameters
+
+.SH SYNOPSIS
+.nf
+#include <libar2simplified.h>
+
+const char *libar2simplified_recommendation(int \fIside_channel_free\fP);
+.fi
+.PP
+Link with
+.IR "-lar2simplified" .
+
+.SH DESCRIPTION
+The
+.BR libar2simplified_recommendation ()
+function returns a hashing parameter string
+that can be used as input to the
+.BR libar2simplified_crypt (3)
+and
+.BR libar2simplified_decode (3)
+functions.
+.PP
+.I side_channel_free
+shall be 1 if you know that the environment
+is safe enought against side-channel attacks,
+otherwise it shall be 0.
+.PP
+The output parameters are just so you have
+something to start with, they shall not be taken
+too seriously, and should be tween to your
+requirements.
+
+.SH RETURN VALUES
+The
+.BR libar2simplified_recommendation ()
+function returns a statically allocated,
+read-only, hashing parameter string.
+
+.SH ERRORS
+The
+.BR libar2simplified_recommendation ()
+function cannot fail.
+
+.SH SEE ALSO
+.BR libar2simplified (7),
+.BR libar2simplified_crypt (3),
+.BR libar2simplified_decode (3),
+.BR libar2_hash (3)
diff --git a/libar2simplified_recommendation.c b/libar2simplified_recommendation.c
new file mode 100644
index 0000000..23f7060
--- /dev/null
+++ b/libar2simplified_recommendation.c
@@ -0,0 +1,9 @@
+/* See LICENSE file for copyright and license details. */
+#include "common.h"
+
+
+const char *
+libar2simplified_recommendation(int side_channel_free)
+{
+	return side_channel_free ? RECOMMENDATION_SIDE_CHANNEL_FREE_ENVIRONMENT : RECOMMENDATION_SIDE_CHANNEL_ENVIRONMENT;
+}
diff --git a/test.c b/test.c
index 413131a..a656b99 100644
--- a/test.c
+++ b/test.c
@@ -3,6 +3,10 @@
 #ifdef __linux__
 #include <sys/random.h>
 #endif
+#include <time.h>
+#ifndef CLOCK_MONOTONIC_RAW
+# define CLOCK_MONOTONIC_RAW CLOCK_MONOTONIC
+#endif
 
 #define SALT_ALPHABET "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"
 
@@ -114,8 +118,9 @@ check_hash(const char *pwd, size_t pwdlen, const char *input, const char *output
 
 
 #ifdef __linux__
-static ssize_t getrandom_return;
+static ssize_t getrandom_return = -1;
 static char getrandom_random0;
+static int getrandom_real;
 #endif
 
 ssize_t
@@ -149,6 +154,7 @@ check_random_salt_generate(void)
 		"HIJKLMNOHIJ"
 	};
 
+	getrandom_real = 0;
 	for (i = 0; i < sizeof(params) / sizeof(*params); i++) {
 		getrandom_return = (ssize_t)(i + 1);
 		getrandom_random0 = (char)i;
@@ -177,6 +183,41 @@ check_random_salt_generate(void)
 }
 
 
+static void
+time_hash(const char *params_str, const char *params_name, int lineno)
+{
+	struct libar2_argon2_parameters *params;
+	unsigned char hash[1024];
+	struct timespec start, end;
+	uintmax_t ms, sub_ms;
+	int r;
+
+	from_lineno = lineno;
+	errno = 0;
+
+	assert(!!(params = libar2simplified_decode(params_str, NULL, NULL, NULL)));
+	assert(params->hashlen <= sizeof(hash));
+	clock_gettime(CLOCK_MONOTONIC_RAW, &start);
+	r = libar2simplified_hash(hash, NULL, 0, params);
+	clock_gettime(CLOCK_MONOTONIC_RAW, &end);
+	assert(!r);
+	free(params);
+	end.tv_sec -= start.tv_sec;
+	end.tv_nsec -= start.tv_nsec;
+	if (end.tv_nsec < 0) {
+		end.tv_sec -= 1;
+		end.tv_nsec += 1000000000L;
+	}
+	ms = (uintmax_t)end.tv_sec;
+	ms *= 1000;
+	ms += (uintmax_t)(end.tv_nsec / 1000000L);
+	sub_ms = (uintmax_t)(end.tv_nsec % 1000000L);
+	fprintf(stderr, "Hash time for %s: %ju.%06jums\n", params_name, ms, sub_ms);
+
+	from_lineno = 0;
+}
+
+
 static int
 gensalt_ICAgICAgICA(char *out, size_t n)
 {
@@ -192,6 +233,7 @@ gensalt_ICAgICAgICA(char *out, size_t n)
 int
 main(void)
 {
+#if 1
 #define CHECK(PWD, HASH)\
 	check_hash(MEM(PWD), HASH, HASH, NULL, __LINE__)
 
@@ -245,5 +287,15 @@ main(void)
 
 	check_random_salt_generate();
 
+	assert_streq(libar2simplified_recommendation(0), RECOMMENDATION_SIDE_CHANNEL_ENVIRONMENT);
+	assert_streq(libar2simplified_recommendation(1), RECOMMENDATION_SIDE_CHANNEL_FREE_ENVIRONMENT);
+#endif
+
+#if 0
+#define TIME_HASH(PARAMS) time_hash(PARAMS, #PARAMS, __LINE__)
+	TIME_HASH(libar2simplified_recommendation(0));
+	TIME_HASH(libar2simplified_recommendation(1));
+#endif
+
 	return 0;
 }