Re: BUG #8467: Slightly confusing pgcrypto example in docs

On Tue, Sep 24, 2013 at 11:20:55PM +0100, Richard Neill wrote:
> I'm sorry about that: I think I need to correct my proposed
> correction!  I think I've been writing too much C recently, and so I
> foolishly mis-read that as returning pswhash, rather than returning
> the truth of the comparison.
>
> What I meant to write, for clarity, was:
>
> SELECT (pswhash = crypt('entered password', pswhash)) AS pswmatch FROM ... ;
>
> which would make it obvious that we're returning the boolean named pswmatch.
>
> >
> >>[Also, should the default example perhaps use gen_salt('bf'), as opposed to
> >>gen_salt('md5') ?]
> >
> >This, however, might be a good idea. People should of course always
> >read the documentation, but having the examples including the "best
> >practice" would probably be a good idea.
>
> Incidentally, there are 2 other things that confused me in this section.
>
> 1. Table F-18. Supported algorithms for crypt()  has a column
> labelled "max password length".  It would perhaps also be useful to
> know the size of column needed to store the crypted password (my
> original crypt using md5 easily fits in a varchar(70), whereas using
> bf needs the column to be varchar(100).)
>
>
> 2. Table F-20. Hash algorithm speeds
>
> What's the difference here between "crypt-md5" and "md5" ?
>
> If I've rightly read this, the algorithm named "md5" in the crypt()
> documentation is named "crypt-md5" here, whereas Table F20's "md5"
> algorithm seems to refer to something else - probably the "normal"
> version of md5.
>
> If so, it would be clearer to write that the last 2 lines ("md5" and
> "sha1") are for comparison only, and refer to the speed of doing an
> ordinary md5/sha1 sum, rather than the md5-variant of crypt().
>
>
> Anyway, thanks again for your help - Postgres is a wonderful system,
> which I've found to be repeatedly useful.

Based on your report, I have developed the attached doc patch which
clarifies when MD5 hash is being referenced, and when MD5 crypt is.  I
have also added your other suggestions.

--
  Bruce Momjian  <bruce@momjian.us>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

  + It's impossible for everything to be true. +