gokeepasslib

package module
v3.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 28, 2026 License: MIT Imports: 21 Imported by: 46

README

gokeepasslib

GitHub Build Status GitHub go.mod Go version GitHub release (latest by date)

gokeepasslib is a library which allows reading Keepass 2 files (kdbx).

Note: only Keepass v2.30 or higher is properly supported since earlier versions do not allow empty XML tags but expected self-closing tags (which is valid XML but not really supported by Golang on XML marshaling) Basically: this lib can probably read most Keepass2 files, but only Keepass v2.30 can be expected to read files created in this lib.

Installing

Use go get to retrieve the latest version:

go get -u github.com/tobischo/gokeepasslib/v3@latest

For including it in your code:

import "github.com/tobischo/gokeepasslib/v3"
Example: reading a file
package main

import (
    "fmt"
    "github.com/tobischo/gokeepasslib/v3"
    "os"
)

func main() {
    file, _ := os.Open("examples/reading/example.kdbx")

    db := gokeepasslib.NewDatabase()
    db.Credentials = gokeepasslib.NewPasswordCredentials("abcdefg12345678")
    _ = gokeepasslib.NewDecoder(file).Decode(db)

    db.UnlockProtectedEntries()

    // Note: This is a simplified example and the groups and entries will depend on the specific file.
    // bound checking for the slices is recommended to avoid panics.
    entry := db.Content.Root.Groups[0].Groups[0].Entries[0]
    fmt.Println(entry.GetTitle())
    fmt.Println(entry.GetPassword())
}

Note the db.UnlockProtectedEntries() call: you have to unlock protected entries before using the database and call db.LockProtectedEntries() before saving it to ensure that the passwords are not stored in plaintext in the xml. In kdbx files, which are encrypted using the file credentials, fields are protected with another stream cipher.

File format versions

New databases are created as KDBX 3.1 unless a different version is requested:

db := gokeepasslib.NewDatabase(
    gokeepasslib.WithDatabaseKDBXVersion41(),
)

Available options are WithDatabaseKDBXVersion3() (KDBX 3.1), WithDatabaseKDBXVersion40() (KDBX 4.0) and WithDatabaseKDBXVersion41() (KDBX 4.1).

Reading works for all of them without passing an option, since the version is taken from the file itself.

Some elements, e.g. Group.Tags or Entry.PreviousParentGroup, only exist in KDBX 4.1. Setting one of them on a KDBX 4.0 database upgrades it to KDBX 4.1 while encoding. Setting one of them on a KDBX 3.1 database makes encoding return an ErrKdbxVersionUpgradeRequired, because the upgrade would change the structure of the file itself, e.g. the key derivation function and the way binaries are stored.

Example: writing a file

See examples/writing/example-writing.go

Example: deleting a file

See examples/deleting/example-deleting.go

TODO
  • Improve code readability
  • Write more tests
Contributing

CONTRIBUTING

Changelog

CHANGELOG

License

LICENSE

Copyright © 2024 Tobias Schoknecht. All rights reserved.

Documentation

Index

Examples

Constants

View Source 
const (
	InnerHeaderTerminator byte = 0x00 // Inner header terminator byte
	InnerHeaderIRSID      byte = 0x01 // Inner header InnerRandomStreamID byte
	InnerHeaderIRSKey     byte = 0x02 // Inner header InnerRandomStreamKey byte
	InnerHeaderBinary     byte = 0x03 // Inner header binary byte

)

Inner header bytes

View Source 
const (
	NoStreamID     uint32 = 0 // ID for non-protection
	ARC4StreamID   uint32 = 1 // ID for ARC4 protection, not implemented
	SalsaStreamID  uint32 = 2 // ID for Salsa20 protection
	ChaChaStreamID uint32 = 3 // ID for ChaCha20 protection
)

Constant enumerator for the inner random stream ID

View Source 
const (
	NoCompressionFlag   uint32 = 0 // No compression flag
	GzipCompressionFlag uint32 = 1 // Gzip compression flag

)

Compression flags

View Source 
const ZeroUUIDText = "AAAAAAAAAAAAAAAAAAAAAA=="

ZeroUUIDText is the base64 representation of a zero UUID. KeePass writes it for elements which have to contain a UUID but which do not reference anything, e.g. the LastSelectedGroup of a new database.

Variables

View Source 
var (
	// BaseSignature is the valid base signature for kdbx files
	BaseSignature = [...]byte{0x03, 0xd9, 0xa2, 0x9a}

	// SecondarySignature is the valid version signature for kdbx files
	SecondarySignature = [...]byte{0x67, 0xfb, 0x4b, 0xb5}

	// DefaultKDBX3Sig is the full valid default signature struct for new databases (Kdbx v3.1)
	DefaultKDBX3Sig = Signature{BaseSignature, SecondarySignature, 1, 3}

	// DefaultKDBX40Sig is the full valid default signature struct for new databases (Kdbx v4.0)
	DefaultKDBX40Sig = Signature{BaseSignature, SecondarySignature, 0, 4}

	// DefaultKDBX41Sig is the full valid default signature struct for new databases (Kdbx v4.1)
	DefaultKDBX41Sig = Signature{BaseSignature, SecondarySignature, 1, 4}

	// DefaultKDBX4Sig is the full valid default signature struct for new databases (Kdbx v4.0)
	//
	// Deprecated: use DefaultKDBX40Sig instead
	DefaultKDBX4Sig = DefaultKDBX40Sig

	// DefaultSig is the full valid default signature struct for new databases (Kdbx v3.1)
	DefaultSig = DefaultKDBX3Sig
)
View Source 
var CipherAES = []byte{
	0x31, 0xC1, 0xF2, 0xE6,
	0xBF, 0x71, 0x43, 0x50,
	0xBE, 0x58, 0x05, 0x21,
	0x6A, 0xFC, 0x5A, 0xFF,
}

CipherAES is the AES cipher ID

View Source 
var CipherChaCha20 = []byte{
	0xD6, 0x03, 0x8A, 0x2B,
	0x8B, 0x6F, 0x4C, 0xB5,
	0xA5, 0x24, 0x33, 0x9A,
	0x31, 0xDB, 0xB5, 0x9A,
}

CipherChaCha20 is the ChaCha20 cipher ID

View Source 
var CipherTwoFish = []byte{
	0xAD, 0x68, 0xF2, 0x9F,
	0x57, 0x6F, 0x4B, 0xB9,
	0xA3, 0x6A, 0xD4, 0x7A,
	0xF9, 0x65, 0x34, 0x6C,
}

CipherTwoFish is the TwoFish cipher ID

View Source 
var ErrEndOfHeaders = errors.New("gokeepasslib: header id was 0, end of headers")

ErrEndOfHeaders is the error returned when end of headers is read

View Source 
var ErrEndOfInnerHeaders = errors.New("gokeepasslib: inner header id was 0, end of inner headers")

ErrEndOfInnerHeaders is the error returned when the end of inner header is read

View Source 
var ErrInvalidDatabaseOrCredentials = errors.New(
	"Cannot read database: Either credentials are invalid or the database file is corrupted",
)

ErrInvalidDatabaseOrCredentials is returned when the file cannot be read properly.

View Source 
var ErrInvalidProtectedBinary = errors.New(
	"gokeepasslib: content of a protected binary is not valid base64",
)

ErrInvalidProtectedBinary is retured if the content of a stream protected binary is not valid base64. Such content can neither be locked nor unlocked, since the amount of bytes taken from the inner stream cipher depends on it, and processing it anyway would corrupt every protected value which follows it.

View Source 
var ErrInvalidUUIDLength = errors.New("gokeepasslib: length of decoded UUID was not 16")

ErrInvalidUUIDLength is an error which is returned during unmarshaling if the UUID does not have 16 bytes length

View Source 
var ErrUnsupportedEncrypterType = errors.New("Type of encrypter unsupported")

ErrUnsupportedEncrypterType is retured if no encrypter manager can be created due to an invalid length of EncryptionIV

View Source 
var ErrUnsupportedStreamType = errors.New("Type of stream manager unsupported")

ErrUnsupportedStreamType is retured if no stream manager can be created due to an unsupported InnerRandomStreamID value

View Source 
var KdfAES3 = []byte{
	0xC9, 0xD9, 0xF3, 0x9A,
	0x62, 0x8A, 0x44, 0x60,
	0xBF, 0x74, 0x0D, 0x08,
	0xC1, 0x8A, 0x4F, 0xEA,
}

KdfAES3 is the AES key derivation function ID for Kdbx v3.1

View Source 
var KdfAES4 = []byte{
	0x7C, 0x02, 0xBB, 0x82,
	0x79, 0xA7, 0x4A, 0xC0,
	0x92, 0x7D, 0x11, 0x4A,
	0x00, 0x64, 0x82, 0x38,
}

KdfAES4 is the AES key derivation function ID for Kdbx v4

View Source 
var KdfArgon2 = []byte{
	0xEF, 0x63, 0x6D, 0xDF,
	0x8C, 0x29, 0x44, 0x4B,
	0x91, 0xF7, 0xA9, 0xA4,
	0x03, 0xE3, 0x0A, 0x0C,
}

KdfArgon2 is the Argon2 key derivation function ID

Functions

func ParseKeyData 

func ParseKeyData(data []byte) ([]byte, error)

ParseKeyData returns the hashed key from a key file in bytes, parsing xml if needed

func ParseKeyFile 

func ParseKeyFile(location string) ([]byte, error)

ParseKeyFile returns the hashed key from a key file at the path specified by location, parsing xml if needed

func WithKDBXv4Binary added in v3.3.0 

func WithKDBXv4Binary(binary *Binary)

WithKDBXv4Binary can be passed to the Binaries.Add function as an option to ensure that the Binary will follow the KDBXv4 format

func WithKDBXv31Binary added in v3.3.0 

func WithKDBXv31Binary(binary *Binary)

WithKDBXv31Binary can be passed to the Binaries.Add function as an option to ensure that the Binary will follow the KDBXv31 format

Types

type AutoTypeAssociation 

type AutoTypeAssociation struct {
	Window            string `xml:"Window"`
	KeystrokeSequence string `xml:"KeystrokeSequence"`
}

AutoTypeAssociation is a structure that store the keystroke sequence of a window for AutoTypeData

type AutoTypeData 

type AutoTypeData struct {
	Enabled                 w.BoolWrapper         `xml:"Enabled"`
	DataTransferObfuscation int64                 `xml:"DataTransferObfuscation"`
	DefaultSequence         string                `xml:"DefaultSequence"`
	Associations            []AutoTypeAssociation `xml:"Association,omitempty"`
}

AutoTypeData is a structure containing auto type settings of an entry

type Binaries 

type Binaries []Binary

Binaries Stores a slice of binaries in the metadata header of a database This will be used only on KDBX 3.1 Since KDBX 4, binaries are stored into the InnerHeader

func (*Binaries) Add deprecated 

func (bs *Binaries) Add(c []byte, options ...BinaryOption) *Binary

Deprecated: Add appends binary data to the slice Note: this function should not be used directly, use `Database.AddBinary(c []byte) *Binary` instead

func (Binaries) Find 

func (bs Binaries) Find(id int) *Binary

Find returns a reference to a binary with the same ID as id, or nil if none if found

type Binary 

type Binary struct {
	ID               int            `xml:"ID,attr"`                  // Index (manual on KDBX v4)
	MemoryProtection byte           `xml:"-"`                        // Memory protection (KDBX v4)
	Content          []byte         `xml:",innerxml"`                // Binary content
	Compressed       w.BoolWrapper  `xml:"Compressed,attr"`          // Compressed flag (KDBX v3.1)
	Protected        *w.BoolWrapper `xml:"Protected,attr,omitempty"` // Stream cipher flag (KDBX v3.1)
	// contains filtered or unexported fields
}

Binary stores a binary found in the metadata header of a database

func (Binary) CreateReference 

func (b Binary) CreateReference(f string) BinaryReference

CreateReference creates a reference with the same id as b with filename f

func (Binary) GetContent deprecated 

func (b Binary) GetContent() (string, error)

GetContent returns a string which is the plaintext content of a binary

Deprecated: use GetContentString() instead

func (Binary) GetContentBytes added in v3.2.3 

func (b Binary) GetContentBytes() ([]byte, error)

GetContentBytes returns a bytes slice containing content of a binary

func (Binary) GetContentString added in v3.2.3 

func (b Binary) GetContentString() (string, error)

GetContentString returns the content of a binary as a string

func (*Binary) SetContent 

func (b *Binary) SetContent(c []byte) error

SetContent encodes and (if Compressed=true) compresses c and sets b's content

The content of a stream protected binary is never compressed, matching KeePass

func (Binary) String 

func (b Binary) String() string

type BinaryOption added in v3.3.0 

type BinaryOption func(binary *Binary)

BinaryOption is the option function type for use with Binary structs

type BinaryReference 

type BinaryReference struct {
	Name  string `xml:"Key"`
	Value struct {
		ID int `xml:"Ref,attr"`
	} `xml:"Value"`
}

BinaryReference stores a reference to a binary which appears in the xml of an entry

func NewBinaryReference 

func NewBinaryReference(name string, id int) BinaryReference

NewBinaryReference creates a new BinaryReference with the given name and id

func (*BinaryReference) Find deprecated 

func (br *BinaryReference) Find(db *Database) *Binary

Deprecated: Find returns a reference to a binary in the database db with the same id as br, or nil if none is found Note: this function should not be used directly, use `Database.FindBinary(id int) *Binary` instead

func (BinaryReference) String 

func (br BinaryReference) String() string

type BlockHMACBuilder 

type BlockHMACBuilder struct {
	// contains filtered or unexported fields
}

func NewBlockHMACBuilder 

func NewBlockHMACBuilder(masterSeed []byte, transformedKey []byte) *BlockHMACBuilder

func (*BlockHMACBuilder) BuildHMAC 

func (b *BlockHMACBuilder) BuildHMAC(index uint64, length uint32, data []byte) []byte

type CustomData 

type CustomData struct {
	XMLName xml.Name `xml:"Item"`
	Key     string   `xml:"Key"`
	Value   string   `xml:"Value"`

	// LastModificationTime was added in KDBX 4.1.
	//
	// Note that the KDBX XML schema only documents it for the custom data of
	// the MetaData, while KeePass itself writes it for the custom data of
	// groups and entries as well. It is therefore supported in all three
	// places, matching the behaviour of KeePass.
	LastModificationTime *w.TimeWrapper `xml:"LastModificationTime,omitempty"`
}

CustomData is the structure for plugins custom data

type CustomIcon added in v3.2.1 

type CustomIcon struct {
	UUID UUID   `xml:"UUID"` // Entry's CustomIcon UUID should match this
	Data string `xml:"Data"` // base64 encoded PNG icon.  Unknown size constraints

	Name                 string         `xml:"Name,omitempty"`                 // KDBX 4.1
	LastModificationTime *w.TimeWrapper `xml:"LastModificationTime,omitempty"` // KDBX 4.1
}

CustomIcon is the structure needed to store custom icons. Unsure of what version/format requires this

type DBContent 

type DBContent struct {
	RawData     []byte       `xml:"-"` // XML encoded original data
	InnerHeader *InnerHeader `xml:"-"`
	XMLName     xml.Name     `xml:"KeePassFile"`
	Meta        *MetaData    `xml:"Meta"`
	Root        *RootData    `xml:"Root"`
}

DBContent is a container for all elements of a keepass database

func NewContent 

func NewContent(options ...DBContentOption) *DBContent

NewContent creates a new database content with some good defaults

type DBContentOption 

type DBContentOption func(*DBContent)

func WithDBContentFormattedTime 

func WithDBContentFormattedTime(formatted bool) DBContentOption

type DBCredentials 

type DBCredentials struct {
	Passphrase []byte // Passphrase if using one, stored in sha256 hash
	Key        []byte // Contents of the keyfile if using one, stored in sha256 hash
	Windows    []byte // Whatever is returned from windows user account auth, stored in sha256 hash
}

DBCredentials holds the key used to lock and unlock the database

func NewKeyCredentials 

func NewKeyCredentials(location string) (*DBCredentials, error)

NewKeyCredentials builds a new DBCredentials from a key file at the path specified by location

func NewKeyDataCredentials 

func NewKeyDataCredentials(data []byte) (*DBCredentials, error)

NewKeyDataCredentials builds a new DBCredentials from a key file in bytes

func NewPasswordAndKeyCredentials 

func NewPasswordAndKeyCredentials(password, location string) (*DBCredentials, error)

NewPasswordAndKeyCredentials builds a new DBCredentials from a password and the key file at the path specified by location

func NewPasswordAndKeyDataCredentials 

func NewPasswordAndKeyDataCredentials(password string, data []byte) (*DBCredentials, error)

NewPasswordAndKeyDataCredentials builds a new DBCredentials from a password and the key file in bytes

func NewPasswordCredentials 

func NewPasswordCredentials(password string) *DBCredentials

NewPasswordCredentials builds a new DBCredentials from a Password string

func (*DBCredentials) String 

func (c *DBCredentials) String() string

type DBHashes 

type DBHashes struct {
	Sha256 [32]byte
	Hmac   [32]byte
}

DBHashes stores the hashes of a Kdbx v4 database

func NewHashes 

func NewHashes(header *DBHeader) *DBHashes

NewHashes creates a new DBHashes based on the given header

func (DBHashes) String 

func (h DBHashes) String() string

type DBHeader 

type DBHeader struct {
	RawData     []byte
	Signature   *Signature
	FileHeaders *FileHeaders
}

DBHeader is the header of a database

func NewHeader 

func NewHeader() *DBHeader

NewHeader creates a new Header with good defaults

func NewKDBX3Header added in v3.1.0 

func NewKDBX3Header() *DBHeader

NewKDBX3Header creates a new Header with good defaults for KDBX3

func NewKDBX4Header deprecated added in v3.1.0 

func NewKDBX4Header() *DBHeader

NewKDBX4Header creates a new Header with good defaults for KDBX 4.0

Deprecated: use NewKDBX40Header instead

func NewKDBX40Header added in v3.7.0 

func NewKDBX40Header() *DBHeader

NewKDBX40Header creates a new Header with good defaults for KDBX 4.0

func NewKDBX41Header added in v3.7.0 

func NewKDBX41Header() *DBHeader

NewKDBX41Header creates a new Header with good defaults for KDBX 4.1

func (*DBHeader) GetHmacSha256 

func (h *DBHeader) GetHmacSha256(hmacKey []byte) [32]byte

GetHmacSha256 returns the HMAC-Sha256 hash of the header

func (*DBHeader) GetSha256 

func (h *DBHeader) GetSha256() [32]byte

GetSha256 returns the Sha256 hash of the header

func (*DBHeader) IsKdbx4 

func (h *DBHeader) IsKdbx4() bool

IsKdbx4 returns true if the header major version equals to 4

func (*DBHeader) IsKdbx41 added in v3.7.0 

func (h *DBHeader) IsKdbx41() bool

IsKdbx41 returns true if the header version is at least 4.1

func (DBHeader) String 

func (h DBHeader) String() string

func (*DBHeader) ValidateHmacSha256 

func (h *DBHeader) ValidateHmacSha256(hmacKey []byte, hash [32]byte) error

ValidateHmacSha256 validates the given hash with the HMAC-Sha256 of the header

func (*DBHeader) ValidateSha256 

func (h *DBHeader) ValidateSha256(hash [32]byte) error

ValidateSha256 validates the given hash with the Sha256 of the header

type DBOptions 

type DBOptions struct {
	ValidateHashes bool // True to validate header hash
}

DBOptions stores options for database decoding/encoding

func NewOptions 

func NewOptions() *DBOptions

NewOptions creates new options with default values

type Database 

type Database struct {
	Options     *DBOptions
	Credentials *DBCredentials
	Header      *DBHeader
	Hashes      *DBHashes
	Content     *DBContent
}

Database stores all contents necessary for a keepass database file

func NewDatabase 

func NewDatabase(options ...DatabaseOption) *Database

NewDatabase creates a new database with some sensable default settings in KDBX version 3.1. To create a database with no settings pre-set, use gokeepasslib.Database{}

Example (Kdbxv3) 
buf := bytes.NewBuffer([]byte{})

// create the new database
db := NewDatabase(
	WithDatabaseKDBXVersion3(),
)
db.Content.Meta.DatabaseName = "KDBX4"
db.Credentials = NewPasswordCredentials("supersecret")

// Lock entries using stream cipher
db.LockProtectedEntries()

// and encode it into the file
keepassEncoder := NewEncoder(buf)
if err := keepassEncoder.Encode(db); err != nil {
	panic(err)
}

log.Printf("Wrote kdbx file to buffer")
Example (Kdbxv4) 
buf := bytes.NewBuffer([]byte{})

// create the new database
db := NewDatabase(
	WithDatabaseKDBXVersion4(),
)
db.Content.Meta.DatabaseName = "KDBX4"
db.Credentials = NewPasswordCredentials("supersecret")

// Lock entries using stream cipher
db.LockProtectedEntries()

// and encode it into the file
keepassEncoder := NewEncoder(buf)
if err := keepassEncoder.Encode(db); err != nil {
	panic(err)
}

log.Printf("Wrote kdbx file to buffer")

func (*Database) AddBinary added in v3.3.0 

func (db *Database) AddBinary(binaryContent []byte) *Binary

AddBinary adds a binary to the database. It takes care of adding it to the correct place based on the format version

func (*Database) FindBinary added in v3.3.0 

func (db *Database) FindBinary(id int) *Binary

FindBinary returns the binary with the given id if one could be found. It returns nil otherwise

func (*Database) GetEncrypterManager 

func (db *Database) GetEncrypterManager(transformedKey []byte) (*EncrypterManager, error)

GetEncrypterManager returns an EncryptManager based on the master key and EncryptionIV, or nil if the type is unsupported

func (*Database) GetStreamManager 

func (db *Database) GetStreamManager() (*StreamManager, error)

GetStreamManager returns a StreamManager based on the db headers, or nil if the type is unsupported Can be used to lock only certain entries instead of calling

func (*Database) LockProtectedEntries 

func (db *Database) LockProtectedEntries() error

LockProtectedEntries goes through the entire database and decrypts any Values in entries with protected=true set. It also locks protected binaries in the KDBX v3.1 metadata section. Warning: Do not call this if entries are already locked Warning: Encoding a database calls LockProtectedEntries automatically

func (*Database) UnlockProtectedEntries 

func (db *Database) UnlockProtectedEntries() error

UnlockProtectedEntries goes through the entire database and encrypts any Values in entries with protected=true set. It also unlocks protected binaries in the KDBX v3.1 metadata section. This should be called after decoding if you want to view plaintext password in an entry Warning: If you call this when entry values are already unlocked, it will cause them to be unreadable

type DatabaseOption 

type DatabaseOption func(*Database)

func WithDatabaseFormattedTime 

func WithDatabaseFormattedTime(formatted bool) DatabaseOption

func WithDatabaseKDBXVersion3 added in v3.1.0 

func WithDatabaseKDBXVersion3() DatabaseOption

WithDatabaseKDBXVersion3 initializes the database as a KDBX 3.1 file

func WithDatabaseKDBXVersion4 deprecated added in v3.1.0 

func WithDatabaseKDBXVersion4() DatabaseOption

WithDatabaseKDBXVersion4 initializes the database as a KDBX 4.0 file

Deprecated: use WithDatabaseKDBXVersion40 instead

func WithDatabaseKDBXVersion40 added in v3.7.0 

func WithDatabaseKDBXVersion40() DatabaseOption

WithDatabaseKDBXVersion40 initializes the database as a KDBX 4.0 file

func WithDatabaseKDBXVersion41 added in v3.7.0 

func WithDatabaseKDBXVersion41() DatabaseOption

WithDatabaseKDBXVersion41 initializes the database as a KDBX 4.1 file

type Decoder 

type Decoder struct {
	// contains filtered or unexported fields
}

Decoder stores a reader which is expected to be in kdbx format

func NewDecoder 

func NewDecoder(r io.Reader) *Decoder

NewDecoder creates a new decoder with reader r, identical to gokeepasslib.Decoder{r}

func (*Decoder) Decode 

func (d *Decoder) Decode(db *Database) error

Decode populates given database with the data of Decoder reader

type DeletedObjectData 

type DeletedObjectData struct {
	XMLName      xml.Name       `xml:"DeletedObject"`
	UUID         UUID           `xml:"UUID"`
	DeletionTime *w.TimeWrapper `xml:"DeletionTime"`
}

DeletedObjectData is the structure for a deleted object

type Encoder 

type Encoder struct {
	// contains filtered or unexported fields
}

Encoder is used to automaticaly encrypt and write a database to a file, network, etc

func NewEncoder 

func NewEncoder(w io.Writer) *Encoder

NewEncoder creates a new encoder with writer w, identical to gokeepasslib.Encoder{w}

func (*Encoder) Encode 

func (e *Encoder) Encode(db *Database) error

Encode writes db to e's internal writer

type Encrypter 

type Encrypter interface {
	Decrypt(data []byte) []byte
	Encrypt(data []byte) []byte
}

Encrypter is responsible for database encrypting and decrypting

type EncrypterManager 

type EncrypterManager struct {
	Encrypter Encrypter
}

EncrypterManager is the manager to handle an Encrypter

func NewEncrypterManager 

func NewEncrypterManager(
	cipherID []byte,
	key []byte,
	iv []byte,
) (*EncrypterManager, error)

NewEncrypterManager initialize a new EncrypterManager

func (*EncrypterManager) Decrypt 

func (em *EncrypterManager) Decrypt(data []byte) []byte

Decrypt returns the decrypted data

func (*EncrypterManager) Encrypt 

func (em *EncrypterManager) Encrypt(data []byte) []byte

Encrypt returns the encrypted data

type Entry 

type Entry struct {
	UUID                UUID              `xml:"UUID"`
	IconID              int64             `xml:"IconID"`
	CustomIconUUID      UUID              `xml:"CustomIconUUID"`
	ForegroundColor     string            `xml:"ForegroundColor"`
	BackgroundColor     string            `xml:"BackgroundColor"`
	OverrideURL         string            `xml:"OverrideURL"`
	QualityCheck        *w.BoolWrapper    `xml:"QualityCheck,omitempty"` // KDBX 4.1
	Tags                string            `xml:"Tags"`
	PreviousParentGroup *UUID             `xml:"PreviousParentGroup,omitempty"` // KDBX 4.1
	Times               TimeData          `xml:"Times"`
	Values              []ValueData       `xml:"String,omitempty"`
	Binaries            []BinaryReference `xml:"Binary,omitempty"`
	AutoType            AutoTypeData      `xml:"AutoType"`
	CustomData          []CustomData      `xml:"CustomData>Item"`
	Histories           []History         `xml:"History"`
}

Entry is the structure which holds information about a parsed entry in a keepass database

The order of the fields matches the order in which KeePass writes the elements, as defined by the KDBX XML schema.

func NewEntry 

func NewEntry(options ...EntryOption) Entry

NewEntry return a new entry with time data and uuid set

func (Entry) Clone added in v3.5.0 

func (e Entry) Clone() Entry

Clone creates a copy of an Entry struct including its child entities

func (*Entry) Get 

func (e *Entry) Get(key string) *ValueData

Get returns the value in e corresponding with key k, or an empty string otherwise

func (*Entry) GetContent 

func (e *Entry) GetContent(key string) string

GetContent returns the content of the value belonging to the given key in string form

func (*Entry) GetIndex 

func (e *Entry) GetIndex(key string) int

GetIndex returns the index of the Value belonging to the given key, or -1 if none is found

func (*Entry) GetPassword 

func (e *Entry) GetPassword() string

GetPassword returns the password of an entry

func (*Entry) GetPasswordIndex 

func (e *Entry) GetPasswordIndex() int

GetPasswordIndex returns the index in the values slice belonging to the password

func (*Entry) GetTitle 

func (e *Entry) GetTitle() string

GetTitle returns the title of an entry

type EntryOption 

type EntryOption func(*Entry)

func WithEntryFormattedTime 

func WithEntryFormattedTime(formatted bool) EntryOption

type ErrInvalidSignature 

type ErrInvalidSignature struct {
	Name     string
	Is       any
	Shouldbe any
}

ErrInvalidSignature is the error returned if the file signature is invalid

func (ErrInvalidSignature) Error 

func (e ErrInvalidSignature) Error() string

type ErrKdbxVersionUpgradeRequired added in v3.7.0 

type ErrKdbxVersionUpgradeRequired struct {
	// Field is the name of a field which requires the higher version
	Field string

	// CurrentVersion is the file format version of the database header
	CurrentVersion string

	// RequiredVersion is the file format version required by the content
	RequiredVersion string
}

ErrKdbxVersionUpgradeRequired is returned when encoding a database whose content can not be represented in the file format version of its header, and where upgrading it automatically would require changing the structure of the file itself.

func (ErrKdbxVersionUpgradeRequired) Error added in v3.7.0 

func (e ErrKdbxVersionUpgradeRequired) Error() string

type ErrRequiredAttributeMissing 

type ErrRequiredAttributeMissing string

ErrRequiredAttributeMissing is returned if a required value is not given

func (ErrRequiredAttributeMissing) Error 

func (e ErrRequiredAttributeMissing) Error() string

type ErrUnknownHeaderID 

type ErrUnknownHeaderID int

ErrUnknownHeaderID is the error returned if an unknown header is read

func (ErrUnknownHeaderID) Error 

func (i ErrUnknownHeaderID) Error() string

type ErrUnknownInnerHeaderID 

type ErrUnknownInnerHeaderID byte

ErrUnknownInnerHeaderID is the error returned if an unknown inner header is read

func (ErrUnknownInnerHeaderID) Error 

func (e ErrUnknownInnerHeaderID) Error() string

type ErrUnknownParameterID 

type ErrUnknownParameterID string

ErrUnknownParameterID is the error returned if an unknown kdf parameter is read

func (ErrUnknownParameterID) Error 

func (s ErrUnknownParameterID) Error() string

type FileHeaders 

type FileHeaders struct {
	Comment             []byte             // FieldID: 1
	CipherID            []byte             // FieldID: 2
	CompressionFlags    uint32             // FieldID: 3
	MasterSeed          []byte             // FieldID: 4
	TransformSeed       []byte             // FieldID: 5 (KDBX 3.1)
	TransformRounds     uint64             // FieldID: 6 (KDBX 3.1)
	EncryptionIV        []byte             // FieldID: 7
	ProtectedStreamKey  []byte             // FieldID: 8 (KDBX 3.1)
	StreamStartBytes    []byte             // FieldID: 9 (KDBX 3.1)
	InnerRandomStreamID uint32             // FieldID: 10 (KDBX 3.1)
	KdfParameters       *KdfParameters     // FieldID: 11 (KDBX 4)
	PublicCustomData    *VariantDictionary // FieldID: 12 (KDBX 4)
}

FileHeaders contains every field of the header

func NewFileHeaders 

func NewFileHeaders() *FileHeaders

NewFileHeaders creates a new FileHeaders with good defaults

func NewKDBX3FileHeaders added in v3.1.0 

func NewKDBX3FileHeaders() *FileHeaders

NewKDBX3FileHeaders creates a new FileHeaders with good defaults for KDBX3

func NewKDBX4FileHeaders added in v3.1.0 

func NewKDBX4FileHeaders() *FileHeaders

NewKDBX4FileHeaders creates a new FileHeaders with good defaults for KDBX 4

The file headers depend on the major version only, so they are the same for KDBX 4.0 and KDBX 4.1, which differ in the XML content of the database

func (FileHeaders) String 

func (fh FileHeaders) String() string

type Group 

type Group struct {
	UUID                    UUID                  `xml:"UUID"`
	Name                    string                `xml:"Name"`
	Notes                   string                `xml:"Notes"`
	IconID                  int64                 `xml:"IconID"`
	CustomIconUUID          UUID                  `xml:"CustomIconUUID"`
	Times                   TimeData              `xml:"Times"`
	IsExpanded              w.BoolWrapper         `xml:"IsExpanded"`
	DefaultAutoTypeSequence string                `xml:"DefaultAutoTypeSequence"`
	EnableAutoType          w.NullableBoolWrapper `xml:"EnableAutoType"`
	EnableSearching         w.NullableBoolWrapper `xml:"EnableSearching"`
	LastTopVisibleEntry     string                `xml:"LastTopVisibleEntry"`
	PreviousParentGroup     *UUID                 `xml:"PreviousParentGroup,omitempty"` // KDBX 4.1
	Tags                    string                `xml:"Tags,omitempty"`                // KDBX 4.1
	CustomData              []CustomData          `xml:"CustomData>Item"`               // KDBX 4
	Entries                 []Entry               `xml:"Entry,omitempty"`
	Groups                  []Group               `xml:"Group,omitempty"`
	// contains filtered or unexported fields
}

Group is a structure to store entries in their named groups for organization

The order of the fields matches the order in which KeePass writes the elements, as defined by the KDBX XML schema.

func NewGroup 

func NewGroup(options ...GroupOption) Group

NewGroup returns a new group with time data and uuid set

func (Group) Clone added in v3.5.0 

func (g Group) Clone() Group

Clone creates a copy of a Group struct including its child entities

func (*Group) UnmarshalXML added in v3.2.4 

func (g *Group) UnmarshalXML(d *xml.Decoder, _ xml.StartElement) error

UnmarshalXML unmarshals the boolean from d

type GroupOption 

type GroupOption func(*Group)

func WithGroupFormattedTime 

func WithGroupFormattedTime(formatted bool) GroupOption

type History 

type History struct {
	Entries []Entry `xml:"Entry"`
}

History stores information about changes made to an entry, in the form of a list of previous versions of that entry

func (History) Clone added in v3.5.0 

func (h History) Clone() History

Clone creates a copy of a History struct including its child entities

type InnerHeader 

type InnerHeader struct {
	InnerRandomStreamID  uint32
	InnerRandomStreamKey []byte
	Binaries             Binaries
}

InnerHeader is the container of crypt options and binaries, only for Kdbx v4

func (InnerHeader) String 

func (ih InnerHeader) String() string

type KdfParameters 

type KdfParameters struct {
	RawData     *VariantDictionary // Raw data of KdfParameters
	UUID        []byte             // $UUID - KDF ID
	Rounds      uint64             // R - Rounds
	Salt        [32]byte           // S - Salt (Argon 2) / Seed (AES)
	Parallelism uint32             // P - Parallelism
	Memory      uint64             // M - Memory
	Iterations  uint64             // I - Iterations
	Version     uint32             // V - Version
	SecretKey   []byte             // K - Secret key
	AssocData   []byte             // A - AssocData
}

KdfParameters contains every field of the KdfParameters header field

func (*KdfParameters) String 

func (k *KdfParameters) String() string

type MemProtection 

type MemProtection struct {
	ProtectTitle    w.BoolWrapper `xml:"ProtectTitle"`
	ProtectUserName w.BoolWrapper `xml:"ProtectUserName"`
	ProtectPassword w.BoolWrapper `xml:"ProtectPassword"`
	ProtectURL      w.BoolWrapper `xml:"ProtectURL"`
	ProtectNotes    w.BoolWrapper `xml:"ProtectNotes"`
}

MemProtection is a structure containing settings for MemoryProtection

type MetaData 

type MetaData struct {
	Generator                  string         `xml:"Generator"`
	SettingsChanged            *w.TimeWrapper `xml:"SettingsChanged"`
	HeaderHash                 string         `xml:"HeaderHash,omitempty"`
	DatabaseName               string         `xml:"DatabaseName"`
	DatabaseNameChanged        *w.TimeWrapper `xml:"DatabaseNameChanged"`
	DatabaseDescription        string         `xml:"DatabaseDescription"`
	DatabaseDescriptionChanged *w.TimeWrapper `xml:"DatabaseDescriptionChanged"`
	DefaultUserName            string         `xml:"DefaultUserName"`
	DefaultUserNameChanged     *w.TimeWrapper `xml:"DefaultUserNameChanged"`
	MaintenanceHistoryDays     int64          `xml:"MaintenanceHistoryDays"`
	Color                      string         `xml:"Color"`
	MasterKeyChanged           *w.TimeWrapper `xml:"MasterKeyChanged"`
	MasterKeyChangeRec         int64          `xml:"MasterKeyChangeRec"`
	MasterKeyChangeForce       int64          `xml:"MasterKeyChangeForce"`
	MemoryProtection           MemProtection  `xml:"MemoryProtection"`
	CustomIcons                []CustomIcon   `xml:"CustomIcons>Icon"`
	RecycleBinEnabled          w.BoolWrapper  `xml:"RecycleBinEnabled"`
	RecycleBinUUID             UUID           `xml:"RecycleBinUUID"`
	RecycleBinChanged          *w.TimeWrapper `xml:"RecycleBinChanged"`
	EntryTemplatesGroup        string         `xml:"EntryTemplatesGroup"`
	EntryTemplatesGroupChanged *w.TimeWrapper `xml:"EntryTemplatesGroupChanged"`
	HistoryMaxItems            int64          `xml:"HistoryMaxItems"`
	HistoryMaxSize             int64          `xml:"HistoryMaxSize"`
	LastSelectedGroup          string         `xml:"LastSelectedGroup"`
	LastTopVisibleGroup        string         `xml:"LastTopVisibleGroup"`
	Binaries                   Binaries       `xml:"Binaries>Binary,omitempty"`
	CustomData                 []CustomData   `xml:"CustomData>Item"`
}

MetaData is the structure for the metadata headers at the top of kdbx files, it contains things like the name of the database

func NewMetaData 

func NewMetaData(options ...MetaDataOption) *MetaData

NewMetaData creates a MetaData struct with some defaults set

type MetaDataOption 

type MetaDataOption func(*MetaData)

func WithMetaDataFormattedTime 

func WithMetaDataFormattedTime(formatted bool) MetaDataOption

type RootData 

type RootData struct {
	Groups         []Group             `xml:"Group"`
	DeletedObjects []DeletedObjectData `xml:"DeletedObjects>DeletedObject"`
}

RootData stores the actual content of a database (all enteries sorted into groups and the recycle bin)

func NewRootData 

func NewRootData(options ...RootDataOption) *RootData

NewRootData returns a RootData struct with good defaults

type RootDataOption 

type RootDataOption func(*RootData)

func WithRootDataFormattedTime 

func WithRootDataFormattedTime(formatted bool) RootDataOption

type Signature 

type Signature struct {
	BaseSignature      [4]byte
	SecondarySignature [4]byte
	MinorVersion       uint16
	MajorVersion       uint16
}

Signature holds the Keepass File Signature. The first 4 Bytes are the Base Signature, followed by 4 Bytes for the Version of the Format which is followed by 4 Bytes for the File Version

func (Signature) String 

func (s Signature) String() string

type Stream 

type Stream interface {
	Unpack(payload string) []byte
	Pack(payload []byte) string
}

Stream is responsible for stream encrypting and decrypting of protected fields

type StreamManager 

type StreamManager struct {
	Stream Stream
}

StreamManager is the manager to handle a Stream

func NewStreamManager 

func NewStreamManager(id uint32, key []byte) (*StreamManager, error)

NewStreamManager initialize a new StreamManager

func (*StreamManager) LockProtectedEntries 

func (cs *StreamManager) LockProtectedEntries(es []Entry)

LockProtectedEntries locks an array of unprotected entries

func (*StreamManager) LockProtectedEntry 

func (cs *StreamManager) LockProtectedEntry(e *Entry)

LockProtectedEntry locks an unprotected entry

func (*StreamManager) LockProtectedGroup 

func (cs *StreamManager) LockProtectedGroup(g *Group)

LockProtectedGroup locks an unprotected group

func (*StreamManager) LockProtectedGroups 

func (cs *StreamManager) LockProtectedGroups(gs []Group)

LockProtectedGroups locks an array of unprotected groups

func (*StreamManager) Pack 

func (cs *StreamManager) Pack(payload []byte) string

Pack returns the payload as encrypted string

func (*StreamManager) UnlockProtectedEntries 

func (cs *StreamManager) UnlockProtectedEntries(e []Entry)

UnlockProtectedEntries unlocks an array of protected entries

func (*StreamManager) UnlockProtectedEntry 

func (cs *StreamManager) UnlockProtectedEntry(e *Entry)

UnlockProtectedEntry unlocks a protected entry

func (*StreamManager) UnlockProtectedGroup 

func (cs *StreamManager) UnlockProtectedGroup(g *Group)

UnlockProtectedGroup unlocks a protected group

func (*StreamManager) UnlockProtectedGroups 

func (cs *StreamManager) UnlockProtectedGroups(gs []Group)

UnlockProtectedGroups unlocks an array of protected groups

func (*StreamManager) Unpack 

func (cs *StreamManager) Unpack(payload string) []byte

Unpack returns the payload as unencrypted byte array

type TimeData 

type TimeData struct {
	CreationTime         *w.TimeWrapper `xml:"CreationTime"`
	LastModificationTime *w.TimeWrapper `xml:"LastModificationTime"`
	LastAccessTime       *w.TimeWrapper `xml:"LastAccessTime"`
	ExpiryTime           *w.TimeWrapper `xml:"ExpiryTime"`
	Expires              w.BoolWrapper  `xml:"Expires"`
	UsageCount           int64          `xml:"UsageCount"`
	LocationChanged      *w.TimeWrapper `xml:"LocationChanged"`
}

TimeData contains all metadata related to times for groups and entries e.g. the last modification time or the creation time

func NewTimeData 

func NewTimeData(options ...TimeDataOption) TimeData

NewTimeData returns a TimeData struct with good defaults (no expire time, all times set to now)

type TimeDataOption 

type TimeDataOption func(*TimeData)

func WithTimeDataFormattedTime 

func WithTimeDataFormattedTime(formatted bool) TimeDataOption

type UUID 

type UUID [16]byte

UUID stores a universal identifier for each group+entry

func NewUUID 

func NewUUID() UUID

NewUUID returns a new randomly generated UUID

func (UUID) Compare 

func (u UUID) Compare(c UUID) bool

Compare allowes to check whether two instance of UUID are equal in value. This is used for searching a uuid UUID is a fixed-size [16]byte array, so direct comparison with == is safe and compares all elements.

func (UUID) IsZero added in v3.7.0 

func (u UUID) IsZero() bool

IsZero returns true if the UUID only consists of zero bytes, which is how KeePass expresses the absence of a UUID value

func (UUID) MarshalText 

func (u UUID) MarshalText() ([]byte, error)

MarshalText is a marshaler method to encode uuid content as base 64 and return it

func (UUID) MarshalXML added in v3.7.0 

func (u UUID) MarshalXML(e *xml.Encoder, start xml.StartElement) error

MarshalXML marshals the UUID as the base64 encoded content of the given element.

A zero valued CustomIconUUID is not written at all: KeePass only writes the element if a custom icon is actually set and the KDBX XML schema expects every CustomIconUUID to reference an icon in the CustomIcons of the MetaData.

func (*UUID) UnmarshalText 

func (u *UUID) UnmarshalText(text []byte) error

UnmarshalText unmarshals a byte slice into a UUID by decoding the given data from base64

type V 

type V struct {
	Content   string        `xml:",chardata"`
	Protected w.BoolWrapper `xml:"Protected,attr,omitempty"`
}

V is a wrapper for the content of a value, so that it can store whether it is protected

type ValueData 

type ValueData struct {
	Key   string `xml:"Key"`
	Value V      `xml:"Value"`
}

ValueData is a structure containing key value pairs of information stored in an entry

type VariantDictionary 

type VariantDictionary struct {
	Version uint16
	Items   []*VariantDictionaryItem
}

VariantDictionary is a structure used into KdfParameters and PublicCustomData

func (*VariantDictionary) Get 

func (vd *VariantDictionary) Get(key string) *VariantDictionaryItem

Get a VariantDictionaryItem via its key

func (VariantDictionary) String 

func (vd VariantDictionary) String() string

type VariantDictionaryItem 

type VariantDictionaryItem struct {
	Type        byte
	NameLength  int32
	Name        []byte
	ValueLength int32
	Value       []byte
}

VariantDictionaryItem is an item of a VariantDictionary

func (VariantDictionaryItem) String 

func (vdi VariantDictionaryItem) String() string

Source Files

View all Source files

Directories

Path Synopsis
examples
deleting command
kdbx4 command
keyfile command
new command
reading command
writing command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.