The host uses this command to transmit another command securely. This “secure wrapper” mechanism provides the device a means to ensure the wrapped command originated from an authentic, authorized host. In addition, its implementation includes an operation that starts a countdown timer, which ensures the command is current and is not an unauthorized replay of a previously intercepted / stored command. This command can use multiple authentication methods, including MAC or ECDSA Signature. The method and parameters to use are specific to the command being wrapped, and are specified in the documentation for that command.
The sequence of events is as follows:
1
Determine command and compose Message Payload
The host determines what command it wants to call from Section 6 Commands, determines the command must be secured, and uses the Request Data table for that command to compose Message Payload.
2
The host uses Get Challenge - Command 0xE001 to retrieve a Challenge Token and unlock the device for receiving the desired command for a limited period of time. When the time expires, the device will no longer accept the Challenge Token and the host will have to retrieve another one.
3
The host creates an instance of Send Secured Command to Device - Command 0xEEEE in the format below and includes the Message Payload and Challenge Token inside it. In the Request Message, it fills in Command ID as the command number of the wrapped Message Payload, instead of 0xEEEE. Some parameters are command-specific; see the documentation for the command that is being wrapped to determine what values to use.
4
The host sends the resulting composite command request to the device.
5
The device validates the serial number and challenge token, then examines the parameters to determine which authentication method is being used and authenticates the command accordingly.
6
If the device determines the command request is authentic, it will start executing the secure command defined by the Message Payload.
7
The device sends a response to the host reporting success or failure. In both cases, the response uses the format that corresponds to the command invoked by the Message Payload. See the documentation for that command to determine the format of the response.
Tag
Len
Value / Description
Typ
Req
Default
Example (Hex):
EEEE = Send Secured Command to Device - Command 0xEEEE
A1
var
Security Parameters — This parameter describes how the Signature parameter in this data object is calculated, and is a Security Parameters Type TLV data object. To determine which values to use in that TLV data object, see the documentation for the command being wrapped.
T
R
82
04
Serial Number
B
R
83
08
Challenge Token — The token the device returned when the host called Get Challenge - Command 0xE001.
B
R
84
var
Message Payload
B
R
9E
var
MAC or Signature
B
R
End of any wrappers, at minimum including Request Message
Beginning of any wrappers, at minimum including Request Message
Retrieve Challenge Token
Build the 0xEEEE request
Send the composite command
Device validates and authenticates
Device executes secure command
Device responds
Request Data for Send Secured Command to Device - Command 0xEEEE
Request Example Using MAC
Request Example Using ECDSA
This example wraps [**Command 0xD811 - Start Send File to Device (Secured)
AA 00 81 04 01 04 D8 11 84 81 8F EE EE A1 19 81 05 03 03 06 02 08 84 00 85 00 A8 0A 81 02 11 02 82 00 86 00 88 00 A9 00 82 04 FF FF FF F0 83 08 C9 65 45 F2 97 69 85 B1 84 4E D8 11 81 04 00 00 03 00 A2 2B 81 04 00 00 02 99 82 01 04 83 20 87 A4 B3 54 61 C5 CB D3 1D DC BA 9D 65 25 5A D4 6A 22 FA 51 5E FD 65 87 AF AC A8 8C 4F AF 80 9B A3 14 38 31 30 38 33 30 33 30 33 30 33 30 33 33 33 30 33 30 87 01 01 9E 10 7D E4 27 C8 A0 70 72 08 19 0A 1E 0A 3F 48 BB F1
This example wraps [**Command 0xF015 - Read Log & Clear Tamper (MAGTEK INTERNAL ONLY)**](#_bookmark52):
AA 00 // Marker
81 04 01 0F F0 15 // Message Information
84 81 C8 // Request Payload
EE EE // 0xEEEE, Secure Wrapper
A1 24 // P4-A1, Security Parameters
81 04 02 01 04 05 // 02=Cmd Auth-sign, 01=ECDSA, 04=SHA-256, 05=P-521
84 00 // Data (for IV, nonce, as needed)
85 00 // Extra data item (reserved for future use)
A8 16 // Key Info
81 02 00 00 // Key Slot ID
82 07 45 43 43 53 49 47 4E // Key Label, “ECCSIGN”
86 05 45 43 44 53 41 // KSN or derive info, ECDSA
88 00 // Added Info
A9 00 // 2nd Key Info (reserved for future use)
82 04 B5 03 3D A0 // P4-P2, Device Serial Number
83 08 5B 6B 45 4B 00 5B CE 31 // P4-P3, Challenge Token
84 02 F0 15 // P4-P4, Payload Command 0xF015
9E 81 89 // P4-P30, Signature for Secure Wrapper
30 81 86 02 41 // Sig->R
52 5B 04 9A C7 CC 56 DE 5A EA 89 62 47 BB B8 0D 93 80 CE C8 AD 6E 16 F7 6E DA 08 42 0B 9C 69 77 61 B0 99 FC 05 7D AE AF 75 79 9C 7B B3 81 72 5C 4E 5B 92 DC F3 B6 85 5E B3 A2 71 0D 1D 93 B5 0D 0C
02 41 // Sig->S
46 47 0A EF 6F D5 97 ED 4F 41 E8 3C FD 20 A1 CE 7D E5 CA D3 E8 22 3B ED BC 2A 8A A0 BF 73 72 81 35 4F CB 52 B6 A9 07 6F 36 7F 5D 35 D5 29 3D 5D 78 17 0E B2 D6 AA A5 0D B3 4D B9 04 2C 03 6A AC A5