anynet secure device integration guide - zendesk secure device integration guide ... transfer the...
TRANSCRIPT
AnyNet Secure Device Integration Guide
Document Reference: 8424
July 2017
Version: 2
Page 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
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
Page 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
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
Page 3
+ 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
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.
Page 4
+ 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
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
Page 5
+ 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
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.
Page 6
+ 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
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.
Page 7
+ 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
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”
Page 8
+ 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
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
Page 9
+ 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
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
Page 10
+ 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
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)
read_lock_function(&file_data[255], 28641, 261, 255)
read_lock_function(&file_data[510], 28641, 516, 255)
read_lock_function(&file_data[765], 28641, 771, 255)
read_lock_function(&file_data[1020], 28641, 1026, 219)
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
Page 11
+ 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
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
Page 12
+ 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
Vendor Command
Telit AT#STIA=1
Quectel AT+QSTK=1
Sierra Wireless AT+STSF=1
Huawei AT^STSF=1
Page 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
Eseye, AnyNet, AnyNet Secure and Eseye Logos are registered trademarks of Eseye Ltd © Eseye 2017 Limited.
All Rights Reserved. [email protected] | eseye.com
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