gojwt

README

Go JWT

A Golang implementation of JSON Web Token (JWT) - RFC 7519.

Supported Go versions

Our support of Go versions is aligned with Go's version release policy. So we will support a major version of Go until there are two newer major releases.

---

• Install
• Available Algorithms
• Quick Start
• Issue Reporting
• Secure
• Author
• License

---

Install

With a correctly configured Go toolchain:

go get -u github.com/dmalix/gojwt

Available Algorithms

The library implements JWT Verification and Signing using the following algorithms:

JWS	Algorithm	Description
HS256	HMAC256	HMAC with SHA-256
HS512	HMAC512	HMAC with SHA-512

Quick Start

Create a new JWT instance and configure the parameters:

jwtInstance, err := gojwt.NewToken(&gojwt.Config{
   Headers: &gojwt.Headers{
      Type:               gojwt.EnumTokenTypeJWT,
      SignatureAlgorithm: gojwt.EnumTokenSignatureAlgorithmHS256,   
   },
   Claims: &gojwt.Claims{
      Issuer:  "some data",
      Subject: "some subject",
   },
   ParseOptions: gojwt.ParseOptions{
      RequiredHeaderContentType:   true,
      RequiredClaimIssuer:         true,
      RequiredClaimSubject:        true,
      RequiredClaimJwtId:          true,
      RequiredClaimData:           true
   },
   TokenLifetimeSec: 100,
   Key:              "your-256-bit-secret",
})
if err != nil {
   log.Fatal(err)
}

Create a new token:

jwt, err := jwtInstance.Create(&gojwt.Claims{
   JwtId: "some Id",
   Data:  []byte("some dataset"),
})
if err != nil {
   log.Fatal(err)
}

And so you can check and get data from the token:

jwt := "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
jwtToken, codeError, err := jwtInstance.Parse(jwt)
if err != nil {
   log.Fatalln(codeError, err)
}

Issue Reporting

If you have found a bug or if you have a feature request, please report them at this repository issues section. Please do not report security vulnerabilities on the public GitHub issue tracker.

Secure

If you discover any security related issues, please email dmalix@yahoo.com instead of using the issue tracker.

Author

DmAlix

License

This project is licensed under the MIT license. See the LICENSE file for more info.

Documentation

Index

• func NewToken(config *Config) (*resources, error)
• type Claims
• type Config
• type EnumError
• type EnumTokenSignatureAlgorithm
• type EnumTokenType
• type EnumValidationMessage
• type Headers
• type Jwt
• type MockDescription
  • func (s *MockDescription) Create(_ Claims, _ ...Headers) (string, error)
  • func (s *MockDescription) GetClaims() Claims
  • func (s *MockDescription) GetHeaders() Headers
  • func (s *MockDescription) GetParseOptions() ParseOptions
  • func (s *MockDescription) Parse(_ string, _ ...ParseOptions) (Token, string, error)
• type ParseOptions
• type Token

Functions

func NewToken

func NewToken(
	config *Config) (*resources, error)

Types

type Claims

type Claims struct {
	Issuer         string `json:"iss,omitempty"`
	Subject        string `json:"sub,omitempty"`
	Audience       string `json:"aud,omitempty"`
	ExpirationTime int64  `json:"exp"`
	NotBefore      int64  `json:"nbf,omitempty"`
	IssuedAt       int64  `json:"iat"`
	JwtId          string `json:"jti,omitempty"`
	Data           []byte `json:"data,omitempty"` // It is a custom field for any data (for example, encrypted data).
}

type Config

type Config struct {
	Headers       *Headers
	Claims        *Claims
	ParseOptions  ParseOptions
	TokenLifetime int64
	Key           string
}

type EnumError

type EnumError error

var (
	EnumErrorInvalidToken EnumError = errors.New("invalid token")
	EnumErrorMalformed    EnumError = errors.New("malformed token")
)

type EnumTokenSignatureAlgorithm

type EnumTokenSignatureAlgorithm string

const (
	EnumTokenSignatureAlgorithmHS256 EnumTokenSignatureAlgorithm = "HS256"
	EnumTokenSignatureAlgorithmHS512 EnumTokenSignatureAlgorithm = "HS512"
)

type EnumTokenType

type EnumTokenType string

const (
	EnumTokenTypeJWT EnumTokenType = "JWT"
)

type EnumValidationMessage

type EnumValidationMessage string

const (
	EnumValidationMessageMalformed        EnumValidationMessage = "token is malformed"
	EnumValidationMessageHeadersMalformed EnumValidationMessage = "token headers are malformed"
	EnumValidationMessageClaimsMalformed  EnumValidationMessage = "token claims are malformed"
	EnumValidationMessageUnverifiable     EnumValidationMessage = "the token could not be verified due to problems with the generation of the test sample"
	EnumValidationMessageSignatureInvalid EnumValidationMessage = "signature validation failed"

	EnumValidationMessageHeadersContentType EnumValidationMessage = "header 'cty' validation failed"
	EnumValidationMessageHeadersKeyId       EnumValidationMessage = "header 'kid' validation failed"
	EnumValidationMessageHeadersCritical    EnumValidationMessage = "header 'crit' validation failed"

	EnumValidationMessageClaimsIssuer      EnumValidationMessage = "claim 'iss' validation failed"
	EnumValidationMessageClaimsSubject     EnumValidationMessage = "claim 'sub' validation failed"
	EnumValidationMessageClaimsAudience    EnumValidationMessage = "claim 'aud' validation failed"
	EnumValidationMessageClaimsExpired     EnumValidationMessage = "claim 'exp' validation failed"
	EnumValidationMessageClaimsNotValidYet EnumValidationMessage = "claim 'nbf' validation failed"
	EnumValidationMessageClaimsIssuedAt    EnumValidationMessage = "claim 'iat' validation failed"
	EnumValidationMessageClaimsJwtId       EnumValidationMessage = "claim 'jti' validation failed"
	EnumValidationMessageClaimsData        EnumValidationMessage = "claim 'data' validation failed"
)

type Headers

type Headers struct {
	Type               EnumTokenType               `json:"typ"`
	SignatureAlgorithm EnumTokenSignatureAlgorithm `json:"alg"`
	ContentType        string                      `json:"cty,omitempty"`
	KeyId              string                      `json:"kid,omitempty"`
	Critical           string                      `json:"crit,omitempty"`
}

type Jwt

type Jwt interface {
	Create(claims *Claims, headers ...*Headers) (string, error)
	Parse(jwt string, options ...*ParseOptions) (*Token, EnumValidationMessage, error)

	GetHeaders() *Headers
	GetClaims() *Claims
	GetParseOptions() ParseOptions
}

type MockDescription

type MockDescription struct {
	Expected struct {
		Create struct {
			Jwt   string
			Error error
		}
		Parse struct {
			Token Token
			Error error
		}
		GetHeaders struct {
			Headers Headers
		}
		GetClaims struct {
			Claims Claims
		}
		GetParseOptions struct {
			ParseOptions ParseOptions
		}
	}
}

var Mock MockDescription

func (*MockDescription) Create

func (s *MockDescription) Create(_ Claims, _ ...Headers) (string, error)

func (*MockDescription) GetClaims

func (s *MockDescription) GetClaims() Claims

func (*MockDescription) GetHeaders

func (s *MockDescription) GetHeaders() Headers

func (*MockDescription) GetParseOptions

func (s *MockDescription) GetParseOptions() ParseOptions

func (*MockDescription) Parse

func (s *MockDescription) Parse(_ string, _ ...ParseOptions) (Token, string, error)

type ParseOptions

type ParseOptions struct {
	RequiredHeaderContentType             bool
	RequiredHeaderKeyId                   bool
	RequiredHeaderX509CertificateChain    bool
	RequiredHeaderX509CertificateChainURL bool
	RequiredHeaderCritical                bool
	RequiredClaimIssuer                   bool
	RequiredClaimSubject                  bool
	RequiredClaimAudience                 bool
	RequiredClaimJwtId                    bool
	RequiredClaimData                     bool
	SkipClaimsValidation                  bool
	SkipSignatureValidation               bool
}

type Token

type Token struct {
	Headers   Headers
	Claims    Claims
	Signature string
}