Suggested change to luaossl manual...

[Paul Ducklin <pducklin@...>]

The luaossl manual includes this advice for the :sign() and  :verify() functions in the openssl.pkey module:

---cut here old---
pkey:sign(digest)
Sign data which has been consumed by the specified openssl. digest 'digest'. Digests and keys are not all interchangeable.
[. . .]
pkey:verify(signature,digest)
Verify the string 'signature' as signing the document consumed by openssl.digest 'digest'. See the :sign method for constraints on the format and type of the parameters.
---end---


I suggest editing this for clarity so it says:

---cut here new---
pkey:sign(digest)
Sign data which has been consumed by the specified openssl. digest 'digest'. Digests and keys are not all interchangeable.

Note: fold the the data that you want to sign into 'digest' by calling digest:update(), but do not call digest:final() before using pkey:sign(). (If you want to find the digest of the data you just signed, it is OK to call digest:final() *after* computing the signature.)
[. . .]
pkey:verify(signature,digest)
Verify the string 'signature' as signing the document consumed by openssl.digest 'digest'. See the :sign method for constraints on the format and type of the parameters.

Note: fold the data whose signature you want to verify into 'digest' by calling digest:update(), but do not call digest:final() before using pkey:verify(). (If you want to find the digest of the data you just verified, it is OK to call digest:final() *after* verifying the signature.)
---end---

FWIW, the digest:final() function can take a final bunch of data to fold into the hash in luaossl but not in the OpenSSL API).

The luaossl code at the moment means there is no way to do any sort of hash reset, so you can't sensibly call digest:update() after digest:final() or digest:final() after digest:final(). If you do, however, it appears to work but gives dangerously incorrect results.

I therefore suggest at least adding a note to say  "never call digest:final() a second time, and don't calle :update() after calling :final()" Or make the code throw an error if you try.

My 3c.