End-to-end Symmetric KMS

The module includes a (D)TLS security layer profile manager, which handles security profiles containing (D)TLS connection properties. Each security profile can be associated to sockets or higher level applications (e.g., HTTP, MQTT) using the module internal (D)TLS stack. In general, the AT+USECPRF command is used to configure a security profile.

The following AT commands can be used to configure a security profile on the module with certain PSKIdentity and PSK:

This way, associating a TCP socket to security profile 0, PSKIdentity and PSK will be used to handle the TLS communication through that TCP socket.

Examples

Following are some examples of the procedure described above.

These are example commands and do not use real world API keys or authorization headers. Actual API secret key and authorization headers must first be created before running these commands.

• Get PSK and PSKIdentity from RoT. For example, get a 16 bytes long PSK:

AT+USECPSK=16

+USECPSK: "11010008002F33244B115B0AEEB9","E5DE45B367DB690F2E17CF9D80A18E87"

OK

• 11010008002F33244B115B0AEEB9 is the PSKIdentity in hex format: this has to be sent to the remote service during the (D)TLS handshake.

• E5DE45B367DB690F2E17CF9D80A18E87 is the actual PSK in hex format: this can be used to encrypt the communication to the remote service.

• Configure the (D)TLS stack to use the PSKIdentity and PSK generated by RoT.

This step depends on the (D)TLS stack used. We provide 2 examples:

• Use OpenSSL command to test the connection to the remote service.

  • Call OpenSSL this way:

openssl s_client -psk_identity "11010008002F33244B115B0AEEB9" -psk "E5DE45B367DB690F2E17CF9D80A18E87" -connect <server_IP:server_port>

• • Use a modem internal socket to communicate to the remote service.

Configure a security profile (profile 0 in this example):

AT+USECPRF=0,8,"E5DE45B367DB690F2E17CF9D80A18E87",1

OK

AT+USECPRF=0,9,"11010008002F33244B115B0AEEB9"

OK

Then, create a socket and enable the secure option on the socket, associating the security profile 0 to it:

AT+USOCR=6

+USOCR: 0              <-- created socket with id 0

OK

AT+USOSEC=0,1,0        <-- associate socket 0 to security profile 0

OK

Connect the socket to the remote service:

AT+USOCO=0,"<server_IP>",<server_port>

• Analyzing the communication between client and remote service, we can see the PSKIdentity being sent by the client in the ClientKeyExchange message during (D)TLS handshake:

• On the server side.

The actual way to extract the PSKIdentity from the ClientKeyExchange message can vary and depends on the (D)TLS stack used.

For example, a server application using OpenSSL libraries and wishing to use PSKs for TLSv1.2 and below, must provide a callback function called when the server receives the ClientKeyExchange message. This function has the purpose of fetching the correct PSK starting from the PSKIdentity retrieved from the client. The callback function is set by calling SSL_CTX_set_psk_server_callback(SSL_CTX *ctx, SSL_psk_server_cb_func cb):

#include <openssl/ssl.h>

#include <openssl/err.h>

…

SSL_CTX *ctx;

const SSL_METHOD *method;

method = SSLv23_server_method();

ctx = SSL_CTX_new(method);

if (!ctx) {

    ERR_print_errors_fp(stderr);

    return -1;

}

SSL_CTX_set_ecdh_auto(ctx, 1);

SSL_CTX_use_psk_identity_hint(ctx, "hint hint");

SSL_CTX_set_psk_server_callback(ctx, psk_server_cb);

During (D)TLS handshake, when the server receives the ClientKeyExchange message, the psk_server_cb function is called.

static unsigned int psk_server_cb(SSL *ssl,

                const char *identity,

                unsigned char *psk,

                unsigned int max_psk_len) {

    char* py_psk;

    if (identity == NULL) {

        return 0;

    }

    /* Retrieve the PSK for the given identity */

/* … */

See OpenSSL documentation for more details (https://www.openssl.org/docs/).

Once the PSKIdentity is retrieved, the customer can obtain the PSK via the GetPSK REST API call (https://ssapi.services.u-blox.com/v1/GetPSK). Make sure to have an AuthToken to use for the Authorization header – if not, call the Authorize API to get one.

We show the API call using cURL: we have to specify the PSKIdentity in the KeyID parameter and, optionally, the PSK length (in bits) in the KeyLength parameter:

curl -X POST "https://ssapi.services.u-blox.com/v1/GetPSK" -H "accept: application/json" -H "Authorization: [AuthToken]" -H "Content-Type: application/json" -d "{ \"KeyID\": \"11010008002F33244B115B0AEEB9\", \"KeyLength\": \"128\"}"

In the previous C server application, it’s possible for example to use the libcurl library to perform the API request. See libcurl documentation for more details (https://curl.haxx.se/libcurl/c/).

• The API returns a JSON containing the PSK encoded using base64:

{

    "Key": "5d5Fs2fbaQ8uF8+dgKGOhw==",

    "ROTPublicUID": "0002000089282245"

}

• Considering the C server application from above, at this point the server can create a server socket (sock_fd) and wrap it with the OpenSSL context from before (ctx):

SSL *ssl;

const SSL_METHOD *method;

method = SSLv23_server_method();

SSL_CTX_set_ecdh_auto(ctx, 1);

SSL_CTX_use_psk_identity_hint(ctx, "hint hint");

SSL_CTX_set_psk_server_callback(ctx, psk_server_cb);

ssl = SSL_new(ctx);

if (ssl == NULL) {

    // Failed to initialise SSL buffer

    return NULL;

}

if (0 == SSL_set_fd(ssl, sock_fd)) {

// Failed to configure IO for the SSL socket

    ERR_print_errors_fp(stderr);

    return NULL;

};

if (SSL_accept(ssl) <= 0) {

// Failed to setup SSL socket as server

    ERR_print_errors_fp(stderr);

    SSL_free(ssl);

    return NULL;

}

At this point, the server application can exchange data through the secure socket by using SSL_read() and SSL_write. See OpenSSL documentation for more details (https://www.openssl.org/docs/).