Documentation
¶
Overview ¶
Package cell provides Themis Secure Cell.
Secure Сell is a high-level cryptographic service, aimed to protect arbitrary data being stored in various types of storages (like databases, filesystem files, document archives, cloud storage etc). It provides a simple way to secure your data using strong encryption and data authentication mechanisms, with easy-to-use interfaces for broad range of use-cases.
Implementing secure storage is often constrained by various practical matters – ability to store keys, existence of length-sensitive code bound to database structure, requirements to preserve structure. To cover a broader range of usage scenarios and provide highest security level for systems with such constraints, we’ve designed several types of interfaces and implementations of secure data container, Secure Cell. They slightly differ in overall security level and ease of use: more complicated and slightly less secure ones can cover more constrained environments though. Interfaces below are prioritized by our preference, which takes only security and ease of use into account.
“SecureCellSeal” is the most secure and the easiest one to use.
“SecureCellTokenProtect” is able to preserve the encrypted data length but requires separate data storage to be available.
“SecureCellContextImprint” preserves encrypted data length too, but at a cost of slightly lower security and more involved interface.
Read more about Secure Cell modes here:
https://docs.cossacklabs.com/themis/crypto-theory/cryptosystems/secure-cell/
Index ¶
Examples ¶
Constants ¶
const ( ModeSeal = iota ModeTokenProtect ModeContextImprint )
Secure Cell operation mode.
Deprecated: Since 0.13. Use SealWithKey(), TokenProtectWithKey(), ContextImprintWithKey() constructutors instead.
const ( CELL_MODE_SEAL = ModeSeal CELL_MODE_TOKEN_PROTECT = ModeTokenProtect CELL_MODE_CONTEXT_IMPRINT = ModeContextImprint )
Secure Cell operation mode.
Deprecated: Since 0.13. Use SealWithKey(), TokenProtectWithKey(), ContextImprintWithKey() constructutors instead.
Variables ¶
var ( ErrGetOutputSize = errors.New("failed to get output size") ErrEncryptData = errors.New("failed to protect data") ErrDecryptData = errors.New("failed to unprotect data") ErrInvalidMode = errors.NewWithCode(errors.InvalidParameter, "invalid Secure Cell mode specified") ErrMissingKey = errors.NewWithCode(errors.InvalidParameter, "empty symmetric key for Secure Cell") ErrMissingPassphrase = errors.NewWithCode(errors.InvalidParameter, "empty passphrase for Secure Cell") ErrMissingMessage = errors.NewWithCode(errors.InvalidParameter, "empty message for Secure Cell") ErrMissingToken = errors.NewWithCode(errors.InvalidParameter, "authentication token is required in Token Protect mode") ErrMissingContext = errors.NewWithCode(errors.InvalidParameter, "associated context is required in Context Imprint mode") ErrOutOfMemory = errors.NewWithCode(errors.NoMemory, "Secure Cell cannot allocate enough memory") // Deprecated: Since 0.14. Use ErrOutOfMemory instead. ErrOverflow = ErrOutOfMemory )
Errors returned by Secure Cell.
Functions ¶
This section is empty.
Types ¶
type SecureCell
deprecated
type SecureCell struct {
// contains filtered or unexported fields
}
SecureCell is a high-level cryptographic service aimed at protecting arbitrary data stored in various types of storage
Deprecated: Since 0.13. Use SecureCellSeal, SecureCellTokenProtect, SecureCellContextImprint instead.
func New
deprecated
func New(key []byte, mode int) *SecureCell
New makes a new Secure Cell with master key and specified mode.
Deprecated: Since 0.13. Use SealWithKey(), TokenProtectWithKey(), ContextImprintWithKey() constructutors instead.
type SecureCellContextImprint ¶ added in v0.13.0
type SecureCellContextImprint struct {
// contains filtered or unexported fields
}
SecureCellContextImprint is Secure Cell in Context Imprint mode.
The data is protected by a secret symmetric key. Use keys.NewSymmetricKey() to generate keys suitable for Secure Cell.
Context Imprint mode is intended for environments where storage constraints do not allow the size of the data to grow and there is no auxiliary storage available. Context Imprint mode requires an additional “associated context” to be provided along with the secret in order to protect the data.
In Context Imprint mode no authentication token is computed or verified. This means the integrity of the data is not enforced, so the overall security level is slightly lower than in Seal or Token Protect modes.
To ensure highest security level possible, supply a different associated context for each encryption invocation with the same secret.
Read more about Context Imprint mode here:
https://docs.cossacklabs.com/themis/crypto-theory/cryptosystems/secure-cell/#context-imprint-mode
Example ¶
key, err := keys.NewSymmetricKey()
if err != nil {
return
}
cell, err := ContextImprintWithKey(key)
if err != nil {
return
}
message := []byte("I was... Um, I was wondering why you're carrying the same bat.")
context := []byte("Even though he joined a team, he never played any sports.")
encrypted, err := cell.Encrypt(message, context)
if err != nil {
return
}
decrypted, err := cell.Decrypt(encrypted, context)
if err != nil {
return
}
fmt.Println(string(decrypted))
Output: I was... Um, I was wondering why you're carrying the same bat.
func ContextImprintWithKey ¶ added in v0.13.0
func ContextImprintWithKey(key *keys.SymmetricKey) (*SecureCellContextImprint, error)
ContextImprintWithKey makes a new Secure Cell in Context Imprint mode secured by a symmetric key.
func (*SecureCellContextImprint) Decrypt ¶ added in v0.13.0
func (sc *SecureCellContextImprint) Decrypt(encrypted []byte, context []byte) ([]byte, error)
Decrypt message.
Secure Cell validates association with the context data and decrypts the message. You need to provide the same context as it was used during encryption.
Non-empty decrypted data is returned if everything goes well.
Note that data integrity is not verified by Context Imprint mode: garbage in — garbage out. If data has been corrupted, a different key is used, or the context is incorrect then Secure Cell will most likely successfully return corrupted output.
An error will be returned on failure, such as if the message or context is empty, or in case of some internal failure in cryptographic backend.
func (*SecureCellContextImprint) Encrypt ¶ added in v0.13.0
func (sc *SecureCellContextImprint) Encrypt(message []byte, context []byte) ([]byte, error)
Encrypt message.
Message is encrypted and provided context is cryptographically mixed with the data, but is not included into the resulting encrypted message. You will have to provide the same context again during decryption. Usually this is some plaintext data associated with encrypted data, such as database row number, protocol message ID, etc.
Encrypted data is returned as a single byte slice of the same size as input, it cannot be authenticated later.
An error is returned on failure, such as if the message or context is empty, or in case of some internal failure in cryptographic backend.
type SecureCellSeal ¶ added in v0.13.0
type SecureCellSeal struct {
// contains filtered or unexported fields
}
SecureCellSeal is Secure Cell in Seal mode. This is the most secure and easy way to protect stored data.
The data is protected by a secret symmetric key. Use keys.NewSymmetricKey() to generate keys suitable for Secure Cell.
Secure Cell in Seal mode will encrypt the data and append an “authentication tag” to it with auxiliary security information. This means that that size of the encrypted data will be larger than the original input.
Additionally, it is possible to bind the encrypted data to some “associated context” (for example, database row number). In this case decryption of the data with incorrect context will fail (even if the secret is correct and the data has not been tampered). This establishes cryptographically secure association between the protected data and the context in which it is used. With database row numbers, for example, this prevents the attacker from swapping encrypted password hashes in the database so the system will not accept credentials of a different user.
Read more about Seal mode here:
https://docs.cossacklabs.com/themis/crypto-theory/cryptosystems/secure-cell/#seal-mode
Example ¶
key, err := keys.NewSymmetricKey()
if err != nil {
return
}
cell, err := SealWithKey(key)
if err != nil {
return
}
message := []byte("The corpse. Did you bury it properly?")
context := []byte("-- 34 to K1 in her car")
encrypted, err := cell.Encrypt(message, context)
if err != nil {
return
}
decrypted, err := cell.Decrypt(encrypted, context)
if err != nil {
return
}
fmt.Println(string(decrypted))
Output: The corpse. Did you bury it properly?
func SealWithKey ¶ added in v0.13.0
func SealWithKey(key *keys.SymmetricKey) (*SecureCellSeal, error)
SealWithKey makes a new Secure Cell in Seal mode secured by a symmetric key.
func (*SecureCellSeal) Decrypt ¶ added in v0.13.0
func (sc *SecureCellSeal) Decrypt(encrypted, context []byte) ([]byte, error)
Decrypt message.
Secure Cell validates association with the context data, decrypts the message, and verifies its integrity using authentication data embedded into the message.
You need to provide the same context as used during encryption. (If there was no context you can use empty or nil value).
Non-empty decrypted data is returned if everything goes well.
An error will be returned on failure, such as if the message is empty, or if the data has been tampered with, or if the secret or associated context do not match the ones used for encryption.
func (*SecureCellSeal) Encrypt ¶ added in v0.13.0
func (sc *SecureCellSeal) Encrypt(message, context []byte) ([]byte, error)
Encrypt message.
Message is encrypted and authentication token is appended to it, forming a single sealed buffer.
The context, if provided, is cryptographically mixed with the data, but is not included into the resulting encrypted message. You will have to provide the same context again during decryption. Usually this is some plaintext data associated with encrypted data, such as database row number, protocol message ID, etc. Empty and nil contexts are identical.
Encrypted data is returned as a single byte slice.
An error is returned on failure, such as if the message is empty, or in case of some internal failure in cryptographic backend.
type SecureCellSealPassphrase ¶ added in v0.13.0
type SecureCellSealPassphrase struct {
// contains filtered or unexported fields
}
SecureCellSealPassphrase is Secure Cell in Seal mode. This is the most secure and easy way to protect stored data.
The data is protected by a secret passphrase. You can safely use relatively short, human-readable passwords with this mode.
If you do not need to keep the secret in the head and would rather write it into a file, consider using symmetric keys. See “cell.SealWithKey()” and “SecureCellSeal”.
Read more about Seal mode here:
https://docs.cossacklabs.com/themis/crypto-theory/cryptosystems/secure-cell/#seal-mode
Example ¶
cell, err := SealWithPassphrase("friendship")
if err != nil {
return
}
message := []byte("Would you show me your... seal?")
context := []byte("Why would you ask for such a thing?")
encrypted, err := cell.Encrypt(message, context)
if err != nil {
return
}
decrypted, err := cell.Decrypt(encrypted, context)
if err != nil {
return
}
fmt.Println(string(decrypted))
Output: Would you show me your... seal?
func SealWithPassphrase ¶ added in v0.13.0
func SealWithPassphrase(passphrase string) (*SecureCellSealPassphrase, error)
SealWithPassphrase makes a new Secure Cell in Seal mode secured by a passphrase.
func (*SecureCellSealPassphrase) Decrypt ¶ added in v0.13.0
func (sc *SecureCellSealPassphrase) Decrypt(encrypted, context []byte) ([]byte, error)
Decrypt message.
Secure Cell validates association with the context data, decrypts the message, and verifies its integrity using authentication data embedded into the message.
You need to provide the same context as used during encryption. (If there was no context you can use empty or nil value).
Non-empty decrypted data is returned if everything goes well.
An error will be returned on failure, such as if the message is empty, or if the data has been tampered with, or if the secret or associated context do not match the ones used for encryption.
func (*SecureCellSealPassphrase) Encrypt ¶ added in v0.13.0
func (sc *SecureCellSealPassphrase) Encrypt(message, context []byte) ([]byte, error)
Encrypt message.
Message is encrypted and authentication token is appended to it, forming a single sealed buffer.
The context, if provided, is cryptographically mixed with the data, but is not included into the resulting encrypted message. You will have to provide the same context again during decryption. Usually this is some plaintext data associated with encrypted data, such as database row number, protocol message ID, etc. Empty and nil contexts are identical.
Encrypted data is returned as a single byte slice.
An error is returned on failure, such as if the message is empty, or in case of some internal failure in cryptographic backend.
type SecureCellTokenProtect ¶ added in v0.13.0
type SecureCellTokenProtect struct {
// contains filtered or unexported fields
}
SecureCellTokenProtect is Secure Cell in Token Protect mode.
The data is protected by a secret symmetric key. Use keys.NewSymmetricKey() to generate keys suitable for Secure Cell.
Token Protect mode is designed for cases when underlying storage constraints do not allow the size of the data to grow (so Seal mode cannot be used). However, if you have access to a different storage location (e.g., another table in the database) where additional security parameters can be stored then Token Protect mode can be used instead of Seal mode.
Token Protect mode produces authentication tag and other auxiliary data (aka “authentication token”) in a detached buffer. This keeps the original size of the encrypted data while enabling separate storage of security information. Note that the same token must be provided along with the correct secret and matching associated context in order for the data to be decrypted successfully.
Since Token Protect mode uses the same security parameters as Seal mode (just stored in a different location), these modes have the same highest security level. Token Protect mode only requires slightly more effort in exchange for preserving the original data size.
Read more about Token Protect mode here:
https://docs.cossacklabs.com/themis/crypto-theory/cryptosystems/secure-cell/#token-protect-mode
Example ¶
key, err := keys.NewSymmetricKey()
if err != nil {
return
}
cell, err := TokenProtectWithKey(key)
if err != nil {
return
}
message := []byte("Should we speak in my car?")
context := []byte("I have AC running there")
encrypted, token, err := cell.Encrypt(message, context)
if err != nil {
return
}
decrypted, err := cell.Decrypt(encrypted, token, context)
if err != nil {
return
}
fmt.Println(string(decrypted))
Output: Should we speak in my car?
func TokenProtectWithKey ¶ added in v0.13.0
func TokenProtectWithKey(key *keys.SymmetricKey) (*SecureCellTokenProtect, error)
TokenProtectWithKey makes a new Secure Cell in Token Protect mode secured by a symmetric key.
func (*SecureCellTokenProtect) Decrypt ¶ added in v0.13.0
func (sc *SecureCellTokenProtect) Decrypt(encrypted, token, context []byte) ([]byte, error)
Decrypt message.
Secure Cell validates association with the context data, decrypts the message, and verifies data integrity using the provided authentication token.
You need to provide the same context as used during encryption. (If there was no context you can use empty or nil value).
Non-empty decrypted data is returned if everything goes well.
An error will be returned on failure, such as if the message or token is empty, or if the data has been tampered with, or if the secret or associated context do not match the ones used for encryption.
func (*SecureCellTokenProtect) Encrypt ¶ added in v0.13.0
func (sc *SecureCellTokenProtect) Encrypt(message, context []byte) (encrypted, token []byte, e error)
Encrypt message.
Message is encrypted and authentication token is produced separately.
The context, if provided, is cryptographically mixed with the data, but is not included into the resulting encrypted message. You will have to provide the same context again during decryption. Usually this is some plaintext data associated with encrypted data, such as database row number, protocol message ID, etc. Empty, and nil contexts are identical.
Encrypted data and authentication token are returned as byte slices.
An error is returned on failure, such as if the message is empty, or in case of some internal failure in cryptographic backend.
Source Files