Draft: draft-ietf-cose-msg

Commentary: Do a word smithing pass Change to use comprssed EPK
There has been an increased focus on the small, constrained devices
that make up the Internet of Things (IOT).  One of the standards that
has come out of this process is the Concise Binary Object
Representation (CBOR).  CBOR extended the data model of the
JavaScript Object Notation (JSON) 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 as well having a schema
free decoder.  A need exists to provide basic message security
services for IOT and using CBOR as the message encoding format makes
sense.
There has been an increased focus on the small, constrained devices
that make up the Internet of Things (IOT).  One of the standards that
has come out of this process is the Concise Binary Object
Representation (CBOR).  CBOR extended the data model of the
JavaScript Object Notation (JSON) 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 as well having 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 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 in this
document except for keys.  While these buckets can be present, they
may not all be usable in all instances.  For example, while the
protected bucket is defined as part of recipient structures, most of
the algorithms that are used for recipients do not provide for
authenticated data and thus the bucket should not be used.
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 can be present, they may not all be usable
in all instances.  For example, while the protected bucket is defined
as part of recipient structures, most of the algorithms that are used
for recipients do not provide for authenticated data and thus the
bucket should not be used.
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 perform the same checks that the
labels appearing in the protected and unprotected headers are unique
as well.  If the message is not rejected as malformed, attributes
MUST be obtained from the protected bucket before they are obtained
from the unprotected bucket.
This parameter is used to ensure that applications will take
appropriate action based on the values found.  The parameter is
used to indicate which protected header labels an application that
is processing a message is required to understand.  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.
Labels for parameters required for an application MAY be
omitted.  Applications should have a statement if the label can
or cannot be omitted.
This parameter holds a counter signature value.  Counter
signatures provide a method of having a second party sign some
data.  The counter signature can occur as an unprotected attribute
in any of the following structures: COSE_Sign, COSE_Sign1,
COSE_Signature, COSE_Enveloped, COSE_recipient, COSE_Encrypted,
COSE_Mac and COSE_Mac0.  These structures all have the same basic
structure so that a consistent calculation of the counter
signature can be computed.  Details on computing counter
signatures are found in counter_signature.
This parameter holds a counter signature value.  Counter
signatures provide a method of having a second party sign some
data.  The counter signature can occur as an unprotected attribute
in any of the following structures: COSE_Sign, COSE_Sign1,
COSE_Signature, COSE_Enveloped, COSE_recipient, COSE_Encrypted,
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 counter_signature.
so that they cannot be modified in transit.  This is the purpose of
the externally supplied data field.
so that if they cannot be modified in transit it can be detected.
This is the purpose of the externally supplied data field.
The protected attributes from the body structure encoded in a bstr
type.
The protected attributes from the signer structure encoded in a
bstr type.  This field is omitted for the COSE_Sign1 signature
structure.
The protected attributes from the body structure encoded in a bstr
type.  If there are no protected attributes, a bstr of length zero
is used.
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.
Create a Sig_structure and populate it with the appropriate
fields.  For body_protected and sign_protected, if the map is
empty, a bstr of length zero is used.
Create a Sig_structure and populate it with the appropriate
fields.
Create a Sig_structure object and populate it with the appropriate
fields.  For body_protected and sign_protected, if the map is
empty, a bstr of length zero is used.
Create a Sig_structure object and populate it with the appropriate
fields.
An example of a proxy signature on a signature can be found in Sig-
03.  An example of a proxy signature on an encryption object can be
found in Enc-03.
The creation and validation of counter signatures over the different
items relies on the fact that the structure all of our objects have
the same structure.  The elements are a set of protected attributes,
a set of unprotected attributes and a body in that order.  This means
that the Sig_structure can be used for in a uniform manner to get the
byte stream for processing a signature.  If the counter signature is
going to be computed over a COSE_Enveloped structure, the
body_protected and payload items can be mapped into the Sig_structure
in the same manner as from the COSE_Sign structure.
It should be noted that only signature algorithm with appendix (see
SigAlgs) should be used for counter signatures.  This is because the
body should be able to be processed without having to evaluate the
countersignature, and this is not possible for signature schemes with
message recovery.
COSE supports two different encryption structures.  COSE_Enveloped is
used when the key needs to be explicitly identified.  This structure
supports the use of recipient structures to allow for random content
encryption keys to be used.  COSE_Encrypted is used when a recipient
structure is not needed because the key to be used is known
implicitly.
In COSE, the same techniques and structures are used for encrypting
both the plain text and the keys used to protect the text.  This is
different from the approach used by both RFC5652 and RFC7516 where
different structures are used for the content layer and for the
recipient layer.  Two structures are defined COSE_Enveloped to hold
the encrypted content and COSE_recipient to hold the encrypted keys
for recipients.  Examples of encrypted messages can be found in
EncryptedExamples.
An example of a counter signature on a signature can be found in Sig-
03.  An example of a counter signature in an encryption object can be
found in Enc-03.
The creation and validation of counter signatures over the different
items relies on the fact that the structure of the objects have the
same structure.  The elements are a set of protected attributes, a
set of unprotected attributes and a body in that order.  This means
that the Sig_structure can be used for in a uniform manner to get the
byte stream for processing a signature.  If the counter signature is
going to be computed over a COSE_Enveloped structure, the
body_protected and payload items can be mapped into the Sig_structure
in the same manner as from the COSE_Sign structure.
It should be noted that only a signature algorithm with appendix (see
SigAlgs) can be used for counter signatures.  This is because the
body should be able to be processed without having to evaluate the
countersignature, and this is not possible for signature schemes with
message recovery.
COSE supports two different encryption structures.  COSE_Encrypted is
used when a recipient structure is not needed because the key to be
used is known implicitly.  COSE_Enveloped is used the rest of time
time.  This includes cases where there are multiple recipients, a
recipient algorithm other than direct is to be used, or the key to be
used is not known.
The enveloped structure allows for one or more recipients of a
message.  There are provisions for parameters about the content and
parameters about the recipient information to be carried in the
message.  The protected parameters associated with the content are
authenticated by the content encryption algorithm.  The protected
parameters associated with the recipient are authenticated by the
recipient algorithm (when the algorithm supports it).  Examples of
parameters about the content are the type of the content, and the
content encryption algorithm.  Examples of parameters about the
recipient are the recipient's key identifier, the recipient
encryption algorithm.
The same techniques and structures are used for encrypting both the
plain text and the keys used to protect the text.  This is different
from the approach used by both RFC5652 and RFC7516 where different
structures are used for the content layer and for the recipient
layer.  Two structures are defined: COSE_Enveloped to hold the
encrypted content, and COSE_recipient to hold the encrypted keys for
recipients.  Examples of encrypted messages can be found in
EncryptedExamples.
contains the encrypted plain text 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 null object.
contains the cipher text 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 null object.
contains an array of recipient information structures.  The type
for the recipient information structure is a COSE_recipient.  If
there are no recipient information structures, this element is
absent.
contains an array of recipient information structures.  The type
for the recipient information structure is a COSE_recipient.  (And
example of this can be found in three-layer.)  If there are no
recipient information structures, this element is absent.
The CEK is encrypted with the recipient's public key.
The CEK is encrypted in a KEK that is derived from a password.
The CEK is encrypted with the recipient's public key.  No key
transport algorithms are defined in this document.
The CEK is encrypted in a KEK that is derived from a password.  No
password algorithms are defined in this document.
contains the encrypted plain text.  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 null value.
for a recipient encoding to be placed in a recipient structure.
COSE supports two different MAC structures.  COSE_MAC is used when
the key needs to be explicitly identified.  The structure supports
the use of recipient structures to allow for random content
encryption keys to be used.  COSE_MAC0 is used when a recipient
structure is not needed because the key to be used is implicitly
known.
COSE supports two different MAC structures.  COSE_MAC0 is used when a
recipient structure is not needed because the key to be used is
implicitly known.  COSE_MAC is used for all other cases.  These
include a requirement for multiple recipients, the key being unknown,
a recipient algorithm of other than direct.
contains the recipient information.  See the description under
COSE_Enveloped for more info.
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 null CBOR
object is placed in this location and it is the responsibility of
the application to ensure that it will be transported without
changes.
as described in Mac_n.
The protected attributes from the COSE_MAC structure.  If there
are no protected attributes, a zero length binary string is to be
encoded.
The protected attributes from the COSE_MAC structure.  If there
are no protected attributes, a zero length bstr is used.
Encode the MAC_structure using a canonical CBOR encoder.  The
resulting bytes is the value to compute the MAC on.
Encode the MAC_structure using a canonical CBOR encoder.  The
resulting bytes are the value to compute the MAC on.
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 a set of parameters that are
defined for a specific key type.  Key type specific parameters can be
found in Key-specific-labels.
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
Key-specific-labels.
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
table_key_types.  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 a trust decision process.
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
table_key_types.  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.
becomes the same as doing a signature with appendix.  Thirdly, in the
event that multiple signatures are applied to a message, all of the
signature algorithms are going to be required to consume the same
number of bytes of message content.
becomes the same as doing a signature with appendix.  Finally, in the
event that multiple signatures are applied to a message, all of the
signature algorithms are going to be required to consume the same
number of bytes of message content.  This means that mixing of the
different schemes in a single message is not supported, and if a
recovery signature scheme is used then the same amount of content
needs to be consumed by all of the signatures.
The signature algorithm results in a pair of integers (R, S).  These
integers will be of the same order as length of the key used for the
signature process.  The signature is encoded by converting the
integers into byte strings of the same length as the key size.  The
length is rounded up to the nearest byte and is left padded with zero
bits to get to the correct length.  The two integers are then
concatenated together to form a byte string that is the resulting
signature.
The signature algorithm results in a pair of integers (R, S).  These
integers will the same length as length of the key used for the
signature process.  The signature is encoded by converting the
integers into byte strings of the same length as the key size.  The
length is rounded up to the nearest byte and is left padded with zero
bits to get to the correct length.  The two integers are then
concatenated together to form a byte string that is the resulting
signature.
Note: Use of this technique a good idea even when good random number
generation exists.  Doing so both reduces the possibility of having
the same value of 'k' in two signature operations, but allows for
reproducible signature values which helps testing.
Note: Use of this technique a good idea even when good random number
generation exists.  Doing so both reduces the possibility of having
the same value of 'k' in two signature operations and allows for
reproducible signature values which helps testing.
MACs use the same scheme as signature with appendix algorithms.  The
message content is processed and an authentication code is produced.
The authentication code is frequently called a tag.
The HMAC algorithm is parameterized by an inner and outer padding, a
hash function (h) and an authentication tag value length.  For this
specification, the inner and outer padding are fixed to the values
set in RFC2104.  The length of the authentication tag corresponds to
the difficulty of producing a forgery.  For use in constrained
environments, we define a set of HMAC algorithms that are truncated.
There are currently no known issues when truncating, however the
security strength of the message tag is correspondingly reduced in
strength.  When truncating, the left-most tag length bits are kept
and transmitted.
The HMAC algorithm is parameterized by an inner and outer padding, a
hash function (h) and an authentication tag value length.  For this
specification, the inner and outer padding are fixed to the values
set in RFC2104.  The length of the authentication tag corresponds to
the difficulty of producing a forgery.  For use in constrained
environments, we define a set of HMAC algorithms that are truncated.
There are currently no known issues with truncation, however the
security strength of the message tag is correspondingly reduced in
strength.  When truncating, the left-most tag length bits are kept
and transmitted.
Some recipient algorithms carry the key while others derive a key
from secret data.  For those algorithms that carry the key (i.e.
RSA-OAEP and AES-KeyWrap), the size of the HMAC key SHOULD be the
same size as the underlying hash function.  For those algorithms that
derive the key, the derived key MUST be the same size as the
underlying hash function.
Some recipient algorithms carry the key while others derive a key
from secret data.  For those algorithms that carry the key (i.e.
AES-KeyWrap), the size of the HMAC key SHOULD be the same size as the
underlying hash function.  For those algorithms that derive the key
(i.e.  ECDH), the derived key MUST be the same size as the underlying
hash function.
AES-CBC-MAC is defined in MAC.
AES-CBC-MAC is defined in MAC.  (Note this is not the same algorithm
as AES-CMAC RFC4493).
The total amount of data encrypted MUST NOT exceed 2^39 - 256
bits.  An explicit check is required only in environments where it
is expected that it might be exceeded.
The total amount of data encrypted for a single key MUST NOT
exceed 2^39 - 256 bits.  An explicit check is required only in
environments where it is expected that it might be exceeded.
We define a matrix of algorithms in this document over the values of
L and M.  Constrained devices are usually operating in situations
where they use short messages and want to avoid doing recipient
specific cryptographic operations.  This favors smaller values of
both L and M.  Less constrained devices do will want to be able to
user larger messages and are more willing to generate new keys for
every operation.  This favors larger values of L and M.
Many functions are going to handle the first two type of secrets
differently.  The KDF function defined in HKDF can use different
underlying constructions if the secret is uniformly random than if
the secret is not uniformly random.  This is reflected in the set of
algorithms defined for HKDF.
When using KDF functions, one component that is generally included is
context information.  Context information is used to allow for
different keying information to be derived from the same secret.  The
use of context based keying material is considered to be a good
security practice.  This document defines a single context structure
and a single KDF function.
The same KDF function can be setup to deal with the first two types
of secrets different.  The KDF function defined in HKDF is such a
function.  This is reflected in the set of algorithms defined for
HKDF.
When using KDF functions, one component that is included is context
information.  Context information is used to allow for different
keying information to be derived from the same secret.  The use of
context based keying material is considered to be a good security
practice.  This document defines a single context structure and a
single KDF function.
salt - an optional public value that is used to change the
generation process.  The salt value can be either public or
private.  If the salt is public and carried in the message, then
the 'salt' algorithm header parameter defined in HKDF_Alg_Params
is used.  While RFC5869 suggests that the length of the salt be
the same as the length of the underlying hash value, any amount of
salt will improve the security as different key values will be
generated.  This parameter is protected by being included in the
key computation and does not need to be separately authenticated.
The salt value does not need to be unique for every message sent.
context information - Information that describes the context in
which the resulting value will be used.  Making this information
specific to the context that the material is going to be used
ensures that the resulting material will always be unique.  The
context structure used is encoded into the algorithm identifier.
PRF - The underlying pseudo-random function to be used in the HKDF
algorithm.  The PRF is encoded into the HKDF algorithm selection.
HKDF is defined to use HMAC as the underlying PRF.  However, it is
possible to use other functions in the same construct to provide a
different KDF function that can be more appropriate in the
constrained world.  Specifically, one can use AES-CBC-MAC as the PRF
for the expand step, but not for the extract step.  When using a good
random shared secret of the correct length, the extract step can be
skipped.  For the AES algorithm versions, the extract step is always
skipped.  The extract cannot be skipped if the secret is not
uniformly random, for example if it is the result of an ECDH key
agreement step.  (This implies that the AES HKDF function cannot be
used with ECDH.)  If the extract step is skipped, the 'salt' value is
not used as part of the KDF functionality.
salt - an optional value that is used to change the generation
process.  The salt value can be either public or private.  If the
salt is public and carried in the message, then the 'salt'
algorithm header parameter defined in HKDF_Alg_Params is used.
While RFC5869 suggests that the length of the salt be the same as
the length of the underlying hash value, any amount of salt will
improve the security as different key values will be generated.
This parameter is protected by being included in the key
computation and does not need to be separately authenticated.  The
salt value does not need to be unique for every message sent.
context information - Information that describes the context in
which the resulting value will be used.  Making this information
specific to the context that the material is going to be used
ensures that the resulting material will always be tied to the
context.  The context structure used is encoded into the algorithm
identifier.
HKDF is defined to use HMAC as the underlying PRF.  However, it is
possible to use other functions in the same construct to provide a
different KDF function that is more appropriate in the constrained
world.  Specifically, one can use AES-CBC-MAC as the PRF for the
expand step, but not for the extract step.  When using a good random
shared secret of the correct length, the extract step can be skipped.
For the AES algorithm versions, the extract step is always skipped.
The extract step cannot be skipped if the secret is not uniformly
random, for example if it is the result of an ECDH key agreement
step.  (This implies that the AES HKDF version cannot be used with
ECDH.)  If the extract step is skipped, the 'salt' value is not used
as part of the HKDF functionality.
Application protocols are free to define the roles differently.  For
example, they could assign the PartyU role to the entity that
initiates the connection and allow directly sending multiple messages
over the connection in both directions without changing the role
information.  It is still recommended that different keys be derived
in each direction to avoid reflection problems.
Fields can be define by the application.  This is commonly used to
assign fixed names to parties.
Fields can be define by the application.  This is commonly used to
assign fixed names to parties, but can be used for other items
such as nonces.
This contains a nonce value.  The nonce can either be implicit
from the protocol or carried as a value in the unprotected
headers.
We define an algorithm parameter 'PartyU nonce' that can be
used to carry this value in the message However, the nonce
value could be determined by the application and the value
determined from elsewhere.
This item is optional and can be absent.
This contains the identity information for party V.  The
identities can be assigned in one of two manners.  Firstly, a
protocol can assign identities based on roles.  For example,
the roles of "client" and "server" may be assigned to different
entities in the protocol.  Each entity would then use the
correct label for the data they send or receive.  The second
way is for a protocol to assign identities is to use a name
based on a naming system (i.e.  DNS, X.509 names).
We define an algorithm parameter 'PartyU identity' that can be
used to carry identity information in the message.  However,
identity information is often known as part of the protocol and
can thus be inferred rather than made explicit.  If identity
information is carried in the message, applications SHOULD have
a way of validating the supplied identity information.  The
identity information does not need to be specified and can be
left as absent.
This contains other information that is defined by the
protocol.
This item is optional and can be absent.
See description of PartyUInfo identity.
See description of PartyUInfo nonce.
See description of PartyUInfo other.
This field contains the protected parameter field.
This field contains the protected parameter field.  If there
are no elements in the protected field, then use a zero length
bstr.
This field contains private information that is mutually known
information.  An example of this information would be a pre-
existing shared secret.  The field is optional and will only be
present if the application defines a structure for this
information.  Applications that define this SHOULD use CBOR to
encode the data so that types and lengths are correctly included.
This field contains private information that is mutually known
information.  An example of this information would be a pre-
existing shared secret.  (This could for example, be used in
combination with an ECDH key agreement to provide a secondary
proof of identity.)  The field is optional and will only be
present if the application defines a structure for this
information.  Applications that define this SHOULD use CBOR to
encode the data so that types and lengths are correctly included.
Recipient algorithms can be defined into a number of different
classes.  COSE has the ability to support many classes of recipient
algorithms.  In this section, a number of classes are listed and then
a set of algorithms are specified for each of the classes.  The names
of the recipient algorithm classes used here are the same as are
defined in RFC7516.  Other specifications use different terms for the
recipient algorithm classes or do not support some of our recipient
algorithm classes.
Recipient algorithms can be defined into a number of different
classes.  COSE has the ability to support many classes of recipient
algorithms.  In this section, a number of classes are listed and then
a set of algorithms are specified for each of the classes.  The names
of the recipient algorithm classes used here are the same as are
defined in RFC7516.  Other specifications use different terms for the
recipient algorithm classes or do not support some of the recipient
algorithm classes.
These recipient algorithms take a common shared secret between the
two parties and applies the HKDF function (HKDF) using the context
structure defined in context to transform the shared secret into the
necessary key.  The 'protected' field can be of non-zero length.  The
'protected' field is copied into the SuppPubInfo.protected field of
the context structure.  Either the 'salt' parameter of HKDF or the
partyU 'nonce' parameter of the context structure MUST be present.
The salt/nonce parameter can be generated either randomly or
deterministically.  The requirement is that it be a unique value for
the key pair in question.
These recipient algorithms take a common shared secret between the
two parties and applies the HKDF function (HKDF) using the context
structure defined in context to transform the shared secret into the
necessary key.  The 'protected' field can be of non-zero length.
Either the 'salt' parameter of HKDF or the partyU 'nonce' parameter
of the context structure MUST be present.  The salt/nonce parameter
can be generated either randomly or deterministically.  The
requirement is that it be a unique value for the key/IV pair in
question.
The AES Key Wrapping algorithm is defined in RFC3394.  This algorithm
uses an AES key to wrap a value that is a multiple of 64 bits.  As
such, it can be used to wrap a key for any of the content encryption
algorithms defined in this document.  The algorithm requires a single
fixed parameter, the initial value.  This is fixed to the value
specified in Section 2.2.3.1 of RFC3394.  There are no public
parameters that vary on a per invocation basis.
The AES Key Wrapping algorithm is defined in RFC3394.  This algorithm
uses an AES key to wrap a value that is a multiple of 64 bits.  As
such, it can be used to wrap a key for any of the content encryption
algorithms defined in this document.  The algorithm requires a single
fixed parameter, the initial value.  This is fixed to the value
specified in Section 2.2.3.1 of RFC3394.  There are no public
parameters that vary on a per invocation basis.  The protected header
field MUST be empty.
The most commonly used key agreement algorithm used is Diffie-
Hellman, but other variants exist.  Since COSE is designed for a
store and forward environment rather than an on-line environment,
many of the DH variants cannot be used as the receiver of the message
cannot provide any key material.  One side-effect of this is that
perfect forward secrecy (see RFC4949) is not achievable.  A static
key will always be used for the receiver of the COSE message.
The most commonly used key agreement algorithm is Diffie-Hellman, but
other variants exist.  Since COSE is designed for a store and forward
environment rather than an on-line environment, many of the DH
variants cannot be used as the receiver of the message cannot provide
any dynamic key material.  One side-effect of this is that perfect
forward secrecy (see RFC4949) is not achievable.  A static key will
always be used for the receiver of the COSE message.
Static-Static DH: where a static key is used for both the sender
and the recipient.  The use of static keys allows for 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 is required to ensure that a different key is created for
each message.
In this specification, both variants are specified.  This has been
done to provide the weak data origination option for use with MAC
operations.
Static-Static DH: where a static key is used for both the sender
and the recipient.  The use of static keys allows for 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.
The 'protected' field MUST be absent.
At a minimum, the 'unprotected' field MUST contain the 'alg'
parameter and SHOULD contain a parameter identifying the
recipient's asymmetric key.
The 'unprotected' field MUST contain the 'epk' parameter.
The basic mathematics for Elliptic Curve Diffie-Hellman can be found
in RFC6090.
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 senders key for the static-static
versions and MUST contain the senders ephemeral key for the
ephemeral-static versions.
The mathematics for Elliptic Curve Diffie-Hellman can be found in
RFC6090.
Key derivation algorithm: The result of an ECDH key agreement
process does not provide a uniformly random secret.  As such, it
needs to be run through a KDF in order to produce a usable key.
Processing the secret through a KDF also allows for the
introduction of both context material, how the key is going to be
used, and one time material in the even to of a static-static key
agreement.
Key Wrap algorithm: A key wrap algorithm of 'none' means that the
result of the KDF is going to be used as the key directly.  This
option, along with static-static, should be used if knowledge
about the sender is desired.  If 'none' is used, then the content
layer encryption algorithm size is value fed to the context
structure.  Support is also provided for any of the key wrap
algorithms defined in key_wrap_algs.  If one of these options is
used, the input key size to the key wrap algorithm is the value
fed into the context structure as the key size.
Key derivation algorithm: The result of an ECDH key agreement
process does not provide a uniformly random secret.  As such, it
needs to be run through a KDF in order to produce a usable key.
Processing the secret through a KDF also allows for the
introduction of both context material, how the key is going to be
used, and one time material in the event of a static-static key
agreement.
Key Wrap algorithm: No key wrap algorithm is used.  This is
represented in table-ecdh-es-table as 'none'.  The key size for
the context structure is the content layer encryption algorithm
size.
Key Wrap Algorithm: Any of the key wrap algorithms defined in
key_wrap_algs are supported.  The size of the key used for the key
wrap algorithm is fed into the KDF function.  The set of
identifiers are found in table-ecdh-es-table.
For each of the key types, we define both public and private members.
The public members are what is transmitted to others for their usage.
We define private members mainly for the purpose of archival of keys
by individuals.  However, there are some circumstances in which
private keys may be distributed by various entities in a protocol.
Examples include: entities that have poor random number generation,
centralized key creation for multi-cast type operations, and
protocols in which a shared secret is used as a bearer token for
authorization purposes.
For each of the key types, we define both public and private members.
The public members are what is transmitted to others for their usage.
We define private members mainly for the purpose of archival of keys
by individuals.  However, there are some circumstances in which
private keys may be distributed to entities in a protocol.  Examples
include: entities that have poor random number generation,
centralized key creation for multi-cast type operations, and
protocols in which a shared secret is used as a bearer token for
authorization purposes.