1 of 10

0xE001 - Get Challenge

The host uses this command to request challenge data from the device, which the host can then use to perform a specific sensitive operation / modify a specific type of device setting. Information about how the host should pass the required challenge data to the device is included in the documentation for all commands that use this security mechanism.

The sequence of events is as follows:

The host already wants to perform a secured operation that requires a challenge (for example Command 0xEEEE - Send Secured Command to Device).

The host constructs the command request for Get Challenge - Command 0xE001 in the format below.

The host sends the command request to the device.

The device generates a random number for the challenge, stores it locally, and sends a response in the format below to the host.

The device starts a 5 minute countdown timer during which the challenge is valid. If the host takes no action within 5 minutes, the timer expires, the device erases the challenge data, and the device must retrieve a fresh challenge to perform the operation it wants to perform. This binding of the command to a specific time period allows the device to detect and reject commands that have been captured/intercepted at one point in time and replayed later.

Tag

Len

Value / Description

Typ

Req

Default

Tag

Len

Value / Description

Typ

Req

Default

0xEF06 - Change Device Lock State

The host can use this command to change the device’s lock state. To get the device’s lock state or to set it using MagTek security see Device Lock State - Property 1.2.5.2.1.1. The value of the device lock state will revert to the value of Device Lock State After Reset - Property 1.2.5.2.1.2 after a reset or a power cycle. See Device Lock Feature for more information.

Change Device Lock State - Request Data for Command 0xEF06

Tag

Len

Value / Description

Typ

Req

Default

Tag

Len

Value / Description

Typ

Req

Default

0xEF11 - Get Key Info

The host uses this command to retrieve information about a key slot, including details about the key stored in that slot. It can be used for several purposes, including:

Determine if a key exists / has been loaded
Get key derivation data to derive a DUKPT key
Get transport key information to retrieve the appropriate transport key

Sequence of events:

The host constructs the command request in the format below.

The host sends the command request to the device.

The device sends a response in the format below to the host.

Tag

Len

Value / Description

Typ

Req

Default

Tag

Len

Value / Description

Typ

Req

Default

0xE001 - Get Challenge

The sequence of events is as follows:

The host already wants to perform a secured operation that requires a challenge (for example Command 0xEEEE - Send Secured Command to Device).

The host constructs the command request for Get Challenge - Command 0xE001 in the format below.

The host sends the command request to the device.

The device generates a random number for the challenge, stores it locally, and sends a response in the format below to the host.

Tag

Len

Value / Description

Typ

Req

Default

Tag

Len

Value / Description

Typ

Req

Default

0xEF11 - Get Key Info

The host uses this command to retrieve information about a key slot, including details about the key stored in that slot. It can be used for several purposes, including:

Determine if a key exists / has been loaded
Get key derivation data to derive a DUKPT key
Get transport key information to retrieve the appropriate transport key

Sequence of events:

The host constructs the command request in the format below.

The host sends the command request to the device.

The device sends a response in the format below to the host.

Tag

Len

Value / Description

Typ

Req

Default

Tag

Len

Value / Description

Typ

Req

Default

Passcode — The value of the passcode depends on the value of the passcode format parameter.

If the passcode format is set to Clear (0x00), then the value of the passcode is the passcode in the clear and can have a length of 4–63 bytes.
If the passcode format is set to Fixed SHA-256 (0x01), then the value of the passcode is the 32-byte SHA-256 hash value of the passcode
If the passcode format is set to Variable SHA-256 (0x02), then the value of the passcode is the 32-byte SHA-256 hash value of: an 8-byte random challenge token followed by the 4–63 byte passcode. The challenge token must have been retrieved from the device within the last 5 minutes using Command 0xE001 - Get Challenge

0xEF01 - Load Key Using TR-31

The host uses this command to load a key into one of several available slots in the device’s secure memory.

Device Key ID / Slot

Label

Description

Load TK

1000

TMPTK

To inject a specific key in the above table, the corresponding Load TK shall be injected previously.

As shown in the table, MTK injection requires that a TMPTK has been created. See Establish Ephemeral KBPK - Command 0xF017.

After MTK has been injected successfully, the sequence of injecting other keys is as follows:

The host uses Command 0xE001 - Get Challenge to establish a secure session with the device.

The host constructs a TR-31 (X9.143) key block for the key it is going to load. (Note that the Load Key must be injected previously.)

The host constructs the command request for Command 0xEF01 - Load Key Using TR-31 in the format below.

Tag

Len

Value / Description

Typ

Req

Default

Tag

Len

Value / Description

Typ

Req

Default

Example (Hex)

AA 00 81 04 01 1A EF 01 84 82 01 36 EF 01 84 82 01 30 44 30 33 30 34 42 31 54 58 30 30 
4E 30 36 30 30 49 4B 31 38 46 46 46 46 39 38 37 36 35 34 33 32 31 30 33 30 30 30 30 30 
32 31 35 38 4D 47 54 4B 31 30 30 31 54 31 31 30 34 32 30 30 37 31 32 30 34 31 30 38 31 
32 31 30 34 30 30 33 46 33 31 30 37 42 35 30 41 46 44 32 33 32 31 30 43 39 33 36 31 39 
44 44 41 41 32 31 33 36 43 37 33 33 31 30 32 30 32 30 31 32 30 34 54 31 37 31 36 33 30 
5A 4B 50 30 45 30 31 39 33 36 46 41 33 32 45 4B 43 30 41 30 30 34 35 30 30 54 53 31 34 
32 30 32 30 30 39 30 32 54 31 35 35 38 30 32 5A 50 42 30 34 35 37 32 31 37 46 33 34 37 
31 34 43 32 42 38 38 46 33 39 35 35 32 32 32 46 46 35 39 41 41 30 35 37 44 39 39 41 46 
38 32 41 37 35 37 32 46 39 33 38 46 38 33 38 42 43 36 35 45 45 35 34 46 39 34 37 46 35 
39 41 30 36 43 44 34 35 35 31 39 32 32 37 41 32 35 35 43 37 44 35 44 37 43 38 36 37 34 
35 30 33 46 41 43 36 46 41 37 31 33 32 43 38 46 41 39 39 36 42 34 45 42 36 41 41 31 31 
34 46 45

0xEEEE - Send Secured Command to Device

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:

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.

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.

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.

The host sends the resulting composite command request to the device.

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.

If the device determines the command request is authentic, it will start executing the secure command defined by the Message Payload.

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):

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

0xEF02 - Generate CSR Keys (WLAN Only)

The host uses this command to generate a key pair to be used for a certificate signing request (CSR). The key pair generated will be 256 bit elliptic-curve (EC) keys. The key pair generated will be saved to non-volatile memory in the device and will overwrite any existing CSR key pair. The key pair will persist in non-volatile memory associated with a CSR until it is either overwritten or until a leaf certificate is loaded into the device with Start Send File to Device (Secured) - Command 0xD811 that contains a public key that matches the key pair at which point the key pair will be associated with that certificate instead of a CSR.

The sequence of events is as follows:

Host sends command request

The host constructs the command request in the format below and sends it to the device.

The device sends a response in the format below to the host to indicate that key pair generation has been started.

Once the device finishes generating the key pair, it will send Device Information Update - Notification 0x1001 with the category set to key management and the reason set to CSR keys generated to indicate that the key pair generation process has completed.

The device typically takes around a second or two to generate a 256 bit EC key pair. If this command is extended in the future to support 2048 bit RSA keys, then it will take an average of 30 seconds and sometimes much longer to generate the RSA keys. That is why a notification is used to indicate that the key pair has been generated instead of a command response that indicates that it is complete.

The host will typically send Generate CSR (WLAN Only) - Command 0xEF03 as the next step. See that command for more detail and more potential steps.

Tag

Len

Value / Description

Typ

Req

Default

Tag

Len

Value / Description

Typ

Req

Default

Example (Hex):

0xEF09 - Encrypt User Data

The host uses this command to request that the device encrypt a block of user data embedded in the command string. The SRED ID 2 Key will be used for encryption. The TLVs of KSN and Encryption Type will be provided at the end of the string for decryption.

Host request and device processing

The sequence of events is as follows:

The host composes a command request in the format below and sends it to the device.
The device will fetch the Real-Time Clock Date/Timestamp, retrieve the device's Serial Number, extract the data within 0xA3 TLV in the command string. And then concatenate all the collected TLVs as follows: + + <User Data TLV(s)>. The format of the encrypted data string is shown in the Response Data below.
If the command is invalid or encryption fails, then a response of failure will be sent to the host.

Tag

Len

Value / Description

Typ

Req

Default

Tag

Len

Value / Description

Typ

Req

Default

Tag

Len

Value / Description

Typ

Req

Default

0xEnnn - Security

Security

This section of the DynaFamily Programmer's Manual lists available security commands to utilize various functions in the device.

Applies to: All Dyna Family products

Information in this group

Section

Information

The host uses this command to request challenge data from the device, which the host can then use to perform a specific sensitive operation / modify a specific type of device setting.

Need Help?

For additional support, please contact MagTek Support:

Technical Support:

📧 Email: support@magtek.com
📞 Phone: 1-562-546-6800 (US)
🕐 Hours: Monday-Friday, 5:30 AM - 5:00 PM PST

Online Resources:

🌐 Support Portal: developer.magtek.com

Documentation Feedback:

Help us improve this documentation!

0xEF03 - Generate CSR (WLAN Only)

The host uses this command to generate a certificate signing request (CSR) in PEM format. The CSR generated will be saved to volatile memory in the device and will overwrite any existing CSR. The CSR will persist in volatile memory until it is overwritten, fetched with Start Get File from Device - Command 0xD821 or the device is power cycled or reset.

The sequence of events is as follows:

Generate CSR — Step

The host will use Generate CSR keys (WLAN Only) - Command 0xEF02 if it wants generate a CSR using a new CSR key pair.

The host constructs the command request in the format below and sends it to the device.

The device sends a response in the format below to the host to indicate that CSR generation has completed.

The host fetches the CSR with Start Get File from Device - Command 0xD821.

The CSR is used to create a certificate.

The host loads the certificate into the device with Start Send File to Device (Secured) - Command 0xD811.

Tag

Len

Value / Description

Typ

Req

Default

Tag

Len

Value / Description

Typ

Req

Default

Subject

Including this optional parameter will override the default subject. This parameter should contain a null terminated string. This string should contain a list of attributes separated bycommas. If an attribute’s value contains a comma, the comma should be replaced with “\,” Each attribute value should be prefixed with its attribute name followed by “=”. The following is a list of valid attribute names.

"CN" "commonName" "C" "countryName” "O" "organizationName" “L” “locality” "R" “OU” "organizationalUnitName" “ST” "stateOrProvinceName" "emailAddress" "serialNumber" “postalAddress” "postalCode" “dnQualifier” "title" “surname” "SN" “givenName” "GN" “initials” "pseudonym" "generationQualifier" “domainComponent” "DC" “O=MagTek Inc,CN= test1.com” is an example with two attributes.

Subject Alternative Names

Including this optional parameter will override the default subject alternative names. This parameter should contain a null terminated string. Only DNS names and IP addresses are supported and only a maximum of two each. DNS names must be prefixed with “DNS=” and IP addresses must be prefixed with “IPA=”. All Subject Alternative Names

Must be separated with a comma and not spaces. Subject Alternative Names may not be ordered in the CSR the same as they are ordered here.

"DNS=test1.com,DNS=test2.,IPA=1.10.16.255,IPA=2.10.16.25

4" is an example.

0xE001 - Get Challenge

0xEF06 - Change Device Lock State

Change Device Lock State - Request Data for Command 0xEF06

0xEF11 - Get Key Info

0xE001 - Get Challenge

Request Data for Get Challenge - Command 0xE001

Response Data for Get Challenge - Command 0xE001

Request Example - Command 0xE001

Response Example - Command 0xE001

0xEF11 - Get Key Info

Construct request

Send request

Receive response

Request Data for Command 0xEF11 - Get Key Info

Response Data for Command 0xEF11 - Get Key Info

Request Example - Command 0xEF11

Response Example - Command 0xEF11

0xEF06 - Change Device Lock State

Change Device Lock State - Request Data for Command 0xEF06

Response Data for Change Device Lock State - Command 0xEF06

Request Example - Command 0xEF06

Response Example - Command 0xEF06

0xEF07 - Change Device Lock Passcode

Change Device Lock Passcode - Request Data for Command 0xEF07

Response Data for Change Device Lock Passcode - Command 0xEF07

Request example - Command 0xEF07

Response example - Command 0xEF07

0xEF01 - Load Key Using TR-31

Device Key ID / Slot

Establish a secure session (Get Challenge)

Construct TR-31 key block

Construct command request

Load Key Using TR-31 - Request Data for Command 0xEF01

Load Key Using TR-31 - Response Data for Command 0xEF01

Request Example - Command 0xEF01

Response Example - Command 0xEF01

Send the command

Device response

0xEEEE - Send Secured Command to Device

Determine command and compose Message Payload

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

0xEF02 - Generate CSR Keys (WLAN Only)

Host sends command request

Device sends immediate response

Device sends notification when generation completes

Host typically requests CSR next

Generate CSR keys (WLAN Only) - Request Data for Command 0xEF02

Response Data for Generate CSR keys (WLAN Only) - Command 0xEF02

Request Example - Command 0xEF02

Response Example - Command 0xEF02

0xEF09 - Encrypt User Data

Host request and device processing

Request Data for Command 0xEF09 - Encrypt User Data

Response Data for Command 0xEF09 – Encrypt User Data

Response Data for Encrypt User Data (after decryption) - Command 0xEF09

Request Example - Command 0xEF09

Response Example - Command 0xEF09

0xEnnn - Security

Security

Information in this group

Need More Help

0xEF03 - Generate CSR (WLAN Only)

Generate CSR — Step

Construct and send request

Device response

Fetch CSR

Create certificate

Load certificate into device

Request Data for Command 0xEF03 – Generate CSR (WLAN Only)

Response Data for Command 0xEF03 – Generate CSR (WLAN Only)

Request Example - Command 0xEF03

Response Example - Command 0xEF03