boltsec

README

boltsec

A boltdb wrapper to encrypt and decrypt the values stored in the boltdb via AES Cryptor, and also provides common db operations such as GetOne, GetByPrefix, GetKeyList, Save, Delete and etc.

Boltdb file is always open in the file system unless the DB.Close() is called, which cause inconvenience if you want to do some file operations to the db file while the program is running. This package provides the parameter: batchMode to control whether to close the db after each db operation, this has performance impact but could be a useful feature.

Features

1. Support AES to encrypt and decrypt the values
2. Batch mode option to control whether to close the db after each db operation
3. Initialize db file and cryptor

Performance

The below is the benchmark data for the DB related operations.

BenchmarkDBMOps-8               	    2000	   1114202 ns/op
BenchmarkDBMOpsBatchMode-8      	    5000	    383995 ns/op
BenchmarkDBMOpsNoEncryption-8   	    1000	   1029510 ns/op

LICENSE

This project is under license MIT

Usage Example

var err error
bucketName := "article"

dbm, err := NewDBManager("test.dat", "example", "secret", false, []string{bucketName})

data := Article{
	ID: "ID-0001", 
	Title: "input with more than 16 characters", 
}

if err=dbm.Save(bucketName, data.ID, data); err != nil {
	t.Errorf("TestDBMCreate save data return err: %s", err)
}

var bytes []byte
if bytes, err = dbm.GetOne(bucketName, data.ID); err != nil {
	t.Errorf("TestDBMCreate GetOne return err: %s", err)
}

resNew := new(Article)
if err = json.Unmarshal(bytes, resNew); err != nil {
    t.Errorf("json.Unmarshal return err: %s", err)
}

if resNew.Title != data.Title {
	t.Errorf("returned Title is not equal: new:%s, org: %s", resNew.Title, data.Title)
}

if err=dbm.Delete(bucketName, data.ID); err != nil {
	t.Errorf("TestDBMCreate Delete return err: %s", err)
}

A example code can be found in example folder on how to utilize this package

Documentation

Overview

A boltdb wrapper to encrypt and decrypt the values stored in the boltdb via AES Cryptor, and also provides db operations functions

Index

• Variables
• type DBManager
  • func NewDBManager(name, path, secret string, batchMode bool, buckets []string) (dbm *DBManager, err error)
  • func (dbm *DBManager) Delete(bucket, key string) error
  • func (dbm *DBManager) GetByPrefix(bucket, prefix string) ([][]byte, error)
  • func (dbm *DBManager) GetKeyList(bucket, prefix string) ([]string, error)
  • func (dbm *DBManager) GetOne(bucket, key string) ([]byte, error)
  • func (dbm *DBManager) Save(bucket, key string, data interface{}) error
  • func (dbm *DBManager) SetBatchMode(mode bool)
  • func (dbm *DBManager) SetSecret(secret string) (err error)

Examples

• NewDBManager

Variables

var (
	ErrFileNameInvalid = errors.New("invalid file name")
	ErrPathInvalid     = errors.New("invalid path name")
	ErrKeyInvalid      = errors.New("invalid key or key is nil")
)

The key error messages generated in the package

var Debug = false

var Logger = log.New(os.Stdout, "[DB] ", log.LstdFlags)

Types

type DBManager

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

The DBManager struct, all fields are not needed to be accessed by other packages

func NewDBManager

func NewDBManager(name, path, secret string, batchMode bool, buckets []string) (dbm *DBManager, err error)

The main function to initialize the the DB manager for all DB related operations

name: the db file name, such as mydb.dat, mytest.db
path: the db file's path, can be "" or any other director
secret: the secret value if you want to encrypt the values; if you don't want to encrypt the data, simply put it as ""
batchMode: to control whether to close the db file after each db operation
buckets: the buckets in the db file to be initialized if the db file does not existed

Example

var err error
bucketName := "article"

dbm, err := NewDBManager("test.dat", "example", "secret", false, []string{bucketName})

if err != nil {
	// Handle the error
}

var bytes []byte
if bytes, err = dbm.GetOne(bucketName, "data.ID"); err != nil {
	// handle the error
}

resNew := new(Article)
if err = json.Unmarshal(bytes, resNew); err != nil {
	// handle the error
}

func (*DBManager) Delete

func (dbm *DBManager) Delete(bucket, key string) error

The Delete function deletes the record specified by the key.

func (*DBManager) GetByPrefix

func (dbm *DBManager) GetByPrefix(bucket, prefix string) ([][]byte, error)

The GetByPrefix function returns the byte arrays for those records matched with specified Prefix. If the secret is set, the function returns the decrypted content.

func (*DBManager) GetKeyList

func (dbm *DBManager) GetKeyList(bucket, prefix string) ([]string, error)

The GetKeyList function returns the string array for keys with specified Prefix.

func (*DBManager) GetOne

func (dbm *DBManager) GetOne(bucket, key string) ([]byte, error)

The GetOne function returns the first record containing the key, If the secret is set, the function returns the decrypted content.

func (*DBManager) Save

func (dbm *DBManager) Save(bucket, key string, data interface{}) error

The Save function stores the record into the db file. If the secret value is set, the function encrypts the content before storing into the db.

func (*DBManager) SetBatchMode

func (dbm *DBManager) SetBatchMode(mode bool)

SetBatchMode is to set the batchMode for the boltdb. The boltdb file is always open in the file system unless the Close() is called. This cause inconvenience if you want to do some file operation to the db file while the program is running. Thus if the batchMode is set to false, the db will be closed after each db operation, this could reduce a certain performance. Thus if you have a lots of db operations to execute, you can set the batchMode to be true before those operations.

func (*DBManager) SetSecret

func (dbm *DBManager) SetSecret(secret string) (err error)

SetSecret is to set the AES Cryptor key, if the key is nil, the cryptor is not initialized; otherwise the cryptor is initialized, including the key and Cipher block that can be used directly for encrypt and decrypt functions