aboutsummaryrefslogtreecommitdiff
path: root/manual
diff options
context:
space:
mode:
authorAlexandre Oliva <aoliva@redhat.com>2014-01-29 05:27:54 -0200
committerAlexandre Oliva <aoliva@redhat.com>2014-01-29 05:27:54 -0200
commit7616763710afe030ebf5268412cf689cb8e18685 (patch)
tree0b088e97df6a7b1bed73178c6532a76a9fe37343 /manual
parente567f2a0b4ca0350e3877e4199820dffc634d983 (diff)
downloadglibc-7616763710afe030ebf5268412cf689cb8e18685.tar
glibc-7616763710afe030ebf5268412cf689cb8e18685.tar.gz
glibc-7616763710afe030ebf5268412cf689cb8e18685.tar.bz2
glibc-7616763710afe030ebf5268412cf689cb8e18685.zip
* manual/crypt.texi: Document MTASC-safety properties.
Diffstat (limited to 'manual')
-rw-r--r--manual/crypt.texi30
1 files changed, 30 insertions, 0 deletions
diff --git a/manual/crypt.texi b/manual/crypt.texi
index 9c65b9535e..fd007cfa66 100644
--- a/manual/crypt.texi
+++ b/manual/crypt.texi
@@ -99,6 +99,13 @@ in a convenient way.
@comment unistd.h
@comment BSD
@deftypefun {char *} getpass (const char *@var{prompt})
+@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,
@@ -134,6 +141,13 @@ The substitute takes the same parameters as @code{getline}
@comment crypt.h
@comment BSD, SVID
@deftypefun {char *} crypt (const char *@var{key}, const char *@var{salt})
+@safety{@prelim{}@mtunsafe{@mtasurace{:crypt}}@asunsafe{@asucorrupt{} @asulock{} @ascuheap{} @ascudlopen{}}@acunsafe{@aculock{} @acsmem{}}}
+@c Besides the obvious problem of returning a pointer into static
+@c storage, the DES initializer takes an internal lock with the usual
+@c set of problems for AS- and AC-Safety. The FIPS mode checker and the
+@c NSS implementations of may leak file descriptors if canceled. The
+@c The MD5, SHA256 and SHA512 implementations will malloc on long keys,
+@c and NSS relies on dlopening, which brings about another can of worms.
The @code{crypt} function takes a password, @var{key}, as a string, and
a @var{salt} character array which is described below, and returns a
@@ -195,6 +209,9 @@ for a password and prints ``Access granted.'' if the user types
@comment crypt.h
@comment GNU
@deftypefun {char *} crypt_r (const char *@var{key}, const char *@var{salt}, {struct crypt_data *} @var{data})
+@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
@@ -241,6 +258,11 @@ specifies the unused bits.
@comment crypt.h
@comment BSD, SVID
@deftypefun void setkey (const char *@var{key})
+@safety{@prelim{}@mtunsafe{@mtasurace{:crypt}}@asunsafe{@asucorrupt{} @asulock{}}@acunsafe{@aculock{}}}
+@c The static buffer stores the key, making it fundamentally
+@c thread-unsafe. The locking issues are only in the initialization
+@c path; cancelling the initialization will leave the lock held, it
+@c would otherwise repeat the initialization on the next call.
The @code{setkey} function sets an internal data structure to be an
expanded form of @var{key}. @var{key} is specified as an array of 64
@@ -252,6 +274,8 @@ parity.
@comment crypt.h
@comment BSD, SVID
@deftypefun void encrypt (char *@var{block}, int @var{edflag})
+@safety{@prelim{}@mtunsafe{@mtasurace{:crypt}}@asunsafe{@asucorrupt{} @asulock{}}@acunsafe{@aculock{}}}
+@c Same issues as setkey.
The @code{encrypt} function encrypts @var{block} if
@var{edflag} is 0, otherwise it decrypts @var{block}, using a key
@@ -265,9 +289,11 @@ stored in a @code{char}, but there are no parity bits in @var{block}.
@comment crypt.h
@comment GNU
@deftypefun void setkey_r (const char *@var{key}, {struct crypt_data *} @var{data})
+@c @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @asulock{}}@acunsafe{@aculock{}}}
@comment crypt.h
@comment GNU
@deftypefunx void encrypt_r (char *@var{block}, int @var{edflag}, {struct crypt_data *} @var{data})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{} @asulock{}}@acunsafe{@aculock{}}}
These are reentrant versions of @code{setkey} and @code{encrypt}. The
only difference is the extra parameter, which stores the expanded
@@ -282,6 +308,7 @@ defined in @file{crypt.h}.
@comment rpc/des_crypt.h
@comment SUNRPC
@deftypefun int ecb_crypt (char *@var{key}, char *@var{blocks}, unsigned @var{len}, unsigned @var{mode})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The function @code{ecb_crypt} encrypts or decrypts one or more blocks
using DES. Each block is encrypted independently.
@@ -356,6 +383,7 @@ is not a multiple of 8 or @var{len} is larger than @code{DES_MAXDATA}.
@comment rpc/des_crypt.h
@comment SUNRPC
@deftypefun int DES_FAILED (int @var{err})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This macro returns 1 if @var{err} is a `success' result code from
@code{ecb_crypt} or @code{cbc_crypt}, and 0 otherwise.
@end deftypefun
@@ -363,6 +391,7 @@ This macro returns 1 if @var{err} is a `success' result code from
@comment rpc/des_crypt.h
@comment SUNRPC
@deftypefun int cbc_crypt (char *@var{key}, char *@var{blocks}, unsigned @var{len}, unsigned @var{mode}, char *@var{ivec})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The function @code{cbc_crypt} encrypts or decrypts one or more blocks
using DES in Cipher Block Chaining mode.
@@ -389,6 +418,7 @@ Otherwise, all the parameters are similar to those for @code{ecb_crypt}.
@comment rpc/des_crypt.h
@comment SUNRPC
@deftypefun void des_setparity (char *@var{key})
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The function @code{des_setparity} changes the 64-bit @var{key}, stored
packed in 8-bit bytes, to have odd parity by altering the low bits of