Class EcdsaVerify

Namespace

Yubico.YubiKey.Cryptography

Assembly

Yubico.YubiKey.dll

This class can verify the ECDSA signature using different types of public keys.

public class EcdsaVerify

Inheritance

object

EcdsaVerify

Remarks

This class will use the default System.Security.Cryptography.ECDsa implementation to verify a signature. In order to do so, it must be able to "convert" the public key and the signature into the formats required by that class.

The ECDsa class is disposable, which is why this class is as well.

Converting the key into the appropriate format is done by the constructor. The public key you will use to verify the signature will likely be in one of these formats:

PivPublicKey
CoseKey
X509Certificate2
ECDsa
encoded point (0x04 || x-coordinate || y-coordinate)

Create an instance of this class with the key you have. Then examine the ECDsa property. You will see your key is now loaded in the format needed. For example, suppose you have an object that contains information about a PIV slot, and the PublicKey property is a Yubico.YubiKey.Piv.PivPublicKey containing the public key partner to the private key in that slot.

using var ecdsaVerifier = new EcdsaVerify(slotContents[index].PublicKey);

The ECDsa class also requires the signature to be in a specific format that is not standard. Most standards specify that an ECDSA signature is formatted following the BER encoding of the following ASN.1 definition:

Ecdsa-Sig-Value  ::=  SEQUENCE  {
  r     INTEGER,
  s     INTEGER  }

However, the ECDsa class expects the signature to be represented as the concatenation of r and s where each value is exactly the curve size. For example, the size of the NIST curve P-256 is 256 bits, which is 32 bytes. Hence, the signature r||s must be 64 bytes, both r and s must be exactly 32 bytes. If a value is shorter than 32 bytes, it is prepended with 00 bytes.

The verification methods will convert a standard signature into the format the ECDsa class needs. They can also verify signatures that are formatted as r||s.

The YubiKey returns an ECDSA signature following the standard, namely the BER encoding.

Each of the verify methods will return a boolean, indicating whether the signature verifies or not. If a signature does not verify, that is not an error. The methods will throw exceptions if they encounter bad data, such as x- or y-coordinates that do not fit the specified curve.

For example,

using var ecdsaVfy = new EcdsaVerify(authData.CredentialPublicKey);
bool isVerified = ecdsaVerify.VerifyDigest(digest, signature);

using var ecdsaVfy = new EcdsaVerify(AttestationCert);
bool isVerified = ecdsaVerify.VerifyData(dataToVerify, signature, false);

Constructors

EcdsaVerify(ReadOnlyMemory<byte>)

Create an instance of the EcdsaVerify class using the encoded point.

public EcdsaVerify(ReadOnlyMemory<byte> encodedEccPoint)

Parameters

encodedEccPoint ReadOnlyMemory<byte>

The public key to use to verify.

Remarks

This supports the uncompressed encoded point: 04||x-coordinate||y-coordinate where both coordinates are the curve size (each coordinate is 32 bytes for P-256, 48 bytes for P-384 and 66 bytes for P-521), prepended with 00 bytes if necessary.

Exceptions

ArgumentNullException

The coseKey is null.

ArgumentException

The key is not for a supported algorithm or curve, or is malformed.

EcdsaVerify(ECDsa)

Create an instance of the EcdsaVerify class using the ECDsa object that contains the public key.

public EcdsaVerify(ECDsa ecdsa)

Parameters

ecdsa ECDsa

The public key to use to verify. This constructor will copy a reference to this object.

Exceptions

ArgumentNullException

The ecdsa argument is null.

ArgumentException

The key is not for a supported algorithm or curve, or is malformed.

EcdsaVerify(X509Certificate2)

Create an instance of the EcdsaVerify class using the given certificate.

public EcdsaVerify(X509Certificate2 certificate)

Parameters

certificate X509Certificate2

The certificate containing the public key to use to verify.

Exceptions

ArgumentNullException

The certificate argument is null.

ArgumentException

The key is not for a supported algorithm or curve, or is malformed.

EcdsaVerify(ECPublicKey)

public EcdsaVerify(ECPublicKey publicKey)

Parameters

publicKey ECPublicKey

EcdsaVerify(CoseKey)

Create an instance of the EcdsaVerify class using the COSE EC public key.

public EcdsaVerify(CoseKey coseKey)

Parameters

coseKey CoseKey

The public key to use to verify.

Exceptions

ArgumentNullException

The coseKey is null.

ArgumentException

The key is not for a supported algorithm or curve, or is malformed.

Properties

ECDsa

The object built that will perform the verification operation.

public ECDsa ECDsa { get; }

Property Value

ECDsa

Remarks

This must be P-256, P-384 or P-521, and contain valid coordinates.

Methods

Dispose()

Clean up.

public void Dispose()

Dispose(bool)

Clean up

protected virtual void Dispose(bool disposing)

Parameters

disposing bool

Disposing or called from elsewhere.

VerifyData(byte[], byte[], bool)

Verify the signature using the dataToVerify. This method will digest the dataToVerify using SHA-256, SHA-384 or SHA-512, depending on the public key's curve, and then verify the signature using the digest.

public bool VerifyData(byte[] dataToVerify, byte[] signature, bool isStandardSignature = true)

Parameters

dataToVerify byte[]

The data data to verify. To verify an ECDSA signature, this method will digest the data using SHA-256, SHA-384 or SHA-512, depending on the public key's curve.

signature byte[]

The signature to verify.

isStandardSignature bool

true if the signature is formatted as the BER encoding specified by most standards, or false if the signature is formatted as the concatenation of r and s.

Returns

bool

A boolean, true if the signature verifies, false if it does not.

Remarks

If the signature is the standard BER encoding, then pass true for isStandardSignature. That argument defaults to true so if the signature is formatted in the standard way, you can call this method with that argument missing. If the signature is the concatenation of r and s, pass false for isStandardSignature.

VerifyDigestedData(byte[], byte[], bool)

Verify the signature using the digestToVerify.

public bool VerifyDigestedData(byte[] digestToVerify, byte[] signature, bool isStandardSignature = true)

Parameters

digestToVerify byte[]

The digest of the data to verify.

signature byte[]

The signature to verify.

isStandardSignature bool

true if the signature is formatted as the BER encoding (DSASignatureFormat.Rfc3279DerSequence) specified by most standards, or false if the signature is formatted as the concatenation of r and s.

Returns

bool

A boolean, true if the signature verifies, false if it does not.

Remarks

If the signature is the standard BER encoding, then pass true for isStandardSignature. That argument defaults to true so if the signature is formatted in the standard way, you can call this method with that argument missing. If the signature is the concatenation of r and s, pass false for isStandardSignature.