key

package module
v2.0.8 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 11, 2024 License: MIT Imports: 14 Imported by: 2

README

Golang Key library

Golang library to

  • sign and verify signature using ED25519, ECDSA or RSA public/private keys.
  • creating shared keys using Curve25519 or ECDH.
  • Encode keys to JWK (public/private keys ONLY).
  • Decode JWK to keys (public/private keys ONLY).

Key Usage

Generating keys

Possible key types that can be generated are

  • ED25519 - ED25519 256 bit
  • ECDSA256 - ECDSA 256 bit
  • ECDSA384 - ECDSA 384 bit
  • ECDSA521 - ECDSA 521 bit
  • RSA2048 - RSA 2048 bit
  • RSA4096 - RSA 4096 bit
  • RSA8192 - RSA 8192 bit
// create a new instance of Key
k, err := GenerateKey(ED25519)
if nil != err {
    fmt.Println(err)
    os.Exit(1)
}
fmt.Println("JWK:", k)
Decode JWK string to key
// create an instance of Key from an existing JWK string
k, err := NewKeyFromStr("{\"crv\":\"Ed25519\",\"d\":\"vUjQ3PaX8iqHA0Q58Wf7mN8h-oMgAE_cFQDfi0Sr2Js\",\"kty\":\"OKP\",\"x\":\"etHd2wg1POjqvQZ3yhiwwU2JRwCtcqzYQIOmp7BnnSo\"}")
if nil != err {
    fmt.Println(err)
    os.Exit(1)
}
fmt.Println("JWK:", k)
Signing hashed data
// assume a key instance already exists from generation or decoding a JWK string

// signing data is done over a hash of existing data
s := sha3.New256()
s.Write([]byte("hello, "))
s.Write([]byte("world"))

h := s.Sum(nil)

// k is an instance of Key
signed, err := k.Sign(h)
if nil != err {
    fmt.Println(err)
    os.Exit(1)
}
fmt.Println(base64.StdEncoding.EncodeToString(signed))
Verifying hashed data
// assume a key instance already exists from generation or decoding a JWK string

if k.Verify(signed, h) {
    fmt.Println("verified data for ED25519")
} else {
    fmt.Println("unable to verify data for ED25519")
}
Complete example
k, err := GenerateKey(ED25519)
if nil != err {
    fmt.Println(err)
    os.Exit(1)
}
fmt.Println("JWK:", k)

kPub, err := k.PublicKey()
if nil != err {
    fmt.Println(err)
    os.Exit(1)
}
//fmt.Println("JWK:", kPub)

k2, err := NewKeyFromStr(kPub.String())
if nil != err {
    fmt.Println(err)
    os.Exit(1)
}
fmt.Println("JWK:", k2)

s := sha3.New256()
s.Write([]byte("hello, "))
s.Write([]byte("world"))

h := s.Sum(nil)

signed, err := k.Sign(h)
if nil != err {
    fmt.Println(err)
    os.Exit(1)
}
fmt.Println(base64.StdEncoding.EncodeToString(signed))

//h = append(h, []byte("abcd")...)
if k2.Verify(signed, h) {
    fmt.Println("verified data for ED25519")
} else {
    fmt.Println("unable to verify data for ED25519")
}

Key Exchange

Generating keys

Possible key types that can be generated are

  • CURVE255519 - ED25519Curve25519 256 bit
  • ECDH256 - ECDH 256 bit
  • ECDH384 - ECDH 384 bit
  • ECDH521 - ECDH 521 bit
// create a new instance of Key
a, err := GenerateKeyExchange(CURVE25519)
if nil != err {
    fmt.Println(err)
    os.Exit(1)
}

fmt.Println("A private key:\t", a)
fmt.Println("A public key:\t", a.PublicKey())
Decode key exchange from string
aStr := "ybAlYu1qLcRoiMZKDfuFy8yUTU2TxXRpoYY4xvCjmUfq"

a, err := NewKXFromStr(aStr)
if nil != err {
    fmt.Println(err)
    os.Exit(1)
}
fmt.Println("A private key type: ", a.KeyType())
fmt.Println("A private key length: ", a.Length())
fmt.Println("A private key:\t", a)
aPub := a.PublicKey()
fmt.Println("A public key:\t", aPub)
fmt.Println("A public key length:\t", aPub.Length())
Creating shared key
// for a shared key, we would require A's private key and B's public key
// both A and B **MUST** be using the same type of key exchange i.e. CURVE25519 or ECDH*
// assume both have been generated or converted from string

sharedSecretA, err := a.SharedSecret(b.PublicKey())
if nil != err {
    fmt.Println(err)
    os.Exit(1)
}
fmt.Println("A shared secret with B:\t", base64.StdEncoding.EncodeToString(sharedSecretA))

sharedSecretB, err := b.SharedSecret(a.PublicKey())
if nil != err {
    fmt.Println(err)
    os.Exit(1)
}
fmt.Println("B shared secret with A:\t", base64.StdEncoding.EncodeToString(sharedSecretB))
Complete Code
// A
a, err := GenerateKeyExchange(CURVE25519)
if nil != err {
    fmt.Println(err)
    os.Exit(1)
}
//fmt.Println(a)

fmt.Println("A private key:\t", a)
fmt.Println("A public key:\t", a.PublicKey())

// end A

// B
b, err := GenerateKeyExchange(CURVE25519)
if nil != err {
    fmt.Println(err)
    os.Exit(1)
}

fmt.Println("B private key:\t", b)
fmt.Println("B public key:\t", b.PublicKey())

// end B

// generate shared key
sharedSecretA, err := a.SharedSecret(b.PublicKey())
if nil != err {
    fmt.Println(err)
    os.Exit(1)
}
fmt.Println("A shared secret with B:\t", base64.StdEncoding.EncodeToString(sharedSecretA))

sharedSecretB, err := b.SharedSecret(a.PublicKey())
if nil != err {
    fmt.Println(err)
    os.Exit(1)
}
fmt.Println("B shared secret with A:\t", base64.StdEncoding.EncodeToString(sharedSecretB))

// end generate shared key

Documentation

Index

Constants

View Source 
const (

	// Unknown - unknown key type
	Unknown = shared.Unknown

	// ED25519 - generates an ED25519 256 bit key
	ED25519 = shared.ED25519

	// ECDSA256 - generate an ECDSA 256 bit key
	ECDSA256 = shared.ECDSA256

	// ECDSA384 - generate an ECDSA 384 bit key
	ECDSA384 = shared.ECDSA384

	// ECDSA521 - generate an ECDSA 512 bit key
	ECDSA521 = shared.ECDSA521

	// RSA2048 - generate an RSA 2048 bit key
	RSA2048 = shared.RSA2048

	// RSA4096 - generate an RSA 4096 bit key
	RSA4096 = shared.RSA4096

	// RSA4096 - generate an RSA 4096 bit key
	RSA8192 = shared.RSA8192
)
View Source 
const (
	// CURVE25519 - generates a Curve25519 key exchange
	CURVE25519 = shared.CURVE25519

	// ECDH256 - generates a EC Diffie-Hellman 256-bit key exchange
	ECDH256 = shared.ECDH256

	// ECDH384 - generates a EC Diffie-Hellman 384-bit key exchange
	ECDH384 = shared.ECDH384

	// ECDH521 - generates a EC Diffie-Hellman 521-bit key exchange
	ECDH521 = shared.ECDH521
)

Variables

This section is empty.

Functions

func GenerateKey 

func GenerateKey(kt shared.KeyType) (k shared.Key, err error)

GenerateKey - generates a new key

func GenerateKeyExchange 

func GenerateKeyExchange(kxt shared.KeyXType) (kx shared.KeyExchange, err error)

GenerateKeyExchange - generates a new key exchange public/private

func GetKeyType added in v2.0.6 

func GetKeyType(ktyName string) (kty shared.KeyType)

GetKeyType - returns proper key type given its name

func GetKeyXType added in v2.0.6 

func GetKeyXType(kxtyName string) (kxty shared.KeyXType)

GetKeyXType - returns proper key exchange type given its name

Types

type Key added in v2.0.5 

type Key = shared.Key // create an alias so users don't need to understand the layout of the library to use this type

Key - alias of `shared.Key`

func NewFromRawKey added in v2.0.4 

func NewFromRawKey(rawKey interface{}) (k Key, err error)

NewFromRawKey - returns new instance of key from given raw key

func NewKeyFromBytes 

func NewKeyFromBytes(jwkBytes []byte) (k Key, err error)

NewKeyFromBytes - returns new instance of key from given JWK bytes

func NewKeyFromStr 

func NewKeyFromStr(jwkStr string) (k Key, err error)

NewKeyFromStr - returns new instance of key from a given JWK string

type KeyExchange added in v2.0.5 

type KeyExchange = shared.KeyExchange

Key - alias of `shared.KeyExchange`

func NewKXFromBytes 

func NewKXFromBytes(kxBytes []byte) (kx KeyExchange, err error)

NewKXFromBytes - returns new instance of key exchange from given bytes

func NewKXFromStr 

func NewKXFromStr(kxStr string) (kx KeyExchange, err error)

NewKXFromStr - returns new instance of key exchange from a given string

Source Files

View all Source files

Directories

Path Synopsis
asym
ec
ed
r
kx
crv
ecdhc

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.