Re: [MTASCsft PATCH 06/??] MT-, AS- and AC-Safety docs: manual/crypt.texi

["Carlos O'Donell" <carlos at redhat dot com>]

On 01/23/2014 10:14 AM, Alexandre Oliva wrote:
> The oddity here is that setkey_r and encrypt_r are documented together,
> with @deftypefun and @deftypefunx, and introducing a @safety note
> between them broke something (I don't recall exactly what; it could be
> just my report script, but I could cause some formatting problems).
> This is the only case in which two significantly different functions are
> documented together, but fortunately their safety properties were the
> same, so I just commented out the first @safety line.  How's that?
 
That's fine. They should really be two entries there, but that's another bug.

OK to checkin.
 
> for ChangeLog
> 
> 	* manual/crypt.texi: Document MTASC-safety properties.
> ---
>  manual/crypt.texi |   30 ++++++++++++++++++++++++++++++
>  1 file changed, 30 insertions(+)
> 
> diff --git a/manual/crypt.texi b/manual/crypt.texi
> index 9c65b95..fd007cf 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
> 
>