From 89a3701464bb74b6341e2ffaaa26a4bbc9bad0d7 Mon Sep 17 00:00:00 2001 From: Mariano Cano Date: Wed, 31 Oct 2018 14:03:54 -0700 Subject: [PATCH] Improve step crypto nacl docs. Fixes smallstep/ca-component#105 --- command/crypto/nacl/auth.go | 35 +++++++++++++++++------ command/crypto/nacl/box.go | 49 ++++++++++++++++++++++++++++++-- command/crypto/nacl/nacl.go | 5 +--- command/crypto/nacl/secretbox.go | 25 +++++++++++++--- command/crypto/nacl/sign.go | 23 +++++++++++---- 5 files changed, 114 insertions(+), 23 deletions(-) diff --git a/command/crypto/nacl/auth.go b/command/crypto/nacl/auth.go index 07222d34..d42ac59a 100644 --- a/command/crypto/nacl/auth.go +++ b/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 [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** ", - 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** ", - 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**.`, } diff --git a/command/crypto/nacl/box.go b/command/crypto/nacl/box.go index 2676c18d..9a08ab55 100644 --- a/command/crypto/nacl/box.go +++ b/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 [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 . +This command uses an implementation of the NaCl crypto_box function. + +For examples, see **step help crypto nacl box**. + ## POSITIONAL ARGUMENTS diff --git a/command/crypto/nacl/nacl.go b/command/crypto/nacl/nacl.go index 127a5f72..dfcc886f 100644 --- a/command/crypto/nacl/nacl.go +++ b/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(), diff --git a/command/crypto/nacl/secretbox.go b/command/crypto/nacl/secretbox.go index 09305f96..1a629dfb 100644 --- a/command/crypto/nacl/secretbox.go +++ b/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 [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{ diff --git a/command/crypto/nacl/sign.go b/command/crypto/nacl/sign.go index 118019dc..03866df2 100644 --- a/command/crypto/nacl/sign.go +++ b/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 [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** ", - 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{