keyagr

README

Key agreement

import "github.com/a-novel-kit/jwt-core/jwe/keyagr"

Handlers for the key agreement of JSON Web Encryption.

Derive

Derive takes a private asymmetric key and a public asymmetric key, and returns the derived shared secret.

sharedSecret, err := keyagr.Derive(privateKey, publicKey, out, apu, apv)

Out is the algorithm the derived key is expected to be used with. It can be one of the following:

Algorithm	Method
AES-CBC-128	keyarg.AlgA128CBC
AES-CBC-192	keyarg.AlgA192CBC
AES-CBC-256	keyarg.AlgA256CBC
AES-GCM-128	keyarg.AlgA128GCM
AES-GCM-192	keyarg.AlgA192GCM
AES-GCM-256	keyarg.AlgA256GCM
A128KW	keyarg.AlgA128KW
A192KW	keyarg.AlgA192KW
A256KW	keyarg.AlgA256KW

Documentation

Index

• Variables
• func ComputeECSharedSecret(ownPrivKey *ecdsa.PrivateKey, sharedPubKey *ecdsa.PublicKey) ([]byte, error)
• func ComputeSharedEDSecret(ownPrivKey *ecdh.PrivateKey, sharedPubKey *ecdh.PublicKey) ([]byte, error)
• func Derive(z []byte, out Alg, apu, apv []byte) ([]byte, error)
• func DeriveECDHED(ownPrivKey *ecdh.PrivateKey, sharedPubKey *ecdh.PublicKey, out Alg, ...) ([]byte, error)
• func DeriveECDHES(ownPrivKey *ecdsa.PrivateKey, sharedPubKey *ecdsa.PublicKey, out Alg, ...) ([]byte, error)
• type Alg
• type AlgType

Variables

var (
	// AlgA128CBC is the algorithm used for direct key agreement with AES-CBC-128.
	AlgA128CBC = Alg{
		ID:   string(jwa.A128CBC),
		Size: int(jwkgen.AESKeySize256),
		Type: AlgTypeDirect,
	}
	// AlgA192CBC is the algorithm used for direct key agreement with AES-CBC-192.
	AlgA192CBC = Alg{
		ID:   string(jwa.A192CBC),
		Size: int(jwkgen.AESKeySize384),
		Type: AlgTypeDirect,
	}
	// AlgA256CBC is the algorithm used for direct key agreement with AES-CBC-256.
	AlgA256CBC = Alg{
		ID:   string(jwa.A256CBC),
		Size: int(jwkgen.AESKeySize512),
		Type: AlgTypeDirect,
	}

	// AlgA128GCM is the algorithm used for direct key agreement with AES-GCM-128.
	AlgA128GCM = Alg{
		ID:   string(jwa.A128GCM),
		Size: int(jwkgen.AESKeySize128),
		Type: AlgTypeDirect,
	}
	// AlgA192GCM is the algorithm used for direct key agreement with AES-GCM-192.
	AlgA192GCM = Alg{
		ID:   string(jwa.A192GCM),
		Size: int(jwkgen.AESKeySize192),
		Type: AlgTypeDirect,
	}
	// AlgA256GCM is the algorithm used for direct key agreement with AES-GCM-256.
	AlgA256GCM = Alg{
		ID:   string(jwa.A256GCM),
		Size: int(jwkgen.AESKeySize256),
		Type: AlgTypeDirect,
	}
)

Direct Key Agreement mode.

var (
	// AlgA128KW is the algorithm used for key agreement with key wrapping with ECDH-ES+A128KW.
	AlgA128KW = Alg{
		ID:   string(jwa.A128KW),
		Size: int(jwkgen.AESKeySize128),
		Type: AlgTypeKeyWrap,
	}
	// AlgA192KW is the algorithm used for key agreement with key wrapping with ECDH-ES+A192KW.
	AlgA192KW = Alg{
		ID:   string(jwa.A192KW),
		Size: int(jwkgen.AESKeySize192),
		Type: AlgTypeKeyWrap,
	}
	// AlgA256KW is the algorithm used for key agreement with key wrapping with ECDH-ES+A256KW.
	AlgA256KW = Alg{
		ID:   string(jwa.A256KW),
		Size: int(jwkgen.AESKeySize256),
		Type: AlgTypeKeyWrap,
	}
)

KeyWrap Key Agreement mode.

var ErrKeyMismatch = errors.New("key mismatch")

Functions

func ComputeECSharedSecret

func ComputeECSharedSecret(ownPrivKey *ecdsa.PrivateKey, sharedPubKey *ecdsa.PublicKey) ([]byte, error)

ComputeECSharedSecret computes the shared secret Z between 2 unrelated ECDSA keys.

https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-56Ar2.pdf

A shared secret Z is computed using the domain parameters (q, FR, a, b{, SEED}, G, n, h), the other party’s public key, and one’s own private key. This primitive is used in Section 6 by the Full Unified Model, Ephemeral Unified Model, One-Pass Unified Model, One-Pass DiffieHellman and Static Unified Model schemes. Assume that the party performing the computation is party A, and the other party is party B. Note that party A could be either party U or party V.

Both keys must be on the same curve.

func ComputeSharedEDSecret

func ComputeSharedEDSecret(ownPrivKey *ecdh.PrivateKey, sharedPubKey *ecdh.PublicKey) ([]byte, error)

ComputeSharedEDSecret computes the shared secret between two Ed25519 keys.

https://datatracker.ietf.org/doc/html/rfc8037#section-3.2.1

Apply the appropriate ECDH function to the ephemeral private key (as scalar input) and receiver public key (as u-coordinate input). The output is the Z value.

func Derive

func Derive(z []byte, out Alg, apu, apv []byte) ([]byte, error)

Derive is a generic function to derive a key from a shared secret.

Private key is used to derive the shared secret Z, along with the shared public key.

On the recipient side, it is the private counterpart of the public key shared to the issuer.

On the issuer side, it is an ephemeral key that can be thrown away after the key has been derived (note that the public key counterpart must be saved and shared with the recipient).

Alg is the expected algorithm the output key is intended to be used with. This information can be retrieved from the "alg" header on the recipient side.

It returns the generated CEK, along with the public counterpart of the ephemeral key used to generate it.

The returned public key can (and must) safely be shared with the recipient, so it can derive the same key.

func DeriveECDHED

func DeriveECDHED(
	ownPrivKey *ecdh.PrivateKey, sharedPubKey *ecdh.PublicKey, out Alg, apu, apv []byte,
) ([]byte, error)

DeriveECDHED implements Derive for ECDH-ED.

func DeriveECDHES

func DeriveECDHES(
	ownPrivKey *ecdsa.PrivateKey, sharedPubKey *ecdsa.PublicKey, out Alg, apu, apv []byte,
) ([]byte, error)

DeriveECDHES implements Derive for ECDH-ES.

Types

type Alg

type Alg struct {
	// ID is the algorithm identifier (the "enc" header parameter for direct key agreement, or the "alg" header
	// that should be used for wrapping).
	ID string
	// Size is the expected output size in bytes.
	Size int
	// Type is the type of key agreement algorithm this value should be used with.
	Type AlgType
}

Alg represents the expected output of the key agreement algorithm.

type AlgType

type AlgType int

const (
	// AlgTypeDirect is the direct key agreement mode.
	AlgTypeDirect AlgType = iota
	// AlgTypeKeyWrap is the key agreement with key wrapping mode.
	AlgTypeKeyWrap
)