-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.md.in
143 lines (112 loc) · 5.03 KB
/
README.md.in
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
# EnScrypt @enscrypt_version@
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](https://www.grc.com/)
* [Algorithm Detail](https://www.grc.com/sqrl/scrypt.htm)
* This software (EnScrypt) is an implementation of the EnScrypt algorithm that Steve designed for SQRL.
* scrypt-jane
* Author: Andrew M
* [Source](https://github.com/floodyberry/scrypt-jane)
* 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](http://NadeauSoftware.com/)
* [Article](http://nadeausoftware.com/articles/2012/04/c_c_tip_how_measure_elapsed_real_time_benchmarking)
* 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](https://www.grc.com/sqrl/scrypt.htm). 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.