A Library for Signing, Verifying and Decoding Authentication Tokens
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
Lucas Hinderberger 06da5668c9 Migration to Codeberg 6 months ago
.gitignore Initial Commit 10 months ago
LICENSE.txt Initial Commit 10 months ago
README.md Migration to Codeberg 6 months ago
RELEASES.md Migration to Codeberg 6 months ago
authority_test.go Renamed error prefixes 6 months ago
error.go Renamed error prefixes 6 months ago
go.mod Migration to Codeberg 6 months ago
go.sum Wrote unit tests 10 months ago
json.go Renamed error prefixes 6 months ago
json_test.go Renamed error prefixes 6 months ago
library.go Fixed an outdated documentation comment 6 months ago
sign.go Renamed error prefixes 6 months ago
sign_test.go Renamed error prefixes 6 months ago
testhelpers_test.go Large-Scale API Refactoring 8 months ago
time.go Large-Scale API Refactoring 8 months ago
verifydecode.go Renamed error prefixes 6 months ago
verifydecode_test.go Renamed error prefixes 6 months ago

README.md

KISStokens

A Library for Signing, Verifying and Decoding Authentication Tokens

Summary

KISStokens is a Go library that implements a practical subset of the JSON Web Signature (JWS, RFC7515) and JSON Web Token (JWT, RFC7519) standards to provide a simple, straightforward means of signing, verifying and decoding authentication tokens in common use cases.

KISStokens aims to abstract away the details of encoding and signing of authentication tokens using reasonable defaults and to let you simply sign and verify an arbitrary set of claims. To achieve that, KISStokens internally uses JWS/JWT for encoding with HMAC-SHA256 for signing only. Unlike standard JWT, KISStokens requires tokens to always have the "Issued At" and "Expiration Time" fields set, and it forbids the use of the "none" signing algorithm (and any signing algorithm other than HS256).

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

Setup

KISStokens are signed and verified by a TokenAuthority object. A TokenAuthority is an object that holds key and configuration for signing and verifying KISStokens.

import "codeberg.org/lhinderberger/KISStokens"

...

// Set secretKey to an at least 32 bytes long key, generated from a cryptographically secure random generator
secretKey := []byte{...}
tokenLifetime := 30 * time.Minute

authority, err := KISStokens.NewTokenAuthority(secretKey, tokenLifetime)

// Check for error

Issuing a KISStoken

To issue and sign a KISStoken, call the Sign method of the TokenAuthority:

// You can pass arbitrary claims into your payload map (as long as they can be serialized into JSON)
// The Claims type stands for map[string]interface{}
payload := KISStokens.Claims {
	"sub": "example@lhinderberger.com",
}

token, err := authority.Sign(payload)

// Unless an error was returned, token should now be a KISStokens.Token object
// containing, amongst other information, a string holding the encoded and
// signed authentication token

Verifying a KISStoken

To verify a received KISStoken, call the DecodeAndVerify method of the TokenAuthority:

// This is how a typical encoded KISStoken looks like
token := "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE2MTIwNjIxNDIsImV4cCI6NDEwMjQ0NDc5OSwic3ViIjoibWFpbEBsaGluZGVyYmVyZ2VyLmNvbSJ9.cZR9zkgNP7YHFzXrLVR20BZxfToeradH5CJdTh12yuI"

decoded, err := authority.DecodeAndVerify(token)

// If token was a valid authentication token for the given TokenAuthority,
// decoded now contains a KISStokens.Token object,
// containing, amongst other information, the token's claims

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.

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