aesgcm

Documentation

Overview

Package aesgcm provides easy to use function to perform encryption and decryption using the secure AES-GCM AHEAD algorithm. It support AES-128, AES-192 and AES-256 key sizes. This package wraps the go's 'crypto/aes' library operations into easy to use functions like 'Encrypt' and 'Decrypt'. It also provides the required constants that are needed for dermining size of keys and nonce. Additionally it ensure a proper cryptographically secure nonce is used for the encryption process automatically when the same is not supplied.

Example

package main

import (
	"crypto/subtle"
	"encoding/hex"
	"fmt"

	"github.com/boseji/auth/aesgcm"
)

func main() {
	// Load your secret key from a safe place and reuse it across multiple
	// Seal/Open calls. (Obviously don't use this example key for anything
	// real.) If you want to convert a passphrase to a key, use a suitable
	// package like bcrypt or scrypt.
	// When decoded the key should be 16 bytes (AES-128) or 32 (AES-256).
	key, _ := hex.DecodeString("6368616e676520746869732070617373776f726420746f206120736563726574")
	plaintext := []byte("exampleplaintext")

	// Encryption without Nonce, it will be automatically be generated automatically
	ciphertext, nonce, err := aesgcm.Encrypt(plaintext, key, nil)
	if err != nil {
		panic(err.Error())
	}

	// Decryption should use the same nonce and key as used for Encryption
	plaintext2, err := aesgcm.Decrypt(ciphertext, nonce, key)
	if err != nil {
		panic(err.Error())
	}

	// Cryptographically secure constant time comparison
	if subtle.ConstantTimeCompare(plaintext, plaintext2) != 1 {
		fmt.Println("Error results don't match")
		return
	}

	fmt.Println("Success !")

}

Output:

Success !

Index

• Constants
• func Decrypt(ciphertext, nonce, key []byte) (plaintext []byte, err error)
• func Encrypt(plaintext, key, iNonce []byte) (ciphertext []byte, nonce []byte, err error)
• type Crypt
  • func New(method string, key []byte) (*Crypt, error)
  • func (c *Crypt) Create(plaintext []byte, _ interface{}) (ciphertext []byte, err error)
  • func (c *Crypt) Decrypt(ciphertext []byte) (plaintext []byte, nonce interface{}, err error)
  • func (c *Crypt) Encrypt(plaintext []byte) (ciphertext []byte, err error)
  • func (c *Crypt) Set(method string, key interface{}) error
  • func (c *Crypt) Verify(ciphertext []byte, _ interface{}) (plaintext []byte, nonce interface{}, err error)

Examples

• Package
• Decrypt
• Encrypt
• New

Constants

const (
	// NonceSize provides the default recommended Nonce size
	NonceSize = 12
	// KeySizeAES128 specifies the minimum Key size needed for AES-GCM-128
	KeySizeAES128 = 16
	// KeySizeAES192 specifies the minimum Key size needed for AES-GCM-192
	KeySizeAES192 = 24
	// KeySizeAES256 specifies the minimum Key size needed for AES-GCM-256
	KeySizeAES256 = 32
	// AES128 defines the Encryption method AES-GCM-128
	AES128 = "AES128"
	// AES192 defines the Encryption method AES-GCM-192
	AES192 = "AES192"
	// AES256 defines the Encryption method AES-GCM-256
	AES256 = "AES256"
)

Functions

func Decrypt

func Decrypt(ciphertext, nonce, key []byte) (plaintext []byte, err error)

Decrypt function performs the AES-GCM Decryption. On needs to provide the same nonce generated by the Encrypt function and the same key as used there. The ciphertext needs to be non tampered else the decryption would fail. This is due to the AHEAD security nature of AES-GCM.

Example

package main

import (
	"encoding/hex"
	"fmt"

	"github.com/boseji/auth/aesgcm"
)

func main() {
	// Load your secret key from a safe place and reuse it across multiple
	// Seal/Open calls. (Obviously don't use this example key for anything
	// real.) If you want to convert a passphrase to a key, use a suitable
	// package like bcrypt or scrypt.
	// When decoded the key should be 16 bytes (AES-128) or 32 (AES-256).
	key, _ := hex.DecodeString("6368616e676520746869732070617373776f726420746f206120736563726574")
	ciphertext, _ := hex.DecodeString("022100c774487456c404b3bb9b3938c7234b3837746a27fbd84a91df5d3ba62e")
	nonce, _ := hex.DecodeString("eed01d5099dc428d44bb18f1")

	// Decryption with supplied nonce and key
	plaintext, err := aesgcm.Decrypt(ciphertext, nonce, key)
	if err != nil {
		panic(err.Error())
	}

	fmt.Printf("Plain Text: %s\n", plaintext)

}

Output:

Plain Text: exampleplaintext

func Encrypt

func Encrypt(plaintext, key, iNonce []byte) (ciphertext []byte, nonce []byte, err error)

Encrypt function performs the AES-GCM Encryption The supplied 'plaintext' is encrypted using the 'key'. Typically a Nonce is needed for the computation involved in encryption. This can be supplied using `iNonce` parameter and should at least have a size equivalent to 'NonceSize' constant. In case no nonce is supplied then a cryptographically secure random nonce is generated (using auth.GetRandom function).

Example

package main

import (
	"encoding/hex"
	"fmt"

	"github.com/boseji/auth/aesgcm"
)

func main() {
	// Load your secret key from a safe place and reuse it across multiple
	// Seal/Open calls. (Obviously don't use this example key for anything
	// real.) If you want to convert a passphrase to a key, use a suitable
	// package like bcrypt or scrypt.
	// When decoded the key should be 16 bytes (AES-128) or 32 (AES-256).
	key, _ := hex.DecodeString("6368616e676520746869732070617373776f726420746f206120736563726574")
	plaintext := []byte("exampleplaintext")

	// Should not use a Zero Nonce for normal operation
	iNonce := make([]byte, aesgcm.NonceSize)

	// Encryption using a fixed or pre-set nonce
	ciphertext, nonce, err := aesgcm.Encrypt(plaintext, key, iNonce)
	if err != nil {
		panic(err.Error())
	}

	fmt.Printf("Nonce: %x\n", nonce)
	fmt.Printf("Cipher Text: %x\n", ciphertext)

}

Output:

Nonce: 000000000000000000000000
Cipher Text: b9e3743b8019206437b8ddc1ceb150096aa14c85d9f623096ffffaf48232c4f8

Types

type Crypt

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

Crypt implements the Auth interface for Encryption and Decryption

func New

func New(method string, key []byte) (*Crypt, error)

New function creates a new instance of the AES-GCM Crypt Engine. In case it fails to do so it returns the underlying error cause. The methods supported are specied by AES128 , AES192 and AES256. Any thing else would return an error. If the supplied key is shorter than specified length for a given method, then a SHAKE256 Hash is taken to expand the key.

Example

package main

import (
	"crypto/subtle"
	"encoding/hex"
	"fmt"

	"github.com/boseji/auth/aesgcm"
)

func main() {
	// Load your secret key from a safe place and reuse it across multiple
	// Seal/Open calls. (Obviously don't use this example key for anything
	// real.) If you want to convert a passphrase to a key, use a suitable
	// package like bcrypt or scrypt.
	// When decoded the key should be 16 bytes (AES-128) or 32 (AES-256).
	key, _ := hex.DecodeString("6368616e676520746869732070617373776f726420746f206120736563726574")
	plaintext := []byte("exampleplaintext")

	// Create the Crypt instance to perfrom AES-GCM operations
	crypt, err := aesgcm.New(aesgcm.AES256, key)
	if err != nil {
		panic(err.Error())
	}

	// Encryption :  Nonce, it will be automatically be generated automatically
	// and placed inside the Cipher text
	ciphertext, err := crypt.Encrypt(plaintext)
	if err != nil {
		panic(err.Error())
	}

	// Decryption : Same Ciphertext as from encryption
	plaintext2, _, err := crypt.Decrypt(ciphertext)
	if err != nil {
		panic(err.Error())
	}

	// Cryptographically secure constant time comparison
	if subtle.ConstantTimeCompare(plaintext, plaintext2) != 1 {
		fmt.Println("Error results don't match")
		return
	}

	fmt.Println("Success !")

}

Output:

Success !

func (*Crypt) Create

func (c *Crypt) Create(plaintext []byte, _ interface{}) (ciphertext []byte, err error)

Create method of Auth interface performs the Encryption operation using the pre-initialized cipher in Crypt. The output is actually the ciphertext. It contains both the nonce and cipher text combined in one block.

func (*Crypt) Decrypt

func (c *Crypt) Decrypt(ciphertext []byte) (plaintext []byte, nonce interface{}, err error)

Decrypt method wraps the Verify method

func (*Crypt) Encrypt

func (c *Crypt) Encrypt(plaintext []byte) (ciphertext []byte, err error)

Encrypt method wraps Create method

func (*Crypt) Set

func (c *Crypt) Set(method string, key interface{}) error

Set method of the Auth Interface configures the Cipher engine for AES-GCM. The methods supported are specied by AES128 , AES192 and AES256. Any thing else would return an error. If the supplied key is shorter than specified length for a given method, then a SHAKE256 Hash is taken to expand the key.

func (*Crypt) Verify

func (c *Crypt) Verify(ciphertext []byte, _ interface{}) (plaintext []byte, nonce interface{}, err error)

Verify method of the Auth interface performs the Decryption operation using the pre-initialized cipher in Crypt. This would only work with the ciphertext generated using the Create function with the same Crypt configuration. This method returns the plaintext and the nonce used upon successful decryption.