AnyNet Secure Device Integration Guide - Zendesk Secure Device Integration Guide ... transfer the...

AnyNet Secure Device Integration Guide

Document Reference: 8424

July 2017

Version: 2

+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000

Eseye, AnyNet, AnyNet Secure and Eseye Logos are registered trademarks of Eseye Ltd © Eseye 2017 Limited.

All Rights Reserved. [email protected] | eseye.com

Version

Number

Date Author Changes

1 Nov 2016 Sam Smith

2 Jul 2017 Sam Smith Branding updated

+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000



Contents 1 Introduction ......................................................................................................................................... 3

1.1 Preparation ................................................................................................................................. 3

1.2 How it works ................................................................................................................................ 3

1.3 Files Format ................................................................................................................................. 3

1.3.1 length: ...................................................................................................................................... 3

1.3.2 checksum: .............................................................................................................................. 3

1.3.3 package: ................................................................................................................................ 3

1.4 Available files and sizes ............................................................................................................ 4

2 The AT+CRSM command .................................................................................................................. 4

2.1 Request Command Parameters............................................................................................. 4

2.1.1 Command .............................................................................................................................. 4

2.1.2 File Id ........................................................................................................................................ 5

2.1.3 P1, P2 ........................................................................................................................................ 5

2.1.4 P3 .............................................................................................................................................. 5

2.1.5 Data ......................................................................................................................................... 5

2.1.6 Path ID ..................................................................................................................................... 5

2.2 Response Command Parameters .......................................................................................... 5

2.2.1 SW1, SW2 ................................................................................................................................. 5

2.2.2 Response ................................................................................................................................. 5

2.2.3 Err .............................................................................................................................................. 6

3 Basic Data read process ................................................................................................................... 7

3.1 Read block function ................................................................................................................. 7

3.2 Read file header ........................................................................................................................ 8

3.3 Read file in chunks .................................................................................................................... 9

3.4 File verification ......................................................................................................................... 10

3.5 Read the remaining files ........................................................................................................ 10

3.6 File format conversion ............................................................................................................ 11

4 Appendix A - Enabling SIM Toolkit ................................................................................................. 11

5 Appendix B - CRC32 Example ........................................................................................................ 13

+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000



1 Introduction When your IoT device uses the AnyNet Secure SIM it provides access to Eseye’s high

availability network of networks globally as well as the ability to securely deliver encryption

certificates and connection details for your cloud service.

1.1 Preparation The modem must support SIM Toolkit and its operation must be enabled. Examples for

enabling SIM toolkit on selected modems are detailed in Appendix A - Enabling SIM Toolkit.

The modem should support Restricted SIM access using the AT+CRSM command defined in

3GPP TS 27.007. This is defined as optional however it is anticipated that most modems will

provide support for this interface.

You must already have knowledge of AT command and cellular modem usage for data

communications.

1.2 How it works During the device activation process through your cloud service provider the Eseye AnyNet

Secure SIM will be activated. The cloud service will create the security keys and service URLs

to enable the secure data connection from your device to the cloud service platform.

When you switch on the device’s modem with the AnyNet Secure SIM installed and register

the modem with one of Eseye’s network of service providers the AnyNet Secure service

platform will securely transfer the security keys and connection data to the SIM.

1.3 Files Format As the files arrive at the SIM you can read them using the AT+CRSM

The files all follow the same basic format

<length><checksum><package>

where

1.3.1 length: 2-byte unsigned 16-bit integer stored most significant byte first.

This represents the byte length of the package.

1.3.2 checksum: 4-byte unsigned 32-bit integer stored most significant byte first.

This represents the CRC-32 checksum of the package.

1.3.3 package: Binary Data. Some post processing of the data field may be required in the case of

encryption keys and certificates. For clarity each file location will be described later with

details of any post processing requirements.

+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000



1.4 Available files and sizes The following files may be delivered to your AnyNet Secure SIM. Sizing is provided to indicate

the maximum amount of data available. The header of the file will describe the length of

the actual data.

File Name File ID

(decimal)

File ID

(hexadecimal)

File Max Size

(bytes)

Thing Name 28640 6FE0 256

Root CA 28641 6FE1 2048

Public signed

certificate

28642 6FE2 2048

Private key 28643 6FE3 2048

Mqtt Endpoint 28644 6FE4 256

2 The AT+CRSM command The main tool for reading the files from the SIM is the AT+CRSM command. See below for a

generic description of the command syntax.

For precise formats and response details consult documentation from your modem provider.

Note not all values for all fields are detailed. Only those utilized and required for the

operations performed for file extraction are defined. A more complete definition may be

found in 3GPP TS 27.007.

Command Possible response(s) +CRSM=<command>[,<fileid>[,<P1

>,<P2>,<P3>[,<data>[,<pathid>]

]]]

+CRSM: <sw1>,<sw2>[,<response>]

+CME ERROR: <err>

+CRSM=?

The use of the +CRSM command instead of the Generic SIM Access +CSIM command

provides easier access to the SIM file system as the modem takes care of the SIM interface

locking and file selection routines.

2.1 Request Command Parameters

2.1.1 Command To extract the data from the SIM the only value used in this field is

176 READ BINARY

+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000



2.1.2 File Id This is the identifier of a file on the SIM, AnyNet Secure delivers 5 files. The file contents and

their ID are:

File Content fileid THING_NAME 28640

ROOT_CA 28641

PUBLIC_CERT 28642

PRIVATE_KEY 28643

MQTT_ENDPOINT 28644

2.1.3 P1, P2 Parameters used for the READ_BINARY command

<P1> and <P2> define the offset from which to start the file read. The +CRSM in general

cannot return more than 255 bytes in a single read. These fields allow us to read the file in

chunks. <P1> is the value contained in the top 8 bits of a 16 bit file offset value, <P2>

contains the value of the bottom 8 bits of the 16 bit file offset value. An example of checked

reading is proved later in this document.

2.1.4 P3 <P3> is the length of the data to be read. The read should be limited to 255 bytes per block.

2.1.5 Data This field is not used for READ BINARY and will be left empty

2.1.6 Path ID Contains the path of an elementary file on the SIM/UICC in hexadecimal format

To read files from the AnyNet Secure SIM you should use "7FEE" for this field.

2.2 Response Command Parameters

2.2.1 SW1, SW2 Information from the SIM about the execution of the command. These may include specific

file read errors as well as success indication.

2.2.2 Response For a successful read this field will contain the requested data.

+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000



2.2.3 Err The error result code +CME ERROR may be returned when the command cannot be passed

to the SIM this field may detail the error. Please consult documentation from your modem

provider for the values that they may return with a CME ERROR response.

+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000



3 Basic Data read process For each file defined above the following process actions should be followed:

Read file header() using the block read function()

If ((header length != 0) and (header length != 0xFFFF) and

(header checksum != 0) and (header checksum != 0xFFFFFFFF))

then

{

// FILE ready to read

Read file data in chunks() // using calls to block

read function()

Verify checksum ()

File Format Conversion () // convert DER to PEM as

required

}

else

{

// FILE not found – random back-off and try again

}

3.1 Read block function It is useful to implement a single function with which you can request a block of file data from

the SIM.

A block read is achieved with a +CRSM command.

Three arguments should be passed into the block read function:

byte pointer: output_data

Integer value: file_id

Integer value: file_offset

Integer value: read_length

This would result in the command in format of

AT+CRSM=176,<file_id>,(<offset>/256),(<offset> MOD

256),<length>,,”7FEE”

+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000



As an example; to read the header of the THING_NAME file into a buffer called returned

_data the read block function would be called with

output_data = returned_data

file_id = 28640

file_offset = 0

read_length = 6

Which results in the command:

AT+CRSM=176,28640,0,0,6,,”7FEE”

A short while after the command is issued the modem should return a response in the

following format:

+CRSM: 144,0,”<data>”

The data is returned in an ASCII HEX string so you need to return the data to its binary form.

Eg. If the data in the file was the string “MAP” then <data> would be returned as “4D4150”

The first character in the data is the upper nibble of the first data byte, the second being the

lower nibble of the first data byte.

Remember what you have read are ASCII characters. You need to convert each nibble into

its hexadecimal data byte value.

Something like:

index = 0;

while (index < read_length)

{

sscanf( &data[index], “%02X”, *output_data++);

index = index + 2

}

This processes the returned string, reading two ASCII characters and converts them to byte

value storing the resultant byte value at the location defined by output_data .

3.2 Read file header Using the read block function read 6 bytes from offset 0 in the file

As an example to read the header of the THING_NAME

+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000



Call the read block function with

output_data = returned_data

file_id = 28640

file_offset = 0

read_length = 6

This reads fileid 28640 (THING_NAME) from the start of the file (offset 0) and returns 6

(which is the size of the header) bytes in returned_data . If the suggested read block

functionality is used then the data returned is Binary not the ASCII returned by the modem.

Once the response data is received we can extract the two header fields

Remember the first 2 bytes of data are the length and the next 4 are the checksum

Both values are big-endian so consider that you may need to reverse the byte order

length = *(unsigned short *)&returned_data[0] // read 16

bit length

checksum = *(unsigned int *)&returned_data[2] // read 32

bit checksum

If length is not equal to 0 and 0xFFFF and the checksum is not equal to 0 and 0xFFFFFFFF the

rest of the file can be read.

3.3 Read file in chunks We have already read the first 6 bytes of the file, the header, now read the data content

starting at offset 6. Read up to 255 bytes at a time, you might want to check your modem

command manual as shorter length limits per read may apply.

Again in the example we will read the ROOT_CA file of length 1239 bytes

Something like:

file_data = malloc(1240)

offset=6;

while (length)

{

if (length > 255) bytes_to_read = 255;

else bytes_to_read = length;

// See 3.1 Read block function

+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000



read_block_function(&file_data[offset – 6], 28640,

offset, bytes_to_read)

// Wait for the read bock response and process the data

nibbles

length = length – bytes_to_read

offset = offset + bytes_to_read

// repeat if more data to read

}

For a file with a data record 927 bytes this would result in the following sequence of calls

read_lock_function(&file_data[0], 28641, 6, 255)





which in turn will result in the following At commands being issued

AT+CRSM=176,28641,0,6,255,,”7FEE”

AT+CRSM=176,28641,1,5,255,,”7FEE”

AT+CRSM=176,28641,2,4,255,,”7FEE”

AT+CRSM=176,28641,3,3,255,,”7FEE”

AT+CRSM=176,28641,4,2,219,,”7FEE”

3.4 File verification Once all the data bytes have been read from the SIM it needs to be verified. To do this

perform a CRC32 calculation for the data and compare it to the checksum in the header.

Assuming the sum matches the file read is complete. Otherwise randomly backoff to wait a

little longer for the file to update and try again.

See Appendix B - CRC32 Example

3.5 Read the remaining files There are 5 files to read

+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000



THING_NAME 28640

ROOT_CA 28641

PUBLIC_CERT 28642

PRIVATE_KEY 28643

MQTT_ENDPOINT 28644

Repeat the basic read data process for each file.

3.6 File format conversion The ROOT_CA, PUBLIC_CERT and PRIVATE_KEY are transferred in Binary DER-encoded /

ASN.1 BER-encoded format

You may need to convert these into PEM or base64 format for use with you SSL/TLS client. This

can be done by base64 encoding the data and adding header and footer lines

e.g.

certificate = sprint( “-----BEGIN CERTIFICATE-----\n”)

offset = strlen( certificate);

cert_offset = 0;

while (cert_offset < cert_length )

{

Length = (cert_length – cert_offset);

If (length > 64) length = 64;

base64encode(encoded, certificate[cert_offset], length)

cert_offset += length;

Memcpy( certificate[offset], encoded, length)

Offset += length;

certificate[offset++] = ‘\n’;

}

Memcpy( certificate[offset], “-----END CERTIFICATE-----\n” )

4 Appendix A - Enabling SIM Toolkit For most current modules SIM toolkit is enabled. However if you want to make sure the

following commands may be used to enable SIM toolkit operation

+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000



Vendor Command

Telit AT#STIA=1

Quectel AT+QSTK=1

Sierra Wireless AT+STSF=1

Huawei AT^STSF=1

+ 44 1483 802501 | +1 512-813-0599 | +27 87 551 8200 | +33 9 87 67 53 36 | +61 8 9551 5200 | +61 400 435 1000



5 Appendix B - CRC32 Example A standard CRC32 calculator is used

An example implementation can be found at

https://opensource.apple.com/source/xnu/xnu-1456.1.26/bsd/libkern/crc32.c

https://opensource.apple.com/source/xnu/xnu-1456.1.26/bsd/libkern/crc32.c

AnyNet Secure Device Integration Guide - Zendesk Secure Device Integration Guide ... transfer the...

Documents

Transcript of AnyNet Secure Device Integration Guide - Zendesk Secure Device Integration Guide ... transfer the...