KeyAgree Method
KeyAgree(Byte, PivPublicKey)
Perform Phase 2 of EC Diffie-Hellman Key Agreement using the private key in the given slot, and the corresponding party's public key.
public byte[] KeyAgree(byte slotNumber, PivPublicKey correspondentPublicKey)Parameters
| Type | Name | Description |
|---|---|---|
| System.Byte | slotNumber | The slot containing the key to use. |
| PivPublicKey | correspondentPublicKey | The correspondent's public key. |
Returns
The resulting shared secret data.
Exceptions
| Type | Condition |
|---|---|
| System.ArgumentNullException | The |
| System.ArgumentException | The slot number given was not valid, or the public key was invalid (e.g. empty, wrong algorithm). |
| System.InvalidOperationException | There was no key in the slot specified or the public key did not match the private key (e.g. the public key was for ECC P256 but the private key in the given slot was ECC P384). |
| System.OperationCanceledException | Either the PIN was required and the user canceled collection or touch was required and the user did not touch within the timeout period. |
| System.Security.SecurityException | The remaining retries count indicates the PIN is blocked. |
Remarks
The YubiKey supports key agreement only with ECC keys.
This method returns the raw shared secret data, if it can perform the key agreement operation. It will not perform any derivation operations. The result will be the same size as the key. That is, for a 256-bit ECC key, the shared secret is 32 bytes, and for a 384-bit key, the shared secret is 48 bytes.
The data returned is not formatted, nor encoded, it is simply a byte array. It happens to be the x coordinate of an ECC point that is the result of an EC scalar multiplication operation.
Key Agreement might require the PIN and/or touch, depending on the PIN and touch policies specified at the time the key was generated or imported.
If a PIN is required, this method will call the necessary routines to verify the PIN. See VerifyPin() for more information on PIN verification. If the user cancels, this method will throw an exception.
If touch is required, the YubiKey itself will flash its touch signal
and wait. If the YubiKey is not touched before the touch timeout, the
YubiKey will return with an error, and this method will throw an
exception (OperationCanceledException). Note that this method
will not make another effort to perform key agreement if the YubiKey
is not touched, it will simply throw the exception.
Note that on YubiKeys prior to version 5.3, it is not possible to know programmatically what the PIN or touch policies are without actually trying to perform key agreement. Also, it is not possible to know programmatically if an authentication failure is due to PIN or touch. This means that on older YubiKeys, this method will try to perform the key agreement operation without the PIN, and if it does not work because of authentication failure, it will not know if the failure was due to PIN or touch. Hence, it will try to verify the PIN then try to perform the key agreement operation again. This all means that on older YubiKeys, it is possible a YubiKey slot was originally configured with a PIN policy of "never" and a touch policy of "always", and this method will call for the PIN anyway. This happens if the user does not touch the YubiKey before the timeout. See the User's Manual entry on keeping track of slot contents.