msg

README

MSG

An experimental crytographic library for Go.

Named after Monosodium Glutamate, the MSG encryption library is written in Go and uses AES256-GCM and NaCl to facilitate secure data sharing between multiple parties without need for out of band secret key or passphrase transmission.

NaCl's simplicity and security come at a price. Multiple party decryption of a single ciphertext is not possible without shared keys. Instead, new cipher text must be created for each individual with which a user intends to communicate. MSG addresses this by using AES-256-GCM (Galois Counter Mode) to secure the initial message and then encrypting the secret key used by AES with NaCl. The final ciphertext is the concatenation of the AES-256-GCM cipher text with fixed size repeating blocks of NaCl ciphertext containing the key necessary to decrypt the original message.

Encrypt

Signature: ( plainText []byte, authorizedPubKeys []*[32]byte, selfPubKey, selfPrivKey *[32]byte)

Returns: []byte

The passed plainText is encrypted with AES256-GCM using a randomly generated 32 byte key and a unique salt. That key is then encrypted with each of the NaCl public keys in the authorizedPubKeys array.

The returned byte array is assembled like so:

gcmNonce(12 bytes) cipherTextLength(10 bytes) cipherText(? bytes) pubKeyOfSecretCreator(32 bytes)

The remainder of the blob is made up of repeating 92 byte chunks containing the NaCl encrypted AES256-GCM key prefixed with the fingerprint of the public key used for encryption and a unique nonce:

usersPubKeyFingerprint(20 bytes) NaClNonce(24 bytes) NaClSecret(48 bytes)

Decrypt

Signature: ( blob []byte, selfPubKey, selfPrivKey *[32]byte )

Returns: []byte, error

The decrypter uses it's knowledge of the encrypted blob and breaks it appart into pieces. It loops through the 92 byte chunks at the end until it finds a key fingerprint that matches the passed in selfPubKey. It then decryptes the NaCl cipher text, and uses that value as the key to decrypt the large AES256-GCM encrypted cipher text.

It returns either the plain text in a byte array or a decrytion error.

Keys

Several helper methods are provided for reading and writing keys for NaCl and AES256-GCM. In order to use the encryption and decryption functionality you must have a public/private NaCl keypair and the public keys of those you wish to encrypt information for.

Entropy

Helper methods are provided to generate cryptographically secure salts for use with NaCl and AES256-GCM.

Contributing

If you think this is an interesting idea and want to contribute, please do!

Documentation

Overview

*

• decrypter
• The decrypter chunks out the cipher text into its relevant parts per the encryption
• implementation and attempts to decrypt the secrets it contains. *
• Once the parts of the cipherText have been identified, the decrypter loops through the
• repeating perUserPayload portion until it finds the fingerprint of the current user's public
• key in the first 20 bytes of the block. When found, it attempts to decrypt the payload using
• NaCl, thus learning the key necessary to decrypt the main cipher text.

*

• encrypter *
• The encrypter utilizes two different forms of authenticated encryption to protect data:
• AES256-GCM and NaCl *
• TWO TYPES OF ENCRYPTION!?
• Yes, but they are NOT used on top of one another. Each technology is used independently and
• their outputs are combined into a large cipher text blob which provides secure data sharing
• among many individuals without requiring out of band passphrase sharing, something
• neither encryption technology is able of achieving on its own. *
• WHAT IS GCM USED FOR?
• GCM is used to secure the actual plain text which is passed into the Encrypt method.
• The required 32 byte AES key is generated randomly, as is the 12 byte nonce. *
• WHAT IS NaCl USED FOR?
• NaCl is used to allow the "owner" of the secret data to secure the random 32 byte key used
• in AES256-GCM by encrypting it with each authorized user's public key. *
• HOW IS THE CIPHER TEXT BLOB CONSTRUCTED?
• The beginning of the cipher text blob contains all of the GCM encryption information along with
• the public key of the secret creator: *
• gcmNonce(12 bytes) cipherTextLength(10 bytes) cipherText(? bytes) pubKeyOfSecretCreator(32 bytes) *
• The remainder of the blob is made up of repeating 92 byte chunks containing the
• NaCl encrypted AES256-GCM key prefixed with the fingerprint of the public key used for encryption
• and a unique nonce: *
• usersPubKeyFingerprint(20 bytes) NaClNonce(24 bytes) NaClSecret(48 bytes)

*

• entropy
• The entropy module provides a simple wrapper around the rand reader and ReadFull
• to ensure the returned buffer is completely filled with cryptographically sound random
• data. Helper methods are also provided to cast byte array data to proper nonce types
• so it can be used in the necessary cryptographic method calls.

*

• keys
• This module handles all the key generation logic for NaCl and AES.
• It passes off reading from the rand reader to the entropy module to
• limit code duplication. It also provides helper methods to turn byte
• array data into the proper key types so they can be used in the crypto
• methods where they are needed, and read and write key files to disk.

Index

• Constants
• func BytesToNACLKey(bytes []byte) *[32]byte
• func BytesToNACLNonce(bytes []byte) *[24]byte
• func Decrypt(blob []byte, selfPubKey, selfPrivKey *[32]byte) (plainText []byte, err error)
• func Encrypt(plainText []byte, authorizedPubKeys []*[32]byte, ...) []byte
• func GenAES256Key() []byte
• func GenerateGCMNonce() []byte
• func GenerateNACLKeyPair() (pubKey, privKey *[32]byte)
• func GenerateNACLNonce() *[24]byte
• func GetNACLKeyFingerprint(key *[32]byte) []byte
• func NACLKeyFromFile(filePath string) *[32]byte
• func ReadFromRand(numBytes int) []byte
• func ReadNACLKeyFile(keyFilePath string) string
• func StringToNACLKey(encodedKeyString string) *[32]byte
• func WriteNACLKeyFile(keyFilePath string, key *[32]byte, keyComment string, perms os.FileMode)

Constants

const CTLENGTH_BLOCK_END = CTLENGTH_BLOCK_START + CTLENGTH_BLOCK_SIZE

const CTLENGTH_BLOCK_SIZE = 16

Always store ctLength in a fixed size block. This should be large enough to capture the ctLength for VERY large files. GCM should be capable of securing terrabytes of data without the need for a key change. This block size must be fixed in order for us to predictably chop up the cipher text when we try to decrypt

const CTLENGTH_BLOCK_START = GCM_NONCE_END

const ENCRYPTED_GCM_KEY_BYTES = 48

const GCM_NONCE_BYTES = 12

gcm nonce size is 12 bytes (96 bits) Since the nonce length and space is large enough, and a new key is used every time Encrypt is called enforcing nonce uniqueness should not be necessary

const GCM_NONCE_END = 12

const GCM_NONCE_START = 0

Constants which store magic numbers related to how the encrypted blob is constructed

const NACL_FINGERPRINT_BYTES = 20

Include getters to make it clear other modules within cryptoUtils are using these constants

const NACL_KEY_BYTES = 32

const NACL_NONCE_BYTES = 24

NaCl nonce size is 24 bytes per spec

const PBKDF2_CYCLES = 5000

const PBKDF2_KEY_BYTES = 32

const PBKDF2_PASSWORD_BYTES = 32

const PBKDF2_SALT_BYTES = 32

Consts used in this module

Functions

func BytesToNACLKey

func BytesToNACLKey(bytes []byte) *[32]byte

*

• BytesToNACLKey
• Helper that takes in a byte array and casts it to *[32]byte so it can be used
• as an NACL key. This is used by ReadNACLKeyFile.

func BytesToNACLNonce

func BytesToNACLNonce(bytes []byte) *[24]byte

*

• BytesToNACLNonce
• Read in a byte array and attempt to cast it to *[24]byte for use with
• NACL as a Nonce.

func Decrypt

func Decrypt(blob []byte, selfPubKey, selfPrivKey *[32]byte) (plainText []byte, err error)

*

• Decrypt attempts to decrypt the underlying secret data as per the header comment

func Encrypt

func Encrypt(plainText []byte, authorizedPubKeys []*[32]byte, selfPubKey, selfPrivKey *[32]byte) []byte

*

• Encrypt returns a byte array which is constructed per the header comments

func GenAES256Key

func GenAES256Key() []byte

*

• GenAES256Key
• Generate a completley random 32 byte key using PBKDF2 with a completely random
• "passphrase" and salt. sha256 is being used as the hashing function.

func GenerateGCMNonce

func GenerateGCMNonce() []byte

*

• GenerateGCMNonce
• Generate a random nonce for use with AES GCM

func GenerateNACLKeyPair

func GenerateNACLKeyPair() (pubKey, privKey *[32]byte)

*

• GenerateNACLKeyPair
• Helper method that wraps NaCl's built in key generation function.

func GenerateNACLNonce

func GenerateNACLNonce() *[24]byte

*

• GenerateNACLNonce
• Generate a random nonce for use with NaCl

func GetNACLKeyFingerprint

func GetNACLKeyFingerprint(key *[32]byte) []byte

*

• GetNACLKeyFingerprint
• Generates 20 byte fingerprints for NaCl Keys using sha1
• This is only meant to be used with PUBLIC keys.

func NACLKeyFromFile

func NACLKeyFromFile(filePath string) *[32]byte

*

• NACLKeyFromFile
• Helper method that reads files containing an NaCl key string and returns an NaCl key.

func ReadFromRand

func ReadFromRand(numBytes int) []byte

*

• ReadFromRand
• Return a byte array of size numBytes that is completely full of cryptographically
• sound random data.

func ReadNACLKeyFile

func ReadNACLKeyFile(keyFilePath string) string

*

• ReadNACLKeyFile
• Helper method to read NACL key files that were written to disk with WriteNACLKeyFile.

func StringToNACLKey

func StringToNACLKey(encodedKeyString string) *[32]byte

*

• StringToNACLKey
• Helper method to read encoded NACL key data strings and return an NACL key.
• Because this is a helper method, we assume the string passed in is encoded
• as base64.

func WriteNACLKeyFile

func WriteNACLKeyFile(keyFilePath string, key *[32]byte, keyComment string, perms os.FileMode)

*

• WriteNACLKeyFile
• Helper method that encodes NACL keys to base64 then writes them to disk.