Documentation
¶
Index ¶
- func Commands(database *bun.DB, cipher Cipher) []clicontract.Command
- func CommandsFromResolver(databaseResolver func() (*bun.DB, error), cipher Cipher) []clicontract.Command
- func UseCipher(cipherInstance Cipher)
- func UseCipherNamed(name string, cipherInstance Cipher)
- type Cipher
- type CipherRef
- type CommandContextConfig
- type EncryptDatabaseCommand
- func NewEncryptDatabaseCommand(database *bun.DB, cipher Cipher) *EncryptDatabaseCommand
- func NewEncryptDatabaseCommandFromResolver(databaseResolver func() (*bun.DB, error), cipher Cipher) *EncryptDatabaseCommand
- func NewEncryptDatabaseCommandFromResolverWithName(databaseResolver func() (*bun.DB, error), cipher Cipher, commandName string) *EncryptDatabaseCommand
- func NewEncryptDatabaseCommandWithName(database *bun.DB, cipher Cipher, commandName string) *EncryptDatabaseCommand
- type EncryptedColumn
- type EncryptedDeterministicString
- func (instance EncryptedDeterministicString) Format(state fmt.State, verb rune)
- func (instance EncryptedDeterministicString) GoString() stringdeprecated
- func (instance EncryptedDeterministicString) LogValue() slog.Value
- func (instance EncryptedDeterministicString) MarshalJSON() ([]byte, error)
- func (instance *EncryptedDeterministicString) Scan(source any) error
- func (instance EncryptedDeterministicString) String() string
- func (instance *EncryptedDeterministicString) UnmarshalJSON(data []byte) error
- func (instance EncryptedDeterministicString) Value() (driver.Value, error)
- type EncryptedDeterministicStringFor
- func (instance EncryptedDeterministicStringFor[R]) Format(state fmt.State, verb rune)
- func (instance EncryptedDeterministicStringFor[R]) GoString() stringdeprecated
- func (instance EncryptedDeterministicStringFor[R]) LogValue() slog.Value
- func (instance EncryptedDeterministicStringFor[R]) MarshalJSON() ([]byte, error)
- func (instance *EncryptedDeterministicStringFor[R]) Scan(source any) error
- func (instance EncryptedDeterministicStringFor[R]) String() string
- func (instance *EncryptedDeterministicStringFor[R]) UnmarshalJSON(data []byte) error
- func (instance EncryptedDeterministicStringFor[R]) Value() (driver.Value, error)
- type EncryptedString
- func (instance EncryptedString) Format(state fmt.State, verb rune)
- func (instance EncryptedString) GoString() stringdeprecated
- func (instance EncryptedString) LogValue() slog.Value
- func (instance EncryptedString) MarshalJSON() ([]byte, error)
- func (instance *EncryptedString) Scan(source any) error
- func (instance EncryptedString) String() string
- func (instance *EncryptedString) UnmarshalJSON(data []byte) error
- func (instance EncryptedString) Value() (driver.Value, error)
- type EncryptedStringFor
- func (instance EncryptedStringFor[R]) Format(state fmt.State, verb rune)
- func (instance EncryptedStringFor[R]) GoString() stringdeprecated
- func (instance EncryptedStringFor[R]) LogValue() slog.Value
- func (instance EncryptedStringFor[R]) MarshalJSON() ([]byte, error)
- func (instance *EncryptedStringFor[R]) Scan(source any) error
- func (instance EncryptedStringFor[R]) String() string
- func (instance *EncryptedStringFor[R]) UnmarshalJSON(data []byte) error
- func (instance EncryptedStringFor[R]) Value() (driver.Value, error)
- type KeyProvider
- type Migrator
- func (instance *Migrator) EnsureColumnCapacity(ctx context.Context, spec TableSpec) error
- func (instance *Migrator) EnsureColumnCapacityForReencrypt(ctx context.Context, spec TableSpec, targetKeyId string) error
- func (instance *Migrator) MigrateDecrypt(ctx context.Context, spec TableSpec) (int, error)
- func (instance *Migrator) MigrateEncrypt(ctx context.Context, spec TableSpec) (int, error)
- func (instance *Migrator) MigrateReencrypt(ctx context.Context, spec TableSpec, targetKeyId string) (int, error)
- type Module
- type ModuleConfig
- type StaticKeyProvider
- func (instance *StaticKeyProvider) ActiveKeyIds() []string
- func (instance *StaticKeyProvider) CurrentKeyId() string
- func (instance StaticKeyProvider) Format(state fmt.State, verb rune)
- func (instance StaticKeyProvider) GoString() stringdeprecated
- func (instance *StaticKeyProvider) Key(keyId string) ([]byte, error)
- func (instance StaticKeyProvider) String() string
- type TableSpec
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CommandsFromResolver ¶ added in v3.3.0
func CommandsFromResolver(databaseResolver func() (*bun.DB, error), cipher Cipher) []clicontract.Command
CommandsFromResolver is Commands against a lazily-resolved database: the resolver runs at the first command run instead of at construction, so the database is opened once the container is fully booted.
func UseCipher ¶
func UseCipher(cipherInstance Cipher)
UseCipher installs the process-wide default cipher used by EncryptedString and EncryptedDeterministicString. A single-database application needs nothing else; a binary with several key compartments installs one named cipher per compartment with UseCipherNamed and binds columns via EncryptedStringFor.
func UseCipherNamed ¶ added in v3.2.0
UseCipherNamed installs a named cipher — one key compartment — for columns bound through a CipherRef marker. Each named cipher owns its KeyProvider, so compartments are isolated as long as each provider holds keys of its own: the name selects the registry entry and is not bound into the ciphertext, so two compartments holding the same key under the same id decrypt each other. Merging every key into one provider loses even that, since either context can read the other's rows.
Types ¶
type Cipher ¶
type Cipher interface {
Encrypt(plaintext string) (string, error)
EncryptWithKeyId(plaintext string, keyId string) (string, error)
EncryptDeterministic(plaintext string) (string, error)
EncryptDeterministicWithKeyId(plaintext string, keyId string) (string, error)
CiphertextCandidates(plaintext string) ([][]byte, error)
Decrypt(encoded string) (string, error)
}
func NewCipher ¶
func NewCipher(keys KeyProvider) Cipher
func NewFakeCipher ¶
func NewFakeCipher() Cipher
NewFakeCipher answers a cipher whose every operation is the identity, for tests and local development. In production it writes plaintext into every encrypted column with no error, where having no cipher fails closed at the first write, so no production wiring path may reach it.
type CipherRef ¶ added in v3.2.0
type CipherRef interface {
CipherName() string
}
CipherRef binds a column type to a named cipher through the type system: a zero-size marker type implementing CipherName parameterizes EncryptedStringFor and EncryptedDeterministicStringFor, since database/sql gives Value and Scan no context.
type CommandContextConfig ¶ added in v3.2.0
type CommandContextConfig struct {
Name string
Database *bun.DB
Cipher Cipher
DatabaseFactory func(resolver containercontract.Resolver) (*bun.DB, error)
}
CommandContextConfig binds one compartment's database and cipher to a suffixed bulk command. Supply a DatabaseFactory to resolve the compartment's database from the container at the first command run; setting it together with Database is ambiguous and panics at registration.
type EncryptDatabaseCommand ¶
type EncryptDatabaseCommand struct {
// contains filtered or unexported fields
}
func NewEncryptDatabaseCommand ¶
func NewEncryptDatabaseCommand(database *bun.DB, cipher Cipher) *EncryptDatabaseCommand
func NewEncryptDatabaseCommandFromResolver ¶ added in v3.3.0
func NewEncryptDatabaseCommandFromResolver(databaseResolver func() (*bun.DB, error), cipher Cipher) *EncryptDatabaseCommand
NewEncryptDatabaseCommandFromResolver builds the command against a lazily-resolved database: the resolver runs at the first command run rather than at construction, so a registry-backed database is opened once the container is fully booted instead of at module registration. A resolver success is memoized and reused by subsequent runs; a resolver error is returned from the run and retried on the next one.
func NewEncryptDatabaseCommandFromResolverWithName ¶ added in v3.3.0
func NewEncryptDatabaseCommandFromResolverWithName( databaseResolver func() (*bun.DB, error), cipher Cipher, commandName string, ) *EncryptDatabaseCommand
NewEncryptDatabaseCommandFromResolverWithName is NewEncryptDatabaseCommandFromResolver under an explicit command name, so a multi-context binary can expose one lazily-resolved bulk command per compartment (melody:encrypt:database:<context>).
func NewEncryptDatabaseCommandWithName ¶ added in v3.2.0
func NewEncryptDatabaseCommandWithName(database *bun.DB, cipher Cipher, commandName string) *EncryptDatabaseCommand
NewEncryptDatabaseCommandWithName is NewEncryptDatabaseCommand under an explicit command name, so a multi-context binary can expose one bulk command per compartment (melody:encrypt:database:<context>).
func (*EncryptDatabaseCommand) Description ¶
func (instance *EncryptDatabaseCommand) Description() string
func (*EncryptDatabaseCommand) Flags ¶
func (instance *EncryptDatabaseCommand) Flags() []clicontract.Flag
func (*EncryptDatabaseCommand) Name ¶
func (instance *EncryptDatabaseCommand) Name() string
func (*EncryptDatabaseCommand) Run ¶
func (instance *EncryptDatabaseCommand) Run( runtimeInstance runtimecontract.Runtime, commandContext *clicontract.CommandContext, ) error
type EncryptedColumn ¶ added in v3.6.0
type EncryptedColumn interface {
// contains filtered or unexported methods
}
EncryptedColumn marks every encrypted column type, the generic instantiations included. A consumer such as the audit trail's auto-redaction matches this interface, since each generic instantiation is a distinct reflect.Type.
type EncryptedDeterministicString ¶
type EncryptedDeterministicString string
EncryptedDeterministicString is EncryptedString with the nonce derived from the plaintext, so equal plaintext seals to equal ciphertext and the column answers an equality lookup through Cipher.CiphertextCandidates. The nonce is keyed by the key and the plaintext alone, so equal values are correlatable across every deterministic column and table sealed under the same key; the readme's "Searchable (deterministic) encryption" section says what that rules the type out for.
func (EncryptedDeterministicString) Format ¶ added in v3.6.0
func (instance EncryptedDeterministicString) Format(state fmt.State, verb rune)
Format answers every verb that reaches it, the numeric ones included, with the redacted rendering; its limits are on EncryptedString.Format.
func (EncryptedDeterministicString) GoString
deprecated
added in
v3.2.0
func (instance EncryptedDeterministicString) GoString() string
Deprecated: GoString is never reached — fmt consults Formatter before GoStringer, and this type implements Format, so Format answers %#v too. It is kept only because it was released in integrations/bunorm/v3.2.0 and dropping an exported method is a breaking change; it is removed at v4. String and Format carry the redaction.
func (EncryptedDeterministicString) LogValue ¶
func (instance EncryptedDeterministicString) LogValue() slog.Value
func (EncryptedDeterministicString) MarshalJSON ¶
func (instance EncryptedDeterministicString) MarshalJSON() ([]byte, error)
func (*EncryptedDeterministicString) Scan ¶
func (instance *EncryptedDeterministicString) Scan(source any) error
func (EncryptedDeterministicString) String ¶
func (instance EncryptedDeterministicString) String() string
func (*EncryptedDeterministicString) UnmarshalJSON ¶ added in v3.6.0
func (instance *EncryptedDeterministicString) UnmarshalJSON(data []byte) error
UnmarshalJSON refuses the redaction placeholder MarshalJSON writes and decodes any other string, for the reason on EncryptedString.UnmarshalJSON.
type EncryptedDeterministicStringFor ¶ added in v3.2.0
EncryptedDeterministicStringFor is EncryptedDeterministicString bound to the named cipher the CipherRef marker R selects; see EncryptedStringFor for the compartment semantics and EncryptedDeterministicString for what the plaintext-derived nonce reveals.
func (EncryptedDeterministicStringFor[R]) Format ¶ added in v3.6.0
func (instance EncryptedDeterministicStringFor[R]) Format(state fmt.State, verb rune)
Format answers every verb that reaches it, the numeric ones included, with the redacted rendering; its limits are on EncryptedString.Format.
func (EncryptedDeterministicStringFor[R]) GoString
deprecated
added in
v3.2.0
func (instance EncryptedDeterministicStringFor[R]) GoString() string
Deprecated: GoString is never reached — fmt consults Formatter before GoStringer, and this type implements Format, so Format answers %#v too. It is kept only because it was released in integrations/bunorm/v3.2.0 and dropping an exported method is a breaking change; it is removed at v4. String and Format carry the redaction.
func (EncryptedDeterministicStringFor[R]) LogValue ¶ added in v3.2.0
func (instance EncryptedDeterministicStringFor[R]) LogValue() slog.Value
func (EncryptedDeterministicStringFor[R]) MarshalJSON ¶ added in v3.2.0
func (instance EncryptedDeterministicStringFor[R]) MarshalJSON() ([]byte, error)
func (*EncryptedDeterministicStringFor[R]) Scan ¶ added in v3.2.0
func (instance *EncryptedDeterministicStringFor[R]) Scan(source any) error
func (EncryptedDeterministicStringFor[R]) String ¶ added in v3.2.0
func (instance EncryptedDeterministicStringFor[R]) String() string
func (*EncryptedDeterministicStringFor[R]) UnmarshalJSON ¶ added in v3.6.0
func (instance *EncryptedDeterministicStringFor[R]) UnmarshalJSON(data []byte) error
UnmarshalJSON refuses the redaction placeholder MarshalJSON writes and decodes any other string, for the reason on EncryptedString.UnmarshalJSON.
type EncryptedString ¶
type EncryptedString string
func (EncryptedString) Format ¶ added in v3.6.0
func (instance EncryptedString) Format(state fmt.State, verb rune)
Format answers every verb that reaches it, the numeric ones included, with the redacted rendering. %p and %w never reach it, since fmt prints the operand by reflection first, and a value in an unexported field of a struct rendered with %v is walked by reflection with no method called.
func (EncryptedString) GoString
deprecated
added in
v3.2.0
func (instance EncryptedString) GoString() string
Deprecated: GoString is never reached — fmt consults Formatter before GoStringer, and this type implements Format, so Format answers %#v too. It is kept only because it was released in integrations/bunorm/v3.2.0 and dropping an exported method is a breaking change; it is removed at v4. String and Format carry the redaction.
func (EncryptedString) LogValue ¶
func (instance EncryptedString) LogValue() slog.Value
func (EncryptedString) MarshalJSON ¶
func (instance EncryptedString) MarshalJSON() ([]byte, error)
func (*EncryptedString) Scan ¶
func (instance *EncryptedString) Scan(source any) error
func (EncryptedString) String ¶
func (instance EncryptedString) String() string
func (*EncryptedString) UnmarshalJSON ¶ added in v3.6.0
func (instance *EncryptedString) UnmarshalJSON(data []byte) error
UnmarshalJSON refuses the redaction placeholder MarshalJSON writes, so a round-tripped document cannot seal the placeholder over the secret. Any other string is the plaintext, and a json null leaves the value untouched.
type EncryptedStringFor ¶ added in v3.2.0
EncryptedStringFor is EncryptedString bound to the named cipher selected by the CipherRef marker R, so a multi-context binary keeps one key compartment per context:
type CrmCipher struct{}
func (instance CrmCipher) CipherName() string {
return "crm"
}
type Customer struct {
Iban encrypt.EncryptedStringFor[CrmCipher] `bun:"iban"`
}
Install the compartment with encrypt.UseCipherNamed("crm", cipher). Each named cipher owns its KeyProvider: key rotation inside the compartment keeps working through the key id embedded in the ciphertext, and a column of one compartment cannot decrypt another's as long as each provider holds keys of its own, since the name is not bound into the ciphertext.
func (EncryptedStringFor[R]) Format ¶ added in v3.6.0
func (instance EncryptedStringFor[R]) Format(state fmt.State, verb rune)
Format answers every verb that reaches it, the numeric ones included, with the redacted rendering; its limits are on EncryptedString.Format.
func (EncryptedStringFor[R]) GoString
deprecated
added in
v3.2.0
func (instance EncryptedStringFor[R]) GoString() string
Deprecated: GoString is never reached — fmt consults Formatter before GoStringer, and this type implements Format, so Format answers %#v too. It is kept only because it was released in integrations/bunorm/v3.2.0 and dropping an exported method is a breaking change; it is removed at v4. String and Format carry the redaction.
func (EncryptedStringFor[R]) LogValue ¶ added in v3.2.0
func (instance EncryptedStringFor[R]) LogValue() slog.Value
func (EncryptedStringFor[R]) MarshalJSON ¶ added in v3.2.0
func (instance EncryptedStringFor[R]) MarshalJSON() ([]byte, error)
func (*EncryptedStringFor[R]) Scan ¶ added in v3.2.0
func (instance *EncryptedStringFor[R]) Scan(source any) error
func (EncryptedStringFor[R]) String ¶ added in v3.2.0
func (instance EncryptedStringFor[R]) String() string
func (*EncryptedStringFor[R]) UnmarshalJSON ¶ added in v3.6.0
func (instance *EncryptedStringFor[R]) UnmarshalJSON(data []byte) error
UnmarshalJSON refuses the redaction placeholder MarshalJSON writes and decodes any other string, for the reason on EncryptedString.UnmarshalJSON.
type KeyProvider ¶
type KeyProvider interface {
CurrentKeyId() string
ActiveKeyIds() []string
Key(keyId string) ([]byte, error)
}
KeyProvider hands the cipher its keys. The contract has three obligations the compiler cannot see. Every id CurrentKeyId or ActiveKeyIds answers must stay resolvable through Key for as long as it is answered — the cipher reads in two steps (the id, then the key), so a provider that retires an id between the two fails a write that should have succeeded. Every id must match the key id grammar (`^[A-Za-z0-9_.-]{1,32}$`): the id is written into the stored value in front of a ":" separator, and seal refuses one that would corrupt the wire format. And a retired key must STAY in the set until every value sealed under it has been re-encrypted — the cipher treats a marker-shaped value under an unknown id as ordinary plaintext and seals it, so dropping a key while its ciphertexts remain makes them unrecoverable at the next write that touches them.
type Migrator ¶
type Migrator struct {
// contains filtered or unexported fields
}
func (*Migrator) EnsureColumnCapacity ¶ added in v3.6.0
func (*Migrator) EnsureColumnCapacityForReencrypt ¶ added in v3.6.0
func (*Migrator) MigrateDecrypt ¶
MigrateDecrypt reads the stored format before the cipher does, so a pass-through cipher cannot turn an unknown seal into plaintext, and stops on a decrypted value of the marker family, which written bare would read back as a seal.
func (*Migrator) MigrateEncrypt ¶
type Module ¶
type Module struct {
// contains filtered or unexported fields
}
func NewModule ¶
func NewModule(config ModuleConfig) *Module
func (*Module) Description ¶
func (*Module) RegisterCliCommands ¶
func (instance *Module) RegisterCliCommands(kernelInstance kernelcontract.Kernel) []clicontract.Command
type ModuleConfig ¶
type ModuleConfig struct {
Database *bun.DB
Cipher Cipher
/* DatabaseFactory resolves the database for the unsuffixed command at the first command run, after Boot, and a success is memoized. A database it opens is not closed by the container, and a non-MySQL dialect panics at that first run. */
DatabaseFactory func(resolver containercontract.Resolver) (*bun.DB, error)
/* Contexts adds one bulk command per key compartment — melody:encrypt:database:<name> — for a multi-context binary; it composes with the legacy fields above, which keep the unsuffixed command. */
Contexts []CommandContextConfig
}
ModuleConfig wires the melody:encrypt:database bulk command from a prebuilt *bun.DB or from a DatabaseFactory evaluated at the first command run, so a process in another mode never opens the database. Setting both panics at registration; with Database, DatabaseFactory and Cipher all nil no unsuffixed command is registered, and any other partial combination panics.
type StaticKeyProvider ¶
type StaticKeyProvider struct {
// contains filtered or unexported fields
}
func NewStaticKeyProvider ¶
func NewStaticKeyProvider(currentKeyId string, keysById map[string][]byte) *StaticKeyProvider
NewStaticKeyProvider holds the keys it is handed for the life of the process. Every key must be 32 bytes, the AES-256 size, and not all zero bytes, the key of a buffer nobody wrote to; nothing beyond that is judged.
func (*StaticKeyProvider) ActiveKeyIds ¶
func (instance *StaticKeyProvider) ActiveKeyIds() []string
func (*StaticKeyProvider) CurrentKeyId ¶
func (instance *StaticKeyProvider) CurrentKeyId() string
func (StaticKeyProvider) Format ¶ added in v3.2.0
func (instance StaticKeyProvider) Format(state fmt.State, verb rune)
Format answers every verb that reaches it, the numeric ones included, with the String rendering, so no verb walks the keys by reflection. %p and %w never reach it: fmt prints the operand by reflection before consulting any method.
func (StaticKeyProvider) GoString
deprecated
added in
v3.2.0
func (instance StaticKeyProvider) GoString() string
Deprecated: GoString is never reached — fmt consults Formatter before GoStringer, and this type implements Format, so Format answers %#v too. It is kept only because it was released in integrations/bunorm/v3.2.0 and dropping an exported method is a breaking change; it is removed at v4. String and Format carry the redaction.
func (*StaticKeyProvider) Key ¶
func (instance *StaticKeyProvider) Key(keyId string) ([]byte, error)
func (StaticKeyProvider) String ¶ added in v3.2.0
func (instance StaticKeyProvider) String() string
String keeps the master keys out of every rendering fmt routes through this value's methods, naming only the current key id. A provider held in an unexported field of another struct is walked by reflection with no method called, so it is not embedded that way.