jose

package module
v0.0.0-...-3c258e1 Latest Latest
Warning

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

 Go to latest Published: Dec 2, 2025 License: MIT Imports: 5 Imported by: 0

README

JOSE

Go implementation of JSON Object Signing and Encryption (JOSE) standards.

Package Description RFC
jwk JSON Web Key RFC 7517
jws JSON Web Signature RFC 7515
jwe JSON Web Encryption RFC 7516

JWK

Parse, create, and serialize cryptographic keys in JWK format.

// Parse a JWK Set (e.g., from /.well-known/jwks.json)
set, err := jwk.ParseSet(jsonData)
verifiers, err := set.Verifiers()
verified, err := jws.Verify(token, verifiers...)

// Create JWK from Go crypto key
privateJWK, err := jwk.FromPrivateKey(ecdsaKey, "key-id")
signer, err := privateJWK.Signer()

Supported key types:

  • EC (P-256, P-384, P-521) for ECDSA
  • RSA for RS*/PS* algorithms
  • OKP (Ed25519) for EdDSA
  • oct for HMAC

JWS

Sign and verify data with digital signatures or MACs.

// Sign
signer, verifier, err := jws.HMAC(crypto.SHA256, "key-id", secret)
msg, err := jws.Sign([]byte("payload"), signer)
token, err := msg.Compact()

// Verify
verified, err := jws.Verify(token, verifier)
fmt.Println(string(verified.Payload))

Supported algorithms:

Algorithm Type Constructor
HS256, HS384, HS512 HMAC jws.HMAC
RS256, RS384, RS512 RSA PKCS#1 v1.5 jws.RSA
PS256, PS384, PS512 RSA-PSS jws.RSAPSS
ES256, ES384, ES512 ECDSA jws.ECDSA
EdDSA Ed25519 jws.EdDSA

JWE

Encrypt and decrypt data with authenticated encryption.

// Encrypt
encrypter, err := jwe.RSAOAEP256(publicKey, jwe.A256GCM, "key-id")
msg, err := jwe.Encrypt([]byte("secret"), encrypter)
token, err := msg.Compact()

// Decrypt
decrypter, err := jwe.RSAOAEP256Decrypter(privateKey, "key-id")
decrypted, err := jwe.Decrypt(token, decrypter)
fmt.Println(string(decrypted.Plaintext))

Key management algorithms:

Algorithm Type Constructor
RSA-OAEP RSA-OAEP with SHA-1 jwe.RSAOAEP
RSA-OAEP-256 RSA-OAEP with SHA-256 jwe.RSAOAEP256
A128KW, A192KW, A256KW AES Key Wrap jwe.A128KW, jwe.A192KW, jwe.A256KW
ECDH-ES ECDH Ephemeral Static jwe.ECDHES
ECDH-ES+A128KW, +A192KW, +A256KW ECDH-ES with AES Key Wrap jwe.ECDHESA128KW, etc.
dir Direct encryption jwe.Direct

Content encryption algorithms:

Algorithm Description
A128GCM, A192GCM, A256GCM AES-GCM
A128CBC-HS256, A192CBC-HS384, A256CBC-HS512 AES-CBC with HMAC

Documentation

Overview

Package jose implements JSON Object Signing and Encryption (JOSE) as defined in RFC 7515 (JWS), RFC 7516 (JWE), and RFC 7517 (JWK).

This package provides the shared primitives used by the subpackages. Most users should import those packages directly:

Signing (JWS)

Use the jws package to create and verify signed tokens: 

signer, verifier, _ := jws.ES256(privateKey, "key-id")
signed, _ := jws.Sign([]byte("payload"), signer)
verified, _ := jws.Verify(signed, verifier)

Encryption (JWE)

Use the jwe package to encrypt and decrypt data: 

encrypter, _ := jwe.RSAOAEP256(publicKey, jwe.A256GCM, "key-id")
msg, _ := jwe.Encrypt([]byte("secret"), encrypter)
token, _ := msg.Compact()

decrypter, _ := jwe.RSAOAEP256Decrypter(privateKey, "key-id")
decrypted, _ := jwe.Decrypt(token, decrypter)

JSON Web Keys (JWK)

Use the jwk package to work with keys in JWK format: 

jwkKey, _ := jwk.FromPrivateKey(privateKey, "key-id")
signer, _ := jwkKey.Signer()
encrypter, _ := jwkKey.JWKPublicKey().Encrypter(jwe.A256GCM)

Base64URL Encoding

JOSE specifications use base64url encoding without padding. The Base64 variable provides the standard encoding used throughout this library.

Index

Constants

View Source 
const (
	HeaderParamAlg     = "alg"
	HeaderParamJKU     = "jku"
	HeaderParamJWK     = "jwk"
	HeaderParamKID     = "kid"
	HeaderParamTYP     = "typ"
	HeaderParamCTY     = "cty"
	HeaderParamCrit    = "crit"
	HeaderParamX5U     = "x5u"
	HeaderParamX5C     = "x5c"
	HeaderParamX5T     = "x5t"
	HeaderParamX5TS256 = "x5t#S256"
)

List of header parameters defined in RFC 7515.

Variables

View Source 
var Base64 = base64.RawURLEncoding

Base64 is the standard base64 encoding for both object encryption and signing.

Functions

This section is empty.

Types

type Binary 

type Binary []byte

Binary represents binary data which JSON representation is a string encoded using Base64.

func (Binary) Bytes 

func (bin Binary) Bytes() []byte

Bytes returns bin as a slice.

func (Binary) MarshalJSON 

func (bin Binary) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

func (Binary) String 

func (bin Binary) String() string

String returns bin as a Base64 encoded string.

func (*Binary) UnmarshalJSON 

func (bin *Binary) UnmarshalJSON(b []byte) error

UnmarshalJSON implements json.Unmarshaler. 

type Header map[string]any

Header represents a JOSE Header object.

func (Header) Alg 

func (h Header) Alg() string

Alg returns the value of the algorithm param.

The returned string is empty if the param doesn't exist or if its value was not valid.

func (Header) CTY 

func (h Header) CTY() string

CTY returns the value of the content type param.

The returned string is empty if the param doesn't exist or if its value was not valid.

func (Header) Clone 

func (h Header) Clone() Header

Clone returns a copy of h.

func (Header) Crit 

func (h Header) Crit() []string

Crit returns the value of the critical param.

The returned slice is empty if the param doesn't exist or if its value was not valid.

func (Header) Del 

func (h Header) Del(param string)

Del removes the given parameter.

func (Header) Encode �� 

func (h Header) Encode() (string, error)

Encode returns the JSON representation of h encoded as Base64-URL string.

func (Header) Get 

func (h Header) Get(param string) any

Get returns the value of the given param.

func (Header) Has 

func (h Header) Has(param string) bool

Has returns true if the given param exists.

func (Header) JKU 

func (h Header) JKU() string

JKU returns the value of the JSON set URL param.

The returned string is empty if the param doesn't exist or if its value was not valid.

func (Header) JWK 

func (h Header) JWK() string

JWK returns the value of the JSON web key param.

The returned string is empty if the param doesn't exist or if its value was not valid.

func (Header) KID 

func (h Header) KID() string

KID returns the value of the key ID param.

The returned string is empty if the param doesn't exist or if its value was not valid.

func (Header) Set 

func (h Header) Set(param string, value any)

Set replaces the value of the given param.

func (Header) TYP 

func (h Header) TYP() string

TYP returns the value of the type param.

The returned string is empty if the param doesn't exist or if its value was not valid.

func (Header) X5C 

func (h Header) X5C() []string

X5C returns the value of the X.509 certificate chain param.

The returned slice is empty if the param doesn't exist or if its value was not valid.

func (Header) X5T 

func (h Header) X5T() string

X5T returns the value of the X.509 certificate SHA-1 thumbprint param.

The returned string is empty if the param doesn't exist or if its value was not valid.

func (Header) X5TS256 

func (h Header) X5TS256() string

X5TS256 returns the value of the X.509 certificate SHA-256 thumbprint param.

The returned string is empty if the param doesn't exist or if its value was not valid.

func (Header) X5U 

func (h Header) X5U() string

X5U returns the value of the X.509 URL param.

The returned string is empty if the param doesn't exist or if its value was not valid.

type NumericDate 

type NumericDate struct {
	Time time.Time
}

NumericDate represents a UNIX epoch timestamp.

func NewNumericDate 

func NewNumericDate(t time.Time) *NumericDate

NewNumericDate returns a new timestamp from the given time.

func (*NumericDate) Epoch 

func (d *NumericDate) Epoch() int64

Epoch returns the Unix timestamp value.

func (*NumericDate) MarshalJSON 

func (d *NumericDate) MarshalJSON() ([]byte, error)

MarshalJSON encodes the time value into a UNIX timestamp.

func (*NumericDate) UnmarshalJSON 

func (d *NumericDate) UnmarshalJSON(b []byte) error

UnmarshalJSON decodes a UNIX timestamp from a JSON number.

Source Files

View all Source files

Directories

Path Synopsis
Package jwe implements JSON Web Encryption (JWE) as defined in [RFC 7516].
 Package jwe implements JSON Web Encryption (JWE) as defined in [RFC 7516].
Package jwk implements JSON Web Key (JWK) as defined in [RFC 7517].
 Package jwk implements JSON Web Key (JWK) as defined in [RFC 7517].
Package jws implements JSON Web Signature (JWS) as defined in [RFC 7515].
 Package jws implements JSON Web Signature (JWS) as defined in [RFC 7515].
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.