jws

package
v0.0.0-...-5e2031a Latest Latest
Warning

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

 Go to latest Published: Aug 7, 2025 License: Apache-2.0 Imports: 15 Imported by: 0

Documentation

Overview

Package jws contains implementations of the JSON Web Signatures (jws) defined in RFC 7517 (https://datatracker.ietf.org/doc/html/rfc7517) as well as parts from JSON Web Algorithms (jwa) as defined in RFC 7518 (https://www.rfc-editor.org/rfc/rfc7518.html)

Example 
package main

import (
	"fmt"

	"github.com/halimath/jose/jws"
)

func main() {
	signatureMethod := jws.HS256([]byte("secret"))

	sig, err := jws.Sign(signatureMethod, []byte("hello, world"), jws.Header{})
	if err != nil {
		panic(err)
	}

	compact := sig.Compact()

	fmt.Println(compact)

	sig2, err := jws.ParseCompact(compact)
	if err != nil {
		panic(err)
	}

	fmt.Println(string(sig2.Payload()))

}

Output:

eyJhbGciOiJIUzI1NiJ9.aGVsbG8sIHdvcmxk.4BeqMvZFJ1IIIpDSQhXK05lFaJ5k9G39y7CNs8xdfjI
hello, world

Index

Examples

Constants

This section is empty.

Variables

View Source 
var (
	// ErrInvalidCompactJWS is returned when a given string is not a valid JWS in compact serialized form.
	ErrInvalidCompactJWS = errors.New("invalid compact JWS")

	ErrInvalidHeader = errors.New("invalid header")
)
View Source 
var (
	// ErrInvalidSignature is returned from VerifySignature when the signature is not considered valid.
	ErrInvalidSignature = errors.New("invalid signature")
)

Functions

This section is empty.

Types

type HMACSignerVerifier 

type HMACSignerVerifier struct {
	// contains filtered or unexported fields
}

HMACSignerVerifier implements a signature method using a HMAC with a pre-shared secret.

func (*HMACSignerVerifier) Alg 

func (h *HMACSignerVerifier) Alg() SignatureAlgorithm

func (*HMACSignerVerifier) Sign 

func (h *HMACSignerVerifier) Sign(data []byte) ([]byte, error)
type Header struct {
	Algorithm SignatureAlgorithm `json:"alg"`
	Type      string             `json:"typ,omitempty"`
}

Header defines the structure representing a JWS JOSE header as defined in RFC7515 section 4 (https://datatracker.ietf.org/doc/html/rfc7515#section-4). This implementation has no support for private header parameters.

func DecodeHeader 

func DecodeHeader(encoded string) (*Header, error)

func (*Header) Encode 

func (h *Header) Encode() string

type JWS 

type JWS struct {
	// contains filtered or unexported fields
}

JWS implements a JSON Web Signature datastructure. The fields of this struct represent the different components of a JWS in multiple ways. Once created a JWS is immutable. A JWS may only be created through functions exposed from this package, i.e. 

func Sign(signatureMethod SignatureMethod, payload []byte, header Header) JWS
func ParseCompact(compact string) (*JWS, error)

func ParseCompact 

func ParseCompact(compact string) (*JWS, error)

ParseCompact parses the given compact representation into a JWS datastructure and returns it. It performs only a syntactically validation of base64 URL encoded data as well as parsing the JOSE header JSON. The signature ist NOT verified. Use Verify to perform the verification.

func Sign 

func Sign(signer Signer, payload []byte, header Header) (*JWS, error)

Sign signs the given payload and header with the given signature method. It returns a JWS value containing the raw and encoded parts as well as the signature.

func (*JWS) Compact 

func (j *JWS) Compact() string

Compact returns the JWS in compact serialization as specified in RFC 7515 section 7.1 (https://datatracker.ietf.org/doc/html/rfc7515#section-7.1)

func (*JWS) Header 

func (j *JWS) Header() Header

Header returns a copy of j's header.

func (*JWS) HeaderBytes 

func (j *JWS) HeaderBytes() []byte

HeaderBytes returns the decoded but unparsed bytes of the header.

func (*JWS) Payload 

func (j *JWS) Payload() []byte

Payload returns a deep copy of j's payload.

func (*JWS) SignatureBytes 

func (j *JWS) SignatureBytes() []byte

SignatureBytes returns the decoded signature bytes of j.

func (*JWS) VerifySignature 

func (j *JWS) VerifySignature(verifier Verifier) error

Verify verifies that the signature t carries has zero length.

type SignatureAlgorithm 

type SignatureAlgorithm string

SignatureAlgorithm defines the type used to name algorithms creating digital signature including MACs. 

const (
	// The none signature algorithm according to RFC 7618, section 3.6
	// (https://www.rfc-editor.org/rfc/rfc7518.html#section-3.6)
	ALG_NONE SignatureAlgorithm = "none"

	// HMAC using SHA2 w/ 256bit
	ALG_HS256 SignatureAlgorithm = "HS256"

	// HMAC using SHA2 w/ 384bit
	ALG_HS384 SignatureAlgorithm = "HS384"

	// HMAC using SHA2 w/ 512bit
	ALG_HS512 SignatureAlgorithm = "HS512"

	// ECDSA using P-256 and SHA-256
	ALG_ES256 SignatureAlgorithm = "ES256"

	// ECDSA using P-384 and SHA-384
	ALG_ES384 SignatureAlgorithm = "ES384"

	// ECDSA using P-521 and SHA-512
	ALG_ES512 SignatureAlgorithm = "ES512"

	// RSASSA-PKCS1-v1_5 using SHA-256
	ALG_RS256 SignatureAlgorithm = "RS256"

	// RSASSA-PKCS1-v1_5 using SHA-384
	ALG_RS384 SignatureAlgorithm = "RS384"

	// RSASSA-PKCS1-v1_5 using SHA-512
	ALG_RS512 SignatureAlgorithm = "RS512"
)

func (SignatureAlgorithm) UsesEllipticCurves 

func (s SignatureAlgorithm) UsesEllipticCurves() bool

UsesEllipticCurves returns true if s utilizes elliptic curve cryptography.

func (SignatureAlgorithm) UsesSymmetricSecret 

func (s SignatureAlgorithm) UsesSymmetricSecret() bool

UsesSymmetricKey returns true, if s uses the same secret for signing and verification.

type Signer 

type Signer interface {
	// Alg returns the name of the signature algorithm as defined in
	// RFC 7518 section 3.1
	// (https://www.rfc-editor.org/rfc/rfc7518.html#section-3.1)
	Alg() SignatureAlgorithm

	// Sign calculates the the signature or MAC for the given
	// byte slice and returns the signature bytes.
	Sign(data []byte) ([]byte, error)
}

Signer defines the interface for types implementing a given signature method for signing byte slices.

func ES256Signer 

func ES256Signer(privateKey *ecdsa.PrivateKey) (Signer, error)

ES256Signer creates a Signer providing ECDSA using P-256 and SHA-256 signatures using the given private key which must use ellipctic.P256() as the underlying curve.

func ES384Signer 

func ES384Signer(privateKey *ecdsa.PrivateKey) (Signer, error)

ES384Signer creates a Signer providing ECDSA using P-384 and SHA-384 signatures using the given private key which must use ellipctic.P384() as the underlying curve.

func ES512Signer 

func ES512Signer(privateKey *ecdsa.PrivateKey) (Signer, error)

ES512Signer creates a Signer providing ECDSA using P-512 and SHA-512 signatures using the given private key which must use ellipctic.P512() as the underlying curve.

func RS256Signer 

func RS256Signer(privateKey *rsa.PrivateKey) Signer

RS256Signer creates a new Signer using the RS256 algorithm as specified in RFC 7518 section 3.3

func RS384Signer 

func RS384Signer(privateKey *rsa.PrivateKey) Signer

RS384Signer creates a new Signer using the RS384 algorithm as specified in RFC 7518 section 3.3

func RS512Signer 

func RS512Signer(privateKey *rsa.PrivateKey) Signer

RS512Signer creates a new Signer using the RS512 algorithm as specified in RFC 7518 section 3.3

type SignerVerifier 

type SignerVerifier interface {
	Signer
	Verifier
}

SignerVerifier is the combination of both Signer and Verifier. It is used for symmetric signatures (i.e. MACs).

func HS256 

func HS256(secret []byte) SignerVerifier

HS256 creates a signature method implementing the HMAC SHA256 algorithm.

func HS384 

func HS384(secret []byte) SignerVerifier

HS384 creates a signature method implementing the HMAC SHA384 algorithm.

func HS512 

func HS512(secret []byte) SignerVerifier

HS512 creates a signature method implementing the HMAC SHA512 algorithm.

func HSSignerVerifier 

func HSSignerVerifier(alg SignatureAlgorithm, secret []byte) (SignerVerifier, error)

HSSignerVerifier creates a new HMAC based SignerVerifier using alg as the HMAC algorithm and secret as the HMAC secret. If alg does not describe an HMAC algorithm (i.e. ES256 or RS256) a non-nil error is returned.

func None 

func None() SignerVerifier

None returns a signature method that creates no signature. Use this method to create unsecured JWTs as specified in RFC7519 section 6 (https://datatracker.ietf.org/doc/html/rfc7519#section-6)

func SymmetricSignature 

func SymmetricSignature(s Signer) SignerVerifier

SymmetricSignature creates a SignerVerifier

type Verifier 

type Verifier interface {
	// Verify is called to verify the given signature for the given data.
	// Implementations return nil in case of a valid signature or a non-nil error.
	// Implementation MUST NOT modify neither data nor signature.
	Verify(alg SignatureAlgorithm, data []byte, signature []byte) error
}

Verifier defines the interface for types verifying signatures.

func ES256Verifier 

func ES256Verifier(publicKey *ecdsa.PublicKey) (Verifier, error)

ES256Verifier creates a Verifier verifying ECDSA using P-256 and SHA-256 signatures using the given public key which must use ellipctic.P256() as the underlying curve.

func ES384Verifier 

func ES384Verifier(publicKey *ecdsa.PublicKey) (Verifier, error)

ES384Verifier creates a Verifier verifying ECDSA using P-384 and SHA-384 signatures using the given public key which must use ellipctic.P384() as the underlying curve.

func ES512Verifier 

func ES512Verifier(publicKey *ecdsa.PublicKey) (Verifier, error)

ES512Verifier creates a Verifier verifying ECDSA using P-512 and SHA-512 signatures using the given public key which must use ellipctic.P512() as the underlying curve.

func ESVerifier 

func ESVerifier(alg SignatureAlgorithm, publicKey *ecdsa.PublicKey) (Verifier, error)

ESVerifier creates a verifier for the ECDSA based algorithm alg and public key.

func RS256Verifier 

func RS256Verifier(publicKey *rsa.PublicKey) Verifier

RS256Verifier creates a Verifier for RS256 as defined in RFC 7518 section 3.3 (https://www.rfc-editor.org/rfc/rfc7518.html#section-3.3)

func RS384Verifier 

func RS384Verifier(publicKey *rsa.PublicKey) Verifier

RS384Verifier creates a Verifier for RS384 as defined in RFC 7518 section 3.3 (https://www.rfc-editor.org/rfc/rfc7518.html#section-3.3)

func RS512Verifier 

func RS512Verifier(publicKey *rsa.PublicKey) Verifier

RS512Verifier creates a Verifier for RS512 as defined in RFC 7518 section 3.3 (https://www.rfc-editor.org/rfc/rfc7518.html#section-3.3)

func RSVerifier 

func RSVerifier(alg SignatureAlgorithm, publicKey *rsa.PublicKey) (Verifier, error)

RSVerifier creates a new Verifier for RSA based signatures using alg as the algorithm and publicKey as the public key. If algs does not denote a supported RSA algorithm (i.e. HS256 or ES256) a non-nil error is retured.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.