tech-invite   World Map     

3GPP     Specs     Glossaries     Architecture     IMS     UICC       IETF     RFCs     Groups     SIP     ABNFs       Search

RFC 8152

 Errata 
Proposed STD
Pages: 121
Top     in Index     Prev     Next
in Group Index     No Prev: Lowest Number in Group     No Next: Highest Number in Group     Group: COSE

CBOR Object Signing and Encryption (COSE)

Part 1 of 6, p. 1 to 15
None       Next Section

 


Top       ToC       Page 1 
Internet Engineering Task Force (IETF)                         J. Schaad
Request for Comments: 8152                                August Cellars
Category: Standards Track                                      July 2017
ISSN: 2070-1721


               CBOR Object Signing and Encryption (COSE)

Abstract

   Concise Binary Object Representation (CBOR) is a data format designed
   for small code size and small message size.  There is a need for the
   ability to have basic security services defined for this data format.
   This document defines the CBOR Object Signing and Encryption (COSE)
   protocol.  This specification describes how to create and process
   signatures, message authentication codes, and encryption using CBOR
   for serialization.  This specification additionally describes how to
   represent cryptographic keys using CBOR.

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 7841.

   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/rfc8152.

Copyright Notice

   Copyright (c) 2017 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.

Top       Page 2 
Table of Contents

   1. Introduction ....................................................4
      1.1. Design Changes from JOSE ...................................5
      1.2. Requirements Terminology ...................................6
      1.3. CBOR Grammar ...............................................6
      1.4. CBOR-Related Terminology ...................................7
      1.5. Document Terminology .......................................8
   2. Basic COSE Structure ............................................8
   3. Header Parameters ..............................................10
      3.1. Common COSE Headers Parameters ............................12
   4. Signing Objects ................................................16
      4.1. Signing with One or More Signers ..........................16
      4.2. Signing with One Signer ...................................18
      4.3. Externally Supplied Data ..................................19
      4.4. Signing and Verification Process ..........................20
      4.5. Computing Counter Signatures ..............................22
   5. Encryption Objects .............................................22
      5.1. Enveloped COSE Structure ..................................23
           5.1.1. Content Key Distribution Methods ...................24
      5.2. Single Recipient Encrypted ................................25
      5.3. How to Encrypt and Decrypt for AEAD Algorithms ............26
      5.4. How to Encrypt and Decrypt for AE Algorithms ..............28
   6. MAC Objects ....................................................29
      6.1. MACed Message with Recipients .............................30
      6.2. MACed Messages with Implicit Key ..........................31
      6.3. How to Compute and Verify a MAC ...........................32
   7. Key Objects ....................................................33
      7.1. COSE Key Common Parameters ................................34
   8. Signature Algorithms ...........................................37
      8.1. ECDSA .....................................................38
           8.1.1. Security Considerations ............................40
      8.2. Edwards-Curve Digital Signature Algorithms (EdDSAs) .......40
           8.2.1. Security Considerations ............................41
   9. Message Authentication Code (MAC) Algorithms ...................42
      9.1. Hash-Based Message Authentication Codes (HMACs) ...........42
           9.1.1. Security Considerations ............................44
      9.2. AES Message Authentication Code (AES-CBC-MAC) .............44
           9.2.1. Security Considerations ............................45
   10. Content Encryption Algorithms .................................45
      10.1. AES GCM ..................................................46
           10.1.1. Security Considerations ...........................47
      10.2. AES CCM ..................................................47
           10.2.1. Security Considerations ...........................50
      10.3. ChaCha20 and Poly1305 ....................................50
           10.3.1. Security Considerations ...........................51
   11. Key Derivation Functions (KDFs) ...............................51

Top      ToC       Page 3 
      11.1. HMAC-Based Extract-and-Expand Key Derivation
            Function (HKDF) ..........................................52
      11.2. Context Information Structure ............................54
   12. Content Key Distribution Methods ..............................60
      12.1. Direct Encryption ........................................60
           12.1.1. Direct Key ........................................61
           12.1.2. Direct Key with KDF ...............................61
       12.2. Key Wrap ................................................63
           12.2.1. AES Key Wrap ......................................64
       12.3. Key Transport ...........................................65
       12.4. Direct Key Agreement ....................................65
           12.4.1. ECDH ..............................................66
           12.4.2. Security Considerations ...........................69
      12.5. Key Agreement with Key Wrap ..............................69
           12.5.1. ECDH ..............................................70
   13. Key Object Parameters .........................................72
      13.1. Elliptic Curve Keys ......................................73
           13.1.1. Double Coordinate Curves ..........................73
      13.2. Octet Key Pair ...........................................74
      13.3. Symmetric Keys ...........................................75
   14. CBOR Encoder Restrictions .....................................76
   15. Application Profiling Considerations ..........................76
   16. IANA Considerations ...........................................78
      16.1. CBOR Tag Assignment ......................................78
      16.2. COSE Header Parameters Registry ..........................78
      16.3. COSE Header Algorithm Parameters Registry ................79
      16.4. COSE Algorithms Registry .................................79
      16.5. COSE Key Common Parameters Registry ......................81
      16.6. COSE Key Type Parameters Registry ........................81
      16.7. COSE Key Types Registry ..................................82
      16.8. COSE Elliptic Curves Registry ............................83
      16.9. Media Type Registrations .................................84
           16.9.1. COSE Security Message .............................84
           16.9.2. COSE Key Media Type ...............................85
      16.10. CoAP Content-Formats Registry ...........................87
      16.11. Expert Review Instructions ..............................87
   17. Security Considerations .......................................88
   18. References ....................................................90
      18.1. Normative References .....................................90
      18.2. Informative References ...................................92
   Appendix A. Guidelines for External Data Authentication of
               Algorithms ............................................96
      A.1. Algorithm Identification ..................................96
      A.2. Counter Signature without Headers .........................99
   Appendix B. Two Layers of Recipient Information ..................100
   Appendix C. Examples .............................................102
      C.1. Examples of Signed Messages ..............................103
           C.1.1. Single Signature ..................................103

Top      ToC       Page 4 
           C.1.2. Multiple Signers ..................................103
           C.1.3. Counter Signature .................................104
           C.1.4. Signature with Criticality ........................105
      C.2. Single Signer Examples ...................................106
           C.2.1. Single ECDSA Signature  ...........................106
      C.3. Examples of Enveloped Messages ...........................107
           C.3.1. Direct ECDH .......................................107
           C.3.2. Direct Plus Key Derivation ........................108
           C.3.3. Counter Signature on Encrypted Content ............109
           C.3.4. Encrypted Content with External Data ..............111
      C.4. Examples of Encrypted Messages ...........................111
           C.4.1. Simple Encrypted Message ..........................111
           C.4.2. Encrypted Message with a Partial IV ...............112
      C.5. Examples of MACed Messages ...............................112
           C.5.1. Shared Secret Direct MAC ..........................112
           C.5.2. ECDH Direct MAC ...................................113
           C.5.3. Wrapped MAC .......................................114
           C.5.4. Multi-Recipient MACed Message .....................115
      C.6. Examples of MAC0 Messages ................................117
           C.6.1. Shared Secret Direct MAC ..........................117
      C.7. COSE Keys ................................................117
           C.7.1. Public Keys .......................................117
           C.7.2. Private Keys ......................................119
   Acknowledgments ..................................................121
   Author's Address .................................................121

1.  Introduction

   There has been an increased focus on small, constrained devices that
   make up the Internet of Things (IoT).  One of the standards that has
   come out of this process is "Concise Binary Object Representation
   (CBOR)" [RFC7049].  CBOR extended the data model of the JavaScript
   Object Notation (JSON) [RFC7159] by allowing for binary data, among
   other changes.  CBOR is being adopted by several of the IETF working
   groups dealing with the IoT world as their encoding of data
   structures.  CBOR was designed specifically to be both small in terms
   of messages transport and implementation size and be a schema-free
   decoder.  A need exists to provide message security services for IoT,
   and using CBOR as the message-encoding format makes sense.

   The JOSE working group produced a set of documents [RFC7515]
   [RFC7516] [RFC7517] [RFC7518] using JSON that specified how to
   process encryption, signatures, and Message Authentication Code (MAC)
   operations and how to encode keys using JSON.  This document defines
   the CBOR Object Signing and Encryption (COSE) standard, which does
   the same thing for the CBOR encoding format.  While there is a strong

Top      ToC       Page 5 
   attempt to keep the flavor of the original JSON Object Signing and
   Encryption (JOSE) documents, two considerations are taken into
   account:

   o  CBOR has capabilities that are not present in JSON and are
      appropriate to use.  One example of this is the fact that CBOR has
      a method of encoding binary directly without first converting it
      into a base64-encoded string.

   o  COSE is not a direct copy of the JOSE specification.  In the
      process of creating COSE, decisions that were made for JOSE were
      re-examined.  In many cases, different results were decided on as
      the criteria were not always the same.

1.1.  Design Changes from JOSE

   o  Define a single top message structure so that encrypted, signed,
      and MACed messages can easily be identified and still have a
      consistent view.

   o  Signed messages distinguish between the protected and unprotected
      parameters that relate to the content from those that relate to
      the signature.

   o  MACed messages are separated from signed messages.

   o  MACed messages have the ability to use the same set of recipient
      algorithms as enveloped messages for obtaining the MAC
      authentication key.

   o  Use binary encodings for binary data rather than base64url
      encodings.

   o  Combine the authentication tag for encryption algorithms with the
      ciphertext.

   o  The set of cryptographic algorithms has been expanded in some
      directions and trimmed in others.

Top      ToC       Page 6 
1.2.  Requirements Terminology

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
   "OPTIONAL" in this document are to be interpreted as described in BCP
   14 [RFC2119] [RFC8174] when, and only when, they appear in all
   capitals, as shown here.

   When the words appear in lowercase, this interpretation does not
   apply.

1.3.  CBOR Grammar

   There is currently no standard CBOR grammar available for use by
   specifications.  The CBOR structures are therefore described in
   prose.

   The document was developed by first working on the grammar and then
   developing the prose to go with it.  An artifact of this is that the
   prose was written using the primitive type strings defined by CBOR
   Data Definition Language (CDDL) [CDDL].  In this specification, the
   following primitive types are used:

      any -- non-specific value that permits all CBOR values to be
      placed here.

      bool -- a boolean value (true: major type 7, value 21; false:
      major type 7, value 20).

      bstr -- byte string (major type 2).

      int -- an unsigned integer or a negative integer.

      nil -- a null value (major type 7, value 22).

      nint -- a negative integer (major type 1).

      tstr -- a UTF-8 text string (major type 3).

      uint -- an unsigned integer (major type 0).

   Two syntaxes from CDDL appear in this document as shorthand.  These
   are:

      FOO / BAR -- indicates that either FOO or BAR can appear here.

      [+ FOO] -- indicates that the type FOO appears one or more times
      in an array.

Top      ToC       Page 7 
   As well as the prose description, a version of a CBOR grammar is
   presented in CDDL.  Since CDDL has not been published in an RFC, this
   grammar may not work with the final version of CDDL.  The CDDL
   grammar is informational; the prose description is normative.

   The collected CDDL can be extracted from the XML version of this
   document via the following XPath expression below.  (Depending on the
   XPath evaluator one is using, it may be necessary to deal with >
   as an entity.)

   //artwork[@type='CDDL']/text()

   CDDL expects the initial non-terminal symbol to be the first symbol
   in the file.  For this reason, the first fragment of CDDL is
   presented here.

   start = COSE_Messages / COSE_Key / COSE_KeySet / Internal_Types

   ; This is defined to make the tool quieter:
   Internal_Types = Sig_structure / Enc_structure / MAC_structure /
           COSE_KDF_Context

   The non-terminal Internal_Types is defined for dealing with the
   automated validation tools used during the writing of this document.
   It references those non-terminals that are used for security
   computations but are not emitted for transport.

1.4.  CBOR-Related Terminology

   In JSON, maps are called objects and only have one kind of map key: a
   string.  In COSE, we use strings, negative integers, and unsigned
   integers as map keys.  The integers are used for compactness of
   encoding and easy comparison.  The inclusion of strings allows for an
   additional range of short encoded values to be used as well.  Since
   the word "key" is mainly used in its other meaning, as a
   cryptographic key, we use the term "label" for this usage as a map
   key.

   The presence of a label in a COSE map that is not a string or an
   integer is an error.  Applications can either fail processing or
   process messages with incorrect labels; however, they MUST NOT create
   messages with incorrect labels.

   A CDDL grammar fragment defines the non-terminal 'label', as in the
   previous paragraph, and 'values', which permits any value to be used.

   label = int / tstr
   values = any

Top      ToC       Page 8 
1.5.  Document Terminology

   In this document, we use the following terminology:

   Byte is a synonym for octet.

   Constrained Application Protocol (CoAP) is a specialized web transfer
   protocol for use in constrained systems.  It is defined in [RFC7252].

   Authenticated Encryption (AE) [RFC5116] algorithms are those
   encryption algorithms that provide an authentication check of the
   contents algorithm with the encryption service.

   Authenticated Encryption with Authenticated Data (AEAD) [RFC5116]
   algorithms provide the same content authentication service as AE
   algorithms, but they additionally provide for authentication of non-
   encrypted data as well.

2.  Basic COSE Structure

   The COSE object structure is designed so that there can be a large
   amount of common code when parsing and processing the different types
   of security messages.  All of the message structures are built on the
   CBOR array type.  The first three elements of the array always
   contain the same information:

   1.  The set of protected header parameters wrapped in a bstr.

   2.  The set of unprotected header parameters as a map.

   3.  The content of the message.  The content is either the plaintext
       or the ciphertext as appropriate.  The content may be detached,
       but the location is still used.  The content is wrapped in a bstr
       when present and is a nil value when detached.

   Elements after this point are dependent on the specific message type.

   COSE messages are also built using the concept of layers to separate
   different types of cryptographic concepts.  As an example of how this
   works, consider the COSE_Encrypt message (Section 5.1).  This message
   type is broken into two layers: the content layer and the recipient
   layer.  In the content layer, the plaintext is encrypted and
   information about the encrypted message is placed.  In the recipient
   layer, the content encryption key (CEK) is encrypted and information
   about how it is encrypted for each recipient is placed.  A single
   layer version of the encryption message COSE_Encrypt0 (Section 5.2)
   is provided for cases where the CEK is pre-shared.

Top      ToC       Page 9 
   Identification of which type of message has been presented is done by
   the following methods:

   1.  The specific message type is known from the context.  This may be
       defined by a marker in the containing structure or by
       restrictions specified by the application protocol.

   2.  The message type is identified by a CBOR tag.  Messages with a
       CBOR tag are known in this specification as tagged messages,
       while those without the CBOR tag are known as untagged messages.
       This document defines a CBOR tag for each of the message
       structures.  These tags can be found in Table 1.

   3.  When a COSE object is carried in a media type of 'application/
       cose', the optional parameter 'cose-type' can be used to identify
       the embedded object.  The parameter is OPTIONAL if the tagged
       version of the structure is used.  The parameter is REQUIRED if
       the untagged version of the structure is used.  The value to use
       with the parameter for each of the structures can be found in
       Table 1.

   4.  When a COSE object is carried as a CoAP payload, the CoAP
       Content-Format Option can be used to identify the message
       content.  The CoAP Content-Format values can be found in
       Table 26.  The CBOR tag for the message structure is not required
       as each security message is uniquely identified.

   +-------+---------------+---------------+---------------------------+
   | CBOR  | cose-type     | Data Item     | Semantics                 |
   | Tag   |               |               |                           |
   +-------+---------------+---------------+---------------------------+
   | 98    | cose-sign     | COSE_Sign     | COSE Signed Data Object   |
   | 18    | cose-sign1    | COSE_Sign1    | COSE Single Signer Data   |
   |       |               |               | Object                    |
   | 96    | cose-encrypt  | COSE_Encrypt  | COSE Encrypted Data       |
   |       |               |               | Object                    |
   | 16    | cose-encrypt0 | COSE_Encrypt0 | COSE Single Recipient     |
   |       |               |               | Encrypted Data Object     |
   | 97    | cose-mac      | COSE_Mac      | COSE MACed Data Object    |
   | 17    | cose-mac0     | COSE_Mac0     | COSE Mac w/o Recipients   |
   |       |               |               | Object                    |
   +-------+---------------+---------------+---------------------------+

                   Table 1: COSE Message Identification

Top      ToC       Page 10 
   The following CDDL fragment identifies all of the top messages
   defined in this document.  Separate non-terminals are defined for the
   tagged and the untagged versions of the messages.

   COSE_Messages = COSE_Untagged_Message / COSE_Tagged_Message

   COSE_Untagged_Message = COSE_Sign / COSE_Sign1 /
       COSE_Encrypt / COSE_Encrypt0 /
       COSE_Mac / COSE_Mac0

   COSE_Tagged_Message = COSE_Sign_Tagged / COSE_Sign1_Tagged /
       COSE_Encrypt_Tagged / COSE_Encrypt0_Tagged /
       COSE_Mac_Tagged / COSE_Mac0_Tagged

3.  Header Parameters

   The structure of COSE has been designed to have two buckets of
   information that are not considered to be part of the payload itself,
   but are used for holding information about content, algorithms, keys,
   or evaluation hints for the processing of the layer.  These two
   buckets are available for use in all of the structures except for
   keys.  While these buckets are present, they may not all be usable in
   all instances.  For example, while the protected bucket is defined as
   part of the recipient structure, some of the algorithms used for
   recipient structures do not provide for authenticated data.  If this
   is the case, the protected bucket is left empty.

   Both buckets are implemented as CBOR maps.  The map key is a 'label'
   (Section 1.4).  The value portion is dependent on the definition for
   the label.  Both maps use the same set of label/value pairs.  The
   integer and string values for labels have been divided into several
   sections including a standard range, a private range, and a range
   that is dependent on the algorithm selected.  The defined labels can
   be found in the "COSE Header Parameters" IANA registry
   (Section 16.2).

   Two buckets are provided for each layer:

   protected:  Contains parameters about the current layer that are to
      be cryptographically protected.  This bucket MUST be empty if it
      is not going to be included in a cryptographic computation.  This
      bucket is encoded in the message as a binary object.  This value
      is obtained by CBOR encoding the protected map and wrapping it in
      a bstr object.  Senders SHOULD encode a zero-length map as a zero-
      length string rather than as a zero-length map (encoded as h'a0').
      The zero-length binary encoding is preferred because it is both
      shorter and the version used in the serialization structures for
      cryptographic computation.  After encoding the map, the value is

Top      ToC       Page 11 
      wrapped in the binary object.  Recipients MUST accept both a zero-
      length binary value and a zero-length map encoded in the binary
      value.  The wrapping allows for the encoding of the protected map
      to be transported with a greater chance that it will not be
      altered in transit.  (Badly behaved intermediates could decode and
      re-encode, but this will result in a failure to verify unless the
      re-encoded byte string is identical to the decoded byte string.)
      This avoids the problem of all parties needing to be able to do a
      common canonical encoding.

   unprotected:  Contains parameters about the current layer that are
      not cryptographically protected.

   Only parameters that deal with the current layer are to be placed at
   that layer.  As an example of this, the parameter 'content type'
   describes the content of the message being carried in the message.
   As such, this parameter is placed only in the content layer and is
   not placed in the recipient or signature layers.  In principle, one
   should be able to process any given layer without reference to any
   other layer.  With the exception of the COSE_Sign structure, the only
   data that needs to cross layers is the cryptographic key.

   The buckets are present in all of the security objects defined in
   this document.  The fields in order are the 'protected' bucket (as a
   CBOR 'bstr' type) and then the 'unprotected' bucket (as a CBOR 'map'
   type).  The presence of both buckets is required.  The parameters
   that go into the buckets come from the IANA "COSE Header Parameters"
   registry (Section 16.2).  Some common parameters are defined in the
   next section, but a number of parameters are defined throughout this
   document.

   Labels in each of the maps MUST be unique.  When processing messages,
   if a label appears multiple times, the message MUST be rejected as
   malformed.  Applications SHOULD verify that the same label does not
   occur in both the protected and unprotected headers.  If the message
   is not rejected as malformed, attributes MUST be obtained from the
   protected bucket before they are obtained from the unprotected
   bucket.

Top      ToC       Page 12 
   The following CDDL fragment represents the two header buckets.  A
   group "Headers" is defined in CDDL that represents the two buckets in
   which attributes are placed.  This group is used to provide these two
   fields consistently in all locations.  A type is also defined that
   represents the map of common headers.

   Headers = (
       protected : empty_or_serialized_map,
       unprotected : header_map
   )

   header_map = {
       Generic_Headers,
       * label => values
   }

   empty_or_serialized_map = bstr .cbor header_map / bstr .size 0


3.1.  Common COSE Headers Parameters

   This section defines a set of common header parameters.  A summary of
   these parameters can be found in Table 2.  This table should be
   consulted to determine the value of label and the type of the value.

   The set of header parameters defined in this section are:

   alg:  This parameter is used to indicate the algorithm used for the
      security processing.  This parameter MUST be authenticated where
      the ability to do so exists.  This support is provided by AEAD
      algorithms or construction (COSE_Sign, COSE_Sign0, COSE_Mac, and
      COSE_Mac0).  This authentication can be done either by placing the
      header in the protected header bucket or as part of the externally
      supplied data.  The value is taken from the "COSE Algorithms"
      registry (see Section 16.4).

   crit:  The parameter is used to indicate which protected header
      labels an application that is processing a message is required to
      understand.  Parameters defined in this document do not need to be
      included as they should be understood by all implementations.
      When present, this parameter MUST be placed in the protected
      header bucket.  The array MUST have at least one value in it.
      Not all labels need to be included in the 'crit' parameter.  The
      rules for deciding which header labels are placed in the array
      are:

      *  Integer labels in the range of 0 to 8 SHOULD be omitted.

Top      ToC       Page 13 
      *  Integer labels in the range -1 to -128 can be omitted as they
         are algorithm dependent.  If an application can correctly
         process an algorithm, it can be assumed that it will correctly
         process all of the common parameters associated with that
         algorithm.  Integer labels in the range -129 to -65536 SHOULD
         be included as these would be less common parameters that might
         not be generally supported.

      *  Labels for parameters required for an application MAY be
         omitted.  Applications should have a statement if the label can
         be omitted.

      The header parameter values indicated by 'crit' can be processed
      by either the security library code or an application using a
      security library; the only requirement is that the parameter is
      processed.  If the 'crit' value list includes a value for which
      the parameter is not in the protected bucket, this is a fatal
      error in processing the message.

   content type:  This parameter is used to indicate the content type of
      the data in the payload or ciphertext fields.  Integers are from
      the "CoAP Content-Formats" IANA registry table [COAP.Formats].
      Text values following the syntax of "<type-name>/<subtype-name>"
      where <type-name> and <subtype-name> are defined in Section 4.2 of
      [RFC6838].  Leading and trailing whitespace is also omitted.
      Textual content values along with parameters and subparameters can
      be located using the IANA "Media Types" registry.  Applications
      SHOULD provide this parameter if the content structure is
      potentially ambiguous.

   kid:  This parameter identifies one piece of data that can be used as
      input to find the needed cryptographic key.  The value of this
      parameter can be matched against the 'kid' member in a COSE_Key
      structure.  Other methods of key distribution can define an
      equivalent field to be matched.  Applications MUST NOT assume that
      'kid' values are unique.  There may be more than one key with the
      same 'kid' value, so all of the keys associated with this 'kid'
      may need to be checked.  The internal structure of 'kid' values is
      not defined and cannot be relied on by applications.  Key
      identifier values are hints about which key to use.  This is not a
      security-critical field.  For this reason, it can be placed in the
      unprotected headers bucket.

   IV:  This parameter holds the Initialization Vector (IV) value.  For
      some symmetric encryption algorithms, this may be referred to as a
      nonce.  The IV can be placed in the unprotected header as
      modifying the IV will cause the decryption to yield plaintext that
      is readily detectable as garbled.

Top      ToC       Page 14 
   Partial IV:  This parameter holds a part of the IV value.  When using
      the COSE_Encrypt0 structure, a portion of the IV can be part of
      the context associated with the key.  This field is used to carry
      a value that causes the IV to be changed for each message.  The IV
      can be placed in the unprotected header as modifying the IV will
      cause the decryption to yield plaintext that is readily detectable
      as garbled.  The 'Initialization Vector' and 'Partial
      Initialization Vector' parameters MUST NOT both be present in the
      same security layer.

      The message IV is generated by the following steps:

      1.  Left-pad the Partial IV with zeros to the length of IV.

      2.  XOR the padded Partial IV with the context IV.

   counter signature:  This parameter holds one or more counter
      signature values.  Counter signatures provide a method of having a
      second party sign some data.  The counter signature parameter can
      occur as an unprotected attribute in any of the following
      structures: COSE_Sign1, COSE_Signature, COSE_Encrypt,
      COSE_recipient, COSE_Encrypt0, COSE_Mac, and COSE_Mac0.  These
      structures all have the same beginning elements, so that a
      consistent calculation of the counter signature can be computed.
      Details on computing counter signatures are found in Section 4.5.

Top      ToC       Page 15 
   +-----------+-------+----------------+-------------+----------------+
   | Name      | Label | Value Type     | Value       | Description    |
   |           |       |                | Registry    |                |
   +-----------+-------+----------------+-------------+----------------+
   | alg       | 1     | int / tstr     | COSE        | Cryptographic  |
   |           |       |                | Algorithms  | algorithm to   |
   |           |       |                | registry    | use            |
   | crit      | 2     | [+ label]      | COSE Header | Critical       |
   |           |       |                | Parameters  | headers to be  |
   |           |       |                | registry    | understood     |
   | content   | 3     | tstr / uint    | CoAP        | Content type   |
   | type      |       |                | Content-    | of the payload |
   |           |       |                | Formats or  |                |
   |           |       |                | Media Types |                |
   |           |       |                | registries  |                |
   | kid       | 4     | bstr           |             | Key identifier |
   | IV        | 5     | bstr           |             | Full           |
   |           |       |                |             | Initialization |
   |           |       |                |             | Vector         |
   | Partial   | 6     | bstr           |             | Partial        |
   | IV        |       |                |             | Initialization |
   |           |       |                |             | Vector         |
   | counter   | 7     | COSE_Signature |             | CBOR-encoded   |
   | signature |       | / [+           |             | signature      |
   |           |       | COSE_Signature |             | structure      |
   |           |       | ]              |             |                |
   +-----------+-------+----------------+-------------+----------------+

                     Table 2: Common Header Parameters

   The CDDL fragment that represents the set of headers defined in this
   section is given below.  Each of the headers is tagged as optional
   because they do not need to be in every map; headers required in
   specific maps are discussed above.

   Generic_Headers = (
       ? 1 => int / tstr,  ; algorithm identifier
       ? 2 => [+label],    ; criticality
       ? 3 => tstr / int,  ; content type
       ? 4 => bstr,        ; key identifier
       ? 5 => bstr,        ; IV
       ? 6 => bstr,        ; Partial IV
       ? 7 => COSE_Signature / [+COSE_Signature] ; Counter signature
   )


Next Section