/*
* ks.h
* ----
* Keystore, generic parts anyway. This is internal within libhal.
*
* Copyright (c) 2015-2017, NORDUnet A/S All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are
* met:
* - Redistributions of source code must retain the above copyright notice,
* this list of conditions and the following disclaimer.
*
* - Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
*
* - Neither the name of the NORDUnet nor the names of its contributors may
* be used to endorse or promote products derived from this software
* without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
* IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
* TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
* PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
* HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
* TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
* PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
* LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
#ifndef _KS_H_
#define _KS_H_
#include "hal.h"
#include "hal_internal.h"
/*
* Size of a keystore "block".
*
* This must be an integer multiple of the flash subsector size, among
* other reasons because that's the minimum erasable unit.
*/
#ifndef HAL_KS_BLOCK_SIZE
#define HAL_KS_BLOCK_SIZE (4096 * 2)
#endif
/*
* PIN block gets the all-zeros UUID, which will never be returned by
* the UUID generation code (by definition -- it's not a version 4 UUID).
*/
const hal_uuid_t hal_ks_pin_uuid;
/*
* Known block states.
*
* C does not guarantee any particular representation for enums, so
* including enums directly in the block header isn't safe. Instead,
* we use an access method which casts when reading from the header.
* Writing to the header isn't a problem, because C does guarantee
* that enum is compatible with *some* integer type, it just doesn't
* specify which one.
*/
typedef enum {
HAL_KS_BLOCK_TYPE_ERASED = 0xFF, /* Pristine erased block (candidate for reuse) */
HAL_KS_BLOCK_TYPE_ZEROED = 0x00, /* Zeroed block (recently used) */
HAL_KS_BLOCK_TYPE_KEY = 0x55, /* Block contains key material */
HAL_KS_BLOCK_TYPE_PIN = 0xAA, /* Block contains PINs */
HAL_KS_BLOCK_TYPE_UNKNOWN = -1, /* Internal code for "I have no clue what this is" */
} hal_ks_block_type_t;
/*
* Block status.
*/
typedef enum {
HAL_KS_BLOCK_STATUS_LIVE = 0x66, /* This is a live block */
HAL_KS_BLOCK_STATUS_TOMBSTONE = 0x44, /* This is a tombstone left behind during an update */
HAL_KS_BLOCK_STATUS_UNKNOWN = -1, /* Internal code for "I have no clue what this is" */
} hal_ks_block_status_t;
/*
* Common header for all keystore block types. A few of these fields
* are deliberately omitted from the CRC.
*
* The legacy_1 and legacy_2 fields were used in the more complex
* "chunked" layout used in an earlier iteration of this keystore
* design, which proved more complex than it was worth. At the
* moment, the only thing we do with these fields is include them in
* the CRC and check them for allowed values, to avoid gratuitously
* breaking backwards compatability with the earlier design.
*/
typedef struct {
uint8_t block_type;
uint8_t block_status;
uint8_t legacy_1;
uint8_t legacy_2;
hal_crc32_t crc;
} hal_ks_block_header_t;
/*
* Key block. Tail end of "der" field (after der_len) used for attributes.
*/
typedef struct {
hal_ks_block_header_t header;
hal_uuid_t name;
hal_key_type_t type;
hal_curve_name_t curve;
hal_key_flags_t flags;
size_t der_len;
unsigned attributes_len;
uint8_t der[]; /* Must be last field -- C99 "flexible array member" */
} hal_ks_key_block_t;
#define SIZEOF_KS_KEY_BLOCK_DER \
(HAL_KS_BLOCK_SIZE - offsetof(hal_ks_key_block_t, der))
/*
* PIN block. Also includes space for backing up the KEK when
* HAL_MKM_FLASH_BACKUP_KLUDGE is enabled.
*/
typedef struct {
hal_ks_block_header_t header;
hal_ks_pin_t wheel_pin;
hal_ks_pin_t so_pin;
hal_ks_pin_t user_pin;
#if HAL_MKM_FLASH_BACKUP_KLUDGE
uint32_t kek_set;
uint8_t kek[KEK_LENGTH];
#endif
} hal_ks_pin_block_t;
#define FLASH_KEK_NOT_SET 0
#define FLASH_KEK_SET 0x33333333
/*
* One keystore block.
*/
typedef union {
uint8_t bytes[HAL_KS_BLOCK_SIZE];
hal_ks_block_header_t header;
hal_ks_key_block_t key;
hal_ks_pin_block_t pin;
} hal_ks_block_t;
/*
* In-memory cache.
*/
typedef struct {
unsigned blockno;
unsigned lru;
hal_ks_block_t block;
} hal_ks_cache_block_t;
/*
* Keystore object. hal_internal.h typedefs this to hal_ks_t.
*
* We expect this to be a static variable, but we expect the arrays in
* it to be allocated at runtime using hal_allocate_static_memory()
* because they can get kind of large.
*
* Driver-specific stuff is handled by a form of subclassing: the
* driver embeds the hal_ks_t structure at the head of whatever else
* it needs, and performs (controlled, type-safe) casts as needed.
*
* Core of this is the keystore index. This is intended to be usable
* by both memory-based and flash-based keystores. Some of the
* features aren't necessary for memory-based keystores, but should be
* harmless, and let us keep the drivers simple.
*
* General approach is multiple arrays, all but one of which are
* indexed by "block" numbers, where a block number might be a slot in
* yet another static array, the number of a flash sub-sector, or
* whatever is the appropriate unit for holding one keystore record.
*
* The index array only contains block numbers. This is a small data
* structure so that moving data within it is relatively cheap.
*
* The index array is divided into two portions: the index proper, and
* the free queue. The index proper is ordered according to the names
* (UUIDs) of the corresponding blocks; the free queue is a FIFO, to
* support a simplistic form of wear leveling in flash-based keystores.
*
* Key names are kept in a separate array, indexed by block number.
*
* The all-zeros UUID, which (by definition) cannot be a valid key
* UUID, is reserved for the (non-key) block used to stash PINs and
* other small data which aren't really part of the keystore proper
* but are kept with it because the keystore is the flash we have.
*
* Note that this API deliberately says nothing about how the keys
* themselves are stored, that's up to the keystore driver.
*/
typedef struct hal_ks_driver hal_ks_driver_t;
struct hal_ks {
const hal_ks_driver_t *driver;/* Must be first */
unsigned size; /* Blocks in keystore */
unsigned used; /* How many blocks are in use */
uint16_t *index; /* Index/freelist array */
hal_uuid_t *names; /* Keyname array */
unsigned cache_lru; /* Cache LRU counter */
unsigned cache_size; /* Size (how many blocks) in cache */
hal_ks_cache_block_t *cache; /* Cache */
};
/*
* Keystore driver.
*/
struct hal_ks_driver {
hal_error_t (*init) (hal_ks_t *ks, const int alloc);
hal_error_t (*read) (hal_ks_t *ks, const unsigned blockno, hal_ks_block_t *block);
hal_error_t (*write) (hal_ks_t *ks, const unsigned blockno, hal_ks_block_t *block);
hal_error_t (*deprecate) (hal_ks_t *ks, const unsigned blockno);
hal_error_t (*zero) (hal_ks_t *ks, const unsigned blockno);
hal_error_t (*erase) (hal_ks_t *ks, const unsigned blockno);
hal_error_t (*erase_maybe) (hal_ks_t *ks, const unsigned blockno);
hal_error_t (*set_owner) (hal_ks_t *ks, const unsigned blockno,
const hal_client_handle_t client, const hal_session_handle_t session);
hal_error_t (*test_owner) (hal_ks_t *ks, const unsigned blockno,
const hal_client_handle_t client, const hal_session_handle_t session);
hal_error_t (*copy_owner) (hal_ks_t *ks, const unsigned source, const unsigned target);
hal_error_t (*logout) (hal_ks_t *ks, const hal_client_handle_t client);
};
/*
* Wrappers around keystore driver methods.
*
* hal_ks_init() and hal_ks_logout() are missing here because we
* expose them to the rest of libhal.
*/
static inline hal_error_t hal_ks_block_read(hal_ks_t *ks, const unsigned blockno, hal_ks_block_t *block)
{
return
ks == NULL || ks->driver == NULL ? HAL_ERROR_BAD_ARGUMENTS :
ks->driver->read == NULL ? HAL_ERROR_NOT_IMPLEMENTED :
ks->driver->read(ks, blockno, block);
}
static inline hal_error_t hal_ks_block_write(hal_ks_t *ks, const unsigned blockno, hal_ks_block_t *block)
{
return
ks == NULL || ks->driver == NULL ? HAL_ERROR_BAD_ARGUMENTS :
ks->driver->write == NULL ? HAL_ERROR_NOT_IMPLEMENTED :
ks->driver->write(ks, blockno, block);
}
static inline hal_error_t hal_ks_block_deprecate(hal_ks_t *ks, const unsigned blockno)
{
return
ks == NULL || ks->driver == NULL ? HAL_ERROR_BAD_ARGUMENTS :
ks->driver->deprecate == NULL ? HAL_ERROR_NOT_IMPLEMENTED :
ks->driver->deprecate(ks, blockno);
}
static inline hal_error_t hal_ks_block_zero(hal_ks_t *ks, const unsigned blockno)
{
return
ks == NULL || ks->driver == NULL ? HAL_ERROR_BAD_ARGUMENTS :
ks->driver->zero == NULL ? HAL_ERROR_NOT_IMPLEMENTED :
ks->driver->zero(ks, blockno);
}
static inline hal_error_t hal_ks_block_erase(hal_ks_t *ks, const unsigned blockno)
{
return
ks == NULL || ks->driver == NULL ? HAL_ERROR_BAD_ARGUMENTS :
ks->driver->erase == NULL ? HAL_ERROR_NOT_IMPLEMENTED :
ks->driver->erase(ks, blockno);
}
static inline hal_error_t hal_ks_block_erase_maybe(hal_ks_t *ks, const unsigned blockno)
{
return
ks == NULL || ks->driver == NULL ? HAL_ERROR_BAD_ARGUMENTS :
ks->driver->erase_maybe == NULL ? HAL_ERROR_NOT_IMPLEMENTED :
ks->driver->erase_maybe(ks, blockno);
}
static inline hal_error_t hal_ks_block_set_owner(hal_ks_t *ks,
const unsigned blockno,
const hal_client_handle_t client,
const hal_session_handle_t session)
{
return
ks == NULL || ks->driver == NULL ? HAL_ERROR_BAD_ARGUMENTS :
ks->driver->set_owner == NULL ? HAL_ERROR_NOT_IMPLEMENTED :
ks->driver->set_owner(ks, blockno, client, session);
}
static inline hal_error_t hal_ks_block_test_owner(hal_ks_t *ks,
const unsigned blockno,
const hal_client_handle_t client,
const hal_session_handle_t session)
{
return
ks == NULL || ks->driver == NULL ? HAL_ERROR_BAD_ARGUMENTS :
ks->driver->test_owner == NULL ? HAL_ERROR_NOT_IMPLEMENTED :
ks->driver->test_owner(ks, blockno, client, session);
}
static inline hal_error_t hal_ks_block_copy_owner(hal_ks_t *ks,
const unsigned source,
const unsigned target)
{
return
ks == NULL || ks->driver == NULL ? HAL_ERROR_BAD_ARGUMENTS :
ks->driver->copy_owner == NULL ? HAL_ERROR_NOT_IMPLEMENTED :
ks->driver->copy_owner(ks, source, target);
}
/*
* Type safe casts.
*/
static inline hal_ks_block_type_t hal_ks_block_get_type(const hal_ks_block_t * const block)
{
return block == NULL ? HAL_KS_BLOCK_TYPE_UNKNOWN :
(hal_ks_block_type_t) block->header.block_type;
}
static inline hal_ks_block_status_t hal_ks_block_get_status(const hal_ks_block_t * const block)
{
return block == NULL ? HAL_KS_BLOCK_STATUS_UNKNOWN :
(hal_ks_block_status_t) block->header.block_status;
}
/*
* Keystore utilities. Some or all of these may end up static within ks.c.
*/
extern hal_error_t hal_ks_alloc_common(hal_ks_t *ks,
const unsigned ks_blocks,
const unsigned cache_blocks,
void **extra,
const size_t extra_len);
extern hal_error_t hal_ks_init_common(hal_ks_t *ks);
extern hal_crc32_t hal_ks_block_calculate_crc(const hal_ks_block_t * const block);
extern hal_error_t hal_ks_index_heapsort(hal_ks_t *ks);
extern hal_error_t hal_ks_index_find(hal_ks_t *ks,
const hal_uuid_t * const name,
unsigned *blockno,
int *hint);
extern hal_error_t hal_ks_index_add(hal_ks_t *ks,
const hal_uuid_t * const name,
unsigned *blockno,
int *hint);
extern hal_error_t hal_ks_index_delete(hal_ks_t *ks,
const hal_uuid_t * const name,
unsigned *blockno,
int *hint);
extern hal_error_t hal_ks_index_replace(hal_ks_t *ks,
const hal_uuid_t * const name,
unsigned *blockno,
int *hint);
extern hal_error_t hal_ks_index_fsck(hal_ks_t *ks);
extern const size_t hal_ks_attribute_header_size;
extern hal_error_t hal_ks_attribute_scan(const uint8_t * const bytes,
const size_t bytes_len,
hal_pkey_attribute_t *attributes,
const unsigned attributes_len,
size_t *total_len);
extern hal_error_t hal_ks_attribute_delete(uint8_t *bytes,
const size_t bytes_len,
hal_pkey_attribute_t *attributes,
unsigned *attributes_len,
size_t *total_len,
const uint32_t type);
extern hal_error_t hal_ks_attribute_insert(uint8_t *bytes, const size_t bytes_len,
hal_pkey_attribute_t *attributes,
unsigned *attributes_len,
size_t *total_len,
const uint32_t type,
const uint8_t * const value,
const size_t value_len);
extern hal_ks_block_t *hal_ks_cache_pick_lru(hal_ks_t *ks);
extern hal_ks_block_t *hal_ks_cache_find_block(const hal_ks_t * const ks,
const unsigned blockno);
extern void hal_ks_cache_mark_used(hal_ks_t *ks,
const hal_ks_block_t * const block,
const unsigned blockno);
extern void hal_ks_cache_release(hal_ks_t *ks,
const hal_ks_block_t * const block);
extern hal_error_t hal_ks_block_read_cached(hal_ks_t *ks,
const unsigned blockno,
hal_ks_block_t **block);
extern hal_error_t hal_ks_block_update(hal_ks_t *ks,
const unsigned b1,
hal_ks_block_t *block,
const hal_uuid_t * const uuid,
int *hint);
extern hal_error_t hal_ks_available(hal_ks_t *ks, size_t *count);
#endif /* _KS_H_ */
/*
* Local variables:
* indent-tabs-mode: nil
* End:
*/
