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