README
¶
jwgo is a Go library for efficient creation and parsing of JSON web tokens.
Installation
Install jwgo using the go get command:
go get -u github.com/alvii147/jwgo
Usage
Once installed, jwgo can be used to both encode and decode JWTs.
Encoding
jwgo.NewEncoder can be used to encode a given payload:
package main
import (
"fmt"
"os"
"strings"
"time"
"github.com/alvii147/jwgo"
)
func main() {
issuedAt := time.Now().UTC().Unix()
expirationTime := time.Now().UTC().AddDate(0, 0, 1).Unix()
notBefore := time.Now().UTC().AddDate(0, 0, -1).Unix()
payload := &jwgo.Payload{
Issuer: "pickle",
Subject: "rick",
Audience: []string{"foo"},
ExpirationTime: &expirationTime,
NotBefore: ¬Before,
IssuedAt: &issuedAt,
JWTID: "42",
}
key := []byte("deadbeef")
signer := jwgo.NewHS256(key)
var w strings.Builder
err := jwgo.NewEncoder(&w, signer).Encode(payload)
if err != nil {
fmt.Fprint(os.Stderr, "encoding failed", err)
}
fmt.Println(w.String())
// eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJwaW...
}
Decoding
jwgo.NewDecoder can be used to decode a given JWT:
package main
import (
"fmt"
"os"
"strings"
"github.com/alvii147/jwgo"
)
func main() {
key := []byte("deadbeef")
verifier := jwgo.NewHS256(key)
token := "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJwaW..."
r := strings.NewReader(token)
payload := jwgo.Payload{}
err := jwgo.NewDecoder(r, verifier).Decode(&payload)
if err != nil {
fmt.Fprint(os.Stderr, "encoding failed", err)
}
fmt.Printf("%+v\n", payload)
// {Issuer:pickle Subject:rick Audience:[foo] ExpirationTime:0x140000982f8 NotBefore:0x14000098300 IssuedAt:0x14000098308 JWTID:42}
}
Signing Methods
jwgo supports the following signing methods:
| Method Name | Method Details | Constructor Function |
|---|---|---|
HS256 |
HMAC + SHA-256 | NewHS256 |
HS384 |
HMAC + SHA-384 | NewHS384 |
HS512 |
HMAC + SHA-512 | NewHS512 |
RS256 |
RSA-PKCS#1 v1.5 + SHA-256 | NewRS256 |
RS384 |
RSA-PKCS#1 v1.5 + SHA-384 | NewRS384 |
RS512 |
RSA-PKCS#1 v1.5 + SHA-512 | NewRS512 |
PS256 |
RSA-PSS + SHA-256 | NewPS256 |
PS384 |
RSA-PSS + SHA-384 | NewPS384 |
PS512 |
RSA-PSS + SHA-512 | NewPS512 |
ES256 |
ECDSA + SHA-256 | NewES256 |
ES384 |
ECDSA + SHA-384 | NewES384 |
ES512 |
ECDSA + SHA-512 | NewES512 |
EdDSA |
Ed25519 | NewEdDSA |
Benchmark
The full results of benchmark can be found here. The following plots demonstrate the results of benchmarking the performance of HMAC-SHA256 JWT creation and parsing of jwgo against that of github.com/golang-jwt/jwt, which is the most popular Golang library for creating/parsing JWTs:
Documentation
¶
Overview ¶
Package jwgo is a Go library efficient generation and parsing of JSON web tokens.
Index ¶
Constants ¶
const ( // ES256 represents ECDSA SHA-256 signing. ES256 = "ES256" // ES256Header is the pre-computed base64-encoded JWT header for ES256. ES256Header = "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9" // ES256Size is key size for ES256. ES256Size = 32 // ES384 represents ECDSA SHA-384 signing. ES384 = "ES384" // ES384Header is the pre-computed base64-encoded JWT header for ES384. ES384Header = "eyJhbGciOiJFUzM4NCIsInR5cCI6IkpXVCJ9" // ES384Size is key size for ES384. ES384Size = 48 // ES512 represents ECDSA SHA-512 signing. ES512 = "ES512" // ES512Header is the pre-computed base64-encoded JWT header for ES512. ES512Header = "eyJhbGciOiJFUzUxMiIsInR5cCI6IkpXVCJ9" // ES512Size is key size for ES512. ES512Size = 66 )
const ( // EdDSA represents Ed25519 signing. EdDSA = "EdDSA" // EdDSAHeader is the pre-computed base64-encoded JWT header for Ed25519. EdDSAHeader = "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9" )
const ( // HS256 represents HMAC SHA-256 signing. HS256 = "HS256" // HS256Header is the pre-computed base64-encoded JWT header for HMAC SHA-256. HS256Header = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9" // HS384 represents HMAC SHA-384 signing. HS384 = "HS384" // HS384Header is the pre-computed base64-encoded JWT header for HMAC SHA-384. HS384Header = "eyJhbGciOiJIUzM4NCIsInR5cCI6IkpXVCJ9" // HS512 represents HMAC SHA-512 signing. HS512 = "HS512" // HS512Header is the pre-computed base64-encoded JWT header for HMAC SHA-512. HS512Header = "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9" )
const ( // PS256 represents RSA-PSS SHA-256 signing. PS256 = "PS256" // PS256Header is the pre-computed base64-encoded JWT header for PS256. PS256Header = "eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCJ9" // PS384 represents RSA-PSS SHA-384 signing. PS384 = "PS384" // PS384Header is the pre-computed base64-encoded JWT header for PS384. PS384Header = "eyJhbGciOiJQUzM4NCIsInR5cCI6IkpXVCJ9" // PS512 represents RSA-PSS SHA-512 signing. PS512 = "PS512" // PS512Header is the pre-computed base64-encoded JWT header for PS512. PS512Header = "eyJhbGciOiJQUzUxMiIsInR5cCI6IkpXVCJ9" )
const ( // RS256 represents RSA-PKCS#1 v1.5 SHA-256 signing. RS256 = "RS256" // RS256Header is the pre-computed base64-encoded JWT header for RS256. RS256Header = "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9" // RS384 represents RSA-PKCS#1 v1.5 SHA-384 signing. RS384 = "RS384" // RS384Header is the pre-computed base64-encoded JWT header for RS384. RS384Header = "eyJhbGciOiJSUzM4NCIsInR5cCI6IkpXVCJ9" // RS512 represents RSA-PKCS#1 v1.5 SHA-512 signing. RS512 = "RS512" // RS512Header is the pre-computed base64-encoded JWT header for RS512. RS512Header = "eyJhbGciOiJSUzUxMiIsInR5cCI6IkpXVCJ9" )
const ( // Separator is the character separating different sections on the JWT. Separator string = "." )
Variables ¶
var ( // ErrInvalidToken indicates token parsing errors. ErrInvalidToken = errors.New("invalid token") // ErrUnsupportedAlgorithm indicates the algorithm on the token's header is unsupported. ErrUnsupportedAlgorithm = errors.New("unsupported algorithm") // ErrInvalidSignature indicates a verification error in the token's signature. ErrInvalidSignature = errors.New("invalid signature") // ErrExpired indicates that the token is expired. ErrExpired = errors.New("expired") // ErrNotYetEffectiveToken indicates that the token is not yet effective. ErrNotYetEffectiveToken = errors.New("not yet effective") // ErrInvalidIssuedAt indicates that the token has an invalid issued at time. ErrInvalidIssuedAt = errors.New("invalid issued at") )
var ( // PSSSignOptions represents options for RSA-PSS signing. PSSSignOptions = &rsa.PSSOptions{ SaltLength: rsa.PSSSaltLengthEqualsHash, } // PSSVerifyOptions represents options for RSA-PSS verification. PSSVerifyOptions = &rsa.PSSOptions{ SaltLength: rsa.PSSSaltLengthAuto, } )
Functions ¶
func NewDecoder ¶
NewDecoder creates and returns a new [decoder].
func NewEncoder ¶
NewEncoder creates and returns a new [encoder].
Types ¶
type ECDSA ¶
type ECDSA struct {
// contains filtered or unexported fields
}
ECDSA signs and verifies JWT using ECDSA signing.
func NewES256 ¶
func NewES256(publicKey *ecdsa.PublicKey, privateKey *ecdsa.PrivateKey) *ECDSA
NewES256 creates and returns a new ECDSA with ECDSA SHA-256 signing..
func NewES384 ¶
func NewES384(publicKey *ecdsa.PublicKey, privateKey *ecdsa.PrivateKey) *ECDSA
NewES384 creates and returns a new ECDSA with ECDSA SHA-384 signing..
func NewES512 ¶
func NewES512(publicKey *ecdsa.PublicKey, privateKey *ecdsa.PrivateKey) *ECDSA
NewES512 creates and returns a new ECDSA with ECDSA SHA-512 signing..
type ED25519 ¶
type ED25519 struct {
// contains filtered or unexported fields
}
ED25519 signs and verifies JWT using Ed25519 signing.
func NewEdDSA ¶
func NewEdDSA(publicKey ed25519.PublicKey, privateKey ed25519.PrivateKey) *ED25519
NewEdDSA creates and returns a new ED25519.
type HMAC ¶
type HMAC struct {
// contains filtered or unexported fields
}
HMAC signs and verifies JWT using HMAC SHA signing.
type Header ¶
type Header struct {
// Algorithm is the signing algorithm used to sign the JWT.
Algorithm string `json:"alg"`
// Type represents the media type, which is always "JWT" in this case.
Type string `json:"typ"`
}
Header represents the cryptographic operations applied to the JWT.
type Payload ¶
type Payload struct {
// Issuer identifies the principal that issued the JWT.
Issuer string `json:"iss,omitempty"`
// Subject identifies the principal that is the subject of the JWT.
Subject string `json:"sub,omitempty"`
// Audience identifies the recipients that the JWT is intended for.
Audience []string `json:"aud,omitempty"`
// ExpirationTime identifies the expiration time on or after which the JWT MUST NOT be accepted for processing.
ExpirationTime *int64 `json:"exp,omitempty"`
// NotBefore identifies the time before which the JWT MUST NOT be accepted for processing.
NotBefore *int64 `json:"nbf,omitempty"`
// IssuedAt identifies the time at which the JWT was issued.
IssuedAt *int64 `json:"iat,omitempty"`
// JWTID provides a unique identifier for the JWT.
JWTID string `json:"jti,omitempty"`
}
Payload represents registered claims conveyed by the JWT.
type RSAPKCS1v15 ¶
type RSAPKCS1v15 struct {
// contains filtered or unexported fields
}
RSAPKCS1v15 signs and verifies JWT using RSA-PKCS#1 v1.5 signing.
func NewRS256 ¶
func NewRS256(publicKey *rsa.PublicKey, privateKey *rsa.PrivateKey) *RSAPKCS1v15
NewRS256 creates and returns a new RSAPKCS1v15 with RSA-PKCS#1 v1.5 SHA-256 signing.
func NewRS384 ¶
func NewRS384(publicKey *rsa.PublicKey, privateKey *rsa.PrivateKey) *RSAPKCS1v15
NewRS384 creates and returns a new RSAPKCS1v15 with RSA-PKCS#1 v1.5 SHA-384 signing.
func NewRS512 ¶
func NewRS512(publicKey *rsa.PublicKey, privateKey *rsa.PrivateKey) *RSAPKCS1v15
NewRS512 creates and returns a new RSAPKCS1v15 with RSA-PKCS#1 v1.5 SHA-512 signing.
func (*RSAPKCS1v15) Grow ¶
func (r *RSAPKCS1v15) Grow(n int)
Grow grows the allocated size of the underlying data.
func (*RSAPKCS1v15) Header ¶
func (r *RSAPKCS1v15) Header() string
Header returns the pre-computed base64-encoded header.
func (*RSAPKCS1v15) Sign ¶
func (r *RSAPKCS1v15) Sign() ([]byte, error)
Sign signs the written data.
func (*RSAPKCS1v15) String ¶
func (r *RSAPKCS1v15) String() string
String returns the name of the algorithm.
func (*RSAPKCS1v15) Verify ¶
func (r *RSAPKCS1v15) Verify(signature []byte) bool
Verify verifies the written data.
type RSAPSS ¶
type RSAPSS struct {
// contains filtered or unexported fields
}
RSAPSS signs and verifies JWT using RSA-PSS signing.
func NewPS256 ¶
func NewPS256(publicKey *rsa.PublicKey, privateKey *rsa.PrivateKey) *RSAPSS
NewPS256 creates and returns a new RSAPSS with RSA-PSS SHA-256 signing.
func NewPS384 ¶
func NewPS384(publicKey *rsa.PublicKey, privateKey *rsa.PrivateKey) *RSAPSS
NewPS384 creates and returns a new RSAPSS with RSA-PSS SHA-384 signing.
func NewPS512 ¶
func NewPS512(publicKey *rsa.PublicKey, privateKey *rsa.PrivateKey) *RSAPSS
NewPS512 creates and returns a new RSAPSS with RSA-PSS SHA-512 signing.
type TimeConstrainedPayload ¶
TimeConstrainedPayload represents payloads with timed constraints.
Source Files