↓

Filter results by

Security API through SEE

The basic Secure Element API calls can be made through the ARTIK SDK. However, for the advanced features like post-provisioning provided by the ARTIK "s" modules, you will need to use the artiksee interface described here.

Samsung SEE

The Samsung ARTIK solution includes a Security Library that consists of APIs to communicate with the Samsung SEE from the non-secure OS (Linux). The Security Library offers specific functions related to key management, authentication, secure storage, and post-provisioning.

The following table lists the descriptions of the APIs available as part of the artiksee Security Library. For ARTIK "s" modules, access to all the APIs of ARTIK Security Library is available. For standard modules, only the three highlighted APIs are available.

CategoryARTIK APIDescription
Initialize see_init For Initializing a new SEE session.
see_deinit
Key Manager see_generate_key For management of symmetric and asymmetric keys that are not exposed to non-secure operating system user space.
see_set_key
see_get_pubkey
see_get_publickey(05Xs)
see_remove_key
Authentication see_generate_random For use with the TLS library with callback functions to generate a digital true random number, generate or get certificates, get signatures and verify, and to generate or compute DHM parameters.
see_generate_certificate
see_set_certificate *
see_get_certificate
see_remove_certificate
see_get_rsa_signature
see_verify_rsa_signature
see_get_ecdsa_signature
see_verify_ecdsa_signature
see_get_hash
see_get_hmac
see_generate_dhm_params (05Xs)
see_compute_dhm_param (05Xs)
Secure Storage see_write_secure_storage For access to the secure storage for data, credentials, and keys.
see_read_secure_storage
see_list_secure_storage *
see_delete_secure_storage *
Post Provisioning see_post_provision * For injecting an HMAC key or asymmetric key pair (ECC/RSA) into the secure element.
see_post_provision_lock *
Encryption/
Decryption		 see_rsa_decryption For Data encryption and decryption using a key in secure storage.
see_rsa_encryption
see_aes_decryption
see_aes_encryption

*Not available on ARTIK 05Xs

Set see_debug=1 (or 2 or 3) in your code to see helpful output messages.

The various ARTIK SDK API calls make seamless use of the Samsung ARTIK SEE security libraries. A few ARTIK API calls correspond directly to SEE API calls. Others are indirectly assisted by calls to the SEE libraries, for example:

SSL Parameters for Connectivity – Within ARTIK SDK connectivity features, HTTP requests, MQTT messaging, and WebSockets are available to create secure connections. Included is an SSL configuration structure to easily customize TLS handshake parameters for secure connections. Refer to the API examples for sample code.

OpenSSL Library – For applications that are already using or plan to use the OpenSSL software library, the developer can still take advantage of the ARTIK Security features. OpenSSL command support is available directly without installation of the header files. Refer to the OpenSSL Support article for information and test examples.

Developing with Security Libraries

The artiksee libraries are installed in Ubuntu from libartik-security when you build the system image. The library header files are typically installed separately, since they don't need to be part of the image if you're just using them during development.

Refer to the Advanced Developers article for information on downloading and installing the optional security development package. Basically, you'll just need to execute:
dpkg -i libartik-security-dev*
to install the header files. Look for them under the directories noted.

For A530s: /usr/include/arm-linux-gnueabihf/artik/security

For A710s: /usr/include/aarch64-linux-gnu/artik/security

Once you have the header files installed, follow the tutorial below on developing your own secure applications.

Tutorial

Test code examples in the API demonstrate how the SEE calls might be used in a typical application. We've taken that code and modified it slightly, to give you a repeatable sequence for demonstration.

Try out these routines in the order noted.

Test #1: SEE Key Generation – demonstrates how to generate an HMAC_SHA256 key, an AES128 key, and an RSA1024 key, and how to set the AES128 key data. Run this test first before running the others to generate keys for them to use.

File: see-keygen.c
To build : gcc see-keygen.c -o keygen -lartik-security
To run : ./keygen

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
#include <artik/security.h>
#include <stdio.h>
#include <stdlib.h>
#include <stdint.h>
#include <unistd.h>
#include <string.h>
#include <ctype.h>
#include <time.h>
void PrintBuffer(const char *header, unsigned char* buffer, uint32_t len)
{
    register uint32_t i = 0;
    printf("%s : %d\n", header, len);
    for (i = 0; i < len; i++) {
        if (i != 0 && i % 16 == 0) {
            printf("\n");
        }
        printf(" %02X", buffer[i]);
    }
    printf("\n");
}
int main(void)
{
    see_data hash_gen_key;
    see_data aes_gen_key;
    see_data rsa_gen_key;
    see_data get_key;
    see_data set_key;
    printf("  . See Initialize ...");
    fflush(stdout);
    if (0 != see_init("TEST_ID","TEST_PASSWORD")) {
        printf("Fail\n  ! see_init\n");
        return 0;
    }
    printf("ok\n");
    printf("  . SEE Generate Key : HMAC_SHA256 ...");
    fflush(stdout);
    if (0 != see_generate_key(HMAC_SHA256, "hmacsha256key", &hash_gen_key)) {
        printf("Fail\n  ! see_generate_key\n");
        goto exit;
    }
    printf("ok\n");
    printf("  . SEE Generate Key : AES128 ...");
    fflush(stdout);
    if (0 != see_generate_key(AES_128, "aes128key", &aes_gen_key)) {
        printf("Fail\n  ! see_generate_key\n");
        goto exit;
    }
    printf("ok\n");
    printf("  . SEE Generate Key : RSA1024 ...");
    fflush(stdout);
    if (0 != see_generate_key(RSA_1024, "rsa1024key", &rsa_gen_key)) {
        printf("Fail\n  ! see_generate_key\n");
        goto exit;
    }
    printf("ok\n");
    PrintBuffer("RSA1024 Public key", rsa_gen_key.data, rsa_gen_key.length);
    printf("  . SEE Get Publickey ...");
    fflush(stdout);
    if (0 != see_get_pubkey(RSA_1024, "rsa1024key", &get_key)) {
        printf("Fail\n  ! see_get_pubkey\n");
        goto exit;
    }
    printf("ok\n");
    PrintBuffer("RSA1024 Public key", get_key.data, get_key.length);
    printf("  . SEE Set Key : AES128 ...");
    fflush(stdout);
    set_key.data = "1234567890123456";
    set_key.length = 16;
    if (0 != see_set_key(AES_128, "aes128setkey", set_key)) {
        printf("Fail\n  ! see_set_key\n");
        goto exit;
    }
    printf("ok\n");
    exit:
        see_deinit();
        printf("  . See Deinitialize ...\n");
        fflush(stdout);
        return 0;
}

You cannot run this test twice without first using SEE Key Removal; once a key_name (like aes128key) is generated, it cannot be overwritten. Refer to the see_generate_key description for details.

Test #2: SEE Authentication – demonstrates how to get the certificate, generate random bytes, etc. You'll need to generate keys before calling this routine.

File: see-auth.c
To build : gcc see-auth.c -o auth -lartik-security
To run : ./auth

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
#include <artik/security.h>
#include <stdio.h>
#include <stdlib.h>
#include <stdint.h>
#include <unistd.h>
#include <string.h>
#include <ctype.h>
#include <time.h>
void PrintBuffer(const char *header, unsigned char* buffer, uint32_t len)
{
    register uint32_t i = 0;
    printf("%s : %d\n", header, len);
    for (i = 0; i < len; i++) {
        if (i != 0 && i % 16 == 0) {
            printf("\n");
        }
        printf(" %02X", buffer[i]);
    }
    printf("\n");
}
int main(void)
{
    see_data rand;
    see_data cert;
    see_data plaintext;
    see_data hashed;
    see_data hash;
    see_data sign;
    see_data hmac;
    plaintext.data = "01234567890123456789";
    plaintext.length = 20;
    hashed.data = "01234567890123456789012345678901";
    hashed.length = 32;
    printf("  . See Initialize ...");
    fflush(stdout);
    if (0 != see_init("TEST_ID","TEST_PASSWORD")) {
        printf("Fail\n  ! see_init\n");
        return 0;
    }
    printf("ok\n");
    printf("  . SEE Get Random ...");
    fflush(stdout);
    if (0 != see_generate_random(100, &rand)) {
        printf("Fail\n  ! see_generate_random\n");
        goto exit;
    }
    printf("ok\n");
    PrintBuffer("Random", rand.data, rand.length);
    free(rand.data);
    printf("  . SEE Get Certificate ...");
    fflush(stdout);
    if (0 != see_get_certificate("ARTIK/0", &cert)) {
        printf("Fail\n  ! see_get_certificate\n");
        goto exit;
    }
    printf("ok\n");
    PrintBuffer("Certificate", cert.data, cert.length);
    free(cert.data);
    printf("  . SEE Get ECDSA Signature ...");
    fflush(stdout);
    if (0 != see_get_ecdsa_signature(ECDSA_SEC_P256R1, "ARTIK/0", hashed, &sign)) {
        printf("  fail\n  ! see_get_ecdsa_signature\n");
        goto exit;
    }
    printf("ok\n");
    PrintBuffer("Hashed Data", hashed.data, hashed.length);
    PrintBuffer("Signed Data", sign.data, sign.length);
    free(sign.data);
    printf("  . SEE Get HMAC ...");
    fflush(stdout);
    if (0 != see_get_hmac(HMAC_SHA256, "hmacsha256key", plaintext, &hmac)) {
        printf("  fail\n  ! see_get_hmac\n");
        goto exit;
    }
    printf("ok\n");
    PrintBuffer("Plain Data", plaintext.data, plaintext.length);
    PrintBuffer("HMAC Data", hmac.data, hmac.length);
    free(hmac.data);
    printf("  . SEE Get Hash ...");
    fflush(stdout);
    if (0 != see_get_hash(HASH_SHA256, plaintext, &hash)) {
        printf("  fail\n  ! see_get_hash\n");
        goto exit;
    }
    printf("ok\n");
    PrintBuffer("Plain Text", plaintext.data, plaintext.length);
    PrintBuffer("Hashed Data", hash.data, hash.length);
    free(hash.data);
    exit:
        see_deinit();
        printf("  . See Deinitialize ...\n");
        fflush(stdout);
        return 0;
}

Test #3: SEE Encode/Decode – demonstrates how, using the AES key, to encode data and then decode from that to return to the original value. You'll need to generate keys before calling this routine.

File: see-encdec.c
To build : gcc see-encdec.c -o enc -lartik-security
To run : ./enc

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
#include <artik/security.h>
#include <stdio.h>
#include <stdlib.h>
#include <stdint.h>
#include <unistd.h>
#include <string.h>
#include <ctype.h>
#include <time.h>
void PrintBuffer(const char *header, unsigned char* buffer, uint32_t len)
{
    register uint32_t i = 0;
    printf("%s : %d\n", header, len);
    for (i = 0; i < len; i++) {
        if (i != 0 && i % 16 == 0) {
            printf("\n");
        }
        printf(" %02X", buffer[i]);
    }
    printf("\n");
}
int main(void)
{
    see_data iv;
    see_data input;
    see_data aes_enc_data;
    see_data aes_dec_data;
    see_data rsa_enc_data;
    see_data rsa_dec_data;
    iv.data="1234567890123456";
    iv.length = 16;
    input.data="1234567890123456";
    input.length=16;
    printf("  . See Initialize ...\n");
    fflush(stdout);
    if (0 != see_init("TEST_ID","TEST_PASSWORD")) {
        printf("Fail\n  ! see_init\n");
        return 0;
    }
    printf("ok\n");
    printf("  . SEE AES Encryption ...");
    fflush(stdout);
    if (0 != see_aes_encryption(AES_ECB_NOPAD, "aes128key", iv, input, &aes_enc_data)) {
        printf("Fail\n  ! see_aes_encryption\n");
        goto exit;
    }
    printf("ok\n");
    PrintBuffer("Input", input.data, input.length);
    PrintBuffer("Enc Data", aes_enc_data.data, aes_enc_data.length);
    printf("  . SEE AES Decryption ...");
    fflush(stdout);
    if (0 != see_aes_decryption(AES_ECB_NOPAD, "aes128key", iv, aes_enc_data, &aes_dec_data )) {
        printf("Fail\n  ! see_aes_decryption\n");
        goto exit;
    }
    printf("ok\n");
    PrintBuffer("Enc Data", aes_enc_data.data, aes_enc_data.length);
    PrintBuffer("Dec Data", aes_dec_data.data, aes_dec_data.length);
    free(aes_enc_data.data);
    free(aes_dec_data.data);
    printf("  . SEE RSA Encryption ...");
    fflush(stdout);
    if (0 != see_rsa_encryption(RSAES_PKCS1_V1_5, "rsa1024key", input, &rsa_enc_data)) {
        printf("Fail\n  ! see_rsa_encryption\n");
        goto exit;
    }
    printf("ok\n");
    PrintBuffer("Input", input.data, input.length);
    PrintBuffer("Enc Data", rsa_enc_data.data, rsa_enc_data.length);
    printf("  . SEE RSA Decryption ...");
    fflush(stdout);
    if (0 != see_rsa_decryption(RSAES_PKCS1_V1_5, "rsa1024key", rsa_enc_data, &rsa_dec_data )) {
        printf("Fail\n  ! see_rsa_decryption\n");
        goto exit;
    }
    printf("ok\n");
    PrintBuffer("Enc Data", rsa_enc_data.data, rsa_enc_data.length);
    PrintBuffer("Dec Data", rsa_dec_data.data, rsa_dec_data.length);
    free(rsa_enc_data.data);
    free(rsa_dec_data.data);
    exit:
        see_deinit();
        printf("  . See Deinitialize ...\n");
        fflush(stdout);
    return 0;
}

Test #4: SEE Key Removal – demonstrates how to remove generated keys. You'll need to run this one to undo what you did with the SEE Key Generation Test; otherwise, you will get an error if you try to re-run that test.

File: see-keyrem.c
To build : gcc see-keyrem.c -o keyrem -lartik-security
To run : ./keyrem

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
#include <artik/security.h>
#include <stdio.h>
#include <stdlib.h>
#include <stdint.h>
#include <unistd.h>
#include <string.h>
#include <ctype.h>
#include <time.h>

int main(void)
{

    printf("  . See Initialize ...");
    fflush(stdout);
    if (0 != see_init("TEST_ID","TEST_PASSWORD")) {
        printf("Fail\n  ! see_init\n");
        return 0;
    }
    printf("ok\n");
    printf("  . SEE Remove Key ...");
    fflush(stdout);
    if (0 != see_remove_key(HMAC_SHA256, "hmacsha256key")) {
        printf("Fail\n  ! rem hmac key\n");
    }
    if (0 != see_remove_key(AES_128, "aes128key")) {
        printf("Fail\n  ! rem aes key\n");
    }
    if (0 != see_remove_key(AES_128, "aes128setkey")) {
        printf("Fail\n  ! rem aes set key\n");
    }
    if (0 != see_remove_key(RSA_1024, "rsa1024key")) {
        printf("Fail\n  ! rem rsa key\n");
    }
    printf("ok\n");
    exit:
        see_deinit();
        printf("  . See Deinitialize ...\n");
        fflush(stdout);
        return 0;
}

Test #5: SEE Secure Storage – demonstrates how to put information into Secure Storage, and later delete it. The link below takes you to the API test example file.

File: see-securestorage-test.c
To build : gcc see-securestorage-test.c -o secstor -lartik-security
To run : ./secstor

SEE Post-Provisioning – contact your ARTIK Sales representative for information on post-provisioning. It requires disclosures under NDA.

Last updated on: