jwkgen

README

Keygen

import "github.com/a-novel-kit/jwt-core/jwk/gen"

Generate keys compatible with the JWK standards.

• HMAC
• RSA
• ECDSA
• Elliptic-Curve Diffie-Hellman
  • ED25519
  • X25519
• AES
  • Initialization Vector
  • Key set

HMAC

HMAC keys are symmetric keys, consisting of random bytes. They require a key size to be generated.

key, err := jwkgen.GenerateHMACKey(keySize)

You can use the recommended key sizes for your algorithm:

Algorithm	Key Size
HS256	jwkgen.H256KeySize
HS384	jwkgen.H384KeySize
HS512	jwkgen.H512KeySize

RSA

RSA keys are asymmetric keys, consisting of a public and a private key. They require a key size to be generated.

// You can extract the public key from its private counterpart.
//  pubKey = privateKey.PublicKey
privateKey, err := jwkgen.GenerateRSAKey(keySize)

You can use the recommended key sizes for your algorithm:

Algorithm	Key Size
RS256 PS256	jwkgen.RS256KeySize
RS384 PS384	jwkgen.RS384KeySize
RS512 PS512	jwkgen.RS512KeySize

ECDSA

ECDSA keys are asymmetric keys, based on Elliptic Curves. They require a curve to be generated.

// You can extract the public key from its private counterpart.
//  pubKey = privateKey.PublicKey
privateKey, err := jwkgen.GenerateECDSAKey(curve)

The following curves are supported:

Curve	Method
P256	elliptic.P256()
P384	elliptic.P384()
P521	elliptic.P521()

Elliptic-Curve Diffie-Hellman

This package provides handlers for the X25519 curve, introduced in RFC 7748.

Those algorithms use separate keys for signing and encryption. Both MUST not be interchanged.

ED25519

ED25519 keys are asymmetric keys, based on the Ed25519 curve.

privKey, pubKey, err := jwkgen.ED25519()

X25519

X25519 keys are asymmetric keys, based on the X25519 curve.

privKey, pubKey, err := jwkgen.X25519()

AES

AES are symmetric keys used for content encryption. They require a key size to be generated.

key, err := jwkgen.AES(keySize)

You can use the recommended key sizes for your algorithm:

Algorithm	Key Size
128 bit	jwkgen.AESKeySize128
192 bit	jwkgen.AESKeySize192
256 bit	jwkgen.AESKeySize256
384 bit	jwkgen.AESKeySize384
512 bit	jwkgen.AESKeySize512

Initialization Vector

Content encryption usually requires an additional initialization vector (IV).

iv, err := jwkgen.IV(keySize)

You can use the recommended key sizes for your algorithm:

Algorithm	Key Size
96 bit	jwkgen.IVSize96
128 bit	jwkgen.IVSize128

Key set

Since AES encryption key and initialization vector are often used together, you can generate them at once.

key, iv, err := jwkgen.AESKeySet(preset)

The following presets are available, for recommended algorithms:

Algorithm	Preset
A128CBC-HS256	jwkgen.A128CBCKeyPreset
A192CBC-HS384	jwkgen.A192CBCKeyPreset
A256CBC-HS512	jwkgen.A256CBCKeyPreset
A128GCM	jwkgen.A128GCMKeyPreset
A192GCM	jwkgen.A192GCMKeyPreset
A256GCM	jwkgen.A256GCMKeyPreset

Documentation

Index

• Constants
• Variables
• func AES(keySize AESKeySize) ([]byte, error)
• func AESKeySet(preset AESKeyPreset) (*jwkcore.AESKeySet, error)
• func EC(curve elliptic.Curve) (*ecdsa.PrivateKey, error)
• func ED25519() (ed25519.PrivateKey, ed25519.PublicKey, error)
• func HMAC(size int) ([]byte, error)
• func IV(ivSize IVSize) ([]byte, error)
• func RSA(size int) (*rsa.PrivateKey, error)
• func X25519() (*ecdh.PrivateKey, error)
• type AESKeyPreset
• type AESKeySize
• type IVSize

Constants

const (
	// H256KeySize is the recommended key size for HMAC 256 keys.
	//
	// If the key is more than 64 bytes long, it is hashed (using SHA-384) to derive a 32-byte key.
	//
	// https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.hmacsha256.-ctor?view=net-9.0
	H256KeySize = 64
	// H384KeySize is the recommended key size for HMAC 384 keys.
	//
	// If the key is more than 128 bytes long, it is hashed (using SHA-384) to derive a 48-byte key.
	//
	// https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.hmacsha384.-ctor?view=net-9.0
	H384KeySize = 128
	// H512KeySize is the recommended key size for HMAC 512 keys.
	//
	// If the key is more than 128 bytes long, it is hashed (using SHA-384) to derive a 64-byte key.
	//
	// https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.hmacsha512.-ctor?view=net-9.0
	H512KeySize = 128
)

const (
	// RS256KeySize is the recommended key size for RSA 256 keys.
	//
	// The signature size (in bytes, before re-encoding as text) is the key size (in bit), divided by 8 and rounded up
	// to the next integer.
	//
	// ⌈2048/8⌉=256 bytes.
	//
	// https://crypto.stackexchange.com/a/95882
	RS256KeySize = 2048
	// RS384KeySize is the recommended key size for RSA 384 keys.
	//
	// The signature size (in bytes, before re-encoding as text) is the key size (in bit), divided by 8 and rounded up
	// to the next integer.
	//
	// ⌈3072/8⌉=384 bytes.
	//
	// https://crypto.stackexchange.com/a/95882
	RS384KeySize = 3072
	// RS512KeySize is the recommended key size for RSA 512 keys.
	//
	// The signature size (in bytes, before re-encoding as text) is the key size (in bit), divided by 8 and rounded up
	// to the next integer.
	//
	// ⌈4096/8⌉=512 bytes.
	//
	// https://crypto.stackexchange.com/a/95882
	RS512KeySize = 4096
)

Variables

var (
	A128GCMKeyPreset = AESKeyPreset{
		KeySize: AESKeySize128,
		IVSize:  IVSize96,
	}
	A192GCMKeyPreset = AESKeyPreset{
		KeySize: AESKeySize192,
		IVSize:  IVSize96,
	}
	A256GCMKeyPreset = AESKeyPreset{
		KeySize: AESKeySize256,
		IVSize:  IVSize96,
	}

	A128CBCKeyPreset = AESKeyPreset{
		KeySize: AESKeySize256,
		IVSize:  IVSize128,
	}
	A192CBCKeyPreset = AESKeyPreset{
		KeySize: AESKeySize384,
		IVSize:  IVSize128,
	}
	A256CBCKeyPreset = AESKeyPreset{
		KeySize: AESKeySize512,
		IVSize:  IVSize128,
	}
)

Functions

func AES

func AES(keySize AESKeySize) ([]byte, error)

AES creates a new random key that can be used for symmetric encryption.

func AESKeySet

func AESKeySet(preset AESKeyPreset) (*jwkcore.AESKeySet, error)

AESKeySet creates a new random key and IV that can be used for symmetric encryption.

func EC

func EC(curve elliptic.Curve) (*ecdsa.PrivateKey, error)

EC generates a new ECDSA private key of the given curve.

The curve must be one of the following: - elliptic.P256() - elliptic.P384() - elliptic.P521()

func ED25519

func ED25519() (ed25519.PrivateKey, ed25519.PublicKey, error)

ED25519 generates a new EdDSA key pair.

func HMAC

func HMAC(size int) ([]byte, error)

HMAC generates a cryptographically secure random byte slice of the given size. The generated key can be used to sign a token using HMAC.

You can use the recommended default constants as the size parameter.

• H256KeySize
• H384KeySize
• H512KeySize

func IV

func IV(ivSize IVSize) ([]byte, error)

IV creates a new random IV that can be used for symmetric encryption.

func RSA

func RSA(size int) (*rsa.PrivateKey, error)

RSA generates a new RSA private key of the given size. The generated key can be used to sign a token using RSA.

You can use the recommended default constants as the size parameter.

• RS256KeySize
• RS384KeySize
• RS512KeySize

func X25519

func X25519() (*ecdh.PrivateKey, error)

X25519 generates a new X25519 key pair.

Types

type AESKeyPreset

type AESKeyPreset struct {
	// KeySize is the size of the content encryption key to generate.
	KeySize AESKeySize
	// IVSize is the size of the initialization vector to generate.
	IVSize IVSize
}

AESKeyPreset is a set of parameters that can be used to generate a full AESKeySet.

type AESKeySize

type AESKeySize int

const (
	AESKeySize128 AESKeySize = 16
	AESKeySize192 AESKeySize = 24
	AESKeySize256 AESKeySize = 32
	AESKeySize384 AESKeySize = 48
	AESKeySize512 AESKeySize = 64
)

type IVSize

type IVSize int

const (
	IVSize96  IVSize = 12
	IVSize128 IVSize = 16
)