Filter results by

Secure your devices

ARTIK Cloud supports secure device registration for communicating securely to devices. ARTIK Cloud ensures the following:

  • The device is genuine.
  • The device owner has the device in hand.
  • Every message exchanged between the device and ARTIK Cloud is verified.
  • We use TLS with mutual client/server authentication where a client key is usually protected by hardware, such as the embedded Secure Element found in ARTIK Modules.

If you are a device manufacturer, follow the below steps to create a secure device type:

Secure endpoints

These secure endpoints are used during registration and in subsequent API calls.

1
2
https://s-api.artik.cloud/v1.1/
wss://s-api.artik.cloud/v1.1/

Secure registration

The secure registration flow differs from the typical registration flow, in which an authenticated user creates a device, and can then request an access token for the device, or send data for the device as its logged-in owner.

Instead, the secure flow functions as follows:

A registered device will appear in My ARTIK Cloud on the list of user-owned devices.

The following sequence diagram shows the interactions among a user, a secure device, the user's browser and ARTIK Cloud. You need to implement the functionalities performed by "Device" in this diagram.

Secure Device Registration

In our examples below, ‘curl’ must be built with OpenSSL v1.0.2 or higher to work with the secure endpoints.

Generate certificates

ARTIK Cloud uses the X.509 certificate standard.

For the device type

To enable secure device registration for your device type, you will need to attach a CA certificate to the device type in the Developer Dashboard.

Generate a private key for your device type certificate with the following command:

1
openssl genrsa -out rootCA.key

Use the private key from the key pair to generate a root CA certificate for all devices of this device type:

1
openssl req -x509 -new -nodes -key rootCA.key -out rootCA.pem -days 500 -sha256

You will be asked to enter information that will be incorporated in your certificate request.

These commands will vary according to your use case and security requirements. In the above command, we include -sha256 to use the strong SHA-2 hash functions and -days 500 to define a certificate expiration date of 500 days.

For the device

A client certificate must be stored in the device before initiating the secure flow. Client certificates must be unique for each device.

Generate a private key for your client certificate with the following command:

1
openssl genrsa -out deviceCert.key

Create a CSR (Certificate Signing Request) for the client certificate:

1
openssl req -new -key deviceCert.key -out deviceCert.csr

You will be asked to enter information that will be incorporated into your certificate request.

Create a client certificate from the CSR:

1
openssl x509 -req -in deviceCert.csr -CA rootCA.pem -CAkey rootCA.key -CAcreateserial -out deviceCert.pem -days 500 -sha256

These commands will vary according to your use case and security requirements. In the above command, we include -sha256 to use the strong SHA-2 hash functions and -days 500 to define a certificate expiration date of 500 days.

When possible, you (as the device manufacturer) should generate and store the client certificate in the secure element of your device. This is the certificate used during the TLS handshake with ARTIK Cloud.

A user can call this API to get detailed information about a device's certificates.

Enable secure device registration

Your organization must be using the Enterprise pricing plan to enable secure device registration.

Secure device registration can be enabled for private device types and for public device types with no connected devices on ARTIK Cloud.

Navigate to the Developer Dashboard and click on Device Types. Select your Device Type.

In the left menu, navigate to the Device Security page under Set Up.

ARTIK Cloud secure device registration

Here you can enable or disable secure device registration and add one or more CAs (Certificate Authorities) that will validate the client certificates of your devices. Client certificates must be signed by the registered CA certificate in order to perform secure device registration and securely send messages to ARTIK Cloud.

ARTIK Cloud secure device registration ARTIK Cloud secure device registration

You must upload at least one CA certificate to establish a trust anchor for your device and enable secure registration.

  • If you are using an intermediate CA certificate to sign your client certificates, you must upload the intermediate CA certificate. It will be considered as the trust anchor.
  • To have your root CA considered as the trust anchor, you must upload the root CA certificate and any intermediate CA certificates in the chain.

Only the last certificate of a chain sent by the client will be validated. This certificate is taken as the client certificate.

ARTIK Cloud secure device registration

Click "Enable SDR" to instantly enable secure device registration.

ARTIK Cloud secure device registration

Once a new device is securely registered, the device will embed a client certificate. When a device sends a message to ARTIK Cloud, we will verify that the client certificate sent by the device:

  • Is valid: Correctly formed, not expired, and active.
  • Has not been used for another device in ARTIK Cloud (device certificates should be unique).
  • Issued by a valid CA that has been uploaded in the device type (in the "Device Type's Device Security page in the developer portal)

ARTIK Cloud secure device registration

Initiate the registration

To initiate the registration process (Step 3 in the sequence diagram above), the device must pass a device type ID (dtid) and vendor device ID (vdid). The vdid is normally determined by the vendor, and must be unique for the device being registered. The API will return a 409 error if another device tries to register with the same vdid and dtid.

The following example shows how to make the API call using a curl command and the corresponding response. The response includes rid (request ID), pin (user PIN) and nonce (secret string, to be used in Step 15), which will be used in the subsequent API calls.

1
2
3
4
5
6
7
8
9
10
11
12
13
localhost:~$ curl -X POST -k -i -H "Accept: application/json" -H "Content-Type: application/json" \
-d '{"deviceTypeId":"dt430e40b477dd42ccb09cc83241ef9b99","vendorDeviceId":"a1b2c3d4"}' \
--cert /path/to/client.cert --key /path/to/client-pri.key https://s-api.artik.cloud/v1.1/cert/devices/registrations

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Referer, User-Agent, Authorization
Access-Control-Allow-Methods: POST, GET, PUT, DELETE, OPTIONS
Allow: *
Content-Type: application/json; charset=utf-8
Content-Length: 96

{"data":{"rid":"01329450db1b4a2d8e17acb4449b0f70","pin":"QJ39NCBO","nonce":"35cc3b62c8a544788a696a652d63d8c5","expiresOn":1423197470000}}

Check registration status

At Step 8 of secure device registration, the user is presented pin and a registration URL. The user should navigate to this URL in their browser to move registration to the next phase.

During this process, the device can make the following optional API call to query the registration status. (This step is not illustrated in the sequence diagram.)

1
  GET /cert/devices/registrations/:rid/status

nonce is passed as data to this GET request. The below excerpt illustrates sending the HTTP request using curl, and the corresponding HTTP response.

1
2
3
4
5
6
7
8
9
10
11
12
localhost:~$ curl -k -i -H "Accept: application/json" \
--cert /path/to/client.cert --key /path/to/client-pri.key https://s-api.artik.cloud/v1.1/cert/devices/registrations/01329450db1b4a2d8e17acb4449b0f70/status

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Referer, User-Agent, Authorization
Access-Control-Allow-Methods: POST, GET, PUT, DELETE, OPTIONS
Allow: *
Content-Type: application/json; charset=utf-8
Content-Length: 29

{"data":{"status":"PENDING_DEVICE_COMPLETION"}}

In the HTTP response, status could be one of the following strings:

  • "PENDING_USER_CONFIRMATION": After initial registration; before user confirmation
  • "PENDING_DEVICE_COMPLETION": After user confirmation; before device registration completes
  • "REGISTERED": Device is registered
  • "EXPIRED": Request is expired
  • "REVOKED": Request is revoked due to another request being created for the same device

If "status" is "REGISTERED", the response will also contain did, the device ID.

The following error codes may be returned in the HTTP response:

  • 404: Not found
  • 403: Client certificates do not match the info in the request

Complete the registration

When the user clicks the "Pair" button (Step 14), the device makes the final API call to complete the registration (Step 15). The following example shows sending the HTTP request via a curl command, and the corresponding reply:

1
2
3
4
5
6
7
8
9
10
11
12
13
localhost:~$ curl -X PUT -k -i -H "Accept: application/json" -H "Content-Type: application/json" \
-d '{"nonce":"35cc3b62c8a544788a696a652d63d8c5"}' --cert /path/to/client.cert --key /path/to/client-pri.key \
https://s-api.artik.cloud/v1.1/cert/devices/registrations/01329450db1b4a2d8e17acb4449b0f70

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Referer, User-Agent, Authorization
Access-Control-Allow-Methods: POST, GET, PUT, DELETE, OPTIONS
Allow: *
Content-Type: application/json; charset=utf-8
Content-Length: 141

{"data":{"accessToken":"e542564a82a5441a8bf20cb8c74cc43f","uid":"9c2717258a4d4092aeb3800e44629180","did":"0c9adcb292124f08955f11ea65c77e5d"}}

From now on, the accessToken from the above response will be used with the certificate in subsequent calls sending messages to ARTIK Cloud.

Securely exchange information

After secure registration, the device must make all subsequent API calls in the secure manner. The secure manner means that calls are made to a secure endpoint and contain both the device access token and the certificate.

If a secure device makes an API call to a non-secure endpoint, it will get a 403 error.

The following examples illustrate sending messages from a secure device to ARTIK Cloud via REST and WebSocket APIs.

Securely post messages

This excerpt shows how to make such an API call and the corresponding HTTP response:

1
2
3
4
5
6
7
8
9
10
11
12
13
localhost:~$ curl -X POST -k -i -H "Accept: application/json" -H "Content-Type: application/json" \
-H "Authorization: bearer e542564a82a5441a8bf20cb8c74cc43f" \
-d '{"sdid":"0c9adcb292124f08955f11ea65c77e5d","data":{"stepCount":100,"timeInBed":200,"asleepTime":10,"calories":150}}' \
--cert /path/to/client.cert --key /path/to/client-pri.key https://s-api.artik.cloud:443/v1.1/message

HTTP/1.1 200 OK
X-Rate-Limit-Limit: 100/1000
X-Rate-Limit-Remaining: 99/997
X-Rate-Limit-Reset: 1423179332/1423180800
Content-Type: application/json
Content-Length: 51
 
{"data":{"mid":"7d005bba074e4afab21d56e49f5301bd"}}

Securely send and receive via WebSocket

The below sequence diagram gives an overview of sending and receiving data securely to and from ARTIK Cloud using WebSockets:

Secure Device Registration

Below are the details.

Setting up a device channel WebSocket

Make the following WebSocket call to the secure WebSocket endpoint:

1
WebSocket /websocket

In the above call, you must pass the client certificate and the corresponding private key. You do not use the certificate in this call when establishing the pipe between an ordinary device and ARTIK Cloud.

In addition, this call is only one for which you must provide the certificate for a secure session. Follow-up WebSocket calls in this session won't use the certificate.

Connecting the device to the WebSocket

After the device channel is established, the device sends a message with type "register" to connect itself to the session. Below is the example of the message payload:

1
2
3
4
5
{
  "sdid": "887750439b0548aba42a22c0ad26bc95",
  "Authorization": "bearer d77054a9b0874ba884499eef7768b7b9",
  "type": "register"
}         

Sending and receiving messages

After the device is connected into the secure pipe, it can securely send and receive messages to and from ARTIK Cloud.

Below is an example of sending a message to ARTIK Cloud in the established session:

1
send {"type":"message", "sdid":"887750439b0548aba42a22c0ad26bc95", "data":"data payload"}