Table of Contents

Class CoseKey

Namespace
Yubico.YubiKey.Fido2.Cose
Assembly
Yubico.YubiKey.dll

A base class for all COSE key representations.

public abstract class CoseKey : ICborEncode
Inheritance
object
CoseKey
Implements
Derived

Constructors

CoseKey()

Constructs a CoseKey instance.

protected CoseKey()

Fields

TagAlgorithm

The CBOR tag (key of key/value pair) for the COSE key algorithm.

protected const int TagAlgorithm = 3

Field Value

int

TagKeyType

The CBOR tag (key of key/value pair) for the COSE key type.

protected const int TagKeyType = 1

Field Value

int

Properties

Algorithm

The key's algorithm.

public CoseAlgorithmIdentifier Algorithm { get; set; }

Property Value

CoseAlgorithmIdentifier

Type

The key's type (or family). E.g. "EC2" for elliptic curve with an X,Y point.

public CoseKeyType Type { get; set; }

Property Value

CoseKeyType

Methods

Create(ReadOnlyMemory<byte>, out int)

Creates the correct COSE key representation based on the CBOR data provided.

public static CoseKey Create(ReadOnlyMemory<byte> coseEncodedKey, out int bytesRead)

Parameters

coseEncodedKey ReadOnlyMemory<byte>

A valid COSE key representation.

bytesRead int

The method will return the number of bytes read in this argument.

Returns

CoseKey

A COSE key instance corresponding to the type described by the CBOR data.

Remarks

This is the strict entry point. Use it when you require a key this SDK can fully model and want an exception otherwise — for example when validating a key at a trust boundary before relying on it.

If the encoding came from an authenticator rather than from your own code, and an algorithm this SDK does not model should not be fatal, use CreateOrUnsupported(ReadOnlyMemory<byte>) instead. That returns a CoseUnsupportedPublicKey preserving the original encoding rather than throwing. This applies both when decoding a live response and when re-reading a key your application persisted earlier.

Exceptions

Ctap2DataException

The CBOR reader is not in the correct position.

--- or ---

The CoseAlgorithmIdentifier could not be determined from the data provided.

NotSupportedException

The CoseAlgorithmIdentifier is not supported by this object representation.

See Also

CreateOrUnsupported(ReadOnlyMemory<byte>)

Creates the COSE key representation for coseEncodedKey, tolerating algorithms this SDK does not implement in its typed decoder.

public static CoseKey CreateOrUnsupported(ReadOnlyMemory<byte> coseEncodedKey)

Parameters

coseEncodedKey ReadOnlyMemory<byte>

A valid COSE key representation.

Returns

CoseKey

A COSE key instance corresponding to the type described by the CBOR data, or a CoseUnsupportedPublicKey if this SDK does not implement the algorithm.

Remarks

This never returns null. When the algorithm is one this SDK models, the behavior is identical to Create(ReadOnlyMemory<byte>, out int). When the algorithm is not implemented by the typed decoder, this returns a CoseUnsupportedPublicKey carrying the original encoding plus the reported key type and algorithm, instead of throwing System.NotSupportedException.

This still throws when the encoding is malformed, when the key type or algorithm is missing, or when a modeled algorithm is paired with the wrong key type. Those indicate corrupt data rather than a future algorithm, so they are not tolerated. Malformed CBOR fails here exactly as it does in Create(ReadOnlyMemory<byte>, out int), with the same exception.

One case differs from Create(ReadOnlyMemory<byte>, out int) by design. For an algorithm this SDK does not model, Create(ReadOnlyMemory<byte>, out int) never inspects the key type, so it reports the unrecognized algorithm and throws System.NotSupportedException whether or not a key type is present. This method must read the key type in order to build the result, so a missing one surfaces as Ctap2DataException instead. Both reject the input; only the reported reason differs.

Use this in preference to Create(ReadOnlyMemory<byte>, out int) whenever the encoding came from an authenticator rather than from your own code. Two common cases: decoding a response field where an unrecognized key must not abort decoding of the surrounding data, and re-reading a key your application persisted earlier, which may have been produced by an extension whose algorithm this SDK does not model.

To decode the raw bytes of a CoseUnsupportedPublicKey, read EncodedKey.

Exceptions

Ctap2DataException

The encoding is not a CBOR map, is missing the key type or the algorithm, or pairs a modeled algorithm with the wrong key type.

CborContentException

The encoding is not well-formed CBOR, or violates the CTAP2 canonical encoding rules.

InvalidCastException

A field within the encoding is not of the expected CBOR type.

KeyNotFoundException

A modeled key type is missing a field that type requires.

ArgumentException

The algorithm is one this SDK models, but the curve or a coordinate length is not. Such a key is currently rejected rather than returned as a CoseUnsupportedPublicKey.

See Also

CreateOrUnsupported(ReadOnlyMemory<byte>, out int)

Creates the COSE key representation for coseEncodedKey, tolerating algorithms this SDK does not implement in its typed decoder, and reports how many bytes were consumed.

public static CoseKey CreateOrUnsupported(ReadOnlyMemory<byte> coseEncodedKey, out int bytesRead)

Parameters

coseEncodedKey ReadOnlyMemory<byte>

A valid COSE key representation, possibly followed by further data.

bytesRead int

The method will return the number of bytes read in this argument.

Returns

CoseKey

A COSE key instance corresponding to the type described by the CBOR data, or a CoseUnsupportedPublicKey if this SDK does not implement the algorithm in its typed decoder.

Remarks

This behaves exactly as CreateOrUnsupported(ReadOnlyMemory<byte>). Use this overload when the COSE key is embedded in a larger buffer and you need to know where it ends.

Exceptions

Ctap2DataException

The encoding is not a CBOR map, is missing the key type or the algorithm, or pairs a modeled algorithm with the wrong key type.

CborContentException

The encoding is not well-formed CBOR, or violates the CTAP2 canonical encoding rules.

InvalidCastException

A field within the encoding is not of the expected CBOR type.

KeyNotFoundException

A modeled key type is missing a field that type requires.

ArgumentException

The algorithm is one this SDK models, but the curve or a coordinate length is not. Such a key is currently rejected rather than returned as a CoseUnsupportedPublicKey.

See Also

Encode()

Return a new byte array that is the key data encoded following the FIDO2/CBOR standard.

public abstract byte[] Encode()

Returns

byte[]

The encoded key.

Exceptions

InvalidOperationException

The object contains no key data.