manual: Reorganize crypt.texi.
In preparation for a major revision of the documentation for crypt(_r), getentropy, and getrandom, reorganize crypt.texi. This patch does not change any text; it only deletes and moves text. The description of 'getpass' moves to terminal.texi, since all it does is read a password from the controlling terminal with echo disabled. The "Legal Problems" section of crypt.texi is dropped, and the introductory text is shifted down to the "Encrypting Passwords" section; the next patch will add some new introductory text. Also, it is no longer true that crypt.texi's top @node needs to have no pointers. That was a vestige of crypt/ being an add-on. (makeinfo itself doesn't need @node pointers anymore, but the scripts that assemble the libc manual's topmost node rely on each chapter-level node having them.)
This commit is contained in:
Zack Weinberg
Florian Weimer
parent
b10a0accee
commit
6ab902e4de
|
|
@ -1,3 +1,11 @@
|
|||
2018-06-29 Zack Weinberg <zackw@panix.com>
|
||||
|
||||
* manual/crypt.texi: Use a normal top-level @node declaration.
|
||||
Move most of the introductory text to the 'crypt' section.
|
||||
Move the example programs below the @deftypefun for 'crypt_r'.
|
||||
Move the 'getpass' section...
|
||||
* manual/terminal.texi: ...here.
|
||||
|
||||
2018-06-29 Zack Weinberg <zackw@panix.com>
|
||||
Florian Weimer <fweimer@redhat.com>
|
||||
|
||||
|
|
|
|||
|
|
@ -1,8 +1,14 @@
|
|||
@c This node must have no pointers.
|
||||
@node Cryptographic Functions
|
||||
@c @node Cryptographic Functions, Debugging Support, System Configuration, Top
|
||||
@chapter DES Encryption and Password Handling
|
||||
@c %MENU% DES encryption and password handling
|
||||
@node Cryptographic Functions, Debugging Support, System Configuration, Top
|
||||
@chapter Cryptographic Functions
|
||||
@c %MENU% Password storage and strongly unpredictable bytes
|
||||
|
||||
@menu
|
||||
* crypt:: A one-way function for passwords.
|
||||
* Unpredictable Bytes:: Randomness for cryptography purposes.
|
||||
@end menu
|
||||
|
||||
@node crypt
|
||||
@section Encrypting Passwords
|
||||
|
||||
On many systems, it is unnecessary to have any kind of user
|
||||
authentication; for instance, a workstation which is not connected to a
|
||||
|
|
@ -30,103 +36,6 @@ message-digest algorithm that is compatible with modern BSD systems,
|
|||
and the other based on the Data Encryption Standard (DES) that is
|
||||
compatible with Unix systems.
|
||||
|
||||
@menu
|
||||
* Legal Problems:: This software can get you locked up, or worse.
|
||||
* getpass:: Prompting the user for a password.
|
||||
* crypt:: A one-way function for passwords.
|
||||
* Unpredictable Bytes:: Randomness for cryptography purposes.
|
||||
@end menu
|
||||
|
||||
@node Legal Problems
|
||||
@section Legal Problems
|
||||
|
||||
Because of the continuously changing state of the law, it's not possible
|
||||
to provide a definitive survey of the laws affecting cryptography.
|
||||
Instead, this section warns you of some of the known trouble spots; this
|
||||
may help you when you try to find out what the laws of your country are.
|
||||
|
||||
Some countries require that you have a license to use, possess, or import
|
||||
cryptography. These countries are believed to include Byelorussia,
|
||||
Burma, India, Indonesia, Israel, Kazakhstan, Pakistan, Russia, and Saudi
|
||||
Arabia.
|
||||
|
||||
Some countries restrict the transmission of encrypted messages by radio;
|
||||
some telecommunications carriers restrict the transmission of encrypted
|
||||
messages over their network.
|
||||
|
||||
Many countries have some form of export control for encryption software.
|
||||
The Wassenaar Arrangement is a multilateral agreement between 33
|
||||
countries (Argentina, Australia, Austria, Belgium, Bulgaria, Canada, the
|
||||
Czech Republic, Denmark, Finland, France, Germany, Greece, Hungary,
|
||||
Ireland, Italy, Japan, Luxembourg, the Netherlands, New Zealand, Norway,
|
||||
Poland, Portugal, the Republic of Korea, Romania, the Russian
|
||||
Federation, the Slovak Republic, Spain, Sweden, Switzerland, Turkey,
|
||||
Ukraine, the United Kingdom and the United States) which restricts some
|
||||
kinds of encryption exports. Different countries apply the arrangement
|
||||
in different ways; some do not allow the exception for certain kinds of
|
||||
``public domain'' software (which would include this library), some
|
||||
only restrict the export of software in tangible form, and others impose
|
||||
significant additional restrictions.
|
||||
|
||||
The United States has additional rules. This software would generally
|
||||
be exportable under 15 CFR 740.13(e), which permits exports of
|
||||
``encryption source code'' which is ``publicly available'' and which is
|
||||
``not subject to an express agreement for the payment of a licensing fee or
|
||||
royalty for commercial production or sale of any product developed with
|
||||
the source code'' to most countries.
|
||||
|
||||
The rules in this area are continuously changing. If you know of any
|
||||
information in this manual that is out-of-date, please report it to
|
||||
the bug database. @xref{Reporting Bugs}.
|
||||
|
||||
@node getpass
|
||||
@section Reading Passwords
|
||||
|
||||
When reading in a password, it is desirable to avoid displaying it on
|
||||
the screen, to help keep it secret. The following function handles this
|
||||
in a convenient way.
|
||||
|
||||
@deftypefun {char *} getpass (const char *@var{prompt})
|
||||
@standards{BSD, unistd.h}
|
||||
@safety{@prelim{}@mtunsafe{@mtasuterm{}}@asunsafe{@ascuheap{} @asulock{} @asucorrupt{}}@acunsafe{@acuterm{} @aculock{} @acucorrupt{}}}
|
||||
@c This function will attempt to create a stream for terminal I/O, but
|
||||
@c will fallback to stdio/stderr. It attempts to change the terminal
|
||||
@c mode in a thread-unsafe way, write out the prompt, read the password,
|
||||
@c then restore the terminal mode. It has a cleanup to close the stream
|
||||
@c in case of (synchronous) cancellation, but not to restore the
|
||||
@c terminal mode.
|
||||
|
||||
@code{getpass} outputs @var{prompt}, then reads a string in from the
|
||||
terminal without echoing it. It tries to connect to the real terminal,
|
||||
@file{/dev/tty}, if possible, to encourage users not to put plaintext
|
||||
passwords in files; otherwise, it uses @code{stdin} and @code{stderr}.
|
||||
@code{getpass} also disables the INTR, QUIT, and SUSP characters on the
|
||||
terminal using the @code{ISIG} terminal attribute (@pxref{Local Modes}).
|
||||
The terminal is flushed before and after @code{getpass}, so that
|
||||
characters of a mistyped password are not accidentally visible.
|
||||
|
||||
In other C libraries, @code{getpass} may only return the first
|
||||
@code{PASS_MAX} bytes of a password. @Theglibc{} has no limit, so
|
||||
@code{PASS_MAX} is undefined.
|
||||
|
||||
The prototype for this function is in @file{unistd.h}. @code{PASS_MAX}
|
||||
would be defined in @file{limits.h}.
|
||||
@end deftypefun
|
||||
|
||||
This precise set of operations may not suit all possible situations. In
|
||||
this case, it is recommended that users write their own @code{getpass}
|
||||
substitute. For instance, a very simple substitute is as follows:
|
||||
|
||||
@smallexample
|
||||
@include mygetpass.c.texi
|
||||
@end smallexample
|
||||
|
||||
The substitute takes the same parameters as @code{getline}
|
||||
(@pxref{Line Input}); the user must print any prompt desired.
|
||||
|
||||
@node crypt
|
||||
@section Encrypting Passwords
|
||||
|
||||
@deftypefun {char *} crypt (const char *@var{key}, const char *@var{salt})
|
||||
@standards{BSD, crypt.h}
|
||||
@standards{SVID, crypt.h}
|
||||
|
|
@ -177,6 +86,23 @@ password against the result of a previous call to @code{crypt}, pass
|
|||
the result of the previous call as the @var{salt}.
|
||||
@end deftypefun
|
||||
|
||||
@deftypefun {char *} crypt_r (const char *@var{key}, const char *@var{salt}, {struct crypt_data *} @var{data})
|
||||
@standards{GNU, crypt.h}
|
||||
@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @asulock{} @ascuheap{} @ascudlopen{}}@acunsafe{@aculock{} @acsmem{}}}
|
||||
@c Compared with crypt, this function fixes the @mtasurace:crypt
|
||||
@c problem, but nothing else.
|
||||
|
||||
The @code{crypt_r} function does the same thing as @code{crypt}, but
|
||||
takes an extra parameter which includes space for its result (among
|
||||
other things), so it can be reentrant. @code{data@w{->}initialized} must be
|
||||
cleared to zero before the first time @code{crypt_r} is called.
|
||||
|
||||
The @code{crypt_r} function is a GNU extension.
|
||||
@end deftypefun
|
||||
|
||||
The @code{crypt} and @code{crypt_r} functions are prototyped in the
|
||||
header @file{crypt.h}.
|
||||
|
||||
The following short program is an example of how to use @code{crypt} the
|
||||
first time a password is entered. Note that the @var{salt} generation
|
||||
is just barely acceptable; in particular, it is not unique between
|
||||
|
|
@ -195,23 +121,6 @@ for a password and prints ``Access granted.'' if the user types
|
|||
@include testpass.c.texi
|
||||
@end smallexample
|
||||
|
||||
@deftypefun {char *} crypt_r (const char *@var{key}, const char *@var{salt}, {struct crypt_data *} @var{data})
|
||||
@standards{GNU, crypt.h}
|
||||
@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @asulock{} @ascuheap{} @ascudlopen{}}@acunsafe{@aculock{} @acsmem{}}}
|
||||
@c Compared with crypt, this function fixes the @mtasurace:crypt
|
||||
@c problem, but nothing else.
|
||||
|
||||
The @code{crypt_r} function does the same thing as @code{crypt}, but
|
||||
takes an extra parameter which includes space for its result (among
|
||||
other things), so it can be reentrant. @code{data@w{->}initialized} must be
|
||||
cleared to zero before the first time @code{crypt_r} is called.
|
||||
|
||||
The @code{crypt_r} function is a GNU extension.
|
||||
@end deftypefun
|
||||
|
||||
The @code{crypt} and @code{crypt_r} functions are prototyped in the
|
||||
header @file{crypt.h}.
|
||||
|
||||
@node Unpredictable Bytes
|
||||
@section Generating Unpredictable Bytes
|
||||
|
||||
|
|
|
|||
|
|
@ -24,6 +24,7 @@ descriptor is and how to open a file descriptor for a terminal device.
|
|||
* Line Control:: Sending break sequences, clearing
|
||||
terminal buffers @dots{}
|
||||
* Noncanon Example:: How to read single characters without echo.
|
||||
* getpass:: Prompting the user for a password.
|
||||
* Pseudo-Terminals:: How to open a pseudo-terminal.
|
||||
@end menu
|
||||
|
||||
|
|
@ -1871,6 +1872,50 @@ existing shells do not actually do this, so you may wish to establish
|
|||
handlers for job control signals that reset terminal modes. The above
|
||||
example does so.
|
||||
|
||||
@node getpass
|
||||
@section Reading Passwords
|
||||
|
||||
When reading in a password, it is desirable to avoid displaying it on
|
||||
the screen, to help keep it secret. The following function handles this
|
||||
in a convenient way.
|
||||
|
||||
@deftypefun {char *} getpass (const char *@var{prompt})
|
||||
@standards{BSD, unistd.h}
|
||||
@safety{@prelim{}@mtunsafe{@mtasuterm{}}@asunsafe{@ascuheap{} @asulock{} @asucorrupt{}}@acunsafe{@acuterm{} @aculock{} @acucorrupt{}}}
|
||||
@c This function will attempt to create a stream for terminal I/O, but
|
||||
@c will fallback to stdio/stderr. It attempts to change the terminal
|
||||
@c mode in a thread-unsafe way, write out the prompt, read the password,
|
||||
@c then restore the terminal mode. It has a cleanup to close the stream
|
||||
@c in case of (synchronous) cancellation, but not to restore the
|
||||
@c terminal mode.
|
||||
|
||||
@code{getpass} outputs @var{prompt}, then reads a string in from the
|
||||
terminal without echoing it. It tries to connect to the real terminal,
|
||||
@file{/dev/tty}, if possible, to encourage users not to put plaintext
|
||||
passwords in files; otherwise, it uses @code{stdin} and @code{stderr}.
|
||||
@code{getpass} also disables the INTR, QUIT, and SUSP characters on the
|
||||
terminal using the @code{ISIG} terminal attribute (@pxref{Local Modes}).
|
||||
The terminal is flushed before and after @code{getpass}, so that
|
||||
characters of a mistyped password are not accidentally visible.
|
||||
|
||||
In other C libraries, @code{getpass} may only return the first
|
||||
@code{PASS_MAX} bytes of a password. @Theglibc{} has no limit, so
|
||||
@code{PASS_MAX} is undefined.
|
||||
|
||||
The prototype for this function is in @file{unistd.h}. @code{PASS_MAX}
|
||||
would be defined in @file{limits.h}.
|
||||
@end deftypefun
|
||||
|
||||
This precise set of operations may not suit all possible situations. In
|
||||
this case, it is recommended that users write their own @code{getpass}
|
||||
substitute. For instance, a very simple substitute is as follows:
|
||||
|
||||
@smallexample
|
||||
@include mygetpass.c.texi
|
||||
@end smallexample
|
||||
|
||||
The substitute takes the same parameters as @code{getline}
|
||||
(@pxref{Line Input}); the user must print any prompt desired.
|
||||
|
||||
@node Pseudo-Terminals
|
||||
@section Pseudo-Terminals
|
||||
|
|
|
|||
Loading…
Reference in New Issue