frontalnh/heimdall

Simple library that keeps your data secure through signing and verification 🔑

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/it-chain/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.