Draft: draft-ietf-cose-rfc8152bis-algs

Commentary: Upgrade the algs document from v2 to v3 .
Extract the sections dealing with specific algorithms into this
document.  The sections dealing with structure and general
processing rules are placed in I-D.ietf-cose-rfc8152bis-struct.
The algorithms defined in this document can be found in table_ecdsa.
The algorithms defined in this document can be found in
x-table_ecdsa.
The 'kty' field MUST be present, and it MUST be 'EC2'.
If the 'alg' field is present, it MUST match the ECDSA signature
algorithm being used.
If the 'key_ops' field is present, it MUST include 'sign' when
creating an ECDSA signature.
If the 'key_ops' field is present, it MUST include 'verify' when
verifying an ECDSA signature.
Changing the curve used to validate the signature: If one changes
the curve used to validate the signature, then potentially one
could have two messages with the same signature, each computed
under a different curve.  The only requirement on the new curve is
that its order be the same as the old one and it be acceptable to
the client.  An example would be to change from using the curve
secp256r1 (aka P-256) to using secp256k1.  (Both are 256-bit
curves.)  We currently do not have any way to deal with this
version of the attack except to restrict the overall set of curves
that can be used.
Change the hash function used to validate the signature: If one
either has two different hash functions of the same length or can
truncate a hash function down, then one could potentially find
collisions between the hash functions rather than within a single
hash function (for example, truncating SHA-512 to 256 bits might
collide with a SHA-256 bit hash value).  As the hash algorithm is
part of the signature algorithm identifier, this attack is
mitigated by including a signature algorithm identifier in the
protected header.
The algorithms defined in this document can be found in table-eddsa-
algs.  A single signature algorithm is defined, which can be used for
multiple curves.
The 'kty' field MUST be present, and it MUST be 'OKP' (Octet Key
Pair).
The 'crv' field MUST be present, and it MUST be a curve defined
for this signature algorithm.
If the 'alg' field is present, it MUST match 'EdDSA'.
If the 'key_ops' field is present, it MUST include 'sign' when
creating an EdDSA signature.
If the 'key_ops' field is present, it MUST include 'verify' when
verifying an EdDSA signature.
The algorithms defined in this document can be found in x-table-
eddsa-algs.  A single signature algorithm is defined, which can be
used for multiple curves.
The algorithms defined in this document can be found in table-hmac.
The algorithms defined in this document can be found in x-table-hmac.
If the 'alg' field is present, it MUST match the HMAC algorithm
being used.
If the 'key_ops' field is present, it MUST include 'MAC create'
when creating an HMAC authentication tag.
If the 'key_ops' field is present, it MUST include 'MAC verify'
when verifying an HMAC authentication tag.
AES-CBC-MAC is parameterized by the key length, the authentication
tag length, and the IV used.  For all of these algorithms, the IV is
fixed to all zeros.  We provide an array of algorithms for various
key lengths and tag lengths.  The algorithms defined in this document
are found in table-aes-mac.
AES-CBC-MAC is parameterized by the key length, the authentication
tag length, and the IV used.  For all of these algorithms, the IV is
fixed to all zeros.  We provide an array of algorithms for various
key lengths and tag lengths.  The algorithms defined in this document
are found in x-table-aes-mac.
If the 'alg' field is present, it MUST match the AES-MAC algorithm
being used.
If the 'key_ops' field is present, it MUST include 'MAC create'
when creating an AES-MAC authentication tag.
If the 'key_ops' field is present, it MUST include 'MAC verify'
when verifying an AES-MAC authentication tag.
Cipher Block Chaining (CBC) mode, if the same key is used for both
encryption and authentication operations, an attacker can produce
messages with a valid authentication code.
If the IV can be modified, then messages can be forged.  This is
addressed by fixing the IV to all zeros.
The set of algorithms defined in this document are in table-AES-GCM.
The set of algorithms defined in this document are in x-table-AES-
GCM.
If the 'alg' field is present, it MUST match the AES-GCM algorithm
being used.
The key and nonce pair MUST be unique for every message encrypted.
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.
This limits messages to 2^16 bytes (64 KiB) in length.  This is
sufficiently long for messages in the constrained world.  The
nonce length is 13 bytes allowing for 2^104 possible values of the
nonce without repeating.
This limits messages to 2^64 bytes in length.  The nonce length is
7 bytes allowing for 2^56 possible values of the nonce without
repeating.
This produces a 64-bit authentication tag.  This implies that
there is a 1 in 2^64 chance that a modified message will
authenticate.
This produces a 128-bit authentication tag.  This implies that
there is a 1 in 2^128 chance that a modified message will
authenticate.
If the 'alg' field is present, it MUST match the AES-CCM algorithm
being used.
The key and nonce pair MUST be unique for every message encrypted.
Note that the value of L influences the number of unique nonces.
The total number of times the AES block cipher is used MUST NOT
exceed 2^61 operations.  This limitation is the sum of times the
block cipher is used in computing the MAC value and in performing
stream encryption operations.  An explicit check is required only
in environments where it is expected that it might be exceeded.
The ChaCha20/Poly1305 AEAD construction defined in RFC8439 has no
parameterization.  It takes a 256-bit key and a 96-bit nonce, as well
as the plaintext and additional data as inputs and produces the
ciphertext as an option.  We define one algorithm identifier for this
algorithm in Table-CHACHA.
The ChaCha20/Poly1305 AEAD construction defined in RFC8439 has no
parameterization.  It takes a 256-bit key and a 96-bit nonce, as well
as the plaintext and additional data as inputs and produces the
ciphertext as an option.  We define one algorithm identifier for this
algorithm in x-table-CHACHA.
If the 'alg' field is present, it MUST match the ChaCha20/Poly1305
algorithm being used.
secret -- a shared value that is secret.  Secrets may be either
previously shared or derived from operations like a Diffie-Hellman
(DH) key agreement.
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.
length -- the number of bytes of output that need to be generated.
context information -- Information that describes the context in
which the resulting value will be used.  Making this information
specific to the context in which the material is going to be used
ensures that the resulting material will always be tied to that
usage.  The context structure defined in context is used by the
KDFs in this document.
PRF -- The underlying pseudorandom function to be used in the HKDF
algorithm.  The PRF is encoded into the HKDF algorithm selection.
The algorithms defined in this document are found in table-hkdf.
The algorithms defined in this document are found in x-table-hkdf.
Fields can be defined by the application.  This is commonly used
to assign fixed names to parties, but it can be used for other
items such as nonces.
Fields can be defined by usage of the output.  Examples of this
are the algorithm and key size that are being generated.
Fields can be defined by parameters from the message.  We define a
set of parameters in KDF_Context_Alg_Params that can be used to
carry the values associated with the context structure.  Examples
of this are identities and nonce values.  These parameters are
designed to be placed in the unprotected bucket of the recipient
structure; they do not need to be in the protected bucket since
they already are included in the cryptographic computation by
virtue of being included in the context structure.
This field indicates the algorithm for which the key material will
be used.  This normally is either a key wrap algorithm identifier
or a content encryption algorithm identifier.  The values are from
the "COSE Algorithms" registry.  This field is required to be
present.  The field exists in the context information so that if
the same environment is used for different algorithms, then
completely different keys will be generated for each of those
algorithms.  This practice means if algorithm A is broken and thus
is easier to find, the key derived for algorithm B will not be the
same as the key derived for algorithm A.
This contains the identity information for party U.  The
identities can be assigned in one of two manners.  First, 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 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 is set
to nil in that case.
This contains a nonce value.  The nonce can either be implicit
from the protocol or be 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 option does not need to be specified and is set to nil in
that case.
This contains other information that is defined by the
protocol.  This option does not need to be specified and is set
to nil in that case.
This field holds information about party V.  The content of the
structure is the same as for the PartyUInfo but for party V.
This field contains public information that is mutually known to
both parties.
This is set to the number of bits of the desired output value.
This practice means if algorithm A can use two different key
lengths, the key derived for longer key size will not contain
the key for shorter key size as a prefix.
This field contains the protected parameter field.  If there
are no elements in the protected field, then use a zero-length
bstr.
This field is for free form data defined by the application.
An example is that an application could define two different
strings to be placed here to generate different keys for a data
stream versus a control stream.  This 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
private information.  An example of this information would be a
preexisting 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.
This recipient algorithm is the simplest; the identified key is
directly used as the key for the next layer down in the message.
There are no algorithm parameters defined for this algorithm.  The
algorithm identifier value is assigned in table-direct.
This recipient algorithm is the simplest; the identified key is
directly used as the key for the next layer down in the message.
There are no algorithm parameters defined for this algorithm.  The
algorithm identifier value is assigned in x-table-direct.
These keys need to have some method to be regularly updated over
time.  All of the content encryption algorithms specified in this
document have limits on how many times a key can be used without
significant loss of security.
These keys need to be dedicated to a single algorithm.  There have
been a number of attacks developed over time when a single key is
used for multiple different algorithms.  One example of this is
the use of a single key for both the CBC encryption mode and the
CBC-MAC authentication mode.
Breaking one message means all messages are broken.  If an
adversary succeeds in determining the key for a single message,
then the key for all messages is also determined.
The set of algorithms defined in this document can be found in table-
direct-kdf.
If the 'alg' field is present, it MUST match the algorithm being
used.
If the 'key_ops' field is present, it MUST include 'deriveKey' or
'deriveBits'.
The set of algorithms defined in this document can be found in x-
table-direct-kdf.
If the 'alg' field is present, it MUST match the AES Key Wrap
algorithm being used.
Curve Type/Curve: The curve selected controls not only the size of
the shared secret, but the mathematics for computing the shared
secret.  The curve selected also controls how a point in the curve
is represented and what happens for the identity points on the
curve.  In this specification, we allow for a number of different
curves to be used.  A set of curves are defined in table-ec-
curves.
The math used to obtain the computed secret is based on the curve
selected and not on the ECDH algorithm.  For this reason, a new
algorithm does not need to be defined for each of the curves.
Computed Secret to Shared Secret: Once the computed secret is
known, the resulting value needs to be converted to a byte string
to run the KDF.  The x-coordinate is used for all of the curves
defined in this document.  For curves X25519 and X448, the
resulting value is used directly as it is a byte string of a known
length.  For the P-256, P-384, and P-521 curves, the x-coordinate
is run through the I2OSP function defined in RFC8017, using the
same computation for n as is defined in ECDSA.
Ephemeral-Static or Static-Static: The key agreement process may
be done using either a static or an ephemeral key for the sender's
side.  When using ephemeral keys, the sender MUST generate a new
ephemeral key for every key agreement operation.  The ephemeral
key is placed in the 'ephemeral key' parameter and MUST be present
for all algorithm identifiers that use ephemeral keys.  When using
static keys, the sender MUST either generate a new random value or
create a unique value.  For the KDFs used, this means either the
'salt' parameter for HKDF (HKDF_Alg_Params) or the 'PartyU nonce'
parameter for the context structure (KDF_Context_Alg_Params) MUST
be present (both can be present if desired).  The value in the
parameter MUST be unique for the pair of keys being used.  It is
acceptable to use a global counter that is incremented for every
static-static operation and use the resulting value.  When using
static keys, the static key should be identified to the recipient.
The static key can be identified either by providing the key
('static key') or by providing a key identifier for the static key
('static key id').  Both of these parameters are defined in table-
ecdh-es-parameter-table.
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 context material: how the key is going to be used
and one-time material for static-static key agreement.  All of the
algorithms defined in this document use one of the HKDF algorithms
defined in HKDF with the context structure defined in context.
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.
The set of direct ECDH algorithms defined in this document are found
in table-ecdh-es-table.
The set of direct ECDH algorithms defined in this document are found
in x-table-ecdh-es-table.
These algorithms are defined in table-ecdh-es-table-wrap.
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.  The set of identifiers are
found in table-ecdh-es-table-wrap.
These algorithms are defined in x-table-ecdh-es-table-wrap.
This contains an identifier of the curve to be used with the key.
The curves defined in this document for this key type can be found
in table-ec-curves.  Other curves may be registered in the future,
and private curves can be used as well.
This contains the x-coordinate for the EC point.  The integer is
converted to an octet string as defined in SEC1.  Leading zero
octets MUST be preserved.
This contains either the sign bit or the value of the y-coordinate
for the EC point.  When encoding the value y, the integer is
converted to an octet string (as defined in SEC1) and encoded as a
CBOR bstr.  Leading zero octets MUST be preserved.  The compressed
point encoding is also supported.  Compute the sign bit as laid
out in the Elliptic-Curve-Point-to-Octet-String Conversion
function of SEC1.  If the sign bit is zero, then encode y as a
CBOR false value; otherwise, encode y as a CBOR true value.  The
encoding of the infinity point is not supported.
This contains an identifier of the curve to be used with the key.
The curves defined in this document for this key type can be found
in table-ec-curves.  Other curves may be registered in the future
and private curves can be used as well.
This contains the x-coordinate for the EC point.  The octet string
represents a little-endian encoding of x.
This contains the value of the key.
The restriction applies to the encoding of the COSE_KDF_Context.
Encoding MUST be done using definite lengths and the length of the
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.
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 this document 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)?