incorruptible

package module
v0.0.0-...-9d6a5ee Latest Latest
Warning

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

 Go to latest Published: Jul 15, 2024 License: MIT Imports: 18 Imported by: 2

README

🍸 Incorruptible       GoDoc Go Report Card

The Incorruptible project provides a safer, shorter and faster Bearer Token for session cookie and Authorization HTTP header. See the limitations.

Incorruptible is also a 🍸 drink that the Garçon de café likes to serve to clients. See the origin of the name.

logo

🎯 Target

  • Safer: State-of-the-art cipher configuration, including expiration time and client IP, shuffled BasE91 alphabet, random padding and salt.

  • Shorter: BasE91 encoded (shorter than Base64), optimized data encoding (no string keys) and adaptive compression. The smallest token is 27 bytes long at default settings.

  • Faster: AES-128 (no RSA), hardwired encryption (AMD/Intel processors) and CPU-friendly serializer.

👶 Motivation

At Teal.Finance, our cookies were based on JWT and gorilla/session. The JWT is well standardized. We use the usual way: JSON, Base64, RSA, HMAC-SHA256… This is not very fast and generates large tokens: the long JSON string is converted into Base64 text, to which the signature stuff is appended.

With the purpose of the session cookie purpose, we are free to innovate. We love challenges. As a hobby we tried to replace gorilla/session. The result is Incorruptible. 🎉

To make the implementation successful, we updated our security knowledge to the latest research. We also benchmarked Base64/Ascii85/BasE91/Base92 encoders. We think we did a good job, with a good tradeoff between security, performance and low bandwidth.

🤫 Usage

Now we use less JWT and more Incorruptible tokens in production:

  • JWT as authentication provided by the Quid server (trusted third party).
  • Incorruptible as a session token (session cookie).
JWT

The JWT is well suited when multiple servers manage the authentication: It avoids sharing the private key. We use the good old RSA with a 32-bytes key (256 bits). The Auth server is the only one that owns the private key. Thus, the backend manages the user login, since the signature provided by the authentication server is sufficient. So our backend can be moderately secure (no user data). Only the authentication server requires high security (for example, we uninstall the SSH daemon on the machine).

Incorruptible

We use Incorruptible when the backend manages alone its relationship with the frontend alone. The secret is known only to the backend (it does not need to be shared).

🔐 Encryption

The current trend towards symmetric encryption prefers ChaCha20 / Poly1305 (server-side). In addition to its cryptographic qualities, ChaCha20 is easy to configure and requires few CPU/memory resources (chosen by Wireguard).

On the other hand, AES is faster on AMD/Intel processors (optimized instructions). In addition, the Go crypto allows easy and secure AES configuration.

Therefore, Incorruptible supports both ciphers:

  • ChaCha20-Poly1305
  • AES-128 (256 bits is not relevant for fast short cookie)

We place more emphasis on mastering the encryption configuration than on performance. See also https://go.dev/blog/tls-cipher-suites.

The encryption depends only on standard Go library. The package "math/rand" is used when a strong random number generator is not required ("math/rand" is 40 times faster than "crypto/rand"). The user may call rand.Seed() to randomize the "math/rand" generator.

Read more about our security design.

Please share your thoughts on security or other topics.

🍪 Encoding format

Serialization has been designed for the Incorruptible needs. The format consists of:

  • Magic Code (1 byte)
  • Random salt (1 byte)
  • Header bits (1 byte)
  • Expiration time (from 0 to 4 bytes)
  • Client IP (0, 4 or 16 bytes)
  • Conveyed values, up to 31 values (from 0 to 7900 bytes)
  • Optional random padding (padding length is also random)

See also https://pkg.go.dev/github.com/teal-finance/incorruptible/format.

The precision of the expiration time is defined at build time with constants in the source code. The default encoding size is 24 bits, giving a range of 10 years with an accuracy of 20 seconds. The configuration constants allow to easily decrease/increase of the storage from 1 to 4 bytes, reducing/improving the timing precision.

Random padding can also be appended. This feature is currently disabled, but can be enabled in the source code.

If the token is too long, its payload is compressed with Snappy S2.

Then, the entire data bytes are encrypted with AES-GCM 128 bits. This encryption adds 28 bytes: 12 bytes for the nonce, and 16 bytes for the GCM tag including the authentication. We may split the nonce and trim the GCM tag in a future release… Please share your thoughts.

Finally, the cipher-text is encoded with BasE91, which produces cookie-friendly tokens at the cost of increasing the size by 19% (³⁄₁₆). In comparison, Base64 and Ascii85 increase the size by 33% and 25%, respectively.

In the end, the minimum required 3 bytes (Magic+Salt+Header) becomes a 42-bytes long Incorruptible token (BasE91).

🚫 Limitations

Incorruptible works perfectly with a single server. Secrets can be stored in a data vault, or randomly generated at startup time.

However, with multiple servers (load-balancer, authentication server) the encryption key must be shared.

In this last case, JWT/CWT are preferable, since sharing secrets is a weak link in the security chain.

See also Quid, a JWT authentication server with public-key verified signatures.

🍸 Name

The name Incorruptible comes from the incorruptible drink, a mocktail with lemonade, grapefruit, and orange juice.

The Incorruptible project was originally implemented as part of the Teal.Finance/Garcon server. In French, "Garcon" (garçon) is a 💁‍♂️ waiter, who serves drinks to clients. 😉

We wanted a name for a drink without alcohol, that uses a single word, and could be understood in different languages. So Incorruptible was our best choice at that time.

✨ Contributions welcome

This new project needs your help to get better. Please suggest your improvements or even further refactoring.

We welcome contributions in many forms, and there is always plenty to do!

🗣️ Feedback

If you have some suggestions or need a new feature, please open an issue or contact us at Teal.Finance@pm.me / @TealFinance.

Feel free to pull a request too. Your contributions are welcome. 😉

Copyright (c) 2022 Teal.Finance/incorruptible contributors

Teal.Finance/incorruptible is free software, and may be redistributed and/or modified under the terms of the MIT License. SPDX-License-Identifier: MIT

Teal.Finance/incorruptible is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

See the LICENSE file (alongside the source files) or https://opensource.org/licenses/MIT.

Documentation

Overview

Package incorruptible provides a safer, shorter, faster secret token for session cookie and Authorization HTTP header.

Index

Constants

View Source 
const (
	HeaderSize = magicCodeSize + saltSize + metadataSize

	MaxValues int = maskNValues
)
View Source 
const (
	// The expiry is stored in 3 bytes, with a 30 seconds precision, starting from 2022.
	ExpiryStartYear = 2022
	ExpiryMaxYear   = ExpiryStartYear + rangeInYears

	ExpirySize = 3 // 24 bits = 10 years with 20-second precision

	PrecisionInSeconds = 20
)
View Source 
const (
	HTTP  = "http"
	HTTPS = "https"
)

URL schemes.

View Source 
const (
	// Base91MinSize and ciphertextMinSize need to be adapted according
	// on any change about expiry encoding size, padding size...
	Base91MinSize = 42
)
View Source 
const (
	EnablePadding = false
)

Variables

This section is empty.

Functions

func AppendIP 

func AppendIP(buf []byte, ip net.IP) []byte

func BytesToUint64 

func BytesToUint64(buf []byte) (uint64, error)

func DecodeExpiry 

func DecodeExpiry(buf []byte) ([]byte, int64)

func Decrypt 

func Decrypt(aead cipher.AEAD, all []byte) (plaintext []byte, err error)

Decrypt decrypts the ciphertext using any AEAD cipher. The parameter "all" contains the nonce + the ciphertext + the potential GCM tag. in the format "nonce|ciphertext|tag" where '|' indicates concatenation.

func Encrypt 

func Encrypt(aead cipher.AEAD, plaintext []byte) []byte

Encrypt encrypts data using the given cipher. Output takes the form "nonce|ciphertext|tag" where '|' indicates concatenation.

"math/rand" is 40 times faster than "crypto/rand" see: https://github.com/SimonWaldherr/golang-benchmarks#random

func MagicCode 

func MagicCode(buf []byte) uint8

func Marshal 

func Marshal(tv TValues, magic uint8) ([]byte, error)

Marshal serializes a TValues in a short way. The format starts with a magic code (2 bytes), followed by the expiry time, the client IP, the user-defined values, and ends with random salt as padding for a final size aligned on 32 bits.

func NewAESCipher 

func NewAESCipher(secretKey []byte) cipher.AEAD

NewAESCipher creates a cipher with Encrypt() and Decrypt() functions for AEAD (Authenticated Encryption with Associated Data).

Implementation is based on: - https://en.wikipedia.org/wiki/Authenticated_encryption - https://go.dev/blog/tls-cipher-suites - https://github.com/gtank/cryptopasta

The underlying algorithm is AES-128 GCM: - AES is a symmetric encryption, faster than asymmetric (e.g. RSA) - 128-bit key is sufficient for most usages (256-bits is much slower)

Assumption design: This function should be used on AES-supported hardware like AMD/Intel processors providing optimized AES instructions set. If this is not your case, please use NewChaChaCipher().

GCM (Galois Counter Mode) is preferred over CBC (Cipher Block Chaining) because of CBC-specific attacks and configuration difficulties. But, CBC is faster and does not have any weakness in our server-side use case. If requested, this implementation may change to use CBC. Your feedback or suggestions are welcome, please contact us.

This package follows the Golang Cryptography Principles: https://golang.org/design/cryptography-principles Secure implementation, faultlessly configurable, performant and state-of-the-art updated.

func NewChaCipher 

func NewChaCipher(secretKey []byte) cipher.AEAD

NewChaCipher creates a cipher for ChaCha20-Poly1305. with Encrypt() and Decrypt() functions.

func NewCipher 

func NewCipher(secretKey []byte) cipher.AEAD

func PutExpiry 

func PutExpiry(buf []byte, unix int64) error

func Uint64ToBytes 

func Uint64ToBytes(v uint64) []byte

Uint64ToBytes works on the byte-level encoding of the Incorruptible token.

Types

type Incorruptible 

type Incorruptible struct {
	SetIP bool // If true => put the remote IP in the token.
	// contains filtered or unexported fields
}

func New 

func New(writeErr WriteErr, urls []*url.URL, secretKey []byte, cookieName string, maxAge int, setIP bool) *Incorruptible

New creates a new Incorruptible. The order of the parameters are consistent with garcon.NewJWTChecker (see Teal-Finance/Garcon). The Garcon middleware constructors use a garcon.Writer as first parameter. Please share your thoughts/feedback, we can still change that.

func (*Incorruptible) BearerToken 

func (incorr *Incorruptible) BearerToken(r *http.Request) (string, error)

BearerToken returns the token (in base91 format) from the HTTP Authorization header.

func (*Incorruptible) Chk 

func (incorr *Incorruptible) Chk(next http.Handler) http.Handler

Chk is a middleware accepting requests only if it has a valid Incorruptible cookie, Chk does not consider the "Authorization" header (only the token within the cookie). Use instead the Vet() middleware to also verify the "Authorization" header. Chk finally stores the decoded token in the request context. In dev. mode, Chk accepts requests without valid cookie but does not store invalid tokens.

func (*Incorruptible) Cookie 

func (incorr *Incorruptible) Cookie(_ int) *http.Cookie

Cookie returns a pointer to the default cookie values. This can be used to customize some cookie values (may break), and also to facilitate testing.

func (*Incorruptible) CookieName 

func (incorr *Incorruptible) CookieName() string

func (*Incorruptible) CookieToken 

func (incorr *Incorruptible) CookieToken(r *http.Request) (string, error)

CookieToken returns the token (in base91 format) from the cookie.

func (*Incorruptible) DeadCookie 

func (incorr *Incorruptible) DeadCookie() *http.Cookie

DeadCookie returns an Incorruptible cookie without Value and with "Max-Age=0" in order to delete the Incorruptible cookie in the current HTTP session.

Example: 

func logout(w http.ResponseWriter, r *http.Request) {
    http.SetCookie(w, Incorruptible.DeadCookie())
}

func (*Incorruptible) Decode 

func (incorr *Incorruptible) Decode(base91 string) (TValues, error)

func (*Incorruptible) DecodeBearerToken 

func (incorr *Incorruptible) DecodeBearerToken(r *http.Request) (TValues, error)

func (*Incorruptible) DecodeCookieToken 

func (incorr *Incorruptible) DecodeCookieToken(r *http.Request) (TValues, error)

func (*Incorruptible) DecodeToken 

func (incorr *Incorruptible) DecodeToken(r *http.Request) (TValues, []any)

func (*Incorruptible) Encode 

func (incorr *Incorruptible) Encode(tv TValues) (string, error)

func (*Incorruptible) NewCookie 

func (incorr *Incorruptible) NewCookie(r *http.Request, keyValues ...KVal) (*http.Cookie, TValues, error)

NewCookie creates a new cookie based on default values. the HTTP request parameter is used to get the remote IP (only when incorr.SetIP is true).

func (*Incorruptible) NewCookieFromToken 

func (incorr *Incorruptible) NewCookieFromToken(token string, maxAge int) *http.Cookie

func (*Incorruptible) NewCookieFromValues 

func (incorr *Incorruptible) NewCookieFromValues(tv TValues) (*http.Cookie, error)

func (*Incorruptible) NewTValues 

func (incorr *Incorruptible) NewTValues(r *http.Request, keyValues ...KVal) (TValues, error)

func (*Incorruptible) Set 

func (incorr *Incorruptible) Set(next http.Handler) http.Handler

Set is a middleware putting a "session" cookie when the request has no valid "incorruptible" token. The token is searched in the "session" cookie and in the first "Authorization" header. The "session" cookie (that is added in the response) contains a minimalist "incorruptible" token. Finally, Set stores the decoded token in the request context.

func (*Incorruptible) Vet 

func (incorr *Incorruptible) Vet(next http.Handler) http.Handler

Vet is a middleware accepting requests having a valid Incorruptible token either in the cookie or in the first "Authorization" header. Vet finally stores the decoded token in the request context. In dev. mode, Vet accepts requests without a valid token but does not store invalid tokens.

type KBool 

type KBool struct {
	Key int
	Val bool
}

func Bool 

func Bool(k int, v ...bool) KBool

func (KBool) Bool 

func (kv KBool) Bool() bool

func (KBool) Get 

func (kv KBool) Get(tv *TValues) (KVal, error)

func (KBool) Int64 

func (kv KBool) Int64() int64

func (KBool) Set 

func (kv KBool) Set(tv *TValues) error

func (KBool) String 

func (kv KBool) String() string

func (KBool) Uint64 

func (kv KBool) Uint64() uint64

type KInt64 

type KInt64 struct {
	Key int
	Val int64
}

func Int64 

func Int64(k int, v ...int64) KInt64

func (KInt64) Bool 

func (kv KInt64) Bool() bool

func (KInt64) Get 

func (kv KInt64) Get(tv *TValues) (KVal, error)

func (KInt64) Int64 

func (kv KInt64) Int64() int64

func (KInt64) Set 

func (kv KInt64) Set(tv *TValues) error

func (KInt64) String 

func (kv KInt64) String() string

func (KInt64) Uint64 

func (kv KInt64) Uint64() uint64

type KString 

type KString struct {
	Key int
	Val string
}

func String 

func String(k int, v ...string) KString

func (KString) Bool 

func (kv KString) Bool() bool

func (KString) Get 

func (kv KString) Get(tv *TValues) (KVal, error)

func (KString) Int64 

func (kv KString) Int64() int64

func (KString) Set 

func (kv KString) Set(tv *TValues) error

func (KString) String 

func (kv KString) String() string

func (KString) Uint64 

func (kv KString) Uint64() uint64

type KUint64 

type KUint64 struct {
	Key int
	Val uint64
}

func Uint64 

func Uint64(k int, v ...uint64) KUint64

func (KUint64) Bool 

func (kv KUint64) Bool() bool

func (KUint64) Get 

func (kv KUint64) Get(tv *TValues) (KVal, error)

func (KUint64) Int64 

func (kv KUint64) Int64() int64

func (KUint64) Set 

func (kv KUint64) Set(tv *TValues) error

func (KUint64) String 

func (kv KUint64) String() string

func (KUint64) Uint64 

func (kv KUint64) Uint64() uint64

type KVal 

type KVal interface {
	Set(*TValues) error
	Get(*TValues) (KVal, error)
	Uint64() uint64
	Int64() int64
	Bool() bool
	String() string
}

type Metadata 

type Metadata byte

func GetMetadata 

func GetMetadata(buf []byte) Metadata

func NewMetadata 

func NewMetadata(ipLength int, compressed bool, nValues int) (Metadata, error)

NewMetadata sets the metadata bits within the token.

func (Metadata) DecodeIP 

func (meta Metadata) DecodeIP(buf []byte) ([]byte, net.IP)

func (Metadata) IsCompressed 

func (meta Metadata) IsCompressed() bool

func (Metadata) NValues 

func (meta Metadata) NValues() int

func (Metadata) PayloadMinSize 

func (meta Metadata) PayloadMinSize() int

func (Metadata) PutHeader 

func (meta Metadata) PutHeader(buf []byte, magic uint8)

PutHeader fills the magic code, the salt and the metadata.

"math/rand" is 40 times faster than "crypto/rand" see: https://github.com/SimonWaldherr/golang-benchmarks#random

type Serializer 

type Serializer struct {
	// contains filtered or unexported fields
}

type TValues 

type TValues struct {
	Expires int64  // Unix time UTC (seconds since 1970)
	IP      net.IP // TOTO: use netip.Addr
	Values  [][]byte
}

TValues (Token Values) represents the decoded form of an Incorruptible token.

func EmptyTValues 

func EmptyTValues() TValues

EmptyTValues returns an empty TValues that can be used to generate a minimalist token.

func FromCtx 

func FromCtx(r *http.Request) (TValues, bool)

FromCtx gets the decoded token from the request context.

func NewTValues 

func NewTValues(keyValues ...KVal) (TValues, error)

NewTValues returns an empty TValues that can be used to generate a minimalist token.

func Unmarshal 

func Unmarshal(buf []byte) (TValues, error)

func (TValues) Bool 

func (tv TValues) Bool(key int) (bool, error)

func (TValues) BoolIfAny 

func (tv TValues) BoolIfAny(key int, defaultValue ...bool) bool

func (TValues) CompareExpiry 

func (tv TValues) CompareExpiry() int

func (*TValues) EmptyIP 

func (tv *TValues) EmptyIP()

func (TValues) ExpiryTime 

func (tv TValues) ExpiryTime() time.Time

func (*TValues) Get 

func (tv *TValues) Get(keyValues ...KVal) ([]KVal, error)

func (TValues) Int64 

func (tv TValues) Int64(key int) (int64, error)

func (TValues) Int64IfAny 

func (tv TValues) Int64IfAny(key int, defaultValue ...int64) int64

func (TValues) KBool 

func (tv TValues) KBool(k int, v ...bool) KBool

func (TValues) KInt64 

func (tv TValues) KInt64(k int, v ...int64) KInt64

func (TValues) KString 

func (tv TValues) KString(k int, v ...string) KString

func (TValues) KUint64 

func (tv TValues) KUint64(k int, v ...uint64) KUint64

func (TValues) MaxAge 

func (tv TValues) MaxAge() int

func (TValues) NoIP 

func (tv TValues) NoIP() bool

NoIP returns true when no IP is set within the TValues. NoIP returns false when an IP is present.

func (*TValues) Set 

func (tv *TValues) Set(keyValues ...KVal) error

func (*TValues) SetBool 

func (tv *TValues) SetBool(key int, val bool) error

func (*TValues) SetExpiry 

func (tv *TValues) SetExpiry(maxAge int)

func (*TValues) SetExpiryDuration 

func (tv *TValues) SetExpiryDuration(d time.Duration)

func (*TValues) SetExpiryTime 

func (tv *TValues) SetExpiryTime(t time.Time)

func (*TValues) SetInt64 

func (tv *TValues) SetInt64(key int, val int64) error

func (*TValues) SetRemoteIP 

func (tv *TValues) SetRemoteIP(r *http.Request) error

func (*TValues) SetString 

func (tv *TValues) SetString(key int, val string) error

func (*TValues) SetUint64 

func (tv *TValues) SetUint64(key int, val uint64) error

func (*TValues) ShortenIP4Length 

func (tv *TValues) ShortenIP4Length()

func (TValues) String 

func (tv TValues) String(key int) (string, error)

func (TValues) StringIfAny 

func (tv TValues) StringIfAny(key int, defaultValue ...string) string

func (TValues) ToCtx 

func (tv TValues) ToCtx(r *http.Request) *http.Request

ToCtx stores the decoded token in the request context.

func (TValues) Uint64 

func (tv TValues) Uint64(key int) (uint64, error)

func (TValues) Uint64IfAny 

func (tv TValues) Uint64IfAny(key int, defaultValue ...uint64) uint64

func (TValues) Valid 

func (tv TValues) Valid(r *http.Request) error

func (TValues) ValidExpiry 

func (tv TValues) ValidExpiry() bool

func (TValues) ValidIP 

func (tv TValues) ValidIP(r *http.Request) error

type WriteErr 

type WriteErr func(w http.ResponseWriter, r *http.Request, statusCode int, messages ...any)

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.