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

On Tue, Sep 24, 2013 at 1:11 AM, <postgresql(at)richardneill(dot)org> wrote:
> The following bug has been logged on the website:
>
> Bug reference: 8467
> Logged by: Richard Neill
> Email address: postgresql(at)richardneill(dot)org
> PostgreSQL version: 9.3.0
> Operating system: Documentation bug
> Description:
>
> 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:
>
>
> --------------------
> 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:
>
>
> --------------------
> 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.

> [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.

--
Magnus Hagander
Me: http://www.hagander.net/
Work: http://www.redpill-linpro.com/