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, etc...

Boltdb file is always open in the file system unless 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 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

header code

package main

import (
    "encoding/json"
    "fmt"

    "github.com/linkthings/boltsec"
)

type article struct {
    ID            string
    Name          string
}

func main() {
    bucketName := "article"
    dbm, _ := boltsec.NewDBManager("test.dat", "", "secret", false, []string{bucketName})

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

    dbm.Save(bucketName, data.ID, data)

    var bytes []byte
    bytes, _ = dbm.GetOne(bucketName, data.ID)

    resNew := new(article)
    json.Unmarshal(bytes, resNew)

    if resNew.Name == data.Name {
        fmt.Printf("Decrypted data matches origional input:\nDecrypted:%s\nOriginal:%s\n", resNew.Name, data.Name)
    }

    dbm.Delete(bucketName, data.ID)
}

A complete example with error handling and testing can be found in the example folder

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 []byte) error
  • func (dbm *DBManager) SetBatchMode(mode bool)
  • func (dbm *DBManager) SetSecret(secret string) (err error)
• type ProtobufArticle
  • func (*ProtobufArticle) Descriptor() ([]byte, []int)
  • func (m *ProtobufArticle) GetID() string
  • func (m *ProtobufArticle) GetTitle() string
  • func (*ProtobufArticle) ProtoMessage()
  • func (m *ProtobufArticle) Reset()
  • func (m *ProtobufArticle) String() string
  • func (m *ProtobufArticle) XXX_DiscardUnknown()
  • func (m *ProtobufArticle) XXX_Marshal(b []byte, deterministic bool) ([]byte, error)
  • func (m *ProtobufArticle) XXX_Merge(src proto.Message)
  • func (m *ProtobufArticle) XXX_Size() int
  • func (m *ProtobufArticle) XXX_Unmarshal(b []byte) 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
}

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)

NewDBManager is 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

Delete function deletes the record specified by the key.

func (*DBManager) GetByPrefix

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

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)

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

func (*DBManager) GetOne

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

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 []byte) error

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

type ProtobufArticle

type ProtobufArticle struct {
	ID                   string   `protobuf:"bytes,1,opt,name=ID,proto3" json:"ID,omitempty"`
	Title                string   `protobuf:"bytes,2,opt,name=Title,proto3" json:"Title,omitempty"`
	XXX_NoUnkeyedLiteral struct{} `json:"-"`
	XXX_unrecognized     []byte   `json:"-"`
	XXX_sizecache        int32    `json:"-"`
}

func (*ProtobufArticle) Descriptor

func (*ProtobufArticle) Descriptor() ([]byte, []int)

func (*ProtobufArticle) GetID

func (m *ProtobufArticle) GetID() string

func (*ProtobufArticle) GetTitle

func (m *ProtobufArticle) GetTitle() string

func (*ProtobufArticle) ProtoMessage

func (*ProtobufArticle) ProtoMessage()

func (*ProtobufArticle) Reset

func (m *ProtobufArticle) Reset()

func (*ProtobufArticle) String

func (m *ProtobufArticle) String() string

func (*ProtobufArticle) XXX_DiscardUnknown

func (m *ProtobufArticle) XXX_DiscardUnknown()

func (*ProtobufArticle) XXX_Marshal

func (m *ProtobufArticle) XXX_Marshal(b []byte, deterministic bool) ([]byte, error)

func (*ProtobufArticle) XXX_Merge

func (m *ProtobufArticle) XXX_Merge(src proto.Message)

func (*ProtobufArticle) XXX_Size

func (m *ProtobufArticle) XXX_Size() int

func (*ProtobufArticle) XXX_Unmarshal

func (m *ProtobufArticle) XXX_Unmarshal(b []byte) error