Documentation
¶
Index ¶
- Constants
- Variables
- func Copy(dst, src []byte)
- func Decrypt(ciphertext, key []byte, output []byte) (int, error)
- func EnclaveSize(e *Enclave) int
- func Encrypt(plaintext, key []byte) ([]byte, error)
- func Equal(x, y []byte) bool
- func Exit(c int)
- func Hash(b []byte) []byte
- func Move(dst, src []byte)
- func Panic(v interface{})
- func Purge()
- func Scramble(buf []byte) error
- func Wipe(buf []byte)
- type Buffer
- type Coffer
- type Enclave
Constants ¶
const Overhead int = secretbox.Overhead + 24 // auth + nonce
Overhead is the size by which the ciphertext exceeds the plaintext.
Variables ¶
var ErrBufferExpired = errors.New("<memguard::core::ErrBufferExpired> buffer has been purged from memory and can no longer be used")
ErrBufferExpired is returned when attempting to perform an operation on or with a buffer that has been destroyed.
var ErrBufferTooSmall = errors.New("<memguard::core::ErrBufferTooSmall> the given buffer is too small to hold the plaintext")
ErrBufferTooSmall is returned when the decryption function, Open, is given an output buffer that is too small to hold the plaintext. In practice the plaintext will be Overhead bytes smaller than the ciphertext returned by the encryption function, Seal.
var ErrCofferExpired = errors.New("<memguard::core::ErrCofferExpired> attempted usage of destroyed key object")
ErrCofferExpired is returned when a function attempts to perform an operation using a secure key container that has been wiped and destroyed.
var ErrDecryptionFailed = errors.New("<memguard::core::ErrDecryptionFailed> decryption failed: key is wrong or ciphertext is corrupt")
ErrDecryptionFailed is returned when the attempted decryption fails. This can occur if the given key is incorrect or if the ciphertext is invalid.
var ErrInvalidKeyLength = errors.New("<memguard::core::ErrInvalidKeyLength> key must be exactly 32 bytes")
ErrInvalidKeyLength is returned when attempting to encrypt or decrypt with a key that is not exactly 32 bytes in size.
var ErrNullBuffer = errors.New("<memguard::core::ErrNullBuffer> buffer size must be greater than zero")
ErrNullBuffer is returned when attempting to construct a buffer of size less than one.
var ErrNullEnclave = errors.New("<memguard::core::ErrNullEnclave> enclave size must be greater than zero")
ErrNullEnclave is returned when attempting to construct an enclave of size less than one.
Functions ¶
func Copy ¶
func Copy(dst, src []byte)
Copy is identical to Go's builtin copy function except the copying is done in constant time. This is to mitigate against side-channel attacks.
func Decrypt ¶
Decrypt decrypts a given ciphertext with a given 32 byte key and writes the result to the start of a given buffer.
The buffer must be large enough to contain the decrypted data. This is in practice Overhead bytes less than the length of the ciphertext returned by the Seal function above. This value is the size of the nonce plus the size of the Poly1305 authenticator.
The size of the decrypted data is returned.
func EnclaveSize ¶ added in v0.20.0
EnclaveSize returns the number of bytes of plaintext data stored inside an Enclave.
func Encrypt ¶
Encrypt takes a plaintext message and a 32 byte key and returns an authenticated ciphertext.
func Equal ¶
Equal does a constant-time comparison of two byte slices. This is to mitigate against side-channel attacks.
func Exit ¶
func Exit(c int)
Exit terminates the process with a specified exit code but securely wipes and cleans up sensitive data before doing so.
func Move ¶
func Move(dst, src []byte)
Move is identical to Copy except it wipes the source buffer after the copy operation is executed.
func Panic ¶
func Panic(v interface{})
Panic is identical to the builtin panic except it purges the session before calling panic.
func Purge ¶
func Purge()
Purge wipes all sensitive data and keys before reinitialising the session with a fresh encryption key and secure values. Subsequent library operations will use these fresh values and the old data is assumed to be practically unrecoverable.
The creation of new Enclave objects should wait for this function to return since subsequent Enclave objects will use the newly created key.
This function should be called before the program terminates, or else the provided Exit or Panic functions should be used to terminate.
Types ¶
type Buffer ¶
type Buffer struct {
sync.RWMutex // Local mutex lock // TODO: this does not protect 'data' field
// contains filtered or unexported fields
}
Buffer is a structure that holds raw sensitive data.
The number of Buffers that can exist at one time is limited by how much memory your system's kernel allows each process to mlock/VirtualLock. Therefore you should call DestroyBuffer on Buffers that you no longer need, ideally defering a Destroy call after creating a new one.
func Open ¶
Open decrypts an Enclave and puts the contents into a Buffer object. The given Enclave is left untouched and may be reused.
The Buffer object should be destroyed after the contents are no longer needed.
func (*Buffer) Destroy ¶
func (b *Buffer) Destroy()
Destroy performs some security checks, securely wipes the contents of, and then releases a Buffer's memory back to the OS. If a security check fails, the process will attempt to wipe all it can before safely panicking.
If the Buffer has already been destroyed, the function does nothing and returns nil.
func (*Buffer) Freeze ¶
func (b *Buffer) Freeze()
Freeze makes the underlying memory of a given buffer immutable. This will do nothing if the Buffer has been destroyed.
func (*Buffer) Inner ¶ added in v0.20.1
Inner returns a byte slice representing the entire inner memory pages. This should NOT be used unless you have a specific need.
func (*Buffer) Melt ¶
func (b *Buffer) Melt()
Melt makes the underlying memory of a given buffer mutable. This will do nothing if the Buffer has been destroyed.
type Coffer ¶
Coffer is a specialized container for securing highly-sensitive, 32 byte values.
func (*Coffer) Destroy ¶
Destroy wipes and cleans up all memory related to a Coffer object. Once this method has been called, the Coffer can no longer be used and a new one should be created instead.
func (*Coffer) Destroyed ¶
Destroyed returns a boolean value indicating if a Coffer has been destroyed.
func (*Coffer) Init ¶ added in v0.22.3
Init is used to reset the value stored inside a Coffer to a new random 32 byte value, overwriting the old.
type Enclave ¶
type Enclave struct {
// contains filtered or unexported fields
}
Enclave is a sealed and encrypted container for sensitive data.
func NewEnclave ¶
NewEnclave is a raw constructor for the Enclave object. The given buffer is wiped after the enclave is created.
Source Files