<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
    <!ENTITY RFC2119 PUBLIC '' 
      'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml'>
    <!ENTITY RFC5866 PUBLIC '' 
      'http://xml.resource.org/public/rfc/bibxml/reference.RFC.5866.xml'>

    <!ENTITY RFC6733 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.6733.xml'> 
    <!ENTITY I-D.ietf-jose-json-web-signature PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-jose-json-web-signature.xml'> 
    <!ENTITY I-D.ietf-jose-json-web-encryption PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-jose-json-web-encryption.xml'> 
]>
<rfc category="std" ipr="trust200902" docName="draft-korhonen-dime-e2e-security-03.txt">
  <?rfc toc="yes" ?>
  <?rfc symrefs="yes" ?>
  <?rfc sortrefs="yes"?>
  <?rfc compact="no" ?>
  <?rfc iprnotified="no" ?>
  <?rfc strict="yes" ?>
  <front>
    <title abbrev="Diameter E2E Security">Diameter AVP Level Security: Keyed Message Digests, Digital Signatures, and Encryption</title>
    
    <author initials='J.' surname="Korhonen" fullname='Jouni Korhonen'>
     <organization abbrev="Broadcom Ltd.">Broadcom Ltd.</organization>
     <address>
       <postal>
         <street>3151 Zanker Road</street>
         <code>95134</code>
         <region>CA</region>
         <country>US</country>
       </postal>
       <email>jouni.nospam@gmail.com</email>
     </address>
    </author>
    <author initials="H." surname="Tschofenig" fullname="Hannes Tschofenig">
      <organization>ARM Ltd.</organization>
      <address>
        <email>Hannes.Tschofenig@gmx.de</email>
        <uri>http://www.tschofenig.priv.at</uri>
      </address>
    </author>    
    <date year="2016"/>
    <area>OPS</area>
    <workgroup>DIME</workgroup>
    <keyword>I-D</keyword>
    <keyword>Internet-Draft</keyword>
    <keyword>Diameter</keyword>
    <keyword>End-to-End Security</keyword>
    <abstract>
     <t>This document defines an extension for end to end authentication, integrity and confidentiality protection of Diameter Attribute Value Pairs. The solutions focuses on protecting Diameter Attribute Value Pairs and leaves the key distribution solution to a separate specification. The integrity protection can be introduced in a backward compatible manner to existing application. The confidentiality protection requires an explicit support from an application, thus is applicable only for newly defined applications.</t>
    </abstract>

    <!-- ******************************************************************************* -->

    <note title="Terminology">
      <t> 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 <xref target="RFC2119">RFC 2119</xref>.</t>
    </note>
  </front>
  <middle>

    <!-- ******************************************************************************* -->
  <section anchor="introduction" title="Introduction"> 
   <t>The Diameter base protocol <xref target="RFC6733"/> 
    leverages IPsec and TLS for mutual authentication between neighboring 
    Diameter nodes and for channel security offering data origin authentication, 
    integrity and confidentiality protection. The Diameter base protocol, 
    however, also defines Diameter agents, namely Relay Agents, Proxy Agents, 
    Redirect Agents, and Translation Agents.
   </t>
   <t>Relay Agents are Diameter agents that accept requests and route
    messages to other Diameter nodes based on information found in the
    messages. Since Relays do not perform any application level processing, they
    provide relaying services for all Diameter applications.
   </t>
   <t>Similarly to Relays, Proxy Agents route Diameter messages using the
    Diameter routing table.  However, they differ since they modify
    messages to implement policy enforcement.
   </t>
   
   <t>Redirect Agents do not relay messages, and only return an answer with 
    the information necessary for Diameter agents to communicate directly, they 
    do not modify messages. Redirect Agents do not have negative impacts on 
    end-to-end security and are therefore not considered in this document.
   </t>
   
   <t>A Translation Agent is a device that provides translation between two
    protocols. To offer end-to-end security across different protocol requires 
    the ability to convey and process the AVPs defined in this document by both 
    end points. Since such support is very likely not available this document 
    does not cover this functionality.
   </t> 

   <t>The Diameter extension defined in this document specifies how AVP 
    authentication, integrity and  confidentiality protection can be offered 
    using either symmetric or asymmetric cryptography. As a solution mechanism 
    is derived form Javascript Object Signing  and Encryption (JOSE). JOSE 
    offers a simple encoding with small set of features ideal for the purpose of 
    Diameter. This document further defines a binary efficient coding of JOSE 
    objects.
   </t>
   
   <t>This document focuses on protecting Diameter AVP and leaves the key 
    distribution solution to a separate specification, which most likely is
    going to be a specific key exchange application. To offer the functionality 
    two grouped AVPs are defined: Signed-Data and Encrypted-Data. The respective
    JOSE objects are transported within these two AVPs.
   </t>
  </section>


    <!-- ******************************************************************************* -->
  <section title="Solution description">
   <section title="Integrity protection of AVPs" anchor="sig-example">
    <t>JWS represents digitally signed or HMACed content using JSON data
     structures.  The representation in <xref 
     target="I-D.ietf-jose-json-web-signature"/> consists of three parts: the
     JWS Header, the JWS Payload, and the JWS Signature. The three parts are
     represented as the concatenation of the encoded strings in that order, with
     the three strings being separated by period ('.') characters. For the JWS
     Payload one would define a new JSON object that contains an array of AVP
     code number and a hash of AVP pairs. The JWS Signature then covers the all
     APVs to be signed or HMACed. Both JWS Payload and signature MUST use the
     same hash algorithm of the cryptographic algorithm indicated in the JWS
     Header.
    </t>
    <t>Although the solution relies on the JSON, the encoding into Diameter AVPs
     differ from the text based encoding of the JSON objects. Specifically, none 
     of of the JWS Header, JWS Payload or JWS Signature are not BASE64 encoded 
     but  are processed in their plaintext or binary representation formats. For 
     example, the JWS Header is encoded in its plaintext format into the 
     Header-Parameters AVP:
<figure><artwork><![CDATA[
{  "typ":"JWT",
   "alg":"HS256",
   "kid":"abc123"
}
]]></artwork></figure>     
    </t>
    <t>The JWS Payload and the JWS Signature hashes and AVP Code values are
     encoded in their binary format as octets, not in textual or BASE64 encoded
     formats. Sections <xref target="jws-payload" format="counter"/> and <xref 
     target="jws-signature" format="counter"/> describe the encodings of the
     needed AVPs.
    </t>

    <t>To package a set of AVPs for signing, each AVP octet representation to be 
     protected are first individually hashed and encoded into the "JSON object"  
     with its four octets AVP code number.
     The entire AVP MUST be input to the hash calculation, from
     the first byte of the AVP code to the last byte of the AVP data,
     including all other fields, length, reserved/flags, and optional
     vendor IDs, and padding.  The AVP MUST be input to the hash calculation
     in network byte order.
    </t> 

    <t>The JWS Signature is calculated over the entire JWS Payloads and then the 
     all three JWS parts are placed in the Signed-Data AVP. There can be 
     multiple Signed-Data AVPs in a Diameter message. The AVP code in the JWS 
     Payload is to indicate which AVP this hash possibly refers to. If there are 
     multiple instances of the same AVP in the Diameter message, there is no 
     other way than make the verification against all of those. It is possible 
     that the message sender only hashed one AVP of the same type and, 
     therefore, the receiver MUST verify the hash against all occurrences of the 
     AVP of the same code number. Such flexibility is added there to allow 
     reordering of the AVPs and addition or deletion of new AVPs by 
     intermediating agents.
    </t>
   
    <t>If a receiver detects errors with the processing of the Signed-Data AVP
     it MAY return one of the errors defined in <xref target="error"/>. If a 
     receiver does not find any AVP the Signed-Data AVP has a signature for, it 
     MAY also return one of the errors defined in <xref target="error"/>.
    </t>

    <t>When AVPs are to be both encrypted and signed, the Encrypted-Data
     AVP MUST be created first. This means that signing is
     "outside" encryption.
    </t>
   
    <t>Here is an example: Imagine the following AVPs from the QoS-Resources AVP 
     in the QoS-Install Request (defined in RFC 5866 <xref target="RFC5866"/>
     message shall be signed. The resulting example message has the following 
     structure:
  
     <figure title="Example Diameter Message with Signed-Data AVP">
     <artwork><![CDATA[
<QoS-Install-Request> ::= < Diameter Header: 327, REQ, PXY >
                          < Session-Id >
                          { Auth-Application-Id }
                          { Origin-Host }
                          { Origin-Realm }
                          { Destination-Realm }
                          { Auth-Request-Type }
                          [ Signed-Data ]
                        * [ QoS-Resources ]
                          ...
]]></artwork></figure>
    </t>
 
    <t>The Signed-Data AVP in this example may contain a JWS Header that 
     indicates the use of the HMAC SHA-256 algorithm with the key id 'abc123'. 
     The protected AVPs are Session-Id, Origin-Host and Origin-Realm. The 
     calculated HMAC SHA-256 values are for example purposes only (i.e., are not 
     real):
     <figure title="Example JWS Header, Payload and Signature">
     <artwork><![CDATA[
JWS Header encoded as such in JWS-Header AVP:

 {"typ":"JWT",
  "alg":"HS256",
  "kid":"abc123"
 }

0x00000xxx  // JWS-Header code 'xxx'
0x00000034  // Flags=0, Length=52
'{"typ":"JWT","alg":"HS256","kid":"abc123"}'  // 41
0x00,0x00,0x00  // 3 octets padding

JWS Payload encoded into three JWS-AVP-Payload AVPs:

0x00000zzz  // JWS-AVP-Payload code 'zzz'    <--+
0x0000001c  // Flags=0, Length=28               |
0x00000107  // 263, Session-Id, 4 octets        s
0x9d0e0495  // hash of Session-Id, 128 bits     i
0xba8c0312                                      g
0xb6274c52                                      n
0x7d51a048                                      a
                                                t
0x00000zzz  // JWS-AVP-Payload code 'zzz'       u
0x0000001c  // Flags=0, Length=28               r
0x00000108  // 264, Origin-Host, 4 octets       e
0x39ca88ff  // hash of Origin-Host, 128 bits    |
0xaa5a6ff9                                      c
0x029ed95b                                      o
0xa534e028                                      v
                                                e
0x00000zzz  // JWS-AVP-Payload code 'zzz'       r
0x0000001c  // Flags=0, Length=28               a
0x00000128  // 296, Origin-Realm, 4 octets      g
0x202730ac  // hash of Origin-Realm, 128 bits   e
0xa6e3a180                                      |
0x2f44a633                                      |
0xf250f6fe                                   <--+

JWS Signature encoded into the JWS-Signature AVP:

0x00000yyy  // JWS-Signature code 'yyy'
0x00000018  // Flags=0, Length=24
0xaabbccdd,0xddeeff00,0x11223344,0x55667788
]]></artwork></figure>
    </t>
   </section> 

   <section title="Confidentiality protection of AVPs">
    
    <t>The Encrypted-Data AVP (AVP Code TBD) is of type OctetString and
    contains the JSON Web Encryption (JWE) <xref 
    target="I-D.ietf-jose-json-web-encryption"/> data structure and consists of 
    four parts: the JWE Header, the JWE Encrypted Key, the JWE Initialization
    Vector and the JWE Ciphertext.  The four parts are 
    represented as the concatenation of the encoded strings in that
    order, with the three strings being separated by period ('.')
    characters. JWE does not add a content integrity check if not
    provided by the underlying encryption algorithm.
   </t>

    <t>Although the solution relies on the JSON, the encoding into Diameter AVPs
     differ from the text based encoding of the JSON objects. Specifically, none 
     of of the the JWE Header, the JWE Encrypted Key, the JWE Initialization
     Vector and the JWE Ciphertext are not BASE64 encoded but 
     are processed in their plaintext or binary representation formats. The 
     concept follows what was already described in <xref target="sig-example"/>.
    </t>
   
   <t>A single AVP or an entire list of AVPs MUST be input to the encryption 
    process, from the first byte of the AVP code to the last byte of the AVP 
    data, including all other fields, length, reserved/flags, and optional
    vendor IDs, and padding. The AVP MUST be input to the encryption
    process in network byte order, and the encryptor is free to order
    AVPs whatever way it chooses.   When AVPs are to be both encrypted and 
    authenticated, the Encrypted-Data AVP MUST be created first.
   </t>

   <t>Note that the usage of the Encrypted-Data AVP requires explicit support by 
    the Diameter application since a receiving Diameter node must first decrypt 
    the content of the Encrypted-Data AVP in order to evaluate the AVPs carried 
    in the message. In case that a Diameter node is unable to understand 
    the Encrypted-Data AVP and ignores the AVP then two possible outcomes are 
    possible: First, if the encrypted AVPs are optional then their content is 
    not considered by the receiving Diameter server without any indication 
    to the sender that they have not been processes. Worse, in the second case 
    when the encrypted AVPs are mandatory to be processed then the receiving 
    Diameter node will return an error that may not inform the sender about the 
    failure to decrypt the Encrypted-Data AVP. Consequently, the usage of the 
    Encrypted-Data AVP may require changes to the ABNF definition of a Diameter 
    application. 
   </t>
   
   <t> If a receiver detects that the contents of the Encrypted-Data AVP is
    invalid, it SHOULD return the new Result-Code AVP value defined in
    <xref target="error"/>.
   </t> 
  </section> 

  <section title="Definition of the 'End Point'">
   <t>Although this specification claims to introduce the end-to-end security
    into Diameter, the definition who actually is the 'end point' is not 
    obvious. The 'end point' does not need to be the original Diameter request
    or answer originator but the Diameter node that inserts the Signed-Data or
    the Encrypted-Data AVPs into the Diameter message. The node can be the
    request or answer originator or a proxy agent. Use of proxy agents doing the
    'end-to-end' security on behalf of other nodes mimics the deployments where
    site-to-site VPNs are used.
   </t>
  </section>

 </section>

 <section title="AVP Encoding">  
  <section title="Signed-Data AVP"> 
   <t>The Signed-Data AVP (AVP Code TBD1) is of type Grouped and
    utilizes the JSON Web signature (JWS) mechanism defined in 
    <xref target="I-D.ietf-jose-json-web-signature"/>. The JWS payload
    is then encoded into the Signed-Data AVP:

    <figure><artwork><![CDATA[
Signed-Data  ::= < AVP Header: TBD1 >
                 { JWS-Header }
               * { JWS-AVP-Payload }
                 { JWS-Signature }
               * [ AVP ]
    ]]></artwork></figure>
   </t> 
  </section>

  <section title="JWS-Header AVP">
   <t>The JWS-Header AVP (AVP Code TBD2) is of type UTF8String and contains the
    JSON Web Signature Header. The contents of the AVP follow the rules for the
    header found in <xref target="I-D.ietf-jose-json-web-signature"/>, which 
    implies the required IANA registries are also defined by JSON documents.
    <figure><artwork><![CDATA[
JWS-Header  ::= < AVP Header: TBD2 >
                { Header-Parameters }
              * [ AVP ]
    ]]></artwork></figure>
   </t>
   <t>The "alg" is the only REQUIRED Header Parameter for the signature 
    purposes. The "typ" and "kid" Header Parameters are also RECOMMENDED.
   </t>
  </section>

  <section title="Header-Parameters AVP">
   <t>The Header-Parameters AVP (AVP Code TBD3) is of type UTF8String and
    contains the JSON Header Parameter Name and its value as described in 
    <xref target="I-D.ietf-jose-json-web-signature"/>. The encoding (textual)
    also follows <xref target="I-D.ietf-jose-json-web-signature"/>. Differing
    from the JSON specifications the  parameter names and values are not BASE64 
    encoded but in their original UTF-8 representation format.
   </t>
  </section>

  <section title="JWS-AVP-Payload AVP" anchor="jws-payload">
   <t>The JWS-AVP-Payload AVP (AVP Code TBD4) is of type OctetString and
    contains both an AVP Code and a hash of the entire AVP identified by the 
    AVP Code. The first four octets contain the AVP Code in a network byte order
    followed by the hash octets. The length of the hash octets depends on the
    used hash algorithm.
   </t>
  </section>

  <section title="JWS-Signature AVP" anchor="jws-signature">
   <t>The JWS-Signature AVP (AVP Code TBD5) is of type OctetString and
    contains the signature calculated over the array of complete JWS-AVP-Payload
    AVPs (including AVP header fields etc) in 
    the order they appear in the Signed-Data AVP. The length of the signature
    octets depends on the used signature algorithm.
   </t>
  </section>

  <section title="Encrypted-Data AVP"> 
   <t>The Encrypted-Data AVP (AVP Code TBD6) is of type Grouped and
    utilizes the JSON Web Encryption (JWE) mechanism defined in 
    <xref target="I-D.ietf-jose-json-web-encryption"/>. The JWE payload
    is then encoded into the Encrypted-Data AVP:

    <figure><artwork><![CDATA[
Encrypted-Data  ::= < AVP Header: TBD1 >
                    { JWE-Header }
                    { JWE-Enc-Key }
                    [ JWE-Init-Vec ]
                    { JWE-AVP-Ciphertext }
                  * [ AVP ]
    ]]></artwork></figure>
   </t> 
  </section>
  
  <section title="JWE-Header AVP">
   <t>The JWE-Header AVP (AVP Code TBD7) is of type UTF8String and contains the
    JSON Web Encryption Header. The contents of the AVP follow the rules for the
    header found in <xref target="I-D.ietf-jose-json-web-encryption"/>, which 
    implies the required IANA registries are also defined by JSON documents.
    <figure><artwork><![CDATA[
JWE-Header  ::= < AVP Header: TBD7 >
                { Header-Parameters }
              * [ AVP ]
    ]]></artwork></figure>
   </t>
   <t>The "alg" and "enc" are the REQUIRED Header Parameter for the encryption 
    purposes. The "typ" and "kid" Header Parameters are also RECOMMENDED.
   </t>
  </section>

  <section title="JWE-Enc-Key AVP">
   <t>The JWE-Enc-Key AVP (AVP Code TBD8) is of type OctetString and
    contains the JWE Encrypted Key in its binary format.
   </t>
  </section>

  <section title="JWE-Init-Vec AVP">
   <t>The JWE-Init-Vec AVP (AVP Code TBD9) is of type OctetString and
    contains the JWE Initialization Vector in its binary format.
   </t>
  </section>


  <section title="JWE-AVP-Ciphertext AVP">
   <t>The JWE-AVP-Ciphertext AVP (AVP Code TBD10) is of type OctetString and
    contains the encrypted AVPs. The encrypted AVPs are first concatenated into
    one large plaintext octet blob and then encrypted as a whole. The length of
    the  ciphertext  depends on the used algorithm and encrypted AVPs. The 
    plaintext to be encrypted is never BASE64 encoded but MAY be compressed if a
    "zip" parameter was included in the JWE Header.
   </t>
  </section>
 </section>

     

    <!-- ******************************************************************************* -->


 <section anchor="error" title="Result-Code AVP Values"> 
  <t>This section defines new Diameter result code values for usage with 
   Diameter applications.
  </t> 
   
  <section title="Transient Failures"> 
   <t>Errors that fall within the transient failures category are used to
    inform a peer that the request could not be satisfied at the time it
    was received, but MAY be able to satisfy the request in the future.
   </t>
      
   <t><list style="hanging"> 
   <t hangText="DIAMETER_KEY_UNKNOWN (TBD11)"><vspace blankLines="1"/>
         This error code is returned when a Signed-Data or an 
         Encrypted-Data AVP is received that was generated using a key
         that cannot be found in the key store. This error may, for example, 
         be caused if 
         one of the endpoints of an end-to-end security association lost
         a previously agreed upon key, perhaps as a result of a reboot.
         To recover a new end-to-end key establishment procedure may need to
         be invoked. 
   </t>
   <t hangText="DIAMETER_HEADER_NAME_ERROR (TBD12)"><vspace blankLines="1"/>
         This error code is returned when a Header Parameter Name is not
         understood in the JWS-Header AVP or in the JWE-Header AVP.
   </t>
   </list> 
   </t>
   
   </section> 

   <section title="Permanent Failures">

   <t>
   Errors that fall within the permanent failures category are used to
   inform the peer that the request failed, and should not be attempted
   again.
   </t>

   <t><list style="hanging"> 
   <t hangText="DIAMETER_DECRYPTION_ERROR (TBD13)"><vspace blankLines="1"/>
         This error code is returned when an Encrypted-Data AVP is received
         and the decryption fails for an unknown reason.
         </t>
   <t hangText="DIAMETER_SIGNATURE_ERROR (TBD14)"><vspace blankLines="1"/>
         This error code is returned when a Signed-Data AVP is received
         and the verification fails for an unknown reason.
         </t>
   </list> 
   </t>
   
   </section>       

</section> 

    <!-- ******************************************************************************* -->

    <section title="IANA Considerations">
      <t>IANA is requested to allocate AVP codes for the following AVPs:
               <figure>
                    <artwork><![CDATA[
+------------------------------------------------------------------+
|                                     AVP    Section               |
|AVP Name                             Code   Defined   Data Type   |
+------------------------------------------------------------------+
|Signed-Data                          TBD1   3.1       Grouped     |
|JWS-Header                           TBD2   3.x       Grouped     |
|JWS-AVP-Paylaod                      TBD3   3.x       OctetString |
|JSW-Signature                        TBD4   3.x       OctetString |
|Header-Parameters                    TBD5   3.x       UTF8String  |
|Encrypted-Data                       TBD6   3.x       Grouped     |
|JWE-Header                           TBD7   3.x       Grouped     |
|JWE-Enc-Key                          TBD8   3.x       OctetString |
|JWE-Init-Vec                         TBD9   3.x       OctetString |
|JWE-AVP-Ciphertext                   TBD10  3.x       OctetString |
+------------------------------------------------------------------+
]]></artwork>
         </figure>
      </t>
      <t>This specification additionally defines a few Result-Code AVP values, see 
      <xref target="error"/>.</t>
    </section>

    <!-- ******************************************************************************* -->

    <section title="Security Considerations">
      <t>The purpose of this document is to offer end-to-end security mechanisms 
      for calculating keyed message digest, for signing, and for encryption of 
      Diameter AVPs.
      </t>
      <t>An intermediate Diameter agent that for a reason or other reorders
       the AVPs within the Signed-Data AVP may cause the signature verification
       fail even if no AVP was actually tampered.
      </t>
    </section>

    <!-- ******************************************************************************* -->

    <section title="Acknowledgements">
      <t>We would like to thank the authors of <xref target="I-D.ietf-aaa-diameter-e2e-sec"/> for their work on 
      CMS end-to-end security for Diameter. Their document inspired us. </t>
    </section>

    <!-- ******************************************************************************* -->

  </middle>

  <back>
    <references title="Normative References">
      &RFC2119;
      &RFC6733;
      &I-D.ietf-jose-json-web-signature;
      &I-D.ietf-jose-json-web-encryption;
    </references>

    <references title="Informational References">   
     <reference anchor="I-D.ietf-aaa-diameter-e2e-sec">
      <front>
       <title>Diameter End-2-End Security Extension</title>
       <author fullname="Pat Calhoun" initials="P." surname="Calhoun"> </author>
       <date year="2001"/>
      </front>
      <format type="TXT" target="http://tools.ietf.org/html/draft-ietf-aaa-diameter-e2e-sec-02"/>
     </reference>

      &RFC5866;
    </references>
   </back>
</rfc>
