This is a major rewrite of the description of 'crypt', 'getentropy',
and 'getrandom'.
A few highlights of the content changes:
- Throughout the manual, public headers, and user-visible messages,
I replaced the term "password" with "passphrase", the term
"password database" with "user database", and the term
"encrypt(ion)" with "(one-way) hashing" whenever it was applied to
passphrases. I didn't bother making this change in internal code
or tests. The use of the term "password" in ruserpass.c survives,
because that refers to a keyword in netrc files, but it is adjusted
to make this clearer.
There is a note in crypt.texi explaining that they were
traditionally called passwords but single words are not good enough
anymore, and a note in users.texi explaining that actual passphrase
hashes are found in a "shadow" database nowadays.
- There is a new short introduction to the "Cryptographic Functions"
section, explaining how we do not intend to be a general-purpose
cryptography library, and cautioning that there _are_, or have
been, legal restrictions on the use of cryptography in many
countries, without getting into any kind of detail that we can't
promise to keep up to date.
- I added more detail about what a "one-way function" is, and why
they are used to obscure passphrases for storage. I removed the
paragraph saying that systems not connected to a network need no
user authentication, because that's a pretty rare situation
nowadays. (It still says "sometimes it is necessary" to
authenticate the user, though.)
- I added documentation for all of the hash functions that glibc
actually supports, but not for the additional hash functions
supported by libxcrypt. If we're going to keep this manual section
around after the transition is more advanced, it would probably
make sense to add them then.
- There is much more detailed discussion of how to generate a salt,
and the failure behavior for crypt is documented. (Returning an
invalid hash on failure is what libxcrypt does; Solar Designer's
notes say that this was done "for compatibility with old programs
that assume crypt can never fail".)
- As far as I can tell, the header 'crypt.h' is entirely a GNU
invention, and never existed on any other Unix lineage. The
function 'crypt', however, was in Issue 1 of the SVID and is now
in the XSI component of POSIX. I tried to make all of the
@standards annotations consistent with this, but I'm not sure I got
them perfectly right.
- The genpass.c example has been improved to use getentropy instead
of the current time to generate the salt, and to use a SHA-256 hash
instead of MD5. It uses more random bytes than is strictly
necessary because I didn't want to complicate the code with proper
base64 encoding.
- The testpass.c example has three hardwired hashes now, to
demonstrate that different one-way functions produce different
hashes for the same input. It also demonstrates how DES hashing
only pays attention to the first eight characters of the input.
- There is new text explaining in more detail how a CSPRNG differs
from a regular random number generator, and how
getentropy/getrandom are not exactly a CSPRNG. I tried not to make
specific falsifiable claims here. I also tried to make the
blocking/cancellation/error behavior of both getentropy and
getrandom clearer.
This adds system call wrappers for pkey_alloc, pkey_free, pkey_mprotect,
and x86-64 implementations of pkey_get and pkey_set, which abstract over
the PKRU CPU register and hide the actual number of memory protection
keys supported by the CPU. pkey_mprotect with a -1 key is implemented
using mprotect, so it will work even if the kernel does not support the
pkey_mprotect system call.
The system call wrapers use unsigned int instead of unsigned long for
parameters, so that no special treatment for x32 is needed. The flags
argument is currently unused, and the access rights bit mask is limited
to two bits by the current PKRU register layout anyway.
Reviewed-by: Adhemerval Zanella <adhemerval.zanella@linaro.org>
Clean up calls to malloc_printerr and trim its argument list.
This also removes a few bits of work done before calling
malloc_printerr (such as unlocking operations).
The tunable/environment variable still enables the lightweight
additional malloc checking, but mallopt (M_CHECK_ACTION)
no longer has any effect.
The Summary is now generated from @standards, and syntax-checking is
performed. If invalid @standards syntax is detected, summary.pl will
fail, reporting all errors. Failure and error reporting is disabled
for now, however, since much of the manual is still incomplete
wrt. header and standards annotations.
Note that the sorting order of the Summary has changed; summary.pl
respects the locale, like summary.awk did, but the use of LC_ALL=C is
introduced in the Makefile. Other notable deviations are improved
detection of the annotated elements' names, which are used for
sorting, and improved detection of the @node used to reference into
the manual. The most noticeable difference in the rendered Summary is
that entries may now contain multiple lines, one for each header and
standard combination.
summary.pl accepts a `--help' option, which details the expected
syntax of @standards. If errors are reported, the user is directed to
this feature for further information.
* manual/Makefile: Generate summary.texi with summary.pl.
Force use of the C locale. Update Perl dependency comment.
* manual/header.texi: Update reference to summary.awk.
* manual/macros.texi: Refer authors to `summary.pl --help'.
* manual/summary.awk: Remove file.
* manual/summary.pl: New file. Generate summary.texi, and
check for @standards-related syntax errors.
* manual/argp.texi: Convert header and standards @comments to
@standards.
* manual/arith.texi: Likewise.
* manual/charset.texi: Likewise.
* manual/conf.texi: Likewise.
* manual/creature.texi: Likewise.
* manual/crypt.texi: Likewise.
* manual/ctype.texi: Likewise.
* manual/debug.texi: Likewise.
* manual/errno.texi: Likewise.
* manual/filesys.texi: Likewise.
* manual/getopt.texi: Likewise.
* manual/job.texi: Likewise.
* manual/lang.texi: Likewise.
* manual/llio.texi: Likewise.
* manual/locale.texi: Likewise.
* manual/math.texi: Likewise.
* manual/memory.texi: Likewise.
* manual/message.texi: Likewise.
* manual/pattern.texi: Likewise.
* manual/pipe.texi: Likewise.
* manual/process.texi: Likewise.
* manual/resource.texi: Likewise.
* manual/search.texi: Likewise.
* manual/setjmp.texi: Likewise.
* manual/signal.texi: Likewise.
* manual/socket.texi: Likewise.
* manual/startup.texi: Likewise.
* manual/stdio.texi: Likewise.
* manual/string.texi: Likewise.
* manual/sysinfo.texi: Likewise.
* manual/syslog.texi: Likewise.
* manual/terminal.texi: Likewise.
* manual/threads.texi: Likewise.
* manual/time.texi: Likewise.
* manual/users.texi: Likewise.
Texinfo @vindex commands add entries to the Variable and Constant
Macro Index. Similarly, @items in @vtables are automatically indexed.
A number of @tables exist where all @items are @vindexed or all @items
are variables, but not indexed, suggesting an optimization by
converting such @tables to @vtables and dropping the @vindex.
Using a @vtable provides a context for processing @items whereby it
can be known the @items should have header and standards annotations.
This commit converts @tables of such @items to @vtables in order to
establish a framework for automated processing.
A pleasant consequence of these changes is that @items previously
lacking a @vindex are present in the Variable and Constant Macro Index
now. @vindex entries previously detected by summary.awk will still be
detected as @items with appropriate annotations.
The @vtable of the NSS databases is converted to a @table because 1)
those @items are not variables (and will no longer appear in the
Variable and Constant Macro Index) and 2) they do not need header and
standards annotations, so the incorrect context is fixed.
* manual/nss.texi: Change incorrect @vtable to @table.
* manual/arith.texi: Convert @tables of variables to @vtables
and remove unnecessary indexing.
* manual/filesys.texi: Likewise.
* manual/llio.texi: Likewise.
* manual/memory.texi: Likewise.
* manual/process.texi: Likewise.
* manual/resource.texi: Likewise.
* manual/search.texi: Likewise.
* manual/signal.texi: Likewise.
* manual/socket.texi: Likewise.
* manual/stdio.texi: Likewise.
* manual/sysinfo.texi: Likewise.
* manual/syslog.texi: Likewise.
* manual/terminal.texi: Likewise.
* manual/time.texi: Likewise.
* manual/users.texi: Likewise.
The manual incorrectly references sbrk as the method used to grow and
shrink heaps and the fact that M_TRIM_THRESHOLD and M_TOP_PAD control
that behavior. In reality, a heap may be grown or shrunk through
multiple methods depending on whether it is the main arena (in which
case sbrk is correct) or not (in which case, there are a number of
strategies including allocating an additional heap to grow an arena
and/or 'mprotect' a region to make it available for allocation).
Remove references to sbrk so that it covers the behavior more
accurately.
* manual/memory.texi (M_TOP_PAD): Remove reference to sbrk.
(M_TRIM_THRESHOLD): Likewise.
The M_ARENA_* mallopt parameters are in wide use in production to
control the number of arenas that a long lived process creates and
hence there is no point in stating that this interface is non-public.
Document this interface and remove the obsolete comment.
* manual/memory.texi (M_ARENA_TEST): Add documentation.
(M_ARENA_MAX): Likewise.
* malloc/malloc.c: Remove obsolete comment.
The mallopt parameters manual does not mention the environment
variables that can be used to set these parameters at program startup.
Mention those environment variables for completeness.
* manual/memory.texi: Add environment variable alternatives to
setting mallopt parameters.
__malloc_initialize_hook is interposed by application code, so
the usual approach to define a compatibility symbol does not work.
This commit adds a new mechanism based on #pragma GCC poison in
<stdc-predef.h>.
Previously, a thread M invoking fork would acquire locks in this order:
(M1) malloc arena locks (in the registered fork handler)
(M2) libio list lock
A thread F invoking flush (NULL) would acquire locks in this order:
(F1) libio list lock
(F2) individual _IO_FILE locks
A thread G running getdelim would use this order:
(G1) _IO_FILE lock
(G2) malloc arena lock
After executing (M1), (F1), (G1), none of the threads can make progress.
This commit changes the fork lock order to:
(M'1) libio list lock
(M'2) malloc arena locks
It explicitly encodes the lock order in the implementations of fork,
and does not rely on the registration order, thus avoiding the deadlock.
* manual/examples/strncat.c: Remove.
This example was misleading, as the code would have undefined
behavior if "hello" was longer than SIZE. Anyway, the manual
shouldn't encourage strncpy+strncat for this sort of thing.
* manual/string.texi (Copying Strings and Arrays): Split into
three sections Copying Strings and Arrays, Concatenating Strings,
and Truncating Strings, as this section was way too long. All
cross-referenced changed. Add advice about string-truncation
functions. Remove misleading strncat example.
ChangeLog:
2013-12-16 Will Newton <will.newton@linaro.org>
* manual/memory.texi (Malloc Examples): Mention aligned_alloc.
(Aligned Memory Blocks): Add documentation for aligned_alloc
and suggest it as an alternative to posix_memalign.
(Hooks for Malloc): Document __memalign_hook is also called
for aligned_alloc. (Summary of Malloc): Add summary for
aligned alloc. Document __memalign_hook is also called
for aligned_alloc.
The current documentation suggests using memalign and valloc which
are now considered obsolete, so suggest using posix_memalign instead.
Also document the possible error return and errno values for memalign
and posix_memalign and improve documentation of __memalign_hook.
ChangeLog:
2013-12-16 Will Newton <will.newton@linaro.org>
* manual/memory.texi (Malloc Examples): Clarify default
alignment documentation. Suggest posix_memalign rather
than memalign or valloc.
(Aligned Memory Blocks): Remove suggestion to use memalign
or valloc. Remove obsolete comment about BSD.
Document memalign errno values and mark the function obsolete.
Document posix_memalign returned error codes. Mark valloc
as obsolete. (Hooks for Malloc): __memalign_hook is also
called for posix_memalign and valloc.
(Summary of Malloc): Add posix_memalign to function summary.
__memalign_hook is also called for posix_memalign and valloc.
The register keyword doesn't add any information to the examples
and is not useful for modern compilers.
ChangeLog:
2013-11-06 Will Newton <will.newton@linaro.org>
* manual/memory.texi (Malloc Examples): Remove register
keyword from examples.
2004-08-09 Paul Eggert <eggert@cs.ucla.edu>
[BZ #315]
* manual/memory.texi (Obstacks Data Alignment): The default
alignment is not 4: it is enough to hold any type of data.
Problem reported by Benno in
<http://sources.redhat.com/ml/libc-alpha/2004-08/msg00055.html>.
2005-08-29 Thomas Schwinge <schwinge@nic-nac-project.de>
[BZ #1261]
* manual/memory.texi (Hooks for Malloc): Correct prototype of
my_init_hook and definition of my_free_hook.
