Debian Codegraph @

README

raw
1 [![Build matrix](https://github.com/besser82/libxcrypt/actions/workflows/config-matrix.yml/badge.svg)](https://github.com/besser82/libxcrypt/actions/workflows/config-matrix.yml)
2 [![Memcheck](https://github.com/besser82/libxcrypt/actions/workflows/memcheck.yml/badge.svg)](https://github.com/besser82/libxcrypt/actions/workflows/memcheck.yml)
3 [![Distcheck](https://github.com/besser82/libxcrypt/actions/workflows/distcheck.yml/badge.svg)](https://github.com/besser82/libxcrypt/actions/workflows/distcheck.yml)
4 [![COPR Build Status](https://copr.fedorainfracloud.org/coprs/besser82/libxcrypt_CI/package/libxcrypt/status_image/last_build.png)](https://copr.fedorainfracloud.org/coprs/besser82/libxcrypt_CI)
5 [![codecov](https://codecov.io/gh/besser82/libxcrypt/branch/develop/graph/badge.svg)](https://codecov.io/gh/besser82/libxcrypt)
6 [![Coverity Scan Build Status](https://scan.coverity.com/projects/17073/badge.svg)](https://scan.coverity.com/projects/besser82-libxcrypt)
7 [![Codacy Badge](https://api.codacy.com/project/badge/Grade/1ebaa2314aca4bab92e14130906d5096)](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