jws

Documentation

Overview

Package jws provides a partial implementation of JSON Web Signature encoding and decoding. It includes support for HS256, HS384, HS512, RS256, RS384, and RS512 algorithms, although developers may extend this package by creating new Signer interfaces.

See RFC 7515.

Index

• func DecodeHeader(token string, hdr interface{}) error
• func ParseRSAKey(key []byte) (*rsa.PrivateKey, error)
• func Verify(token string, v Verifier) error
• type ClaimSet
  • func DecodePayload(token string) (*ClaimSet, error)
  • func (c *ClaimSet) JWT(signer Signer) (string, error)
  • func (c *ClaimSet) MarshalJSON() ([]byte, error)
  • func (c *ClaimSet) SetExpirationClaims(startOffset, tokenDuration time.Duration) error
  • func (c *ClaimSet) UnmarshalJSON(b []byte) error
• type Signer
  • func HS256(secret []byte) Signer
  • func HS384(secret []byte) Signer
  • func HS512(secret []byte) Signer
  • func RS256(key *rsa.PrivateKey, keyID string) Signer
  • func RS256FromPEM(pemBytes []byte, keyID string) (Signer, error)
  • func RS384(key *rsa.PrivateKey, keyID string) Signer
  • func RS384FromPEM(pemBytes []byte, keyID string) (Signer, error)
  • func RS512(key *rsa.PrivateKey, keyID string) Signer
  • func RS512FromPEM(pemBytes []byte, keyID string) (Signer, error)
• type Verifier
  • func HS256Verifier(secret []byte) Verifier
  • func HS384Verifier(secret []byte) Verifier
  • func HS512Verifier(secret []byte) Verifier
  • func RS256Verifier(key *rsa.PublicKey) Verifier
  • func RS384Verifier(key *rsa.PublicKey) Verifier
  • func RS512Verifier(key *rsa.PublicKey) Verifier

Functions

func DecodeHeader

func DecodeHeader(token string, hdr interface{}) error

DecodeHeader decodes the header from a JWT into hdr (usually a &map[string]interface{})

func ParseRSAKey

func ParseRSAKey(key []byte) (*rsa.PrivateKey, error)

ParseRSAKey converts the binary contents of a private key file to an *rsa.PrivateKey. It detects whether the private key is in a PEM container or not. If so, it extracts the the private key from PEM container before conversion. It only supports PEM containers with no passphrase.

func Verify

func Verify(token string, v Verifier) error

Verify tests whether the provided JWT token's signature is valid

Types

type ClaimSet

type ClaimSet struct {
	Issuer    string // iss: client_id of the application making the access token request
	Audience  string // aud: descriptor of the intended target of the assertion (Optional).
	ExpiresAt int64  // exp: the expiration time of the assertion (seconds since Unix epoch)
	IssuedAt  int64  // iat: the time the assertion was issued (seconds since Unix epoch)
	NotBefore int64  // nbf: the time before which the JWT MUST NOT be accepted for processing (Optional)
	ID        string // jti: The "jti" (JWT ID) claim provides a unique identifier for the JWT (Optional)
	Subject   string // sub: Email/UserID for which the application is requesting delegated access (Optional).

	// See https://tools.ietf.org/html/rfc7519#section-4.3
	// This array is marshalled using custom code (see (c *ClaimSet) MarshalJSON()).
	PrivateClaims map[string]interface{}
}

ClaimSet contains information about the JWT signature including the permissions being requested (scopes), the target of the token, the issuer, the time the token was issued, and the lifetime of the token. see https://tools.ietf.org/html/rfc7519

func DecodePayload

func DecodePayload(token string) (*ClaimSet, error)

DecodePayload decodes a claim set from a JWT.

func (*ClaimSet) JWT

func (c *ClaimSet) JWT(signer Signer) (string, error)

JWT creates a token using the signer

func (*ClaimSet) MarshalJSON

func (c *ClaimSet) MarshalJSON() ([]byte, error)

MarshalJSON flattens json output of PrivateClaims

func (*ClaimSet) SetExpirationClaims

func (c *ClaimSet) SetExpirationClaims(startOffset, tokenDuration time.Duration) error

SetExpirationClaims sets the IssuedAt (iat) and ExpiresAt (exp) claims

func (*ClaimSet) UnmarshalJSON

func (c *ClaimSet) UnmarshalJSON(b []byte) error

UnmarshalJSON places extra keys into PrivateClaims

type Signer

type Signer interface {
	Sign([]byte) ([]byte, error)
	Header() []byte
}

Signer provides a signature for a JWT as well as the Header

func HS256

func HS256(secret []byte) Signer

HS256 returns a signer implementing the HMAC with SHA-256 algorithm with the passed secret.

func HS384

func HS384(secret []byte) Signer

HS384 returns a signer implementing the HMAC with SHA-384 algorithm with the passed secret.

func HS512

func HS512(secret []byte) Signer

HS512 returns a signer implementing the HMAC with SHA-512 algorithm with the passed secret.

func RS256

func RS256(key *rsa.PrivateKey, keyID string) Signer

RS256 creates a signer for the RS256 algorithm

func RS256FromPEM

func RS256FromPEM(pemBytes []byte, keyID string) (Signer, error)

RS256FromPEM creates a signer that implements the RS256 (RSA PKCS#1 with SHA-512) algorithm for the encoded key in pemBytes. An error is returned if the pem encoding is invalid. pemBytes should contain the contents of a PEM file using PKCS8 or PKCS1 encoding. PEM containers with a passphrase are not supported. Use the following command to convert a PKCS 12 file into a PEM.

$ openssl pkcs12 -in key.p12 -out key.pem -nodes

func RS384

func RS384(key *rsa.PrivateKey, keyID string) Signer

RS384 creates a signer that implements the RS512 (RSA PKCS#1 with SHA-384) algorithm for the key. keyID is the optional and will be used in the kid header claim.

func RS384FromPEM

func RS384FromPEM(pemBytes []byte, keyID string) (Signer, error)

RS384FromPEM creates a signer that implements the RS384 (RSA PKCS#1 with SHA-512) algorithm for the encoded key in pemBytes. An error is returned if the pem encoding is invalid. pemBytes should contain the contents of a PEM file using PKCS8 or PKCS1 encoding. PEM containers with a passphrase are not supported.

func RS512

func RS512(key *rsa.PrivateKey, keyID string) Signer

RS512 creates a signer that implements the RS512 (RSA PKCS#1 with SHA-512) algorithm for the key. keyID is the optional and will be used in the kid header claim.

func RS512FromPEM

func RS512FromPEM(pemBytes []byte, keyID string) (Signer, error)

RS512FromPEM creates a signer that implements the RS512 (RSA PKCS#1 with SHA-512) algorithm for the encoded key in pemBytes. An error is returned if the pem encoding is invalid. pemBytes should contain the contents of a PEM file using PKCS8 or PKCS1 encoding. PEM containers with a passphrase are not supported.

type Verifier

type Verifier func(signature, content []byte) error

Verifier is a funct that verifies the signature of a specific content

func HS256Verifier

func HS256Verifier(secret []byte) Verifier

HS256Verifier verifies the signature using SHA256 hmac using secret

func HS384Verifier

func HS384Verifier(secret []byte) Verifier

HS384Verifier verifies the signature using SHA384 hmac using secret

func HS512Verifier

func HS512Verifier(secret []byte) Verifier

HS512Verifier verifies the signature using SHA384 hmac using secret

func RS256Verifier

func RS256Verifier(key *rsa.PublicKey) Verifier

RS256Verifier verifies the signature using PKCS1v15 using key

func RS384Verifier

func RS384Verifier(key *rsa.PublicKey) Verifier

RS384Verifier verifies the signature using PKCS1v15 using key

func RS512Verifier

func RS512Verifier(key *rsa.PublicKey) Verifier

RS512Verifier verifies the signature using PKCS1v15 using key