tweetnacl

Documentation

Overview

tweetnacl-go is a port of Dan Bernstein's "crypto library in a 100 tweets" code to the Go language. It is implemented as a wrapper around the original code to preserve the design and timing characteristics of the original implementation.

The Go wrapper has been kept as 'thin' as possible to avoid compromising the careful design and coding of the original TweetNaCl implementation. However, cryptography being what it is, the wrapper may have (entirely inadvertently) introduced non-obvious vulnerabilities (for instance.

http://tweetnacl.cr.yp.to

Index

• Constants
• Variables
• func CryptoBox(message, nonce, publicKey, secretKey []byte) ([]byte, error)
• func CryptoBoxAfterNM(message, nonce, key []byte) ([]byte, error)
• func CryptoBoxBeforeNM(publicKey, secretKey []byte) ([]byte, error)
• func CryptoBoxOpen(ciphertext, nonce, publicKey, secretKey []byte) ([]byte, error)
• func CryptoBoxOpenAfterNM(ciphertext, nonce, key []byte) ([]byte, error)
• func CryptoCoreHSalsa20(in, key, constant []byte) ([]byte, error)
• func CryptoCoreSalsa20(in, key, constant []byte) ([]byte, error)
• func CryptoHash(message []byte) ([]byte, error)
• func CryptoOneTimeAuth(message, key []byte) ([]byte, error)
• func CryptoOneTimeAuthVerify(authenticator, message, key []byte) (bool, error)
• func CryptoSecretBox(message, nonce, key []byte) ([]byte, error)
• func CryptoSecretBoxOpen(ciphertext, nonce, key []byte) ([]byte, error)
• func CryptoSign(message, key []byte) ([]byte, error)
• func CryptoSignOpen(signed, key []byte) ([]byte, error)
• func CryptoStream(length int, nonce, key []byte) ([]byte, error)
• func CryptoStreamSalsa20(length int, nonce, key []byte) ([]byte, error)
• func CryptoStreamSalsa20Xor(message, nonce, key []byte) ([]byte, error)
• func CryptoStreamXor(message, nonce, key []byte) ([]byte, error)
• func CryptoVerify16(x, y []byte) (bool, error)
• func CryptoVerify32(x, y []byte) (bool, error)
• func ScalarMult(n, p []byte) ([]byte, error)
• func ScalarMultBase(n []byte) ([]byte, error)
• type KeyPair
  • func CryptoBoxKeyPair() (*KeyPair, error)
  • func CryptoSignKeyPair() (*KeyPair, error)

Examples

• CryptoBox
• CryptoHash

Constants

const BOX_BEFORENMBYTES int = 32

The number of bytes in an initialised crypto_box_beforenm key buffer.

const BOX_BOXZEROBYTES int = 16

The number of zero padding bytes for a crypto_box ciphertext

const BOX_NONCEBYTES int = 24

The number of bytes for a crypto_box nonce.

const BOX_PUBLICKEYBYTES int = 32

The number of bytes in a crypto_box public key

const BOX_SECRETKEYBYTES int = 32

The number of bytes in a crypto_box secret key

const BOX_ZEROBYTES int = 32

The number of zero padding bytes for a crypto_box message

const HASHBLOCKS_BLOCKBYTES int = 128

The block size for the message for crypto_hashblocks.

const HASHBLOCKS_STATEBYTES int = 64

The size of the state byte array for crypto_hashblocks.

const HASH_BYTES int = 64

The number of bytes returned by CryptHash.

const HSALSA20_CONSTBYTES int = 16

The number of bytes in the constant for crypto_core_hsalsa20.

const HSALSA20_INPUTBYTES int = 16

The number of bytes in the shared secret for crypto_core_hsalsa20.

const HSALSA20_KEYBYTES int = 32

The number of bytes in the secret keyfor crypto_core_hsalsa20.

const HSALSA20_OUTPUTBYTES int = 32

The number of bytes in an HSALSA20 intermediate key.

const ONETIMEAUTH_BYTES int = 16

The number of bytes in the authenticator.

const ONETIMEAUTH_KEYBYTES int = 32

The number of bytes in the secret key used to generate the authenticator.

const SALSA20_CONSTBYTES int = 16

The number of bytes in the constant for crypto_core_salsa20.

const SALSA20_INPUTBYTES int = 16

The number of bytes in the shared secret for crypto_core_salsa20.

const SALSA20_KEYBYTES int = 32

The number of bytes in the secret key for crypto_core_salsa20.

const SALSA20_OUTPUTBYTES int = 64

The number of bytes in the calculated intermediate key.

const SCALARMULT_BYTES int = 32

The number of bytes in the group element component of scalar multiplication.

const SCALARMULT_SCALARBYTES int = 32

The number of bytes in the integer component of scalar multiplication.

const SECRETBOX_BOXZEROBYTES int = 16

The number of zero padding bytes for a crypto_secretbox ciphertext

const SECRETBOX_KEYBYTES int = 32

The number of bytes in the secret key used with crypto_secretbox and crypto_secretbox_open.

const SECRETBOX_NONCEBYTES int = 24

The number of bytes in the nonce used with crypto_secretbox and crypto_secretbox_open.

const SECRETBOX_ZEROBYTES int = 32

The number of zero padding bytes in the message for crypto_secretbox.

const SIGN_BYTES int = 64

The number of bytes added to a message for a signature.

const SIGN_PUBLICKEYBYTES int = 32

The number of bytes in a signing key pair public key.

const SIGN_SECRETKEYBYTES int = 64

The number of bytes in a signing key pair secret key.

const STREAM_KEYBYTES int = 32

The number of bytes in the secret key for crypto_stream.

const STREAM_NONCEBYTES int = 24

The number of bytes in the nonce for crypto_stream.

const STREAM_SALSA20_KEYBYTES int = 32

The number of bytes in the secret key for crypto_stream_salsa20.

const STREAM_SALSA20_NONCEBYTES int = 8

The number of bytes in the nonce for crypto_stream_salsa20.

const VERIFY16_BYTES int = 16

The number of bytes in a 'secret' for the crypto_verify_16 function.

const VERIFY32_BYTES int = 32

The number of bytes in a 'secret' for the crypto_verify_32 function.

Variables

var BOX_PADDING = []byte{
	0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
	0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
	0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
	0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00}

Constant zero-filled byte array used for padding messages

var SECRETBOX_PADDING = []byte{0x00, 0x00, 0x00, 0x00,
	0x00, 0x00, 0x00, 0x00,
	0x00, 0x00, 0x00, 0x00,
	0x00, 0x00, 0x00, 0x00,
	0x00, 0x00, 0x00, 0x00,
	0x00, 0x00, 0x00, 0x00,
	0x00, 0x00, 0x00, 0x00,
	0x00, 0x00, 0x00, 0x00}

Constant zero-filled byte array used for padding messages

Functions

func CryptoBox

func CryptoBox(message, nonce, publicKey, secretKey []byte) ([]byte, error)

Wrapper function for crypto_box.

Encrypts and authenticates the message using the secretKey, publicKey and nonce. The zero padding required by the crypto_box C API is added internally and should not be included in the supplied ciphertext. Likewise the zero padding that prefixes the ciphertext returned by the crypto_box C API is stripped from the returned ciphertext.

Ref. http://nacl.cr.yp.to/box.html

Example

message := []byte("Neque porro quisquam est qui dolorem ipsum quia dolor sit amet")
nonce := make([]byte, BOX_NONCEBYTES)
alice, _ := CryptoBoxKeyPair()
bob, _ := CryptoBoxKeyPair()

rand.Read(nonce)

ciphertext, err := CryptoBox(message, nonce, bob.PublicKey, alice.SecretKey)

if err != nil {
	fmt.Printf("%v", err)
	return
}

plaintext, err := CryptoBoxOpen(ciphertext, nonce, alice.PublicKey, bob.SecretKey)

if err != nil {
	fmt.Printf("%v", err)
	return
}

fmt.Printf("[%s]", string(plaintext))

Output:

[Neque porro quisquam est qui dolorem ipsum quia dolor sit amet]

func CryptoBoxAfterNM

func CryptoBoxAfterNM(message, nonce, key []byte) ([]byte, error)

Wrapper function for crypto_box_afternm.

Encrypts a message using the shared key generated by CryptoBoxBeforeNM. The zero padding required by the crypto_box C API is added internally and should not be included in the supplied message. Likewise the zero padding that prefixes the ciphertext returned by the crypto_box C API is stripped from the returned ciphertext.

Ref. http://nacl.cr.yp.to/box.html

func CryptoBoxBeforeNM

func CryptoBoxBeforeNM(publicKey, secretKey []byte) ([]byte, error)

Wrapper function for crypto_box_beforenm.

Calculates a 32 byte shared key for the hashed key-exchange described for curve 25519.

Applications that send several messages to the same receiver can gain speed by splitting CryptoBox into two steps, CryptoBoxBeforeNM and CryptoBoxAfterNM. Similarly, applications that receive several messages from the same sender can gain speed by splitting CryptoBoxOpen into two steps, CryptoBoxBeforeNM and CryptoBoxAfterNMOpen.

Ref. http://nacl.cr.yp.to/box.html

func CryptoBoxOpen

func CryptoBoxOpen(ciphertext, nonce, publicKey, secretKey []byte) ([]byte, error)

Wrapper function for crypto_box_open.

Verifies and decrypts the ciphertext using the secretKey, publicKey and nonce. The zero padding required by the crypto_box C API is added internally and should not be included in the supplied message. Likewise the zero padding that prefixes the plaintext returned by the crypto_box C API is stripped from the returned plaintext.

Ref. http://nacl.cr.yp.to/box.html

func CryptoBoxOpenAfterNM

func CryptoBoxOpenAfterNM(ciphertext, nonce, key []byte) ([]byte, error)

Wrapper function for crypto_box_open_afternm.

Verifies and decrypts a message using the shared key generated by CryptoBoxBeforeNM. The zero padding required by the crypto_box C API is added internally and should not be included in the supplied message. Likewise the zero padding that prefixes the plaintext returned by the crypto_box C API is stripped from the returned plaintext.

Ref. http://nacl.cr.yp.to/box.html

func CryptoCoreHSalsa20

func CryptoCoreHSalsa20(in, key, constant []byte) ([]byte, error)

Wrapper function for crypto_core_hsalsa20.

From the available documentation crypto_core_hsalsa20 apparently calculates an intermediate key (from a secret key and shared secret) for encrypting and authenticating packets.

in is a HSALSA20_INPUTBYTES byte array containing the shared secret. key is a HSALSA20_KEYBYTES byte array containing the secret key. constant is a HSALSA20_CONSTBYTES byte array containing an apparently arbitrary 'constant' (IV ?) to be used for the intermediate key calculation.

func CryptoCoreSalsa20

func CryptoCoreSalsa20(in, key, constant []byte) ([]byte, error)

Wrapper function for crypto_core_salsa20.

From the available documentation crypto_core_salsa20 apparently calculates an intermediate key (from a secret key and shared secret) for encrypting and authenticating packets.

func CryptoHash

func CryptoHash(message []byte) ([]byte, error)

Wrapper function for crypto_hash.

Calculates a SHA-512 hash of the message.

Ref. http://nacl.cr.yp.to/hash.html

Example

message := []byte("Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor")

hash, err := CryptoHash(message)

if err != nil {
	fmt.Printf("%v", err)
	return
}

fmt.Printf("%x", hash)

Output:

5dfaeb09829a546d8adcef4437957814b7b2f44a128600ab0e4f5322c6150cf5c33957f13055b9266e370c199bb764d4f38bb277b5f345e890d2e0bb3992c4dd

func CryptoOneTimeAuth

func CryptoOneTimeAuth(message, key []byte) ([]byte, error)

Wrapper function for crypto_onetimeauth.

Uses the supplied secret key to calculate an authenticator for the message.

Ref. http://nacl.cr.yp.to/onetimeauth.html

func CryptoOneTimeAuthVerify

func CryptoOneTimeAuthVerify(authenticator, message, key []byte) (bool, error)

Wrapper function for crypto_onetimeauth_verify.

Uses the supplied secret key to verify the authenticator for the message.

Ref. http://nacl.cr.yp.to/onetimeauth.html

func CryptoSecretBox

func CryptoSecretBox(message, nonce, key []byte) ([]byte, error)

Wrapper function for crypto_secretbox.

Encrypts and authenticates a message using the supplied secret key and nonce. The zero padding required by crypto_secretbox is added internally and should not be included in the supplied message. Likewise the zero padding that prefixes the ciphertext returned by the crypto_secretbox C API is stripped from the returned

ciphertext.

Ref. http://nacl.cr.yp.to/secretbox.html

func CryptoSecretBoxOpen

func CryptoSecretBoxOpen(ciphertext, nonce, key []byte) ([]byte, error)

Wrapper function for crypto_secretbox_open.

Verifies and decrypts the ciphertext using the supplied secret key and nonce. The The zero padding required by the crypto_secretbox C API is added internally and should not be included in the supplied ciphertext. Likewise the zero padding that prefixes the plaintext returned by the crypto_secretbox C API is stripped from the returned plaintext.

Ref. http://nacl.cr.yp.to/secretbox.html

func CryptoSign

func CryptoSign(message, key []byte) ([]byte, error)

Wrapper function for crypto_sign.

Signs a message using a secret signing key and returns the signed message. Be aware that this function internally allocates a buffer the same size as the signed message.

Ref. http://nacl.cr.yp.to/sign.html

func CryptoSignOpen

func CryptoSignOpen(signed, key []byte) ([]byte, error)

Wrapper function for crypto_sign_open.

Verifies a signed message against a public key. Be warned that this function reuses the 'signed' message to store the unsigned message i.e. use a copy of the signed message if retaining it is important.

Ref. http://nacl.cr.yp.to/sign.html

func CryptoStream

func CryptoStream(length int, nonce, key []byte) ([]byte, error)

Wrapper function for crypto_stream.

Generates a cipher stream of size 'length' as a function of the key and nonce.

Ref. http://nacl.cr.yp.to/stream.html

func CryptoStreamSalsa20

func CryptoStreamSalsa20(length int, nonce, key []byte) ([]byte, error)

Wrapper function for crypto_stream_salsa20.

Uses Salsa20 as the underlying cipher to produces a 'length' stream as a function of the key and nonce.

Ref. http://nacl.cr.yp.to/stream.html

func CryptoStreamSalsa20Xor

func CryptoStreamSalsa20Xor(message, nonce, key []byte) ([]byte, error)

Wrapper function for crypto_stream_salsa20_xor.

Encrypts a message using salsa20 as the underlying cipher. The returned ciphertext is the plaintext XOR with the output of the stream generated by crypto_stream_salsa20 with the supplied secret key and nonce.

Ref. http://nacl.cr.yp.to/stream.html

func CryptoStreamXor

func CryptoStreamXor(message, nonce, key []byte) ([]byte, error)

Wrapper function for crypto_stream_xor.

Encrypts a message using a secret key and a nonce. The returned ciphertext is the plaintext XOR with the output of the stream generated by crypto_stream with the secret key and nonce.

Ref. http://nacl.cr.yp.to/stream.html

func CryptoVerify16

func CryptoVerify16(x, y []byte) (bool, error)

Wrapper function for crypto_verify_16.

Compares two 'secrets' encoded as 16 byte arrays in a time independent of the content of the arrays.

Ref. http://nacl.cr.yp.to/verify.html

func CryptoVerify32

func CryptoVerify32(x, y []byte) (bool, error)

Wrapper function for crypto_verify_32.

Compares two 'secrets' encoded as 32 byte arrays in a time independent of the content of the arrays.

Ref. http://nacl.cr.yp.to/verify.html

func ScalarMult

func ScalarMult(n, p []byte) ([]byte, error)

Wrapper function for crypto_scalarmult.

Computes the scalar product of a group element p and an integer n.

Ref. http://nacl.cr.yp.to/scalarmult.html

func ScalarMultBase

func ScalarMultBase(n []byte) ([]byte, error)

Wrapper function for crypto_scalarmult_base.

Computes the scalar product of a standard group element and an integer <code>n</code>.

Ref. http://nacl.cr.yp.to/scalarmult.html

Types

type KeyPair

type KeyPair struct {
	PublicKey []byte
	SecretKey []byte
}

func CryptoBoxKeyPair

func CryptoBoxKeyPair() (*KeyPair, error)

Wrapper function for crypto_box_keypair.

Randomly generates a secret key and a corresponding public key. It guarantees that the secret key has BOX_PUBLICKEYBYTES bytes and that the public key has BOX_SECRETKEYBYTES bytes, returns a KeyPair initialised with a crypto_box public/private key pair.

Ref. http://nacl.cr.yp.to/box.html

func CryptoSignKeyPair

func CryptoSignKeyPair() (*KeyPair, error)

Wrapper function for crypto_sign_keypair.

Randomly generates a secret key and corresponding public key.

Ref. http://nacl.cr.yp.to/sign.html