TOC 
DraftJ. Panzer, Ed.
 B. Laurie
 D. Balfanz
 Google Inc.
 August 26, 2010


Magic Signatures [EXPERIMENTAL DRAFT]

Abstract

This document defines a lightweight, robust mechanism for digitally signing nearly arbitrary messages, along with a simple public key infrastructure.

It is intended to be a building block in the construction of protocols, providing a commonly agreed upon abstraction layer on top of lower level specifications such as Webfinger/LRDD (Eran, E., “LRDD: Link-based Resource Descriptor Discovery,” .) [LRDD], XRD (Eran, EHL. and WN. Will, “Extensible Resource Descriptor (XRD) Version 1.0, Working Draft 13,” .) [XRD], and PKCS (Jonsson, J. and B. Kaliski, “Public-Key Cryptography Standards (PKCS) #1: RSA Cryptography Specifications Version 2.1,” February 2003.) [RFC3447]. It is not a complete protocol in itself, and requires that dependent protocols document the specific profile(s) used.



Table of Contents

1.  Introduction
    1.1.  Requirements Language
2.  Definitions
3.  Magic Envelope Definition
    3.1.  Magic Envelope Parameters
    3.2.  The Signature Base String
    3.3.  The Compact Serialization
    3.4.  The XML Serialization
    3.5.  The JSON Serialization
4.  Provenance in Atom Entries
5.  Provenance in JSON Data Structures
6.  Standalone Magic Envelope Messages
    6.1.  Syndicating Magic Envelope Messages
7.  Encoding of data and sig using base64url
    7.1.  Encoding
    7.2.  Decoding
8.  The HMAC-SHA256 Private Key Signature Algorithm
    8.1.  Calculating the HMAC-SHA256 signature string
    8.2.  Signing and Verifying Messages with HMAC-SHA256
9.  The RSA-SHA256 Public Key Signature Algorithm
    9.1.  Signing Messages with RSA-SHA256
    9.2.  Verifying Messages with RSA-SHA256
10.  Simple Public Key Infrastructure
    10.1.  The application/magic-key MIME type
    10.2.  Discovery
        10.2.1.  The JSON Serialization of Magic Keys
        10.2.2.  The XRD XML Serialialization of Magic Keys
        10.2.3.  Discovery Flow
        10.2.4.  Key Selection
11.  Acknowledgements
12.  IANA Considerations
13.  Security Considerations
14.  References
    14.1.  Normative References
    14.2.  Informative References
Appendix A.  Specification Feedback
§  Authors' Addresses




 TOC 

1.  Introduction

The primary goal of Magic Signatures is to enable lightweight and robust public key signing for messages that may be transformed, converted, stored, and reconstituted in arbitrary ways. In order to make this mechanism useful, it also defines a public key discovery protocol that enables recipients to reliably map from URIs for signers to their public keys. It also allows for private key signatures, but leaves private key exchange mechanisms unspecified.

This mechanism is an alternative to XML-DSig. In the field, XML-DSig has proven to be problematic in applications such as syndication of feeds. Compared to XML-DSig, Magic Signatures offers the following features:

  1. Can handle any data format; not tied to XML.
  2. Does not require any canonicalization beyond removal of whitespace, so it is much easier to verify messages correctly.
  3. Can survive message disassembly, storage into arbitrary systems, and re-constitution without invalidating the signature.
  4. Significantly smaller and simpler specification.

Magic Signatures does not attempt to address every XML-DSig use case, so it is best described as a lightweight, robust, and minimal form of digital signatures that can be used and deployed where XML-DSig cannot be relied on. Note that for XML, it is possible to combine both mechanisms.



 TOC 

1.1.  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].



 TOC 

2.  Definitions

Signature:
A digital signature that provably binds a message to a signer's secret key.
Signer:
In this specification, an arbitrary URI used to determine a key used to sign an envelope. This specification does not dictate how signer URIs are to be determined, but in the usual case they are embedded within the signed data and extracted via a data format specific algorithm.
Public Key Infrastructure (PKI)
A set of hardware, software, people, policies, and procedures needed to create, manage, distribute, use, store, and revoke digital certificates. This specification uses a very simple, limited PKI.



 TOC 

3.  Magic Envelope Definition

A "Magic Envelope" comprises a message bundled along with signature(s) for that message, expressed as a series of parameters, and serialized as either XML or JSON. The envelope specifies the data to be signed, the MIME type of the data, the transfer encoding, and the signature.



 TOC 

3.1.  Magic Envelope Parameters

This section describes the semantics of the parameters independent of the serialization used.

data:
The payload covered by the signature, encoded into an ASCII string. This string is guaranteed to be safe to include without escaping as XML text and in JSON strings. Appears exactly once.
data_type:
The MIME (Freed, N. and N. Borenstein, “Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies,” November 1996.) [RFC2045] type of the payload prior to encoding. Appears exactly once.
encoding:
The encoding used to convert between the MIME type and the "data" string. In this specification, encoding MUST be the string "base64url", indicating the url safe base64 encoding as described in RFC 4648 (Josefsson, S., “The Base16, Base32, and Base64 Data Encodings,” October 2006.) [RFC4648]. All implementations MUST support this encoding. Appears exactly once.
alg:
The algorithm used for the signature. This specification describes only one public key signature algorithm, "RSA-SHA256", and one private key signature algorithm, "HMAC-SHA256". Specifications using Magic Signatures MUST specify which of these MUST be supported for a particular protocol. Implementations of general Magic Signatures SHOULD support both for maximum interoperability. Appears exactly once.
sig:
A generated signature. This is a string in the base64url encoded format as described above. It is generated according to the rules for the "alg" in use. A Magic Envelope has one or more signatures. Each signature has at most one associated "key_id" parameter.
key_id:
Optional hint indicating which specific key owned by the signer should be used to verify the signature. This allows signers to explicitly signal a change of key to recipients. Omitting this parameter is equivalent to setting it to an empty string. The format of this parameter is unspecified except that all characters must be from the base64url allowed character set. Thus, "", "1", "AH478=", "0x6EF37D", and "fred" are all legal key_ids. The exact format is up to the key issuer. Note that any binary data can be converted into an acceptable key_id by base64url encoding it. One way to generate a usable key_id is to base64url-encode the SHA256 hash of the public signing key's magicsig representation; this allows a signer to provide usable ids without maintaining a mapping table.



 TOC 

3.2.  The Signature Base String

The Signature Base String used for both RSA-SHA256 and HMAC-SHA256 is described here. It is used as input to the signature algorithms, as well as to create the Compact Serialization (The Compact Serialization), below.

Given a Magic Envelope with "data", "data_type", "encoding", and "alg" parameters, the corresponding Signature Base String is produced by concatenating the following substrings together, separated by periods (ASCII 0x2E):

  1. The armored string for "data" produced by Section 7.1 (Encoding)
  2. The Base64url encoding of the "data_type" parameter
  3. The Base64url encoding of the "encoding" parameter
  4. The Base64url encoding of the "alg" parameter



 TOC 

3.3.  The Compact Serialization

The Magic Envelope Compact Serialization stores the envelope itself in a compact, armored form suitable for storage as a simple string. It is guaranteed to contain no spaces and no URL unsafe characters, and allows for only a single signature.

Given a singly signed envelope with one "sig" and one "key_id", the Compact Serialization is produced by concatenating the following substrings together, separated by periods (ASCII 0x2E):

  1. The value of the "key_id" parameter
  2. The value of the "sig" parameter
  3. The Signature Base String as described in The Signature Base String (The Signature Base String), above.

For example, if the key_id is "4k8ikoyC2Xh+8BiIeQ+ob7Hcd2J7/Vj3uM61dy9iRMI=", the "sig" is "EvGSD2vi8qYcveHnb-rrlok07qnCXjn8YSeCDDXlbhILSabgvNsPpbe76up8w63i2fWHvLKJzeGLKfyHg8ZomQ", and the armored data is "Tm90IHJlYWxseSBBdG9t" with MIME type application/atom+xml, then the Compact Serialization would be the string: "4k8ikoyC2Xh+8BiIeQ+ob7Hcd2J7/Vj3uM61dy9iRMI=.EvGSD2vi8qYcveHnb-rrlok07qn CXjn8YSeCDDXlbhILSabgvNsPpbe76up8w63i2fWHvLKJzeGLKfyHg8ZomQ.Tm90IHJlYWxse SBBdG9t.YXBwbGljYXRpb24vYXRvbSt4bWw=.YmFzZTY0dXJs.UlNBLVNIQTI1Ng=="

Any parameter MAY be omitted by leaving its slot empty, as indicated by two consecutive periods. When the "encoding" parameter is omitted, a recipient MUST decode the envelope as if it had the value "base64url". When the "alg" parameter is omitted, a recipient MUST interpret the message as if the "alg" parameter had the value "RSA-SHA256". The "data_type" parameter SHOULD NOT be omitted as it provides a defense against content type masquerading attacks.



 TOC 

3.4.  The XML Serialization

A Magic Envelope XML Document is defined in terms of the XML Information Set, serialized as XML 1.0 [W3C.REC-xml-20040204] and identified with the "application/magic-envelope+xml" media type. Magic Envelope XML Documents MUST be well-formed XML. This specification does not define a DTD, and thus does not require validity (in the sense used by XML).

When used as a standalone XML document, the root element MUST be me:env. When incorporated as a subtree of another XML document, the root of the subtree MAY be either me:env or me:provenance. The me:provenance form indicates that the data is intended for verification of its sibling DOM nodes; the me:env form merely adds a signed envelope to the DOM without implying any particular semantics.

The parameters are mapped to XML elements and attributes as follows. Each parameter MUST appear exactly once per envelope.

The <me:data> element (REQUIRED):
Contains the "data" payload, an ASCII string, as described in Section 3.1 (Magic Envelope Parameters). The element contains one REQUIRED attribute, "type", which contains the value of the "data_type" parameter.
The <me:encoding> element (REQUIRED):
Contains the value of the "encoding" parameter.
The <me:alg> element (REQUIRED):
Contains the value of the "alg" parameter.
The <me:sig> element (REQUIRED):
Contains the value of the "sig" parameter, an ASCII string. MAY be repeated multiple times to record multiple signatures over the same text. MUST have a key_id attribute containing the "key_id" value for the signature.

Additional elements not defined by this specification MAY appear as children of the me:env or me:provenance elements. Processors MUST ignore elements they do not understand.

Example:

<?xml version='1.0' encoding='UTF-8'?>
<me:env xmlns:me='http://salmon-protocol.org/ns/magic-env'>
  <me:data type='application/atom+xml'>
    PD94bWwgdmVyc2lvbj0nMS4wJyBlbmNvZGluZz0nVVRGLTgnPz4KPGVudHJ5IHhtbG5zPS
    dodHRwOi8vd3d3LnczLm9yZy8yMDA1L0F0b20nPgogIDxpZD50YWc6ZXhhbXBsZS5jb20s
    MjAwOTpjbXQtMC40NDc3NTcxODwvaWQ-ICAKICA8YXV0aG9yPjxuYW1lPnRlc3RAZXhhbX
    BsZS5jb208L25hbWUPHVyaT5hY2N0OmpwYW56ZXJAZ29vZ2xlLmNvbTwvdXJpPjwvYXV0a
    G9yPgogIDx0aHI6aW4tcmVwbHktdG8geG1sbnM6dGhyPSdodHRwOi8vcHVybC5vcmcvc3l
    uZGljYXRpb24vdGhyZWFkLzEuMCcKICAgICAgcmVmPSd0YWc6YmxvZ2dlci5jb20sMTk5O
    TpibG9nLTg5MzU5MTM3NDMxMzMxMjczNy5wb3N0LTM4NjE2NjMyNTg1Mzg4NTc5NTQnPnR
    hZzpibG9nZ2VyLmNvbSwxOTk5OmJsb2ctODkzNTkxMzc0MzEzMzEyNzM3LnBvc3QtMzg2M
    TY2MzI1ODUzODg1Nzk1NAogIDwvdGhyOmluLXJlcGx5LXRvPgogIDxjb250ZW50PlNhbG1
    vbiBzd2ltIHVwc3RyZWFtITwvY29udGVudD4KICA8dGl0bGUU2FsbW9uIHN3aW0gdXBzdH
    JlYW0hPC90aXRsZT4KICA8dXBkYXRlZD4yMDA5LTEyLTE4VDIwOjA0OjAzWjwvdXBkYXRl
    ZD4KPC9lbnRyeT4KICAgIA
  </me:data>
  <me:encoding>base64url</me:encoding>
  <me:alg>RSA-SHA256</me:alg>
  <me:sig key_id="4k8ikoyC2Xh+8BiIeQ+ob7Hcd2J7/Vj3uM61dy9iRMI=">
    EvGSD2vi8qYcveHnb-rrlok07qnCXjn8YSeCDDXlbhILSabgvNsPpbe76up8w63i2f
    WHvLKJzeGLKfyHg8ZomQ
  </me:sig>
</me:env>



 TOC 

3.5.  The JSON Serialization

Magic Envelope JSON MUST be well formed JSON as defined in [RFC4627] (Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.). The parameters are serialized into a JSON object as a sequence of name/value pairs for the parameter names "data", "data_type", "encoding", and "alg". These values are represented as JSON strings. The "sig" parameter is represented as a "sigs" name whose value is an array of objects; each object has a "value" with the signature string, and a "key_id" with the associated "key_id" parameter.

Additional name/value pairs MAY appear within the JSON object and processors MUST ignore elements they do not understand.

Example:

{
  "data": "
    PD94bWwgdmVyc2lvbj0nMS4wJyBlbmNvZGluZz0nVVRGLTgnPz4KPGVudHJ5IHhtbG5zPS
    dodHRwOi8vd3d3LnczLm9yZy8yMDA1L0F0b20nPgogIDxpZD50YWc6ZXhhbXBsZS5jb20s
    MjAwOTpjbXQtMC40NDc3NTcxODwvaWQ-ICAKICA8YXV0aG9yPjxuYW1lPnRlc3RAZXhhbX
    BsZS5jb208L25hbWUPHVyaT5hY2N0OmpwYW56ZXJAZ29vZ2xlLmNvbTwvdXJpPjwvYXV0a
    G9yPgogIDx0aHI6aW4tcmVwbHktdG8geG1sbnM6dGhyPSdodHRwOi8vcHVybC5vcmcvc3l
    uZGljYXRpb24vdGhyZWFkLzEuMCcKICAgICAgcmVmPSd0YWc6YmxvZ2dlci5jb20sMTk5O
    TpibG9nLTg5MzU5MTM3NDMxMzMxMjczNy5wb3N0LTM4NjE2NjMyNTg1Mzg4NTc5NTQnPnR
    hZzpibG9nZ2VyLmNvbSwxOTk5OmJsb2ctODkzNTkxMzc0MzEzMzEyNzM3LnBvc3QtMzg2M
    TY2MzI1ODUzODg1Nzk1NAogIDwvdGhyOmluLXJlcGx5LXRvPgogIDxjb250ZW50PlNhbG1
    vbiBzd2ltIHVwc3RyZWFtITwvY29udGVudD4KICA8dGl0bGUU2FsbW9uIHN3aW0gdXBzdH
    JlYW0hPC90aXRsZT4KICA8dXBkYXRlZD4yMDA5LTEyLTE4VDIwOjA0OjAzWjwvdXBkYXRl
    ZD4KPC9lbnRyeT4KICAgIA",
  "data_type": "application/atom+xml",
  "encoding": "base64url",
  "alg": "RSA-SHA256",
  "sigs": [
    {
    "value": "EvGSD2vi8qYcveHnb-rrlok07qnCXjn8YSeCDDXlbhILSabgvNsPpbe76
    up8w63i2fWHvLKJzeGLKfyHg8ZomQ",
    "key_id": "4k8ikoyC2Xh+8BiIeQ+ob7Hcd2J7/Vj3uM61dy9iRMI="
    }
  ]
}



 TOC 

4.  Provenance in Atom Entries

Magic Envelope parameters may be embedded within an Atom Entry to provide verifiable provenance. In this case the Magic Envelope elements are contained within an "me:provenance" root element to signal their purpose.

Example:


<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <id>tag:example.com,2009:3897938434</id>
  <author><name>E. Xample</name><uri>acct:test@example.com</uri></author>
  <content>Verify this content via me:provenance.</content>
  <title>A verifiable entry.</title>
  <updated>2009-12-18T20:04:03Z</updated>
  <me:provenance xmlns:me="http://salmon-protocol.org/ns/magic-env">
    <me:data type='application/atom+xml'>
    PD94bWwgdmVyc2lvbj0nMS4wJyBlbmNvZGluZz0nVVRGLTgnPz4KPGVudHJ5IHhtbG5zPS
    dodHRwOi8vd3d3LnczLm9yZy8yMDA1L0F0b20nPgogIDxpZD50YWc6ZXhhbXBsZS5jb20s
    MjAwOTpjbXQtMC40NDc3NTcxODwvaWQ-ICAKICA8YXV0aG9yPjxuYW1lPnRlc3RAZXhhbX
    BsZS5jb208L25hbWUPHVyaT5hY2N0OmpwYW56ZXJAZ29vZ2xlLmNvbTwvdXJpPjwvYXV0a
    G9yPgogIDx0aHI6aW4tcmVwbHktdG8geG1sbnM6dGhyPSdodHRwOi8vcHVybC5vcmcvc3l
    uZGljYXRpb24vdGhyZWFkLzEuMCcKICAgICAgcmVmPSd0YWc6YmxvZ2dlci5jb20sMTk5O
    TpibG9nLTg5MzU5MTM3NDMxMzMxMjczNy5wb3N0LTM4NjE2NjMyNTg1Mzg4NTc5NTQnPnR
    hZzpibG9nZ2VyLmNvbSwxOTk5OmJsb2ctODkzNTkxMzc0MzEzMzEyNzM3LnBvc3QtMzg2M
    TY2MzI1ODUzODg1Nzk1NAogIDwvdGhyOmluLXJlcGx5LXRvPgogIDxjb250ZW50PlNhbG1
    vbiBzd2ltIHVwc3RyZWFtITwvY29udGVudD4KICA8dGl0bGUU2FsbW9uIHN3aW0gdXBzdH
    JlYW0hPC90aXRsZT4KICA8dXBkYXRlZD4yMDA5LTEyLTE4VDIwOjA0OjAzWjwvdXBkYXRl
    ZD4KPC9lbnRyeT4KICAgIA
    </me:data>
    <me:encoding>base64url</me:encoding>
    <me:alg>RSA-SHA256</me:alg>
    <me:sig>
    EvGSD2vi8qYcveHnb-rrlok07qnCXjn8YSeCDDXlbhILSabgvNsPpbe76up8w63i2f
    WHvLKJzeGLKfyHg8ZomQ
    </me:sig>
  </me:provenance>
</entry>



 TOC 

5.  Provenance in JSON Data Structures

A Magic Envelope JSON data structure may be embedded within any JSON structure. When this is done to verify the provenance of associated data by augmenting an existing object, the object SHOULD use the key name "provenance" for the object containing the Magic Envelope fields.



 TOC 

6.  Standalone Magic Envelope Messages

The application/magic-envelope+{atom,json} data structures MAY be used standalone, as a drop-in replacement for the data that is encoded in the data element. This would be appropriate where the recipient understands the Magic Envelope specification and can automatically decode the data to recover the original format. For example, instead of POSTing an application/atom+xml type entry to create a new blog post, a client could POST an application/magic-envelope+xml with data of type application/atom+xml.



 TOC 

6.1.  Syndicating Magic Envelope Messages

It may be useful to syndicate Atom entries which have been enveloped and signed. This can be done in two ways: By adding a me:provenance element to the existing Atom entry and essentially duplicating its content in a signed me:data element, or by completely replacing each signed Atom entry with the corresponding me:env element.

Feed processors who understand Magic Signatures SHOULD treat me:env elements which verify correctly as if the underlying Atom entry had been sent. The semantics of me:env elements whose signatures cannot be verified are undefined by this specification; processors MAY ignore them, produce an error, attach a warning, or perform other actions as required by their security model. [TODO5] (JP: Talk about security models somewhere; clearly delineate where this spec leaves off and referencing specs need to provide a model.)



 TOC 

7.  Encoding of data and sig using base64url

The data and sig fields of a Magic Envelope are encoded as armored ASCII strings using a procedure chosen to be robust in the face of various types of transports and storage systems. Specifically, the encoded form is safe to include directly as text in XML, a string in JSON, a parameter in URLs, or as form data, without escaping. This section defines the mapping between arbitrary binary data (a stream of octets) and the armored form (an ASCII string). The ASCII string is also chosen so as to be a valid and equivalent UTF-8 string.



 TOC 

7.1.  Encoding

The basic procedure is to use the URL and Filename safe variant of the base64 encoding as described in RFC 4648 (Josefsson, S., “The Base16, Base32, and Base64 Data Encodings,” October 2006.) [RFC4648], section 5, hereafter known as "base64url" encoding. The result is a string that consists only of the ASCII alphanumeric characters along with '-' and '_', and possibly '='. In regular expression form, this is "^[A-Za-z0-9\-_]*=?=?=?$". This is the normalized form of the encoded data, and is the basis for the octet sequence that is used to generate the digital signature. Implementations and transports MAY add arbitrary whitespace (ASCII values 0x09-0x0D and 0x20) anywhere in this string after signing but before output so as to, e.g., comply with line length restrictions in certain environments.



 TOC 

7.2.  Decoding

The basic procedure is the reverse of encoding, with the additional step that whitespace from the input should be ignored. This is necessary for robustness because some transports may insert whitespace, and is useful to allow for human readable formatting of documents in any case.

  1. Normalize the string by removing all whitespace characters from input.
  2. Base64url decode the resulting string to produce the original binary data.



 TOC 

8.  The HMAC-SHA256 Private Key Signature Algorithm

This section defines a basic HMAC based private key signature algorithm. HMAC key exchange and rotation is outside the scope of this specification, but may be defined in specifications referencing this one.



 TOC 

8.1.  Calculating the HMAC-SHA256 signature string

First, create an HMAC-SHA256 signature using the algorithm described in RFC 2104 (Krawczyk, H., Bellare, M., and R. Canetti, “HMAC: Keyed-Hashing for Message Authentication,” February 1997.) [RFC2104], using SHA-256 as the hash function H, base string described in Section 3.2 (The Signature Base String) as the input text, and the shared secret key K. The resulting array of bytes is then base64url encoded to produce the "sig" parameter.



 TOC 

8.2.  Signing and Verifying Messages with HMAC-SHA256

Signing consists of calculating the "sig" parameter and serializing it along with the other parameters to create a Magic Envelope. Verifying consists of re-calculating the expected "sig" parameter given the other parameters, and doing an exact string comparison of the "sig" parameters after normalization (whitespace removal).



 TOC 

9.  The RSA-SHA256 Public Key Signature Algorithm

This section defines the default public key signature algorithm for Magic Signatures. In addition to indicating the signing algorithm, use of RSA-SHA256 by default also implies use of the Simple Public Key Infrastructure Section 10 (Simple Public Key Infrastructure) to obtain public keys. Specifications using Magic Signatures MAY specify other mechanisms for key retrieval.



 TOC 

9.1.  Signing Messages with RSA-SHA256

Signing a message consists of signing the contents of "data", "data_type", "encoding", and "alg" using the chosen algorithm. This section defines the "RSA-SHA256" algorithm, meaning the RSASSA-PKCS1-v1_5 signature algorithm from RFC 3447 (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.

Note: As best current crypto practices change, new algorithms will become available and both extensions and future revisions of this specification may include additional new public key algorithms (e.g., RSASSA-PSS). When both clients and servers have sufficiently widespread support for the latest algorithm, older algorithms (e.g., RSASSA-PKCS1-v1_5) will be deprecated and removed in subsequent revisions of this specification.

The signature is computed as signature_octets = RSASSA-PKCS1-V1_5-SIGN (K, M), where K is the private signing key and M is the Signature Base String (The Signature Base String) defined above. Thus M is produced by concatenating the following substrings together, separated by periods (ASCII 0x2E):

  1. The armored string for "data" produced by Section 7.1 (Encoding)
  2. The Base64url encoding of the "data_type" parameter
  3. The Base64url encoding of the "encoding" parameter
  4. The Base64url encoding of the "alg" parameter

For example, if the armored data is "Tm90IHJlYWxseSBBdG9t" with MIME type application/atom+xml, then M would be the string: "Tm90IHJlYWxseSBBdG9t.YXBwbGljYXRpb24vYXRvbSt4bWw=.YmFzZTY0dXJs.UlNBLVNIQTI1Ng=="

For convenience we summarize the steps for the required EMSA-PKCS1-v1_5 with RSA-SHA256 algorithm here. In the following, '+' means string concatenation.

  1. Let hash = the SHA256 hash digest of M
  2. Let prefix = the constant byte sequence [NOTE1] (JP: The octets are Elvish, of an ancient mode, but the language is that of ASN.1, which I will not utter here. But this in the Common Tongue is what is said, close enough:) [0x30, 0x31, 0x30, 0xd, 0x6, 0x9, 0x60, 0x86, 0x48, 0x1, 0x65, 0x3, 0x4, 0x2, 0x1, 0x5, 0x0, 0x4, 0x20]
  3. Let k = the number of bytes in the public key modulus
  4. Let padding = '\xFF' repeated (k - length(prefix+hash) - 3) times
  5. Let emsa = '\x00' + '\x01' + padding + '\x00' + prefix + hash
  6. RSA sign the emsa byte sequence

The signature is then encoded as in Section 7.1 (Encoding) and the resulting ASCII armored string stored as a "sig" signature. The associated "key_id" is the base64url encoded respresentation of the SHA-256 hash of public key's application/magic-key representation.



 TOC 

9.2.  Verifying Messages with RSA-SHA256

Verifying a message signature consists of verifying that "sig" is a valid signature for "data" using "alg". This specification defines only the "RSA-SHA256" verification algorithm, meaning the RSASSA-PKCS1-v1_5 verification algorithm from RFC 3447 (Jonsson, J. and B. Kaliski, “Public-Key Cryptography Standards (PKCS) #1: RSA Cryptography Specifications Version 2.1,” February 2003.) [RFC3447] section 8.2.1.

The verification is performed by executing RSASSA-PKCS1-V1_5-VERIFY ((n, e), M, S), where (n ,e) comprise the public key, M is the message string documented in Section 9.1 (Signing Messages with RSA-SHA256), and S is the decoded value of a selected "sig". (Note that this algorithm creates the emsa byte sequence as in Section 9.1 (Signing Messages with RSA-SHA256) and then performing RSA verification using (n, e), emsa, and S.)

The scope of the verification covers only the contents of the Magic Envelope itself. In some cases, e.g., when using envelope data as provenance for enclosing data, the decoded "data" value must be checked against or override the enclosing data. A secure if lossy mechanism is to throw away the enclosing information and replace it with the output of the decoded "data". Another altnernative is to compare trees, override with signed information where there are conflicts, and annotate unsigned parts as insecure/unreliable. The correct mechanism depends on the security model required by the processor and is outside the scope of this specification.

It is RECOMMENDED that signed content contain expiration information after which the signed data SHOULD NOT be verified or used without additional confirmation. Such confirmation is outside the scope of this specification. However, when this is done and signing keys also expire on a predictable time in the future, signers SHOULD ensure that the content expiration is not after the known key expiration time. That is, the signed content should expire no later than the expiration date of the key used to sign it.

Note that emergency key revocation is outside the scope of this specification. However, implementations SHOULD honor HTTP cache control directives when retrieving key material and SHOULD NOT use keys for verification without revalidating the content as directed by the origin server. This allows origin servers to trade off performance for smaller periods of vulnerability.

Unless specified otherwise, the public key (n, e) is obtained using the simple public key infrastructure described by Section 10 (Simple Public Key Infrastructure).



 TOC 

10.  Simple Public Key Infrastructure

This section defines a public key infrastructure based on URIs. It uses LRDD discovery plus direct retrieval via secure URLs. Specifically, given a signer URI such as "acct:bob@example.com" or "http://example.com/bob", the corresponding public key(s) for that identifier can be found discovery as defined below. The result is a set of RSA public keys in a simple string format.



 TOC 

10.1.  The application/magic-key MIME type

The application/magic-key format is a very minimal format for representing public key data. It consists of a string of ASCII text, separated into 3 components, with components separated by a "." (0x2E) character. The first component is the key type; this specification only defines the "RSA" key type for future upgradeability. Thus a magic key consists of the string "RSA.modulus(n).exponent(e)" The pair (n, e) is used as input to RSASSA-PKCS1-V1_5-VERIFY.

Each of the components is first represented as an integer in network byte order (big endian) and encoded via the "base64url" mechanism described in Section 3.1 (Magic Envelope Parameters).

This specificaion defines only a public key format, and anticipates that keypairs may be stored securely in other formats (e.g., DER encoded X.509 certificates) and that the application/magic-key data will be generated via tools.



 TOC 

10.2.  Discovery

This section defines how to map from a signer URI identifier to a set of public signing keys for that identifier. The exact mechanism for a verifier to determine the signer URI is outside the scope of this specification, and MUST be specified by the particular protocol or application of Magic Signatures. The URI identifier MUST appear within, or be derived from, information within the "data" parameter and therefore be covered by the signature.

Many existing formats contain authorship, sender, or issuer fields and these SHOULD be used or extended where possible. Protocols which rely on Magic Signatures for digital signatures MUST specify a format-dependent model for determining potential signer URIs given the signed data. This section describes the subsequent discovery step: How to take a general URI and securely map it to a set of public signing keys with optional key ids.

The end result of discovery will be a collection of magic keys. Each magic key has a "data" parameter, a string in application/magic-public-key format; and an optional "key_id" parameter, a string as defined in [TBD:REF]. If the key_id is omitted from a key, it defaults to the Base64url encoding of the SHA-256 hash of the "value" parameter. That is, when doing discovery, processors MUST assume that an omitted key_id is equivalent to specifying key_id = Base64url(SHA-256(value)). A signer MAY then use this value as a key_id on a signature in order to signal use of that key.

There are two standard serializations of this collection, one for JSON and one for XML. Both are intended to be embeddable within general discovery metadata.



 TOC 

10.2.1.  The JSON Serialization of Magic Keys

The keys are stored within an array named "magic_keys". The array's values are objects, each of which MUST have a string "value" element containing the application/magic-key string, and which MAY have a string "key_id" element containing the id of that key.

Example:

{
  "magic_keys": [
    {"value": "RSA.mVgY8RN6URBTstndvmUUPb4UZTdwvwmddSKE5z_jvKUEK6yk1u3rrC9yN8k6FilGj9K0eeUPe2hf4Pj-5CmHww.AQAB",
     "key_id": "1"},
    {"value": "RSA.wvwmdK0eeUPe2hURBTstndvmUUPb4UZTd6wvwmddSrrC89yN8k6FilGwvwmddSKE5z_jvKUEKj9f4Pj-5CmHww.AQAB",
     "key_id": "2"}
  ]
}



 TOC 

10.2.2.  The XRD XML Serialialization of Magic Keys

The keys are stored as XRD Property elements within the XRD document. The type of the Property element is "ns:magic_key" [NOTE10] (JP: This is just to drive Will Norris insane.) . Each one has an optional mpk:key_id attribute containing the key's id; the body of the Property element contains the application/magic-key string data.

Example:

<Property type="ns:magic_key" mpk:key_id="1">
  RSA.mVgY8RN6URBTstndvmUUPb4UZTdwvwmddSKE5z_jvKUEK6yk1u3rrC9yN8k6FilGj9K0eeUPe2hf4Pj-5CmHww.AQAB
</Property>
<Property type="ns:magic_key" mpk:key_id="2">
  RSA.wvwmdK0eeUPe2hURBTstndvmUUPb4UZTd6wvwmddSrrC89yN8k6FilGwvwmddSKE5z_jvKUEKj9f4Pj-5CmHww.AQAB
</Property>



 TOC 

10.2.3.  Discovery Flow

Given a URI U, first perform discovery on U per Webfinger/LRDD (Eran, E., “LRDD: Link-based Resource Descriptor Discovery,” .) [LRDD] and interpret the result per the XRD XML Serialization. If this step produces a set of keys, stop. Otherwise, if U is an https URL, directly retrieve the resource U via SSL, performing necessary certificate checks, and see if the resulting data is of type application/metadata+json. If so, look for the "magic_public_keys" array as per the JSON Serialization. If both of these steps fail to produce a set of keys, stop.



 TOC 

10.2.4.  Key Selection

Once a set of possible key candidates have been determined, via discovery or alternatively via an extension mechanism outside the scope of this specification, a verifier must then determine whether a given signature is valid. This section details how to do so in an interoperable way.

Among the available keys, select the key for verification by matching the key_id against the key_id specified in the signature. In this context an empty string key_id matches everything. This produces a smaller set of possible keys to use for verification. Verification succeeds if any one of these keys successfully verifies the signature.

Note that in the case of multiple signatures, it is possible for one signature to be verified but for others to fail. Specifications relying on Magic Signatures MUST specify the semantics in these cases.



 TOC 

11.  Acknowledgements

TODO.



 TOC 

12.  IANA Considerations

This specification introduces three new media types.

The MIME media type for the XML serialization of a Magic Envelope is application/magic-env+xml.

Type name: application

Subtype name: magic-env+xml

Required parameters: n/a

Optional parameters: n/a

The MIME media type for the unique JSON serialization of a Magic Envelope is application/magic-env+json, though application/json is also appropriate.

Type name: application

Subtype name: magic-env+json

Required parameters: n/a

Optional parameters: n/a

The MIME media type for key(pairs) is application/magic-key.

Type name: application

Subtype name: magic-key

Required parameters: n/a

Optional parameters: n/a



 TOC 

13.  Security Considerations

TODO. See RFC 3552 (Rescorla, E. and B. Korver, “Guidelines for Writing RFC Text on Security Considerations,” July 2003.) [RFC3552] for a guide.



 TOC 

14.  References



 TOC 

14.1. Normative References

[LRDD] Eran, E., “LRDD: Link-based Resource Descriptor Discovery.”
[RFC2045] Freed, N. and N. Borenstein, “Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies,” RFC 2045, November 1996 (TXT).
[RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, “HMAC: Keyed-Hashing for Message Authentication,” RFC 2104, February 1997 (TXT).
[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).
[RFC3552] Rescorla, E. and B. Korver, “Guidelines for Writing RFC Text on Security Considerations,” BCP 72, RFC 3552, July 2003 (TXT).
[RFC4627] Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” RFC 4627, July 2006 (TXT).
[RFC4648] Josefsson, S., “The Base16, Base32, and Base64 Data Encodings,” RFC 4648, October 2006 (TXT).
[XRD] Eran, EHL. and WN. Will, “Extensible Resource Descriptor (XRD) Version 1.0, Working Draft 13.”


 TOC 

14.2. Informative References

[I-D.narten-iana-considerations-rfc2434bis] Narten, T. and H. Alvestrand, “Guidelines for Writing an IANA Considerations Section in RFCs,” draft-narten-iana-considerations-rfc2434bis-09 (work in progress), March 2008 (TXT).


 TOC 

Appendix A.  Specification Feedback

The primary driver of this specification is the Salmon protocol. Feedback on this specification is thus welcomed via the salmon-discuss mailing list, salmon-protocol@googlegroups.com. For more information, see the Salmon discussion group. Bugs and errata may also be reported via the Salmon bug tracker.



 TOC 

Authors' Addresses

  John Panzer (editor)
  Google Inc.
  1600 Ampitheatre Parkway
  Mountain View, CA
  USA
Phone: 
Email:  jpanzer@google.com
  
  Ben Laurie
  Google Inc.
  
  Dirk Balfanz
  Google Inc.