GetAes128SessionKeys Method
GetAes128SessionKeys(String, ReadOnlyMemory<Byte>, ReadOnlyMemory<Byte>, ReadOnlyMemory<Byte>)
Calculate session keys from an AES-128 credential. These session keys are used to establish a secure session with a YubiHSM 2 device.
public SessionKeys GetAes128SessionKeys(string credentialLabel, ReadOnlyMemory<byte> credentialPassword, ReadOnlyMemory<byte> hostChallenge, ReadOnlyMemory<byte> hsmDeviceChallenge)Parameters
| Type | Name | Description |
|---|---|---|
| System.String | credentialLabel | The label of the credential for calculating the session keys. The string must meet the same requirements as Label. |
| System.ReadOnlyMemory<System.Byte> | credentialPassword | The password of the credential for calculating the session keys. It must meet the same requirements as CredentialPassword. |
| System.ReadOnlyMemory<System.Byte> | hostChallenge | The 8 byte challenge generated by the host. |
| System.ReadOnlyMemory<System.Byte> | hsmDeviceChallenge | The 8 byte challenge generated by the YubiHSM 2 device. |
Returns
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).
Exceptions
| Type | Condition |
|---|---|
| System.InvalidOperationException | The credential could not be found. |
| System.Security.SecurityException | The credential password was incorrect, or touch was required but not supplied. |
| System.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.
If the credential requires touch (see TouchRequired), then the user must also touch the YubiKey as part of the authentication procedure. A System.TimeoutException will be thrown if touch is not supplied in time.
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.