ICNRG M. Mosko Internet-Draft PARC, Inc. Intended status: Experimental January 9, 2015 Expires: July 13, 2015 CCNx Messages in TLV Format draft-mosko-icnrg-ccnxmessages-00 Abstract This document specifies the encoding of CCNx messages using a TLV Packet specification. CCNx messages follow the CCNx Semantics specification described in [draft-mosko-icnrg-ccnxsemantics-00]. This document defines the TLV types used by each message element and the encoding of each value. Status of this Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on July 13, 2015. Copyright Notice Copyright (c) 2015 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. Mosko Expires July 13, 2015 [Page 1] Internet-Draft CCNx TLV January 2015 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 4 2. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 5 3. Type-Length-Value (TLV) Packets . . . . . . . . . . . . . . . 6 3.1. Overall packet format . . . . . . . . . . . . . . . . . . 6 3.2. Fixed Headers . . . . . . . . . . . . . . . . . . . . . . 7 3.2.1. Interest Fixed Header . . . . . . . . . . . . . . . . 8 3.2.1.1. Interest HopLimit . . . . . . . . . . . . . . . . 8 3.2.1.2. Interest Flags . . . . . . . . . . . . . . . . . . 9 3.2.2. Content Object Fixed Header . . . . . . . . . . . . . 9 3.2.2.1. Content Object Flags . . . . . . . . . . . . . . . 9 3.2.3. InterestReturn Fixed Header . . . . . . . . . . . . . 9 3.2.3.1. Interest HopLimit . . . . . . . . . . . . . . . . 10 3.2.3.2. Interest Flags . . . . . . . . . . . . . . . . . . 10 3.2.3.3. Return Code . . . . . . . . . . . . . . . . . . . 10 3.2.4. Vendor Extensions . . . . . . . . . . . . . . . . . . 10 3.3. Hop-by-hop TLV headers . . . . . . . . . . . . . . . . . . 11 3.3.1. Lifetime . . . . . . . . . . . . . . . . . . . . . . . 11 3.3.2. Recommended Cache Time . . . . . . . . . . . . . . . . 11 3.4. Top-Level Types . . . . . . . . . . . . . . . . . . . . . 12 3.5. Global Formats . . . . . . . . . . . . . . . . . . . . . . 13 3.6. CCNx Message . . . . . . . . . . . . . . . . . . . . . . . 13 3.6.1. Name . . . . . . . . . . . . . . . . . . . . . . . . . 14 3.6.1.1. Name Segments . . . . . . . . . . . . . . . . . . 15 3.6.1.2. Interest Payload ID . . . . . . . . . . . . . . . 16 3.6.2. Metadata . . . . . . . . . . . . . . . . . . . . . . . 16 3.6.2.1. Interest Metadata . . . . . . . . . . . . . . . . 16 3.6.2.2. Content Object Metadata . . . . . . . . . . . . . 18 3.6.3. Payload . . . . . . . . . . . . . . . . . . . . . . . 20 3.7. Validation . . . . . . . . . . . . . . . . . . . . . . . . 20 3.7.1. Validation Algorithm . . . . . . . . . . . . . . . . . 21 3.7.1.1. Message Integrity Checks . . . . . . . . . . . . . 22 3.7.1.2. Message Authentication Checks . . . . . . . . . . 23 3.7.1.3. Signature . . . . . . . . . . . . . . . . . . . . 23 3.7.1.4. Validation Dependent Data . . . . . . . . . . . . 23 3.7.1.5. Validation Examples . . . . . . . . . . . . . . . 26 3.7.2. Validation Payload . . . . . . . . . . . . . . . . . . 27 4. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 28 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 29 6. Security Considerations . . . . . . . . . . . . . . . . . . . 30 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 31 7.1. Normative References . . . . . . . . . . . . . . . . . . . 31 7.2. Informative References . . . . . . . . . . . . . . . . . . 31 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 32 Mosko Expires July 13, 2015 [Page 2] Internet-Draft CCNx TLV January 2015 1. Introduction This document specifies the TLV types and value encodings for the CCNx protocol. This draft describes the mandatory and common optional fields of Interests and Content Objects. Several additional protocols specified in their own documents are in use that extend this specification. CCNx specifies a network protocol around Interests (request messages) and Content Objects (response messages) to move named payloads. An Interest includes the Name, two optional restrictions to limit responses to a specific publisher or a specific Content Object, and an optional Payload used to compute a response. The Content Object response carries a matching Name and the specified payload. Matching a Content Object to an Interest is an exact match on the Name. The CCNx network protocol of Interests and Content Objects imposes a restriction on Names: each Name should be hierarchical and is used to route towards an authoritative source. The CCNx Name looks like a URI absolute path and we use URI terminology to describe the absolute path as made up of path segments. A full description of the semantics of CCNx messages, providing an encoding-free description of CCNx messages and message elements, may be found in [draft-mosko-icnrg-ccnxsemantics-00]. In the final draft, the type values will be assigned to be compact. All type values are relative to their parent containers. It is possible for a TLV to redefine a type value defined by its parent. For example, each level of a nested TLV structure might define a "type = 1" with a completely different meaning. This document specifies: o The TLV types used by CCNx messages. o The encoding of values for each type. o Top level types that exist at the outermost containment. o Interest TLVs that exist within Interest containment. o Content Object TLVs that exist within Content Object containment. This document is supplemented by this document: o Message semantics: see [draft-mosko-icnrg-ccnxsemantics-00] for the protocol operation regarding Interest and Content Object, including the Interest Return protocol. Mosko Expires July 13, 2015 [Page 3] Internet-Draft CCNx TLV January 2015 Packets are represented as 32-bit wide words using ASCII art. Due to the nested levels of TLV encoding and the presence of optional fields and variable sizes, there is no concise way to represent all possibilities. We use the convention that ASCII art fields enclosed by vertical bars "|" represent exact bit widths. Fields with a forward slash "/" are variable bit widths, which we typically pad out to word alignment for picture readability. TODO -- we have not adopted the Requirements Language yet. 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 [RFC2119]. Mosko Expires July 13, 2015 [Page 4] Internet-Draft CCNx TLV January 2015 2. Definitions o HSVLI: Hierarchically structured variable length identifier, also called a Name. It is an ordered list of path segments, which may be variable length octet strings. In human-readable form, it is represented in URI format as lci:/path/part. There is no host or query string. o Name: see HSVLI o Interest: A message requesting a Content Object with a matching Name and other optional selectors to choose from multiple objects with the same Name. Any Content Object with a Name and optional selectors that matches the Name and optional selectors of the Interest is said to satisfy the Interest. o Content Object: A data object sent in response to an Interest request. It has an HSVLI Name and a content payload that are bound together via cryptographic means. Mosko Expires July 13, 2015 [Page 5] Internet-Draft CCNx TLV January 2015 3. Type-Length-Value (TLV) Packets We use 16-bit Type and 16-bit Length fields to encode TLV based packets. This provides 64K different possible types and value field lengths of up to 64KiB. With 64K possible types, there should be sufficient space for basic protocol types, while also allowing ample room for experimentation, application use, and growth. In the event that more space is needed, either for types or for length, a new version of the protocol would be needed. 1 2 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +---------------+---------------+---------------+---------------+ | Type | Length | +---------------+---------------+---------------+---------------+ The Length field contains the length of the Value field in octets. It does not include the length of the Type and Length fields. A zero length TLV is permissible. TLV structures are nestable, allowing the Value field of one TLV structure to contain another TLV structure. The enclosing TLV structure is called the container of the enclosed TLV. Type values are context-dependent. Within a TLV container, one may re-use previous type values for new context-dependent purposes. 3.1. Overall packet format Each packet includes the 8 byte fixed header, described below, followed by a set of hop-by-hop headers in TLV format, followed by a payload. The packet payload is a TLV encoding of the CCNx message, followed by the optional Validation TLVs. 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +---------------+---------------+---------------+---------------+ | Version | PacketType | PacketLength | +---------------+---------------+---------------+---------------+ | PacketType specific fields | HeaderLength | +---------------+---------------+---------------+---------------+ / Optional Hop-by-hop header in TLV format / +---------------+---------------+---------------+---------------+ | CCNx Message TLV / +---------------+---------------+---------------+---------------+ / Optional CCNx ValidationAlgorithm TLV / +---------------+---------------+---------------+---------------+ / Optional CCNx ValidationPayload TLV (ValidationAlg required) / Mosko Expires July 13, 2015 [Page 6] Internet-Draft CCNx TLV January 2015 +---------------+---------------+---------------+---------------+ This document describes the Version "1" TLV encoding. After discarding the fixed and hop-by-hop headers the remaining payload should be a valid protocol message. Therefore, the payload always begins with a 4 byte TLV defining the protocol message (whether it is an Interest or a Content Object or a future message type) and its total length. The embedding of a self-sufficient protocol data unit inside the fixed and hop-by-hop headers allows a network stack to discard the headers and operate only on the embedded message. It is acceptable to have a 0-length payload, in which case all signaling is done in the fixed and hop-by-hop headers and PacketLength = HeaderLength. The range of bytes protected by the Validation includes the CCNx Message and the ValidationAlgorithm. The ContentObjectHash begins with the CCNx Message and ends at the tail of the packet. 3.2. Fixed Headers CCNx messages begin with an 8 byte fixed header (in a non-TLV format). The HeaderLength field in the fixed header represents the combined length of the fixed and hop-by-hop headers, therefore the beginning of the protocol message is found at "packet start + HeaderLength". A specific PacketType may assign meaning to the reserved bytes. The payload of a CCNx TLV packet is the protocol message itself. The Content Object Hash is computed over the payload only, excluding the fixed and hop-by-hop headers as those may change from hop to hop. Signed information or Similarity Hashes should not include any of the fixed or hop-by-hop headers. The payload should be self-sufficient in the event that the fixed and hop-by-hop headers are removed. 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +---------------+---------------+---------------+---------------+ | Version | PacketType | PacketLength | +---------------+---------------+---------------+---------------+ | PacketType specific fields | HeaderLength | +---------------+---------------+---------------+---------------+ Mosko Expires July 13, 2015 [Page 7] Internet-Draft CCNx TLV January 2015 o Version: defines the version of the packet. o HeaderLength: The length of the fixed header (8 bytes) and hop-by- hop headers. The minimum value is "8". o PacketType: describes forwarder actions to take on the packet. o PacketLength: Total octets of packet including all headers (fixed header plus hop-by-hop headers) and protocol message. o PacketType Specific Fields: specific PacketTypes define the use of these bits. The PacketType field indicates how the forwarder should process the packet. A Request Packet (Interest) has PacketType 0, a Response (Content Object) has PacketType 1, and an InterestReturn Packet has PacketType 2. HeaderLength is the number of octets from the start of the packet (Version) to the end of the hop-by-hop headers. PacketLength is the number of octets from the start of the packet to the end of the packet. The PacketType specific fields are reserved bits whose use depends on the PacketType. They are used for network-level signaling. 3.2.1. Interest Fixed Header An Interest PacketType defines a HopLimit and Flags fields. It also reserves a byte for a FeedbackCode, used in an InterestReturn PacketType. The reserved field must be set to 0 in an Interest 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +---------------+---------------+---------------+---------------+ | Version | 1 | PacketLength | +---------------+---------------+---------------+---------------+ | HopLimit | Reserved | Flags | HeaderLength | +---------------+---------------+---------------+---------------+ 3.2.1.1. Interest HopLimit For an Interest message, the HopLimit is a counter that is decremented with each hop. It limits the distance an Interest may travel on the network. The node originating the Interest may put in any value - up to the maximum of 255. Each node that receives an Interest with a HopLimit decrements the value upon reception. If the value is 0 after the decrement, the Interest cannot be forwarded off Mosko Expires July 13, 2015 [Page 8] Internet-Draft CCNx TLV January 2015 the node. It is an error to receive an Interest with a 0 hop-limit from a remote node. 3.2.1.2. Interest Flags There are currently no flags defined, so this field must be set to 0. 3.2.2. Content Object Fixed Header A Content Object defines a Flags field. There are currently no flags defined, so bytes 5-7 must be set to 0. 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +---------------+---------------+---------------+---------------+ | Version | 2 | PacketLength | +---------------+---------------+---------------+---------------+ | Reserved | Flags | HeaderLength | +---------------+---------------+---------------+---------------+ 3.2.2.1. Content Object Flags There are currently no flags defined, so this field must be set to 0. 3.2.3. InterestReturn Fixed Header An InterestReturn packet is an Interest packet with the PacketType set to InterestReturn and the Interest Reserved octet set as a ReturnCode. All other fields are unchanged. The purpose of this encoding is to prevent packet length changes so no additional bytes are needed to return an Interest to the previous hop. See [draft-mosko-icnrg-ccnxsemantics-00] for a protocol description of this packet type. 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +---------------+---------------+---------------+---------------+ | Version | 3 | PacketLength | +---------------+---------------+---------------+---------------+ | HopLimit | ReturnCode | Flags | HeaderLength | +---------------+---------------+---------------+---------------+ Mosko Expires July 13, 2015 [Page 9] Internet-Draft CCNx TLV January 2015 3.2.3.1. Interest HopLimit This is the original Interest's HopLimit, as received. It is the value before being decremented at the current node. 3.2.3.2. Interest Flags These are the original Flags as set in the Interest. 3.2.3.3. Return Code The numeric value assigned to the return types is defined below. This value is set by the node creating the Interest Return. A return code of "0" is not allowed, as it indicates that the returning system did not modify the Return Code field. +-------+--------------------+ | Value | Return Type | +-------+--------------------+ | 1 | No Route | | | | | 2 | Hop Limit Exceeded | | | | | 3 | No Resources | | | | | 4 | Path Error | | | | | 5 | Prohibited | | | | | 6 | Congested | | | | | 7 | MTU too large | +-------+--------------------+ Table 1: Return Codes 3.2.4. Vendor Extensions Vendors or other parties may request proprietary TLV types in the Hop-By-Hop headers section or other TLV containers. The vendor then has control of the contents of the the Value, which may be its own binary field or an encapsulated set of TLVs. The inner TLVs, because we use a context-dependent TLV scheme, may be fully defined by the vendor. Mosko Expires July 13, 2015 [Page 10] Internet-Draft CCNx TLV January 2015 3.3. Hop-by-hop TLV headers Hop-by-hop TLV headers are unordered and no meaning should be attached to their ordering. Two hop-by-hop headers - the InterestLifetime for Interests and the RecommendedCacheTime for Content Objects - are described in this document. Additional hop-by- hop headers are defined in higher level specifications such as the fragmentation and chunking specifications. 3.3.1. Lifetime The Interest Lifetime is the time that an Interest should stay pending at an intermediate node. It is expressed in milliseconds as an unsigned, network byte order integer. A value of 0 (encoded as 1 byte %x00) indicates the Interest does not elicit a Content Object response. It should still be forwarded, but no reply is expected. 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +---------------+---------------+---------------+---------------+ | T_INT_LIFE | Length | +---------------+---------------+---------------+---------------+ / / / Lifetime (length octets) / / / +---------------+---------------+---------------+---------------+ 3.3.2. Recommended Cache Time The Recommended Cache Time (RCT) is a measure of the useful lifetime of a Content Object as assigned by a content producer or upstream node.. It serves as a guideline to the Content Store cache in determining how long to keep the Content Object. It is a recommendation only and may be ignored by the cache. This is in contrast to the ExpiryTime (described in Section 3.6.2.2.2)which takes precedence over the RCT and must be obeyed. Because the Recommended Cache Time is an optional hop-by-hop header and not a part of the signed message, a content producer may re-issue a previously signed Content Object with an updated RCT without needing to re-sign the message. There is little ill effect from an attacker changing the RCT as the RCT serves as a guideline only. The Recommended Cache Time (a millisecond timestamp) is a network byte ordered unsigned integer of the number of milliseconds since the epoch in UTC of when the payload expires. It is a 64-bit field. Mosko Expires July 13, 2015 [Page 11] Internet-Draft CCNx TLV January 2015 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +---------------+---------------+---------------+---------------+ | T_CACHE_TIME | 8 | +---------------+---------------+---------------+---------------+ / / / Recommended Cache Time / / / +---------------+---------------+---------------+---------------+ 3.4. Top-Level Types The top-level TLV types listed below exist at the outermost level of a CCNx protocol message. +--------+----------------------+-----------------+-----------------+ | Type | Abbrev | Name | Description | +--------+----------------------+-----------------+-----------------+ | %x0001 | T_INTEREST | Interest | An Interest | | | | (Section 3.6) | MessageType. | | | | | | | %x0002 | T_OBJECT | Content Object | A Content | | | | (Section 3.6) | Object | | | | | MessageType | | | | | | | %x0003 | T_VALIDATION_ALG | Validation | The method of | | | | Algorithm | message | | | | (Section 3.7.1) | verification | | | | | such as Message | | | | | Integrity Check | | | | | (MIC), a | | | | | Message | | | | | Authentication | | | | | Code (MAC), or | | | | | a cryptographic | | | | | signature. | | | | | | | %x0004 | T_VALIDATION_PAYLOAD | Validation | The validation | | | | Payload | output, such as | | | | (Section 3.7.2) | the CRC32C code | | | | | or the RSA | | | | | signature. | +--------+----------------------+-----------------+-----------------+ Table 2: CCNx Top Level Types Mosko Expires July 13, 2015 [Page 12] Internet-Draft CCNx TLV January 2015 3.5. Global Formats The pad type may be used by protocols that prefer word-aligned data. The size of the word may be defined by the protocol. Padding 4-byte words, for example, would use a 1-byte, 2-byte, and 3-byte Length. Padding 8-byte words would use a (0, 1, 2, 3, 5, 6, 7)-byte Length. A pad may be inserted after any TLV except within a Name TLV. In the remainder of this document, we will not show optional pad TLVs. 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +---------------+---------------+---------------+---------------+ | T_PAD | Length | +---------------+---------------+---------------+---------------+ / variable length pad MUST be zeros / +---------------+---------------+---------------+---------------+ 3.6. CCNx Message This is the format for the CCNx protocol message itself. The CCNx message is the portion of the packet between the hop-by-hop headers and the Validation TLVs. The figure below is an expansion of the "CCNx Message TLV" depicted in the beginning of Section 3. The CCNx message begins with MessageType and runs through the optional Payload. The same general format is used for both Interest and Content Object messages which are differentiated by the MessageType field. The first enclosed TLV of a CCNx Message is always the Name TLV. This is followed by an optional Metadata TLV and an optional Payload TLV. 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +---------------+---------------+---------------+---------------+ | MessageType | MessageLength | +---------------+---------------+---------------+---------------+ | Name TLV (Type = T_NAME) | +---------------+---------------+---------------+---------------+ / Optional Metadata TLV (Type = T_METADATA) / +---------------+---------------+---------------+---------------+ / Optional Payload TLV (Type = T_PAYLOAD) / +---------------+---------------+---------------+---------------+ Mosko Expires July 13, 2015 [Page 13] Internet-Draft CCNx TLV January 2015 +--------+------------+-----------------+---------------------------+ | Type | Abbrev | Name | Description | +--------+------------+-----------------+---------------------------+ | %x0000 | T_NAME | Name | The CCNx Name requested | | | | (Section 3.6.1) | in an Interest or | | | | | published in a Content | | | | | Object. | | | | | | | %x0001 | T_METADATA | Metadata | A container for protocols | | | | (Section 3.6.2) | to place their own TLVs. | | | | | | | %x0002 | T_PAYLOAD | Payload | The message payload. | | | | (Section 3.6.3) | | +--------+------------+-----------------+---------------------------+ Table 3: CCNx Message Types 3.6.1. Name A Name is a TLV encoded sequence of segments. The table below lists the type values appropriate for these Name segments. A Name MUST NOT include PAD TLVs. 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +---------------+---------------+---------------+---------------+ | T_NAME | Length | +---------------+---------------+---------------+---------------+ / Name segment TLVs / +---------------+---------------+---------------+---------------+ +--------+---------------+-------------------+----------------------+ | Type | Symbolic Name | Name | Description | +--------+---------------+-------------------+----------------------+ | %x0001 | T_NAMESEGMENT | Name segment | A generic name | | | | (Section 3.6.1.1) | Segment. | | | | | | | %x0020 | T_IPID | Interest Payload | An identifier that | | | | ID | represents the | | | | (Section 3.6.1.2) | Interest Payload | | | | | field. | | | | | | Mosko Expires July 13, 2015 [Page 14] Internet-Draft CCNx TLV January 2015 | %x1000 | T_APP:00 - | Application | Application-specific | | - | T_APP:4096 | Components | payload in a name | | %x1FFF | | (Section 3.6.1.1) | segment. An | | | | | application may | | | | | apply its own | | | | | semantics to the | | | | | 4096 reserved types. | +--------+---------------+-------------------+----------------------+ Table 4: CCNx Name Types The path segment types KeyId and ContentObjectHash are used to name a Payload - they are not the same as the KeyIdRestriction or ContentObjectHashRestriction. Putting a KeyId in a Name, for example, means that the Name is saying something about that KeyId - it is not imposing a matching restriction to the publisher's KeyId. One might use a KeyId field in a Name segment because the Payload of the Content Object is that key. Likewise, putting a ContentObjectHash type in a Name segment only means the Payload is somehow related to that hash. The Payload, for example, might be bibliographic information about the Content Object identified by that ContentObjectHash. Putting a ContentObjectHash Name segment in a Name will not force a match against a computed ContentObjectHash. The Nonce Segment is used to create a unique name using random bytes. The value of the nonce carries no specific meaning. 3.6.1.1. Name Segments Special application payload name segments are in the range %x1000 - %1FFF. These have application semantics applied to them. A good convention is to put the application's identity in the name prior to using these name segments. For example, a name like "lci:/foo/bar/Nonce=256" would be encoded as: Mosko Expires July 13, 2015 [Page 15] Internet-Draft CCNx TLV January 2015 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +---------------+---------------+---------------+---------------+ | (T_NAME) | %x14 (20) | +---------------+---------------+---------------+---------------+ | (T_NAME_SEGMENT) | %x03 (3) | +---------------+---------------+---------------+---------------+ | f o o |(T_NAME_SEGMENT) +---------------+---------------+---------------+---------------+ | %x03 (3) | b +---------------+---------------+---------------+---------------+ a r | (T_NAME_SEMGMENT) | +---------------+---------------+---------------+---------------+ | %x02 (2) | y | o | +---------------+---------------+---------------+---------------+ 3.6.1.2. Interest Payload ID The Interest Payload ID is an octet string created by the origin of an Interest to represent the Interest Payload. A common representation is to use a hash of the Interest Payload as the Interest Payload ID. 3.6.2. Metadata The metadata section of a CCNx message is a container for protocol specific TLVs. Each message type (Interest or Content Object) is associated with a set of optional Metadata TLVs. Additional specification documents may extend the types associated with each. 3.6.2.1. Interest Metadata There are two Metadata TLVs currently associated with an Interest message: the KeyIdRestriction selector and the ContentObjectHashRestriction selector. These two selectors are used to narrow the universe of acceptable Content Objects that would satisfy the Interest. 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +---------------+---------------+---------------+---------------+ | T_METADATA | Length | +---------------+---------------+---------------+---------------+ / Optional KeyIdRestriction TLV / +---------------------------------------------------------------+ / Optional ContentObjectHashRestriction TLV / +---------------------------------------------------------------+ / Optional InterestPayloadIdMethod TLV / Mosko Expires July 13, 2015 [Page 16] Internet-Draft CCNx TLV January 2015 +---------------------------------------------------------------+ +--------+-----------+------------------------------+---------------+ | Type | Abbrev | Name | Description | +--------+-----------+------------------------------+---------------+ | %x0001 | T_KEYID | KeyIdRestriction | An octet | | | | (Section 3.6.2.1.1) | string | | | | | identifying | | | | | the specific | | | | | publisher | | | | | signing key | | | | | that would | | | | | satisfy the | | | | | Interest. | | | | | | | %x0002 | T_OBJHASH | ContentObjectHashRestriction | The SHA-256 | | | | (Section 3.6.2.1.2) | hash of the | | | | | specific | | | | | Content | | | | | Object that | | | | | would satisfy | | | | | the Interest. | | | | | | | %x0005 | T_IPIDM | Interest Payload ID Method | Defines the | | | | (Section 3.6.2.1.3) | method used | | | | | to create the | | | | | Interest | | | | | Payload ID. | +--------+-----------+------------------------------+---------------+ Table 5: CCNx Interest Metadata Types 3.6.2.1.1. KeyIdRestriction An Interest may include a KeyIdRestriction selector. This ensures that only Content Objects with matching KeyIds will satisfy the Interest. See Section 3.7.1.4.1 for the format of a KeyId. 3.6.2.1.2. ContentObjectHashRestriction An Interest may also contain a ContentObjectHashRestriction selector. This is the SHA-256 hash of the Content Object - the self-certifying name restriction that must be verified in the network, if present. The only acceptable length is 32. Mosko Expires July 13, 2015 [Page 17] Internet-Draft CCNx TLV January 2015 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +---------------+---------------+---------------+---------------+ | T_OBJHASH | Length | +---------------+---------------+---------------+---------------+ / / / SHA-256 digest (32 bytes) / / / / / +---------------+---------------+---------------+---------------+ 3.6.2.1.3. Interest Payload ID Method An optional enumeration that identifies how the Interest Payload ID was created. If the IPIDM field is missing, it is assumed to be "0" (application specific). o 0: Application specific o 1: Nonce o 2: RFC 6920 If using an RFC 6920 [RFC6920] name segment for the payload ID, only include the "Digest Algorithm; Digest Value" portion of the NI name in an LCI URI. For example, use a name like lci:/name=foo/name=bar/ ipid=sha-256-32;f4OxZQ." The binary wire-format uses the RFC 6920 Binary Format inside the name segment Value. 3.6.2.2. Content Object Metadata The following metadata TLVs are currently defined for Content Objects: PayloadType (required) and ExpiryTime (optional). 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +---------------+---------------+---------------+---------------+ | T_METADATA | Length | +---------------+---------------+---------------+---------------+ / Mandatory PayloadType TLV / +---------------------------------------------------------------+ / Optional ExpiryTime TLV / +---------------------------------------------------------------+ Mosko Expires July 13, 2015 [Page 18] Internet-Draft CCNx TLV January 2015 +--------+-------------+---------------------+----------------------+ | Type | Abbrev | Name | Description | +--------+-------------+---------------------+----------------------+ | %x0003 | T_PAYLDTYPE | PayloadType | Indicates the type | | | | (Section 3.6.2.2.1) | of Payload contents | | | | | (e.g. 0 = data, 1 = | | | | | encrypted data, 2 = | | | | | key, 3 = link, etc.) | | | | | | | %x0004 | T_EXPIRY | ExpiryTime | The time at which | | | | (Section 3.6.2.2.2) | the Payload expires, | | | | | as expressed in the | | | | | number of | | | | | milliseconds since | | | | | the epoch in UTC. | | | | | If missing, Content | | | | | Object may be used | | | | | as long as desired. | +--------+-------------+---------------------+----------------------+ Table 6: CCNx Content Object Metadata Types 3.6.2.2.1. PayloadType The PayloadType is a network byte order integer representing the general type of the Payload TLV. o 0: Data (possibly encrypted) o 1: Key o 2: Link o 3: Manifest The Data type indicate that the Payload of the ContentObject is opaque application bytes. The Key type indicates that the Payload is a DER encoded public key. The Link type indicates that the Payload is a Link (Sec 3.6.1.4.5). A Manifest type indicates that the Payload is a Manifest (format TBD). We have removed the Encrypted Data, NACK, and GONE types. Those types indicated a higher-layer functionality, such as a versioning protocol or end-to-end content management, which does not belong in network-layer signaling. Mosko Expires July 13, 2015 [Page 19] Internet-Draft CCNx TLV January 2015 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +---------------+---------------+---------------+---------------+ | T_PAYLDTYPE | Length | +---------------+---------------+---------------+---------------+ | PayloadType / +---------------+ 3.6.2.2.2. ExpiryTime The ExpiryTime is the time at which the Payload expires, as expressed by a timestamp containing the number of milliseconds since the epoch in UTC. It is a network byte order unsigned integer in a 64-bit field. A cache or end system should not respond with a Content Object past its ExpiryTime. Routers forwarding a Content Object do not need to check the ExpiryTime. If the ExpiryTime field is missing, the Content Object has no expressed expiration and a cache or end system may use the Content Object for as long as desired. 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +---------------+---------------+---------------+---------------+ | T_EXPIRY | 8 | +---------------+---------------+---------------+---------------+ / ExpiryTime / / / +---------------+---------------+---------------+---------------+ 3.6.3. Payload The Payload TLV contains the content of the packet. It is permissible to have a "0" length. If a packet does not have any payload, this field may be omitted, rather than carrying a "0" length. 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +---------------+---------------+---------------+---------------+ | T_PAYLOAD | Length | +---------------+---------------+---------------+---------------+ / Payload Contents / +---------------+---------------+---------------+---------------+ 3.7. Validation Both Interests and Content Objects have the option to include information about how to validate the CCNx message. This information is contained in two TLVs: the ValidationAlgorithm TLV and Mosko Expires July 13, 2015 [Page 20] Internet-Draft CCNx TLV January 2015 theValidationPayload TLV. The ValidationAlgorithm TLV specifies the mechanism to be used to verify the CCNx message. Examples include verification with a Message Integrity Check (MIC), a Message Authentication Code (MAC), or a cryptographic signature. The ValidationPayload TLV contains the validation output, such as the CRC32C code or the RSA signature. An Interest would most likely only use a MIC type of validation - a crc, checksum, or digest. 3.7.1. Validation Algorithm The ValidationAlgorithm is a set of nested TLVs containing all of the information needed to verify the message. The outermost container has type = T_VALIDATION_ALG. The first nested TLV defines the specific type of validation to be performed on the message. The type is identified with the "ValidationType" as shown in the figure below and elaborated in the table below. Nested within that container are the TLVs for any ValidationType dependent data, for example a Key Id, Key Locator etc. Complete examples of several types may be found in Section 3.7.1.5 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +---------------+---------------+---------------+---------------+ | T_VALIDATION_ALG | ValidationAlgLength | +---------------+---------------+---------------+---------------+ | ValidationType | Length | +---------------+---------------+---------------+---------------+ / ValidationType dependent data / +---------------+---------------+---------------+---------------+ Mosko Expires July 13, 2015 [Page 21] Internet-Draft CCNx TLV January 2015 +-----+---------+-------------+-------------------------------------+ | Typ | Abbrev | Name | Description | | e | | | | +-----+---------+-------------+-------------------------------------+ | %x0 | T_CRC32 | CRC32 | The Ethernet CRC32 (normal form | | 0 0 | | (Section 3. | polynomial 0x04C11DB7). | | 1 | | 7 .1.1) | | | | | | | | %x0 | T_CRC32 | CRC32C | Castagnoli CRC32 (iSCSI, ext4, | | 0 0 | C | (Section 3. | etc.), with normal form polynomial | | 2 | | 7 .1.1) | 0x1EDC6F41. | | | | | | | %x0 | T_RFC79 | RFC793 | The TCP checksum. | | 0 0 | 3 | (Section 3. | | | 3 | | 7 .1.1) | | | | | | | | %x0 | T_HMAC- | HMAC-SHA256 | HMAC (RFC 2104) using SHA256 hash. | | 0 0 | S HA256 | (Section 3. | | | 4 | | 7 .1.2) | | | | | | | | %x0 | T_VMAC- | VMAC-128 | VMAC with 128bit tags | | 0 0 | 1 28 | (Section 3. | (http://www.fastcrypto.org/vmac/dra | | 5 | | 7 .1.2) | ft-krovetz-vmac-01.txt). | | | | | | | %x0 | T_RSA-S | RSA-SHA256 | RSA public key signature using | | 0 0 | H A256 | (Section 3. | SHA256 digest. | | 6 | | 7 .1.3) | | | | | | | | %x0 | EC-SECP | SECP-256K1 | Elliptic Curve signature with | | 0 0 | - 256K1 | (Section 3. | SECP-256K1 parameters | | 7 | | 7 .1.3) | (http://www.secg.org/collateral/sec | | | | | 2_final.pdf). | | | | | | | %x0 | EC-SECP | SECP-384R1 | Elliptic Curve signature with | | 0 0 | - 384R1 | (Section 3. | SECP-384R1 parameters | | 8 | | 7 .1.3) | (http://www.secg.org/collateral/sec | | | | | 2_final.pdf). | +-----+---------+-------------+-------------------------------------+ Table 7: CCNx Validation Types 3.7.1.1. Message Integrity Checks MICs do not require additional data in order to perform the verification. Examples are CRC32, CRC32C, RFC793, etc., that have a "0" length value. Mosko Expires July 13, 2015 [Page 22] Internet-Draft CCNx TLV January 2015 3.7.1.2. Message Authentication Checks MACs are useful for communication between two trusted parties who have already shared private keys. Examples include T_HMAC-SHA256 or others. They rely on a KeyId. Some MACs might use more than a KeyId, but those would be defined in the future. 3.7.1.3. Signature Signature type Validators specify a digest mechanism and a signing algorithm to verify the message. Examples include T_RSA-SHA256, Elliptic Curve, etc. These Validators require a KeyId and a mechanism for locating the publishers public key (a KeyLocator) - optionally a PublicKey or Certificate or KeyName. 3.7.1.4. Validation Dependent Data Different Validation Algorithms require access to different pieces of data contained in the ValidationAlgorithm TLV. As described above, Key Ids, Key Locators, Public Keys, Certificates, Links and Key Names all play a role in different Validation Algorithms. Following is a table of CCNx ValidationType dependent data types: +--------+----------------+---------------------+-------------------+ | Type | Abbrev | Name | Description | +--------+----------------+---------------------+-------------------+ | %x0009 | T_KEYID | SignerKeyId | An identifier of | | | | (Section 3.7.1.4.1) | the shared secret | | | | | or public key | | | | | associated with a | | | | | MAC or Signature. | | | | | Typically the | | | | | SHA256 hash of | | | | | the key. | | | | | | | %x000A | T_PUBLICKEYLOC | PublicKeyLocator | A data structure | | | | (Section 3.7.1.4.6) | that tells how to | | | | | locate the public | | | | | key associated | | | | | with a signing. | | | | | It may contain a | | | | | Public Key, a | | | | | Certificate, or a | | | | | Link to a Key. | | | | | | | %x000B | T_PUBLICKEY | Public Key | DER encoded | | | | (Section 3.7.1.4.3) | public key. | Mosko Expires July 13, 2015 [Page 23] Internet-Draft CCNx TLV January 2015 | %x000C | T_CERT | Certificate | DER encoded X509 | | | | (Section 3.7.1.4.4) | certificate. | | | | | | | %x000D | T_LINK | Link | A CCNx Link | | | | (Section 3.7.1.4.5) | object. | | | | | | | %x000E | T_KEYNAME | KeyName | A CCNx Link | | | | (Section 3.7.1.4.6) | object. | | | | | | | %x000F | T_SIGTIME | SignatureTime | A millsecond | | | | (Section 3.7.1.4.7) | timestamp | | | | | indicating the | | | | | time when the | | | | | signature was | | | | | created. | +--------+----------------+---------------------+-------------------+ Table 8: CCNx Validation Dependent Data Types 3.7.1.4.1. KeyId The KeyId is the publisher key identifier. It is similar to a Subject Key Identifier from X509 [RFC 3820, Section 4.2.1.2]. It should be derived from the key used to sign, such as from the SHA-256 hash of the key. It applies to both public/private key systems and to symmetric key systems. 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +---------------+---------------+---------------+---------------+ | T_KEYID | Length | +---------------+---------------+---------------+---------------+ / KeyId / /---------------+---------------+-------------------------------+ 3.7.1.4.2. KeyLocator The KeyLocator is an optional field. If it is not present, a node wishing to authenticate a Content Object must have prior knowledge of the Publisher KeyId, or be able to retrieve the corresponding key through external means. The KeyLocator may contain one of: a DER encoded Public Key, a DER encoded X509 Certificate, or a KeyName. 3.7.1.4.3. Public Key A Public Key is a DER encoded Subject Public Key Info block, as in an X509 certificate. Mosko Expires July 13, 2015 [Page 24] Internet-Draft CCNx TLV January 2015 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +---------------+---------------+---------------+---------------+ | T_PUBLICKEY | Length | +---------------+---------------+---------------+---------------+ / Public Key (DER encoded SPKI) / +---------------+---------------+---------------+---------------+ 3.7.1.4.4. Certificate 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +---------------+---------------+---------------+---------------+ | T_CERT | Length | +---------------+---------------+---------------+---------------+ / Certificate (DER encoded X509) / +---------------+---------------+---------------+---------------+ 3.7.1.4.5. Link A Link is the tuple: {CCNx Name, KeyId, ContentObjectHash}. It may be the payload of a Content Object with PayloadType = "Link". Alternatively, it could be the KeyName field in a KeyLocator. 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +---------------+---------------+-------------------------------+ / Mandatory CCNx Name / +---------------+---------------+-------------------------------+ / Optional KeyId / +---------------------------------------------------------------+ / Optional ContentObjectHash / +---------------------------------------------------------------+ 3.7.1.4.6. KeyName A KeyName type KeyLocator is a Link. The KeyName digest is the publisher digest of the Content Object identified by KeyName. It may be included on an Interest's digest restriction. A KeyName is a mandatory Name and an optional KeyId. The KeyId inside the KeyLocator may be included in an Interest's KeyId to retrieve only the specified key. Mosko Expires July 13, 2015 [Page 25] Internet-Draft CCNx TLV January 2015 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +---------------+---------------+-------------------------------+ | T_KEYNAME | Length | +---------------+---------------+-------------------------------+ / Link / +---------------------------------------------------------------+ 3.7.1.4.7. SignatureTime The SignatureTime is a millisecond timestamp indicating the time at which a signature was created. The signer sets this field to the current time when creating a signature. A verifier may use this time to determine whether or not the signature was created during the validity period of a key, or if it occurred in a reasonable sequence with other associated signatures. The SignatureTime is unrelated to any time associated with the actual CCNx Message, which could have been created long before the signature. The default behavior is to always include a SignatureTime when creating an authenticated message (e.g. HMAC or RSA). SignatureTime is a network byte ordered unsigned integer of the number of milliseconds since the epoch in UTC of when the signature was created. It is a fixed 64-bit field. 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +---------------+---------------+-------------------------------+ | T_SIGTIME | 8 | +---------------+---------------+-------------------------------+ / SignatureTime / +---------------------------------------------------------------+ 3.7.1.5. Validation Examples As an example of a MIC type validation, the encoding for CRC32 validation would be: 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +---------------+---------------+---------------+---------------+ | T_VALIDATION_ALG | 4 | +---------------+---------------+---------------+---------------+ | T_CRC32 | 0 | +---------------+---------------+---------------+---------------+ As an example of a MAC type validation, the encoding for an HMAC using a SHA256 hash would be: Mosko Expires July 13, 2015 [Page 26] Internet-Draft CCNx TLV January 2015 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +---------------+---------------+---------------+---------------+ | T_VALIDATION_ALG | 40 | +---------------+---------------+---------------+---------------+ | T_HMAC-SHA256 | 36 | +---------------+---------------+---------------+---------------+ | T_KEYID | 32 | +---------------+---------------+---------------+---------------+ / KeyId / /---------------+---------------+-------------------------------+ As an example of a Signature type validation, the encoding for an RSA public key signing using a SHA256 digest and Public Key would be: 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +---------------+---------------+---------------+---------------+ | T_VALIDATION_ALG | 44 + Variable Length | +---------------+---------------+---------------+---------------+ | T_RSA-SHA256 | 40 + Variable Length | +---------------+---------------+---------------+---------------+ | T_KEYID | 32 | +---------------+---------------+---------------+---------------+ / KeyId / /---------------+---------------+-------------------------------+ | T_PUBLICKEY | Variable Length (~ 160) | +---------------+---------------+---------------+---------------+ / Public Key (DER encoded SPKI) / +---------------+---------------+---------------+---------------+ 3.7.2. Validation Payload 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +---------------+---------------+---------------+---------------+ | T_VALIDATION_PAYLOAD | ValidationPayloadLength | +---------------+---------------+---------------+---------------+ / Type-dependent data / +---------------+---------------+---------------+---------------+ The ValidationPayload contains the validation output, such as the CRC32C code or the RSA signature. Mosko Expires July 13, 2015 [Page 27] Internet-Draft CCNx TLV January 2015 4. Acknowledgements Mosko Expires July 13, 2015 [Page 28] Internet-Draft CCNx TLV January 2015 5. IANA Considerations This memo includes no request to IANA. All drafts are required to have an IANA considerations section (see Guidelines for Writing an IANA Considerations Section in RFCs [RFC5226] for a guide). If the draft does not require IANA to do anything, the section contains an explicit statement that this is the case (as above). If there are no requirements for IANA, the section will be removed during conversion into an RFC by the RFC Editor. Mosko Expires July 13, 2015 [Page 29] Internet-Draft CCNx TLV January 2015 6. Security Considerations All drafts are required to have a security considerations section. See RFC 3552 [RFC3552] for a guide. Mosko Expires July 13, 2015 [Page 30] Internet-Draft CCNx TLV January 2015 7. References 7.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. 7.2. Informative References [CCN] PARC, Inc., "CCNx Open Source", 2007, . [RFC3552] Rescorla, E. and B. Korver, "Guidelines for Writing RFC Text on Security Considerations", BCP 72, RFC 3552, July 2003. [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 5226, May 2008. [RFC6920] Farrell, S., Kutscher, D., Dannewitz, C., Ohlman, B., Keranen, A., and P. Hallam-Baker, "Naming Things with Hashes", RFC 6920, April 2013. Mosko Expires July 13, 2015 [Page 31] Internet-Draft CCNx TLV January 2015 Author's Address Marc Mosko PARC, Inc. Palo Alto, California 94304 USA Phone: +01 650-812-4405 Email: marc.mosko@parc.com Mosko Expires July 13, 2015 [Page 32]