nkeys

README

NKEYS

A public-key signature system based on Secp256k1 for the NATS ecosystem.

About

The NATS ecosystem will be moving to Secp256k1 keys for identity, authentication and authorization for entities such as Accounts, Users, Servers and Clusters.

TODO: update this section about Secp256k1

Installation

Use the go command:

$ go get github.com/dongnguyenvt/nkeys

nk - Command Line Utility

Located under the nk directory.

Basic API Usage

// Create a new User KeyPair
user, _ := nkeys.CreateUser()

// Sign some data with a full key pair user.
data := []byte("Hello World")
sig, _ := user.Sign(data)

// Verify the signature.
err = user.Verify(data, sig)

// Access the seed, the only thing that needs to be stored and kept safe.
// seed = "SUAKYRHVIOREXV7EUZTBHUHL7NUMHPMAS7QMDU3GTIUWEI5LDNOXD43IZY"
seed, _ := user.Seed()

// Access the public key which can be shared.
// publicKey = "UD466L6EBCM3YY5HEGHJANNTN4LSKTSUXTH7RILHCKEQMQHTBNLHJJXT"
publicKey, _ := user.PublicKey()

// Create a full User who can sign and verify from a private seed.
user, _ = nkeys.FromSeed(seed)

// Create a User who can only verify signatures via a public key.
user, _ = nkeys.FromPublicKey(publicKey)

// Create a User KeyPair with our own random data.
var rawSeed [40]byte
_, err := io.ReadFull(rand.Reader, rawSeed[:])  // Or some other random source.
user2, _ := nkeys.FromRawSeed(PrefixByteUser, rawSeed)

License

Unless otherwise noted, the NATS source files are distributed under the Apache Version 2.0 license found in the LICENSE file.

Documentation

Overview

Package nkeys is an Ed25519 based public-key signature system that simplifies keys and seeds and performs signing and verification.

Index

• Constants
• Variables
• func CompatibleKeyPair(kp KeyPair, expected ...PrefixByte) error
• func Decode(expectedPrefix PrefixByte, src []byte) ([]byte, error)
• func Encode(prefix PrefixByte, src []byte) ([]byte, error)
• func EncodeSeed(public PrefixByte, src []byte) ([]byte, error)
• func GenerateKey(raw []byte) (PublicKey, PrivateKey, error)
• func IsValidEncoding(src []byte) bool
• func IsValidPublicAccountKey(src string) bool
• func IsValidPublicClusterKey(src string) bool
• func IsValidPublicKey(src string) bool
• func IsValidPublicOperatorKey(src string) bool
• func IsValidPublicServerKey(src string) bool
• func IsValidPublicUserKey(src string) bool
• func ParseDecoratedJWT(contents []byte) (string, error)
• func Sign(priv PrivateKey, input []byte) ([]byte, error)
• func Verify(pub PublicKey, message, sig []byte) bool
• type KeyPair
  • func CreateAccount() (KeyPair, error)
  • func CreateCluster() (KeyPair, error)
  • func CreateOperator() (KeyPair, error)
  • func CreatePair(prefix PrefixByte) (KeyPair, error)
  • func CreateServer() (KeyPair, error)
  • func CreateUser() (KeyPair, error)
  • func FromPublicKey(public string) (KeyPair, error)
  • func FromRawSeed(prefix PrefixByte, rawSeed []byte) (KeyPair, error)
  • func FromSeed(seed []byte) (KeyPair, error)
  • func ParseDecoratedNKey(contents []byte) (KeyPair, error)
  • func ParseDecoratedUserNKey(contents []byte) (KeyPair, error)
• type PrefixByte
  • func DecodeSeed(src []byte) (PrefixByte, []byte, error)
  • func Prefix(src string) PrefixByte
  • func (p PrefixByte) String() string
• type PrivateKey
• type PublicKey

Constants

const SignatureSize = crypto.SignatureLength

const Version = "0.3.0"

Version is our current version

Variables

var (
	ErrInvalidPrefixByte = errors.New("nkeys: invalid prefix byte")
	ErrInvalidKey        = errors.New("nkeys: invalid key")
	ErrInvalidPublicKey  = errors.New("nkeys: invalid public key")
	ErrInvalidSeedLen    = errors.New("nkeys: invalid seed length")
	ErrInvalidSeed       = errors.New("nkeys: invalid seed")
	ErrInvalidEncoding   = errors.New("nkeys: invalid encoded key")
	ErrInvalidSignature  = errors.New("nkeys: signature verification failed")
	ErrCannotSign        = errors.New("nkeys: can not sign, no private key available")
	ErrPublicKeyOnly     = errors.New("nkeys: no seed or private key available")
	ErrIncompatibleKey   = errors.New("nkeys: incompatible key")
)

Errors

var ErrInvalidChecksum = errors.New("nkeys: invalid checksum")

ErrInvalidChecksum indicates a failed verification.

var (
	SeedSize = curve.Params().BitSize/8 + 8
)

Functions

func CompatibleKeyPair

func CompatibleKeyPair(kp KeyPair, expected ...PrefixByte) error

CompatibleKeyPair returns an error if the KeyPair doesn't match expected PrefixByte(s)

func Decode

func Decode(expectedPrefix PrefixByte, src []byte) ([]byte, error)

Decode will decode the base32 string and check crc16 and enforce the prefix is what is expected.

func Encode

func Encode(prefix PrefixByte, src []byte) ([]byte, error)

Encode will encode a raw key or seed with the prefix and crc16 and then base32 encoded.

func EncodeSeed

func EncodeSeed(public PrefixByte, src []byte) ([]byte, error)

EncodeSeed will encode a raw key with the prefix and then seed prefix and crc16 and then base32 encoded.

func GenerateKey

func GenerateKey(raw []byte) (PublicKey, PrivateKey, error)

func IsValidEncoding

func IsValidEncoding(src []byte) bool

IsValidEncoding will tell you if the encoding is a valid key.

func IsValidPublicAccountKey

func IsValidPublicAccountKey(src string) bool

IsValidPublicAccountKey will decode and verify the string is a valid encoded Public Account Key.

func IsValidPublicClusterKey

func IsValidPublicClusterKey(src string) bool

IsValidPublicClusterKey will decode and verify the string is a valid encoded Public Cluster Key.

func IsValidPublicKey

func IsValidPublicKey(src string) bool

IsValidPublicKey will decode and verify that the string is a valid encoded public key.

func IsValidPublicOperatorKey

func IsValidPublicOperatorKey(src string) bool

IsValidPublicOperatorKey will decode and verify the string is a valid encoded Public Operator Key.

func IsValidPublicServerKey

func IsValidPublicServerKey(src string) bool

IsValidPublicServerKey will decode and verify the string is a valid encoded Public Server Key.

func IsValidPublicUserKey

func IsValidPublicUserKey(src string) bool

IsValidPublicUserKey will decode and verify the string is a valid encoded Public User Key.

func ParseDecoratedJWT

func ParseDecoratedJWT(contents []byte) (string, error)

ParseDecoratedJWT takes a creds file and returns the JWT portion.

func Sign

func Sign(priv PrivateKey, input []byte) ([]byte, error)

func Verify

func Verify(pub PublicKey, message, sig []byte) bool

Types

type KeyPair

type KeyPair interface {
	Seed() ([]byte, error)
	PublicKey() (string, error)
	PrivateKey() ([]byte, error)
	Sign(input []byte) ([]byte, error)
	Verify(input []byte, sig []byte) error
	Wipe()
}

KeyPair provides the central interface to nkeys.

func CreateAccount

func CreateAccount() (KeyPair, error)

CreateAccount will create an Account typed KeyPair.

func CreateCluster

func CreateCluster() (KeyPair, error)

CreateCluster will create a Cluster typed KeyPair.

func CreateOperator

func CreateOperator() (KeyPair, error)

CreateOperator will create an Operator typed KeyPair.

func CreatePair

func CreatePair(prefix PrefixByte) (KeyPair, error)

CreatePair will create a KeyPair based on the rand entropy and a type/prefix byte. rand can be nil.

func CreateServer

func CreateServer() (KeyPair, error)

CreateServer will create a Server typed KeyPair.

func CreateUser

func CreateUser() (KeyPair, error)

CreateUser will create a User typed KeyPair.

func FromPublicKey

func FromPublicKey(public string) (KeyPair, error)

FromPublicKey will create a KeyPair capable of verifying signatures.

func FromRawSeed

func FromRawSeed(prefix PrefixByte, rawSeed []byte) (KeyPair, error)

FromRawSeed will create a KeyPair from the raw 32 byte seed for a given type.

func FromSeed

func FromSeed(seed []byte) (KeyPair, error)

FromSeed will create a KeyPair capable of signing and verifying signatures.

func ParseDecoratedNKey

func ParseDecoratedNKey(contents []byte) (KeyPair, error)

ParseDecoratedNKey takes a creds file, finds the NKey portion and creates a key pair from it.

func ParseDecoratedUserNKey

func ParseDecoratedUserNKey(contents []byte) (KeyPair, error)

ParseDecoratedUserNKey takes a creds file, finds the NKey portion and creates a key pair from it. Similar to ParseDecoratedNKey but fails for non-user keys.

type PrefixByte

type PrefixByte byte

PrefixByte is a lead byte representing the type.

const (
	// PrefixByteSeed is the version byte used for encoded NATS Seeds
	PrefixByteSeed PrefixByte = 18 << 3 // Base32-encodes to 'S...'

	// PrefixBytePrivate is the version byte used for encoded NATS Private keys
	PrefixBytePrivate PrefixByte = 15 << 3 // Base32-encodes to 'P...'

	// PrefixByteServer is the version byte used for encoded NATS Servers
	PrefixByteServer PrefixByte = 13 << 3 // Base32-encodes to 'N...'

	// PrefixByteCluster is the version byte used for encoded NATS Clusters
	PrefixByteCluster PrefixByte = 2 << 3 // Base32-encodes to 'C...'

	// PrefixByteOperator is the version byte used for encoded NATS Operators
	PrefixByteOperator PrefixByte = 14 << 3 // Base32-encodes to 'O...'

	// PrefixByteAccount is the version byte used for encoded NATS Accounts
	PrefixByteAccount PrefixByte = 0 // Base32-encodes to 'A...'

	// PrefixByteUser is the version byte used for encoded NATS Users
	PrefixByteUser PrefixByte = 20 << 3 // Base32-encodes to 'U...'

	// PrefixByteUnknown is for unknown prefixes.
	PrefixByteUnknown PrefixByte = 23 << 3 // Base32-encodes to 'X...'
)

func DecodeSeed

func DecodeSeed(src []byte) (PrefixByte, []byte, error)

DecodeSeed will decode the base32 string and check crc16 and enforce the prefix is a seed and the subsequent type is a valid type.

func Prefix

func Prefix(src string) PrefixByte

Prefix returns PrefixBytes of its input

func (PrefixByte) String

func (p PrefixByte) String() string

type PrivateKey

type PrivateKey []byte

type PublicKey

type PublicKey []byte