From patchwork Mon Jun 25 13:43:47 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Florian Weimer X-Patchwork-Id: 28013 Received: (qmail 105717 invoked by alias); 25 Jun 2018 13:43:52 -0000 Mailing-List: contact libc-alpha-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: libc-alpha-owner@sourceware.org Delivered-To: mailing list libc-alpha@sourceware.org Received: (qmail 105480 invoked by uid 89); 25 Jun 2018 13:43:51 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-23.2 required=5.0 tests=BAYES_50, GIT_PATCH_0, GIT_PATCH_1, GIT_PATCH_2, GIT_PATCH_3, KAM_LAZY_DOMAIN_SECURITY, SPF_HELO_PASS autolearn=ham version=3.3.2 spammy=indonesia, Indonesia, ireland, republic X-HELO: mx1.redhat.com Date: Mon, 25 Jun 2018 15:43:47 +0200 To: libc-alpha@sourceware.org Subject: [PATCH] manual: Reorganize crypt.texi. User-Agent: Heirloom mailx 12.5 7/5/10 MIME-Version: 1.0 Message-Id: <20180625134347.33A3D43994575@oldenburg.str.redhat.com> From: fweimer@redhat.com (Florian Weimer) From: Zack Weinberg 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.) * 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-25 Zack Weinberg * 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. diff --git a/manual/crypt.texi b/manual/crypt.texi index 6bbe2bfdc5..0f04ee9899 100644 --- a/manual/crypt.texi +++ b/manual/crypt.texi @@ -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,24 +86,6 @@ password against the result of a previous call to @code{crypt}, pass the result of the previous call as the @var{salt}. @end deftypefun -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 -machines, and in many applications it would not be acceptable to let an -attacker know what time the user's password was last set. - -@smallexample -@include genpass.c.texi -@end smallexample - -The next program shows how to verify a password. It prompts the user -for a password and prints ``Access granted.'' if the user types -@code{GNU libc manual}. - -@smallexample -@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{}}} @@ -212,6 +103,24 @@ The @code{crypt_r} function is a GNU extension. 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 +machines, and in many applications it would not be acceptable to let an +attacker know what time the user's password was last set. + +@smallexample +@include genpass.c.texi +@end smallexample + +The next program shows how to verify a password. It prompts the user +for a password and prints ``Access granted.'' if the user types +@code{GNU libc manual}. + +@smallexample +@include testpass.c.texi +@end smallexample + @node Unpredictable Bytes @section Generating Unpredictable Bytes diff --git a/manual/terminal.texi b/manual/terminal.texi index 4aace48b14..0b275fc002 100644 --- a/manual/terminal.texi +++ b/manual/terminal.texi @@ -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