TryGetAes128SessionKeys Method
TryGetAes128SessionKeys(string, ReadOnlyMemory<byte>, ReadOnlyMemory<byte>, out SessionKeys?)
Calculate session keys from an AES-128 credential, using the KeyCollector to retrieve the credential password and prompt for touch when required. These session keys are used to establish a secure session with a YubiHSM 2 device.
public bool TryGetAes128SessionKeys(string credentialLabel, ReadOnlyMemory<byte> hostChallenge, ReadOnlyMemory<byte> hsmDeviceChallenge, out SessionKeys? sessionKeys)Parameters
| Type | Name | Description |
|---|---|---|
| string | credentialLabel | The label of the credential for calculating the session keys. The string must meet the same requirements as Label. |
| ReadOnlyMemory<byte> | hostChallenge | The 8 byte challenge generated by the host. |
| ReadOnlyMemory<byte> | hsmDeviceChallenge | The 8 byte challenge generated by the YubiHSM 2 device. |
| SessionKeys | sessionKeys | Session keys are used to establish an encrypted and authenticated session with a YubiHSM 2 device. The secure session is based on the Global Platform Secure Channel Protocol '03' (SCP03). |
Returns
True, when the management key has been changed successfully.
False when the KeyCollector returns false
(usually indicating user cancellation).
Exceptions
| Type | Condition |
|---|---|
| InvalidOperationException | The credential could not be found. |
| TimeoutException | The operation timed out waiting for touch. |
Remarks
Some steps must be performed prior to calling this command. First, generate an 8-byte "host challenge" using a random or pseudorandom method. Next, send the host challenge to the YubiHSM 2 device using the yh_begin_create_session_ext method of the libyubihsm library, where the YubiHSM 2 device responds with an 8-byte "HSM device challenge". Both of these challenges are then used to construct this command.
There is a limit of 8 attempts to authenticate with the credential's password before the credential is deleted. Once the credential is deleted, it cannot be recovered. Supplying the correct password before the credential is deleted will reset the retry counter to 8.
When the credential password is needed, the KeyCollector
is called with Request set to
AuthenticateYubiHsmAuthCredentialPassword.
The KeyCollector gets the credential password from the user,
stores it using SubmitValue(ReadOnlySpan<byte>),
and returns true.
Next, if the credential requires touch (see
TouchRequired), the KeyCollector
is called with Request set to
TouchRequest. Typically, you will want
to react to this request by alerting your user that they need to
physically touch the YubiKey. Additionally, the return value will be
ignored. That is, it is not possible to cancel the operation once
this TouchRequest is sent. Ideally, you should not block this
call. However, to ensure the proper function of the SDK, this request
will be issued on a separate thread from the one that originated this
call.
If the user does not touch the YubiKey in time, a System.TimeoutException will be thrown. Failing to touch the YubiKey does not change the credential's retry count.
The secure session protocol is based on Secure Channel Protocol 3 (SCP03). The session keys returned by the application are the Session Secure Channel Encryption Key (S-ENC), Secure Channel Message Authentication Code Key for Command (S-MAC), and Secure Channel Message Authentication Code Key for Response (S-RMAC). These session-specific keys are used to encrypt and authenticate commands and responses with a YubiHSM 2 device during a single session. The session keys are discarded afterwards.