triplesec

README

TripleSec

---

Golang implementation of the layered encryption scheme TripleSec

A fork of Fillipo's TripleSec

See TripleSec Homepage for more info.

---

Installation

go get github.com/keybase/go-triplesec

Usage

import "github.com/keybase/go-triplesec"

Example

    package main

    import (
    	"crypto/rand"
    	"fmt"
    	"github.com/keybase/go-triplesec"
    	"log"
    )

    func main() {
    	// Make Random 16 byte salt
    	passphrase := []byte("password1234567890")
    	salt := make([]byte, 16)
    	_, err := rand.Read(salt)
    	if err != nil {
    		log.Fatal("Could not create random salt")
    	}
    	// Create Cipher
    	cipher, err := triplesec.NewCipher(passphrase, salt)
    	if err != nil {
    		log.Fatal("Error creating new triple sec cipher")
    	}
    	fileBytes := []byte("testdata")
    	encryptedFileBytes, err := cipher.Encrypt(fileBytes)
        if err != nil {
            log.Fatal("Encryption error")
        }
    
    	// Do something with encrypted data such as save the file/send to remote
    }

Documentation

Overview

Package triplesec implements the TripleSec v3 encryption and authentication scheme.

For details on TripleSec, go to https://keybase.io/triplesec/

Index

• Constants
• Variables
• type BadPassphraseError
  • func (e BadPassphraseError) Error() string
• type Cipher
  • func NewCipher(passphrase []byte, salt []byte) (*Cipher, error)
  • func (c *Cipher) Decrypt(src []byte) (res []byte, err error)
  • func (c *Cipher) DeriveKey(extra int) ([]byte, []byte, error)
  • func (c *Cipher) Encrypt(src []byte) (dst []byte, err error)
  • func (c *Cipher) GetSalt() ([]byte, error)
  • func (c *Cipher) Scrub()
  • func (c *Cipher) SetSalt(salt []byte) error
• type CorruptionError
  • func (e CorruptionError) Error() string
• type VersionError
  • func (e VersionError) Error() string

Constants

const MacOutputLen = 64

MacOutputLen is used for calculation of Overhead

const SaltLen = 16

SaltLen determines the size of salt applied to hash functions

Variables

var (
	IVLen      = 16
	SalsaIVLen = 24
	TotalIVLen = 2*IVLen + SalsaIVLen
	DkLen      = 2*macKeyLen + 3*cipherKeyLen
)

IVLen sets Initialization Vector length

var MagicBytes = [4]byte{0x1c, 0x94, 0xd7, 0xde}

MagicBytes are the four bytes prefixed to every TripleSec ciphertext, 1c 94 d7 de.

var Overhead = len(MagicBytes) + 4 + SaltLen + 2*MacOutputLen + TotalIVLen

Overhead is the amount of bytes added to a TripleSec ciphertext.

len(plaintext) + Overhead = len(ciphertext)

It consists of: magic bytes + version + salt + 2 * MACs + 3 * IVS.

var Version uint32 = 3

Version is written to encrypted items to support different implementation versions

Types

type BadPassphraseError

type BadPassphraseError struct{}

BadPassphraseError indicates an incorrect passphrase or failed MAC

func (BadPassphraseError) Error

func (e BadPassphraseError) Error() string

type Cipher

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

Cipher consists of passphrase, salt, and derived key

func NewCipher

func NewCipher(passphrase []byte, salt []byte) (*Cipher, error)

NewCipher is an instance of TripleSec using a particular key and a particular salt

func (*Cipher) Decrypt

func (c *Cipher) Decrypt(src []byte) (res []byte, err error)

Decrypt decrypts a TripleSec ciphertext using the Cipher passphrase. The dst buffer size must be at least len(src) - Overhead. dst and src can not overlap. src is left untouched.

Encrypt returns a error if the ciphertext is not recognized, if authentication fails or on memory failures.

func (*Cipher) DeriveKey

func (c *Cipher) DeriveKey(extra int) ([]byte, []byte, error)

DeriveKey creates a new derived key

func (*Cipher) Encrypt

func (c *Cipher) Encrypt(src []byte) (dst []byte, err error)

Encrypt encrypts and signs a plaintext message with TripleSec using a random salt and the Cipher passphrase. The dst buffer size must be at least len(src) + Overhead. dst and src can not overlap. src is left untouched.

Encrypt returns a error on memory or RNG failures.

func (*Cipher) GetSalt

func (c *Cipher) GetSalt() ([]byte, error)

GetSalt creates a new salt from crypto/rand

func (*Cipher) Scrub

func (c *Cipher) Scrub()

Scrub zeros out the bytes of the passphrase and derived key in memory

func (*Cipher) SetSalt

func (c *Cipher) SetSalt(salt []byte) error

SetSalt allows you to set salt programmatically

type CorruptionError

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

CorruptionError indicates that the encrypted item is corrupted

func (CorruptionError) Error

func (e CorruptionError) Error() string

type VersionError

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

VersionError indicates a version mismatch or unsuppported version

func (VersionError) Error

func (e VersionError) Error() string