KISStokens

README

KISStokens

A Library for Signing, Verifying and Decoding JWS/JWT Authentication Tokens

Summary

KISStokens is a Go library for signing, verifying and decoding authentication tokens following the JSON Web Signature (JWS, RFC7515) and JSON Web Token (JWT, RFC7519) standards.

KISStokens offers both a high-level and a low-level API. While the high-level API aims to be easily usable from within applications, offering implementations with reasonable defaults for common use cases, the low-level API offers a more direct representation of the JWS and JWT standards, for use cases in which more control is needed.

Status

KISStokens is currently in the 0.x version range.

It can be used for experimental and testing purposes. Although this library is built with robustness and security in mind, its use in production is expressly discouraged until v1.0.0.

Make sure you have read and understood the library's license (see LICENCE file), especially the sections "Disclaimer of Warranty" and "Limitation of Liability", before using the library.

Usage

Reference Documentation

Reference documentation can be found at pkg.go.dev

Installation

Install KISStokens by running the following:

go get codeberg.org/lhinderberger/KISStokens

High-Level API

For common use cases, it is recommended to use the opinionated high-level API, which can be found in the opinionated sub-package.

Import is using:

import "codeberg.org/lhinderberger/KISStokens/opinionated"

Then build a token authority, an object holding key and configuration for signing and verifying authentication tokens, like this:

authority, err := opinionated.NewTokenAuthority(secretKey)

Using the token authority, you can then sign tokens like this:

encodedToken, err := authority.Sign(&claims) // With claims being an jwt.Claims struct

Or decode and verify a token like this:

claims, err := authority.DecodeAndVerify(token)

Low-level API

While the high-level API provides an easy interface and reasonable defaults for common use cases, there are times when you need more control about your tokens.

For this, KISStokens exposes a low-level API in its jws and jwt packages. These packages map fairly closely to the relevant parts of the RFC7515 and RFC7519 standards. They for example allow you to precisely control the contents of your JWS tokens and to manipulate the JOSE Header.

For details about the low-level API, pleae refer to the reference documentation at pkg.go.dev.

Dependencies

KISStokens is designed to have no run-time dependencies, other than Go's standard library.

Thus, the dependencies in go.mod / go.sum are testing dependencies and can be omitted when redistributing an application that uses KISStokens.

Versioning and Compatibility

Versioning of KISStokens follows the Semantic Versioning convention.

KISStokens keeps a changelog in RELEASES.md

Until 1.0.0, any substantial changes to the library (breaking and non-breaking) will trigger an increase of the minor version, while bug fixes and similar minor improvements may trigger an increase of the patch version.

Copyright

KISStokens is (C) 2021 Lucas Hinderberger

It is licensed under the Apache Licence Version 2.0. For details, please refer to the LICENCE file.

Contact

The repository of KISStokens can be found at https://codeberg.org/lhinderberger/KISStokens

You're welcome to file bug reports, other issues and pull requests there.

You can also contact the author via email at mail@lhinderberger.com

Documentation

Overview

Package KISStokens is a Go library for signing, verifying and decoding authentication tokens following the JSON Web Signature (JWS, RFC7515) and JSON Web Token (JWT, RFC7519) standards.

KISStokens offers both a high-level and a low-level API. While the high-level API aims to be easily usable from within applications, offering implementations with reasonable defaults for common use cases, the low-level API offers a more direct representation of the JWS and JWT standards, for use cases in which more control is needed.

The high-level API is contained in the top-level KISStokens package, with opinionated implementations in the subpackage opinionated. The low-level API can be found in the subpackages jws and jwt, with strictjson being a helper package for unambiguous JSON parsing.

Index

• type TokenAuthority

Types

type TokenAuthority

type TokenAuthority interface {
	// Sign produces a signed authentication token for the given set of claims.
	// Note that this function may check the given claims object against constraints defined by the
	// concrete TokenAuthority implementation, rejecting claim sets that don't meet its requirements.
	Sign(claims *jwt.Claims) (string, error)

	// DecodeAndVerify decodes and verifies an authentication token and returns its JWT claims.
	// On failure, an error describing why decoding or verification failed will be returned.
	DecodeAndVerify(encodedToken string) (*jwt.Claims, error)
}

A TokenAuthority holds key and configuration for signing and verifying authentication tokens It provides methods for signing, and decoding/verifying tokens.