Filter results by

Security API through SDK

The ARTIK SDK, used in conjunction with the ARTIK IDE, provides a simple means of interacting with the ARTIK Secure Element.

API call Description
get_certificate Get the certificate stored in the SE.
get_key_from_cert Get private key from the certificate stored in the SE.
get_root_ca Get root CA stored in the SE.
get_random_bytes Generate true random bytes.
get_certificate_sn Get the serial number from the certificate.
verify_signature_init Initialize verification of PKCS7 signature against a signed binary.
verify_signature_update Feed data of the signed binary to the verification process.
verify_signature_final Finalize signature verification process and return final result.

Refer to the ARTIK Security API listing for complete details.

The ARTIK SDK acts as a higher-level wrapper to the lower-level artiksee library, part of the ARTIK Secure Execution Environment (SEE). For details on the low-level library, refer to the see_ calls in the Secure API – SEE article.

Tutorial

Here we'll let you demonstrate to yourself how simple it is to use the ARTIK Secure Element by way of the ARTIK SDK.

Prerequisites

In preparation for this tutorial, you must:

  • Understand the certificate creation process described in this article.

  • Have one ARTIK 5/7/10 board available.

The time for completing this installment of the tutorial series is less than 10 minutes.

Procedure

  1. Create the “Security” project in ARTIK IDE for ARTIK 5/7/10 following the general instructions here.

  2. Take a look at this tiny program. You'll see that it has just three routines:
    test_security_get_serial_number()
    test_security_get_certificate_and_key()
    test_security_random_bytes()

    Within test_security_get_certificate_and_key(), for example, you'll find these security module calls:
       security->request(&handle)
       security->get_certificate(handle, &cert)
    That's all it takes to return the CA certificate.

  3. Run the program and verify the CA certificate.

    1. Save the CA certificate output in a file “cert”

    2. Read its contents with
      openssl x509 -in cert -noout -text

    3. Note that the Root of Trust is “ARTIK CA”

  4. Likewise, verify the private key public certificate.

    1. Save the certificate output in a file “priv”

    2. Read its contents with
      openssl pkey -in priv -noout -text

That's all there is to it!

Troubleshooting

If the calls are failing, make sure you have installed the security test package.

Operational Overview

The following information applies to the pre-provisioned (default out-of-the-box) Secure Element on all ARTIK Linux modules.

Private key access

As you saw in the tutorial, you can readily extract the module certificate using an API call.

The certificate that is provisioned in the Secure Element does not contain the private key part, which is buried in the Secure Element and not accessible from the outside. Although this certificate can mostly be used for TLS authentication, you cannot sign anything with it since you don’t have the private key.

The private key part returned by get_key_from_cert is a "dummy" key since no access to the private key is allowed.

When you call the API to extract the key using get_key_from_cert, you get the correct public key but the dummy private key that should not be used. This is a workaround, in that a lot of SSL libraries need a private key to start the handshake and won’t reach this point if you don’t provide something.

TLS handshake

The Secure Element is used in the ARTIK SDK, in all of the TLS-based modules, by way of the artiksee OpenSSL engine. The TLS handshake goes like this:

  1. Get the certificate and the keys (including the dummy private key) from the SE.

  2. Set up the OpenSSL context with the certificate and keys.

  3. Load the artiksee engine.

  4. Start the handshake; during the process, the certificate and public key will be sent to the server.

  5. When the server replies during ECDSA exchange, OpenSSL calls see_get_ecdsa_signature of the SE through the engine. This function is executed in the SE and uses the real private key matching the certificate. It also calls the see_generate_random function from the SE for true random number generation.

Only the SE can make use of the private key, through see_get_ecdsa_signature. On standard ARTIK modules, the Secure Element has been designed mainly to do this task. "s" modules come with more API calls and allow post-provisioning of your own certificates.

Summary

With the simplicity of the ARTIK Security API, you can start using the Secure Element features immediately in your own applications.

Tahe a moment now to look at the "s" module feature set. The "s" versions add additional security that you may, or may not, need for your purposes.


Last updated on: