jwt

package
v1.20210908.5 Latest Latest
Warning

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

 Go to latest Published: Sep 8, 2021 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package jwt provides helpers for creating and validating json web tokens.

Index

Constants

View Source 
const (
	SigningMethodNameHMAC256 = "HS256"
	SigningMethodNameHMAC384 = "HS384"
	SingingMethodNameHMAC512 = "HS512"

	SigningMethodNameES256 = "ES256"
	SigningMethodNameES384 = "ES384"
	SigningMethodNameES512 = "ES512"

	SigningMethodNameRS256 = "RS256"
	SigningMethodNameRS384 = "RS384"
	SigningMethodNameRS512 = "RS512"
)

Common signing method names.

View Source 
const (
	KTYRSA = "RSA"
)

KTY parameter values as defined in https://tools.ietf.org/html/rfc7518#section-6.1

Variables

View Source 
var (
	ErrNotECPublicKey  ex.Class = "Key is not a valid ECDSA public key"
	ErrNotECPrivateKey ex.Class = "Key is not a valid ECDSA private key"
)

Common ECDSA errors.

View Source 
var (
	// ErrValidation will be the top most class in most cases.
	ErrValidation ex.Class = "validation error"

	ErrValidationAudienceUnset ex.Class = "token claims audience unset"
	ErrValidationExpired       ex.Class = "token expired"
	ErrValidationIssued        ex.Class = "token issued in future"
	ErrValidationNotBefore     ex.Class = "token not before"

	ErrValidationSignature ex.Class = "signature is invalid"

	ErrKeyfuncUnset         ex.Class = "keyfunc is unset"
	ErrInvalidKey           ex.Class = "key is invalid"
	ErrInvalidKeyType       ex.Class = "key is of invalid type"
	ErrInvalidSigningMethod ex.Class = "invalid signing method"
	ErrHashUnavailable      ex.Class = "the requested hash function is unavailable"

	ErrHMACSignatureInvalid ex.Class = "hmac signature is invalid"

	ErrECDSAVerification ex.Class = "crypto/ecdsa: verification error"

	ErrKeyMustBePEMEncoded ex.Class = "invalid key: key must be pem encoded pkcs1 or pkcs8 private key"
	ErrNotRSAPrivateKey    ex.Class = "key is not a valid rsa private key"
	ErrNotRSAPublicKey     ex.Class = "key is not a valid rsa public key"
)

Error constants.

View Source 
var (
	SigningMethodHMAC256 = &SigningMethodHMAC{SigningMethodNameHMAC256, crypto.SHA256}
	SigningMethodHMAC384 = &SigningMethodHMAC{SigningMethodNameHMAC384, crypto.SHA384}
	SigningMethodHMAC512 = &SigningMethodHMAC{SingingMethodNameHMAC512, crypto.SHA512}

	SigningMethodES256 = &SigningMethodECDSA{SigningMethodNameES256, crypto.SHA256, 32, 256}
	SigningMethodES384 = &SigningMethodECDSA{SigningMethodNameES384, crypto.SHA384, 48, 384}
	SigningMethodES512 = &SigningMethodECDSA{SigningMethodNameES512, crypto.SHA512, 66, 521}

	SigningMethodRS256 = &SigningMethodRSA{SigningMethodNameRS256, crypto.SHA256}
	SigningMethodRS384 = &SigningMethodRSA{SigningMethodNameRS384, crypto.SHA384}
	SigningMethodRS512 = &SigningMethodRSA{SigningMethodNameRS512, crypto.SHA512}
)

Static references for specific signing methods.

View Source 
var TimeFunc = time.Now

TimeFunc provides the current time when parsing token to validate "exp" claim (expiration time). You can override it to use another time value. This is useful for testing or if your server uses a different time zone than your tokens.

Functions

func DecodeSegment 

func DecodeSegment(seg string) ([]byte, error)

DecodeSegment decodes a JWT specific base64url encoding with suffix '=' padding added back if not present.

func EncodeSegment 

func EncodeSegment(seg []byte) string

EncodeSegment en codes JWT specific base64url encoding with suffix '=' padding stripped.

func IsValidation 

func IsValidation(err error) bool

IsValidation returns if the error is a validation error instead of a more structural error with the key infrastructure.

func ParseECPrivateKeyFromPEM 

func ParseECPrivateKeyFromPEM(key []byte) (*ecdsa.PrivateKey, error)

ParseECPrivateKeyFromPEM parses a PEM encoded Elliptic Curve Private Key Structure

func ParseECPublicKeyFromPEM 

func ParseECPublicKeyFromPEM(key []byte) (*ecdsa.PublicKey, error)

ParseECPublicKeyFromPEM parses a PEM encoded PKCS1 or PKCS8 public key.

func ParseRSAPrivateKeyFromPEM 

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

ParseRSAPrivateKeyFromPEM parses a PEM encoded PKCS1 or PKCS8 private key.

func ParseRSAPrivateKeyFromPEMWithPassword 

func ParseRSAPrivateKeyFromPEMWithPassword(key []byte, password string) (*rsa.PrivateKey, error)

ParseRSAPrivateKeyFromPEMWithPassword parses a PEM encoded PKCS1 or PKCS8 private key protected with password.

func ParseRSAPublicKeyFromPEM 

func ParseRSAPublicKeyFromPEM(key []byte) (*rsa.PublicKey, error)

ParseRSAPublicKeyFromPEM parses a PEM encoded PKCS1 or PKCS8 public key.

Types

type Claims 

type Claims interface {
	Valid() error
}

Claims are a type that must just have a Valid method that determines if the token is invalid for any supported reason

type JWK added in v1.20201204.1 

type JWK struct {
	KTY string `json:"kty"`
	USE string `json:"use,omitempty"`
	ALG string `json:"alg,omitempty"`
	KID string `json:"kid,omitempty"`
	E   string `json:"e,omitempty"`
	N   string `json:"n,omitempty"`
}

JWK represents a cryptographic key as defined by https://tools.ietf.org/html/rfc7517#section-4

func RSAPublicKeyToJWK added in v1.20210306.2 

func RSAPublicKeyToJWK(key *rsa.PublicKey) JWK

RSAPublicKeyToJWK converts an RSA public key to a JWK.

func (JWK) RSAPublicKey added in v1.20210306.2 

func (j JWK) RSAPublicKey() (*rsa.PublicKey, error)

RSAPublicKey parses the public key in the JWK to a rsa.PublicKey.

type JWKSet added in v1.20210306.2 

type JWKSet struct {
	Keys []JWK `json:"keys"`
}

JWKSet represents a set of JWKs as defined by https://tools.ietf.org/html/rfc7517#section-5

type Keyfunc 

type Keyfunc func(*Token) (interface{}, error)

Keyfunc should return the key used in verification based on the raw token passed to it.

func KeyfuncStatic added in v1.20201204.1 

func KeyfuncStatic(key []byte) Keyfunc

KeyfuncStatic returns a static key func.

type MapClaims 

type MapClaims map[string]interface{}

MapClaims is a claims type that uses the map[string]interface{} for JSON decoding This is the default claims type if you don't supply one

func (MapClaims) Valid 

func (m MapClaims) Valid() error

Valid validates time based claims "exp, iat, nbf". There is no accounting for clock skew. As well, if any of the above claims are not in the token, it will still be considered a valid claim.

func (MapClaims) VerifyAudience 

func (m MapClaims) VerifyAudience(cmp string, req bool) bool

VerifyAudience compares the aud claim against cmp. If required is false, this method will return true if the value matches or is unset

func (MapClaims) VerifyExpiresAt 

func (m MapClaims) VerifyExpiresAt(cmp int64, req bool) bool

VerifyExpiresAt compares the exp claim against cmp. If required is false, this method will return true if the value matches or is unset

func (MapClaims) VerifyIssuedAt 

func (m MapClaims) VerifyIssuedAt(cmp int64, req bool) bool

VerifyIssuedAt compares the iat claim against cmp. If required is false, this method will return true if the value matches or is unset

func (MapClaims) VerifyIssuer 

func (m MapClaims) VerifyIssuer(cmp string, req bool) bool

VerifyIssuer compares the iss claim against cmp. If required is false, this method will return true if the value matches or is unset

func (MapClaims) VerifyNotBefore 

func (m MapClaims) VerifyNotBefore(cmp int64, req bool) bool

VerifyNotBefore compares the nbf claim against cmp. If required is false, this method will return true if the value matches or is unset

type Parser 

type Parser struct {
	ValidMethods         []string // If populated, only these methods will be considered valid
	UseJSONNumber        bool     // Use JSON Number format in JSON decoder
	SkipClaimsValidation bool     // Skip claims validation during token parsing
}

Parser is a parser for tokens.

func (*Parser) Parse 

func (p *Parser) Parse(tokenString string, keyFunc Keyfunc) (*Token, error)

Parse parses, validate, and return a token.

func (*Parser) ParseUnverified 

func (p *Parser) ParseUnverified(tokenString string, claims Claims) (token *Token, parts []string, err error)

ParseUnverified parses the token but doesn't validate the signature. WARNING: Don't use this method unless you know what you're doing It's only ever useful in cases where you know the signature is valid (because it has been checked previously in the stack) and you want to extract values from it.

func (*Parser) ParseWithClaims 

func (p *Parser) ParseWithClaims(tokenString string, claims Claims, keyFunc Keyfunc) (*Token, error)

ParseWithClaims parses a token with a given set of claims.

type SigningMethod 

type SigningMethod interface {
	Verify(signingString, signature string, key interface{}) error // Returns nil if signature is valid
	Sign(signingString string, key interface{}) (string, error)    // Returns encoded signature or error
	Alg() string                                                   // returns the alg identifier for this method (example: 'HS256')
}

SigningMethod is a type that implements methods required to sign tokens.

func GetSigningMethod 

func GetSigningMethod(name string) SigningMethod

GetSigningMethod returns a signing method with a given name.

type SigningMethodECDSA 

type SigningMethodECDSA struct {
	Name      string
	Hash      crypto.Hash
	KeySize   int
	CurveBits int
}

SigningMethodECDSA implements the ECDSA family of signing methods signing methods Expects *ecdsa.PrivateKey for signing and *ecdsa.PublicKey for verification

func (*SigningMethodECDSA) Alg 

func (m *SigningMethodECDSA) Alg() string

Alg returns the signing method name.

func (*SigningMethodECDSA) Sign 

func (m *SigningMethodECDSA) Sign(signingString string, key interface{}) (string, error)

Sign implements the Sign method from SigningMethod For this signing method, key must be an ecdsa.PrivateKey struct

func (*SigningMethodECDSA) Verify 

func (m *SigningMethodECDSA) Verify(signingString, signature string, key interface{}) error

Verify implements the Verify method from SigningMethod For this verify method, key must be an ecdsa.PublicKey struct

type SigningMethodHMAC 

type SigningMethodHMAC struct {
	Name string
	Hash crypto.Hash
}

SigningMethodHMAC implements the HMAC-SHA family of signing methods signing methods Expects key type of []byte for both signing and validation

func (*SigningMethodHMAC) Alg 

func (m *SigningMethodHMAC) Alg() string

Alg returns the name of the signing method.

func (*SigningMethodHMAC) Sign 

func (m *SigningMethodHMAC) Sign(signingString string, key interface{}) (string, error)

Sign implements the Sign method from SigningMethod for this signing method. Key must be []byte

func (*SigningMethodHMAC) Verify 

func (m *SigningMethodHMAC) Verify(signingString, signature string, key interface{}) error

Verify the signature of HSXXX tokens. Returns nil if the signature is valid.

type SigningMethodRSA 

type SigningMethodRSA struct {
	Name string
	Hash crypto.Hash
}

SigningMethodRSA implements the RSA family of signing methods signing methods Expects *rsa.PrivateKey for signing and *rsa.PublicKey for validation

func (*SigningMethodRSA) Alg 

func (m *SigningMethodRSA) Alg() string

Alg returns the name of the signing method.

func (*SigningMethodRSA) Sign 

func (m *SigningMethodRSA) Sign(signingString string, key interface{}) (string, error)

Sign implements the Sign method from SigningMethod For this signing method, must be an *rsa.PrivateKey structure.

func (*SigningMethodRSA) Verify 

func (m *SigningMethodRSA) Verify(signingString, signature string, key interface{}) error

Verify implements the Verify method from SigningMethod For this signing method, must be an *rsa.PublicKey structure.

type StandardClaims 

type StandardClaims struct {
	ID        string `json:"jti,omitempty"`
	Audience  string `json:"aud,omitempty"`
	ExpiresAt int64  `json:"exp,omitempty"`
	IssuedAt  int64  `json:"iat,omitempty"`
	Issuer    string `json:"iss,omitempty"`
	NotBefore int64  `json:"nbf,omitempty"`
	Subject   string `json:"sub,omitempty"`
}

StandardClaims are a structured version of Claims Section, as referenced at https://tools.ietf.org/html/rfc7519#section-4.1 See examples for how to use this with your own claim types

func (StandardClaims) Valid 

func (c StandardClaims) Valid() error

Valid asserts time based claims "exp, iat, nbf". There is no accounting for clock skew. As well, if any of the above claims are not in the token, it will still be considered a valid claim.

func (*StandardClaims) VerifyAudience 

func (c *StandardClaims) VerifyAudience(cmp string, req bool) bool

VerifyAudience compares the aud claim against cmp. If required is false, this method will return true if the value matches or is unset

func (*StandardClaims) VerifyExpiresAt 

func (c *StandardClaims) VerifyExpiresAt(cmp int64, req bool) bool

VerifyExpiresAt compares the exp claim against cmp. If required is false, this method will return true if the value matches or is unset

func (*StandardClaims) VerifyIssuedAt 

func (c *StandardClaims) VerifyIssuedAt(cmp int64, req bool) bool

VerifyIssuedAt compares the iat claim against cmp. If required is false, this method will return true if the value matches or is unset

func (*StandardClaims) VerifyIssuer 

func (c *StandardClaims) VerifyIssuer(cmp string, req bool) bool

VerifyIssuer compares the iss claim against cmp. If required is false, this method will return true if the value matches or is unset

func (*StandardClaims) VerifyNotBefore 

func (c *StandardClaims) VerifyNotBefore(cmp int64, req bool) bool

VerifyNotBefore compares the nbf claim against cmp. If required is false, this method will return true if the value matches or is unset

type Token 

type Token struct {
	Raw       string                 // The raw token.  Populated when you Parse a token
	Method    SigningMethod          // The signing method used or to be used
	Header    map[string]interface{} // The first segment of the token
	Claims    Claims                 // The second segment of the token
	Signature string                 // The third segment of the token.  Populated when you Parse a token
	Valid     bool                   // Is the token valid?  Populated when you Parse/Verify a token
}

Token is a JWT token. Different fields will be used depending on whether you're creating or parsing/verifying a token.

func New 

func New(method SigningMethod) *Token

New creates a new Token with a given signing method.

func NewWithClaims 

func NewWithClaims(method SigningMethod, claims Claims) *Token

NewWithClaims creates a new token with the given claims object.

func Parse 

func Parse(tokenString string, keyFunc Keyfunc) (*Token, error)

Parse validates and returns a token from a given string. KeyFunc will receive the parsed token and should return the key for validating.

func ParseWithClaims 

func ParseWithClaims(tokenString string, claims Claims, keyFunc Keyfunc) (*Token, error)

ParseWithClaims parses a token with a given set of claims.

func (*Token) SignedString 

func (t *Token) SignedString(key interface{}) (output string, err error)

SignedString returns the complete, signed token.

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.