Tizen Native API  6.5
Device Certificate Manager

Device Certificate Manager provides cryptography services (digital certificates and keys) for authentication and secure communication with another system. Device certificate and key was embedded in device storage.

Required Header

#include <device_certificate_manager.h>

Related Features

This module is related with the following features:

  • http://tizen.org/feature/security.device_certificate
    It is recommended to use features in your application for reliability.
    You can check if the device supports the related features for this API by using System Information, and control your application's actions accordingly.
    To ensure your application is running only on devices with specific features, please define the features in your manifest file using the manifest editor in the SDK.
    More details on using features in your application can be found in the feature element description.

Overview

Device Certificate Manager provides cryptography services (digital certificates and keys) for authentication and secure communication with another system. Device certificate and key was embedded in device storage.

Examples

Device Certificate Manager API example

#include <stdio.h>
#include <stdlib.h>

#include "device_certificate_manager.h"

int main()
{
    int result;
    void *key_ctx = NULL;
    char *key_type = NULL;
    size_t key_len;
    char *cert_chain = NULL;
    size_t cert_chain_len;
    char *signature = NULL;
    size_t signature_len;

    result = dcm_create_key_context("example_client", "test_usage", "", &key_ctx);
    if (result != DCM_ERROR_NONE) {
        printf("Can't create context\n");
        goto exit;
    }

    result = dcm_get_certificate_chain(key_ctx, &cert_chain, &cert_chain_len);
    if (result != DCM_ERROR_NONE) {
        printf("Can't get cert chain\n");
        goto exit;
    }
    printf("Cert is %zu bytes\n", cert_chain_len);
    printf("Received cert %s\n", cert_chain);

    result = dcm_get_key_type(key_ctx, &key_type);
    if (result != DCM_ERROR_NONE) {
        printf("Can't get key type\n");
        goto exit;
    }

    result = dcm_get_key_bit_length(key_ctx, &key_len);
    if (result != DCM_ERROR_NONE) {
        printf("Can't get key length\n");
        goto exit;
    }
    printf("Private key is %zu bits\n", key_len);
    printf("Private key is %s\n", key_type);

    result = dcm_create_signature(key_ctx, DCM_DIGEST_SHA256, "12345678901234567890123456789012", 32, &signature, &signature_len);
    if (result != DCM_ERROR_NONE) {
        printf("Can't create signature\n");
        goto exit;
    }

    for(unsigned int i = 0; i < signature_len; i++) {
        printf("%x ", (int)(*(unsigned char*)(&signature[i])));
    }
    printf("\n");

exit:
    free(signature);
    free(cert_chain);
    free(key_type);
    dcm_free_key_context(key_ctx);

    return result;
}

Functions

int dcm_create_key_context (const char *service, const char *usage, const char *key_type, void **key_ctx)
 Creates a new key context based on specific name indication (service name, key usage, key type).
int dcm_free_key_context (void *key_ctx)
 Destroys the key context that was created by calling dcm_create_key_context().
int dcm_get_certificate_chain (const void *key_ctx, char **cert_chain, size_t *cert_chain_len)
 Returns a certificate chain which was pre-injected in device.
int dcm_get_key_bit_length (const void *key_ctx, size_t *key_bit_len)
 Returns the key size in bits for a given key context.
int dcm_get_key_type (const void *key_ctx, char **key_type)
 Returns the key type name for a given key context.
int dcm_create_signature (const void *key_ctx, dcm_digest_algorithm_e md, const char *message, size_t message_len, char **signature, size_t *signature_len)
 Creates a signature on a given data using a private key and returns the signature.

Enumeration Type Documentation

Enumeration for DCM message digest algorithms.

Since :
5.0
Enumerator:
DCM_DIGEST_NONE 

No message digest algorithm

DCM_DIGEST_MD2 

Message digest algorithm MD2

DCM_DIGEST_MD4 

Message digest algorithm MD4

DCM_DIGEST_MD5 

Message digest algorithm MD5

DCM_DIGEST_SHA1 

Message digest algorithm SHA1

DCM_DIGEST_SHA224 

Message digest algorithm SHA224

DCM_DIGEST_SHA256 

Message digest algorithm SHA256

DCM_DIGEST_SHA384 

Message digest algorithm SHA384

DCM_DIGEST_SHA512 

Message digest algorithm SHA512

DCM_DIGEST_RIPEMD160 

Message digest algorithm RIPEMD160

Enumeration for DCM error values.

Since :
5.0
Enumerator:
DCM_ERROR_NONE 

Successful

DCM_ERROR_INVALID_PARAMETER 

Invalid function parameter

DCM_ERROR_OUT_OF_MEMORY 

Out of memory

DCM_ERROR_PERMISSION_DENIED 

Permission denied

DCM_ERROR_NOT_SUPPORTED 

Feature needed to run API is not supported

DCM_ERROR_NO_DATA 

No data available

DCM_ERROR_UNKNOWN 

Unknown error

DCM_ERROR_SOCKET 

Socket error between client and server


Function Documentation

int dcm_create_key_context ( const char *  service,
const char *  usage,
const char *  key_type,
void **  key_ctx 
)

Creates a new key context based on specific name indication (service name, key usage, key type).

Warning:
This is not for use by third-party applications.
Since :
5.0
Privilege Level:
platform
Privilege:
http://tizen.org/privilege/devicecertificate
Remarks:
The key_ctx should be freed with dcm_free_key_context() after use.
Parameters:
[in]serviceService name indicates first category name (if null, default value is used)
[in]usageUsage name indicates sub-category name (if null, default value is used)
[in]key_typeKey type name indication (if null, default value is used)
[out]key_ctxNewly created key context
Returns:
DCM_ERROR_NONE on success, otherwise a negative error value
Return values:
DCM_ERROR_NONESuccessful
DCM_ERROR_NOT_SUPPORTEDFeature needed to run API is not supported
DCM_ERROR_PERMISSION_DENIEDFailed to access device certificate manager
DCM_ERROR_INVALID_PARAMETERInput parameter is invalid
DCM_ERROR_SOCKETSocket error between client and server
DCM_ERROR_OUT_OF_MEMORYOut of memory during processing
DCM_ERROR_UNKNOWNUnknown error
See also:
dcm_free_key_context()
int dcm_create_signature ( const void *  key_ctx,
dcm_digest_algorithm_e  md,
const char *  message,
size_t  message_len,
char **  signature,
size_t *  signature_len 
)

Creates a signature on a given data using a private key and returns the signature.

Warning:
This is not for use by third-party applications.
Since :
5.0
Privilege Level:
platform
Privilege:
http://tizen.org/privilege/devicecertificate
Remarks:
The private key is identified by key_ctx.
The message can be NULL but then message_len must be 0.
The signature should be freed using free().
Parameters:
[in]key_ctxKey context object that identifies a proper private key for signing
[in]mdMessage digest algorithm used in creating signature
[in]messageMessage that is signed with a key
[in]message_lenLength of the message
[out]signatureNewly created signature, will be allocated by the library
[out]signature_lenLength of a newly created signature
Returns:
DCM_ERROR_NONE on success, otherwise a negative error value
Return values:
DCM_ERROR_NONESuccessful
DCM_ERROR_NOT_SUPPORTEDFeature needed to run API is not supported
DCM_ERROR_PERMISSION_DENIEDFailed to access device certificate manager
DCM_ERROR_INVALID_PARAMETERInput parameter is invalid
DCM_ERROR_SOCKETSocket error between client and server
DCM_ERROR_OUT_OF_MEMORYOut of memory during processing
DCM_ERROR_UNKNOWNUnknown error
int dcm_free_key_context ( void *  key_ctx)

Destroys the key context that was created by calling dcm_create_key_context().

Warning:
This is not for use by third-party applications.
Since :
5.0
Privilege Level:
platform
Privilege:
http://tizen.org/privilege/devicecertificate
Parameters:
[in]key_ctxKey context object to be deallocated
Returns:
DCM_ERROR_NONE on success, otherwise a negative error value
Return values:
DCM_ERROR_NONESuccessful
DCM_ERROR_NOT_SUPPORTEDFeature needed to run API is not supported
DCM_ERROR_PERMISSION_DENIEDFailed to access device certificate manager
DCM_ERROR_INVALID_PARAMETERInput parameter is invalid
DCM_ERROR_SOCKETSocket error between client and server
DCM_ERROR_OUT_OF_MEMORYOut of memory during processing
DCM_ERROR_NO_DATANo such key context object
DCM_ERROR_UNKNOWNUnknown error
See also:
dcm_create_key_context()
int dcm_get_certificate_chain ( const void *  key_ctx,
char **  cert_chain,
size_t *  cert_chain_len 
)

Returns a certificate chain which was pre-injected in device.

Warning:
This is not for use by third-party applications.
Since :
5.0
Privilege Level:
platform
Privilege:
http://tizen.org/privilege/devicecertificate
Remarks:
The cert_chain should be freed using free().
Parameters:
[in]key_ctxKey context object that identifies proper certificate chain
[out]cert_chainCertificate chain in binary, will be allocated by the library
[out]cert_chain_lenThe total length of certificate chain
Returns:
DCM_ERROR_NONE on success, otherwise a negative error value
Return values:
DCM_ERROR_NONESuccessful
DCM_ERROR_NOT_SUPPORTEDFeature needed to run API is not supported
DCM_ERROR_PERMISSION_DENIEDFailed to access device certificate manager
DCM_ERROR_INVALID_PARAMETERInput parameter is invalid
DCM_ERROR_SOCKETSocket error between client and server
DCM_ERROR_OUT_OF_MEMORYOut of memory during processing
DCM_ERROR_NO_DATANo certificate chain available
DCM_ERROR_UNKNOWNUnknown error
int dcm_get_key_bit_length ( const void *  key_ctx,
size_t *  key_bit_len 
)

Returns the key size in bits for a given key context.

Warning:
This is not for use by third-party applications.
Since :
5.0
Privilege Level:
platform
Privilege:
http://tizen.org/privilege/devicecertificate
Parameters:
[in]key_ctxKey context object that identifies proper certificate chain
[out]key_bit_lenKey length in bits
Returns:
DCM_ERROR_NONE on success, otherwise a negative error value
Return values:
DCM_ERROR_NONESuccessful
DCM_ERROR_NOT_SUPPORTEDFeature needed to run API is not supported
DCM_ERROR_PERMISSION_DENIEDFailed to access device certificate manager
DCM_ERROR_INVALID_PARAMETERInput parameter is invalid
DCM_ERROR_SOCKETSocket error between client and server
DCM_ERROR_OUT_OF_MEMORYOut of memory during processing
DCM_ERROR_NO_DATANo certificate chain available
DCM_ERROR_UNKNOWNUnknown error
int dcm_get_key_type ( const void *  key_ctx,
char **  key_type 
)

Returns the key type name for a given key context.

Warning:
This is not for use by third-party applications.
Since :
5.0
Privilege Level:
platform
Privilege:
http://tizen.org/privilege/devicecertificate
Remarks:
The key_type should be freed using free().
Parameters:
[in]key_ctxKey context object that identifies proper certificate chain
[out]key_typeKey type name (UNKNOWN, RSA or ECDSA), will be allocated by the library
Returns:
DCM_ERROR_NONE on success, otherwise a negative error value
Return values:
DCM_ERROR_NONESuccessful
DCM_ERROR_NOT_SUPPORTEDFeature needed to run API is not supported
DCM_ERROR_PERMISSION_DENIEDFailed to access device certificate manager
DCM_ERROR_INVALID_PARAMETERInput parameter is invalid
DCM_ERROR_SOCKETSocket error between client and server
DCM_ERROR_OUT_OF_MEMORYOut of memory during processing
DCM_ERROR_NO_DATANo certificate chain available
DCM_ERROR_UNKNOWNUnknown error