TOC 
OpenID Artifact Binding WorkingJ. Bradley
GroupProtivity Government Services
Internet-DraftN. Sakimura (Editor)
Intended status: InformationalNomura Research Institute
Expires: April 3, 2011September 30, 2010


JSON Simple Sign 1.0 draft 01
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.  Signature Parameters
    2.1.  JSON Serialization
    2.2.  Web Token Serialization
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




 TOC 

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.


 TOC 

2.  Signature Parameters

To create signatures, signature parameters that states information such as signature algorithm, certificate location etc. are required. Following is the list of such parameters.

This specification defines two types of serialization for these parameters. They are JSON Serialization and Web Token serialization.



 TOC 

2.1.  JSON Serialization

JSON serialization stores these parameters in an array of JSON Objects that holds signature parameters described above.

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

[
    {
        "key_id": "example.com",
        "algorithm": "HMAC-SHA256"
    }
]

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

[
    {
        "certs_uri": "https://example.com/mycerts.pem"
    },
    {
        "algorithm": "RSA-SHA1",
        "certs_uri": "https://example.org/mycerts.pem"
    }
]



 TOC 

2.2.  Web Token Serialization

To convert the JSON Serialization in Section 2.1 into Web Token Serialization, base64url eoncode the JSON Object. The result is called "ascii armoured sig_params".

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

W3sia2V5X2lkIjogImV4YW1wbGUuY29tIiwiYWxnb3JpdGhtIjogIkhNQUMtU0hBMjU2In1d



 TOC 

3.  Creating Signature

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

  1. Base64url encode the data to be signed to obtain "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".


 TOC 

4.  Serialization

This specification defines two types of serialization



 TOC 

4.1.  JSON Serialization

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

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

{
    "type": "http://openid.net/specs/ab/1.0#jss",
    "data_type": "application/json",
    "data": "eyJhbGdvcml0aG0iOiJITUFDLVNIQTI1NiIsIjAiOiJwYXlsb2FkIn0",
    "sig_params": [
        {
            "key_id": "example.com",
            "algorithm": "HMAC-SHA256"
        }
    ],
    "sigs": [
        "cfXgu64BQGFSQrY0ZcJBZASMvYvTHu9GQ0YM9rjPSso"
    ]
}

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

{
    "type": "http://openid.net/specs/ab/1.0#jss",
    "data_type": "application/json",
    "data": "ewogICAgImF1ZGllbmNlIjogImh0dHBzOi8vZXhhbXBsZS1jbGllbnQuY29tL3Jl
             ZGlyZWN0X3VyaSIsCiAgICAib2F1dGhfdG9rZW4iOiAiYXNkZmprbHNkZmp3b0lq
             ZmsiLAogICAgIm5vdF9hZnRlciI6IDEyMzQ1Njc4LAogICAgInVzZXJfaWQiOiAi
             MTIyMyIsCiAgICAicHJvZmlsZV9pZCI6ICIxMjIzIgp9",
    "sig_params": [
        {
            "certs_uri": "https://example.com/mycerts.pem"
        },
        {
            "algorithm": "RSA-SHA1",
            "certs_uri": "https://example.org/mycerts.pem"
        }
    ] ,
    "sigs": [
        "wm21w_Ppdil0f1HrSyiftu5pWrESclxxC2ON4-Vd1bJj3wlkFb3aoIWrT8TjMiey
         QKkHNgYwezeyvB_EuXnlOR2LZICXrsfAh65gHHynKI_NEgHHVFTt6msqP-wUru6f
         hV1cNAzRgZ6iFoNz6fRkWld1Guh5W6mncBfzWooq4OiAWt1JoHQz_pBc1a2cuGIM
         m5T9T_D8IxKYxnU6H7S56Be0hoaUV37PTbXSAG08_lkl84oSJtJ1Zvxh4c9ycXCd
         cg-VZ5isJsRnKjAqYeexPKg9683CG3iAB3Y7ZdZelstehpOEvkg9bn8BjkhjoOLk
         efeN_vZsXJGPvYJIeFav3A",

        "phLdlfjLEcA5-WOIoIu_CK_eIQV6Mswf9QfDTcpiehiptvDAAIkXo6oyJXVGIB7E
         RxaZ95-3okshSSj0mG4tFunTmV55nBV8zPoHQoxtWrWiksiVMYyG_yRG11xuCXkp
         XVper_fsJ1VJkP8FStYA3DY5E4e4FoV_wZsRvMMot88IPIFcFBmlBBGrdfEVkQBD
         -1sS0PWCLGFOQXrOWZysS9TfiRicPHtmW5gH9hOhGA97n4RwaIMXCjLVjpqvDhT7
         8akYpSQSN53PyaSlo99ffgDpc8Asy0FKNVSQpCqYg6G6BFTj12tt0JTIcH5U8RnI
         fN8bVrcu578pDx1-bwfVkg"
    ]
}



 TOC 

4.2.  Web Token Serialization

Web Token Serialization is done by concatenating the "signature string", "ascii armoured sig_params", and "ascii armoured payload" with a period "."(ASCII 0x2E). "ascii armoured sig_params".

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

98024bab1652fcc65b4948e71473d19a572ff969e11be10eb1b1deee415dea27
.
W3sia2V5X2lkIjogImV4YW1wbGUuY29tIiwiYWxnb3JpdGhtIjogIkhNQUMtU0hBMjU2In1d
.
ewogICAgImF1ZGllbmNlIjogImh0dHBzOi8vZXhhbXBsZS1jbGllbnQuY29tL3Jl
ZGlyZWN0X3VyaSIsCiAgICAib2F1dGhfdG9rZW4iOiAiYXNkZmprbHNkZmp3b0lq
ZmsiLAogICAgIm5vdF9hZnRlciI6IDEyMzQ1Njc4LAogICAgInVzZXJfaWQiOiAi
MTIyMyIsCiAgICAicHJvZmlsZV9pZCI6ICIxMjIzIgp9

If the sig_params are known out of band, then the "ascii armoured sig_params" can be ommitted.

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

98024bab1652fcc65b4948e71473d19a572ff969e11be10eb1b1deee415dea27
.
ewogICAgImF1ZGllbmNlIjogImh0dHBzOi8vZXhhbXBsZS1jbGllbnQuY29tL3Jl
ZGlyZWN0X3VyaSIsCiAgICAib2F1dGhfdG9rZW4iOiAiYXNkZmprbHNkZmp3b0lq
ZmsiLAogICAgIm5vdF9hZnRlciI6IDEyMzQ1Njc4LAogICAgInVzZXJfaWQiOiAi
MTIyMyIsCiAgICAicHJvZmlsZV9pZCI6ICIxMjIzIgp9

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. In this case, "ascii armoured sig_params" MUST NOT be ommitted. Thus, in multiple signatures case, there always are more than four segments.

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

wm21w_Ppdil0f1HrSyiftu5pWrESclxxC2ON4-Vd1bJj3wlkFb3aoIWrT8TjMiey
QKkHNgYwezeyvB_EuXnlOR2LZICXrsfAh65gHHynKI_NEgHHVFTt6msqP-wUru6f
hV1cNAzRgZ6iFoNz6fRkWld1Guh5W6mncBfzWooq4OiAWt1JoHQz_pBc1a2cuGIM
m5T9T_D8IxKYxnU6H7S56Be0hoaUV37PTbXSAG08_lkl84oSJtJ1Zvxh4c9ycXCd
cg-VZ5isJsRnKjAqYeexPKg9683CG3iAB3Y7ZdZelstehpOEvkg9bn8BjkhjoOLk
efeN_vZsXJGPvYJIeFav3A
.
phLdlfjLEcA5-WOIoIu_CK_eIQV6Mswf9QfDTcpiehiptvDAAIkXo6oyJXVGIB7E
RxaZ95-3okshSSj0mG4tFunTmV55nBV8zPoHQoxtWrWiksiVMYyG_yRG11xuCXkp
XVper_fsJ1VJkP8FStYA3DY5E4e4FoV_wZsRvMMot88IPIFcFBmlBBGrdfEVkQBD
-1sS0PWCLGFOQXrOWZysS9TfiRicPHtmW5gH9hOhGA97n4RwaIMXCjLVjpqvDhT7
8akYpSQSN53PyaSlo99ffgDpc8Asy0FKNVSQpCqYg6G6BFTj12tt0JTIcH5U8RnI
fN8bVrcu578pDx1-bwfVkg
.
WwogICAgewogICAgICAgICJjZXJ0c191cmkiOiAiaHR0cHM6Ly9leGFtcGxlLmNv
bS9teWNlcnRzLnBlbSIgCiAgICB9LAogICAgewogICAgICAgICJhbGdvcml0aG0i
OiAiUlNBLVNIQTEiLAogICAgICAgICJjZXJ0c191cmkiOiAiaHR0cHM6Ly9leGFt
cGxlLm9yZy9teWNlcnRzLnBlbSIgCiAgICB9IApd
.
ewogICAgImF1ZGllbmNlIjogImh0dHBzOi8vZXhhbXBsZS1jbGllbnQuY29tL3Jl
ZGlyZWN0X3VyaSIsCiAgICAib2F1dGhfdG9rZW4iOiAiYXNkZmprbHNkZmp3b0lq
ZmsiLAogICAgIm5vdF9hZnRlciI6IDEyMzQ1Njc4LAogICAgInVzZXJfaWQiOiAi
MTIyMyIsCiAgICAicHJvZmlsZV9pZCI6ICIxMjIzIgp9



 TOC 

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 6 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 signatures, "ascii armoured sig_params", and the "ascii armoured 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" or "RSA-SHA1", 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.


 TOC 

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.



 TOC 

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.



 TOC 

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.



 TOC 

7.  IANA Considerations

This document makes no request of IANA.



 TOC 

8.  Security Considerations

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



 TOC 

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), Yaron Goland (Microsoft), Ryo Ito (Yahoo! Japan), Mike Jones (Microsoft), Tony Nadalin (Microsoft), John Panzar (Google), David Recordon (Facebook), Luke Shephard (Facebook), Paul Tarjan (Facebook) for their valuable inputs.



 TOC 

10.  References



 TOC 

10.1. Normative References

[RFC2119] Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” BCP 14, RFC 2119, March 1997 (TXT, HTML, XML).
[RFC3447] Jonsson, J. and B. Kaliski, “Public-Key Cryptography Standards (PKCS) #1: RSA Cryptography Specifications Version 2.1,” RFC 3447, February 2003 (TXT).
[RFC4648] Josefsson, S., “The Base16, Base32, and Base64 Data Encodings,” RFC 4648, October 2006 (TXT).


 TOC 

10.2. Informative References

[magic_signatures] Panzer, J. and B. Laurie, “Magic Signatures,” February 2010.


 TOC 

Appendix A.  An Appendix



 TOC 

Authors' Addresses

  John Bradley
  Protivity Government Services
  
  Nat Sakimura (Editor)
  Nomura Research Institute