Draft: draft-ietf-cose-rfc8152bis-struct

Commentary: Upgrade from v2 to v3
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.
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.
The description of the structure for the CBOR objects which are
transmitted over the wire.  Two objects are defined for
encryption, signing and message authentication.  One object is
defined for transporting keys and one for transporting groups of
keys.
The procedures used to build the inputs to the cryptographic
functions required for each of the structures.
A starting set of attributes that apply to the different security
objects.
Define a single top message structure so that encrypted, signed,
and MACed messages can easily be identified and still have a
consistent view.
Signed messages distinguish between the protected and unprotected
parameters that relate to the content from those that relate to
the signature.
MACed messages are separated from signed messages.
MACed messages have the ability to use the same set of recipient
algorithms as enveloped messages for obtaining the MAC
authentication key.
Use binary encodings for binary data rather than base64url
encodings.
Combine the authentication tag for encryption algorithms with the
ciphertext.
The set of cryptographic algorithms has been expanded in some
directions and trimmed in others.
Split the orignal document into this document and I-D.ietf-cose-
rfc8152bis-algs.
Add some text describing why there is no digest structure defined
by COSE.
Rearrange the text around counter signatures and define a CBOR Tag
for a standalone countersignature.
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).
FOO / BAR -- indicates that either FOO or BAR can appear here.
type1 .cbor type2 -- indicates that the contents of type1, usually
bstr, contains a value of type2.
The set of protected header parameters wrapped in a bstr.
The set of unprotected header parameters as a map.
The content of the message.  The content is either the plaintext
or the ciphertext as appropriate.  The content may be detached
(i.e. transported separately from the COSE structure), but the
location is still used.  The content is wrapped in a bstr when
present and is a nil value when detached.
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.
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 CBOR-Tags.
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
CBOR-Tags.
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 CoAP_content_type.  The
CBOR tag for the message structure is not required as each
security message is uniquely identified.
Contains parameters about the current layer that are
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 byte 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 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.
Contains parameters about the current layer that are not
cryptographically protected.
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_Sign1, COSE_Mac, and
COSE_Mac0).  This authentication can be done either by placing the
parameter in the protected header bucket or as part of the
externally supplied data.  The value is taken from the "COSE
Algorithms" registry (see COSE.Algorithms).
Integer labels in the range of 0 to 7 SHOULD be omitted.
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.
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.
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.
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.
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 (Context IV) while a portion can
be changed with each message (Parital IV).  This field is used to
carry a value that causes the IV to be changed for each message.
The Parital IV can be placed in the unprotected header as
modifying the value 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.
Left-pad the Partial IV with zeros to the length of IV.
XOR the padded Partial IV with the context IV.
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 counter
signatures are found in counter_signature.
When more than one signature is present, the successful validation
of one signature associated with a given signer is usually treated
as a successful signature by that signer.  However, there are some
application environments where other rules are needed.  An
application that employs a rule other than one valid signature for
each signer must specify those rules.  Also, where simple matching
of the signer identifier is not sufficient to determine whether
the signatures were generated by the same signer, the application
specification must describe how to determine which signatures were
generated by the same signer.  Support for different communities
of recipients is the primary reason that signers choose to include
more than one signature.
This field contains the serialized content to be signed.  If the
payload is not present in the message, the application is required
to supply the payload separately.  The payload is wrapped in a
bstr to ensure that it is transported without changes.  If the
payload is transported separately ("detached content"), then a nil
CBOR object is placed in this location, and it is the
responsibility of the application to ensure that it will be
transported without changes.
Note: When a signature with a message recovery algorithm is used
(SigAlgs), the maximum number of bytes that can be recovered is
the length of the payload.  The size of the payload is reduced by
the number of bytes that will be recovered.  If all of the bytes
of the payload are consumed, then the payload is encoded as a
zero-length binary string rather than as being absent.
This field is an array of signatures.  Each signature is
represented as a COSE_Signature structure.
This field contains the computed signature value.  The type of the
field is a bstr.  Algorithms MUST specify padding if the signature
value is not a multiple of 8 bits.
This is as described in full-signature.
This field contains the computed signature value.  The type of the
field is a bstr.
If multiple items are included, applications need to ensure that
the same byte string cannot produced if there are different
inputs.  This would occur by appending the strings 'AB' and 'CDE'
or by appending the strings 'ABC' and 'DE'.  This is usually
addressed by making fields a fixed width and/or encoding the
length of the field as part of the output.  Using options from
CoAP RFC7252 as an example, these fields use a TLV structure so
they can be concatenated without any problems.
If multiple items are included, an order for the items needs to be
defined.  Using options from CoAP as an example, an application
could state that the fields are to be ordered by the option
number.
Applications need to ensure that the byte string is going to be
the same on both sides.  Using options from CoAP might give a
problem if the same relative numbering is kept.  An intermediate
node could insert or remove an option, changing how the relative
number is done.  An application would need to specify that the
relative number must be re-encoded to be relative only to the
options that are in the external data.
"Signature" for signatures using the COSE_Signature structure.
"Signature1" for signatures using the COSE_Sign1 structure.
"CounterSignature" for signatures used as counter signature
attributes.
"CounterSignature0" for signatures used as CounterSignature0
attributes.
The protected attributes from the signer structure encoded in a
bstr type.  If there are no protected attributes, a bstr of length
zero is used.  This field is omitted for the COSE_Sign1 signature
structure and CounterSignature0 attributes.
The payload to be signed encoded in a bstr type.  The payload is
placed here independent of how it is transported.
Create a Sig_structure and populate it with the appropriate
fields.
Call the signature creation algorithm passing in K (the key to
sign with), alg (the algorithm to sign with), and ToBeSigned (the
value to sign).
Place the resulting signature value in the correct location.  This
is the 'signature' field of the COSE_Signature, COSE_Sign1 or
COSE_Countersignature structures.  This is the value of the
Countersignature0 attribute.
Create a Sig_structure object and populate it with the appropriate
fields.
Call the signature verification algorithm passing in K (the key to
verify with), alg (the algorithm used sign with), ToBeSigned (the
value to sign), and sig (the signature to be verified).
This field contains the ciphertext encoded as a bstr.  If the
ciphertext is to be transported independently of the control
information about the encryption process (i.e., detached content),
then the field is encoded as a nil value.
This field contains an array of recipient information structures.
The type for the recipient information structure is a
COSE_recipient.
This field contains the encrypted key encoded as a bstr.  All
encoded keys are symmetric keys; the binary value of the key is
the content.  If there is not an encrypted key, then this field is
encoded as a nil value.
This field contains an array of recipient information structures.
The type for the recipient information structure is a
COSE_recipient (an example of this can be found in three-layer).
If there are no recipient information structures, this element is
absent.
The CEK is the same as the identified previously distributed
symmetric key or is derived from a previously distributed secret.
No CEK is transported in the message.
The CEK is encrypted using a previously distributed symmetric KEK.
Also known as key wrap.
The recipient's public key and a sender's private key are used to
generate a pairwise secret, a Key Derivation Function (KDF) is
applied to derive a key, and then the CEK is either the derived
key or encrypted by the derived key.
The CEK is encrypted with the recipient's public key.
The CEK is encrypted in a KEK that is derived from a password.  As
of when this document was published, no password algorithms have
been defined.
"Encrypt0" for the content encryption of a COSE_Encrypt0 data
structure.
"Encrypt" for the first layer of a COSE_Encrypt data structure
(i.e., for content encryption).
"Enc_Recipient" for a recipient encoding to be placed in an
COSE_Encrypt data structure.
"Mac_Recipient" for a recipient encoding to be placed in a
MACed message structure.
"Rec_Recipient" for a recipient encoding to be placed in a
recipient structure.
Encode the Enc_structure to a byte string (Additional
Authenticated Data (AAD)), using the encoding described in CBOR-
Canonical.
The key is randomly or pseudorandomly generated.
Call the encryption algorithm with K (the encryption key), P (the
plaintext), and AAD.  Place the returned ciphertext into the
'ciphertext' field of the structure.
Encode the Enc_structure to a byte string (AAD), using the
encoding described in CBOR-Canonical.
Call the decryption algorithm with K (the decryption key to use),
C (the ciphertext), and AAD.
The key is randomly generated.
Call the encryption algorithm with K (the encryption key to use)
and P (the plaintext).  Place the returned ciphertext into the
'ciphertext' field of the structure.
Call the decryption algorithm with K (the decryption key to use)
and C (the ciphertext).
This field contains the serialized content to be MACed.  If the
payload is not present in the message, the application is required
to supply the payload separately.  The payload is wrapped in a
bstr to ensure that it is transported without changes.  If the
payload is transported separately (i.e., detached content), then a
nil CBOR value is placed in this location, and it is the
responsibility of the application to ensure that it will be
transported without changes.
This is as described in Mac_n.
A text string that identifies the structure that is being encoded.
This string is "MAC" for the COSE_Mac structure.  This string is
"MAC0" for the COSE_Mac0 structure.
The protected attributes from the COSE_MAC structure.  If there
are no protected attributes, a zero-length bstr is used.
The payload to be MACed encoded in a bstr type.  The payload is
placed here independent of how it is transported.
Create a MAC_structure and populate it with the appropriate
fields.
Place the resulting MAC in the 'tag' field of the COSE_Mac or
COSE_Mac0 structure.
For COSE_Mac structures, encrypt and encode the MAC key for each
recipient of the message.
Create a MAC_structure object and populate it with the appropriate
fields.
For COSE_Mac structures, obtain the cryptographic key from one of
the recipients of the message.
Compare the MAC value to the 'tag' field of the COSE_Mac or
COSE_Mac0 structure.
This document defines a set of common parameters for a COSE Key
object.  table-key-labels provides a summary of the parameters
defined in this section.  There are also parameters that are defined
for specific key types.  Key-type-specific parameters can be found in
I-D.ietf-cose-rfc8152bis-algs.
This parameter is used to identify the family of keys for this
structure and, thus, the set of key-type-specific parameters to be
found.  The set of values defined in this document can be found in
COSE.KeyTypes.  This parameter MUST be present in a key object.
Implementations MUST verify that the key type is appropriate for
the algorithm being processed.  The key type MUST be included as
part of the trust decision process.
This parameter is used to restrict the algorithm that is used with
the key.  If this parameter is present in the key structure, the
application MUST verify that this algorithm matches the algorithm
for which the key is being used.  If the algorithms do not match,
then this key object MUST NOT be used to perform the cryptographic
operation.  Note that the same key can be in a different key
structure with a different or no algorithm specified; however,
this is considered to be a poor security practice.
This parameter is used to give an identifier for a key.  The
identifier is not structured and can be anything from a user-
provided string to a value computed on the public portion of the
key.  This field is intended for matching against a 'kid'
parameter in a message in order to filter down the set of keys
that need to be checked.
This parameter is defined to restrict the set of operations that a
key is to be used for.  The value of the field is an array of
values from table-key-ops.  Algorithms define the values of key
ops that are permitted to appear and are required for specific
operations.  The set of values matches that in RFC7517 and
W3C.WebCrypto.
This parameter is defined to carry the base portion of an IV.  It
is designed to be used with the Partial IV header parameter
defined in cose-headers.  This field provides the ability to
associate a Partial IV with a key that is then modified on a per
message basis with the Partial IV.
Extreme care needs to be taken when using a Base IV in an
application.  Many encryption algorithms lose security if the same
IV is used twice.
If different keys are derived for each sender, using the same Base
IV with Partial IVs starting at zero is likely to ensure that the
IV would not be used twice for a single key.  If different keys
are derived for each sender, starting at the same Base IV is
likely to satisfy this condition.  If the same key is used for
multiple senders, then the application needs to provide for a
method of dividing the IV space up between the senders.  This
could be done by providing a different base point to start from or
a different Partial IV to start with and restricting the number of
messages to be sent before rekeying.
This document defines a set of common parameters for a COSE Key
object.  x-table-key-labels provides a summary of the parameters
defined in this section.  There are also parameters that are defined
for specific key types.  Key-type-specific parameters can be found in
I-D.ietf-cose-rfc8152bis-algs.
Secrets that are uniformly random: This is the type of secret that
is created by a good random number generator.
Secrets that are not uniformly random: This is type of secret that
is created by operations like key agreement.
Secrets that are not random: This is the type of secret that
people generate for things like passwords.
The 'protected' field MUST be a zero-length item unless it is used
in the computation of the content key.
The 'alg' parameter MUST be present.
A parameter identifying the shared secret SHOULD be present.
The 'ciphertext' field MUST be a zero-length item.
The 'recipients' field MUST be absent.
The 'protected' field MUST be absent if the key wrap algorithm is
an AE algorithm.
The 'recipients' field is normally absent, but can be used.
Applications MUST deal with a recipient field being present that
has an unsupported algorthms, not being able to decrypt that
recipient is an acceptable way of dealing with it.  Failing to
process the message is not an acceptable way of dealing with it.
The plaintext to be encrypted is the key from next layer down
(usually the content layer).
At a minimum, the 'unprotected' field MUST contain the 'alg'
parameter and SHOULD contain a parameter identifying the shared
secret.
The 'protected' field MUST be absent.
At a minimum, the 'unprotected' field MUST contain the 'alg'
parameter and SHOULD contain a parameter identifying the
asymmetric key.
Ephemeral-Static (ES) DH: where the sender of the message creates
a one-time DH key and uses a static key for the recipient.  The
use of the ephemeral sender key means that no additional random
input is needed as this is randomly generated for each message.
Static-Static (SS) DH: where a static key is used for both the
sender and the recipient.  The use of static keys allows for the
recipient to get a weak version of data origination for the
message.  When static-static key agreement is used, then some
piece of unique data for the KDF is required to ensure that a
different key is created for each message.
At a minimum, headers MUST contain the 'alg' parameter and SHOULD
contain a parameter identifying the recipient's asymmetric key.
The headers SHOULD identify the sender's key for the static-static
versions and MUST contain the sender's ephemeral key for the
ephemeral-static versions.
The 'protected' field is fed into the KDF context structure.
The 'alg' parameter MUST be present in the layer.
A parameter identifying the recipient's key SHOULD be present.  A
parameter identifying the sender's key SHOULD be present.
The restriction applies to the encoding of the Sig_structure, the
Enc_structure, and the MAC_structure.
Encoding MUST be done using definite lengths and values MUST be
the minimum possible length.  This means that the integer 1 is
encoded as "0x01" and not "0x1801".
Applications MUST NOT generate messages with the same label used
twice as a key in a single map.  Applications MUST NOT parse and
process messages with the same label used twice as a key in a
single map.  Applications can enforce the parse and process
requirement by using parsers that will fail the parse step or by
using parsers that will pass all keys to the application, and the
application can perform the check for duplicate keys.
Applications need to determine the set of messages defined in this
document that they will be using.  The set of messages corresponds
fairly directly to the set of security services that are needed
and to the security levels needed.
Applications may define new header parameters for a specific
purpose.  Applications will often times select specific header
parameters to use or not to use.  For example, an application
would normally state a preference for using either the IV or the
Partial IV parameter.  If the Partial IV parameter is specified,
then the application also needs to define how the fixed portion of
the IV is determined.
When applications use externally defined authenticated data, they
need to define how that data is encoded.  This document assumes
that the data will be provided as a byte string.  More information
can be found in Extern_AAD.
Applications need to determine the set of security algorithms that
are to be used.  When selecting the algorithms to be used as the
mandatory-to-implement set, consideration should be given to
choosing different types of algorithms when two are chosen for a
specific purpose.  An example of this would be choosing HMAC-
SHA512 and AES-CMAC as different MAC algorithms; the construction
is vastly different between these two algorithms.  This means that
a weakening of one algorithm would be unlikely to lead to a
weakening of the other algorithms.  Of course, these algorithms do
not provide the same level of security and thus may not be
comparable for the desired security functionality.
Advertising in the message (S/MIME capabilities) RFC5751.
Advertising in the certificate (capabilities extension)
RFC4262.
Minimum requirements for the S/MIME, which have been updated
over time RFC2633 RFC5751 (note that RFC2633 has been obsoleted
by RFC5751).
Applications that use this media type: IoT applications sending
security content over HTTP(S) transports.
Using the same key for two different algorithms can leak
information about the key.  It is therefore recommended that keys
be restricted to a single algorithm.
Use of 'direct' as a recipient algorithm combined with a second
recipient algorithm exposes the direct key to the second
recipient.
Several of the algorithms in I-D.ietf-cose-rfc8152bis-algs have
limits on the number of times that a key can be used without
leaking information about the key.
What are the permissions associated with the key owner?
Is the cryptographic algorithm acceptable in the current context?
Have the restrictions associated with the key, such as algorithm
or freshness, been checked and are they correct?
Is the request something that is reasonable, given the current
state of the application?
Have any security considerations that are part of the message been
enforced (as specified by the application or 'crit' parameter)?
Languages: There are three different languages that are currently
supported: Java, C# and C.
Cryptography: The Java and C# libraries use Bouncy Castle to
provide the required cryptography.  The C version uses OPENSSL
Version 1.0 for the cryptography.
Coverage: The C version currently does not have full countersign
support.  The other two versions do.  They do have support to
allow for implicit algorithm support as they allow for the
application to set attributes that are not to be sent in the
message.
Testing: All of the examples in the example library are generated
by the C# library and then validated using the Java and C
libraries.  All three libraries have tests to allow for the
creating of the same messages that are in the example library
followed by validating them.  These are not compared against the
example library.  The Java and C# libraries have unit testing
included.  Not all of the MUST statements in the document have
been implemented as part of the libraries.  One such statement is
the requirement that unique labels be present.
Coverage: Full Encrypt, Signature and MAC objects are supported.
Testing: Basic testing against the common example library.
Testing: Basic testing plus running against the common example
library.
Description: A set of tests for the COSE library is provided as
part of the implementation effort.  Both success and fail tests
have been provided.  All of the examples in this document are part
of this example set.
Coverage: An attempt has been made to have test cases for every
message type and algorithm in the document.  Currently examples
dealing with counter signatures, and ECDH with Curve24459 and
Goldilocks are missing.