January 12, 2020 posted by Jason High

Introduction

We successfully incorporated the Argon2 reference implementation into NetBSD/amd64 for our 2019 Google Summer of Coding project. We introduced our project here and provided some hints on how to select parameters here . For our final report, we will provide an overview of what changes were made to complete the project.

Incorporating the Argon2 Reference Implementation

The Argon2 reference implementation, available here , is available under both the Creative Commons CC0 1.0 and the Apache Public License 2.0 . To import the reference implementation into src/external, we chose to use the Apache 2.0 license for this project.

During our initial phase 1, we focused on building the libargon2 library and integrating the functionality into the existing password management framework via libcrypt. Toward this end, we imported the reference implementation and created the "glue" to incorporate the changes into /usr/src/external/apache. The reference implementation is found in

m2$ ls /usr/src/external/apache2/argon2 Makefile dist lib usr.bin

_MKVARS.yes= \ ... MKARGON2 \ ...

.if (defined(MKARGON2) && ${MKARGON2} != "no") SUBDIR+= argon2 .endif

/usr/bin/argon2 /usr/lib/libargon2.a /usr/lib/libargon2.so /usr/lib/libargon2.so.1 /usr/lib/libargon2.so.1.0

.if (defined(MKARGON2) && ${MKARGON2} != "no") HAVE_ARGON2=1 .endif

.if defined(HAVE_ARGON2) SRCS+= crypt-argon2.c CFLAGS+= -DHAVE_ARGON2 -I../../external/apache2/argon2/dist/phc-winner -argon2/include/ LDADD+= -largon2 .endif

The Argon2 reference implementation provides both a library and a binary. We build the libargon2 library to support libcrypt integration, and the argon2(1) binary to provide a userland command-line tool for evaluation. To build the code, we add MKARGON2 to bsd.own.mkand add the following conditional build to /usr/src/external/apache2/MakefileAfter successfully building and installation, we have the following new files and symlinksTo incorporate Argon2 into the password management framework of NetBSD, we focused on libcrypt. In /usr/src/lib/libcrypt/Makefile, we first check for MKARGON2If HAVE_ARGON2 is defined and enabled, we append the following to the build flagsAs hinted above, our most significant addition to libcrypt is the file crypt-argon2.c. This file pulls in the functionality of libargon2 into libcrypt. Changes were also made to pw_gensalt.c to allow for parameter parsing and salt generation.

Having completed the backend support, we pull Argon2 into userland tools, such as pwhash(1), in the same way as above

.if ( defined(MKARGON2) && ${MKARGON2} != "no" ) CPPFLAGS+= -DHAVE_ARGON2 .endif

m2# pwhash -A argon2id password $argon2id$v=19$m=4096,t=3,p=1$.SJJCiU575MDnA8s$+pjT4JsF2eLNQuLPEyhRA5LCFG QWAKsksIPl5ewTWNY

m1# grep -A1 testuser /etc/passwd.conf testuser: localcipher = argon2i,t=6,m=4096,p=1

m1# passwd testuser Changing password for testuser. New Password: Retype New Password: m1# grep testuser /etc/master.passwd testuser:$argon2i$v=19$m=4096,t=6,p=1$PDd65qr6JU0Pfnpr$8YOMYcwINuKHoxIV8Q0FJHG+ RP82xtmAuGep26brilU:1001:100::0:0::/home/testuser:/sbin/nologin

Testing

m2# echo -n password|argon2 somesalt -id -p 3 -m 8 Type: Argon2id Iterations: 3 Memory: 256 KiB Parallelism: 3 Hash: 97f773f68715d27272490d3d2e74a2a9b06a5bca759b71eab7c02be8a453bfb9 Encoded: $argon2id$v=19$m=256,t=3,p=3$c29tZXNhbHQ$l/dz9ocV0nJySQ09LnSiqb BqW8p1m3Hqt8Ar6KRTv7k 0.000 seconds Verification ok

/usr/src/tests/usr.bin/argon2 tp: t_argon2_v10_hash tp: t_argon2_v10_verify tp: t_argon2_v13_hash tp: t_argon2_v13_verify cd /usr/src/tests/usr.bin/argon2 atf-run info: atf.version, Automated Testing Framework 0.20 (atf-0.20) info: tests.root, /usr/src/tests/usr.bin/argon2 .. tc-so:Executing command [ /bin/sh -c echo -n password | \ argon2 somesalt -v 13 -t 2 -m 8 -p 1 -r ] tc-end: 1567497383.571791, argon2_v13_t2_m8_p1, passed ...

Conclusion

Once built, we can specify Argon2 using the '-A' command-line argument to pwhash(1), followed by the Argon2 variant name, and any of the parameterized values specified in argon2(1). See our first blog post for more details. As an example, to generate an argon2id encoding of the passwordusing default parameters, we can use the followingTo simplify Argon2 password management, we can utilize passwd.conf(5) to apply Argon2 to a specified user or all users. The same parameters are accepted as for argon2(1). For example, to specify argon2i with non-default parameters for user 'testuser', you can use the following in your passwd.confWith the above configuration in place, we are able to support standard password management. For exampleThe argon2(1) binary allows us to easily validate parameters and encoding. This is most useful during performance testing, see here . With argon2(1), we can specify our parameterized values and evaluate both the resulting encoding and timing.We provide one approach to evaluating Argon2 parameter tuning in our second post . In addition to manual testing, we also provide some ATF tests for pwhash, for both hashing and verification. These tests are focus on encoding correctness, matching known encodings to test results during execution.We have successfully integrated Argon2 into NetBSD using the native build framework. We have extended existing functionality to support local password management using Argon2 encoding. We are able to tune Argon2 so that we can achieve reasonable performance on NetBSD. In this final post, we summarize the work done to incorporate the reference implementation into NetBSD and how to use it. We hope you can use the work completed during this project. Thank you for the opportunity to participate in the Google Summer of Code 2019 and the NetBSD project!