Chapter 7 |
|
Wireless USB Framework |
Wireless Universal Serial Bus Specification, Revision 1.0 |
7.3.2 Security-related Requests
This section describes the Requests defined for the USB Security Framework.
Table 7-20: Security Requests
Request |
bmRequestType |
bRequest |
wValue |
wIndex |
wLength |
Data |
|
|
|
|
|
|
|
GetKey |
10000000B |
GET_DESCRIPTOR |
Descriptor |
Zero |
Descriptor |
Key |
|
|
|
Type and |
|
Length |
Descriptor |
|
|
|
Key Index |
|
|
|
|
|
|
|
|
|
|
SetKey |
00000000B |
SET_DESCRIPTOR |
Descriptor |
Zero |
Descriptor |
Key |
|
|
|
Type and |
|
Length |
Descriptor |
|
|
|
Key Index |
|
|
|
|
|
|
|
|
|
|
Handshake1 |
00000000B |
SET_HANDSHAKE |
One |
Zero |
Length of |
Handshake |
|
|
|
|
|
Handshake |
1 Data |
|
|
|
|
|
1 Data |
|
Handshake2 |
10000000B |
GET_HANDSHAKE |
Two |
Zero |
Length of |
Handshake |
|
|
|
|
|
Handshake |
2 Data |
|
|
|
|
|
2 Data |
|
|
|
|
|
|
|
|
Handshake3 |
00000000B |
SET_HANDSHAKE |
Three |
Zero |
Length of |
Handshake |
|
|
|
|
|
Hanshake3 |
3 Data |
|
|
|
|
|
Data |
|
|
|
|
|
|
|
|
GetSecurityDescriptor |
10000000B |
GET_DESCRIPTOR |
Descriptor |
Zero |
Descriptor |
Descriptor |
|
|
|
Type |
|
Length |
Data |
|
|
|
Encryption |
|
|
|
SetEncryption |
00000000B |
SET_ENCRYPTION |
Zero |
Zero |
None |
|
|
|
|
Value |
|
|
|
|
|
|
|
|
|
|
GetEncryption |
10000000B |
GET_ENCRYPTION |
Zero |
Zero |
One |
Encryption |
|
|
|
|
|
|
Value |
|
|
|
|
|
|
|
SetConnectionContext |
00000000B |
SET_CONNECTION |
Zero |
Zero |
Fourty- |
Connection |
|
|
|
|
|
eight |
Context |
|
|
|
|
|
|
|
SetSecurityData |
00000000B |
SET_SECURITY_DATA |
Data |
Zero |
Data |
Security |
|
|
|
Number |
|
Length |
Data |
|
|
|
|
|
|
|
GetSecurityData |
10000000B |
GET_SECURITY_DATA |
Data |
Zero |
Data |
Security |
|
|
|
Number |
|
Length |
Data |
|
|
|
|
|
|
|
7.3.2.1Get Security Descriptor
The host uses this command to retrieve the Security Descriptor and its associated sub-descriptors from the device.
bmRequestType |
bRequest |
wValue |
wIndex |
wLength |
Data |
|
|
|
|
|
|
10000000B |
GET_DESCRIPTOR |
Descriptor |
Zero |
Length of |
Security Descriptor |
|
|
Type and |
|
Descriptor |
|
|
|
Zero |
|
|
|
|
|
|
|
|
|
It is a Request Error if wValue or wIndex are other than as specified above. The request is valid for any device in the Connected device state.
UnAuthenticated State: This is a valid request when the device is in the UnAuthenticated state. Default State: This is a valid request when the device is in the Default state.
Address State: This is a valid request when the device is in the Addressed state. Configured State: This is a valid request when the device is in the Configured state.
153
Chapter 7 |
|
Wireless USB Framework |
Wireless Universal Serial Bus Specification, Revision 1.0 |
7.3.2.2Set Encryption
The host uses this command to set the current device encryption type.
bmRequestType |
bRequest |
wValue |
wIndex |
wLength |
Data |
|
|
|
|
|
|
00000000B |
SET_ENCRYPTION |
Encryption |
Zero |
Zero |
None |
|
|
Value |
|
|
|
|
|
|
|
|
|
The host uses this command to inform the device of the type of encryption that will be used. The host determines the types of encryption the device supports by enumerating the security descriptor and its encryption type descriptors. The host also uses this request to enable CCM encryption on the device before beginning the 4-way handshake.
Encryption Value comes from one of the Encryption Type descriptors contained in the Security Descriptor. A value of Zero always represents UNSECURE or no encryption. The request is valid for any device in the Connected device state.
It is a Request Error if Encryption Value does not represent a valid encryption type. It is a Request Error to attempt to set WIRED as the current encryption type.
It is a Request Error if wValue or wIndex are other than as specified above.
UnAuthenticated State: This is a valid request when the device is in the UnAuthenticated state. Default State: This is a valid request when the device is in the Default state.
Address State: This is a valid request when the device is in the Address state. Configured State: This is a valid request when the device is in the Configured state.
7.3.2.3Get Encryption
The host uses this command to get the current device encryption type.
bmRequestType |
bRequest |
wValue |
wIndex |
wLength |
Data |
|
|
|
|
|
|
10000000B |
GET_ENCRYPTION |
Zero |
Zero |
One |
Encryption Value |
|
|
|
|
|
|
Encryption Value comes from one of the Encryption Type descriptors contained in the Security Descriptor. A value of Zero always represents UNSECURE or no encryption.
A wired/wireless device always returns WIRED if it connected with a cable.
It is a Request Error if Encryption Value does not represent a valid encryption type. It is a Request Error if wValue or wIndex are other than as specified above.
UnAuthenticated State: This is a valid request when the device is in the UnAuthenticated state. Default State: This is a valid request when the device is in the Default state.
Address State: This is a valid request when the device is in the Address state. Configured State: This is a valid request when the device is in the Configured state.
154
Chapter 7 |
|
Wireless USB Framework |
Wireless Universal Serial Bus Specification, Revision 1.0 |
7.3.2.4Key Management
This section describes the requests that are related to key management.
The Security Framework uses Key Indices in both descriptors and requests. These values are used to specify individual keys. The Key Index has the following layout:
Table 7-21: Key Index definition
Bit |
|
Description |
|
|
|
0-3 |
Index: Allows selection of one of several of the same type |
|
|
of key. |
|
4-5 |
Type: Specifies the type of key: |
|
|
0 |
= Reserved |
|
1 |
= Association Key |
|
2 |
= GTK |
|
3 |
= Reserved for future use |
|
|
|
6 |
Originator: specifies original source of the key: |
|
|
0 |
= Host |
|
1 |
= Device |
7 |
Reserved for future use |
|
Devices may use the index field to select between multiple device-originated authentication keys. Host-originated public keys use an index of zero (0).
7.3.2.4.1Set Key
The host uses this command to distribute GTKs and host association keys. When Set Key is being used to give an initial GTK to a device, the device must initialize the replay counter associated with this GTK to the SFC value used in the secure encapsulation of the MMC where the Setup command bytes for this command are located. To support this, the host is required to deliver the currently active GTK to a device as its initial GTK.
bmRequestType |
bRequest |
wValue |
wIndex |
wLength |
Data |
|
|
|
|
|
|
00000000B |
SET_DESCRIPTOR |
Descriptor |
Zero |
Descriptor |
Key Descriptor |
|
|
Type and |
|
Length |
|
|
|
Key Index |
|
|
|
|
|
|
|
|
|
When the device receives this command, it uses the key data in the accompanying descriptor to update its copy of the key specified by Key Index. The request is valid for any device in the Connected device state. This request may not be used to distribute new PTKs. PTKs are only distributed using the 4-way Handshake.
It is a Request Error if wIndex or wValue are other than as specified above. It is a Request Error if key originator=device.
It is Request Error to distribute any key other than a host public key in UNSECURE encryption mode. UnAuthenticated State: This is a valid request when the device is in the UnAuthenticated state. Default State: This is a valid request when the device is in the Default state.
Address State: This is a valid request when the device is in the Addressed state. Configured State: This is a valid request when the device is in the Configured state.
155
Chapter 7 |
|
Wireless USB Framework |
Wireless Universal Serial Bus Specification, Revision 1.0 |
7.3.2.4.2Get Key
The host uses this request to get key descriptors from the device.
bmRequestType |
bRequest |
wValue |
wIndex |
wLength |
Data |
|
|
|
|
|
|
10000000B |
GET_DESCRIPTOR |
Descriptor |
Zero |
Descriptor |
Key Descriptor |
|
|
Type and |
|
Length |
|
|
|
Key Index |
|
|
|
|
|
|
|
|
|
When the device receives this command, it uses Key Index to reference the appropriate key. The request is valid for any device in the Connected device state.
It is a Request Error if wValue or wIndex are other than as specified above. It is a Request Error if Key Index refers to a non-existent key.
It is a Request Error if Key Index specifies any key type other than a public key UnAuthenticated State: This is a valid request when the device is in the UnAuthenticated state. Default State: This is a valid request when the device is in the Default state.
Address State: This is a valid request when the device is in the Address state. Configured State: This is a valid request when the device is in the Configured state.
7.3.2.54-Way Handshake
This series of requests are used to establish a 4-way handshake between host and device. This 4-way handshake provides a means for the host and device to perform mutual authentication using the Connection Key while simultaneously deriving the initial PTKs.
The host always assumes an Initiator role in the 4-way handshake while the device always assumes the role of responder. During the 4-way handshake, the host and device exchange 128-bit cryptographic grade random numbers. These numbers are assembled and processed as described in the Security chapter.
The device must expect the individual handshake requests in order: Handshake1, Handshake2 and Handshake3. If a device receives a Handshake1 while it is processing or waiting for a Handshake2 or Handshake3 request, it must abort the handshake in progress and start again with the newly received Handshake1 request. If the device receives an unexpected handshake request, it must report a request error to the host. The format of the Handshake data for all Handshake requests is given in Table 7-22.
Table 7-22. Format of Handshake Data for the Handshake Commands
Offset |
Field |
Size |
Value |
|
Description |
|
|
|
|
|
|
0 |
bMessageNumber |
1 |
Number |
Defines which stage this data payload is |
|
|
|
|
|
associated with. Valid values are: |
|
|
|
|
|
1 |
Handshake1 |
|
|
|
|
2 |
Handshake2 |
|
|
|
|
3 |
Handshake3 |
1 |
bStatus |
1 |
Number |
0 |
Normal, the handshake sequence |
|
|
|
|
|
proceeds |
|
|
|
|
1 |
Aborted per security policy |
|
|
|
|
2 |
Aborted, handshake in progress with |
|
|
|
|
|
same master key |
|
|
|
|
3 |
Aborted, TKID conflict |
|
|
|
|
|
|
2 |
tTKID |
3 |
Number |
The base name for the PTK to be derived |
|
156
Chapter 7 |
|
Wireless USB Framework |
Wireless Universal Serial Bus Specification, Revision 1.0 |
Table 7-22. Format of Handshake Data for the Handshake Commands (cont.)
Offset |
Field |
Size |
Value |
Description |
|
|
|
|
|
5 |
bReserved |
1 |
Constant |
Reserved for future use; Must be zero |
|
|
|
|
|
6 |
CDID |
16 |
Number |
The device’s CDID. Note, this corresponds to |
|
|
|
|
the MKID used by the MAC Layer, see |
|
|
|
|
reference [3] |
22 |
Nonce |
16 |
NONCE |
The Nonce being exchanged for the |
|
|
|
|
handshake |
38 |
MIC |
8 |
Number |
The MIC calculated over the previous fields |
|
|
|
|
of this packet payload. The value of this field |
|
|
|
|
for Handshake1 is zero. |
The host establishes the TKID to be used with PTK by declaring this value in the Handshake1 data payload. This value is maintained throughout the handshake sequence. If the host or device receives a handshake payload with a different TKID, the payload should be discarded.
The last 4-way handshake message, Handshake3, is an instruction to install the freshly derived PTK. Upon completion of the status stage of a Handshake3 request, the device should install the derived PTK, enable CCM cryptographic operations and prepare for receipt of secured traffic.
The host may begin a 4-Way Handshake sequence anytime it decides the connection requires re-authentication. The individual 4-Way Handshake requests are valid in all sub-states of the Connected device state.
The data and status stages of the individual 4-Way Handshake requests are always sent without secure packet encapsulation, i.e. they are sent in plain-text.
The host must make sure the correct security suite is enabled on the device before beginning a 4-way handshake. It does this by using SetEncryption() to enable CCM encryption.
7.3.2.5.1Handshake1
The host uses this request to begin the 4-way handshake procedure with a device.
bmRequestType |
bRequest |
wValue |
wIndex |
wLength |
Data |
|
|
|
|
|
|
00000000B |
SET_HANDSHAKE |
One |
Zero |
46 |
Handshake1 Data |
|
|
|
|
|
|
This command is used to initiate the 4-way handshake sequence. The host starts the process by sending a key name and a 16-byte cryptographic grade random number, HNonce, to the device. The format of the Handshake1 data is given in Table 7-22.
It is a Request Error if wValue or wIndex are other than as specified above.
UnAuthenticated State: This is a valid request when the device is in the UnAuthenticated state. Default State: This is a valid request when the device is in the Default state.
Address State: This is a valid request when the device is in the Address state.
Configured State: This is a valid request when the device is in the Configured state.
157
Chapter 7 |
|
Wireless USB Framework |
Wireless Universal Serial Bus Specification, Revision 1.0 |
7.3.2.5.2Handshake2
The host uses this request to retrieve the second 4-way handshake from the device.
bmRequestType |
bRequest |
wValue |
wIndex |
wLength |
Data |
|
|
|
|
|
|
10000000B |
GET_HANDSHAKE |
Two |
Zero |
46 |
Handshake2 Data |
|
|
|
|
|
|
The host uses this request to retrieve a 16-byte cryptographic grade random number from the device, DNonce, and to validate that the device has derived the correct keys. The format of Handshake 2 Data is given in Table 7-22.
It is a Request Error if wValue or wIndex are other than as specified above.
UnAuthenticated State: This is a valid request when the device is in the UnAuthenticated state. Default State: This is a valid request when the device is in the Default state.
Address State: This is a valid request when the device is in the Address state.
Configured State: This is a valid request when the device is in the Configured state.
7.3.2.5.3Handshake3
The host uses this request to instruct the device to install the derived key.
bmRequestType |
bRequest |
wValue |
wIndex |
wLength |
Data |
|
|
|
|
|
|
00000000B |
SET_HANDSHAKE |
Three |
Zero |
46 |
Handshake3 Data |
|
|
|
|
|
|
This request combines message 3 and message 4 of a 4-way handshake. The data stage of this request contains the host’s message 3. The status stage of this request serves as the device response message 4. The format of the Handshake3 data is given in Table 7-22.
It is a Request Error if wValue or wIndex are other than as specified above.
UnAuthenticated State: This is a valid request when the device is in the UnAuthenticated state. Default State: This is a valid request when the device is in the Default state.
Address State: This is a valid request when the device is in the Address state.
Configured State: This is a valid request when the device is in the Configured state.
7.3.2.5.4Set Connection Context
The host uses this command to modify a device’s Connection Context.
bmRequestType |
bRequest |
wValue |
wIndex |
wLength |
Data |
|
|
|
|
|
|
00000000B |
SET_CONNECTION |
Zero |
Zero |
48 |
Connection |
|
|
|
|
|
Context |
|
|
|
|
|
|
This command is used to modify the current device connection values for CHID, CDID, and CK. This request is only valid for devices in the Authenticated device state. A Connection Context must always be protected during delivery.
A host can also use this command to revoke a context. It does this by setting a context with zero values for CHID and CDID. Any device with a current CDID value of zero must be associated with a host before reconnections can be made.
158