jose

README

JOSE

Goals

This repository aims to implement the Standards by the IETF Javascript Object Signing and Encryption (jose) Working group:

• RFC 7515: JSON Web Signature (JWS)
• RFC 7516: JSON Web Encryption (JWE)
• RFC 7517: JSON Web Key (JWK)
• RFC 7518: JSON Web Algorithms (JWA)
• RFC 7519: JSON Web Token (JWT)
• RFC 7638: JSON Web Key (JWK) Thumbprint
• RFC 7797: JSON Web Signature (JWS) Unencoded Payload Option

Additiontional Information can be found in the informal RFCs:

• RFC 7165: Use Cases and Requirements for JSON Object Signing and Encryption (JOSE)
• RFC 7520: Examples of Protecting Content using JSON Object Signing and Encryption (JOSE)

Focus is on correctness and completeness of the implemention. The implementation will closely follow the RFC. Only exception is, that primitives who did prove to be unsecure will rejected. All API should have sane and safe defaults.

Status of the implementation

• This is not to be considered to be a version 1.0 yet. So use it in production with care.
• The API is not stable yet. It will grow and change with the completing implemenation.

Below you find the completion of the implementation of the different sections of the RFC:

RFC 7515 - JSON Web Signature (JWS)

• 3. JSON Web Signature (JWS) Overview
• 3.1. JWS Compact Serialization Overview
• 3.2. JWS JSON Serialization Overview
• 4. JOSE Header
• 4.1. Registered Header Parameter Names
• 4.1.1. "alg" (Algorithm) Header Parameter
• 4.1.2. "jku" (JWK Set URL) Header Parameter
• 4.1.3. "jwk" (JSON Web Key) Header Parameter
• 4.1.4. "kid" (Key ID) Header Parameter
• 4.1.5. "x5u" (X.509 URL) Header Parameter
• 4.1.6. "x5c" (X.509 Certificate Chain) Header Parameter
• 4.1.7. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header Parameter
• 4.1.8. "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) Header Parameter
• 4.1.9. "typ" (Type) Header Parameter
• 4.1.10. "cty" (Content Type) Header Parameter
• 4.1.11. "crit" (Critical) Header Parameter
• 4.2. Public Header Parameter Names
• 4.3. Private Header Parameter Names
• 5. Producing and Consuming JWSs
• 5.1. Message Signature or MAC Computation
• 5.2. Message Signature or MAC Validation
• 5.3. String Comparison Rules
• 6. Key Identification
• 7. Serializations
• 7.1. JWS Compact Serialization
• 7.2. JWS JSON Serialization
• 7.2.1. General JWS JSON Serialization Syntax
• 7.2.2. Flattened JWS JSON Serialization Syntax
• 8. TLS Requirements
• 9. IANA Considerations
• 9.1. JSON Web Signature and Encryption Header Parameters Registry
• 9.1.1. Registration Template
• 9.1.2. Initial Registry Contents
• 9.2. Media Type Registration
• 9.2.1. Registry Contents
• 10. Security Considerations
• 10.1. Key Entropy and Random Values
• 10.2. Key Protection
• 10.3. Key Origin Authentication
• 10.4. Cryptographic Agility
• 10.5. Differences between Digital Signatures and MACs
• 10.6. Algorithm Validation
• 10.7. Algorithm Protection
• 10.8. Chosen Plaintext Attacks
• 10.9. Timing Attacks
• 10.10. Replay Protection
• 10.11. SHA-1 Certificate Thumbprints
• 10.12. JSON Security Considerations
• 10.13. Unicode Comparison Security Considerations
• 11. References
• 11.1. Normative References
• 11.2. Informative References
• A. JWS Examples
• A.1. Example JWS Using HMAC SHA-256
• A.1.1. Encoding
• A.1.2. Validating
• A.2. Example JWS Using RSASSA-PKCS1-v1_5 SHA-256
• A.2.1. Encoding
• A.2.2. Validating
• A.3. Example JWS Using ECDSA P-256 SHA-256
• A.3.1. Encoding
• A.3.2. Validating
• A.4. Example JWS Using ECDSA P-521 SHA-512
• A.4.1. Encoding
• A.4.2. Validating
• A.5. Example Unsecured JWS
• A.6. Example JWS Using General JWS JSON Serialization
• A.6.1. JWS Per-Signature Protected Headers
• A.6.2. JWS Per-Signature Unprotected Headers
• A.6.3. Complete JOSE Header Values
• A.6.4. Complete JWS JSON Serialization Representation
• A.7. Example JWS Using Flattened JWS JSON Serialization
• B. "x5c" (X.509 Certificate Chain) Example
• C. Notes on Implementing base64url Encoding without Padding
• D. Notes on Key Selection
• E. Negative Test Case for "crit" Header Parameter
• F. Detached Content

RFC 7516 - JSON Web Encryption (JWE)

• 3. JSON Web Encryption (JWE) Overview
• 3.1. JWE Compact Serialization Overview
• 3.2. JWE JSON Serialization Overview
• 3.3. Example JWE
• 4. JOSE Header
• 4.1. Registered Header Parameter Names
• 4.1.1. "alg" (Algorithm) Header Parameter
• 4.1.2. "enc" (Encryption Algorithm) Header Parameter
• 4.1.3. "zip" (Compression Algorithm) Header Parameter
• 4.1.4. "jku" (JWK Set URL) Header Parameter
• 4.1.5. "jwk" (JSON Web Key) Header Parameter
• 4.1.6. "kid" (Key ID) Header Parameter
• 4.1.7. "x5u" (X.509 URL) Header Parameter
• 4.1.8. "x5c" (X.509 Certificate Chain) Header Parameter
• 4.1.9. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header Parameter
• 4.1.10. "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) Header Parameter
• 4.1.11. "typ" (Type) Header Parameter
• 4.1.12. "cty" (Content Type) Header Parameter
• 4.1.13. "crit" (Critical) Header Parameter
• 4.2. Public Header Parameter Names
• 4.3. Private Header Parameter Names
• 5. Producing and Consuming JWEs
• 5.1. Message Encryption
• 5.2. Message Decryption
• 5.3. String Comparison Rules
• 6. Key Identification
• 7. Serializations
• 7.1. JWE Compact Serialization
• 7.2. JWE JSON Serialization
• 7.2.1. General JWE JSON Serialization Syntax
• 7.2.2. Flattened JWE JSON Serialization Syntax
• 8. TLS Requirements
• 9. Distinguishing between JWS and JWE Objects
• 10. IANA Considerations
• 10.1. JSON Web Signature and Encryption Header Parameters Registration
• 10.1.1. Registry Contents
• 11. Security Considerations
• 11.1. Key Entropy and Random Values
• 11.2. Key Protection
• 11.3. Using Matching Algorithm Strengths
• 11.4. Adaptive Chosen-Ciphertext Attacks
• 11.5. Timing Attacks
• 12. References
• 12.1. Normative References
• 12.2. Informative References

RFC 7517 - JSON Web Key (JWK)

• 1. Introduction
• 1.1. Notational Conventions
• 2. Terminology
• 3. Example JWK
• 4. JSON Web Key (JWK) Format
• 4.1. "kty" (Key Type) Parameter
• 4.2. "use" (Public Key Use) Parameter
• 4.3. "key_ops" (Key Operations) Parameter
• 4.4. "alg" (Algorithm) Parameter
• 4.5. "kid" (Key ID) Parameter
• 4.6. "x5u" (X.509 URL) Parameter
• 4.7. "x5c" (X.509 Certificate Chain) Parameter
• 4.8. "x5t" (X.509 Certificate SHA-1 Thumbprint) Parameter
• 4.9. "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) Parameter
• 5. JWK Set Format
• 5.1. "keys" Parameter
• 6. String Comparison Rules
• 7. Encrypted JWK and Encrypted JWK Set Formats
• 8. IANA Considerations
• 8.1. JSON Web Key Parameters Registry
• 8.1.1. Registration Template
• 8.1.2. Initial Registry Contents
• 8.2. JSON Web Key Use Registry
• 8.2.1. Registration Template
• 8.2.2. Initial Registry Contents
• 8.3. JSON Web Key Operations Registry
• 8.3.1. Registration Template
• 8.3.2. Initial Registry Contents
• 8.4. JSON Web Key Set Parameters Registry
• 8.4.1. Registration Template
• 8.4.2. Initial Registry Contents
• 8.5. Media Type Registration
• 8.5.1. Registry Contents
• 9. Security Considerations
• 9.1. Key Provenance and Trust
• 9.2. Preventing Disclosure of Non-public Key Information
• 9.3. RSA Private Key Representations and Blinding
• 9.4. Key Entropy and Random Values
• 10. References
• 10.1. Normative References
• 10.2. Informative References

RFC 7518 - JSON Web Algorithms (JWA)

• 3. Cryptographic Algorithms for Digital Signatures and MACs
• 3.1. "alg" (Algorithm) Header Parameter Values for JWS
• 3.2. HMAC with SHA-2 Functions
• 3.3. Digital Signature with RSASSA-PKCS1-v1_5
• 3.4. Digital Signature with ECDSA
• 3.5. Digital Signature with RSASSA-PSS
• 3.6. Using the Algorithm "none"
• 4. Cryptographic Algorithms for Key Management
• 4.1. "alg" (Algorithm) Header Parameter Values for JWE
• 4.2. Key Encryption with RSAES-PKCS1-v1_5
• 4.3. Key Encryption with RSAES OAEP
• 4.4. Key Wrapping with AES Key Wrap
• 4.5. Direct Encryption with a Shared Symmetric Key
• 4.6. Key Agreement with Elliptic Curve Diffie-Hellman Ephemeral Static (ECDH-ES)
• 4.6.1. Header Parameters Used for ECDH Key Agreement
• 4.6.1.1. "epk" (Ephemeral Public Key) Header Parameter
• 4.6.1.2. "apu" (Agreement PartyUInfo) Header Parameter
• 4.6.1.3. "apv" (Agreement PartyVInfo) Header Parameter
• 4.6.2. Key Derivation for ECDH Key Agreement
• 4.7. Key Encryption with AES GCM
• 4.7.1. Header Parameters Used for AES GCM Key Encryption
• 4.7.1.1. "iv" (Initialization Vector) Header Parameter
• 4.7.1.2. "tag" (Authentication Tag) Header Parameter
• 4.8. Key Encryption with PBES2
• 4.8.1. Header Parameters Used for PBES2 Key Encryption
• 4.8.1.1. "p2s" (PBES2 Salt Input) Header Parameter
• 4.8.1.2. "p2c" (PBES2 Count) Header Parameter
• 5. Cryptographic Algorithms for Content Encryption
• 5.1. "enc" (Encryption Algorithm) Header Parameter Values for JWE
• 5.2. AES_CBC_HMAC_SHA2 Algorithms
• 5.2.1. Conventions Used in Defining AES_CBC_HMAC_SHA2
• 5.2.2. Generic AES_CBC_HMAC_SHA2 Algorithm
• 5.2.2.1. AES_CBC_HMAC_SHA2 Encryption
• 5.2.2.2. AES_CBC_HMAC_SHA2 Decryption
• 5.2.3. AES_128_CBC_HMAC_SHA_256
• 5.2.4. AES_192_CBC_HMAC_SHA_384
• 5.2.5. AES_256_CBC_HMAC_SHA_512
• 5.2.6. Content Encryption with AES_CBC_HMAC_SHA2
• 5.3. Content Encryption with AES GCM
• 6. Cryptographic Algorithms for Keys
• 6.1. "kty" (Key Type) Parameter Values
• 6.2. Parameters for Elliptic Curve Keys
• 6.2.1. Parameters for Elliptic Curve Public Keys
• 6.2.1.1. "crv" (Curve) Parameter
• 6.2.1.2. "x" (X Coordinate) Parameter
• 6.2.1.3. "y" (Y Coordinate) Parameter
• 6.2.2. Parameters for Elliptic Curve Private Keys
• 6.2.2.1. "d" (ECC Private Key) Parameter
• 6.3. Parameters for RSA Keys
• 6.3.1. Parameters for RSA Public Keys
• 6.3.1.1. "n" (Modulus) Parameter
• 6.3.1.2. "e" (Exponent) Parameter
• 6.3.2. Parameters for RSA Private Keys
• 6.3.2.1. "d" (Private Exponent) Parameter
• 6.3.2.2. "p" (First Prime Factor) Parameter
• 6.3.2.3. "q" (Second Prime Factor) Parameter
• 6.3.2.4. "dp" (First Factor CRT Exponent) Parameter
• 6.3.2.5. "dq" (Second Factor CRT Exponent) Parameter
• 6.3.2.6. "qi" (First CRT Coefficient) Parameter
• 6.3.2.7. "oth" (Other Primes Info) Parameter
• 6.4. Parameters for Symmetric Keys
• 6.4.1. "k" (Key Value) Parameter

RFC 7519 - JSON Web Token (JWT)

• 3. JSON Web Token (JWT) Overview
• 3.1. Example JWT
• 4. JWT Claims
• 4.1. Registered Claim Names
• 4.1.1. "iss" (Issuer) Claim
• 4.1.2. "sub" (Subject) Claim
• 4.1.3. "aud" (Audience) Claim
• 4.1.4. "exp" (Expiration Time) Claim
• 4.1.5. "nbf" (Not Before) Claim
• 4.1.6. "iat" (Issued At) Claim10
• 4.1.7. "jti" (JWT ID) Claim
• 4.2. Public Claim Names
• 4.3. Private Claim Names
• 5. JOSE Header
• 5.1. "typ" (Type) Header Parameter
• 5.2. "cty" (Content Type) Header Parameter
• 5.3. Replicating Claims as Header Parameters
• 6. Unsecured JWTs
• 6.1. Example Unsecured JWT
• 7. Creating and Validating JWTs
• 7.1. Creating a JWT
• 7.2. Validating a JWT
• 7.3. String Comparison Rules
• 8. Implementation Requirements
• 9. URI for Declaring that Content is a JWT
• 10. IANA Considerations
• 10.1. JSON Web Token Claims Registry
• 10.1.1. Registration Template 18
• 10.1.2. Initial Registry Contents
• 10.2. Sub-Namespace Registration of urn:ietf:params:oauth:token-type:jwt
• 10.2.1. Registry Contents
• 10.3. Media Type Registration
• 10.3.1. Registry Contents
• 10.4. Header Parameter Names Registration
• 10.4.1. Registry Contents

RFC 7638: JSON Web KEy (JWK) Thumbprint

• 1. Introduction
• 1.1. Notational Conventions
• 2. Terminology
• 3. JSON Web Key (JWK) Thumbprint
• 3.1. Example JWK Thumbprint Computation
• 3.2. JWK Members Used in the Thumbprint Computation
• 3.2.1. JWK Thumbprint of a Private Key
• 3.2.2. Why Not Include Optional Members?
• 3.3. Order and Representation of Members in Hash Input
• 3.4. Selection of Hash Function
• 3.5. JWK Thumbprints of Keys Not in JWK Format
• 4. Practical JSON and Unicode Considerations
• 5. Relationship to Digests of X.509 Values
• 6. IANA Considerations
• 7. Security Considerations
• 8. References
• 8.1. Normative References
• 8.2. Informative References

RFC 7797: JSON Web Signature (JWS) Unencoded Payload Option

• 1. Introduction
• 1.1. Notational Conventions
• 2. Terminology
• 3. The "b64" Header Parameter
• 4. Examples
• 4.1. Example with Header Parameters {"alg":"HS256"}
• 4.2. Example with Header Parameters {"alg":"HS256","b64":false,"crit":["b64"]}
• 5. Unencoded Payload Content Restrictions
• 5.1. Unencoded Detached Payload
• 5.2. Unencoded JWS Compact Serialization Payload
• 5.3. Unencoded JWS JSON Serialization Payload
• 6. Using "crit" with "b64"
• 7. Intended Use by Applications
• 8. Security Considerations
• 9. IANA Considerations
• 9.1. JSON Web Signature and Encryption Header Parameter Registration
• 9.1.1. Registry Contents
• 10. References
• 10.1. Normative References
• 10.2. Informative References

Security Considerations

Interoperability

Documentation

Overview

Package jose implemnents and complies with:

JSON Web Tokens JWT (RFC 7519)
JSON Web Signature JWS (RFC 7515)
JSON Web Algorithms JWA (RFC 7518)
JSON Web Signature JWS Unencoded Payload Option (RFC 7797)

Examples of JSON Object Signing and Encryption (JOSE) (RFC 7520)
Uses Cases and Requirements for JSON Object Signing and Ecnryption (RFC 7165)

Index

• func MakeRandomBytes(length int) ([]byte, error)

Functions

func MakeRandomBytes

func MakeRandomBytes(length int) ([]byte, error)

MakeRandomBytes creates random bytes from crypto/rand.Read for adhoc key generation