Tizen Native API
7.0
|
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:
enum dcm_error_e |
Enumeration for DCM error values.
- Since :
- 5.0
- Enumerator:
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