Documentation ¶
Overview ¶
Package appencryption contains the implementation to securely persist and encrypt data in the public cloud. Your main interaction with the library will most likely be the SessionFactory which should be created on application start up and stored for the lifetime of the app.
A session should closed as close as possible to the creation of the session. It should also be short lived to avoid running into the limits on the amount of memory that can be locked. See mlock documentation on how to set/check the current limits. It can also be checked using ulimit.
Index ¶
- Constants
- type AEAD
- type Config
- type CryptoPolicy
- type DataRowRecord
- type Encryption
- type EnvelopeKeyRecord
- type FactoryOption
- type KeyManagementService
- type KeyMeta
- type Loader
- type Metastore
- type PolicyOption
- func WithExpireAfterDuration(d time.Duration) PolicyOption
- func WithNoCache() PolicyOption
- func WithRevokeCheckInterval(d time.Duration) PolicyOption
- func WithSessionCache() PolicyOption
- func WithSessionCacheDuration(d time.Duration) PolicyOption
- func WithSessionCacheMaxSize(size int) PolicyOption
- func WithSharedIntermediateKeyCache(capacity int) PolicyOption
- type Session
- func (s *Session) Close() error
- func (s *Session) Decrypt(ctx context.Context, d DataRowRecord) ([]byte, error)
- func (s *Session) Encrypt(ctx context.Context, data []byte) (*DataRowRecord, error)
- func (s *Session) Load(ctx context.Context, key interface{}, store Loader) ([]byte, error)
- func (s *Session) Store(ctx context.Context, payload []byte, store Storer) (interface{}, error)
- type SessionFactory
- type Storer
Constants ¶
const ( // CacheTypeSystemKeys is used to cache system keys. CacheTypeSystemKeys cacheKeyType = iota // CacheTypeIntermediateKeys is used to cache intermediate keys. CacheTypeIntermediateKeys )
const ( DefaultExpireAfter = time.Hour * 24 * 90 // 90 days DefaultRevokedCheckInterval = time.Minute * 60 DefaultCreateDatePrecision = time.Minute DefaultKeyCacheMaxSize = 1000 DefaultSessionCacheMaxSize = 1000 DefaultSessionCacheDuration = time.Hour * 2 DefaultSessionCacheEngine = "default" )
Default values for CryptoPolicy if not overridden.
const AES256KeySize int = 32
AES256KeySize is the size of the AES key used by the AEAD implementation
const MetricsPrefix = "ael"
MetricsPrefix prefixes all metrics names
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AEAD ¶
type AEAD interface { // Encrypt encrypts data using the provided key bytes. Encrypt(data, key []byte) ([]byte, error) // Decrypt decrypts data using the provided key bytes. Decrypt(data, key []byte) ([]byte, error) }
AEAD contains the functions required to encrypt and decrypt data using a specific cipher.
type Config ¶
type Config struct { // Service is the identifier for this service. Service string // Product is the identifier for the team or group that owns the calling service. Product string // Policy contains the information on when to expire keys. // If no policy is provided, 90 days rotations will be set // as defaults. Policy *CryptoPolicy }
Config contains the required information to setup and use this library.
type CryptoPolicy ¶
type CryptoPolicy struct { // ExpireKeyAfter is used to determine when a key is considered expired based on its creation time // (regularly-scheduled rotation). ExpireKeyAfter time.Duration // RevokeCheckInterval controls the cache TTL (if caching is enabled) to check if a cached key has been marked as // revoked (irregularly-scheduled rotation). RevokeCheckInterval time.Duration // CreateDatePrecision is used to truncate a new key's creation timestamp to avoid concurrent callers from // excessively creating keys in race condition scenarios. CreateDatePrecision time.Duration // CacheIntermediateKeys determines whether Intermediate Keys will be cached. CacheIntermediateKeys bool // IntermediateKeyCacheMaxSize controls the maximum size of the cache if intermediate key caching is enabled. IntermediateKeyCacheMaxSize int // IntermediateKeyCacheEvictionPolicy controls the eviction policy to use for the shared cache. // Supported values are "lru", "lfu", "slru", and "tinylfu". Default is "lru". IntermediateKeyCacheEvictionPolicy string // Intermediate Keys will share a single cache across all sessions for a given factory. // This option is useful if you have a large number of sessions and want to reduce the memory footprint of the // cache. // // This option is ignored if CacheIntermediateKeys is disabled. SharedIntermediateKeyCache bool // CacheSystemKeys determines whether System Keys will be cached. CacheSystemKeys bool // SystemKeyCacheMaxSize controls the maximum size of the cache if system key caching is enabled. If // SharedKeyCache is enabled, this value will determine the maximum size of the shared cache. SystemKeyCacheMaxSize int // SystemKeyCacheEvictionPolicy controls the eviction policy to use for the shared cache. // Supported values are "lru", "lfu", "slru", and "tinylfu". Default is "lru". SystemKeyCacheEvictionPolicy string // CacheSessions determines whether sessions will be cached. CacheSessions bool // SessionCacheMaxSize controls the maximum size of the cache if session caching is enabled. SessionCacheMaxSize int // SessionCacheDuration controls the amount of time a session will remain cached without being accessed // if session caching is enabled. SessionCacheDuration time.Duration // SessionCacheEvictionPolicy controls the eviction policy to use for the shared cache. // Supported values are "lru", "lfu", "slru", and "tinylfu". Default is "slru". SessionCacheEvictionPolicy string }
CryptoPolicy contains options to customize various behaviors in the SDK.
func NewCryptoPolicy ¶
func NewCryptoPolicy(opts ...PolicyOption) *CryptoPolicy
NewCryptoPolicy returns a new CryptoPolicy with default values.
type DataRowRecord ¶
type DataRowRecord struct { Key *EnvelopeKeyRecord Data []byte }
DataRowRecord contains the encrypted key and provided data, as well as the information required to decrypt the key encryption key. This struct should be stored in your data persistence as it's required to decrypt data.
type Encryption ¶
type Encryption interface { // EncryptPayload encrypts a provided slice of bytes and returns a DataRowRecord which contains // required information to decrypt the data in the future. EncryptPayload(ctx context.Context, data []byte) (*DataRowRecord, error) // DecryptDataRowRecord decrypts a DataRowRecord key and returns the original byte slice // provided to the encrypt function. DecryptDataRowRecord(ctx context.Context, d DataRowRecord) ([]byte, error) // Close frees up any resources. It should be called as soon as an instance is // no longer in use. Close() error }
Encryption implements the required methods to perform encryption/decryption on a payload
type EnvelopeKeyRecord ¶
type EnvelopeKeyRecord struct { Revoked bool `json:"Revoked,omitempty"` ID string `json:"-"` Created int64 `json:"Created"` EncryptedKey []byte `json:"Key"` ParentKeyMeta *KeyMeta `json:"ParentKeyMeta,omitempty"` }
EnvelopeKeyRecord represents an encrypted key and is the data structure used to persist the key in our key table. It also contains the meta data of the key used to encrypt it.
type FactoryOption ¶
type FactoryOption func(*SessionFactory)
FactoryOption is used to configure additional options in a SessionFactory.
func WithMetrics ¶
func WithMetrics(enabled bool) FactoryOption
WithMetrics enables or disables metrics.
func WithSecretFactory ¶
func WithSecretFactory(f securememory.SecretFactory) FactoryOption
WithSecretFactory sets the factory to use for creating Secrets
type KeyManagementService ¶
type KeyManagementService interface { // EncryptKey takes in an unencrypted byte slice and encrypts it with the master key. // The returned value should then be inserted into the Metastore before being // used. EncryptKey(context.Context, []byte) ([]byte, error) // DecryptKey decrypts the encrypted byte slice using the master key. DecryptKey(context.Context, []byte) ([]byte, error) }
KeyManagementService contains the logic required to encrypt a system key with a master key.
type KeyMeta ¶
KeyMeta contains the ID and Created timestamp for an encryption key.
func (KeyMeta) AsLatest ¶ added in v0.4.0
AsLatest returns a copy of the key meta with the Created timestamp set to 0.
type Loader ¶ added in v0.1.6
type Loader interface { // Load returns a DataRowRecord corresponding to the specified key, if found, along with any errors encountered. Load(ctx context.Context, key interface{}) (*DataRowRecord, error) }
Loader declares the behavior for loading data from a persistence store.
type Metastore ¶
type Metastore interface { // Load retrieves a specific key by id and created timestamp. // The return value will be nil if not already present. Load(ctx context.Context, id string, created int64) (*EnvelopeKeyRecord, error) // LoadLatest returns the latest key matching the provided ID. // The return value will be nil if not already present. LoadLatest(ctx context.Context, id string) (*EnvelopeKeyRecord, error) // Store attempts to insert the key into the metastore if one is not // already present. If a key exists, the method will return false. If // one is not present, the value will be inserted and we return true. Store(ctx context.Context, id string, created int64, envelope *EnvelopeKeyRecord) (bool, error) }
Metastore implements the required methods to retrieve an encryption key from it's storage.
type PolicyOption ¶
type PolicyOption func(*CryptoPolicy)
PolicyOption is used to configure a CryptoPolicy.
func WithExpireAfterDuration ¶
func WithExpireAfterDuration(d time.Duration) PolicyOption
WithExpireAfterDuration sets amount of time a key is considered valid.
func WithNoCache ¶
func WithNoCache() PolicyOption
WithNoCache disables caching of both System and Intermediate Keys.
func WithRevokeCheckInterval ¶
func WithRevokeCheckInterval(d time.Duration) PolicyOption
WithRevokeCheckInterval sets the interval to check for revoked keys in the cache.
func WithSessionCache ¶ added in v0.1.3
func WithSessionCache() PolicyOption
WithSessionCache enables session caching. When used all sessions for a given partition will share underlying System and Intermediate Key caches.
func WithSessionCacheDuration ¶ added in v0.1.3
func WithSessionCacheDuration(d time.Duration) PolicyOption
WithSessionCacheDuration specifies the amount of time a session will remain cached without being accessed if session caching is enabled.
func WithSessionCacheMaxSize ¶ added in v0.1.3
func WithSessionCacheMaxSize(size int) PolicyOption
WithSessionCacheMaxSize specifies the session cache max size to use if session caching is enabled.
func WithSharedIntermediateKeyCache ¶ added in v0.4.0
func WithSharedIntermediateKeyCache(capacity int) PolicyOption
WithSharedIntermediateKeyCache enables a shared cache for Intermediate Keys with the provided capacity. The shared cache will be used by all sessions for a given factory.
type Session ¶
type Session struct {
// contains filtered or unexported fields
}
Session is used to encrypt and decrypt data related to a specific partition ID.
func (*Session) Close ¶
Close will close any open resources owned by this session (e.g. cache of keys). It should be called as soon as it's no longer in use.
func (*Session) Decrypt ¶
Decrypt decrypts a DataRowRecord and returns the original byte slice provided to the encrypt function.
func (*Session) Encrypt ¶
Encrypt encrypts a provided slice of bytes and returns a DataRowRecord, which contains required information to decrypt the data in the future.
func (*Session) Load ¶ added in v0.1.6
Load uses a persistence key to load a DataRowRecord from the provided data persistence store, if any, and returns the decrypted payload.
type SessionFactory ¶
type SessionFactory struct { Config *Config Metastore Metastore Crypto AEAD KMS KeyManagementService SecretFactory securememory.SecretFactory // contains filtered or unexported fields }
SessionFactory is used to create new encryption sessions and manage the lifetime of the intermediate keys.
func NewSessionFactory ¶
func NewSessionFactory(config *Config, store Metastore, kms KeyManagementService, crypto AEAD, opts ...FactoryOption) *SessionFactory
NewSessionFactory creates a new session factory with default implementations.
func (*SessionFactory) Close ¶
func (f *SessionFactory) Close() error
Close will close any open resources owned by this factory (e.g. cache of system keys). It should be called when the factory is no longer required
func (*SessionFactory) GetSession ¶
func (f *SessionFactory) GetSession(id string) (*Session, error)
GetSession returns a new session for the provided partition ID.
Source Files ¶
Directories ¶
Path | Synopsis |
---|---|
cmd
|
|
example
Module
|
|
integrationtest
module
|
|
pkg
|
|
cache
Package cache provides a cache implementation with support for multiple eviction policies.
|
Package cache provides a cache implementation with support for multiple eviction policies. |
cache/internal
Package internal contains data structures used by cache implementations.
|
Package internal contains data structures used by cache implementations. |
log
Package log implements simple logging functionality with a focus on debug level logging.
|
Package log implements simple logging functionality with a focus on debug level logging. |