JSON Simple Sign 1.0 draft 00alt
json-simple-sign-1_0

Abstract

This specification defines a very simple signing mechanism to be used for JSON. The signature related parameters together with parameters to be signed are made into a JSON envelope. The signature is calculated over the ascii armoured version of the envelope and the result is recorded either as another JSON object or a string concatenated by a period ".".

Requirements Language

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.) [RFC2119].

Status of this Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as “work in progress.”

This Internet-Draft will expire on April 3, 2011.

Copyright Notice

Copyright (c) 2010 IETF Trust and the persons identified as the document authors. All rights reserved.

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.

Table of Contents

1.  Definitions
2.  Envelope Structures
3.  Creating Signature
4.  Serialization
    4.1.  JSON Serialization
    4.2.  Web Token Serialization
5.  Signature Verification
6.  Key Discovery and the Trust
    6.1.  Shared key in HMAC-SHA256
    6.2.  X.509 Certificates
7.  IANA Considerations
8.  Security Considerations
9.  Acknowledgements
10.  References
    10.1.  Normative References
    10.2.  Informative References
Appendix A.  An Appendix
§  Authors' Addresses

1.  Definitions

Signature

A digital signature that provably binds a message to a signer's keypair or Hash-based Message Authentication Code that can be used to verify both the data integrity and the authenticity of a message.

Thumbprint

A SHA1 of the DER encoded certificate.

Base64url Encoding

The URL and Filename safe variant of the base64 encoding as described in RFC4648 (Josefsson, S., “The Base16, Base32, and Base64 Data Encodings,” October 2006.) [RFC4648], section 5.

HMAC-SHA256

Hash-based Message Authentication Code using SHA-256 as the hash function.

RSA-SHA256

RSASSA-PKCS1-v1_5 signature algorithm from RFC3447 (Jonsson, J. and B. Kaliski, “Public-Key Cryptography Standards (PKCS) #1: RSA Cryptography Specifications Version 2.1,” February 2003.) [RFC3447] section 8.2, also known as PKCS#1, using SHA-256 as the hash function for EMSA-PKCS1-v1_5.

2.  Envelope Structures

JSON Simple Sign Envelope is a JSON object that contains three toplevel parameters, "type", "sig_params", and "payload". All of them are REQUIRED.

Each parameters are JSON object in turn as described below.

• http://jsonenc.info/type/sig_params - An array that has JSON objects with "alorithm", "thumbprint", "certs_uri", "key_id" as its elements.

Followings are the parameters inside "sig_params".

• algorithm - OPTIONAL. A String that identifies the algorithm used. This specification defines the following: "HMAC-SHA256", "RSA-SHA256". Defaults to "RSA-SHA256".
• thumprint - OPTIONAL. A SHA1 of the DER encoded certificate.
• certs_uri - REQUIRED for "RSA-SHA256". An URI that points to the X.509 public key certificates that can be used to verify the signature.
• key_id - REQUIRED for "HMAC-SHA256". A string that act as a key hint for HMAC-SHA256 signatures.

Following is a non-normative example of such envelope for HMAC-SHA256

{
    "http://jsonenc.info/jss/1.0/sig_params": [
        {
            "key_id": "example.com",
            "algorithm": "HMAC-SHA256"
        }
    ],
    "oauth_token": "asdfjklsdfjwoIjfk",
    "not_after": 12345678,
    "user_id": 1223,
    "profile_id": 1223
}

Following is a non-normative example of such envelope for RSA-SHA256

{
    "http://jsonenc.info/jss/1.0/sig_params": [
        {
            "certs_uri": "https://example.com/mycerts.pem"
        },
        {
            "algorithm": "RSA-SHA1",
            "certs_uri": "https://example.org/mycerts.pem"
        }
    ] ,
    "audience": "https://example-client.com/redirect_uri",
    "oauth_token": "asdfjklsdfjwoIjfk",
    "not_after": 12345678,
    "user_id": "1223",
    "profile_id": "1223"
}

3.  Creating Signature

The basic steps of creating the string with the signature is as follows:

1. Base64url encode the envelope to obtain the "ascii armoured payload".
2. Apply signature over the "ascii armoured payload" by the specified algorithm to obtain the signature.
3. Base64url encode the signature to obtain the "signature string".

4.  Serialization

This specification defines two types of serialization

4.1.  JSON Serialization

JSON Serialization is done by putting the "signature string" and "ascii armoured payload" into the following JSON Envelop.

• type - http://openid.net/specs/ab/1.0#signed_format
• sigs - the wrapper element that holds "certs_uri" and "signature"
• signature - the "signature string"
• data - the "ascii armoured payload"
• data_type - the MIME type OR the Type URL of the "ascii armoured payload" prior to encoding

Following is the non-normative example. Line breaks are for display purposes only.

{
    "type": "http://openid.net/specs/ab/1.0#signed_format",
    "data_type": "application/json",
    "data": "eyJhbGdvcml0aG0iOiJITUFDLVNIQTI1NiIsIjAiOiJwYXlsb2FkIn0",
    "sigs": [
        "vlXgu64BQGFSQrY0ZcJBZASMvYvTHu9GQ0YM9rjPSso",
        "cfXgu64BQGFSQrY0ZcJBZASMvYvTHu9GQ0YM9rjPSso"
    ]
}

4.2.  Web Token Serialization

Web Token Serialization is done by concatenating the "signature string" and the "ascii armoured payload" with a period "."(ASCII 0x2E). Note that in Web Token Serialization, only a single signature is supported. If multiple sigantures are used where sig[1], sig[2] etc. are the sequence of the signatures created by the respective keys in the signature parameters, signature strings are concatenated with a perid, and then the "ascii armored payload" is concatinated.

Following is the non-normative example. Line breaks are for display purposes only.

vlXgu64BQGFSQrY0ZcJBZASMvYvTHu9GQ0YM9rjPSso
.
eyJhbGdvcml0aG0iOiJITUFDLVNIQTI1NiIsIjAiOiJwYXlsb2FkIn0

5.  Signature Verification

To verify the signature, the verifier MUST have an access to a trusted signature verification key. Trusted key MAY BE established in the following ways:

1. If the algorithm is HMAC-SHA256, the key MUST BE pre-shared.
2. If the algorithm is asymetric, the key is defined in X.509 certificate. The key MUST be either obtained through the Discovery mechanism defined in Section 5 or looked up in a local key store using the thumbprint.

The verification involves the following steps:

1. If the serialization is JSON, parse it.
2. If the serialization is Web Token, split the JSON Token by a period "."(ASCII 0x2E) to obtain the signature and the payload.
3. Base64url decode both the "signature string" and the "ascii armoured payload" to obtain the signature and the envelope respectively.
4. If the algorithm is "HMAC-SHA256", calculate the signature from the payload using the client_secret.
5. If the algorithm is "RSA-SHA256", find the corresponding "signature" from "certs_uri" which was found inside "data". Then use RSASSA-PKCS1-v1_5 verification algorithm from RFC3447 (Jonsson, J. and B. Kaliski, “Public-Key Cryptography Standards (PKCS) #1: RSA Cryptography Specifications Version 2.1,” February 2003.) [RFC3447] section 8.2.1. to verify the Signature.

6.  Key Discovery and the Trust

To verify the signature, the trusted key MUST be found by the verifier first. This specification defines three such methods.

6.1.  Shared key in HMAC-SHA256

When HMAC-SHA256 is specified as the algorithm, the client_secret must be pre-shared by the parties. The exact method of performing such key exchange is out of scope of this specification.

6.2.  X.509 Certificates

X.509 Certificates are found from the uri in 'certs_uri' field. The uri MUST return a X.509 file in PEM format with "application/x-pem-file" as the mime-type. It MAY contain the certificate chain. The CN of the obtained certificate MUST match the uri found in the 'signer' field. Other attributes in the X.509 certificates SHOULD be checked to verify the validity of the certificates.

7.  IANA Considerations

This document makes no request of IANA.

8.  Security Considerations

Authors strongly recommend against using RSA-SHA1. It is depricated and is there only for backword compatibility.

9.  Acknowledgements

This specification is heavily influenced by the Magic Signatures (Panzer, J. and B. Laurie, “Magic Signatures,” February 2010.) [magic_signatures] and JSON Token draft specifications.

The authors would like Dirk Balfanz (Google), George Fletcher (AOL), Ryo Ito (Yahoo! Japan), John Panzar (Google), David Recordon (Facebook), Luke Shephard (Facebook), Paul Tarjan (Facebook) for their valuable inputs.

10.  References

10.1. Normative References

10.2. Informative References

Appendix A.  An Appendix

Authors' Addresses