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.
int	dcm_e2ee_create_bundle (unsigned char message, size_t message_len, dcm_e2ee_bundle_h bundle)
	Creates an E2EE message bundle from a binary message.
void	dcm_e2ee_free_bundle (dcm_e2ee_bundle_h bundle)
	Releases the memory associated with E2EE message bundle.
int	dcm_e2ee_get_bundle_message (const dcm_e2ee_bundle_h bundle, const unsigned char *message, size_t message_len)
	Retrieves a pointer to the whole binary message contained in the E2EE bundle.
int	dcm_e2ee_get_bundle_platform (const dcm_e2ee_bundle_h bundle, const char **platform)
	Retrieves a pointer to the platform string contained in the E2EE bundle.
int	dcm_e2ee_get_bundle_pkg_id (const dcm_e2ee_bundle_h bundle, const char **pkg_id)
	Retrieves a pointer to the package id string contained in the E2EE bundle.
int	dcm_e2ee_get_bundle_payload (const dcm_e2ee_bundle_h bundle, const unsigned char *payload, size_t payload_len)
	Retrieves a pointer to the payload byte sequence contained in the E2EE bundle.
int	dcm_e2ee_create_signed_bundle (const void key_ctx, dcm_digest_algorithm_e md, const unsigned char payload, size_t payload_len, dcm_e2ee_bundle_h bundle, char signature, size_t signature_len)
	Creates an E2EE message bundle from a payload and signs it using given private key.
Typedefs
typedef struct dcm_e2ee_bundle_s *	dcm_e2ee_bundle_h
	Handle to a struct containing E2EE message bundle.

Typedef Documentation

typedef struct dcm_e2ee_bundle_s* dcm_e2ee_bundle_h

Handle to a struct containing E2EE message bundle.

Since :: 6.5

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
DCM_ERROR_MSG_FORMAT	Message is not in Tizen platform format (Since 6.5)

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_e2ee_create_bundle	(	unsigned char *	message,
		size_t	message_len,
		dcm_e2ee_bundle_h *	bundle
	)

Creates an E2EE message bundle from a binary message.

Since :: 6.5

Parameters:

[in]	message	The binary message. Usually received from another E2EE peer. The message must be allocated with malloc(). The bundle takes the ownership of the message and will free it automatically using free().
[in]	message_len	Length of the message
[out]	bundle	Bundle allowing deserialization of the E2EE message. Must be freed with dcm_e2ee_free_bundle() when no longer needed.

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_INVALID_PARAMETER	Input parameter is invalid (message = NULL or bundle = NULL) or the message format is invalid.
DCM_ERROR_MSG_FORMAT	The message is not in Tizen platform format.
DCM_ERROR_UNKNOWN	Unknown error

See also:: dcm_e2ee_free_bundle(); dcm_e2ee_bundle_h

int dcm_e2ee_create_signed_bundle	(	const void *	key_ctx,
		dcm_digest_algorithm_e	md,
		const unsigned char *	payload,
		size_t	payload_len,
		dcm_e2ee_bundle_h *	bundle,
		char **	signature,
		size_t *	signature_len
	)

Creates an E2EE message bundle from a payload and signs it using given private key.

Warning:: This is not for use by third-party applications.

Since :: 6.5

Privilege Level:: platform

Privilege:: http://tizen.org/privilege/devicecertificate

Remarks:: The private key is identified by key_ctx.; The payload can be NULL but then payload_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]	payload	Byte sequence used to construct the E2EE message that will be signed
[in]	payload_len	Length of the payload
[out]	bundle	Newly created bundle containing the signed E2EE message. Must be freed with dcm_e2ee_free_bundle() when no longer needed
[out]	signature	Newly created signature, will be allocated by the library. Must be freed using free() when no longer needed
[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 (key_ctx = NULL, payload = NULL but payload_len > 0, bundle = NULL, signature = NULL or signature_len = NULL)
DCM_ERROR_OUT_OF_MEMORY	Out of memory during processing
DCM_ERROR_SOCKET	Socket error between client and server
DCM_ERROR_UNKNOWN	Unknown error

See also:: dcm_e2ee_free_bundle(); dcm_e2ee_bundle_h

void dcm_e2ee_free_bundle ( dcm_e2ee_bundle_h bundle )

Releases the memory associated with E2EE message bundle.

Since :: 6.5

Remarks:: It will free the underlying binary message.

Parameters:

[in] bundle Bundle to be freed

See also:: dcm_e2ee_create_bundle(); dcm_e2ee_bundle_h

int dcm_e2ee_get_bundle_message	(	const dcm_e2ee_bundle_h	bundle,
		const unsigned char **	message,
		size_t *	message_len
	)

Retrieves a pointer to the whole binary message contained in the E2EE bundle.

Since :: 6.5

Remarks:: The typical use is to retrieve the message from a bundle created and signed with dcm_e2ee_create_signed_bundle()

Parameters:

[in]	bundle	The bundle to retrieve from
[out]	message	The pointer to the binary message contained in the bundle. The pointer must not be freed. The pointer becomes invalid after the bundle is freed
[out]	message_len	The length of the message

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_INVALID_PARAMETER	bundle, message or message_len is NULL.
DCM_ERROR_UNKNOWN	Unknown error

See also:: dcm_e2ee_create_signed_bundle(); dcm_e2ee_free_bundle(); dcm_e2ee_bundle_h

int dcm_e2ee_get_bundle_payload	(	const dcm_e2ee_bundle_h	bundle,
		const unsigned char **	payload,
		size_t *	payload_len
	)

Retrieves a pointer to the payload byte sequence contained in the E2EE bundle.

Since :: 6.5

Remarks:: The typical use is to retrieve the binary payload from a bundle created with dcm_e2ee_create_bundle() from received binary message.

Parameters:

[in]	bundle	The bundle to retrieve from
[out]	payload	The pointer to the payload byte sequence contained in the bundle. The pointer must not be freed. The pointer becomes invalid after the bundle is freed
[out]	payload_len	The length of the payload

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_INVALID_PARAMETER	bundle, payload or payload_len is NULL.
DCM_ERROR_UNKNOWN	Unknown error

See also:: dcm_e2ee_create_bundle(); dcm_e2ee_free_bundle(); dcm_e2ee_bundle_h

int dcm_e2ee_get_bundle_pkg_id	(	const dcm_e2ee_bundle_h	bundle,
		const char **	pkg_id
	)

Retrieves a pointer to the package id string contained in the E2EE bundle.

Since :: 6.5

Remarks:: The typical use is to retrieve the package id from a bundle created with dcm_e2ee_create_bundle() from received binary message.

Parameters:

[in]	bundle	The bundle to retrieve from
[out]	pkg_id	The pointer to the package id string contained in the bundle. The pointer must not be freed. The pointer becomes invalid after the bundle is freed

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_INVALID_PARAMETER	bundle or pkg_id is NULL.
DCM_ERROR_UNKNOWN	Unknown error

See also:: dcm_e2ee_create_bundle(); dcm_e2ee_free_bundle(); dcm_e2ee_bundle_h

int dcm_e2ee_get_bundle_platform	(	const dcm_e2ee_bundle_h	bundle,
		const char **	platform
	)

Retrieves a pointer to the platform string contained in the E2EE bundle.

Since :: 6.5

Remarks:: The typical use is to retrieve the platform string from a bundle created with dcm_e2ee_create_bundle() from received binary message.

Parameters:

[in]	bundle	The bundle to retrieve from
[out]	platform	The pointer to the platform string contained in the bundle. The pointer must not be freed. The pointer becomes invalid after the bundle is freed

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_INVALID_PARAMETER	bundle or platform is NULL.
DCM_ERROR_UNKNOWN	Unknown error

See also:: dcm_e2ee_create_bundle(); dcm_e2ee_free_bundle(); dcm_e2ee_bundle_h

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

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation