encryption

package
v0.28.4 Latest Latest
Warning

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

 Go to latest Published: Jan 1, 2020 License: AGPL-3.0 Imports: 19 Imported by: 0

Documentation

Index

Examples

Constants

View Source 
const (
	// AESGCMNonceSize is the size of an AES-GCM nonce
	AESGCMNonceSize = 12
)

Variables

View Source 
var ErrDecryptFailed = errs.Class("decryption failed, check encryption key")

ErrDecryptFailed is the errs class when the decryption fails

View Source 
var ErrInvalidConfig = errs.Class("invalid encryption configuration")

ErrInvalidConfig is the errs class for invalid configuration

View Source 
var Error = errs.Class("encryption error")

Error is the default encryption errs class

Functions

func CalcEncompassingBlocks 

func CalcEncompassingBlocks(offset, length int64, blockSize int) (
	firstBlock, blockCount int64)

CalcEncompassingBlocks is a useful helper function that, given an offset, length, and blockSize, will tell you which blocks contain the requested offset and length

func CalcEncryptedSize 

func CalcEncryptedSize(dataSize int64, parameters storj.EncryptionParameters) (int64, error)

CalcEncryptedSize calculates what would be the size of the cipher data after encrypting data with dataSize using a Transformer with the given encryption parameters.

func Decrypt 

func Decrypt(cipherData []byte, cipher storj.CipherSuite, key *storj.Key, nonce *storj.Nonce) (data []byte, err error)

Decrypt decrypts cipherData with the given cipher, key and nonce

func DecryptAESGCM 

func DecryptAESGCM(cipherData []byte, key *storj.Key, nonce *AESGCMNonce) (data []byte, err error)

DecryptAESGCM decrypts byte data with a key and nonce. The plain data is returned

func DecryptKey 

func DecryptKey(keyToDecrypt storj.EncryptedPrivateKey, cipher storj.CipherSuite, key *storj.Key, nonce *storj.Nonce) (*storj.Key, error)

DecryptKey decrypts keyToDecrypt with the given cipher, key and nonce

func DecryptPath 

func DecryptPath(bucket string, path paths.Encrypted, cipher storj.CipherSuite, store *Store) (
	unencPath paths.Unencrypted, err error)

DecryptPath decrypts the path using the provided cipher and looking up keys from the provided store and bucket.

func DecryptPathRaw added in v0.14.2 

func DecryptPathRaw(raw string, cipher storj.CipherSuite, key *storj.Key) (string, error)

DecryptPathRaw decrypts the path using the provided key directly. DecryptPath should be preferred if possible.

func DecryptSecretBox 

func DecryptSecretBox(cipherData []byte, key *storj.Key, nonce *storj.Nonce) (data []byte, err error)

DecryptSecretBox decrypts byte data with a key and nonce. The plain data is returned

func DeriveContentKey 

func DeriveContentKey(bucket string, path paths.Unencrypted, store *Store) (key *storj.Key, err error)

DeriveContentKey returns the content key for the passed in path by looking up the appropriate base key from the store and bucket and deriving the rest.

func DeriveKey 

func DeriveKey(key *storj.Key, message string) (*storj.Key, error)

DeriveKey derives new key from the given key and message using HMAC-SHA512

func DerivePathKey 

func DerivePathKey(bucket string, path paths.Unencrypted, store *Store) (key *storj.Key, err error)

DerivePathKey returns the path key for the passed in path by looking up the appropriate base key from the store and bucket and deriving the rest.

func DeriveRootKey added in v0.14.0 

func DeriveRootKey(password, salt []byte, path storj.Path, argon2Threads uint8) (*storj.Key, error)

DeriveRootKey derives a root key for some path using the salt for the bucket and a password from the user. See the password key derivation design doc.

func Encrypt 

func Encrypt(data []byte, cipher storj.CipherSuite, key *storj.Key, nonce *storj.Nonce) (cipherData []byte, err error)

Encrypt encrypts data with the given cipher, key and nonce

func EncryptAESGCM 

func EncryptAESGCM(data []byte, key *storj.Key, nonce *AESGCMNonce) (cipherData []byte, err error)

EncryptAESGCM encrypts byte data with a key and nonce. The cipher data is returned

func EncryptKey 

func EncryptKey(keyToEncrypt *storj.Key, cipher storj.CipherSuite, key *storj.Key, nonce *storj.Nonce) (storj.EncryptedPrivateKey, error)

EncryptKey encrypts keyToEncrypt with the given cipher, key and nonce

func EncryptPath 

func EncryptPath(bucket string, path paths.Unencrypted, cipher storj.CipherSuite, store *Store) (
	encPath paths.Encrypted, err error)

EncryptPath encrypts the path using the provided cipher and looking up keys from the provided store and bucket.

Example 
package main

import (
	"encoding/hex"
	"fmt"

	"storj.io/storj/pkg/encryption"
	"storj.io/storj/pkg/paths"
	"storj.io/storj/pkg/storj"
)

func main() {
	path := paths.NewUnencrypted("fold1/fold2/fold3/file.txt")

	// seed
	seed := new(storj.Key)
	for i := range seed {
		seed[i] = byte(i)
	}
	fmt.Printf("root key (%d bytes): %s\n", len(seed), hex.EncodeToString(seed[:]))

	store := encryption.NewStore()
	store.SetDefaultKey(seed)

	// use the seed for encrypting the path
	encryptedPath, err := encryption.EncryptPath("bucket", path, storj.EncAESGCM, store)
	if err != nil {
		panic(err)
	}
	fmt.Println("path to encrypt:", path)
	fmt.Println("encrypted path: ", hex.EncodeToString([]byte(encryptedPath.Raw())))

	// decrypting the path
	decryptedPath, err := encryption.DecryptPath("bucket", encryptedPath, storj.EncAESGCM, store)
	if err != nil {
		panic(err)
	}
	fmt.Println("decrypted path: ", decryptedPath)

}

Output:

root key (32 bytes): 000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f
path to encrypt: fold1/fold2/fold3/file.txt
encrypted path:  02387ce34e2054bcb9a0428b820102876eef8325a8397bf7568e91afc40739406ffad12f02453d291b9cb8947155462d6c1edc2367507b0de55b46fa7231f3ba6ad7ce79f4822f02ad7257e8ef4f938ac6b6794b50852873d1b3d32e018dfb17a674dc806ac6e8ddd4262f02aa2128dc8614940f7cf6628513b581f7c18724af3c01018f7c861520c2fdfd78f7b1b25ce0
decrypted path:  fold1/fold2/fold3/file.txt

func EncryptPathRaw added in v0.14.2 

func EncryptPathRaw(raw string, cipher storj.CipherSuite, key *storj.Key) (string, error)

EncryptPathRaw encrypts the path using the provided key directly. EncryptPath should be preferred if possible.

func EncryptSecretBox 

func EncryptSecretBox(data []byte, key *storj.Key, nonce *storj.Nonce) (cipherData []byte, err error)

EncryptSecretBox encrypts byte data with a key and nonce. The cipher data is returned

func Increment 

func Increment(nonce *storj.Nonce, amount int64) (truncated bool, err error)

Increment increments the nonce with the given amount

func Transform 

func Transform(rr ranger.Ranger, t Transformer) (ranger.Ranger, error)

Transform will apply a Transformer to a Ranger.

func TransformReader 

func TransformReader(r io.ReadCloser, t Transformer,
	startingBlockNum int64) io.ReadCloser

TransformReader applies a Transformer to a Reader. startingBlockNum should probably be 0 unless you know you're already starting at a block offset.

func TransformReaderSize 

func TransformReaderSize(r io.ReadCloser, t Transformer,
	startingBlockNum int64, expectedSize int64) io.ReadCloser

TransformReaderSize creates a TransformReader with expected size, i.e. the number of bytes that is expected to be read from this reader. If less than the expected bytes are read, the reader will return io.ErrUnexpectedEOF instead of io.EOF.

Types

type AESGCMNonce 

type AESGCMNonce [AESGCMNonceSize]byte

AESGCMNonce represents the nonce used by the AES-GCM protocol

func ToAESGCMNonce 

func ToAESGCMNonce(nonce *storj.Nonce) *AESGCMNonce

ToAESGCMNonce returns the nonce as a AES-GCM nonce

type Base added in v0.14.2 

type Base struct {
	Unencrypted paths.Unencrypted
	Encrypted   paths.Encrypted
	Key         storj.Key
}

Base represents a key with which to derive further keys at some encrypted/unencrypted path.

type NoopTransformer 

type NoopTransformer struct{}

NoopTransformer is a dummy Transformer that passes data through without modifying it

func (*NoopTransformer) InBlockSize 

func (t *NoopTransformer) InBlockSize() int

InBlockSize is 1

func (*NoopTransformer) OutBlockSize 

func (t *NoopTransformer) OutBlockSize() int

OutBlockSize is 1

func (*NoopTransformer) Transform 

func (t *NoopTransformer) Transform(out, in []byte, blockNum int64) ([]byte, error)

Transform returns the input without modification

type Store added in v0.14.2 

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

The Store allows one to find the matching most encrypted key and path for some unencrypted path. It also reports a mapping of encrypted to unencrypted paths at the searched for unencrypted path.

For example, if the Store contains the mappings 

b1, u1/u2/u3    => <e1/e2/e3, k3>
b1, u1/u2/u3/u4 => <e1/e2/e3/e4, k4>
b1, u1/u5       => <e1/e5, k5>
b1, u6          => <e6, k6>
b1, u6/u7/u8    => <e6/e7/e8, k8>
b2, u1          => <e1', k1'>

Then the following lookups have outputs 

b1, u1          => <{e2:u2, e5:u5}, u1, nil>
b1, u1/u2/u3    => <{e4:u4}, u1/u2/u3, <u1/u2/u3, e1/e2/e3, k3>>
b1, u1/u2/u3/u6 => <{}, u1/u2/u3/, <u1/u2/u3, e1/e2/e3, k3>>
b1, u1/u2/u3/u4 => <{}, u1/u2/u3/u4, <u1/u2/u3/u4, e1/e2/e3/e4, k4>>
b1, u6/u7       => <{e8:u8}, u6/, <u6, e6, k6>>
b2, u1          => <{}, u1, <u1, e1', k1'>>
Example 
s := NewStore()
ep := paths.NewEncrypted
up := paths.NewUnencrypted

// Add a fairly complicated tree to the store.
abortIfError(s.Add("b1", up("u1/u2/u3"), ep("e1/e2/e3"), toKey("k3")))
abortIfError(s.Add("b1", up("u1/u2/u3/u4"), ep("e1/e2/e3/e4"), toKey("k4")))
abortIfError(s.Add("b1", up("u1/u5"), ep("e1/e5"), toKey("k5")))
abortIfError(s.Add("b1", up("u6"), ep("e6"), toKey("k6")))
abortIfError(s.Add("b1", up("u6/u7/u8"), ep("e6/e7/e8"), toKey("k8")))
abortIfError(s.Add("b2", up("u1"), ep("e1'"), toKey("k1")))
abortIfError(s.Add("b3", paths.Unencrypted{}, paths.Encrypted{}, toKey("m1")))

// Look up some complicated queries by the unencrypted path.
printLookup(s.LookupUnencrypted("b1", up("u1")))
printLookup(s.LookupUnencrypted("b1", up("u1/u2/u3")))
printLookup(s.LookupUnencrypted("b1", up("u1/u2/u3/u6")))
printLookup(s.LookupUnencrypted("b1", up("u1/u2/u3/u4")))
printLookup(s.LookupUnencrypted("b1", up("u6/u7")))
printLookup(s.LookupUnencrypted("b2", up("u1")))
printLookup(s.LookupUnencrypted("b3", paths.Unencrypted{}))
printLookup(s.LookupUnencrypted("b3", up("z1")))

fmt.Println()

// Look up some complicated queries by the encrypted path.
printLookup(s.LookupEncrypted("b1", ep("e1")))
printLookup(s.LookupEncrypted("b1", ep("e1/e2/e3")))
printLookup(s.LookupEncrypted("b1", ep("e1/e2/e3/e6")))
printLookup(s.LookupEncrypted("b1", ep("e1/e2/e3/e4")))
printLookup(s.LookupEncrypted("b1", ep("e6/e7")))
printLookup(s.LookupEncrypted("b2", ep("e1'")))
printLookup(s.LookupEncrypted("b3", paths.Encrypted{}))
printLookup(s.LookupEncrypted("b3", ep("z1")))

Output:


<map["e2":"u2" "e5":"u5"], "u1", nil>
<map["e4":"u4"], "u1/u2/u3", <"u1/u2/u3", "e1/e2/e3", "k3">>
<map[], "u1/u2/u3/", <"u1/u2/u3", "e1/e2/e3", "k3">>
<map[], "u1/u2/u3/u4", <"u1/u2/u3/u4", "e1/e2/e3/e4", "k4">>
<map["e8":"u8"], "u6/", <"u6", "e6", "k6">>
<map[], "u1", <"u1", "e1'", "k1">>
<map[], "", <"", "", "m1">>
<map[], "", <"", "", "m1">>

<map["u2":"e2" "u5":"e5"], "e1", nil>
<map["u4":"e4"], "e1/e2/e3", <"u1/u2/u3", "e1/e2/e3", "k3">>
<map[], "e1/e2/e3/", <"u1/u2/u3", "e1/e2/e3", "k3">>
<map[], "e1/e2/e3/e4", <"u1/u2/u3/u4", "e1/e2/e3/e4", "k4">>
<map["u8":"e8"], "e6/", <"u6", "e6", "k6">>
<map[], "e1'", <"u1", "e1'", "k1">>
<map[], "", <"", "", "m1">>
<map[], "", <"", "", "m1">>

func NewStore added in v0.14.2 

func NewStore() *Store

NewStore constructs a Store.

func (*Store) Add added in v0.14.2 

func (s *Store) Add(bucket string, unenc paths.Unencrypted, enc paths.Encrypted, key storj.Key) error

Add creates a mapping from the unencrypted path to the encrypted path and key.

func (*Store) GetDefaultKey added in v0.14.4 

func (s *Store) GetDefaultKey() *storj.Key

GetDefaultKey returns the default key, or nil if none has been set.

func (*Store) Iterate added in v0.14.4 

func (s *Store) Iterate(fn func(string, paths.Unencrypted, paths.Encrypted, storj.Key) error) error

Iterate executes the callback with every value that has been Added to the Store.

func (*Store) LookupEncrypted added in v0.14.2 

func (s *Store) LookupEncrypted(bucket string, path paths.Encrypted) (
	revealed map[string]string, consumed paths.Encrypted, base *Base)

LookupEncrypted finds the matching most encrypted path added to the Store, reports how much of the path matched, any known encrypted paths at the requested path, and if a key an encrypted path exists for some prefix of the encrypted path.

func (*Store) LookupUnencrypted added in v0.14.2 

func (s *Store) LookupUnencrypted(bucket string, path paths.Unencrypted) (
	revealed map[string]string, consumed paths.Unencrypted, base *Base)

LookupUnencrypted finds the matching most unencrypted path added to the Store, reports how much of the path matched, any known unencrypted paths at the requested path, and if a key and encrypted path exists for some prefix of the unencrypted path.

func (*Store) SetDefaultKey added in v0.14.2 

func (s *Store) SetDefaultKey(defaultKey *storj.Key)

SetDefaultKey adds a default key to be returned for any lookup that does not match a bucket.

type Transformer 

type Transformer interface {
	InBlockSize() int  // The block size prior to transformation
	OutBlockSize() int // The block size after transformation
	Transform(out, in []byte, blockNum int64) ([]byte, error)
}

A Transformer is a data transformation that may change the size of the blocks of data it operates on in a deterministic fashion.

func NewAESGCMDecrypter 

func NewAESGCMDecrypter(key *storj.Key, startingNonce *AESGCMNonce, encryptedBlockSize int) (Transformer, error)

NewAESGCMDecrypter returns a Transformer that decrypts the data passing through with key. See the comments for NewAESGCMEncrypter about startingNonce.

func NewAESGCMEncrypter 

func NewAESGCMEncrypter(key *storj.Key, startingNonce *AESGCMNonce, encryptedBlockSize int) (Transformer, error)

NewAESGCMEncrypter returns a Transformer that encrypts the data passing through with key.

startingNonce is treated as a big-endian encoded unsigned integer, and as blocks pass through, their block number and the starting nonce is added together to come up with that block's nonce. Encrypting different data with the same key and the same nonce is a huge security issue. It's safe to always encode new data with a random key and random startingNonce. The monotonically-increasing nonce (that rolls over) is to protect against data reordering.

When in doubt, generate a new key from crypto/rand and a startingNonce from crypto/rand as often as possible.

func NewDecrypter 

func NewDecrypter(cipher storj.CipherSuite, key *storj.Key, startingNonce *storj.Nonce, encryptedBlockSize int) (Transformer, error)

NewDecrypter creates a Transformer using the given cipher, key and nonce to decrypt data passing through it

func NewEncrypter 

func NewEncrypter(cipher storj.CipherSuite, key *storj.Key, startingNonce *storj.Nonce, encryptedBlockSize int) (Transformer, error)

NewEncrypter creates a Transformer using the given cipher, key and nonce to encrypt data passing through it

func NewSecretboxDecrypter 

func NewSecretboxDecrypter(key *storj.Key, startingNonce *storj.Nonce, encryptedBlockSize int) (Transformer, error)

NewSecretboxDecrypter returns a Transformer that decrypts the data passing through with key. See the comments for NewSecretboxEncrypter about startingNonce.

func NewSecretboxEncrypter 

func NewSecretboxEncrypter(key *storj.Key, startingNonce *storj.Nonce, encryptedBlockSize int) (Transformer, error)

NewSecretboxEncrypter returns a Transformer that encrypts the data passing through with key.

startingNonce is treated as a big-endian encoded unsigned integer, and as blocks pass through, their block number and the starting nonce is added together to come up with that block's nonce. Encrypting different data with the same key and the same nonce is a huge security issue. It's safe to always encode new data with a random key and random startingNonce. The monotonically-increasing nonce (that rolls over) is to protect against data reordering.

When in doubt, generate a new key from crypto/rand and a startingNonce from crypto/rand as often as possible.

Source Files

View all Source files

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.