Proposal for nacl.sign API change (next version)

[dchest]

I'd like to change the signature API sometime in the future to this:

nacl.sign(message, secretKey) -> signedMessage
nacl.sign.open(signedMessage, publicKey) -> message | null

(Maybe instead of null, return false when verification fails? null makes more sense to me in this case)

Basically, this is how signatures in NaCl/TweetNaCl work.

But since everyone likes to have signatures separate from messages ("detached signatures"), we will add the following new methods to get the behavior similar, but not identical, to what we currently have:

nacl.sign.detached(message, secretKey) -> signature
nacl.sign.detached.verify(message, signature, publicKey) -> true | false

Note that it's verify and not open, because it returns only true or false, not the "unsigned" message or false like nacl.sign.open.

This is inspired by libsodium.

Compatibility

This would require major version bump (to 1.0.0, argh) according to semver principles.

To deliberately break apps which upgraded to 1.0.0 without changing code, we can throw exception if nacl.sign.open is called with 3 arguments. We can do nothing with nacl.sign, though: instead of just signature it will return signed message. This isn't dangerous. I don't think there's enough users right now anyway to cause headaches :)

Comments?

[dchest]

According to semver spec point 4:

Major version zero (0.y.z) is for initial development. Anything may change at any time. The public
API should not be considered stable.

So it will probably be v0.10.0 instead of v1.0.0, yay.

[devi]

Can we improve nacl.sign.keyPair.fromSecretKey ?

Current implementation is a bit confusing to me.
Since it doesn't generate keypair, does it mean extracting public key from secret key ?

May be we can have something like crypto_sign_seed_keypair from libsodium.

[dchest]

@devi yes, it just extracts the public key, not generates it. I didn't name it "extract" because while in sign case we only copy it from the secret key, in nacl.box.keyPair.fromSecretKey we actually calculate it from the secret key using scalar multiplication.

Probably needs a better documentation rather than API change, but I'm open to new names.

[dchest]

As for crypto_sign_seed_keypair: I need to think about it.

On one hand, there's currently no way to do what this function does without copying half of the library, on the other hand, it complicates code (and makes diff from tweenacl.c not so pretty) for an uncommon use case (which can also be dangerous if you're not careful with producing proper seeds, e.g. from passwords with weak derivation function).

[devi]

It won't be necessary to change names.
I'm just thinking, it would be nice if we could generate public key like nacl.box.keyPair.fromSecretKey did.

[devi]

Internet connection is killing me. Didn't saw your comment regarding crypto_sign_seed_keypair.
That's exactly what I'm thinking.

[dchest]

@devi opened a new issue #37 for it.

[dchest]

PR #40 will be used for further discussions (if any), so closing this now.

[dchest]

Merged.