<?xml version="1.0"?>
<!-- vim: set et sw=2 wm=5 fdm=syntax nofen: -->
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<?rfc toc="yes"?>

<rfc ipr="trust200811" docName="draft-rsalz-atom-adv-sec-00.txt">

<front>

  <title abbrev="ATOM ADVANCED SECURITY">
    Advanced Security Processing for Atom and APP Documents
  </title>

  <author initials="F." surname="Chen" fullname="Fred (Xiangfu) Chen">
    <organization>IBM</organization>
    <address>
      <postal>
        <street>1 Rogers Street</street>
        <city>Cambridge</city> <region>MA</region> <code>02142</code>
        <country>USA</country>
      </postal>
      <phone>+1 617-693-6313</phone>
      <email>chenfr@us.ibm.com</email>
      <uri>http://www.ibm.com</uri>
    </address>
  </author>

  <author initials="M." surname="Hondo" fullname="Maryann Hondo">
    <organization>IBM</organization>
    <address>
      <postal>
        <street>1 Rogers Street</street>
        <city>Cambridge</city> <region>MA</region> <code>02142</code>
        <country>USA</country>
      </postal>
      <phone>+1 617-693-1236</phone>
      <email>mhondo@us.ibm.com</email>
      <uri>http://www.ibm.com</uri>
    </address>
  </author>

  <author initials="R." surname="Salz" fullname="Rich Salz">
    <organization>IBM</organization>
    <address>
      <postal>
        <street>1 Rogers Street</street>
        <city>Cambridge</city> <region>MA</region> <code>02142</code>
        <country>USA</country>
      </postal>
      <phone>+1 617-693-3808</phone>
      <email>rsalz@us.ibm.com</email>
      <uri>https://www.ibm.com/developerworks/mydeveloperworks/blogs/soma/</uri>
    </address>
  </author>

  <date month="August" year="2009"/>
  <area>Applications</area>
  <workgroup>atompub</workgroup>
  <keyword>atom</keyword>
  <keyword>app</keyword>
  <keyword>security</keyword>
  <keyword>trust</keyword>

  <abstract>
    <t>The Atom and APP specifications specify simple
      uses of cryptography to sign and encrypt their documents.
      Each document is processed completely, and in isolation.
      This document specifies additional uses that enable selective
      protection or encryption of content, and allow a "trust path" to
      be created across "atom:link" elements.</t>
  </abstract>
</front>

<middle>

  <section anchor="introduction" title="Introduction">
    <t>The Atom and APP specifications define how to use
      <xref target="W3C.REC-xmlenc-core-20021210">XML Digital Signature</xref>,
      and
      <xref target="W3C.REC-xmlenc-core-20021210">XML Encryption</xref>
      to prevent the contents of a document from being modified or
      inadvertently disclosed.
      This specification profiles how to use <xref target="oasis-wssec-v1.1">
        WS-Security</xref> to provide selective protection and
      encryption of a document and allow a single document to be encrypted
      for multiple recipients.</t>
    <t>Linking is a key point of Atom and APP, and this document defines
      a new element that can be used to establish a chain of trust, from
      the document with the "atom:link" to the content being
      referred-to.</t>

    <section anchor="notation" title="Notational Conventions and Terminology">
      <t>The conventions and terminology of both <xref target="RFC4287">The
          Atom Syndication Format</xref> and <xref target="RFC5023">The Atom
          Publishing Protocol</xref>, known as Atom and APP respectively,
        are incorporated here by reference. Within this document, the
        phrase "Atom document" is used to refer to any document defined by
        either RFC.</t>

      <t>The following namespace prefixes are used in this document:
        <texttable>
          <ttcol align="right">Prefix</ttcol>
          <ttcol align="left">Namespace URI</ttcol>
          <c>atom</c><c>http://www.w3.org/2005/Atom</c>
          <c>app</c><c>http://www.w3.org/2007/app</c>
          <c>atomsec</c><c>http://www.ibm.com/xmlns/stdwip/atomext/security</c>
          <c>dsig</c><c>http://www.w3.org/2000/09/xmldsig#</c>
          <c>xenc</c><c>http://www.w3.org/2001/04/xmlenc#</c>
          <c>wsse</c><c>http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd</c>
          <c>wsu</c><c>"http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd</c>
        </texttable>
      </t>

    </section>

  </section>

  <section anchor="ws-security" title="Using WS-Security">
    <t>The "wsse:Security" element is part of a specification informally
      known as WS-Security. The element is defined as a container for
      security information, including security tokens, XML encryption keys,
      and/or XML digital signatures for SOAP message security. This
      specification uses the semantics of WS-Security processing to achieve
      the goals <a xref="#introduction">described above</a>.
      </t>
      <t>An Atom or APP dcoument MUST NOT have more than one "wsse:Security"
        child element. While compatible with <xref
          target="oasis-wssec-v1.1"/> processing, the schema for the
        "wsse:Security" element is taken from <xref
          target="oasis-wssec-v1.0"/>.
    </t>
    <t>One feature of the WS-Security header is that it should be possible
      to process in a forward-streaming manner. That is, security tokens
      appear before they are used (such as in signatures), and encipherment
      keys appear before the encrypted data. Therefore, if present, the
      "wsse:Security" element SHOULD be the first child of the Atom
      document.</t>
    <t>The "wsse:SecurityTokenReference" element can be used to help
      enable streaming processing, and to reduce multiple occurrences of
      the same credentials. To do this, each credential is made the child
      of a "wsse:BinarySecurityToken" element, which in turn is a child of
      the "wsse:Security" element. For example:</t>
    <figure><artwork xml:space="preserve"><![CDATA[
<wsse:Security>
  <wsse:BinarySecurityToken
      wsu:Id="ssl-cert-1"
      ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3">
    MII...
  </wsse:BinarySecurityToken>.
  ...
</wsse:Security>
    ]]></artwork></figure>

    <t>Note that <xref target="W3C.REC-xmlenc-core-20021210"/> specifies
      many ways to identify key material, including Distinguished Name,
      Issuer/SerialNumber, etc. Any method other than embedding the
      entire certificate SHOULD NOT be used.</t>

    <t>In this document, anywhere a certificate is referenced, the content
      may instead be a "wsse:SecurityTokenReference" to a token in the
      "wsse:Security" element.  For example, the following two document
      fragments are semantically equivalent:</t>
    <figure><artwork xml:space="preserve"><![CDATA[
<dsig:KeyInfo>
  <dsig:X509Data>
    <wsse:SecurityTokenReference>
      <wsse:Reference URI="#ssl-cert-1"/>
    </wsse:SecurityTokenReference>
  </dsig:X509Data>
<dsig:KeyInfo>

<dsig:KeyInfo>
  <dsig:X509Data>
    <dsig:X509Certificate>
      MII...
    </dsig:X509Certificate>
  </dsig:X509Data>
<dsig:KeyInfo>
    ]]></artwork></figure>
    <t>A reference other than a direct reference using the "wsse:Reference"
      element MUST NOT be used.</t>

  </section>

  <section anchor="credentials" title='The "atomsec:credentials" element'>
    <t>The "atomsec:credentials" element is a child element of an
      "atom:link" element.
      It specifies one or more security tokens that may be used to
      validate the provenance of the data being linked-to. The "use"
      attribute specifies how the credentials are to be used. Two values
      are specified, "content" and "transport". If the attribute is not
      present, it is equivalent to providing it with the value
      "content".</t>
    <figure><artwork xml:space="preserve"><![CDATA[
atomSecCredentials =
    element atomsec:credentials {
        atomCommonAttributes*,
        attribute use { "content" | "transport" } ?,
        (extensionElement*)
    }
    ]]></artwork></figure>
    <t>The "transport" value specifies that the credentials can be used to
      validate the SSL certificate of the server containing the linked-to
      data. The "content" value specifies that the credentials can be used
      to validate any digital signatures on the linked-to data.</t>
    <t>An "atom:link" element can have no more than two "atom:credentials"
      elements, one for each of content and transport credentials.</t>
    <t>The child elements of the "atomsec:credentials" element SHOULD be
      "dsig:KeyInfo" elmenents used to locate X.509 certificate data.
      These certificates can be used by the relying party to verify the
      specified trust chain.</t>
    <t>A party that has out of band knowledge MAY ignore this element.</t>
    <t>Here is an example of an Atom document pointing to signed content:</t>
    <figure><artwork xml:space="preserve"><![CDATA[
<atom:link href="http://www.example.org/2003/12/13/foo">
  <atomsec:credentials>
    <!-- This is the certificate that should be signing the content
    at the href.  Or the signer's CA... -->
    <dsig:KeyInfo>
      <dsig:X509Data>
        <dsig:X509Certificate>
          MII...
        </dsig:X509Certificate>
      </dsig:X509Data>
    </dsig:KeyInfo>
  </atomsec:credentials>
</atom:link>
    ]]></artwork></figure>

    <t>Here is another example, one that specifies the CA that issued the
      SSL/TLS certificate used by the server for the host
      www.example.com:</t>
    <figure><artwork xml:space="preserve"><![CDATA[
<atom:link href="https://www.example.org/2003/12/13/foo">
  <atomsec:credentials use="transport">
    <!-- SSL CA, presumably not a typical "browser trusted" one. -->
    <dsig:KeyInfo>
      <dsig:X509Data>
        <dsig:X509Certificate>
          MII...
        </dsig:X509Certificate>
      </dsig:X509Data>
    </dsig:KeyInfo>
  </atomsec:credentials>
</atom:link>
    ]]></artwork></figure>
  </section>

  <section title="Selectively Signing parts of an Atom document">
    <t>A "dsig:Signature" element in the "wsse:Security" element may
      be used to sign one or more elements of an Atom document. The
      signature should be detached, with one "dsig:Reference" for each item
      being signed.</t>
    <t>The processing rules are defined by sections 8.2 and 8.4 of
      <xref target="oasis-wssec-v1.1"/> with the following additions:
      <list style="symbols">
        <t>The SOAP message envelope is not used and the "wsse:Security"
          element MUST be the first element of the root document.</t>
        <t>Each element being signed MUST have a unique "xml:id"
          attribute if not already present.</t>
        <t>The enveloped-signature transform as defined by <xref
            target="W3C.REC-xmlenc-core-20021210"/> SHOULD be used to sign
          the root document. If there are additional signed elements, they
          MUST be signed first so that the root signature will include its
          descendant's signatures.</t>
      </list>
    </t>
  <t>Here is an example:</t>
  <figure><artwork xml:space="preserve"><![CDATA[
<feed xmlns="http://www.w3.org/2005/Atom" xml:id="id3">

  <wsse:Security>

    <wsu:Timestamp xml:id="id1">
      <wsu:Created>XXXX-XX-XXT02:41:15Z</wsu:Created>
      <wsu:Expires>XXXX-XX-XXT02:46:15Z</wsu:Expires>
    </wsu:Timestamp>

    <wsse:BinarySecurityToken xml:id="SecurityToken-df8e8299-0d67-4eaf-bf5e-21c4dc6342ad"
        ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3">
      MII...
    </wsse:BinarySecurityToken>
    <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
      <SignedInfo>
        <CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
        <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
        <Reference URI="#id1">
          <Transforms>
            <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
          </Transforms>
          <DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
          <DigestValue>cHt...</DigestValue>
        </Reference>
        <Reference URI="#id2">
          <Transforms>
            <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
          </Transforms>
          <DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
          <DigestValue>Oj2...</DigestValue>
        </Reference>
      </SignedInfo>
      <SignatureValue>SWz...</SignatureValue>
      <KeyInfo>
        <wsse:SecurityTokenReference>
          <wsse:Reference URI="#SecurityToken-df8e8299-0d67-4eaf-bf5e-21c4dc6342ad"/>
        </wsse:SecurityTokenReference>
      </KeyInfo>
    </Signature>

    <!-- This is the enveloped signature, which covers all the other
         signatures and hence must be generated after all the other
         signatures are in place. -->
    <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
      <SignedInfo>
        <CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
        <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
        <Reference URI="#id3">
          <Transforms>
            <Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
            <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
          </Transforms>
          <DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
          <DigestValue>cRY...</DigestValue>
        </Reference>
      </SignedInfo>
      <SignatureValue>QAw...</SignatureValue>
      <KeyInfo>
        <wsse:SecurityTokenReference>
          <wsse:Reference
              URI="#SecurityToken-df8e8299-0d67-4eaf-bf5e-21c4dc6342ad"/>
        </wsse:SecurityTokenReference>
      </KeyInfo>
    </Signature>
  </wsse:Security>

  <title>Example Feed</title>
  <link href="http://example.org/"/>
  <updated>2003-12-13T18:30:02Z</updated>
  <author>
     <name>John Doe</name>
  </author>
  <id>urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6</id>

  <entry xml:id="id1">
    <title>Atom-Powered Robots Run Amok</title>
    <link href="http://example.org/2003/12/13/atom03"/>
    <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
    <updated>2003-12-13T18:30:02Z</updated>
    <summary>Some text.</summary>
    <content type="xhtml" xml:lang="en" xml:base="http://diveintomark.org/">
      <div xmlns="http://www.w3.org/1999/xhtml">
        <p><i>[Update: The Atom draft is finished.]</i></p>
      </div>
    </content>

  </entry>
</feed>
    ]]></artwork></figure>
  </section>

  <section title="Selectively Encrypting parts of an Atom document">
    <t>The processing rules for encrypting parts of an Atom document are
      defined by sections 9.4.1 and 9.4.2 of <xref target="oasis-wssec-v1.1"/>
      with the following additions:
      <list style="symbols">
      <t>The SOAP message envelope is not used and the "wsse:Security"
        element MUST be the first element of the root document.</t>
      <t>Use WS-Security processing to encrypt the full document.
        If the encrypted result does not have to be valid according to the
        Atom schema's, then the <xref target="W3C.REC-xmlenc-core-20021210"/>
        standard SHOULD be used.</t>
      </list>
    </t>
  <t>Here is an example:</t>
  <figure><artwork xml:space="preserve"><![CDATA[
<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xml:id="id3">

  <wsse:Security>
    <xenc:EncryptedKey>
      <xenc:EncryptionMethod
          Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/>
      <dsig:KeyInfo>
        <wsse:SecurityTokenReference>
          <wsse:KeyIdentifier
              ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3SubjectKeyIdentifier">
            YPArt...
          </wsse:KeyIdentifier>
        </wsse:SecurityTokenReference>
      </dsig:KeyInfo>
      <xenc:CipherData xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">
        <xenc:CipherValue>
        JG0...
        </xenc:CipherValue>
      </xenc:CipherData>
      <xenc:ReferenceList>
        <xenc:DataReference URI="#id1"/>
        <xenc:DataReference URI="#id2"/>
      </xenc:ReferenceList>
    </xenc:EncryptedKey>
  </wsse:Security>

  <title>Example Feed</title>
  <link href="http://example.org/"/>
  <updated>2003-12-13T18:30:02Z</updated>
  <author>
     <name>John Doe</name>
  </author>
  <id>urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6</id>

  <!-- this encrypted an atom:entry element. -->
  <xenc:EncryptedData Id="id1"
      Type="http://www.w3.org/2001/04/xmlenc#Element">
    <EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#tripledes-cbc"/>
    <CipherData xmlns="http://www.w3.org/2001/04/xmlenc#">
      <CipherValue>
      Clm...
      </CipherValue>
    </CipherData>
  </xenc:EncryptedData>

  <!-- this encrypted another atom:entry element. -->
  <xenc:EncryptedData Id="id2" Type="http://www.w3.org/2001/04/xmlenc#Element">
    <EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#tripledes-cbc"/>
    <CipherData xmlns="http://www.w3.org/2001/04/xmlenc#">
      <CipherValue>
      Clm...
      </CipherValue>
    </CipherData>
  </xenc:EncryptedData>

</feed>
    ]]></artwork></figure>
  </section>

  <section anchor="IANA" title="IANA Considerations">
    <t>None.</t>
  </section>

  <section anchor="security-considerations" title="Security Considerations">
    <t>This entire document is about securing Atom documents.
      Authentication and authorization (e.g., to delete a update or delete
      a posting via APP) are not discussed here.</t>
  </section>

</middle>

<back>

  <references title="Normative References">
    <?rfc include="reference.RFC.4287.xml" ?>
    <?rfc include="reference.RFC.5023.xml" ?>
    <?rfc include="reference.W3C.REC-xmldsig-core-20080610" ?>
    <?rfc include="reference.W3C.REC-xmlenc-core-20021210" ?>
    <reference anchor="oasis-wssec-v1.0"
        target="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0.pdf">
      <front>
        <title>Web Services Security: SOAP Message Security 1.0</title>
        <author initials="A." surname="Nadalin" fullname="Anthony Nadalin">
          <organization>IBM</organization>
        </author>
        <author initials="C." surname="Kaler" fullname="Chris Kaler">
          <organization>Microsoft</organization>
        </author>
        <author initials="P." surname="Hallam-Baker"
          fullname="Phillip Halam-Baker">
          <organization>VeriSign</organization>
        </author>
        <author initials="R." surname="Monzillo" fullname="Ron Monzillo">
          <organization>Sun</organization>
        </author>
        <date month="March" year="2004"/>
      </front>
      <seriesInfo name="OASIS Standard" value="200401"/>
    </reference>

    <reference anchor="oasis-wssec-v1.1"
        target="http://docs.oasis-open.org/wss/v1.1/wss-v1.1-spec-os-SOAPMessageSecurity.pdf">
      <front>
        <title>Web Services Security: SOAP Message Security 1.1</title>
        <author initials="" surname="" fullname="">
          <organization/>
        </author>
        <author initials="A." surname="Nadalin" fullname="Anthony Nadalin">
          <organization>IBM</organization>
        </author>
        <author initials="C." surname="Kaler" fullname="Chris Kaler">
          <organization>Microsoft</organization>
        </author>
        <author initials="P." surname="Hallam-Baker"
          fullname="Phillip Halam-Baker">
          <organization>VeriSign</organization>
        </author>
        <author initials="R." surname="Monzillo" fullname="Ron Monzillo">
          <organization>Sun</organization>
        </author>
        <date month="February" year="2006"/>
      </front>
      <seriesInfo name="OASIS Standard" value="(WS-Security 2004)"/>
    </reference>
  </references>

  <section title="Crypto and Security Primer">
    <t>This section provides a very brief overview of common cryptographic
      techniques and how they are used. It is intended only to provide the
      smallest amount of information so that the rest of this document is
      understandable. It is not normative.</t>
    <t>
      Public-key cryptography is done using two numbers that are related to
      each other. One of these numbers is public and can be known or used
      by anyone, while the other is private and should only be known by its
      "owner." The numbers have two very important properties. First,
      anything encrypted with the public key can only be decrypted with the
      private key. This means that anyone can generate text that is only
      legible to the key's owner. The second is that anything that is
      encrypted with the private key can be decrypted by anyone who has the
      public key. This allows anyone receiving such an encrypted item to
      know that it came from the key holder. The most common public-key
      algorithms are RSA and Elliptic-Curve.</t>
    <t>A message digest, or hash takes an arbitrary sequence of bytes and
      returns a fixed-size identifier. The most important property is that
      it is statistically unlikely for two different streams to result in
      the same hash. The most useful hash algorithms are SHA-1 and SHA-256.</t>
    <t>A message digest encrypted with a private key is a signature. Anyone
      with the original document can generate their own digest, decrypt the
      received one, and compare them. If the values do not match, then the
      document has been modified. The most common signature method is
      RSA/SHA-n.</t>
    <t>In symmetric cryptography, the same key is used for encryption and
      decryption. This means that both sender and receiver have to have the
      same key. Common symmetric (or shared-secret) algorithms are AES and
      triple-DES.</t>
    <t>A common technique is to "wrap" a symmetric key by encyrpting it
      with the recipient's public key. The bulk of the data is then
      encrypted using the symmetric key. This allows multiple recipients to
      see the data by only encrypting the symmetric key multiple times,
      rather than the entire data.</t>
    <t>An X.509 certificate is a datum that contains a name and other
      identifying information, and a public key that can be associated with
      that name. The certificate also contains information such as its
      validity period, the ways in which the keys are to be used, and so
      on. For details see the IETF PKI Profile, RFC XXX. A certificate is
      signed by a CA, and common practice is for the entity receiving a
      certificate to be configured to trust everything signed by the CA, or
      perhaps the CA's CA, or further up the chain.</t>
  </section>

</back>

</rfc>
