Go JOSE

Package jose aims to provide an implementation of the Javascript Object Signing and Encryption set of standards. This includes support for JSON Web Encryption, JSON Web Signature, and JSON Web Token standards.

Overview

The implementation follows the JSON Web Encryption (RFC 7516), JSON Web Signature (RFC 7515), and JSON Web Token (RFC 7519) specifications. Tables of supported algorithms are shown below. The library supports both the compact and JWS/JWE JSON Serialization formats, and has optional support for multiple recipients. It also comes with a small command-line utility (jose-util) for dealing with JOSE messages in a shell.

Note: We use a forked version of the encoding/json package from the Go standard library which uses case-sensitive matching for member names (instead of case-insensitive matching). This is to avoid differences in interpretation of messages between go-jose and libraries in other languages.

Versions

Version 4 (branch, doc, releases) is the current stable version:

import "github.com/go-jose/go-jose/v4"

The old square/go-jose repo contains the prior v1 and v2 versions, which are still useable but not actively developed anymore.

Version 3, in this repo, is still receiving security fixes but not functionality updates.

Supported algorithms

See below for a table of supported algorithms. Algorithm identifiers match the names in the JSON Web Algorithms standard where possible. The Godoc reference has a list of constants.

Key encryption	Algorithm identifier(s)
RSA-PKCS#1v1.5	RSA1_5
RSA-OAEP	RSA-OAEP, RSA-OAEP-256
AES key wrap	A128KW, A192KW, A256KW
AES-GCM key wrap	A128GCMKW, A192GCMKW, A256GCMKW
ECDH-ES + AES key wrap	ECDH-ES+A128KW, ECDH-ES+A192KW, ECDH-ES+A256KW
ECDH-ES (direct)	ECDH-ES¹
Direct encryption	dir¹

^{1. Not supported in multi-recipient mode}

Signing / MAC	Algorithm identifier(s)
RSASSA-PKCS#1v1.5	RS256, RS384, RS512
RSASSA-PSS	PS256, PS384, PS512
HMAC	HS256, HS384, HS512
ECDSA	ES256, ES384, ES512
Ed25519	EdDSA²

^{2. Only available in version 2 of the package}

Content encryption	Algorithm identifier(s)
AES-CBC+HMAC	A128CBC-HS256, A192CBC-HS384, A256CBC-HS512
AES-GCM	A128GCM, A192GCM, A256GCM

Compression	Algorithm identifiers(s)
DEFLATE (RFC 1951)	DEF

Supported key types

See below for a table of supported key types. These are understood by the library, and can be passed to corresponding functions such as NewEncrypter or NewSigner. Each of these keys can also be wrapped in a JWK if desired, which allows attaching a key id.

Algorithm(s)	Corresponding types
RSA	rsa.PublicKey, rsa.PrivateKey
ECDH, ECDSA	ecdsa.PublicKey, ecdsa.PrivateKey
EdDSA¹	ed25519.PublicKey, ed25519.PrivateKey
AES, HMAC	[]byte

^{1. Only available in version 2 or later of the package}

Examples

Examples can be found in the Godoc reference for this package. The jose-util subdirectory also contains a small command-line utility which might be useful as an example as well.