Re: BUG #8467: Slightly confusing pgcrypto example in docs - Mailing list pgsql-bugs

Dear Magnus,

Thanks for your reply.

On 24/09/13 18:31, Magnus Hagander wrote:
>> The following bug has been logged on the website:
>>
>> Bug reference:      8467
>>
>> The documentation for pgcrypto:
>> http://www.postgresql.org/docs/current/static/pgcrypto.html
>> (and indeed all versions from 8.3-9.3)
>> contains the following:
>
>> -------[ ONE] -------------
>> Example of authentication:
>> SELECT pswhash = crypt('entered password', pswhash) FROM ... ;
  > This returns true if the entered password is correct.
>> --------------------
>>
>> I found this confusing, because it's  using the same name, "pswhash" in 2
>> places, one of which is a boolean. It would be, imho, clearer to write the
>> example query as:
>>
>> --------[ TWO ]------------
>> SELECT is_authenticated = crypt('entered password', pswhash) FROM ... ;
>> --------------------
>
> That would render the example incorrect. crypt(pwd, hash) returns the
> hash. Not a boolean. This hash needs to be compared to the stored one,
> as is explained in the instructions above the example. It's the whole
> expression, including the "pswhash = " that returns boolean.

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.


Best wishes,

Richard