doc: Add RFC documents

1 files changed, 619 insertions, 0 deletions

diff --git a/doc/rfc/rfc6786.txt b/doc/rfc/rfc6786.txt
new file mode 100644
index 0000000..0193b25
--- /dev/null
+++ b/doc/rfc/rfc6786.txt
@@ -0,0 +1,619 @@
+
+
+
+
+
+
+Internet Engineering Task Force (IETF)                          A. Yegin
+Request for Comments: 6786                                       Samsung
+Category: Standards Track                                      R. Cragie
+ISSN: 2070-1721                                           Gridmerge Ltd.
+                                                           November 2012
+
+
+        Encrypting the Protocol for Carrying Authentication for
+              Network Access (PANA) Attribute-Value Pairs
+
+Abstract
+
+   This document specifies a mechanism for delivering the Protocol for
+   Carrying Authentication for Network Access (PANA) Attribute-Value
+   Pairs (AVPs) in encrypted form.
+
+Status of This Memo
+
+   This is an Internet Standards Track document.
+
+   This document is a product of the Internet Engineering Task Force
+   (IETF).  It represents the consensus of the IETF community.  It has
+   received public review and has been approved for publication by the
+   Internet Engineering Steering Group (IESG).  Further information on
+   Internet Standards is available in Section 2 of RFC 5741.
+
+   Information about the current status of this document, any errata,
+   and how to provide feedback on it may be obtained at
+   http://www.rfc-editor.org/info/rfc6786.
+
+Copyright Notice
+
+   Copyright (c) 2012 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.
+
+
+
+
+
+
+
+Yegin & Cragie               Standards Track                    [Page 1]
+
+RFC 6786                   PANA AVP Encryption             November 2012
+
+
+Table of Contents
+
+   1. Introduction ....................................................2
+      1.1. Specification of Requirements ..............................2
+   2. Details .........................................................3
+   3. Encryption Keys .................................................3
+   4. Encryption-Algorithm AVP ........................................4
+      4.1. AES128_CTR Encryption Algorithm ............................5
+   5. Encryption-Encap AVP ............................................6
+   6. Encryption Policy ...............................................6
+      6.1. Encryption Policy Specification ............................7
+   7. Security Considerations .........................................8
+      7.1. AES-CTR Security Considerations ............................9
+   8. IANA Considerations .............................................9
+      8.1. PANA AVP Codes .............................................9
+      8.2. PANA Encryption-Algorithm AVP Values .......................9
+      8.3. PANA AVP Codes Encryption Policy ..........................10
+   9. Acknowledgments ................................................10
+   10. Normative References ..........................................10
+
+1.  Introduction
+
+   PANA [RFC5191] is a UDP-based protocol to perform an Extensible
+   Authentication Protocol (EAP) authentication between a PANA Client
+   (PaC) and a PANA Authentication Agent (PAA).
+
+   Various types of payload are exchanged as part of the network access
+   authentication and authorization.  These payloads are carried in PANA
+   Attribute-Value Pairs (AVPs).  AVPs can be integrity protected using
+   the AUTH AVP when EAP authentication generates cryptographic keying
+   material.  AVPs are transmitted in the clear (i.e., not encrypted).
+
+   Certain payload types need to be delivered privately (e.g., network
+   keys, private identifiers, etc.).  This document defines a mechanism
+   for applying encryption to selected AVPs.
+
+1.1.  Specification of Requirements
+
+   In this document, several words are used to signify the requirements
+   of the specification.  These words are often capitalized.  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 [RFC2119].
+
+
+
+
+
+
+
+
+Yegin & Cragie               Standards Track                    [Page 2]
+
+RFC 6786                   PANA AVP Encryption             November 2012
+
+
+2.  Details
+
+   This document extends the AVP set defined in Section 8 of [RFC5191]
+   by defining two new AVPs: the Encryption-Algorithm AVP (see Section
+   4) and the Encryption-Encap AVP (see Section 5).  Two new encryption
+   keys, PANA_PAC_ENCR_KEY and PANA_PAA_ENCR_KEY, are defined to encrypt
+   AVPs from the PaC to the PAA and AVPs from the PAA to the PaC,
+   respectively (see Section 3).
+
+   When encryption is needed, the required algorithm is negotiated as
+   follows: the PAA SHALL send the initial PANA-Auth-Request carrying
+   one or more Encryption-Algorithm AVPs supported by it.  The PaC SHALL
+   select one of the algorithms from this AVP, and it SHALL respond with
+   the initial PANA-Auth-Answer carrying one Encryption-Algorithm AVP
+   for the selected algorithm.  Once PANA_PAC_ENCR_KEY and
+   PANA_PAA_ENCR_KEY have been generated, a PANA message MAY contain an
+   Encryption-Encap AVP.
+
+3.  Encryption Keys
+
+   PANA_PAC_ENCR_KEY is used for encrypting the AVP payload of the
+   Encryption-Encap AVP sent in a PANA message from the PaC to the PAA.
+
+   PANA_PAC_ENCR_KEY SHALL be computed according to the following
+   formula:
+
+   PANA_PAC_ENCR_KEY = prf+(MSK, "IETF PANA PaC Encr" | I_PAR |
+                         I_PAN | PaC_nonce | PAA_nonce | Key_ID)
+
+   PANA_PAA_ENCR_KEY is used for encrypting the AVP payload of the
+   Encryption-Encap AVP sent in a PANA message from the PAA to the PaC.
+   PANA_PAA_ENCR_KEY SHALL be computed according to the following
+   formula:
+
+   PANA_PAA_ENCR_KEY = prf+(MSK, "IETF PANA PAA Encr" | I_PAR |
+                         I_PAN | PaC_nonce | PAA_nonce | Key_ID)
+
+   In both cases:
+
+      -  The prf+ function is defined in the Internet Key Exchange
+         Protocol version 2 (IKEv2) [RFC5996].
+
+      -  The pseudo-random function (PRF) to be used for the prf+
+         function SHALL be negotiated using the PRF-Algorithm AVP in the
+         initial PANA-Auth-Request and PANA-Auth-Answer exchange with
+         the 'S' (Start) bit set as described in Section 4.1 of
+         [RFC5191].
+
+
+
+
+Yegin & Cragie               Standards Track                    [Page 3]
+
+RFC 6786                   PANA AVP Encryption             November 2012
+
+
+      -  MSK is the master session key (MSK) generated by the EAP method
+         [RFC3748].  PANA_PAC_ENCR_KEY and PANA_PAA_ENCR_KEY MUST be
+         recalculated whenever a new MSK is generated by the EAP method.
+
+      -  "IETF PANA PaC Encr" and "IETF PANA PAA Encr" are the ASCII
+         code representations of the respective non-NULL terminated
+         strings (excluding the double quotes around them).
+
+      -  I_PAR and I_PAN are the initial PANA-Auth-Request and
+         PANA-Auth-Answer messages (the PANA header and the following
+         PANA AVPs) with the 'S' (Start) bit set, respectively.
+
+      -  PaC_nonce and PAA_nonce are values of the Nonce AVP carried in
+         the first non-initial PANA-Auth-Answer and PANA-Auth-Request
+         messages in the authentication and authorization phase or the
+         first PANA-Auth-Answer and PANA-Auth-Request messages in the
+         re-authentication phase, respectively.
+
+      -  Key_ID is the value of the Key-Id AVP.
+
+   The length of PANA_PAC_ENCR_KEY and PANA_PAA_ENCR_KEY depends on the
+   encryption algorithm in use.
+
+4.  Encryption-Algorithm AVP
+
+   The Encryption-Algorithm AVP (AVP code 13) is used for conveying the
+   encryption algorithm to be used with the Encryption-Encap AVP.  The
+   AVP value data is of type Unsigned32.
+
+   Only one encryption algorithm identifier AES128_CTR (code 1) is
+   identified by this document.  Encryption algorithm identifier values
+   other than 1 are reserved for future use.  Future specifications are
+   allowed to extend this list.
+
+      AES128_CTR: 1
+
+   In the absence of an application profile specifying otherwise, all
+   implementations SHALL support AES128_CTR.
+
+
+
+
+
+
+
+
+
+
+
+
+
+Yegin & Cragie               Standards Track                    [Page 4]
+
+RFC 6786                   PANA AVP Encryption             November 2012
+
+
+4.1.  AES128_CTR Encryption Algorithm
+
+   The AES128_CTR encryption algorithm uses the AES-CTR (Counter) mode
+   of operation as specified in [NIST_SP800_38A] using the AES-128 block
+   cipher.  The formatting function and counter generation function, as
+   specified in Appendix A of [NIST_SP800_38C], are used with the
+   following parameters:
+
+         n = 12,
+         q = 3
+
+   The 12-octet nonce consists of a 4-octet Key-Id, a 4-octet Session
+   ID, and a 4-octet Sequence Number in that order where each 4-octet
+   value is encoded in network byte order.  The Session ID and Sequence
+   Number values SHALL be the same as those in the PANA message carrying
+   the key Encryption-Encap AVP.  The Key-Id value SHALL be the same as
+   the one used for deriving PANA_PAC_ENCR_KEY and PANA_PAA_ENCR_KEY.
+   The output blocks of the encryption processing are encoded as
+   OctetString data in the Value field of a Encryption-Encap AVP.
+
+   Note that the first counter block used for encryption is Ctr_1, where
+   "_1" denotes "subscript 1" as described in Appendix A.3 of
+   [NIST_SP800_38C].  For example, given the following:
+
+         Key-Id = 0x55667788,
+         Session ID = 0xaabbccdd,
+         Sequence Number = 0x11223344
+
+   The first counter block used for encryption will be:
+
+         0x0255667788aabbccdd11223344000001
+
+   where the initial 0x02 represents the Flags field of the counter
+   block.
+
+   The nonce meets the requirement of uniqueness-per-key usage provided
+   that the sequence number does not wrap.  Therefore, for the purpose
+   of generating new keys:
+
+      -  If Encryption-Encap AVPs are being sent from the PaC to the PAA
+         and the sequence number is about to wrap, the PaC SHALL
+         initiate PANA re-authentication as described in Section 4.3 of
+         [RFC5191].
+
+      -  If Encryption-Encap AVPs are being sent from the PAA to the PaC
+         and the sequence number is about to wrap, the PAA SHALL
+         initiate PANA re-authentication as described in Section 4.3 of
+         [RFC5191].
+
+
+
+Yegin & Cragie               Standards Track                    [Page 5]
+
+RFC 6786                   PANA AVP Encryption             November 2012
+
+
+   Re-authentication ensures the generation of a new MSK [RFC3748] and
+   thus a new PANA_PAC_ENCR_KEY and PANA_PAA_ENCR_KEY.
+
+5.  Encryption-Encap AVP
+
+   The Encryption-Encap AVP (AVP code 12) is used to encrypt one or more
+   PANA AVPs.  The format of the Encryption-Encap AVP depends on the
+   negotiated encryption algorithm.
+
+   When the negotiated encryption algorithm identifier is AES128_CTR
+   (code 1), AVP data payload is occupied by the encrypted AVPs.
+
+   There SHALL be only one Encryption-Encap AVP in a PANA message.  All
+   AVPs that require encryption SHALL be encapsulated within the
+   Encryption-Encap AVP.
+
+   The Encryption-Encap AVP uses either PANA_PAC_ENCR_KEY or
+   PANA_PAA_ENCR_KEY, and the encryption algorithm negotiated by the
+   Encryption-Algorithm AVP.  The Encryption-Encap AVP SHALL only be
+   used if the EAP method generates cryptographic keys (specifically,
+   the MSK [RFC3748]).
+
+   The Encryption-Encap AVP MAY be used in a PANA message from the PaC
+   to the PAA when the encryption algorithm has been successfully
+   negotiated and once PANA_PAC_ENCR_KEY has been generated.
+
+   The Encryption-Encap AVP MAY be used in a PANA message from the PAA
+   to the PaC when the encryption algorithm has been successfully
+   negotiated and once PANA_PAA_ENCR_KEY has been generated.
+
+   The Encryption-Encap AVP MAY be used in the very first PANA message
+   carrying the Result-Code AVP set to PANA_Success value and any
+   subsequent message within the same PANA session.
+
+6.  Encryption Policy
+
+   The specification of any AVP SHOULD state that the AVP either shall
+   or shall not be encrypted using the Encryption-Encap AVP.  The
+   specification of an AVP MAY state that the AVP may (or may not) be
+   encrypted using the Encryption-Encap AVP.  The specification SHOULD
+   use a table in the format specified in Section 6.1.  If the
+   specification of an AVP is silent about whether the AVP shall or
+   shall not be encrypted using the Encryption-Encap AVP, this implies
+   that the AVP MAY be encrypted using the Encryption-Encap AVP.
+
+
+
+
+
+
+
+Yegin & Cragie               Standards Track                    [Page 6]
+
+RFC 6786                   PANA AVP Encryption             November 2012
+
+
+6.1.  Encryption Policy Specification
+
+   This section defines a table format for the specification of whether
+   an AVP shall or shall not be encrypted using the Encryption-Encap
+   AVP.
+
+   The table uses the following symbols:
+
+   Y: The AVP SHALL be encrypted using the Encryption-Encap AVP.  If the
+      AVP is encountered not encrypted using the Encryption-Encap AVP,
+      it SHALL be considered invalid and the message containing the AVP
+      SHALL be discarded.
+
+   N: The AVP SHALL NOT be encrypted using the Encryption-Encap AVP.  If
+      the AVP is encountered encrypted using the Encryption-Encap AVP,
+      it SHALL be considered invalid and the message containing the AVP
+      SHALL be discarded.
+
+   X: The AVP MAY be encrypted using the Encryption-Encap AVP.  If the
+      AVP is encountered either encrypted or not encrypted using the
+      Encryption-Encap AVP, it SHALL be considered valid.
+
+   The legitimate occurrence of unencrypted AVPs and AVPs after
+   decryption and unencapsulation SHALL be subject to the AVP Occurrence
+   Table (Figure 4 in [RFC5191]).
+
+   The following table shows the encryption requirements for the
+   existing AVPs defined in [RFC5191]:
+
+            Attribute Name        |Enc|
+            ----------------------+---+
+            AUTH                  | N |
+            EAP-Payload           | X |
+            Integrity-Algorithm   | N |
+            Key-Id                | N |
+            Nonce                 | N |
+            PRF-Algorithm         | N |
+            Result-Code           | N |
+            Session-Lifetime      | X |
+            Termination-Cause     | X |
+            ----------------------+---+
+
+
+
+
+
+
+
+
+
+
+Yegin & Cragie               Standards Track                    [Page 7]
+
+RFC 6786                   PANA AVP Encryption             November 2012
+
+
+   The following table shows the encryption requirements for the AVPs
+   defined in [RFC6345]:
+
+            Attribute Name        |Enc|
+            ----------------------+---+
+            PaC-Information       | N |
+            Relayed-Message       | N |
+            ----------------------+---+
+
+   The following table shows the encryption requirements for the AVPs
+   defined in this document:
+
+            Attribute Name        |Enc|
+            ----------------------+---+
+            Encryption-Algorithm  | N |
+            Encryption-Encap      | N |
+            ----------------------+---+
+
+   The following table is an example showing the encryption requirements
+   for a newly defined AVP, Example-AVP:
+
+            Attribute Name        |Enc|
+            ----------------------+---+
+            Example-AVP           | Y |
+            ----------------------+---+
+
+   The guidance for specifying the encryption requirements for a newly
+   defined AVP is as follows:
+
+   Y: If the payload needs privacy against eavesdroppers (e.g., carrying
+      a secret key).
+
+   N: If the payload may need to be observed by on-path network elements
+      (i.e., subject to deep packet inspection).
+
+   X: If neither concern applies.
+
+7.  Security Considerations
+
+   PANA_PAC_ENCR_KEY and PANA_PAA_ENCR_KEY are secret keys shared
+   between the PaC and the PAA.  They SHALL NOT be used for purposes
+   other than those specified in this document.  Compromise of these
+   keys would lead to compromise of the secret information protected by
+   these keys.
+
+
+
+
+
+
+
+Yegin & Cragie               Standards Track                    [Page 8]
+
+RFC 6786                   PANA AVP Encryption             November 2012
+
+
+7.1.  AES-CTR Security Considerations
+
+   The use of AES-CTR encryption has its own security considerations,
+   which are detailed in the Security Considerations section of
+   [RFC3686].  Specifically:
+
+      -  The nonce specified in Section 4.1 meets the requirement of
+         uniqueness-per-key usage.
+
+      -  Section 4.1 of [RFC5191] states that if the EAP method
+         generates cryptographic keys, an AUTH AVP will always be
+         present in every PANA message after key generation.  Therefore,
+         an Encryption-Encap AVP will always be sent in conjunction with
+         an AUTH AVP.  This meets the requirement of a companion
+         authentication function.
+
+8.  IANA Considerations
+
+   As described in Sections 4 and 5, and following the IANA allocation
+   policy on PANA messages [RFC5872], two PANA AVP codes and one set of
+   AVP values have been registered.  An additional encryption policy for
+   AVP codes has also been registered.
+
+8.1.  PANA AVP Codes
+
+   The following AVP codes have been registered in the "AVP Codes" sub-
+   registry of the "Protocol for Carrying Authentication for Network
+   Access (PANA) Parameters" registry:
+
+   o  A standard AVP code of 12 for the Encryption-Encap AVP.
+
+   o  A standard AVP code of 13 for the Encryption-Algorithm AVP.
+
+8.2.  PANA Encryption-Algorithm AVP Values
+
+   The following AVP values representing the encryption algorithm
+   identifier for the Encryption-Algorithm AVP code have been assigned
+   in the "Encryption-Algorithm (AVP Code 13) AVP Values" sub-registry
+   under the "Protocol for Carrying Authentication for Network Access
+   (PANA) Parameters" registry":
+
+   o  An AVP value of 1 for AES128_CTR.
+
+   o  All other AVP values (0, 2-4294967295) are unassigned.
+
+   The registration procedures are IETF Review or IESG Approval in
+   accordance with [RFC5872].
+
+
+
+
+Yegin & Cragie               Standards Track                    [Page 9]
+
+RFC 6786                   PANA AVP Encryption             November 2012
+
+
+8.3.  PANA AVP Codes Encryption Policy
+
+   The additional encryption policy defined in Section 6.1 has been
+   added as a column labeled "Enc" in the "AVP Codes" sub-registry and
+   has been applied to all existing AVP codes and those defined in this
+   specification.
+
+9.  Acknowledgments
+
+   The authors would like to thank Yoshihiro Ohba, Yasuyuki Tanaka,
+   Adrian Farrel, Brian Carpenter, Yaron Sheffer, Ralph Droms, Stephen
+   Farrell, Barry Leiba, and Sean Turner for their valuable comments.
+
+10.  Normative References
+
+   [NIST_SP800_38A]
+              Dworkin, M., "Recommendation for Block Cipher Modes of
+              Operation: Methods and Techniques", December 2001.
+
+   [NIST_SP800_38C]
+              Dworkin, M., "Recommendation for Block Cipher Modes of
+              Operation: The CCM Mode for Authentication and
+              Confidentiality", May 2004.
+
+   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
+              Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+   [RFC3686]  Housley, R., "Using Advanced Encryption Standard (AES)
+              Counter Mode With IPsec Encapsulating Security Payload
+              (ESP)", RFC 3686, January 2004.
+
+   [RFC3748]  Aboba, B., Blunk, L., Vollbrecht, J., Carlson, J., and H.
+              Levkowetz, Ed., "Extensible Authentication Protocol
+              (EAP)", RFC 3748, June 2004.
+
+   [RFC5191]  Forsberg, D., Ohba, Y., Ed., Patil, B., Tschofenig, H.,
+              and A. Yegin, "Protocol for Carrying Authentication for
+              Network Access (PANA)", RFC 5191, May 2008.
+
+   [RFC5872]  Arkko, J. and A. Yegin, "IANA Rules for the Protocol for
+              Carrying Authentication for Network Access (PANA)", RFC
+              5872, May 2010.
+
+   [RFC5996]  Kaufman, C., Hoffman, P., Nir, Y., and P. Eronen,
+              "Internet Key Exchange Protocol Version 2 (IKEv2)", RFC
+              5996, September 2010.
+
+
+
+
+
+Yegin & Cragie               Standards Track                   [Page 10]
+
+RFC 6786                   PANA AVP Encryption             November 2012
+
+
+   [RFC6345]  Duffy, P., Chakrabarti, S., Cragie, R., Ohba, Y., Ed., and
+              A. Yegin, "Protocol for Carrying Authentication for
+              Network Access (PANA) Relay Element", RFC 6345, August
+              2011.
+
+Authors' Addresses
+
+   Alper Yegin
+   Samsung
+   Istanbul
+   Turkey
+
+   EMail: alper.yegin@yegin.org
+
+
+   Robert Cragie
+   Gridmerge Ltd.
+   89 Greenfield Crescent
+   Wakefield, WF4 4WA
+   United Kingdom
+
+   EMail: robert.cragie@gridmerge.com
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Yegin & Cragie               Standards Track                   [Page 11]
+