Improve step crypto nacl docs.

Fixes smallstep/ca-component#105

command/crypto/nacl/auth.go

@@ -18,9 +18,28 @@ func authCommand() cli.Command {
 		Usage:     "authenticates a message using a secret key",
 		UsageText: "step crypto nacl auth <subcommand> [arguments] [global-flags] [subcommand-flags]",
 		Description: `**step crypto nacl auth** command group uses secret key cryptography to
-authenticate and verify messages using a secret key.
+authenticate and verify messages using a secret key. The implementation is based on NaCl
+crypto_auth functions.
 
-TODO
+NaCl crypto_auth function, viewed as a function of the message for a uniform
+random key, is designed to meet the standard notion of unforgeability. This
+means that an attacker cannot find authenticators for any messages not
+authenticated by the sender, even if the attacker has adaptively influenced the
+messages authenticated by the sender. For a formal definition see, e.g., Section
+2.4 of Bellare, Kilian, and Rogaway, "The security of the cipher block chaining
+message authentication code," Journal of Computer and System Sciences 61 (2000),
+362–399; http://www-cse.ucsd.edu/~mihir/papers/cbc.html.
+
+NaCl crypto_auth does not make any promises regarding "strong" unforgeability;
+perhaps one valid authenticator can be converted into another valid
+authenticator for the same message. NaCl auth also does not make any promises
+regarding "truncated unforgeability."
+
+NaCl crypto_auth is currently an implementation of HMAC-SHA-512-256, i.e., the
+first 256 bits of HMAC-SHA-512. HMAC-SHA-512-256 is conjectured to meet the
+standard notion of unforgeability.
+
+These commands are interoperable with NaCl: https://nacl.cr.yp.to/auth.html
 
 ## EXAMPLES
 
@@ -57,10 +76,10 @@ func authDigestCommand() cli.Command {
 		Action:    cli.ActionFunc(authDigestAction),
 		Usage:     "generates a 32-byte digest for a message",
 		UsageText: "**step crypto nacl auth digest** <key-file>",
-		Description: `**step crypto nacl auth digest** creates a digest to authenticate of a message
-using a secret key.
+		Description: `**step crypto nacl auth digest** creates a digest to authenticate the message
+coming from STDIN using the given secret key.
 
-TODO
+This command uses an implementation of the NaCl crypto_auth function.
 
 For examples, see **step help crypto nacl auth**.`,
 	}
@@ -72,10 +91,10 @@ func authVerifyCommand() cli.Command {
 		Action:    cli.ActionFunc(authVerifyAction),
 		Usage:     "checks digest is a valid for a message",
 		UsageText: "**step crypto nacl auth verify** <key-file> <digest>",
-		Description: `**step crypto nacl auth verify** verifies the digest of a message with a secret
-key.
+		Description: `**step crypto nacl auth verify** checks that the digest is a valid authenticator
+of the message coming from STDIN under the given secret key file.
 
-TODO
+This command uses an implementation of the NaCl crypto_auth_verify function.
 
 For examples, see **step help crypto nacl auth**.`,
 	}

command/crypto/nacl/box.go

@@ -18,8 +18,45 @@ func boxCommand() cli.Command {
 		Name:      "box",
 		Usage:     "authenticate and encrypt small messages using public-key cryptography",
 		UsageText: "step crypto nacl box <subcommand> [arguments] [global-flags] [subcommand-flags]",
-		Description: `**step crypto nacl box** command group uses public-key cryptography to
-encrypt, decrypt and authenticate messages.
+		Description: `**step crypto nacl box** command group uses public-key cryptography to encrypt,
+decrypt and authenticate messages. The implementation is based on NaCl
+crypto_box functions.
+
+NaCl crypto_box function is designed to meet the standard notions of
+privacy and third-party unforgeability for a public-key authenticated-encryption
+scheme using nonces. For formal definitions see, e.g., Jee Hea An,
+"Authenticated encryption in the public-key setting: security notions and
+analyses," https://eprint.iacr.org/2001/079. Distinct messages between the same
+{sender, receiver} set are required to have distinct nonces. For example, the
+lexicographically smaller public key can use nonce 1 for its first message to
+the other key, nonce 3 for its second message, nonce 5 for its third message,
+etc., while the lexicographically larger public key uses nonce 2 for its first
+message to the other key, nonce 4 for its second message, nonce 6 for its third
+message, etc. Nonces are long enough that randomly generated nonces have
+negligible risk of collision.
+
+There is no harm in having the same nonce for different messages if the {sender,
+receiver} sets are different. This is true even if the sets overlap. For
+example, a sender can use the same nonce for two different messages if the
+messages are sent to two different public keys.
+
+NaCl crypto_box is not meant to provide non-repudiation. On the contrary: they
+guarantee repudiability. A receiver can freely modify a boxed message, and
+therefore cannot convince third parties that this particular message came from
+the sender. The sender and receiver are nevertheless protected against forgeries
+by other parties. In the terminology of
+https://groups.google.com/group/sci.crypt/msg/ec5c18b23b11d82c, NaCl crypto_box
+uses "public-key authenticators" rather than "public-key signatures."
+
+Users who want public verifiability (or receiver-assisted public verifiability)
+should instead use signatures (or signcryption).
+
+NaCl crypto_box is curve25519xsalsa20poly1305, a particular combination of
+Curve25519, Salsa20, and Poly1305 specified in "Cryptography in NaCl". This
+function is conjectured to meet the standard notions of privacy and third-party
+unforgeability.
+
+These commands are interoperable with NaCl: https://nacl.cr.yp.to/box.html
 
 ## EXAMPLES
 
@@ -62,6 +99,8 @@ func boxKeypairCommand() cli.Command {
 		Description: `Generates a new public/private keypair suitable for use with seal and open.
 The private key is encrypted using a password in a nacl secretbox.
 
+This command uses an implementation of the NaCl crypto_box_keypair function.
+
 For examples, see **step help crypto nacl box**.
 
 ## POSITIONAL ARGUMENTS
@@ -85,6 +124,8 @@ func boxOpenCommand() cli.Command {
 PRIV_KEY is encrypted you will be prompted for the password. The sealed box is
 read from STDIN and the decrypted plaintext is written to STDOUT.
 
+This command uses an implementation of the NaCl crypto_box_open function.
+
 For examples, see **step help crypto nacl box**.
 
 ## POSITIONAL ARGUMENTS
@@ -117,6 +158,10 @@ func boxSealCommand() cli.Command {
 ciphertext to STDOUT. The "box" can be open by the a recipient who has access
 to the private key corresponding to <recipient-pub-key>.
 
+This command uses an implementation of the NaCl crypto_box function.
+
+For examples, see **step help crypto nacl box**.
+
 ## POSITIONAL ARGUMENTS
 
 <nonce>

command/crypto/nacl/nacl.go

@@ -31,10 +31,7 @@ languages. For internal use cases where compatibility with open standards like
 JWT are not an issue, NaCl should be your default choice for cryptographic
 needs.
 
-TODO: Are we NaCl or libsodium compliant? Maybe have a flag at this level to
-decide? The golang default is libsodium compatible. I think all that changes
-are the defaults for the 'box' operations -- NaCl doesn't support Curve25519
-yet.`,
+For more information on NaCl visit https://nacl.cr.yp.to`,
 		Subcommands: cli.Commands{
 			authCommand(),
 			boxCommand(),

command/crypto/nacl/secretbox.go

@@ -18,9 +18,26 @@ func secretboxCommand() cli.Command {
 		Usage:     "encrypts and authenticates small messages using secret-key cryptography",
 		UsageText: "step crypto nacl secretbox <subcommand> [arguments] [global-flags] [subcommand-flags]",
 		Description: `**step crypto nacl secretbox** command group uses secret-key cryptography to
-encrypt, decrypt and authenticate messages.
+encrypt, decrypt and authenticate messages. The implementation is based on NaCl
+crypto_secretbox functions.
 
-TODO
+NaCl crypto_secretbox is designed to meet the standard notions of privacy and
+authenticity for a secret-key authenticated-encryption scheme using nonces. For
+formal definitions see, e.g., Bellare and Namprempre, "Authenticated encryption:
+relations among notions and analysis of the generic composition paradigm,"
+Lecture Notes in Computer Science 1976 (2000), 531–545,
+http://www-cse.ucsd.edu/~mihir/papers/oem.html. Note that the length is not
+hidden. Note also that it is the caller's responsibility to ensure the
+uniqueness of nonces—for example, by using nonce 1 for the first message, nonce
+2 for the second message, etc. Nonces are long enough that randomly generated
+nonces have negligible risk of collision.
+
+NaCl crypto_secretbox is crypto_secretbox_xsalsa20poly1305, a particular
+combination of Salsa20 and Poly1305 specified in "Cryptography in NaCl". This
+function is conjectured to meet the standard notions of privacy and
+authenticity.
+
+These commands are interoperable with NaCl: https://nacl.cr.yp.to/secretbox.html
 
 ## EXAMPLES
 
@@ -57,7 +74,7 @@ func secretboxOpenCommand() cli.Command {
 		Description: `**step crypto nacl secretbox open** verifies and decrypts a ciphertext using a
 secret key and a nonce.
 
-TODO
+This command uses an implementation of the NaCl crypto_secretbox_open function.
 
 For examples, see **step help crypto nacl secretbox**.`,
 		Flags: []cli.Flag{
@@ -79,7 +96,7 @@ func secretboxSealCommand() cli.Command {
 		Description: `**step crypto nacl secretbox seal** encrypts and authenticates a message using
 a secret key and a nonce.
 
-TODO
+This command uses an implementation of the NaCl crypto_secretbox function.
 
 For examples, see **step help crypto nacl secretbox**.`,
 		Flags: []cli.Flag{

command/crypto/nacl/sign.go

@@ -18,11 +18,18 @@ func signCommand() cli.Command {
 		Name:      "sign",
 		Usage:     "signs small messages using public-key cryptography",
 		UsageText: "step crypto nacl sign <subcommand> [arguments] [global-flags] [subcommand-flags]",
-		Description: `
-**step crypto nacl sign** command group uses public-key cryptography to sign
-and verify messages.
+		Description: `**step crypto nacl sign** command group uses public-key cryptography to sign and
+verify messages. The implementation is based on NaCl crypto_sign functions.
 
-TODO
+NaCl crypto_sign function is designed to meet the standard notion of
+unforgeability for a public-key signature scheme under chosen-message attacks.
+
+NaCl crypto_sign is crypto_sign_edwards25519sha512batch, a particular
+combination of Curve25519 in Edwards form and SHA-512 into a signature scheme
+suitable for high-speed batch verification. This function is conjectured to meet
+the standard notion of unforgeability under chosen-message attacks.
+
+These commands are interoperable with NaCl: https://nacl.cr.yp.to/sign.html
 
 ## EXAMPLES
 
@@ -64,6 +71,8 @@ func signKeypairCommand() cli.Command {
 		Description: `**step crypto nacl sign keypair** generates a secret key and a corresponding
 public key valid for verifying and signing messages.
 
+This command uses an implementation of the NaCl crypto_sign_keypair function.
+
 For examples, see **step help crypto nacl sign**.`,
 	}
 }
@@ -77,6 +86,8 @@ func signOpenCommand() cli.Command {
 		Description: `**step crypto nacl sign open** verifies the signature of a message using the
 signer's public key.
 
+This command uses an implementation of the NaCl crypto_sign_open function.
+
 For examples, see **step help crypto nacl sign**.`,
 		Flags: []cli.Flag{
 			cli.BoolFlag{
@@ -93,9 +104,11 @@ func signSignCommand() cli.Command {
 		Action:    cli.ActionFunc(signSignAction),
 		Usage:     "signs a message using Ed25519",
 		UsageText: "**step crypto nacl sign sign** <priv-file>",
-		Description: `**step crypto nacl sign keypair** signs a message m using the signer's private
+		Description: `**step crypto nacl sign sign** signs a message m using the signer's private
 key.
 
+This command uses an implementation of the NaCl crypto_sign function.
+
 For examples, see **step help crypto nacl sign**.`,
 		Flags: []cli.Flag{
 			cli.BoolFlag{