storage

Documentation

Overview

Package storage : The secureStorage package provides implementation of Secure storage services: Persistence mechanism based on AES Encryption of key-value pairs within a signed file.

The secure storgae allows maintaining data persistently and securely.

The implementation of the secure storage is based on encrypted key-value pairs that are stored
 in signed files to guarantee that the data is not altered or corrupted.
- Both the key and the value are encrypted when they are added to the storage using an Advanced Encryption Standard (AES) algorithm.
- Each time a new secure storage is generated, a secret supplied by the user accompanies it
  and is used in all HMAC and AES calculations related to that storage. To make it difficult for a third party to decipher or use the stored data,
  Cipher Block Chaining (CBC) mode is used to ensure that multiple independent encryptions of the same data with the same key have different results.
  That is, when a block with the same piece of plain text is encrypted with the same key, the result is always different.
- To implement a time efficient secure storage with keys, that is, to identify keys that are
  already stored without decrypting the entire storage, and when such a key is identified replacing its value, a two step mechanism is used.
  The first time a key is introduced, a new IV is drawn, the key is 'HMAC'ed with the secret and is stored with the IV as the value (1st step).
  The original key is encrypted with the drawn IV and stored again, this time with the value that is encrypted with its own random IV (2nd step).
  The next time that same key is stored, the algorithm, identifies that it already exists in the storage, pulls out the random IV that was stored in the 1st step,
  finds the 2nd step storage of that key and replaces its value with the new encrypted one.
- To guarantee that the data is not altered or corrupted, the storage is signed using HMAC. The signature is added to the secure storage. When the storage is loaded,
  the HMAC is calculated and compared with the stored signature to verify that the file is genuine.

Example (Storage)

This example shows how to create a new secure storage list. 1. Add 10 new items with the following format: key: "The key is: %v", Value: "The data is (sum of key digits): %v" 2. Print it 3. Save it to file 4. Remove 1 item from it 5. Print it again 6. Read the saved storage 7. Print it again

package main

import (
	"crypto/rand"
	"fmt"
	"io"
	"os"

	ss "github.com/ibm-security-innovation/libsecurity-go/storage"
)

const (
	keyFmt  = "The key is: %v"
	dataFmt = "The data is (sum of key digits): %v"
)

var (
	aesSecretLen = 32
)

func init() {
}

func generateSecureStorage() (*ss.SecureStorage, []byte) {
	var secret []byte

	secret = make([]byte, aesSecretLen)
	io.ReadFull(rand.Reader, secret)
	storage, _ := ss.NewStorage(secret, false)
	for i := 0; i < 10; i++ {
		keyText := fmt.Sprintf(keyFmt, i)
		dataText := fmt.Sprintf(dataFmt, i*10+1)
		storage.AddItem(keyText, dataText)
	}
	return storage, secret
}

func playWithSecureStorage(storage *ss.SecureStorage, secret []byte) {
	fileName := "try.txt"
	defer os.Remove(fileName)
	err := storage.StoreInfo(fileName)
	if err != nil {
		fmt.Println("Error while saving:", err)
	}

	fmt.Println("Original data:")
	fmt.Println(storage.GetDecryptStorageData())

	keyText := fmt.Sprintf(keyFmt, 1)
	err = storage.RemoveItem(keyText)
	if err != nil {
		fmt.Println("Error while remove key:", err)
	}

	fmt.Println("After removing:")
	fmt.Println(storage.GetDecryptStorageData())

	sd, err := ss.LoadInfo(fileName, secret)
	if err != nil {
		fmt.Println("Error while reading:", err)
	}
	fmt.Println("The data that was read from file:", fileName)
	fmt.Println(sd.GetDecryptStorageData())
}

// This example shows how to create a new secure storage list.
// 1. Add 10 new items with the following format: key: "The key is: %v", Value: "The data is (sum of key digits): %v"
// 2. Print it
// 3. Save it to file
// 4. Remove 1 item from it
// 5. Print it again
// 6. Read the saved storage
// 7. Print it again
func main() {
	storage, secret := generateSecureStorage()
	playWithSecureStorage(storage, secret)
}

Index

• Constants
• func GetSecureKey(secureKeyFilePath string) []byte
• type SecureDataMap
• type SecureStorage
  • func LoadInfo(fileName string, secret []byte) (*SecureStorage, error)
  • func NewStorage(secret []byte, checkSecretStrength bool) (*SecureStorage, error)
  • func (s *SecureStorage) AddItem(key string, value string) error
  • func (s SecureStorage) GetDecryptStorageData() *SecureStorage
  • func (s *SecureStorage) GetItem(key string) (string, error)
  • func (s *SecureStorage) IsSecretMatch(secret []byte) bool
  • func (s *SecureStorage) RemoveItem(key string) error
  • func (s SecureStorage) StoreInfo(fileName string) error
  • func (s SecureStorage) String() string

Examples

• Package (Storage)

Constants

const (
	// FilePermissions : linux style read/write for the owner
	FilePermissions = 0600
	// MaxSaltLen : the maximum salting string length
	MaxSaltLen = 16
	// SaltLen : the default salting string length
	SaltLen = 8
	// SecretLen : the default secret string length
	SecretLen = 16

	// SaltData : the default salting string
	SaltData = "Ravid"
)

Functions

func GetSecureKey

func GetSecureKey(secureKeyFilePath string) []byte

GetSecureKey : Read a secure key from the given file, process it with cryptographic manipulations and return it

Types

type SecureDataMap

type SecureDataMap map[string]string

SecureDataMap : hash to map the modules data

type SecureStorage

type SecureStorage struct {
	Salt    []byte
	Sign    []byte
	Data    SecureDataMap
	Version string
	// contains filtered or unexported fields
}

SecureStorage : structure that holds all the secure data to be store/read from the storage include the calculated signature (the secret is not stored on the disk)

func LoadInfo

func LoadInfo(fileName string, secret []byte) (*SecureStorage, error)

LoadInfo : Read a secure storage from file (JSON format), verify that the file is genuine by calculating the expected signature

func NewStorage

func NewStorage(secret []byte, checkSecretStrength bool) (*SecureStorage, error)

NewStorage : Create a new storage using the given secret

func (*SecureStorage) AddItem

func (s *SecureStorage) AddItem(key string, value string) error

AddItem : Add (or replace) to the storage a new item using the given key and value

func (SecureStorage) GetDecryptStorageData

func (s SecureStorage) GetDecryptStorageData() *SecureStorage

GetDecryptStorageData : Get the decrypted storgae information

func (*SecureStorage) GetItem

func (s *SecureStorage) GetItem(key string) (string, error)

GetItem : Return from storage the item that is associated with the given key

func (*SecureStorage) IsSecretMatch

func (s *SecureStorage) IsSecretMatch(secret []byte) bool

IsSecretMatch : Verify if the given secret match the secure stiorage secret use throttling

func (*SecureStorage) RemoveItem

func (s *SecureStorage) RemoveItem(key string) error

RemoveItem : Remove from the storage the item that is associated with the given key

func (SecureStorage) StoreInfo

func (s SecureStorage) StoreInfo(fileName string) error

StoreInfo : Sign the secure storage and than store it to a given file path without the secret

func (SecureStorage) String

func (s SecureStorage) String() string