An implementation of JOSE standards (JWE, JWS, JWT) in Go
Go Perl
Latest commit 50df5ca Nov 22, 2016 @csstaub csstaub Merge branch 'cs/test-fix'
Permalink
Failed to load latest commit information.
cipher Use uint64 for all size calculations, size checks Sep 3, 2016
jose-util Fix expand in jose-util Aug 31, 2016
json use Fatalf Aug 22, 2016
.gitcookies.sh.enc Use .gitcookies to get around rate-limiting Mar 21, 2016
.gitignore Ignore *.cov files in git Feb 18, 2015
.travis.yml Use proper pip incantation Nov 22, 2016
BUG-BOUNTY.md Fix bug bounty link May 11, 2015
CONTRIBUTING.md Initial commit Dec 19, 2014
LICENSE Initial commit Dec 19, 2014
README.md Update README with info about v2 Oct 27, 2016
asymmetric.go Add a couple of extra sanity checks, improve doc comment Aug 31, 2016
asymmetric_test.go Check algorithm in ecEncrypterVerifier.verifyPayload Aug 31, 2016
crypter.go Improve multi-recipient/multi-sig handling Sep 22, 2016
crypter_test.go Improve multi-recipient/multi-sig handling Sep 22, 2016
doc.go Initial commit Dec 19, 2014
doc_test.go Update readme and package examples Mar 19, 2015
encoding.go Remove support for std_json build tag Aug 31, 2016
encoding_test.go Add test case for over-sized buffer in call to newFixedSizeBuffer Aug 18, 2015
json_fork_test.go Remove support for std_json build tag Aug 31, 2016
jwe.go Remove support for std_json build tag Aug 31, 2016
jwe_test.go Support std_json build tag Mar 10, 2016
jwk.go Reject invalid embedded public keys Sep 22, 2016
jwk_test.go Remove support for std_json build tag Aug 31, 2016
jws.go Merge pull request #112 from square/cs/reject-embed-hmac Sep 22, 2016
jws_test.go Reject invalid embedded public keys Sep 22, 2016
shared.go Address @csstaub comments Oct 8, 2015
signing.go Better docs explaining embedded JWKs Sep 23, 2016
signing_test.go Improve multi-recipient/multi-sig handling Sep 22, 2016
symmetric.go Switch to case-sensitive encoding/json fork Mar 9, 2016
symmetric_test.go Add unit test for static key generator Feb 18, 2015
utils.go Better error messages for jose-util Dec 26, 2014
utils_test.go Fix linter warnings Dec 24, 2014

README.md

Go JOSE

godoc godoc license build coverage

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.

Disclaimer: This library contains encryption software that is subject to the U.S. Export Administration Regulations. You may not export, re-export, transfer or download this code or any part of it in violation of any United States law, directive or regulation. In particular this software may not be exported or re-exported in any form or on any media to Iran, North Sudan, Syria, Cuba, or North Korea, or to denied persons or entities mentioned on any US maintained blocked list.

Overview

The implementation follows the JSON Web Encryption (RFC 7516), JSON Web Signature (RFC 7515), and JSON Web Token (RFC 7519). Tables of supported algorithms are shown below. The library supports both the compact and full 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

We use gopkg.in for versioning.

Version 1 is the old stable version:

import "gopkg.in/square/go-jose.v1"

Version 2 is for new development:

import "gopkg.in/square/go-jose.v2"

The interface for go-jose.v1 will remain backwards compatible. No new feature development will take place on the v1 branch, however bug fixes and security fixes will be backported.

The interface for go-jose.v2 is mostly stable, but we suggest pinning to a particular revision for now as we still reserve the right to make changes. New feature development happens on this branch.

New in go-jose.v2 is a jwt sub-package contributed by @shaxbee.

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-ES1
Direct encryption dir1

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
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
AES, HMAC []byte

Examples

godoc godoc

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.