EnScrypt 1.2 build 1

EnScrypt is an acceleration-resistant password hashing library and utility based on the memory-hard PBKDF Scrypt.

Based On

• SQRL
  • Author: Steve Gibson
  • Author's Site
  • Algorithm Detail
  • This software (EnScrypt) is an implementation of the EnScrypt algorithm that Steve designed for SQRL.
• scrypt-jane
  • Author: Andrew M
  • Source
  • License: Public Domain, or MIT
  • The heavy lifting of the EnScrypt algorithm is handled by scrypt-jane, with minor modifications.
• getRealTime.c
  • Author: David Robert Nadeau
  • Author's Site
  • Article
  • License: Creative Commons Attribution 3.0 Unported License (http://creativecommons.org/licenses/by/3.0/deed.en_US)
  • This is used for accurate cross-platform timing.

Supported Platforms

This implementation is intended to work on multiple platforms. Tested platforms include:

• Linux (Ubuntu 32 and 64 bit)
• Win32 (Tested on Windows 8.1 64 bit)
• Mac OS X (Tested on 10.9.2 64 bit)
• Android ARM
• Android ARM with NEON (optimized implementation with runtime detection of NEON support and fallback)

Compiles, but has not been thoroughly tested on:

• Android X86
• Android MIPS

Planned, but not yet supported:

• iOS

Building and Installing

See the BUILDING.md file for build instructions.

Using the command line utility

The command line utility is substantially similar to Steve Gibson's reference implementation. Normal use is almost identical:

enscrypt [-q] [password] [salt] [iteration_count | duration]

All arguments are optional, and order is arbitrary. This implementation adds the "-q" and "-h" options.

• duration: An integer + 's' or 'S'. For example, "5s" == 5 seconds.
• iteration_count: An integer + 'i' or 'I'. For example, "100i" == 100 iterations.
• salt: a 64 character hex string representing a 32 byte salt. Allowed characters are 0-9, a-f, and A-F.
• -q: Quiet. Suppresses all output except the computed output key.
• -h: Help. Displays usage information.
• password: any string not matching the above arguments.

Using the library

Documentation is available in the enscrypt.h header, or in HTML in the doc directory.

Basic Use

Typically, you'll just need two functions from the library, enscrypt() and enscrypt_ms(). They look like this:

int enscrypt(uint8_t *buf, const char *passwd, size_t passwd_len, const uint8_t *salt, size_t salt_len, int iterations, int n_factor, enscrypt_progress_fn cb_ptr, void *cb_data );
int enscrypt_ms( uint8_t *buf, const char *passwd, size_t passwd_len, const uint8_t *salt, size_t salt_len, int millis, int n_factor, enscrypt_progress_fn cb_ptr, void *cb_data );

To run 100 iterations:

#include <enscrypt.h>

int main()
{
  int time_elapsed;
  uint8_t buf[32];
  uint8_t salt[32] = {0};
  
  time_elapsed = enscrypt( buf, "password", 8, salt, 32, 100, 9, NULL, NULL );
}

Or, to run for 5 seconds:

#include <enscrypt.h>

int main()
{
  int iteration_count;
  uint8_t buf[32];
  uint8_t salt[32] = {0};
  
  iteration_count = enscrypt_ms( buf, "password", 8, salt, 32, 5000, 9, NULL, NULL );
}

To use a callback function to monitor progress:

#include <enscrypt.h>

void progress_fn( int progress )
{
  printf( "%d%%\n", progress );
}

int main()
{
  uint8_t buf[32];
  
  enscrypt( buf, NULL, 0, NULL, 0, 100, 9, progress_fn, NULL );
}

Advanced use

See the documentation in enscrypt.h for more details on each:

• enscrypt_progress_fn - progress callback prototype.
• enscrypt_fatal_errorfn - fatal error function prototype.
• enscrypt_get_real_time() - Get a value representing execution time.
• enscrypt_set_fatal_error() - Set a function to call in the event of an un-recoverable error.

License

This work is released under the MIT License as follows:

Copyright (c) 2014 Adam Comley

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.