cryptoengine

README

Build status

CryptoEngine package

This simplifies even further the usage of the NaCl crypto primitives, by taking care of the nonce part. It uses a KDF, specifically HKDF to compute the nonces.

Big Picture

The encryption and decryption phases are the following:

Message -> Encrypt -> EncryptedMessage -> ToBytes() -> < = NETWORK = >  <- FromBytes() -> EncryptedMessage -> Decrypt -> Message

Usage

1- Import the library

import github.com/sec51/cryptoengine

2- Instanciate the CryptoEngine object via:

	engine, err := cryptoengine.InitCryptoEngine("Sec51")
	if err != nil {
		return err
	}

See the godoc for more info about the InitCryptoEngine parameter

3- Encrypt a message using symmetric encryption

    message := "the quick brown fox jumps over the lazy dog"
	engine.NewMessage(message)
	if err != nil {
		return err
	}

4- Serialize the message to a byte slice, so that it can be safely sent to the network

	messageBytes, err := tcp.ToBytes()
	if err != nil {
		t.Fatal(err)
	}	

5- Parse the byte slice back to a message

	message, err := MessageFromBytes(messageBytes)
	if err != nil {
		t.Fatal(err)
	}

License

Copyright (c) 2015 Sec51.com info@sec51.com

Permission to use, copy, modify, and distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

Documentation

Index

• Variables
• func NewMessage(clearText string, messageType int) (message, error)
• type CryptoEngine
  • func InitCryptoEngine(communicationIdentifier string) (*CryptoEngine, error)
  • func (engine *CryptoEngine) Decrypt(encryptedBytes []byte) (*message, error)
  • func (engine *CryptoEngine) DecryptWithPublicKey(encryptedBytes []byte, verificationEngine VerificationEngine) (*message, error)
  • func (engine *CryptoEngine) NewEncryptedMessage(msg message) (EncryptedMessage, error)
  • func (engine *CryptoEngine) NewEncryptedMessageWithPubKey(msg message, verificationEngine VerificationEngine) (EncryptedMessage, error)
  • func (engine *CryptoEngine) PublicKey() []byte
• type EncryptedMessage
  • func (m EncryptedMessage) ToBytes() ([]byte, error)
• type VerificationEngine
  • func NewVerificationEngine(context string) (VerificationEngine, error)
  • func NewVerificationEngineWithKey(publicKey []byte) (VerificationEngine, error)
  • func (e VerificationEngine) PublicKey() [keySize]byte

Variables

var (
	KeySizeError           = errors.New(fmt.Sprintf("The provisioned key size is less than: %d\n", keySize))
	KeyNotValidError       = errors.New("The provisioned public key is not valid")
	SaltGenerationError    = errors.New("Could not generate random salt")
	KeyGenerationError     = errors.New("Could not generate random key")
	MessageDecryptionError = errors.New("Could not verify the message. Message has been tempered with!")
	MessageParsingError    = errors.New("Could not parse the Message from bytes")
)

Functions

func NewMessage

func NewMessage(clearText string, messageType int) (message, error)

Create a new message with a clear text and the message type messageType: is an identifier to distinguish the messages on the receiver and parse them for example if zero is a JSON message and 1 is XML, then the received can parse different formats with different methods

Types

type CryptoEngine

type CryptoEngine struct {
	// contains filtered or unexported fields
}

This is the basic object which needs to be instanciated for encrypting messages either via public key cryptography or private key cryptography The object has the methods necessary to execute all the needed functions to encrypt and decrypt a message, both with symmetric and asymmetric crypto

func InitCryptoEngine

func InitCryptoEngine(communicationIdentifier string) (*CryptoEngine, error)

This function initialize all the necessary information to carry out a secure communication either via public key cryptography or secret key cryptography. The peculiarity is that the user of this package needs to take care of only one parameter, the communicationIdentifier. It defines a unique set of keys between the application and the communicationIdentifier unique end point. IMPORTANT: The parameter communicationIdentifier defines several assumptions the code use:

• it names the secret key files with the comuncationIdentifier prefix. This means that if you want to have different secret keys with different end points, you can differrentiate the key by having different unique communicationIdentifier. It, also, loads the already created keys back in memory based on the communicationIdentifier
• it does the same with the asymmetric keys

The communicationIdentifier parameter is URL unescape, trimmed, set to lower case and all the white spaces are replaced with an underscore. The publicKey parameter can be nil. In that case the CryptoEngine assumes it has been instanciated for symmetric crypto usage.

func (*CryptoEngine) Decrypt

func (engine *CryptoEngine) Decrypt(encryptedBytes []byte) (*message, error)

This method is used to decrypt messages where symmetrci encryption is used

func (*CryptoEngine) DecryptWithPublicKey

func (engine *CryptoEngine) DecryptWithPublicKey(encryptedBytes []byte, verificationEngine VerificationEngine) (*message, error)

This method is used to decrypt messages where symmetrci encryption is used

func (*CryptoEngine) NewEncryptedMessage

func (engine *CryptoEngine) NewEncryptedMessage(msg message) (EncryptedMessage, error)

This method accepts a message , then encrypts its Version+Type+Text using a symmetric key

func (*CryptoEngine) NewEncryptedMessageWithPubKey

func (engine *CryptoEngine) NewEncryptedMessageWithPubKey(msg message, verificationEngine VerificationEngine) (EncryptedMessage, error)

This method accepts the message as byte slice and the public key of the receiver of the messae, then encrypts it using the asymmetric key public key. If the public key is not privisioned and does not have the required length of 32 bytes it raises an exception.

func (*CryptoEngine) PublicKey

func (engine *CryptoEngine) PublicKey() []byte

Gives access to the public key

type EncryptedMessage

type EncryptedMessage struct {
	// contains filtered or unexported fields
}

This struct represent the encrypted message which can be sent over the networl safely |lenght| => 8 bytes (uint64 total message length) |nonce| => 24 bytes ([]byte size) |message| => N bytes ([]byte message)

func (EncryptedMessage) ToBytes

func (m EncryptedMessage) ToBytes() ([]byte, error)

STRUCTURE 8 => |SIZE| 24 => |NONCE| N => |DATA| |size| => 8 bytes (uint64 total message length) |type| => 4 bytes (int message version) |message| => N bytes ([]byte message)

type VerificationEngine

type VerificationEngine struct {
	// contains filtered or unexported fields
}

The verification engine links two peers basically. It holds the public key and the remote peer public key and the pre-shared key

func NewVerificationEngine

func NewVerificationEngine(context string) (VerificationEngine, error)

This function instantiate the verification engine by leveraging the context Basically if a public key of a peer is available locally then it's locaded here

func NewVerificationEngineWithKey

func NewVerificationEngineWithKey(publicKey []byte) (VerificationEngine, error)

This function instantiate the verification engine by passing it the key (at the moment only the public key) go nacl crypto does not support Ed25519 signatures yet

func (VerificationEngine) PublicKey

func (e VerificationEngine) PublicKey() [keySize]byte