heimdall

README

Heimdall

Heimdall is a simple library for signing and verifying messages written by Golang.

Definition of Heimdall

• In Norse mythology, Heimdall guarded the Bifrost, which the Vikings believed rainbows came from

• Heimdall also appears in the Marvel cinematic universe.

  Heimdall is the all-seeing and all-hearing Asgardian and former guard of the Bifrost Bridge.

Getting Started with Heimdall

Installation

go get -u github.com/DE-labtory/heimdall

Usage

1. Load crypto configuration (maybe from configuration file)

// In this sample, we use default configuration that equals to use heimdall.NewDefaultConfig()
myConfig, err := heimdall.NewConfig(
    192,                        // security level
    heimdall.TestKeyDir,        // key directory path
    heimdall.TestCertDir,       // certificate directory path
    "AES-CTR",                  // encryption algorithm and operation mode name
    "ECDSA",                    // signing algorithm name
    "scrypt",                   // key derivation function name
    heimdall.DefaultScrpytParams, // key derivation function parameters
)

2. Generate key pair

// Generate key pair
privateKey, err := heimdall.GenerateKey(myConfig.CurveOpt)

// public key can be obtained like below
publicKey := &privateKey.PublicKey

3. Minimize key size (bytes <--> key)

The key bytes from these functions have a component for recovering the key.

// private key to bytes(from bytes)
bytePri := heimdall.PriKeyToBytes(privateKey)
recPri, err := heimdall.BytesToPriKey(bytePri, myConfig.CurveOpt)

// public key to bytes(from bytes)
bytePub := heimdall.PubKeyToBytes(publicKey)
recPub, err := heimdall.BytesToPubKey(bytePub, myConfig.CurveOpt)

4. Key ID

Keys can be identified by below key ID with prefix that is "IT" for it-chain.
Key IDs from private key and public key are equal, so we use public key .

// key ID from public key directly
keyId := PubKeyToKeyID(publicKey)

// key ID from SKI(Subject Key Identifier) used in certificate
ski := heimdall.SKIFromPubKey(publicKey)
keyId := heimdall.SKIToKeyID(ski)

// SKI from key ID
recSki := heimdall.SKIFromKeyID(keyId)

5. Store and load key by keystore

// make new keystore
ks, err := heimdall.NewKeyStore(myConFig.KeyDirPath, myConFig.Kdf, myConFig.KdfParams, myConFig.EncAlgo, myConFig.EncKeyLength)

// storing private key with password for encryption of private key
err = ks.StoreKey(privateKey, "password")

// load private key by key ID and password
loadedPri, err := ks.LoadKey(keyId, "password")

6. Store and load certificate by certstore

Assume that 'cert' is a x.509 certificate of 'publicKey' which can be identified by 'keyId'

// make certstore
certstore, err := heimdall.NewCertStore(myConFig.CertDirPath)

// store certificate as .crt file named as its key ID
err = certstore.StoreCert(cert)

// load certificate by key ID
cert, err = certstore.LoadCert(keyId string)

7. Verify certificate

// verify certificate chain (check if the chain of trust is right in local)
err = certstore.VerifyCertChain(cert)

// verify certificate (check if expired or revoked)
timeValid, notRevoked, err := heimdall.VerifyCert(cert)

8. Make signature for data and verify the signature

sampleData := []byte("This is sample data for signing and verifying.")

// signing (making signature)
signature, err := heimdall.Sign(pri, sampleData, nil, myConFig.HashOpt)

/* --------- After data transmitted --------- */
/* --------- In receiver node --------- */
// verify signature with public key
ok, err := heimdall.Verify(pub, signature, sampleData, nil, myConFig.HashOpt)
// verify signature with certificate
ok, err = heimdall.VerifyWithCert(clientCert, signature, sampleData, nil, myConFig.HashOpt)

Features

Signature algorithms

Currently, we support following Signature algorithms with options to provide wide selection range of key length.

• ECDSA ( 224 / 256 / 384 / 512 )

Hash functions

You can make hash data by using SHA Algorithm with various type.

• SHA ( 224 / 256 / 384 / 512 )

Default key storage path

If you enter empty path for your keystore such as "", your private key will be stored in below location.

(Current Directory)/.heimdall/.key

Lincese

Heimdall source code files are made available under the Apache License, Version 2.0 (Apache-2.0), located in the LICENSE file.

Documentation

Index

• Constants
• Variables
• func KeyIDPrefixCheck(keyId string) error
• func SKIToKeyID(ski []byte) string
• func SKIValidCheck(keyId string, ski []byte) error
• type Key
• type KeyGenOpts
• type KeyID
• type KeyRecoverer
• type PriKey
• type PubKey
• type SignerOpts

Constants

const KeyIDPrefix = "IT"

Key ID prefix

Variables

var OptDelimiter = "_"

var RootDir = filepath.Dir(WorkingDir)

var TestCertDir = filepath.Join(WorkingDir, "./.testCerts")

var TestKeyDir = filepath.Join(WorkingDir, "./.testKeys")

var TestPriKeyDir = filepath.Join(WorkingDir, "./.private_key")

var TestPubKeyDir = filepath.Join(WorkingDir, "./.public_keys")

var WorkingDir, _ = os.Getwd()

directories for test

Functions

func KeyIDPrefixCheck

func KeyIDPrefixCheck(keyId string) error

KeyIDPrefixCheck checks if input key id has right prefix.

func SKIToKeyID

func SKIToKeyID(ski []byte) string

SKIToKeyID obtains key ID from SKI(Subject Key Identifier).

func SKIValidCheck

func SKIValidCheck(keyId string, ski []byte) error

SKIValidCheck checks if input SKI is corresponding to key id.

Types

type Key

type Key interface {
	ID() KeyID
	SKI() []byte
	ToByte() ([]byte, error)
	KeyGenOpt() KeyGenOpts
	IsPrivate() bool
}

type KeyGenOpts

type KeyGenOpts interface {
	ToString() string
	KeySize() int
}

KeyGenOpts provides key generation options such as elliptic curve or rsa bits etc.

type KeyID

type KeyID = string

type KeyRecoverer

type KeyRecoverer interface {
	RecoverKeyFromByte(keyBytes []byte, isPrivate bool) (Key, error)
}

type PriKey

type PriKey interface {
	Key
	Clear()
	PublicKey() PubKey
}

type PubKey

type PubKey interface {
	Key
}

type SignerOpts

type SignerOpts interface {
	Algorithm() string
	HashOpt() *hashing.HashOpt
}

SignerOpts provides signer option for signing