README
1[](https://github.com/besser82/libxcrypt/actions/workflows/config-matrix.yml)
2[](https://github.com/besser82/libxcrypt/actions/workflows/memcheck.yml)
3[](https://github.com/besser82/libxcrypt/actions/workflows/distcheck.yml)
4[](https://copr.fedorainfracloud.org/coprs/besser82/libxcrypt_CI)
5[](https://codecov.io/gh/besser82/libxcrypt)
6[](https://scan.coverity.com/projects/besser82-libxcrypt)
7[](https://www.codacy.com/manual/besser82/libxcrypt?utm_source=github.com&utm_medium=referral&utm_content=besser82/libxcrypt&utm_campaign=Badge_Grade)
8
9README for libxcrypt
10====================
11
12libxcrypt is a modern library for one-way hashing of passwords. It
13supports a wide variety of both modern and historical hashing methods:
14yescrypt, gost-yescrypt, scrypt, bcrypt, sha512crypt, sha256crypt,
15md5crypt, SunMD5, sha1crypt, NT, bsdicrypt, bigcrypt, and descrypt.
16It provides the traditional Unix `crypt` and `crypt_r` interfaces, as
17well as a set of extended interfaces pioneered by Openwall Linux,
18`crypt_rn`, `crypt_ra`, `crypt_gensalt`, `crypt_gensalt_rn`, and
19`crypt_gensalt_ra`.
20
21libxcrypt is intended to be used by `login(1)`, `passwd(1)`, and other
22similar programs; that is, to hash a small number of passwords during
23an interactive authentication dialogue with a human. It is not
24suitable for use in bulk password-cracking applications, or in any
25other situation where speed is more important than careful handling of
26sensitive data. However, it *is* intended to be fast and lightweight
27enough for use in servers that must field thousands of login attempts
28per minute.
29
30Authorship and Licensing
31------------------------
32
33libxcrypt is currently maintained by Björn Esser and Zack Weinberg.
34Many people have contributed to the code making up libxcrypt, often
35under the aegis of a different project. Please see the AUTHORS and
36THANKS files for a full set of credits.
37
38libxcrypt as a whole is licensed under the GNU Lesser General Public
39License (version 2.1, or at your option, any later version). However,
40many individual files may be reused under more permissive licenses if
41separated from the library. Please see the LICENSING file for a
42comprehensive inventory of licenses, and COPYING.LIB for the terms of
43the LGPL.
44
45Bug Reports, Feature Requests, Contributions, Etc.
46--------------------------------------------------
47
48libxcrypt is currently maintained at Github: the canonical repository
49URL is <https://github.com/besser82/libxcrypt>. Please file bug
50reports at <https://github.com/besser82/libxcrypt/issues>. This is
51also the appropriate place to suggest new features, offer patches,
52etc. All your feedback is welcome and will eventually receive a
53response, but this is a spare-time project for all of the present
54maintainers, so please be patient.
55
56Build Requirements and Instructions
57-----------------------------------
58
59To build from a tarball release, the tools required are the standard
60Unix shell environment, a C compiler, and Perl (version 5.14 or
61later). Follow the generic build and installation instructions in the
62file `INSTALL`. There are several package-specific configure options;
63run `./configure --help` for more detail on these options.
64Run `man -l crypt.5` for more detail on the hashing algorithms that
65can be enabled or disabled by `--enable-hashes`. You can do both of
66these things before building the software.
67
68Building from a Git checkout additionally requires the Autotools
69suite: `autoconf`, `automake`, `libtool`, and `pkg-config`.
70Run `./autogen.sh` at the top level of the source tree, and then
71follow the instructions in `INSTALL` (which is created by that command).
72
73The oldest versions of Autotools components that are known to work
74are: autoconf 2.69, automake 1.14, libtool 2.4.6, pkg-config 0.29.
75If you test with an older version of one of these and find that it
76works, please let us know. We are not deliberately requiring newer
77versions; we just can’t conveniently test older versions ourselves.
78
79Portability Notes
80-----------------
81
82libxcrypt should be buildable with any ISO C1999-compliant C compiler,
83with one critical exception: the symbol versioning macros in
84`crypt-port.h` only work with compilers that implement certain GCC and
85GNU Binutils extensions (`__attribute__((alias))`, GCC-style `asm`,
86and `.symver`).
87
88A few C2011 features are used; the intention is not to use any of them
89without a fallback, but we do not currently test this. A few POSIX
90and nonstandard-but-widespread Unix APIs are also used; again, the
91intention is not to use any of them without a fallback, but we do not
92currently test this. In particular, the crypt_gensalt functions may
93not always be able to retrieve cryptographically-sound random numbers
94from the operating system; if you call these functions with a null
95pointer for the “rbytes” argument, be prepared for them to fail.
96
97As of mid-2018, GCC and LLVM don’t support link-time optimization of
98libraries that use symbol versioning. If you build libxcrypt with
99either of these compilers, do not use `-flto`. See [GCC bug 48200][1]
100for specifics; the problem is very similar for LLVM. Because this is,
101at its root, a set of missing compiler features, we expect link-time
102optimization won’t work in other C compilers either, but we haven’t
103tested it ourselves.
104
105[1]: https://gcc.gnu.org/bugzilla/show_bug.cgi?id=48200
106
107Compatibility Notes
108-------------------
109
110On Linux-based systems, by default libxcrypt will be binary backward
111compatible with the libcrypt.so.1 shipped as part of the GNU C
112Library. This means that all existing binary executables linked
113against glibc’s libcrypt should work unmodified with this library’s
114libcrypt.so.1. We have taken pains to provide exactly the same symbol
115versions as were used by glibc on various CPU architectures, and to
116account for the variety of ways in which the Openwall extensions were
117patched into glibc’s libcrypt by some Linux distributions. (For
118instance, compatibility symlinks for SUSE’s “libowcrypt” are provided.)
119
120However, the converse is not true: programs linked against libxcrypt
121will not work with glibc’s libcrypt. Also, programs that use certain
122legacy APIs supplied by glibc’s libcrypt (`encrypt`, `encrypt_r`,
123`setkey`, `setkey_r`, and `fcrypt`) cannot be *compiled* against
124libxcrypt.
125
126Binary backward compatibility can be disabled by supplying the
127`--disable-obsolete-api` switch to `configure`, in which case libxcrypt
128will install libcrypt.so.2 instead of libcrypt.so.1. This
129configuration is always used on all operating systems other than
130Linux. We are willing to consider adding binary backward
131compatibility for other operating systems’ existing libcrypts, but we
132don’t currently plan to do that work ourselves.
133
134Individual hash functions may be enabled or disabled by use of the
135`--enable-hashes` switch to `configure`. The default is to enable all
136supported hashes. Disabling the traditional ‘des’ hash algorithm
137implies `--disable-obsolete-api`. Security-conscious environments
138without backward compatibility constraints are encouraged to use
139`--enable-hashes=strong`, which enables only the hash functions that
140are strong enough to be safe for newly hashed passwords.
141
142The original implementation of the SunMD5 hashing algorithm has a bug,
143which is mimicked by libxcrypt to be fully compatible with hashes
144generated on (Open)Solaris. According to the only existing
145[documentation of this algorithm][2], its hashes were supposed to have
146the format `$md5[,rounds=%u]$<salt>$<checksum>`, and include only the
147bare string `$md5[,rounds=%u]$<salt>` in the salt digest
148step. However, almost all hashes encountered in production
149environments have the format `$md5[,rounds=%u]$<salt>$$<checksum>`
150(note the double $$). Unfortunately, it is not merely a cosmetic
151difference: hashes of this format incorporate the first $ after the
152salt within the salt digest step, so the resulting checksum is
153different. The documentation hints that this stems from a bug within
154the production implementation’s parser. This bug causes the
155implementation to return `$$`-format hashes when passed a
156configuration string that ends with `$`. It returns the intended
157original format and checksum only if there is at least one letter
158after the `$`, e.g. `$md5[,rounds=%u]$<salt>$x`.
159
160The NT algorithm, in its original implementation, never came with any
161`gensalt` function, because the algorithm does not use any. libxcrypt
162ships a bogus `gensalt` function for the NT algorithm, which simply
163returns `$3$`.
164
165glibc’s libcrypt could optionally be configured to use Mozilla’s NSS
166library’s implementations of the cryptographic primitives md5crypt,
167sha256crypt, and sha512crypt. This option is not available in
168libxcrypt, because we do not currently believe it is a desirable
169option. The stated rationale for the option was to source all
170cryptographic primitives from a library that has undergone FIPS
171certification, but we believe FIPS certification would need to cover
172all of libxcrypt itself to have any meaningful value. Moreover, the
173strongest hashing methods, yescrypt and bcrypt, use cryptographic
174primitives that are not available from NSS, so the certification
175would not cover any part of what will hopefully be the most used code
176paths.
177
178[2]: https://dropsafe.crypticide.com/article/1389
179
README.md
1[](https://github.com/besser82/libxcrypt/actions/workflows/config-matrix.yml)
2[](https://github.com/besser82/libxcrypt/actions/workflows/memcheck.yml)
3[](https://github.com/besser82/libxcrypt/actions/workflows/distcheck.yml)
4[](https://copr.fedorainfracloud.org/coprs/besser82/libxcrypt_CI)
5[](https://codecov.io/gh/besser82/libxcrypt)
6[](https://scan.coverity.com/projects/besser82-libxcrypt)
7[](https://www.codacy.com/manual/besser82/libxcrypt?utm_source=github.com&utm_medium=referral&utm_content=besser82/libxcrypt&utm_campaign=Badge_Grade)
8
9README for libxcrypt
10====================
11
12libxcrypt is a modern library for one-way hashing of passwords. It
13supports a wide variety of both modern and historical hashing methods:
14yescrypt, gost-yescrypt, scrypt, bcrypt, sha512crypt, sha256crypt,
15md5crypt, SunMD5, sha1crypt, NT, bsdicrypt, bigcrypt, and descrypt.
16It provides the traditional Unix `crypt` and `crypt_r` interfaces, as
17well as a set of extended interfaces pioneered by Openwall Linux,
18`crypt_rn`, `crypt_ra`, `crypt_gensalt`, `crypt_gensalt_rn`, and
19`crypt_gensalt_ra`.
20
21libxcrypt is intended to be used by `login(1)`, `passwd(1)`, and other
22similar programs; that is, to hash a small number of passwords during
23an interactive authentication dialogue with a human. It is not
24suitable for use in bulk password-cracking applications, or in any
25other situation where speed is more important than careful handling of
26sensitive data. However, it *is* intended to be fast and lightweight
27enough for use in servers that must field thousands of login attempts
28per minute.
29
30Authorship and Licensing
31------------------------
32
33libxcrypt is currently maintained by Björn Esser and Zack Weinberg.
34Many people have contributed to the code making up libxcrypt, often
35under the aegis of a different project. Please see the AUTHORS and
36THANKS files for a full set of credits.
37
38libxcrypt as a whole is licensed under the GNU Lesser General Public
39License (version 2.1, or at your option, any later version). However,
40many individual files may be reused under more permissive licenses if
41separated from the library. Please see the LICENSING file for a
42comprehensive inventory of licenses, and COPYING.LIB for the terms of
43the LGPL.
44
45Bug Reports, Feature Requests, Contributions, Etc.
46--------------------------------------------------
47
48libxcrypt is currently maintained at Github: the canonical repository
49URL is <https://github.com/besser82/libxcrypt>. Please file bug
50reports at <https://github.com/besser82/libxcrypt/issues>. This is
51also the appropriate place to suggest new features, offer patches,
52etc. All your feedback is welcome and will eventually receive a
53response, but this is a spare-time project for all of the present
54maintainers, so please be patient.
55
56Build Requirements and Instructions
57-----------------------------------
58
59To build from a tarball release, the tools required are the standard
60Unix shell environment, a C compiler, and Perl (version 5.14 or
61later). Follow the generic build and installation instructions in the
62file `INSTALL`. There are several package-specific configure options;
63run `./configure --help` for more detail on these options.
64Run `man -l crypt.5` for more detail on the hashing algorithms that
65can be enabled or disabled by `--enable-hashes`. You can do both of
66these things before building the software.
67
68Building from a Git checkout additionally requires the Autotools
69suite: `autoconf`, `automake`, `libtool`, and `pkg-config`.
70Run `./autogen.sh` at the top level of the source tree, and then
71follow the instructions in `INSTALL` (which is created by that command).
72
73The oldest versions of Autotools components that are known to work
74are: autoconf 2.69, automake 1.14, libtool 2.4.6, pkg-config 0.29.
75If you test with an older version of one of these and find that it
76works, please let us know. We are not deliberately requiring newer
77versions; we just can’t conveniently test older versions ourselves.
78
79Portability Notes
80-----------------
81
82libxcrypt should be buildable with any ISO C1999-compliant C compiler,
83with one critical exception: the symbol versioning macros in
84`crypt-port.h` only work with compilers that implement certain GCC and
85GNU Binutils extensions (`__attribute__((alias))`, GCC-style `asm`,
86and `.symver`).
87
88A few C2011 features are used; the intention is not to use any of them
89without a fallback, but we do not currently test this. A few POSIX
90and nonstandard-but-widespread Unix APIs are also used; again, the
91intention is not to use any of them without a fallback, but we do not
92currently test this. In particular, the crypt_gensalt functions may
93not always be able to retrieve cryptographically-sound random numbers
94from the operating system; if you call these functions with a null
95pointer for the “rbytes” argument, be prepared for them to fail.
96
97As of mid-2018, GCC and LLVM don’t support link-time optimization of
98libraries that use symbol versioning. If you build libxcrypt with
99either of these compilers, do not use `-flto`. See [GCC bug 48200][1]
100for specifics; the problem is very similar for LLVM. Because this is,
101at its root, a set of missing compiler features, we expect link-time
102optimization won’t work in other C compilers either, but we haven’t
103tested it ourselves.
104
105[1]: https://gcc.gnu.org/bugzilla/show_bug.cgi?id=48200
106
107Compatibility Notes
108-------------------
109
110On Linux-based systems, by default libxcrypt will be binary backward
111compatible with the libcrypt.so.1 shipped as part of the GNU C
112Library. This means that all existing binary executables linked
113against glibc’s libcrypt should work unmodified with this library’s
114libcrypt.so.1. We have taken pains to provide exactly the same symbol
115versions as were used by glibc on various CPU architectures, and to
116account for the variety of ways in which the Openwall extensions were
117patched into glibc’s libcrypt by some Linux distributions. (For
118instance, compatibility symlinks for SUSE’s “libowcrypt” are provided.)
119
120However, the converse is not true: programs linked against libxcrypt
121will not work with glibc’s libcrypt. Also, programs that use certain
122legacy APIs supplied by glibc’s libcrypt (`encrypt`, `encrypt_r`,
123`setkey`, `setkey_r`, and `fcrypt`) cannot be *compiled* against
124libxcrypt.
125
126Binary backward compatibility can be disabled by supplying the
127`--disable-obsolete-api` switch to `configure`, in which case libxcrypt
128will install libcrypt.so.2 instead of libcrypt.so.1. This
129configuration is always used on all operating systems other than
130Linux. We are willing to consider adding binary backward
131compatibility for other operating systems’ existing libcrypts, but we
132don’t currently plan to do that work ourselves.
133
134Individual hash functions may be enabled or disabled by use of the
135`--enable-hashes` switch to `configure`. The default is to enable all
136supported hashes. Disabling the traditional ‘des’ hash algorithm
137implies `--disable-obsolete-api`. Security-conscious environments
138without backward compatibility constraints are encouraged to use
139`--enable-hashes=strong`, which enables only the hash functions that
140are strong enough to be safe for newly hashed passwords.
141
142The original implementation of the SunMD5 hashing algorithm has a bug,
143which is mimicked by libxcrypt to be fully compatible with hashes
144generated on (Open)Solaris. According to the only existing
145[documentation of this algorithm][2], its hashes were supposed to have
146the format `$md5[,rounds=%u]$<salt>$<checksum>`, and include only the
147bare string `$md5[,rounds=%u]$<salt>` in the salt digest
148step. However, almost all hashes encountered in production
149environments have the format `$md5[,rounds=%u]$<salt>$$<checksum>`
150(note the double $$). Unfortunately, it is not merely a cosmetic
151difference: hashes of this format incorporate the first $ after the
152salt within the salt digest step, so the resulting checksum is
153different. The documentation hints that this stems from a bug within
154the production implementation’s parser. This bug causes the
155implementation to return `$$`-format hashes when passed a
156configuration string that ends with `$`. It returns the intended
157original format and checksum only if there is at least one letter
158after the `$`, e.g. `$md5[,rounds=%u]$<salt>$x`.
159
160The NT algorithm, in its original implementation, never came with any
161`gensalt` function, because the algorithm does not use any. libxcrypt
162ships a bogus `gensalt` function for the NT algorithm, which simply
163returns `$3$`.
164
165glibc’s libcrypt could optionally be configured to use Mozilla’s NSS
166library’s implementations of the cryptographic primitives md5crypt,
167sha256crypt, and sha512crypt. This option is not available in
168libxcrypt, because we do not currently believe it is a desirable
169option. The stated rationale for the option was to source all
170cryptographic primitives from a library that has undergone FIPS
171certification, but we believe FIPS certification would need to cover
172all of libxcrypt itself to have any meaningful value. Moreover, the
173strongest hashing methods, yescrypt and bcrypt, use cryptographic
174primitives that are not available from NSS, so the certification
175would not cover any part of what will hopefully be the most used code
176paths.
177
178[2]: https://dropsafe.crypticide.com/article/1389
179
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}