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

enum dcm_digest_algorithm_e

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

enum dcm_error_e

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]	service	Service name indicates first category name (if null, default value is used)
[in]	usage	Usage name indicates sub-category name (if null, default value is used)
[in]	key_type	Key type name indication (if null, default value is used)
[out]	key_ctx	Newly created key context

Returns:: DCM_ERROR_NONE on success, otherwise a negative error value

Return values:

DCM_ERROR_NONE	Successful
DCM_ERROR_NOT_SUPPORTED	Feature needed to run API is not supported
DCM_ERROR_PERMISSION_DENIED	Failed to access device certificate manager
DCM_ERROR_INVALID_PARAMETER	Input parameter is invalid
DCM_ERROR_SOCKET	Socket error between client and server
DCM_ERROR_OUT_OF_MEMORY	Out of memory during processing
DCM_ERROR_UNKNOWN	Unknown 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_ctx	Key context object that identifies a proper private key for signing
[in]	md	Message digest algorithm used in creating signature
[in]	message	Message that is signed with a key
[in]	message_len	Length of the message
[out]	signature	Newly created signature, will be allocated by the library
[out]	signature_len	Length of a newly created signature

Returns:: DCM_ERROR_NONE on success, otherwise a negative error value

Return values:

DCM_ERROR_NONE	Successful
DCM_ERROR_NOT_SUPPORTED	Feature needed to run API is not supported
DCM_ERROR_PERMISSION_DENIED	Failed to access device certificate manager
DCM_ERROR_INVALID_PARAMETER	Input parameter is invalid
DCM_ERROR_SOCKET	Socket error between client and server
DCM_ERROR_OUT_OF_MEMORY	Out of memory during processing
DCM_ERROR_UNKNOWN	Unknown 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_ctx Key context object to be deallocated

Returns:: DCM_ERROR_NONE on success, otherwise a negative error value

Return values:

DCM_ERROR_NONE	Successful
DCM_ERROR_NOT_SUPPORTED	Feature needed to run API is not supported
DCM_ERROR_PERMISSION_DENIED	Failed to access device certificate manager
DCM_ERROR_INVALID_PARAMETER	Input parameter is invalid
DCM_ERROR_SOCKET	Socket error between client and server
DCM_ERROR_OUT_OF_MEMORY	Out of memory during processing
DCM_ERROR_NO_DATA	No such key context object
DCM_ERROR_UNKNOWN	Unknown 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_ctx	Key context object that identifies proper certificate chain
[out]	cert_chain	Certificate chain in binary, will be allocated by the library
[out]	cert_chain_len	The total length of certificate chain

Returns:: DCM_ERROR_NONE on success, otherwise a negative error value

Return values:

DCM_ERROR_NONE	Successful
DCM_ERROR_NOT_SUPPORTED	Feature needed to run API is not supported
DCM_ERROR_PERMISSION_DENIED	Failed to access device certificate manager
DCM_ERROR_INVALID_PARAMETER	Input parameter is invalid
DCM_ERROR_SOCKET	Socket error between client and server
DCM_ERROR_OUT_OF_MEMORY	Out of memory during processing
DCM_ERROR_NO_DATA	No certificate chain available
DCM_ERROR_UNKNOWN	Unknown 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_ctx	Key context object that identifies proper certificate chain
[out]	key_bit_len	Key length in bits

Returns:: DCM_ERROR_NONE on success, otherwise a negative error value

Return values:

DCM_ERROR_NONE	Successful
DCM_ERROR_NOT_SUPPORTED	Feature needed to run API is not supported
DCM_ERROR_PERMISSION_DENIED	Failed to access device certificate manager
DCM_ERROR_INVALID_PARAMETER	Input parameter is invalid
DCM_ERROR_SOCKET	Socket error between client and server
DCM_ERROR_OUT_OF_MEMORY	Out of memory during processing
DCM_ERROR_NO_DATA	No certificate chain available
DCM_ERROR_UNKNOWN	Unknown 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_ctx	Key context object that identifies proper certificate chain
[out]	key_type	Key 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_NONE	Successful
DCM_ERROR_NOT_SUPPORTED	Feature needed to run API is not supported
DCM_ERROR_PERMISSION_DENIED	Failed to access device certificate manager
DCM_ERROR_INVALID_PARAMETER	Input parameter is invalid
DCM_ERROR_SOCKET	Socket error between client and server
DCM_ERROR_OUT_OF_MEMORY	Out of memory during processing
DCM_ERROR_NO_DATA	No certificate chain available
DCM_ERROR_UNKNOWN	Unknown error

Required Header

Related Features

Overview

Examples

Functions

Enumeration Type Documentation

Function Documentation