nkeys – github.com/nats-io/nkeys Index | Files | Directories

package nkeys

import "github.com/nats-io/nkeys"

Package nkeys is an Ed25519 based public-key signature system that simplifies keys and seeds and performs signing and verification. It also supports encryption via x25519 keys and is compatible with https://pkg.go.dev/golang.org/x/crypto/nacl/box.

Index

Constants 

const (
	ErrInvalidPrefixByte        = nkeysError("nkeys: invalid prefix byte")
	ErrInvalidKey               = nkeysError("nkeys: invalid key")
	ErrInvalidPublicKey         = nkeysError("nkeys: invalid public key")
	ErrInvalidPrivateKey        = nkeysError("nkeys: invalid private key")
	ErrInvalidSeedLen           = nkeysError("nkeys: invalid seed length")
	ErrInvalidSeed              = nkeysError("nkeys: invalid seed")
	ErrInvalidEncoding          = nkeysError("nkeys: invalid encoded key")
	ErrInvalidSignature         = nkeysError("nkeys: signature verification failed")
	ErrCannotSign               = nkeysError("nkeys: can not sign, no private key available")
	ErrPublicKeyOnly            = nkeysError("nkeys: no seed or private key available")
	ErrIncompatibleKey          = nkeysError("nkeys: incompatible key")
	ErrInvalidChecksum          = nkeysError("nkeys: invalid checksum")
	ErrNoSeedFound              = nkeysError("nkeys: no nkey seed found")
	ErrInvalidNkeySeed          = nkeysError("nkeys: doesn't contain a seed nkey")
	ErrInvalidUserSeed          = nkeysError("nkeys: doesn't contain an user seed nkey")
	ErrInvalidRecipient         = nkeysError("nkeys: not a valid recipient public curve key")
	ErrInvalidSender            = nkeysError("nkeys: not a valid sender public curve key")
	ErrInvalidCurveKey          = nkeysError("nkeys: not a valid curve key")
	ErrInvalidCurveSeed         = nkeysError("nkeys: not a valid curve seed")
	ErrInvalidEncrypted         = nkeysError("nkeys: encrypted input is not valid")
	ErrInvalidEncVersion        = nkeysError("nkeys: encrypted input wrong version")
	ErrCouldNotDecrypt          = nkeysError("nkeys: could not decrypt input")
	ErrInvalidCurveKeyOperation = nkeysError("nkeys: curve key is not valid for sign/verify")
	ErrInvalidNKeyOperation     = nkeysError("nkeys: only curve key can seal/open")
	ErrCannotOpen               = nkeysError("nkeys: cannot open no private curve key available")
	ErrCannotSeal               = nkeysError("nkeys: cannot seal no private curve key available")
)

Errors 

const Version = "0.4.7"

Version is our current version 

const XKeyVersionV1 = "xkv1"

Only version for now, but could add in X3DH in the future, etc.

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. `src` must be 32 bytes long (ed25519.SeedSize).

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 IsValidPublicCurveKey 

func IsValidPublicCurveKey(src string) bool

IsValidPublicCurveKey will decode and verify the string is a valid encoded Public Curve 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.

Types

type KeyPair 

type KeyPair interface {
	Seed() ([]byte, error)
	PublicKey() (string, error)
	PrivateKey() ([]byte, error)
	// Sign is only supported on Non CurveKeyPairs
	Sign(input []byte) ([]byte, error)
	// Verify is only supported on Non CurveKeyPairs
	Verify(input []byte, sig []byte) error
	Wipe()
	// Seal is only supported on CurveKeyPair
	Seal(input []byte, recipient string) ([]byte, error)
	// SealWithRand is only supported on CurveKeyPair
	SealWithRand(input []byte, recipient string, rr io.Reader) ([]byte, error)
	// Open is only supported on CurveKey
	Open(input []byte, sender string) ([]byte, error)
}

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 CreateCurveKeys 

func CreateCurveKeys() (KeyPair, error)

CreateCurveKeys will create a Curve typed KeyPair.

func CreateCurveKeysWithRand 

func CreateCurveKeysWithRand(rr io.Reader) (KeyPair, error)

CreateCurveKeysWithRand will create a Curve typed KeyPair with specified rand source.

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.

func CreatePairWithRand 

func CreatePairWithRand(prefix PrefixByte, rr io.Reader) (KeyPair, error)

CreatePair will create a KeyPair based on the rand reader 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 FromCurveSeed 

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

Will create a curve key pair from seed.

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...'

	// PrefixByteCurve is the version byte used for encoded CurveKeys (X25519)
	PrefixByteCurve PrefixByte = 23 << 3 // Base32-encodes to 'X...'

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

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

Source Files

crc16.go creds_utils.go errors.go keypair.go nkeys.go public.go strkey.go xkeys.go

Directories

PathSynopsis
nk
Version
v0.4.11 (latest)
Published
Apr 16, 2025
Platform
js/wasm
Imports
10 packages
Last checked
now –

Tools for package owners.