Documentation
¶
Index ¶
- Constants
- Variables
- func APIKeyAAD(keyPrefix string) []byte
- func Decrypt(ciphertext []byte, key []byte, aad []byte) ([]byte, error)
- func DeriveAuditChainKey(masterKey []byte) ([]byte, error)
- func DeriveO5LogonVerifier18453Key(password string, salt []byte) []byte
- func DeriveO5LogonVerifierKey(password string, salt []byte) []byte
- func DeriveSubkey(masterKey []byte, info string) ([]byte, error)
- func DeviceAuthAAD(requestUID string) []byte
- func Encrypt(plaintext []byte, key []byte, aad []byte) ([]byte, error)
- func GenerateO5LogonVerifier(password string) ([]byte, []byte, error)
- func GenerateO5LogonVerifier18453(password string) ([]byte, []byte, error)
- func HashPassword(password string) (string, error)
- func HashPasswordWithParams(password string, params HashParams) (string, error)
- func LoginExchangeAAD(exchangeUID string) []byte
- func ServerAAD(databaseUID string) []byte
- func UserAAD(userUID string) []byte
- func VerifyPassword(encodedHash, password string) (bool, error)
- type HashParams
Constants ¶
const ( // O5LogonSaltLength is the length of the O5LOGON salt. O5LogonSaltLength = 10 // O5LogonVerifierKeyLength is the length of the O5LOGON verifier key (SHA-1 zero-padded to 24). O5LogonVerifierKeyLength = 24 // O5LogonPbkdf2SaltLength is the salt length for the modern verifier-18453 // (12c PBKDF2 / HMAC-SHA512) O5LOGON used by python-oracledb thin, JDBC // thin / SQLcl, and sqlplus against Oracle 12c+ / 23ai. O5LogonPbkdf2SaltLength = 16 // O5LogonVerifier18453KeyLength is the verifier-18453 key length (SHA-512 truncated to 32). O5LogonVerifier18453KeyLength = 32 // O5LogonPbkdf2VgenCount is the AUTH_PBKDF2_VGEN_COUNT iteration count. The // value used to derive a stored verifier MUST equal the count advertised in // the challenge, so generation and the Oracle proxy's challenge builder both // reference this constant. O5LogonPbkdf2VgenCount = 4096 )
const AuditChainInfo = "dbbat-audit-chain-v1"
AuditChainInfo is the HKDF info string that separates the audit-chain MAC key from every other use of the master encryption key.
It is versioned on purpose: a future change to the canonical serialization bumps the info string, which changes the key, which makes the two chain generations trivially distinguishable instead of silently interchangeable.
const DefaultArgon2Memory uint32 = 8 * 1024
DefaultArgon2Memory is the default memory in KB (8 MB).
const DefaultArgon2Threads uint8 = 4
DefaultArgon2Threads is the default parallelism factor.
const DefaultArgon2Time uint32 = 1
DefaultArgon2Time is the default number of iterations.
Variables ¶
var ( ErrInvalidKeySize = errors.New("key must be 32 bytes") ErrCiphertextTooShort = errors.New("ciphertext too short") ErrEmptyDeriveInfo = errors.New("subkey derivation requires a non-empty info string") )
Encryption errors.
var ( ErrInvalidHashFormat = errors.New("invalid hash format") ErrUnsupportedHashAlgo = errors.New("unsupported hash algorithm") )
Hash errors.
Functions ¶
func APIKeyAAD ¶ added in v0.5.0
APIKeyAAD returns the AAD for encrypting API key O5LOGON verifiers. This binds the ciphertext to a specific API key prefix, preventing verifier transplant attacks.
func Decrypt ¶
Decrypt decrypts ciphertext using AES-256-GCM with the provided key. The ciphertext must include the nonce prefix. The aad must match the value used during encryption, or be nil for legacy data.
func DeriveAuditChainKey ¶ added in v0.24.0
DeriveAuditChainKey derives the HMAC-SHA256 key that seals the audit and query chains. See DeriveSubkey.
func DeriveO5LogonVerifier18453Key ¶ added in v0.13.0
DeriveO5LogonVerifier18453Key computes the verifier-18453 key from password and salt:
speedyKey = pbkdf2SpeedyKey(salt || "AUTH_PBKDF2_SPEEDY_KEY", password, vgenCount) verifierKey = SHA-512(speedyKey || salt)[:32]
func DeriveO5LogonVerifierKey ¶ added in v0.5.0
DeriveO5LogonVerifierKey computes the O5LOGON verifier key from password and salt.
func DeriveSubkey ¶ added in v0.24.0
DeriveSubkey derives a 32-byte purpose-bound subkey from the master encryption key (DBB_KEY / DBB_KEYFILE) with HKDF-SHA256.
The salt is deliberately empty: dbbat has no second secret to salt with, and HKDF is defined for an empty salt (it degrades to HMAC with a zero key, which is the standard construction). The separation between purposes comes from info, which must be distinct per purpose.
The result must never be written to the database or to a log. Its whole point is that reading the store is not enough to forge what it protects.
func DeviceAuthAAD ¶ added in v0.19.0
DeviceAuthAAD returns the AAD for encrypting a freshly minted API key while it sits in a pending device authorization request. This binds the ciphertext to the specific request UID, preventing a key transplant between requests.
func Encrypt ¶
Encrypt encrypts plaintext using AES-256-GCM with the provided key. The ciphertext includes the nonce prefix. Optional aad (Additional Authenticated Data) binds the ciphertext to a context, preventing the ciphertext from being used in a different context.
func GenerateO5LogonVerifier ¶ added in v0.5.0
GenerateO5LogonVerifier creates salt + verifier key from a plaintext password. This is used at API key creation time to store O5LOGON verifier data for Oracle proxy auth.
verifier_key = SHA1(password || salt), zero-padded to 24 bytes.
func GenerateO5LogonVerifier18453 ¶ added in v0.13.0
GenerateO5LogonVerifier18453 creates the salt + verifier key for the modern verifier-18453 O5LOGON from a plaintext password. Stored at API key creation so the Oracle proxy can issue PBKDF2 challenges that modern thin clients accept (legacy go-ora uses the 6949 verifier instead).
func HashPassword ¶
HashPassword generates an Argon2id hash of the password using default parameters.
func HashPasswordWithParams ¶ added in v0.0.1
func HashPasswordWithParams(password string, params HashParams) (string, error)
HashPasswordWithParams generates an Argon2id hash of the password using provided parameters.
func LoginExchangeAAD ¶ added in v0.23.0
LoginExchangeAAD returns the AAD for encrypting a web session token while it waits behind a one-time OAuth login exchange code. This binds the ciphertext to the specific exchange row UID, so a token cannot be transplanted onto another (attacker-known) code.
func ServerAAD ¶ added in v0.17.0
ServerAAD returns the AAD for encrypting database credentials. This binds the ciphertext to a specific database UID, preventing credential transplant attacks where encrypted passwords are swapped between database rows.
func UserAAD ¶ added in v0.16.0
UserAAD returns the AAD for encrypting per-user protocol verifier material (e.g. MongoDB SCRAM stored/server keys). This binds the ciphertext to a specific user UID, preventing verifier transplant attacks between users.
func VerifyPassword ¶
VerifyPassword verifies a password against an Argon2id hash.
Types ¶
type HashParams ¶ added in v0.0.1
type HashParams struct {
MemoryKB uint32 // Memory in KB
Time uint32 // Number of iterations
Threads uint8 // Parallelism factor
}
HashParams holds configurable parameters for password hashing.
func DefaultHashParams ¶ added in v0.0.1
func DefaultHashParams() HashParams
DefaultHashParams returns the default hash parameters.
Source Files