crypto

README

crypto

Table of Contents

• Features
• Usage
  • dsa
    • Key Generation
    • Signing
    • Verifying
• Directory Structure

Features

• secp256k1 keygen, deterministic signing, and verification
• ed25519 keygen, signing, and verification
• higher-level API for ecdsa (Elliptic Curve Digital Signature Algorithm)
• higher-level API for eddsa (Edwards-Curve Digital Signature Algorithm)
• higher level API for dsa in general (Digital Signature Algorithm)
• KeyManager interface that can leveraged to manage/use keys (create, sign etc) as desired per the given use case. examples of concrete implementations include: AWS KMS, Azure Key Vault, Google Cloud KMS, Hashicorp Vault etc
• Concrete implementation of KeyManager that stores keys in memory

Usage

dsa

Key Generation

the dsa package provides algorithm ID's that can be passed to the GenerateKey function i.e.

package main

import (
  "fmt"        
  "github.com/abaxxtech/abaxx-id-go/pkg/crypto/dsa"
)

func main() {
  privateJwk, err := dsa.GeneratePrivateKey(dsa.AlgorithmIDSECP256K1)
  if err != nil {
    fmt.Printf("Failed to generate private key: %v\n", err)
    return
  }
}

Signing

Signing takes a private key and a payload to sign. e.g.

package main

import (
  "fmt"
  "github.com/abaxxtech/abaxx-id-go/pkg/crypto/dsa"
)

func main() {
  // Generate private key
  privateJwk, err := dsa.GeneratePrivateKey(dsa.AlgorithmIDSECP256K1)
  if err != nil {
    fmt.Printf("Failed to generate private key: %v\n", err)
    return
  }

  // Payload to be signed
  payload := []byte("hello world")

  // Signing the payload
  signature, err := dsa.Sign(payload, privateJwk)
  if err != nil {
    fmt.Printf("Failed to sign: %v\n", err)
    return
  }
}

Verifying

Verifying takes a public key, the payload that was signed, and the signature. i.e.

package main

import (
  "fmt"
  "github.com/abaxxtech/abaxx-id-go/pkg/crypto/dsa"
)

func main() {
  // Generate ED25519 private key
  privateJwk, err := dsa.GeneratePrivateKey(dsa.AlgorithmIDED25519)
  if err != nil {
    fmt.Printf("Failed to generate private key: %v\n", err)
    return  
  }

  // Payload to be signed
  payload := []byte("hello world")

  // Sign the payload
  signature, err := dsa.Sign(payload, privateJwk)
  if err != nil {
    fmt.Printf("Failed to sign: %v\n", err)
    return
  }

  // Get the public key from the private key
  publicJwk := dsa.GetPublicKey(privateJwk)

  // Verify the signature
  legit, err := dsa.Verify(payload, signature, publicJwk)
  if err != nil {
    fmt.Printf("Failed to verify: %v\n", err)
    return
  }

  if !legit {
    fmt.Println("Failed to verify signature")
  } else {
    fmt.Println("Signature verified successfully")
  }
}

ecdsa and eddsa provide the same high level api as dsa, but specifically for algorithms within those respective families. this makes it so that if you add an additional algorithm, it automatically gets picked up by dsa as well.

Directory Structure

crypto
├── README.md
├── doc.go
├── dsa
│   ├── README.md
│   ├── dsa.go
│   ├── dsa_test.go
│   ├── ecdsa
│   │   ├── ecdsa.go
│   │   ├── secp256k1.go
│   │   └── secp256k1_test.go
│   └── eddsa
│       ├── ed25519.go
│       └── eddsa.go
├── keymanager.go
└── keymanager_test.go

Documentation

Overview

Package crypto provides the following functionality: * Key Generation: secp256k1, ed25519 * Signing: secp256k1, ed25519 * Verification: secp256k1, ed25519 * A KeyManager abstraction that can be leveraged to manage/use keys (create, sign etc) as desired per the given use case

Index

• func GenerateEntropy(n EntropySize) ([]byte, error)
• func GenerateNonce(n EntropySize) (string, error)
• type EntropySize
• type KeyExporter
• type KeyImporter
• type KeyManager
• type LocalKeyManager
  • func NewLocalKeyManager() *LocalKeyManager
  • func (k *LocalKeyManager) ExportKey(keyID string) (jwk.JWK, error)
  • func (k *LocalKeyManager) GeneratePrivateKey(algorithmID string) (string, error)
  • func (k *LocalKeyManager) GetPublicKey(keyID string) (jwk.JWK, error)
  • func (k *LocalKeyManager) ImportKey(key jwk.JWK) (string, error)
  • func (k *LocalKeyManager) Sign(keyID string, payload []byte) ([]byte, error)

Functions

func GenerateEntropy

func GenerateEntropy(n EntropySize) ([]byte, error)

GenerateEntropy generates a random byte array of size n bytes

func GenerateNonce

func GenerateNonce(n EntropySize) (string, error)

GenerateNonce generates a hex-encoded nonce by calling GenerateEntropy with a size of 16 bytes (128 bits)

Types

type EntropySize

type EntropySize int

EntropySize represents the size of the entropy in bits, i.e. Entropy128 is equal to 128 bits (or 16 bytes) of entrop

const (
	Entropy112 EntropySize = 112 / 8 // 14 bytes
	Entropy128 EntropySize = 128 / 8 // 16 bytes
	Entropy192 EntropySize = 192 / 8 // 24 bytes
	Entropy256 EntropySize = 256 / 8 // 32 bytes
)

Directly set the sizes according to NIST recommendations for entropy defined here: https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-90Ar1.pdf

type KeyExporter

type KeyExporter interface {
	ExportKey(keyID string) (jwk.JWK, error)
}

KeyExporter is an abstraction that can be leveraged to implement types which intend to export keys

type KeyImporter

type KeyImporter interface {
	ImportKey(key jwk.JWK) (string, error)
}

KeyImporter is an abstraction that can be leveraged to implement types which intend to import keys

type KeyManager

type KeyManager interface {
	// GeneratePrivateKey generates a new private key, stores it in the key store and returns the key id
	GeneratePrivateKey(algorithmID string) (string, error)

	// GetPublicKey returns the public key for the given key id
	GetPublicKey(keyID string) (jwk.JWK, error)

	// Sign signs the given payload with the private key for the given key id
	Sign(keyID string, payload []byte) ([]byte, error)
}

KeyManager is an abstraction that can be leveraged to manage/use keys (create, sign etc) as desired per the given use case examples of concrete implementations include: AWS KMS, Azure Key Vault, Google Cloud KMS, Hashicorp Vault etc

type LocalKeyManager

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

LocalKeyManager is an implementation of KeyManager that stores keys in memory

func NewLocalKeyManager

func NewLocalKeyManager() *LocalKeyManager

NewLocalKeyManager returns a new instance of InMemoryKeyManager

func (*LocalKeyManager) ExportKey

func (k *LocalKeyManager) ExportKey(keyID string) (jwk.JWK, error)

ExportKey exports the key specific by the key ID from the LocalKeyManager

func (*LocalKeyManager) GeneratePrivateKey

func (k *LocalKeyManager) GeneratePrivateKey(algorithmID string) (string, error)

GeneratePrivateKey generates a new private key using the algorithm provided, stores it in the key store and returns the key id

func (*LocalKeyManager) GetPublicKey

func (k *LocalKeyManager) GetPublicKey(keyID string) (jwk.JWK, error)

GetPublicKey returns the public key for the given key id

func (*LocalKeyManager) ImportKey

func (k *LocalKeyManager) ImportKey(key jwk.JWK) (string, error)

ImportKey imports the key into the LocalKeyManager and returns the key alias

func (*LocalKeyManager) Sign

func (k *LocalKeyManager) Sign(keyID string, payload []byte) ([]byte, error)

Sign signs the payload with the private key for the given key id