1# Go JOSE 2 3[![godoc](http://img.shields.io/badge/godoc-version_1-blue.svg?style=flat)](https://godoc.org/gopkg.in/square/go-jose.v1) 4[![godoc](http://img.shields.io/badge/godoc-version_2-blue.svg?style=flat)](https://godoc.org/gopkg.in/square/go-jose.v2) 5[![license](http://img.shields.io/badge/license-apache_2.0-blue.svg?style=flat)](https://raw.githubusercontent.com/square/go-jose/master/LICENSE) 6[![build](https://travis-ci.org/square/go-jose.svg?branch=v2)](https://travis-ci.org/square/go-jose) 7[![coverage](https://coveralls.io/repos/github/square/go-jose/badge.svg?branch=v2)](https://coveralls.io/r/square/go-jose) 8 9Package jose aims to provide an implementation of the Javascript Object Signing 10and Encryption set of standards. This includes support for JSON Web Encryption, 11JSON Web Signature, and JSON Web Token standards. 12 13**Disclaimer**: This library contains encryption software that is subject to 14the U.S. Export Administration Regulations. You may not export, re-export, 15transfer or download this code or any part of it in violation of any United 16States law, directive or regulation. In particular this software may not be 17exported or re-exported in any form or on any media to Iran, North Sudan, 18Syria, Cuba, or North Korea, or to denied persons or entities mentioned on any 19US maintained blocked list. 20 21## Overview 22 23The implementation follows the 24[JSON Web Encryption](http://dx.doi.org/10.17487/RFC7516) (RFC 7516), 25[JSON Web Signature](http://dx.doi.org/10.17487/RFC7515) (RFC 7515), and 26[JSON Web Token](http://dx.doi.org/10.17487/RFC7519) (RFC 7519). 27Tables of supported algorithms are shown below. The library supports both 28the compact and full serialization formats, and has optional support for 29multiple recipients. It also comes with a small command-line utility 30([`jose-util`](https://github.com/square/go-jose/tree/v2/jose-util)) 31for dealing with JOSE messages in a shell. 32 33**Note**: We use a forked version of the `encoding/json` package from the Go 34standard library which uses case-sensitive matching for member names (instead 35of [case-insensitive matching](https://www.ietf.org/mail-archive/web/json/current/msg03763.html)). 36This is to avoid differences in interpretation of messages between go-jose and 37libraries in other languages. 38 39### Versions 40 41We use [gopkg.in](https://gopkg.in) for versioning. 42 43[Version 2](https://gopkg.in/square/go-jose.v2) 44([branch](https://github.com/square/go-jose/tree/v2), 45[doc](https://godoc.org/gopkg.in/square/go-jose.v2)) is the current version: 46 47 import "gopkg.in/square/go-jose.v2" 48 49The old `v1` branch ([go-jose.v1](https://gopkg.in/square/go-jose.v1)) will 50still receive backported bug fixes and security fixes, but otherwise 51development is frozen. All new feature development takes place on the `v2` 52branch. Version 2 also contains additional sub-packages such as the 53[jwt](https://godoc.org/gopkg.in/square/go-jose.v2/jwt) implementation 54contributed by [@shaxbee](https://github.com/shaxbee). 55 56### Supported algorithms 57 58See below for a table of supported algorithms. Algorithm identifiers match 59the names in the [JSON Web Algorithms](http://dx.doi.org/10.17487/RFC7518) 60standard where possible. The Godoc reference has a list of constants. 61 62 Key encryption | Algorithm identifier(s) 63 :------------------------- | :------------------------------ 64 RSA-PKCS#1v1.5 | RSA1_5 65 RSA-OAEP | RSA-OAEP, RSA-OAEP-256 66 AES key wrap | A128KW, A192KW, A256KW 67 AES-GCM key wrap | A128GCMKW, A192GCMKW, A256GCMKW 68 ECDH-ES + AES key wrap | ECDH-ES+A128KW, ECDH-ES+A192KW, ECDH-ES+A256KW 69 ECDH-ES (direct) | ECDH-ES<sup>1</sup> 70 Direct encryption | dir<sup>1</sup> 71 72<sup>1. Not supported in multi-recipient mode</sup> 73 74 Signing / MAC | Algorithm identifier(s) 75 :------------------------- | :------------------------------ 76 RSASSA-PKCS#1v1.5 | RS256, RS384, RS512 77 RSASSA-PSS | PS256, PS384, PS512 78 HMAC | HS256, HS384, HS512 79 ECDSA | ES256, ES384, ES512 80 Ed25519 | EdDSA<sup>2</sup> 81 82<sup>2. Only available in version 2 of the package</sup> 83 84 Content encryption | Algorithm identifier(s) 85 :------------------------- | :------------------------------ 86 AES-CBC+HMAC | A128CBC-HS256, A192CBC-HS384, A256CBC-HS512 87 AES-GCM | A128GCM, A192GCM, A256GCM 88 89 Compression | Algorithm identifiers(s) 90 :------------------------- | ------------------------------- 91 DEFLATE (RFC 1951) | DEF 92 93### Supported key types 94 95See below for a table of supported key types. These are understood by the 96library, and can be passed to corresponding functions such as `NewEncrypter` or 97`NewSigner`. Each of these keys can also be wrapped in a JWK if desired, which 98allows attaching a key id. 99 100 Algorithm(s) | Corresponding types 101 :------------------------- | ------------------------------- 102 RSA | *[rsa.PublicKey](http://golang.org/pkg/crypto/rsa/#PublicKey), *[rsa.PrivateKey](http://golang.org/pkg/crypto/rsa/#PrivateKey) 103 ECDH, ECDSA | *[ecdsa.PublicKey](http://golang.org/pkg/crypto/ecdsa/#PublicKey), *[ecdsa.PrivateKey](http://golang.org/pkg/crypto/ecdsa/#PrivateKey) 104 EdDSA<sup>1</sup> | [ed25519.PublicKey](https://godoc.org/golang.org/x/crypto/ed25519#PublicKey), [ed25519.PrivateKey](https://godoc.org/golang.org/x/crypto/ed25519#PrivateKey) 105 AES, HMAC | []byte 106 107<sup>1. Only available in version 2 of the package</sup> 108 109## Examples 110 111[![godoc](http://img.shields.io/badge/godoc-version_1-blue.svg?style=flat)](https://godoc.org/gopkg.in/square/go-jose.v1) 112[![godoc](http://img.shields.io/badge/godoc-version_2-blue.svg?style=flat)](https://godoc.org/gopkg.in/square/go-jose.v2) 113 114Examples can be found in the Godoc 115reference for this package. The 116[`jose-util`](https://github.com/square/go-jose/tree/v2/jose-util) 117subdirectory also contains a small command-line utility which might be useful 118as an example. 119