keydb

Documentation

Overview

cryptctl - Copyright (c) 2017 SUSE Linux GmbH, Germany This source code is licensed under GPL version 3 that can be found in LICENSE file.

cryptctl - Copyright (c) 2017 SUSE Linux GmbH, Germany This source code is licensed under GPL version 3 that can be found in LICENSE file.

Index

• Constants
• Variables
• func ValidateUUID(in string) error
• type AliveMessage
• type DB
  • func OpenDB(dir string) (db *DB, err error)
  • func OpenDBOneRecord(dir, recordUUID string) (db *DB, err error)
  • func (db *DB) Erase(uuid string) error
  • func (db *DB) GetByID(id string) (rec Record, found bool)
  • func (db *DB) GetByUUID(uuid string) (rec Record, found bool)
  • func (db *DB) List() (sortedRecords RecordSlice)
  • func (db *DB) ReadRecord(absPath string) (keyRecord Record, err error)
  • func (db *DB) ReloadDB() error
  • func (db *DB) ReloadRecord(uuid string) error
  • func (db *DB) Select(aliveMessage AliveMessage, checkMaxActive bool, uuids ...string) (found map[string]Record, rejected, missing []string)
  • func (db *DB) UpdateAliveMessage(latest AliveMessage, uuids ...string) (rejected []string)
  • func (db *DB) UpdateCommandResult(uuid, ip string, content interface{}, result string)
  • func (db *DB) UpdateSeenFlag(uuid, ip string, content interface{})
  • func (db *DB) UpgradeRecord(record Record) error
  • func (db *DB) UpgradeRecordToVersion1(record Record) error
  • func (db *DB) Upsert(rec Record) (kmipID string, err error)
• type PendingCommand
  • func (cmd *PendingCommand) IsValid() bool
• type Record
  • func (rec *Record) AddPendingCommand(ip string, cmd PendingCommand)
  • func (rec *Record) ClearPendingCommands()
  • func (rec *Record) Deserialise(in []byte) error
  • func (rec *Record) FillBlanks()
  • func (rec *Record) FormatAttrs(separator string) string
  • func (rec *Record) GetMountOptionStr() string
  • func (rec *Record) IsHostAlive(hostIP string) (alive bool, finalMessage AliveMessage)
  • func (rec *Record) RemoveDeadHosts() (deadFinalMessage map[string]AliveMessage)
  • func (rec *Record) RemoveExpiredPendingCommands()
  • func (rec *Record) Serialise() []byte
  • func (rec *Record) UpdateAliveMessage(latestBeat AliveMessage) bool
  • func (rec *Record) UpdateLastRetrieval(latestBeat AliveMessage, checkMaxActive bool) (updateOK bool, deadFinalMessage map[string]AliveMessage)
  • func (rec *Record) Validate() error
• type RecordSlice
  • func (r RecordSlice) Len() int
  • func (r RecordSlice) Less(i, j int) bool
  • func (r RecordSlice) Swap(i, j int)

Constants

const (
	DB_DIR_FILE_MODE = 0700
	DB_REC_FILE_MODE = 0600
)

const (
	CurrentRecordVersion = 2 // CurrentRecordVersion is the version of new database records to be created by cryptctl.
)

Variables

var RegexUUID = regexp.MustCompile("^[a-zA-Z0-9-]+$") // RegexUUID matches characters that are allowed in a UUID

Functions

func ValidateUUID

func ValidateUUID(in string) error

ValidateUUID returns an error only if the input string is empty, or if there are illegal characters among the input.

Types

type AliveMessage

type AliveMessage struct {
	Hostname  string // Hostname is the host name reported by client computer itself.
	IP        string // IP is the client computer's IP as seen by cryptctl server.
	Timestamp int64  // Timestamp is the moment the message arrived at cryptctl server.
}

AliveMessage is a component of key database record, it represents a heartbeat sent by a computer who is actively using an encryption key - i.e. the encrypted disk is currently unlocked and online.

type DB

type DB struct {
	Dir             string
	RecordsByUUID   map[string]Record // key is record UUID string
	RecordsByID     map[string]Record // when saved by built-in KMIP server, the ID is a sequence number; otherwise it can be anything.
	LastSequenceNum int64             // the last sequence number currently in-use
	Lock            *sync.RWMutex     // prevent concurrent access to records
}

The database of key records reside in a directory, each key record is serialised into a file. All key records are read into memory upon startup for fast retrieval. All exported functions are safe for concurrent usage.

func OpenDB

func OpenDB(dir string) (db *DB, err error)

Open a key database directory and read all key records into memory. Caller should consider to lock memory.

func OpenDBOneRecord

func OpenDBOneRecord(dir, recordUUID string) (db *DB, err error)

Open a key database directory but only load a single record into memory. If the specified record is not found in file system, an error is returned Caller should consider ot lock memory.

func (*DB) Erase

func (db *DB) Erase(uuid string) error

Erase a record from both memory and disk.

func (*DB) GetByID

func (db *DB) GetByID(id string) (rec Record, found bool)

Retrieve a key record by its KMIP ID.

func (*DB) GetByUUID

func (db *DB) GetByUUID(uuid string) (rec Record, found bool)

Retrieve a key record by its disk UUID.

func (*DB) List

func (db *DB) List() (sortedRecords RecordSlice)

Return all key records (not including key content) sorted according to latest usage.

func (*DB) ReadRecord

func (db *DB) ReadRecord(absPath string) (keyRecord Record, err error)

Read and deserialise a key record from file system.

func (*DB) ReloadDB

func (db *DB) ReloadDB() error

(Re)load database records.

func (*DB) ReloadRecord

func (db *DB) ReloadRecord(uuid string) error

ReloadRecord reads the latest record content corresponding to the UUID from disk file and loads it into memory. The function panics if the record version is not the latest.

func (*DB) Select

func (db *DB) Select(aliveMessage AliveMessage, checkMaxActive bool, uuids ...string) (found map[string]Record, rejected, missing []string)

Retrieve key records that belong to those UUIDs, and immediately persist last-retrieval information on those records.

func (*DB) UpdateAliveMessage

func (db *DB) UpdateAliveMessage(latest AliveMessage, uuids ...string) (rejected []string)

Record and immediately persist alive message that came from a host.

func (*DB) UpdateCommandResult

func (db *DB) UpdateCommandResult(uuid, ip string, content interface{}, result string)

UpdateCommandResult updates execution result of a pending command. The pending command is updated by looking for a command record matched to the specified UUID, IP, and content. If a matching record is not found, the function will do nothing.

func (*DB) UpdateSeenFlag

func (db *DB) UpdateSeenFlag(uuid, ip string, content interface{})

UpdateSeenFlag updates "seen" flag of a pending command to true. The flag is updated by looking for a command record matched to the specified IP, array index, and content. If a matching record is not found, the function will do nothing.

func (*DB) UpgradeRecord

func (db *DB) UpgradeRecord(record Record) error

Upgrade a record to the latest version.

func (*DB) UpgradeRecordToVersion1

func (db *DB) UpgradeRecordToVersion1(record Record) error

Record version 0 was the first version prior and equal to cryptctl 1.99 pre-release. Version number 1 gives each record a KMIP key ID, a creation time, and knows whether key content is located on external KMIP server.

func (*DB) Upsert

func (db *DB) Upsert(rec Record) (kmipID string, err error)

Create/update and immediately persist a key record. IO errors are returned and logged to stderr.

type PendingCommand

type PendingCommand struct {
	ValidFrom    time.Time     // ValidFrom is the timestamp at which moment the command was created.
	Validity     time.Duration // Validity determines the point in time the command expires. Expired commands disappear almost immediately.
	IP           string        // IP is the client computer's IP the command is issued to.
	Content      interface{}   // Content is the command content, serialised and transmitted between server and client.
	SeenByClient bool          // SeenByClient is updated to true via RPC once the client has seen this command.
	ClientResult string        // ClientResult is updated via RPC once client has finished executing this command.
}

PendingCommand is a time-restricted command issued by cryptctl server administrator to be polled by a client.

func (*PendingCommand) IsValid

func (cmd *PendingCommand) IsValid() bool

IsValid returns true only if the command has not expired.

type Record

type Record struct {
	ID           string    // ID is assigned by KMIP server for the encryption key.
	Version      int       // Version is the version number of this record. Outdated records are automatically upgraded.
	CreationTime time.Time // CreationTime is the timestamp at which the record was created.
	Key          []byte    // Key is the disk encryption key if the key is not stored on an external KMIP server.

	UUID         string   // UUID is the block device UUID of the file system.
	MountPoint   string   // MountPoint is the location (directory) where this file system is expected to be mounted to.
	MountOptions []string // MountOptions is a string array of mount options specific to the file system.

	MaxActive        int // MaxActive is the maximum simultaneous number of online users (computers) for the key, or <=0 for unlimited.
	AliveIntervalSec int // AliveIntervalSec is interval in seconds that all key users (computers) should report they're online.
	AliveCount       int // AliveCount is number of times a key user (computer) can miss regular report and be considered offline.

	LastRetrieval   AliveMessage                // LastRetrieval is the computer who most recently successfully retrieved the key.
	AliveMessages   map[string][]AliveMessage   // AliveMessages are the most recent alive reports in IP - message array pairs.
	PendingCommands map[string][]PendingCommand // PendingCommands are some command to be periodcally polled by clients carrying the IP address (keys).
}

A key record that knows all about the encrypted file system, its mount point, and unlocking keys. When stored on disk, the record resides in a file encoded in gob. The binary encoding method is intentionally chosen to deter users from manually editing the files on disk.

func (*Record) AddPendingCommand

func (rec *Record) AddPendingCommand(ip string, cmd PendingCommand)

AddPendingCommand stores a command associated to the input IP address, and clears expired pending commands along the way.

func (*Record) ClearPendingCommands

func (rec *Record) ClearPendingCommands()

ClearPendingCommands removes all pending commands, and clears expired pending commands along the way.

func (*Record) Deserialise

func (rec *Record) Deserialise(in []byte) error

Deserialise record from input binary content using gob encoding.

func (*Record) FillBlanks

func (rec *Record) FillBlanks()

Initialise all nil attributes.

func (*Record) FormatAttrs

func (rec *Record) FormatAttrs(separator string) string

Format all attributes (except the binary key) for pretty printing, using the specified separator.

func (*Record) GetMountOptionStr

func (rec *Record) GetMountOptionStr() string

Return mount options in a single string, as accepted by mount command.

func (*Record) IsHostAlive

func (rec *Record) IsHostAlive(hostIP string) (alive bool, finalMessage AliveMessage)

Determine whether a host is still alive according to recent alive messages.

func (*Record) RemoveDeadHosts

func (rec *Record) RemoveDeadHosts() (deadFinalMessage map[string]AliveMessage)

Remove all dead hosts from alive message history, return each dead host's final alive .

func (*Record) RemoveExpiredPendingCommands

func (rec *Record) RemoveExpiredPendingCommands()

RemoveDeadPendingCommands removes pending commands and results that were made 10x validity period in the past.

func (*Record) Serialise

func (rec *Record) Serialise() []byte

Serialise the record into binary content using gob encoding.

func (*Record) UpdateAliveMessage

func (rec *Record) UpdateAliveMessage(latestBeat AliveMessage) bool

Record the latest alive message in message history.

func (*Record) UpdateLastRetrieval

func (rec *Record) UpdateLastRetrieval(latestBeat AliveMessage, checkMaxActive bool) (updateOK bool,
	deadFinalMessage map[string]AliveMessage)

If number of maximum active users must be enforced, determine number of active key users from alive message history - if the maximum number is not yet exceeded, update last retrieval information and alive message history for the host; if maximum number is already met, the last retrieval information and alive message history are left untouched.

If number of maximum active users is not enforced, the last retrieval information and alive message history are unconditionally updated.

func (*Record) Validate

func (rec *Record) Validate() error

Return an error if a record attribute does not make sense.

type RecordSlice

type RecordSlice []Record // a slice of key database records that can be sorted by latest usage.

func (RecordSlice) Len

func (r RecordSlice) Len() int

func (RecordSlice) Less

func (r RecordSlice) Less(i, j int) bool

func (RecordSlice) Swap

func (r RecordSlice) Swap(i, j int)