OpenKODE Core extension: KD_ACR_secure

OpenKODE Core extension: KD_ACR_secure_storage

Name	ACR_secure_storage
Name strings	KD_ACR_secure_storage
Contributors	Hitoshi Ooyama, Acrodea
Contacts	Acrodea
Status	Draft
Version	Version 1, 2011-02-18
Number	TBD
Dependencies	Requires OpenKODE Core 1.0 or later. This extension is written based on the wording of the OpenKODE Core 1.0 specification.

1. Overview

This extension module enables to read in data in a protected area. Data in the protected area is encrypted by a key uniquely generated by device so that the data can't be transferred to any other devices. In addition, a hush value of a protected file is saved in a device, which prevents a previously backed-up file from operations such as overwriting, data restoration, etc. (Exceptionally, it is possible to overwrite a file after back-up as long as no changes have been made in the file.)

2. Header file

When this extension is present, its facilities are accessed by including its header file:

#include <KD/ACR_secure_storage.h>

3. New function

3.1. kdSecureStorageSetValueACR

Write in data to a protected area.

Synopsis

`KDint kdSecureStorageSetValueACR(`	const KDchar *`key`,
	const KDchar *`data`,
	KDsize `size)`;

Description

Write in a data to a protected area. It is possible to write in up to 1MByte by data, and memory of a specified volume is saved by atomic operation.

Parameters

key: Specify a pointer to a key (equivalent to a filename) of data to be saved.
data: Specify a pointer of data to be save in a protected area.
size: Specify a length of an argument, data.

Return value

Upon the normal termination, a size of a written in data is returned. Upon the abnormal termination, -1 is returned. For details of the error, refer to kdGetError.

Error codes

KD_EIO: An encryption error. Or, when the data is being written in a disk, it will occur if a low-level I/O error happens.
KD_EINVAL: key and data are NULL, size is over the limit value, or key is blank.

3.2. kdSecureStorageGetValueACR

Read in data from the protected area.

Synopsis

`KDint kdSecureStorageGetValueACR(`	const KDchar *`key`,
	KDchar *`buf`,
	KDsize `maxSize)`;

Description

Read in data from the protected area. Read in all the written data.

Parameters

key: Specify a pointer to a key (equivalent to a filename) of data to be read in.
buf: Specify a pointer to an area which stores the data read in from the protected area.
maxSize: Specify a data size secured for data storage area (buf).

Return value

Upon the normal termination, the size of read-in data is returned. If a key is not present, 0 is returned as the size of read-in data. Upon the abnormal termination, -1 is returned. For details of the error, refer to kdGetError.

Error codes

KD_EIO: An encryption error. Or, when the data is being written in a disk, it will occur if a low-level I/O error happens.
KD_EINVAL: key and buf are NULL, maxsize is over the limit value, or key is blank.

4. Revision history

4.1. Version 1, 2011-02-18

Initial version.