gfc

README

Package gfc

Code in this package provides the core gfc functionality, e.g. I/O (utils.go), byte encoding (encoding.go), and the cryptography code. Cryptography code is organized such that a file represents one algorithm, including its encrypt and decrypt functions.

Users can import this package and use the functions defined here easily.

Buffer

The gfc package uses its own custom interface Buffer (see buffer.go) to describe function parameters. It is usually a bytes.Buffer.

// File buffer.go
type Buffer interface {
  Read([]byte) (int, error)
  Write([]byte) (int, error)
  ReadFrom(io.Reader) (int64, error)
  WriteTo(io.Writer) (int64, error)
  Len() int
  Bytes() []byte
}

gfc's custom symmetric encryption output

All symmetric encryption functions derive key using PBKDF2 automatically. This requires us to store the salt in the encrypted output, so that the salt used during KDF when decrypting the message later. In addition to PBKDF2 salt, we will also have to store the nonce (number-once). The ciphertext output format is:

<Ciphertext> <Cipher Nonce> <PBKDF2 Salt>

TODO: This output format is currently implemented as a structure. Maybe we'll add struct symmOut so that all gfc output from all symmetric key encryption algorithms are standardized. It is currently handled by marshalSymmOut and unmarshalSymmOut.

PBKDF2 Salt is fixed in gfc, at length of 32-byte.

Cipher Nonce size is different for each cipher:

• AES256-GCM: 12-byte

• AES256-CTR: 16-byte

• ChaCha20-Poly1305: 12-byte

• XChaCha20-Poly1305: 24-byte

During decryption, we need to extract the salt first in order to derive our PBKDF2 back from our raw key bytes. The index at which PBKDF2 salt starts is always the length of the ciphertext minus the salt length.

Documentation

Index

• Constants
• type AlgoMode
• type Algorithm
• type Buffer
  • func Compress(compressOption bool, raw Buffer) (Buffer, error)
  • func Decode(encoding Encoding, raw Buffer) (Buffer, error)
  • func Decompress(decompressOption bool, raw Buffer) (Buffer, error)
  • func DecryptCTR(ciphertext Buffer, aesKey []byte) (Buffer, error)
  • func DecryptChaCha20Poly1305(ciphertext Buffer, key []byte) (Buffer, error)
  • func DecryptFamilyChaCha20(newCipherFunc func([]byte) (cipher.AEAD, error), nonceSize int, ...) (Buffer, error)
  • func DecryptGCM(ciphertext Buffer, aesKey []byte) (Buffer, error)
  • func DecryptRSA(ciphertext Buffer, priKey []byte) (Buffer, error)
  • func DecryptXChaCha20Poly1305(ciphertext Buffer, key []byte) (Buffer, error)
  • func Encode(encoding Encoding, raw Buffer) (Buffer, error)
  • func EncryptCTR(plaintext Buffer, aesKey []byte) (Buffer, error)
  • func EncryptChaCha20Poly1305(plaintext Buffer, key []byte) (Buffer, error)
  • func EncryptFamilyChaCha20(newCipherFunc func([]byte) (cipher.AEAD, error), nonceSize int, ...) (Buffer, error)
  • func EncryptGCM(plaintext Buffer, aesKey []byte) (Buffer, error)
  • func EncryptRSA(plaintext Buffer, pubKey []byte) (Buffer, error)
  • func EncryptXChaCha20Poly1305(plaintext Buffer, key []byte) (Buffer, error)
• type Encoding

Constants

const (
	// Default
	NoError gfcError = iota
	// Error PBDKF2 key and salt derivation
	ErrPBKDF2KeySalt
	// Error unmarshaling gfc symmetric key output
	ErrUnmarshalSymmAEAD
	// Error invalid keyfile length (32 bytes)
	ErrInvalidaes256BitKeyFileLen
	// Error CTR new cipher
	ErrNewCipherCTR
	// Error CTR in read loop
	ErrReadCTR
	// Error GCM new cipher
	ErrNewCipherGCM
	// Error GCM new GCM
	ErrNewGCM
	// Error GCM open
	ErrOpenGCM
	// Error RSA parse pubkey
	ErrParsePubRSA
	// Error RSA encrypt
	ErrEncryptRSA
	// Error RSA pase prikey
	ErrParsePriRSA
	// Error RSA decrypt
	ErrDecryptRSA
	// Error XChaCha20Poly1305 New cipher
	ErrNewCipherXChaCha20Poly1305
	// Error XChaCha20Poly1305 Open
	ErrOpenXChaCha20Poly1305
)

const (
	AlgoInvalid Algorithm = iota
	AlgoAES
	AlgoRSA
	AlgoXChaCha20

	ModeInvalid AlgoMode = iota
	ModeAesGCM
	ModeAesCTR
	ModeRsaOEAP
	ModeXChaCha20Poly1305
	ModeChaCha20Poly1305

	EncodingNone Encoding = iota
	EncodingBase64
	EncodingHex
)

Avoid collisions by declaring them in 1 block

Types

type AlgoMode

type AlgoMode uint8

type Algorithm

type Algorithm uint8

type Buffer

type Buffer interface {
	io.Reader
	io.Writer
	io.ReaderFrom
	io.WriterTo
	Len() int
	Bytes() []byte
}

func Compress

func Compress(compressOption bool, raw Buffer) (Buffer, error)

func Decode

func Decode(encoding Encoding, raw Buffer) (Buffer, error)

func Decompress

func Decompress(decompressOption bool, raw Buffer) (Buffer, error)

func DecryptCTR

func DecryptCTR(ciphertext Buffer, aesKey []byte) (Buffer, error)

func DecryptChaCha20Poly1305

func DecryptChaCha20Poly1305(ciphertext Buffer, key []byte) (Buffer, error)

func DecryptFamilyChaCha20

func DecryptFamilyChaCha20(
	newCipherFunc func([]byte) (cipher.AEAD, error),
	nonceSize int,
	ciphertext Buffer,
	key []byte,
) (
	Buffer,
	error,
)

func DecryptGCM

func DecryptGCM(ciphertext Buffer, aesKey []byte) (Buffer, error)

func DecryptRSA

func DecryptRSA(ciphertext Buffer, priKey []byte) (Buffer, error)

func DecryptXChaCha20Poly1305

func DecryptXChaCha20Poly1305(ciphertext Buffer, key []byte) (Buffer, error)

func Encode

func Encode(encoding Encoding, raw Buffer) (Buffer, error)

func EncryptCTR

func EncryptCTR(plaintext Buffer, aesKey []byte) (Buffer, error)

func EncryptChaCha20Poly1305

func EncryptChaCha20Poly1305(plaintext Buffer, key []byte) (Buffer, error)

func EncryptFamilyChaCha20

func EncryptFamilyChaCha20(
	newCipherFunc func([]byte) (cipher.AEAD, error),
	nonceSize int,
	plaintext Buffer,
	key []byte,
) (
	Buffer,
	error,
)

func EncryptGCM

func EncryptGCM(plaintext Buffer, aesKey []byte) (Buffer, error)

func EncryptRSA

func EncryptRSA(plaintext Buffer, pubKey []byte) (Buffer, error)

func EncryptXChaCha20Poly1305

func EncryptXChaCha20Poly1305(plaintext Buffer, key []byte) (Buffer, error)

type Encoding

type Encoding uint8