jose

README

Go JOSE

Package jose aims to provide an implementation of the Javascript Object Signing and Encryption set of standards. For the moment, it mainly focuses on encryption and signing based on the JSON Web Encryption and JSON Web Signature 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 and JSON Web Signature standard drafts as of version 37. 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 encrypting/decrypting JWE messages in a shell.

Supported algorithms

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

Examples

Encryption/decryption example using RSA:

// Generate a public/private key pair to use for this example. The library
// also provides two utility functions (LoadPublicKey and LoadPrivateKey)
// that can be used to load keys from PEM/DER-encoded data.
privateKey, err := rsa.GenerateKey(rand.Reader, 2048)
if err != nil {
  panic(err)
}

// Instantiate an encrypter using RSA-OAEP with AES128-GCM. An error would
// indicate that the selected algorithm(s) are not currently supported.
publicKey := &privateKey.PublicKey
encrypter, err := NewEncrypter(RSA_OAEP, A128GCM, publicKey)
if err != nil {
  panic(err)
}

// Encrypt a sample plaintext. Calling the encrypter returns an encrypted
// JWE object, which can then be serialized for output afterwards. An error
// would indicate a problem in an underlying cryptographic primitive.
var plaintext = []byte("Lorem ipsum dolor sit amet")
object, err := encrypter.Encrypt(plaintext)
if err != nil {
  panic(err)
}

// Serialize the encrypted object using the full serialization format.
// Alternatively you can also use the compact format here by calling
// object.CompactSerialize() instead.
serialized, err := object.FullSerialize()

// Now let's instantiate a decrypter so we can get back the plaintext.
decrypter, err := NewDecrypter(privateKey)
if err != nil {
  panic(err)
}

// Parse the serialized, encrypted JWE object. An error would indicate that
// the given input did not represent a valid message.
object, err = Parse(serialized)
if err != nil {
  panic(err)
}

// Now we can decrypt and get back our original plaintext. An error here
// would indicate the the message failed to decrypt, e.g. because the auth
// tag was broken and the message was tampered with.
decrypted, err := decrypter.Decrypt(object)
if err != nil {
  panic(err)
}

fmt.Printf(string(decrypted))
// output: Lorem ipsum dolor sit amet

Signing/verification example using RSA:

// Generate a public/private key pair to use for this example. The library
// also provides two utility functions (LoadPublicKey and LoadPrivateKey)
// that can be used to load keys from PEM/DER-encoded data.
privateKey, err := rsa.GenerateKey(rand.Reader, 2048)
if err != nil {
	panic(err)
}

// Instantiate a signer using RSASSA-PSS (SHA512) with the given private key.
signer, err := NewSigner(PS512, privateKey)
if err != nil {
	panic(err)
}

// Sign a sample payload. Calling the signer returns a protected JWS object,
// which can then be serialized for output afterwards. An error would
// indicate a problem in an underlying cryptographic primitive.
var payload = []byte("Lorem ipsum dolor sit amet")
object, err := signer.Sign(payload)
if err != nil {
	panic(err)
}

// Serialize the encrypted object using the full serialization format.
// Alternatively you can also use the compact format here by calling
// object.CompactSerialize() instead.
serialized := object.FullSerialize()

// Now let's instantiate a verifier to verify the object.
publicKey := &privateKey.PublicKey
verifier, err := NewVerifier(publicKey)
if err != nil {
	panic(err)
}

// Parse the serialized, protected JWS object. An error would indicate that
// the given input did not represent a valid message.
object, err = ParseSigned(serialized)
if err != nil {
	panic(err)
}

// Now we can verify the signature on the payload. An error here would
// indicate the the message failed to verify, e.g. because the signature was
// broken or the message was tampered with.
output, err := verifier.Verify(object)
if err != nil {
	panic(err)
}

fmt.Printf(string(output))
// output: Lorem ipsum dolor sit amet

More examples can be found in the Godoc reference for this package. The jose-util subdirectory also contains a small command-line utility for encrypting/decrypting JWE messages which might be useful as an example.

Documentation

Overview

Package jose aims to provide an implementation of the Javascript Object Signing and Encryption set of standards. For the moment, it mainly focuses on encryption and signing based on the JSON Web Encryption and JSON Web Signature standards. The library supports both the compact and full serialization formats, and has optional support for multiple recipients.

Example (JWE)

// Generate a public/private key pair to use for this example. The library
// also provides two utility functions (LoadPublicKey and LoadPrivateKey)
// that can be used to load keys from PEM/DER-encoded data.
privateKey, err := rsa.GenerateKey(rand.Reader, 2048)
if err != nil {
	panic(err)
}

// Instantiate an encrypter using RSA-OAEP with AES128-GCM. An error would
// indicate that the selected algorithm(s) are not currently supported.
publicKey := &privateKey.PublicKey
encrypter, err := NewEncrypter(RSA_OAEP, A128GCM, publicKey)
if err != nil {
	panic(err)
}

// Encrypt a sample plaintext. Calling the encrypter returns an encrypted
// JWE object, which can then be serialized for output afterwards. An error
// would indicate a problem in an underlying cryptographic primitive.
var plaintext = []byte("Lorem ipsum dolor sit amet")
object, err := encrypter.Encrypt(plaintext)
if err != nil {
	panic(err)
}

// Serialize the encrypted object using the full serialization format.
// Alternatively you can also use the compact format here by calling
// object.CompactSerialize() instead.
serialized := object.FullSerialize()

// Now let's instantiate a decrypter so we can get back the plaintext.
decrypter, err := NewDecrypter(privateKey)
if err != nil {
	panic(err)
}

// Parse the serialized, encrypted JWE object. An error would indicate that
// the given input did not represent a valid message.
object, err = ParseEncrypted(serialized)
if err != nil {
	panic(err)
}

// Now we can decrypt and get back our original plaintext. An error here
// would indicate the the message failed to decrypt, e.g. because the auth
// tag was broken or the message was tampered with.
decrypted, err := decrypter.Decrypt(object)
if err != nil {
	panic(err)
}

fmt.Printf(string(decrypted))

Output:

Lorem ipsum dolor sit amet

Example (JWS)

// Generate a public/private key pair to use for this example. The library
// also provides two utility functions (LoadPublicKey and LoadPrivateKey)
// that can be used to load keys from PEM/DER-encoded data.
privateKey, err := rsa.GenerateKey(rand.Reader, 2048)
if err != nil {
	panic(err)
}

// Instantiate a signer using RSASSA-PSS (SHA512) with the given private key.
signer, err := NewSigner(PS512, privateKey)
if err != nil {
	panic(err)
}

// Sign a sample payload. Calling the signer returns a protected JWS object,
// which can then be serialized for output afterwards. An error would
// indicate a problem in an underlying cryptographic primitive.
var payload = []byte("Lorem ipsum dolor sit amet")
object, err := signer.Sign(payload)
if err != nil {
	panic(err)
}

// Serialize the encrypted object using the full serialization format.
// Alternatively you can also use the compact format here by calling
// object.CompactSerialize() instead.
serialized := object.FullSerialize()

// Now let's instantiate a verifier to verify the object.
publicKey := &privateKey.PublicKey
verifier, err := NewVerifier(publicKey)
if err != nil {
	panic(err)
}

// Parse the serialized, protected JWS object. An error would indicate that
// the given input did not represent a valid message.
object, err = ParseSigned(serialized)
if err != nil {
	panic(err)
}

// Now we can verify the signature on the payload. An error here would
// indicate the the message failed to verify, e.g. because the signature was
// broken or the message was tampered with.
output, err := verifier.Verify(object)
if err != nil {
	panic(err)
}

fmt.Printf(string(output))

Output:

Lorem ipsum dolor sit amet

Index

• Constants
• Variables
• func LoadPrivateKey(data []byte) (interface{}, error)
• func LoadPublicKey(data []byte) (interface{}, error)
• type CompressionAlgorithm
• type ContentEncryption
• type Decrypter
  • func NewDecrypter(decryptionKey interface{}) (Decrypter, error)
• type Encrypter
  • func NewEncrypter(alg KeyAlgorithm, enc ContentEncryption, encryptionKey interface{}) (Encrypter, error)
• type JweObject
  • func ParseEncrypted(input string) (*JweObject, error)
  • func (obj JweObject) CompactSerialize() (string, error)
  • func (obj JweObject) FullSerialize() string
  • func (obj JweObject) GetAuthData() []byte
• type JwsObject
  • func ParseSigned(input string) (*JwsObject, error)
  • func (obj JwsObject) CompactSerialize() (string, error)
  • func (obj JwsObject) FullSerialize() string
• type KeyAlgorithm
• type MultiEncrypter
  • func NewMultiEncrypter(enc ContentEncryption) (MultiEncrypter, error)
• type MultiSigner
  • func NewMultiSigner() MultiSigner
• type SignatureAlgorithm
• type Signer
  • func NewSigner(alg SignatureAlgorithm, signingKey interface{}) (Signer, error)
• type Verifier
  • func NewVerifier(verificationKey interface{}) (Verifier, error)

Examples

• Package (JWE)
• Package (JWS)
• Encrypter (Encrypt)
• Encrypter (EncryptWithAuthData)
• NewDecrypter (PublicKey)
• NewDecrypter (Symmetric)
• NewEncrypter (PublicKey)
• NewEncrypter (Symmetric)
• NewMultiEncrypter
• NewMultiSigner
• NewSigner (PublicKey)
• NewSigner (Symmetric)
• NewVerifier (PublicKey)
• NewVerifier (Symmetric)

Constants

const (
	RSA1_5             = KeyAlgorithm("RSA1_5")             // RSA-PKCS1v1.5
	RSA_OAEP           = KeyAlgorithm("RSA-OAEP")           // RSA-OAEP-SHA1
	RSA_OAEP_256       = KeyAlgorithm("RSA-OAEP-256")       // RSA-OAEP-SHA256
	A128KW             = KeyAlgorithm("A128KW")             // AES key wrap (128)
	A192KW             = KeyAlgorithm("A192KW")             // AES key wrap (192)
	A256KW             = KeyAlgorithm("A256KW")             // AES key wrap (256)
	DIRECT             = KeyAlgorithm("dir")                // Direct encryption
	ECDH_ES            = KeyAlgorithm("ECDH-ES")            // ECDH-ES
	ECDH_ES_A128KW     = KeyAlgorithm("ECDH-ES+A128KW")     // ECDH-ES + AES key wrap (128)
	ECDH_ES_A192KW     = KeyAlgorithm("ECDH-ES+A192KW")     // ECDH-ES + AES key wrap (192)
	ECDH_ES_A256KW     = KeyAlgorithm("ECDH-ES+A256KW")     // ECDH-ES + AES key wrap (256)
	A128GCMKW          = KeyAlgorithm("A128GCMKW")          // AES-GCM key wrap (128)
	A192GCMKW          = KeyAlgorithm("A192GCMKW")          // AES-GCM key wrap (192)
	A256GCMKW          = KeyAlgorithm("A256GCMKW")          // AES-GCM key wrap (256)
	PBES2_HS256_A128KW = KeyAlgorithm("PBES2-HS256+A128KW") // PBES2 + HMAC-SHA256 + AES key wrap (128)
	PBES2_HS384_A192KW = KeyAlgorithm("PBES2-HS384+A192KW") // PBES2 + HMAC-SHA384 + AES key wrap (192)
	PBES2_HS512_A256KW = KeyAlgorithm("PBES2-HS512+A256KW") // PBES2 + HMAC-SHA512 + AES key wrap (256)
)

Key management algorithms

const (
	HS256 = SignatureAlgorithm("HS256") // HMAC using SHA-256
	HS384 = SignatureAlgorithm("HS384") // HMAC using SHA-384
	HS512 = SignatureAlgorithm("HS512") // HMAC using SHA-512
	RS256 = SignatureAlgorithm("RS256") // RSASSA-PKCS-v1.5 using SHA-256
	RS384 = SignatureAlgorithm("RS384") // RSASSA-PKCS-v1.5 using SHA-384
	RS512 = SignatureAlgorithm("RS512") // RSASSA-PKCS-v1.5 using SHA-512
	ES256 = SignatureAlgorithm("ES256") // RCDSA using P-256 and SHA-256
	ES384 = SignatureAlgorithm("ES384") // RCDSA using P-384 and SHA-384
	ES512 = SignatureAlgorithm("ES512") // RCDSA using P-521 and SHA-512
	PS256 = SignatureAlgorithm("PS256") // RSASSA-PSS using SHA256 and MGF1-SHA256
	PS384 = SignatureAlgorithm("PS384") // RSASSA-PSS using SHA384 and MGF1-SHA384
	PS512 = SignatureAlgorithm("PS512") // RSASSA-PSS using SHA512 and MGF1-SHA512
)

Signature algorithms

const (
	A128CBC_HS256 = ContentEncryption("A128CBC-HS256") // AES-CBC + HMAC-SHA256 (128)
	A192CBC_HS384 = ContentEncryption("A192CBC-HS384") // AES-CBC + HMAC-SHA384 (192)
	A256CBC_HS512 = ContentEncryption("A256CBC-HS512") // AES-CBC + HMAC-SHA512 (256)
	A128GCM       = ContentEncryption("A128GCM")       // AES-GCM (128)
	A192GCM       = ContentEncryption("A192GCM")       // AES-GCM (192)
	A256GCM       = ContentEncryption("A256GCM")       // AES-GCM (256)
)

Content encryption algorithms

const (
	NONE    = CompressionAlgorithm("")    // No compression
	DEFLATE = CompressionAlgorithm("DEF") // DEFLATE (RFC 1951)
)

Compression algorithms

Variables

var (
	// ErrCryptoFailure represents an error in cryptographic primitive. This
	// occurs when, for example, a message had an invalid authentication tag or
	// could not be decrypted.
	ErrCryptoFailure = errors.New("square/go-jose: error in cryptographic primitive")

	// ErrUnsupportedAlgorithm indicates that a selected algorithm is not
	// supported. This occurs when trying to instantiate an encrypter for an
	// algorithm that is not yet implemented.
	ErrUnsupportedAlgorithm = errors.New("square/go-jose: algorithm is currently not supported")

	// ErrUnsupportedKeyType indicates that the given key type/format is not
	// supported. This occurs when trying to instantiate an encrypter and passing
	// it a key of an unrecognized type.
	ErrUnsupportedKeyType = errors.New("square/go-jose: unsupported key type/format")

	// ErrNotSupported serialization of object is not supported. This occurs when
	// trying to compact-serialize an object which can't be represented in
	// compact form.
	ErrNotSupported = errors.New("square/go-jose: compact serialization not supported for object")
)

Functions

func LoadPrivateKey

func LoadPrivateKey(data []byte) (interface{}, error)

LoadPrivateKey loads a private key from PEM/DER-encoded data.

func LoadPublicKey

func LoadPublicKey(data []byte) (interface{}, error)

LoadPublicKey loads a public key from PEM/DER-encoded data.

Types

type CompressionAlgorithm

type CompressionAlgorithm string

CompressionAlgorithm represents an algorithm used for plaintext compression.

type ContentEncryption

type ContentEncryption string

ContentEncryption represents a content encryption algorithm.

type Decrypter

type Decrypter interface {
	Decrypt(object *JweObject) ([]byte, error)
}

Decrypter represents a decrypter which consumes an encrypted JWE object.

func NewDecrypter

func NewDecrypter(decryptionKey interface{}) (Decrypter, error)

NewDecrypter creates an appropriate decrypter based on the key type

Example (PublicKey)

// Instantiate an decrypter using an RSA private key. The decrypter will
// be able to decrypt any messages that are using RSA as the key management
// algorithm, meaning PKCS1v1.5, OAEP, and OAEP-SHA256.
var privateKey *rsa.PrivateKey
NewDecrypter(privateKey)

Example (Symmetric)

// Instantiate an encrypter using a shared symmetric key. The decrypter will
// be able to decrypt direct encrypted messages or any messages that use
// supported symmetric algorithms for key wrapping.
var sharedKey []byte
NewDecrypter(sharedKey)

type Encrypter

type Encrypter interface {
	Encrypt(plaintext []byte) (*JweObject, error)
	EncryptWithAuthData(plaintext []byte, aad []byte) (*JweObject, error)
	SetCompression(alg CompressionAlgorithm)
}

Encrypter represents an encrypter which produces an encrypted JWE object.

Example (Encrypt)

// Encrypt a plaintext in order to get an encrypted JWE object.
var plaintext = []byte("This is a secret message")

encrypter.Encrypt(plaintext)

Example (EncryptWithAuthData)

// Encrypt a plaintext in order to get an encrypted JWE object. Also attach
// some additional authenticated data (AAD) to the object. Note that objects
// with attached AAD can only be represented using full serialization.
var plaintext = []byte("This is a secret message")
var aad = []byte("This is authenticated, but public data")

encrypter.EncryptWithAuthData(plaintext, aad)

func NewEncrypter

func NewEncrypter(alg KeyAlgorithm, enc ContentEncryption, encryptionKey interface{}) (Encrypter, error)

NewEncrypter creates an appropriate encrypter based on the key type

Example (PublicKey)

var publicKey *rsa.PublicKey

// Instantiate an encrypter using RSA-OAEP with AES128-GCM.
NewEncrypter(RSA_OAEP, A128GCM, publicKey)

// Instantiate an encrypter using RSA-PKCS1v1.5 with AES128-CBC+HMAC.
NewEncrypter(RSA1_5, A128CBC_HS256, publicKey)

Example (Symmetric)

var sharedKey []byte

// Instantiate an encrypter using AES128-GCM with AES-GCM key wrap.
NewEncrypter(A128GCMKW, A128GCM, sharedKey)

// Instantiate an encrypter using AES256-GCM directly, w/o key wrapping.
NewEncrypter(DIRECT, A256GCM, sharedKey)

type JweObject

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

JweObject represents an encrypted JWE object after parsing.

func ParseEncrypted

func ParseEncrypted(input string) (*JweObject, error)

ParseEncrypted parses an encrypted message in compact or full serialization format.

func (JweObject) CompactSerialize

func (obj JweObject) CompactSerialize() (string, error)

CompactSerialize serializes an object using the compact serialization format.

func (JweObject) FullSerialize

func (obj JweObject) FullSerialize() string

FullSerialize serializes an object using the full JSON serialization format.

func (JweObject) GetAuthData

func (obj JweObject) GetAuthData() []byte

GetAuthData retrieves the (optional) authenticated data attached to the object.

type JwsObject

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

JwsObject represents a signed JWS object after parsing.

func ParseSigned

func ParseSigned(input string) (*JwsObject, error)

ParseSigned parses an encrypted message in compact or full serialization format.

func (JwsObject) CompactSerialize

func (obj JwsObject) CompactSerialize() (string, error)

CompactSerialize serializes an object using the compact serialization format.

func (JwsObject) FullSerialize

func (obj JwsObject) FullSerialize() string

FullSerialize serializes an object using the full JSON serialization format.

type KeyAlgorithm

type KeyAlgorithm string

KeyAlgorithm represents a key management algorithm.

type MultiEncrypter

type MultiEncrypter interface {
	Encrypt(plaintext []byte) (*JweObject, error)
	EncryptWithAuthData(plaintext []byte, aad []byte) (*JweObject, error)
	SetCompression(alg CompressionAlgorithm)
	AddRecipient(alg KeyAlgorithm, encryptionKey interface{}) error
}

MultiEncrypter represents an encrypter which supports multiple recipients.

func NewMultiEncrypter

func NewMultiEncrypter(enc ContentEncryption) (MultiEncrypter, error)

NewMultiEncrypter creates a multi-encrypter based on the given parameters

Example

var publicKey *rsa.PublicKey
var sharedKey []byte

// Instantiate an encrypter using AES-GCM.
encrypter, err := NewMultiEncrypter(A128GCM)
if err != nil {
	panic(err)
}

// Add a recipient using a shared key with AES-GCM key wap
err = encrypter.AddRecipient(A128GCMKW, sharedKey)
if err != nil {
	panic(err)
}

// Add a recipient using an RSA public key with RSA-OAEP
err = encrypter.AddRecipient(RSA_OAEP, publicKey)
if err != nil {
	panic(err)
}

type MultiSigner

type MultiSigner interface {
	Sign(payload []byte) (*JwsObject, error)
	AddRecipient(alg SignatureAlgorithm, signingKey interface{}) error
}

MultiSigner represents a signer which supports multiple recipients.

func NewMultiSigner

func NewMultiSigner() MultiSigner

NewMultiSigner creates a signer for multiple recipients

Example

var publicKey *rsa.PublicKey
var sharedKey []byte

// Instantiate a signer for multiple recipients.
encrypter := NewMultiSigner()

// Add a recipient using a shared key with HMAC-SHA256
err := encrypter.AddRecipient(HS256, sharedKey)
if err != nil {
	panic(err)
}

// Add a recipient using an RSA public key with RSASSA-PSS with SHA384
err = encrypter.AddRecipient(PS384, publicKey)
if err != nil {
	panic(err)
}

type SignatureAlgorithm

type SignatureAlgorithm string

SignatureAlgorithm represents a signature (or MAC) algorithm.

type Signer

type Signer interface {
	Sign(payload []byte) (*JwsObject, error)
}

Signer represents a signer which takes a payload and produces a signed JWS object.

func NewSigner

func NewSigner(alg SignatureAlgorithm, signingKey interface{}) (Signer, error)

NewSigner creates an appropriate signer based on the key type

Example (PublicKey)

var rsaPrivateKey *rsa.PrivateKey
var ecdsaPrivateKey *ecdsa.PrivateKey

// Instantiate a signer using RSA-PKCS#1v1.5 with SHA-256.
NewSigner(RS256, rsaPrivateKey)

// Instantiate a signer using ECDSA with SHA-384.
NewSigner(ES384, ecdsaPrivateKey)

Example (Symmetric)

var sharedKey []byte

// Instantiate an signer using HMAC-SHA256.
NewSigner(HS256, sharedKey)

// Instantiate an signer using HMAC-SHA512.
NewSigner(HS512, sharedKey)

type Verifier

type Verifier interface {
	Verify(object *JwsObject) ([]byte, error)
}

Verifier represents a verifier which checks signatures on JWS objects.

func NewVerifier

func NewVerifier(verificationKey interface{}) (Verifier, error)

NewVerifier creates a verifier based on the key type

Example (PublicKey)

// Instantiate an verifier using an RSA public key. The verifier will be able
// to verify any messages that are using RSA as the signature algorithm,
// meaning RSASSA-PKCS1v1.5, RSASSA-PSS.
var publicKey *rsa.PublicKey
NewVerifier(publicKey)

Example (Symmetric)

// Instantiate an verifier using a shared key. The verifier will be able to
// verify any messages that are using HMAC.
var sharedKey []byte
NewVerifier(sharedKey)