celo

package module
v0.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 8, 2018 License: MIT Imports: 15 Imported by: 0

README

Celo

Celo is a CLI tool to encrypt files from an user-defined secret phrase.

Celo encrypts files using AES GCM block cipher that provides both privacy and integrity checks. The Nonce used by the cipher is re-generated for every encryption, meaning that no nonce is reused.

Key Generation

Celo uses argon2 for key generation from a phrase with a random salt on every encryption. Even when the same phrase is used twice or more, a different key is generated.

Celo as library

Even though Celo was originally designed to be a command line interface tool, it makes sense to distribute it as a library hoping it could help other projects with similar needs.

Notice!

Celo is still in early development and it's not recommended to be uses in production tasks yet.

CLI Usage

    $ celo [COMMAND] <FILE|PATTERN> [ARG...]

You can get a detailed list o commands and arguments using the --help flag.

    $ celo --help
    $ celo encrypt --help       # $ celo e --help
    $ celo decrypt --help       # $ celo d --help

Encrypting a single file

    $ celo book_draft.md

    > Enter Phrase:
    > Confirm Phrase:

    > 1 file(s) encrypted. (0 failed)    
    > Encrypted Files:
    >   book_draft.md.celo

The book_draft.md file will be encrypted resulting in a new file with the a similar name, suffixed with the .celo extension.

Decrypting a single file

    $ celo d book_draft.md.celo

    > Enter Phrase:

    > 1 file(s) decrypted. (0 failed)    
    > Decrypted Files:
    >   book_draft.md

Working with multiple files

Celo accepts a list of files as well as Glob patterns in both encryption and decryption.

    # Encrypt files with .txt extension.
    $ celo *.txt -rm-source # -rm-source flag removes the original files after successful encryption.
    # [...]

    # Encrypt all files except files with .png extension.
    $ celo ./* -exclude="*.png" # $ celo "./*" -exclude="*.png" works too.
    # [...]

    # Decrypting multiple files with the .celo extension.
    $ celo d ./*.celo
    # [...]

Documentation

Overview

Package celo is a tool to encrypt files from a secret phrase. Celo encrypts files using AES GCM block cipher that provides both privacy and integrity checks. The Nonce used by the cipher is re-generated for every encryption, meaning that no nonce is reused.

Key Generation

Celo uses argon2 for key generation from a phrase with a random salt on every encryption. Even when the same phrase is used twice or more, a different key is generated.

Celo as library

Even though Celo was originally designed to be a command line interface tool, it makes sense to distribute it as a library hoping it could help other projects with similar needs.

Encrypting a single file

The book_draft.md file will be encrypted resulting in a new file with the a similar name, suffixed with the .celo extension.

book_draft.md.celo contains everything needed to decrypt it back, including:

  • Metadata such as version, sizes of salt, nonce, cipher block.
  • Salt used to generate the key.
  • Nonce used at encryption.

Example: 

  e := celo.NewEncrypter()

  encryptedFileName, err := e.EncryptFile(
  	[]byte("One must acknowledge with cryptography no amount of violence will ever solve a math problem"), // Phrase
  	"book_draft.md",   // File to encrypt
  	true,              // Overwrite if "book_draft.md.celo" already exists.
		false,             // Dont't remove "book_draft.md" after succesful encrpytion.
  )

  if err != nil {
  	panic(err.Error())
  }

  fmt.Print(encryptedFileName) // book_draft.md.celo

Index

Constants

View Source 
const (
	// Aes256BlockSize block size used as the default value for the Celo cipher.
	// Celo uses AES GCM with a block siz of 32 (256 bits).
	Aes256BlockSize = 32

	// SaltSize arbitrary salt length used to generate cipher's keys from a
	// phrase. Celo uses argon2 key derivation to generate the key.
	SaltSize = 32

	// NonceSize nonce size recomended for encrypting and signing values with
	// AES GCM.
	NonceSize = 12

	// Extension extension used when creating encrypted files by Celo.
	//  - secrets.txt -> secrets.txt.celo
	Extension = "celo"

	// Version current version of Celo. Version value will be attached to the
	// file signature if a file is created. (See Encrypter.Encode).
	Version = 1
)

Default Celo configuration values.

View Source 
const (
	// MinVersion minimum encrypted file version supported by the decoder of the
	// running version of Celo.
	MinVersion byte = 1
	// MaxVersion maximum encrypted file version supported by the decoder of the
	// running version of Celo.
	MaxVersion byte = 1
)

Supported versions.

View Source 
const SignatureSize = 32

SignatureSize size of bytes used by the Celo file signature. 

..CELO.. 8
vsbn.... 8
........ 8
........ 8
       = 32

Variables

This section is empty.

Functions

func GenerateKey 

func GenerateKey(phrase, salt []byte, blockSize uint32) []byte

GenerateKey generates a derived key of size blockSize using a phrase and a salt. It uses argon2 key derivation algorithm.

func NewSalt 

func NewSalt(saltSize int) (salt []byte, n int, err error)

NewSalt generates a random salt. It returns the salt and number of bytes readed. It returns an error if it fails to read saltSize bytes.

func ReadAndConfirmPhrase 

func ReadAndConfirmPhrase(retries uint32) (phrase []byte, err error)

ReadAndConfirmPhrase reads the phrase and ask for confirmation with a number of retries. If the passed arguments for retries is 0, the number of retries is unlimited.

func ReadPhrase 

func ReadPhrase(printLabel bool) ([]byte, error)

ReadPhrase read phrase from Stdin without echoing it. It will print instructions if true is passed.

func SetExtension 

func SetExtension(ext string) option

SetExtension replaces the default extension attached to encrypted files.

func SignatureHeader 

func SignatureHeader() [8]byte

SignatureHeader File Signature also known as Magic Bytes that identify a file created by Celo. 

..CELO.. <-- Signature Header
vsbn.... v = version, s = saltSize, b = blockSize, n = nonceSize
........
........

func ValidateMetadata 

func ValidateMetadata(signature [8]byte, vsbn [4]byte, reserved [20]byte) error

ValidateMetadata validates correctness of the signature header, version, salt size, block size and nonce size.

Types

type Cipher 

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

Cipher is an abstraction of Golang's AES cipher with GCM mode.

func NewCipher 

func NewCipher(blockSize, nonceSize int, key []byte) (*Cipher, error)

NewCipher creates a pre-configured AES GCM cipher.

func (*Cipher) BlockSize 

func (c *Cipher) BlockSize() int

BlockSize returns block size of the cipher

func (*Cipher) Decrypt 

func (c *Cipher) Decrypt(nonce, ciphertext []byte) (plaintext []byte, err error)

Decrypt decrypts the ciphertext using the passed nonce. It returns plaintext or an error.

func (*Cipher) Encrypt 

func (c *Cipher) Encrypt(plaintext, additionalData []byte) (nonce, ciphertext []byte, err error)

Encrypt encrypts plaintext It returns nonce and ciphertext or an error

func (*Cipher) NonceSize 

func (c *Cipher) NonceSize() int

NonceSize returns nonce size of the cipher

type Decrypter 

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

Decrypter decodes and decrypts files or sources created by Celo.

func NewDecrypter 

func NewDecrypter() *Decrypter

NewDecrypter creates a Decrypter with package's default configuration.

func (*Decrypter) BlockSize 

func (c *Decrypter) BlockSize() int

BlockSize block size used by the cipher.

func (*Decrypter) Config 

func (c *Decrypter) Config(opts ...option)

Config applies custom configurations.

func (*Decrypter) Decode 

func (d *Decrypter) Decode(r io.Reader) (n int, err error)

Decode decodes from a io.Reader everything that is neccesary to initialize a Decrypter instance, including metadata, salt, nonce and the ciphertext. It returns an error if the source is not readable or any of the values aren't found. It is an alias of Decrypter.Read

func (*Decrypter) Decrypt 

func (d *Decrypter) Decrypt(secretPhrase []byte) (plaintext []byte, err error)

Decrypt decrypts ciphertext using previously stored salt and nonce values and the provided phrase (that generates the AES GCM key).

It returns an error if the Decrypter instance isn't initialized. It returns the plaintext as an array of bytes or an error if the decryption process failed.

func (*Decrypter) DecryptFile 

func (d *Decrypter) DecryptFile(secretPhrase []byte, name string, overwrite, removeSource bool) (decryptedFileName string, err error)

DecryptFile decrypts a file with the specified name. It requires the secret phrase. It returns the name of the decrypted file or an error. If a file with the same name as the decrypted file exists, overwrite has to be `true` in order to overwrite the content of the file.

func (*Decrypter) DecryptMultipleFiles 

func (d *Decrypter) DecryptMultipleFiles(secretPhrase []byte, fileNames []string, overwrite, removeSource bool) (decryptedFileNames []string, errs []error)

DecryptMultipleFiles decrypts a list of files with the specified names. It requires the secret phrase. If a file with the same name as the decrypted file exists, overwrite has to be true in order to replace the content of the file. It returns a list of file names that were successfully decrypted and a list of errors, each for a file that couldn't be decrypted.

func (*Decrypter) GetDecryptedFileName 

func (c *Decrypter) GetDecryptedFileName(f *os.File) string

GetDecryptedFileName returns the potential file name after being decrypted.

func (*Decrypter) GetEncryptedFileName 

func (c *Decrypter) GetEncryptedFileName(f *os.File) string

GetEncryptedFileName returns the potential file name after being encrypted.

func (*Decrypter) Init 

func (d *Decrypter) Init(secretPhrase, salt, nonce, ciphertext []byte) error

Init initializes a Decrypter instance by specifying custom salt, phrase, nonce, and ciphertext values. It returns an error if any of the values have incorrect sizes.

func (*Decrypter) IsReady 

func (c *Decrypter) IsReady() bool

IsReady the celo instance has been initialized.

func (*Decrypter) Nonce 

func (c *Decrypter) Nonce() []byte

Nonce nonce used at encryption.

func (*Decrypter) NonceSize 

func (c *Decrypter) NonceSize() int

SaltSize nonce size (number of bytes).

func (*Decrypter) Read 

func (d *Decrypter) Read(r io.Reader) (n int, err error)

Read decodes from a io.Reader everything that is neccesary to initialize a Decrypter instance, including metadata, salt, nonce and the ciphertext. It returns an error if the source is not readable or any of the values aren't found.

func (*Decrypter) Salt 

func (c *Decrypter) Salt() []byte

Salt salt used to generate key.

func (*Decrypter) SaltSize 

func (c *Decrypter) SaltSize() int

SaltSize salt size (number of bytes).

func (*Decrypter) Wipe 

func (c *Decrypter) Wipe()

Wipe dereference stored values. It sets the instance as not initialized. (Not ready).

type Encrypter 

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

Encrypter encrypts and encodes files and sources.

func NewEncrypter 

func NewEncrypter() *Encrypter

NewEncrypter creates a Encrypter with package's default configurations.

func (*Encrypter) BlockSize 

func (c *Encrypter) BlockSize() int

BlockSize block size used by the cipher.

func (*Encrypter) Config 

func (c *Encrypter) Config(opts ...option)

Config applies custom configurations.

func (*Encrypter) Encode 

func (e *Encrypter) Encode(w io.Writer) (n int, err error)

Encode encodes metadata, salt, nonce and the ciphertext to an io.Writer in a way that it can be parsed back to a Decrypter instance. It returns the number of bytes written. It returns an error if the Encrypter is not ready (not initialized). It returns an error if the source is not writeable. It is an alias of Encrypter.Write.

func (*Encrypter) Encrypt 

func (e *Encrypter) Encrypt(secretPhrase []byte, plaintext []byte) (ciphertext []byte, err error)

Encrypt encrypts plaintext using previously stored salt and nonce values and the provided phrase (that generates the AES GCM key).

It returns the ciphertext as an array of bytes if the encryption success. It will initialize the instance with a new cipher. It returns an error if the decryption process fails.

func (*Encrypter) EncryptFile 

func (e *Encrypter) EncryptFile(secretPhrase []byte, name string, overwrite, removeSource bool) (encryptedName string, err error)

EncryptFile encrypts a file with the specified name. It requires the secret phrase to generate the encryption key. It returns the name of the encrypted file or an error. If a file with the same name as the encrypted file exists, overwrite has to be `true` in order to overwrite the content of the file.

func (*Encrypter) EncryptMultipleFiles 

func (e *Encrypter) EncryptMultipleFiles(secretPhrase []byte, fileNames []string, overwrite, removeSource bool) (encryptedFileNames []string, errs []error)

EncryptMultipleFiles encrypts a list of files with the specified names. It requires the secret phrase. If a file with the same name as the encrypted file exists, overwrite has to be true in order to replace the content of the file. It returns a list of file names that were successfully encrypted and a list of errors, each for a file that couldn't be encrypted.

func (*Encrypter) GetDecryptedFileName 

func (c *Encrypter) GetDecryptedFileName(f *os.File) string

GetDecryptedFileName returns the potential file name after being decrypted.

func (*Encrypter) GetEncryptedFileName 

func (c *Encrypter) GetEncryptedFileName(f *os.File) string

GetEncryptedFileName returns the potential file name after being encrypted.

func (*Encrypter) Init 

func (e *Encrypter) Init(secretPhrase []byte) (err error)

Init initialized an Encrypter instance by specifying a secret phrase that will generate a key, later used to create a cipher. It returns an error the cipher is not created. It marks the instance as initialized (Ready to encrypt).

func (*Encrypter) IsReady 

func (c *Encrypter) IsReady() bool

IsReady the celo instance has been initialized.

func (*Encrypter) Nonce 

func (c *Encrypter) Nonce() []byte

Nonce nonce used at encryption.

func (*Encrypter) NonceSize 

func (c *Encrypter) NonceSize() int

SaltSize nonce size (number of bytes).

func (*Encrypter) Salt 

func (c *Encrypter) Salt() []byte

Salt salt used to generate key.

func (*Encrypter) SaltSize 

func (c *Encrypter) SaltSize() int

SaltSize salt size (number of bytes).

func (*Encrypter) Wipe 

func (c *Encrypter) Wipe()

Wipe dereference stored values. It sets the instance as not initialized. (Not ready).

func (*Encrypter) Write 

func (e *Encrypter) Write(w io.Writer) (n int, err error)

Write encodes metadata, salt, nonce and the ciphertext to an io.Writer in a way that it can be parsed back to a Decrypter instance. It returns the number of bytes written. It returns an error if the Encrypter is not ready (not initialized). It returns an error if the source is not writeable.

type Metadata 

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

Metadata stores the file signature.

func DecodeMetadata 

func DecodeMetadata(r io.Reader) (m *Metadata, n int, err error)

DecodeMetadata tries to decode the metadate from a reader. It returns error if any of the values is missing or doesn't pass validations.

func (*Metadata) Bytes 

func (m *Metadata) Bytes() []byte

Bytes of the File Signature that includes metadata about the encrypted file. This is how it should look using ISO 8859-1 encoding. "????" are placeholders for version, saltSize, blockSize and nonceSize bytes in that order. 

..CELO..
????....
........
........

func (*Metadata) Size 

func (m *Metadata) Size() int

Size size of the file signature.

func (*Metadata) Verify 

func (m *Metadata) Verify(b []byte) bool

Verify compares an array of bytes to verify that they are equivalent to current instance of metadata.

Source Files

View all Source files

Directories

Path Synopsis
cmd
celo

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.