linux/drivers/mxc/security/dryice.h File Reference

Definition of DryIce API. More...

Defines

#define SCC_KEY_LEN   168
#define MAX_KEY_LEN   256
DryIce Function Flags

#define DI_FUNC_FLAG_ASYNC   0x01
#define DI_FUNC_FLAG_READ_LOCK   0x02
#define DI_FUNC_FLAG_WRITE_LOCK   0x04
#define DI_FUNC_FLAG_HARD_LOCK   0x08
#define DI_FUNC_FLAG_WORD_KEY   0x10
DryIce Tamper Events

#define DI_TAMPER_EVENT_WTD   (1 << 23)
#define DI_TAMPER_EVENT_ETBD   (1 << 22)
#define DI_TAMPER_EVENT_ETAD   (1 << 21)
#define DI_TAMPER_EVENT_EBD   (1 << 20)
#define DI_TAMPER_EVENT_SAD   (1 << 19)
#define DI_TAMPER_EVENT_TTD   (1 << 18)
#define DI_TAMPER_EVENT_CTD   (1 << 17)
#define DI_TAMPER_EVENT_VTD   (1 << 16)
#define DI_TAMPER_EVENT_MCO   (1 << 3)
#define DI_TAMPER_EVENT_TCO   (1 << 2)

Typedefs

typedef enum di_key di_key_t
typedef enum dryice_return di_return_t

Enumerations

enum  di_key {
  DI_KEY_FK,
  DI_KEY_PK,
  DI_KEY_RK,
  DI_KEY_FPK,
  DI_KEY_FRK
}
enum  dryice_return {
  DI_SUCCESS = 0,
  DI_ERR_BUSY,
  DI_ERR_STATE,
  DI_ERR_INUSE,
  DI_ERR_UNSET,
  DI_ERR_WRITE,
  DI_ERR_INVAL,
  DI_ERR_FAIL,
  DI_ERR_HLOCK,
  DI_ERR_SLOCK,
  DI_ERR_NOMEM
}

Functions

di_return_t dryice_set_programmed_key (const void *key_data, int key_bits, int flags)
di_return_t dryice_get_programmed_key (uint8_t *key_data, int key_bits)
di_return_t dryice_release_programmed_key (void)
di_return_t dryice_set_random_key (int flags)
di_return_t dryice_select_key (di_key_t key, int flags)
di_return_t dryice_check_key (di_key_t *key)
di_return_t dryice_release_key_selection (void)
di_return_t dryice_get_tamper_event (uint32_t *events, uint32_t *timestamp, int flags)
di_return_t dryice_register_callback (void(*func)(di_return_t rc, unsigned long cookie), unsigned long cookie)

Detailed Description

Definition of DryIce API.


Define Documentation

#define DI_FUNC_FLAG_ASYNC   0x01
#define DI_FUNC_FLAG_HARD_LOCK   0x08

locks will be hard (default soft)

Referenced by dryice_select_key(), dryice_set_programmed_key(), and dryice_set_random_key().

#define DI_FUNC_FLAG_READ_LOCK   0x02

set read lock for this resource

Referenced by dryice_set_programmed_key().

#define DI_FUNC_FLAG_WORD_KEY   0x10

key provided as 32-bit words

Referenced by dryice_set_programmed_key().

#define DI_FUNC_FLAG_WRITE_LOCK   0x04

set write lock for resource

Referenced by dryice_select_key(), dryice_set_programmed_key(), and dryice_set_random_key().

#define DI_TAMPER_EVENT_CTD   (1 << 17)

clock tampering det

#define DI_TAMPER_EVENT_EBD   (1 << 20)

external boot detected

#define DI_TAMPER_EVENT_ETAD   (1 << 21)

ext tampering det: input A

#define DI_TAMPER_EVENT_ETBD   (1 << 22)

ext tampering det: input B

#define DI_TAMPER_EVENT_MCO   (1 << 3)

monotonic counter overflow

#define DI_TAMPER_EVENT_SAD   (1 << 19)

security alarm detected

#define DI_TAMPER_EVENT_TCO   (1 << 2)

time counter overflow

#define DI_TAMPER_EVENT_TTD   (1 << 18)

temperature tampering det

#define DI_TAMPER_EVENT_VTD   (1 << 16)

voltage tampering det

#define DI_TAMPER_EVENT_WTD   (1 << 23)

wire-mesh tampering det

#define MAX_KEY_LEN   256

This defines the maximum key length (in bits)

Referenced by dryice_get_programmed_key(), and dryice_set_programmed_key().

#define SCC_KEY_LEN   168

This defines the SCC key length (in bits)


Typedef Documentation

typedef enum di_key di_key_t

DryIce Key Sources

typedef enum dryice_return di_return_t

DryIce Error Codes


Enumeration Type Documentation

enum di_key

DryIce Key Sources

Enumerator:
DI_KEY_FK 

the fused (IIM) key

DI_KEY_PK 

the programmed key

DI_KEY_RK 

the random key

DI_KEY_FPK 

the programmed key XORed with the fused key

DI_KEY_FRK 

the random key XORed with the fused key

DryIce Error Codes

Enumerator:
DI_SUCCESS 

operation was successful

DI_ERR_BUSY 

device or resource busy

DI_ERR_STATE 

dryice is in incompatible state

DI_ERR_INUSE 

resource is already in use

DI_ERR_UNSET 

resource has not been initialized

DI_ERR_WRITE 

error occurred during register write

DI_ERR_INVAL 

invalid argument

DI_ERR_FAIL 

operation failed

DI_ERR_HLOCK 

resource is hard locked

DI_ERR_SLOCK 

resource is soft locked

DI_ERR_NOMEM 

out of memory


Function Documentation

di_return_t dryice_check_key ( di_key_t key  ) 

Check which key will be used in the SCC. This is needed because in some DryIce states, the Key Select Register is overridden by a default value (the Fused/IIM key).

Parameters:
[out] key The source of the key that is currently selected for use by the SCC. This may be different from the key specified by the dryice_select_key function (See di_key_t). This value is set even if an error code (except for BUSY) is returned.
Returns:
Returns SUCCESS (0), BUSY if DryIce is busy, STATE if DryIce is in the wrong state, INVAL on invalid arguments, or UNSET if no key has been selected (See di_return_t).

References DI_ERR_BUSY, DI_ERR_INVAL, DI_ERR_STATE, DI_ERR_UNSET, DI_KEY_FK, DI_KEY_FPK, DI_KEY_FRK, DI_KEY_PK, and DI_KEY_RK.

di_return_t dryice_get_programmed_key ( uint8_t *  key_data,
int  key_bits 
)

Read the Programmed Key registers and write the contents into a buffer.

Parameters:
[out] key_data A byte pointer to where the key data will be written, with the most significant byte being written first.
[in] key_bits The number of bits of the key to be retrieved. This must be a multiple of 8 and within the range of 0 and MAX_KEY_LEN.
Returns:
Returns SUCCESS (0), BUSY if DryIce is busy, INVAL on invalid arguments, UNSET if key has not been programmed, STATE if DryIce is in the wrong state, and HLOCK or SLOCK if the key registers are locked for reading (See di_return_t).

References DI_ERR_BUSY, DI_ERR_HLOCK, DI_ERR_INVAL, DI_ERR_SLOCK, DI_ERR_STATE, DI_ERR_UNSET, and MAX_KEY_LEN.

di_return_t dryice_get_tamper_event ( uint32_t *  events,
uint32_t *  timestamp,
int  flags 
)

Returns tamper-detection status bits. Also an optional timestamp when DryIce is in the Non-valid state. If DryIce is not in Failure or Non-valid state, this interface returns a failure code.

Parameters:
[out] events This is a bit-wise OR of the following events: WTD (Wire Mesh), ETBD (External Tamper B), ETAD (External Tamper A), EBD (External Boot), SAD (Security Alarm), TTD (Temperature Tamper), CTD (Clock Tamper), VTD (Voltage Tamper), MCO (Monolithic Counter Overflow), and TCO (Time Counter Overflow).
[out] timestamp This is the value of the time counter in seconds when the tamper occurred. A timestamp will not be returned if a NULL pointer is specified. If DryIce is not in the Non-valid state the time cannot be read, so a timestamp of 0 will be returned.
[in] flags This is a bit-wise OR of the flags to be passed to the function. Flags is ignored currently by this function.
Returns:
Returns SUCCESS (0), BUSY if DryIce is busy, and INVAL on invalid arguments (See di_return_t).

References DI_ERR_BUSY, DI_ERR_INVAL, and DI_ERR_STATE.

di_return_t dryice_register_callback ( void(*)(di_return_t rc, unsigned long cookie)  func,
unsigned long  cookie 
)

Provide a callback function to be called upon the completion of DryIce calls that are executed asynchronously.

Parameters:
[in] func This is a pointer to a function of type: void callback(di_return_t rc, unsigned long cookie) The return code of the async function is passed back in "rc" along with the cookie provided when registering the callback.
[in] cookie This is an "opaque" cookie of type unsigned long that is returned on subsequent callbacks. It may be of any value.
Returns:
Returns SUCCESS (0), or BUSY if DryIce is busy (See di_return_t).
di_return_t dryice_release_key_selection ( void   ) 

Allow the dryice_select_key interface to be used to set a new key selection in DryIce. Note that this interface does not overwrite the value in DryIce.

Returns:
Returns SUCCESS (0), BUSY if DryIce is busy, UNSET if the no selection has been made previously, and HLOCK or SLOCK if the selection register is locked (See di_return_t).

References DI_ERR_BUSY, DI_ERR_HLOCK, DI_ERR_SLOCK, and DI_ERR_UNSET.

di_return_t dryice_release_programmed_key ( void   ) 

Allow the set_programmed_key interface to be used to write a new Programmed Key to DryIce. Note that this interface does not overwrite the value in the Programmed Key registers.

Returns:
Returns SUCCESS (0), BUSY if DryIce is busy, UNSET if the key has not been previously set, and HLOCK or SLOCK if the key registers are locked for writing (See di_return_t).

References DI_ERR_BUSY, DI_ERR_HLOCK, DI_ERR_SLOCK, and DI_ERR_UNSET.

di_return_t dryice_select_key ( di_key_t  key,
int  flags 
)

Set the key selection in DryIce to determine the key used by an encryption module such as SCC. The selection is held until a call to the Release Selected Key interface is made, or until the appropriate HW reset if the LOCK flags are used.

Parameters:
[in] key The source of the key to be used by the SCC (See di_key_t).
[in] flags This is a bit-wise OR of the flags to be passed to the function. Flags can include: ASYNC, WRITE_LOCK, and HARD_LOCK.
Returns:
Returns SUCCESS (0), BUSY if DryIce is busy, INVAL on invalid arguments, INUSE if a selection has already been made, STATE if DryIce is in the wrong state, HLOCK or SLOCK if the selection register is locked, and WRITE if a write error occurs

References DI_ERR_BUSY, DI_ERR_HLOCK, DI_ERR_INUSE, DI_ERR_INVAL, DI_ERR_SLOCK, DI_ERR_STATE, DI_FUNC_FLAG_ASYNC, DI_FUNC_FLAG_HARD_LOCK, DI_FUNC_FLAG_WRITE_LOCK, DI_KEY_FK, DI_KEY_FPK, DI_KEY_FRK, DI_KEY_PK, and DI_KEY_RK.

di_return_t dryice_set_programmed_key ( const void *  key_data,
int  key_bits,
int  flags 
)

These functions define the DryIce API.

Write a given key to the Programmed Key registers in DryIce, and optionally lock the Programmed Key against either reading or further writing. The value is held until a call to the release_programmed_key interface is made, or until the appropriate HW reset if the write-lock flags are used. Unused key bits will be zeroed.

Parameters:
[in] key_data A pointer to the key data to be programmed, with the most significant byte or word first. This will be interpreted as a byte pointer unless the WORD_KEY flag is set, in which case it will be treated as a word pointer and the key data will be read a word at a time, starting with the MSW. When called asynchronously, the data pointed to by key_data must persist until the operation completes.
[in] key_bits The number of bits in the key to be stored. This must be a multiple of 8 and within the range of 0 and MAX_KEY_LEN.
[in] flags This is a bit-wise OR of the flags to be passed to the function. Flags can include: ASYNC, READ_LOCK, WRITE_LOCK, HARD_LOCK, and WORD_KEY.
Returns:
Returns SUCCESS (0), BUSY if DryIce is busy, INVAL on invalid arguments, INUSE if key has already been programmed, STATE if DryIce is in the wrong state, HLOCK or SLOCK if the key registers are locked for writing, and WRITE if a write error occurs (See di_return_t).

References DI_ERR_BUSY, DI_ERR_HLOCK, DI_ERR_INUSE, DI_ERR_INVAL, DI_ERR_SLOCK, DI_ERR_STATE, DI_FUNC_FLAG_ASYNC, DI_FUNC_FLAG_HARD_LOCK, DI_FUNC_FLAG_READ_LOCK, DI_FUNC_FLAG_WORD_KEY, DI_FUNC_FLAG_WRITE_LOCK, and MAX_KEY_LEN.

di_return_t dryice_set_random_key ( int  flags  ) 

Generate and load a new Random Key in DryIce, and optionally lock the Random Key against further change.

Parameters:
[in] flags This is a bit-wise OR of the flags to be passed to the function. Flags can include: ASYNC, READ_LOCK, WRITE_LOCK, and HARD_LOCK.
Returns:
Returns SUCCESS (0), BUSY if DryIce is busy, STATE if DryIce is in the wrong state, FAIL if the key gen failed, HLOCK or SLOCK if the key registers are locked, and WRITE if a write error occurs (See di_return_t).

References DI_ERR_BUSY, DI_ERR_HLOCK, DI_ERR_SLOCK, DI_ERR_STATE, DI_FUNC_FLAG_ASYNC, DI_FUNC_FLAG_HARD_LOCK, and DI_FUNC_FLAG_WRITE_LOCK.

footer
©  Freescale Semiconductor, Inc., 2007.  All rights reserved.
Freescale Confidential Proprietary
NDA Required
doxygen