diff options
Diffstat (limited to 'hal_internal.h')
| -rw-r--r-- | hal_internal.h | 397 |
1 files changed, 397 insertions, 0 deletions
diff --git a/hal_internal.h b/hal_internal.h new file mode 100644 index 0000000..8c0b0bc --- /dev/null +++ b/hal_internal.h @@ -0,0 +1,397 @@ +/* + * hal_internal.h + * -------------- + * Internal API declarations for libhal. + * + * Authors: Rob Austein, Paul Selkirk + * Copyright (c) 2015, 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 _HAL_INTERNAL_H_ +#define _HAL_INTERNAL_H_ + +#include "hal.h" +#include "verilog_constants.h" + +/* + * Longest hash block and digest we support at the moment. + */ + +#define HAL_MAX_HASH_BLOCK_LENGTH SHA512_BLOCK_LEN +#define HAL_MAX_HASH_DIGEST_LENGTH SHA512_DIGEST_LEN + +/* + * Everything in this file is part of the internal API, that is, + * subject to change without notice. Nothing outside of libhal itself + * should be looking at this file. + */ + +/* + * Dispatch structures for RPC implementation. + * + * The breakdown of which functions go into which dispatch vectors is + * based entirely on pesky details like making sure that the right + * functions get linked in the right cases, and should not be + * construed as making any particular sense in any larger context. + * + * In theory eventually we might want a fully general mechanism to + * allow us to dispatch arbitrary groups of functions either locally + * or remotely on a per-user basis. In practice, we probably want to + * run everything on the HSM except for hashing and digesting, so just + * code for that case initially while leaving the design open for a + * more general mechanism later if warranted. + * + * So we have three cases: + * + * - We're the HSM, so we do everything locally (ie, we run the RPC + * server functions. + * + * - We're the host, so we do everything remotely (ie, we do + * everything using the client-side RPC calls. + * + * - We're the host but are doing hashing locally, so we do a mix. + * This is slightly more complicated than it might at first appear, + * because we must handle the case of one of the pkey functions + * taking a hash context instead of a literal hash value, in which + * case we have to extract the hash value from the context and + * supply it to the pkey RPC client code as a literal value. + */ + +typedef struct { + + hal_error_t (*set_pin)(const hal_client_handle_t client, + const hal_user_t user, + const char * const newpin, const size_t newpin_len); + + hal_error_t (*login)(const hal_client_handle_t client, + const hal_user_t user, + const char * const newpin, const size_t newpin_len); + + hal_error_t (*logout)(const hal_client_handle_t client); + + hal_error_t (*logout_all)(void); + + hal_error_t (*is_logged_in)(const hal_client_handle_t client, + const hal_user_t user); + + hal_error_t (*get_random)(void *buffer, const size_t length); + + hal_error_t (*get_version)(uint32_t *version); + +} hal_rpc_misc_dispatch_t; + + +typedef struct { + + hal_error_t (*get_digest_length)(const hal_digest_algorithm_t alg, size_t *length); + + hal_error_t (*get_digest_algorithm_id)(const hal_digest_algorithm_t alg, + uint8_t *id, size_t *len, const size_t len_max); + + hal_error_t (*get_algorithm)(const hal_hash_handle_t hash, hal_digest_algorithm_t *alg); + + hal_error_t (*initialize)(const hal_client_handle_t client, + const hal_session_handle_t session, + hal_hash_handle_t *hash, + const hal_digest_algorithm_t alg, + const uint8_t * const key, const size_t key_length); + + hal_error_t (*update)(const hal_hash_handle_t hash, + const uint8_t * data, const size_t length); + + hal_error_t (*finalize)(const hal_hash_handle_t hash, + uint8_t *digest, const size_t length); +} hal_rpc_hash_dispatch_t; + + +typedef struct { + + hal_error_t (*load)(const hal_client_handle_t client, + const hal_session_handle_t session, + hal_pkey_handle_t *pkey, + const hal_key_type_t type, + const hal_curve_name_t curve, + const uint8_t * const name, const size_t name_len, + const uint8_t * const der, const size_t der_len, + const hal_key_flags_t flags); + + hal_error_t (*find)(const hal_client_handle_t client, + const hal_session_handle_t session, + hal_pkey_handle_t *pkey, + const hal_key_type_t type, + const uint8_t * const name, const size_t name_len); + + hal_error_t (*generate_rsa)(const hal_client_handle_t client, + const hal_session_handle_t session, + hal_pkey_handle_t *pkey, + const uint8_t * const name, const size_t name_len, + const unsigned key_length, + const uint8_t * const public_exponent, const size_t public_exponent_len, + const hal_key_flags_t flags); + + hal_error_t (*generate_ec)(const hal_client_handle_t client, + const hal_session_handle_t session, + hal_pkey_handle_t *pkey, + const uint8_t * const name, const size_t name_len, + const hal_curve_name_t curve, + const hal_key_flags_t flags); + + hal_error_t (*close)(const hal_pkey_handle_t pkey); + + hal_error_t (*delete)(const hal_pkey_handle_t pkey); + + hal_error_t (*get_key_type)(const hal_pkey_handle_t pkey, + hal_key_type_t *key_type); + + hal_error_t (*get_key_flags)(const hal_pkey_handle_t pkey, + hal_key_flags_t *flags); + + size_t (*get_public_key_len)(const hal_pkey_handle_t pkey); + + hal_error_t (*get_public_key)(const hal_pkey_handle_t pkey, + uint8_t *der, size_t *der_len, const size_t der_max); + + hal_error_t (*sign)(const hal_session_handle_t session, + const hal_pkey_handle_t pkey, + const hal_hash_handle_t hash, + const uint8_t * const input, const size_t input_len, + uint8_t * signature, size_t *signature_len, const size_t signature_max); + + hal_error_t (*verify)(const hal_session_handle_t session, + const hal_pkey_handle_t pkey, + const hal_hash_handle_t hash, + const uint8_t * const input, const size_t input_len, + const uint8_t * const signature, const size_t signature_len); + + hal_error_t (*list)(hal_pkey_info_t *result, + unsigned *result_len, + const unsigned result_max); + +} hal_rpc_pkey_dispatch_t; + + +extern const hal_rpc_misc_dispatch_t hal_rpc_local_misc_dispatch, hal_rpc_remote_misc_dispatch, *hal_rpc_misc_dispatch; +extern const hal_rpc_hash_dispatch_t hal_rpc_local_hash_dispatch, hal_rpc_remote_hash_dispatch, *hal_rpc_hash_dispatch; +extern const hal_rpc_pkey_dispatch_t hal_rpc_local_pkey_dispatch, hal_rpc_remote_pkey_dispatch, hal_rpc_mixed_pkey_dispatch, *hal_rpc_pkey_dispatch; + +/* + * Keystore API. + * + * The original design for this subsystem used two separate tables, + * one for RSA keys, one for EC keys, because the RSA keys are so much + * larger than the EC keys. This led to unnecessarily complex and + * duplicated code, so for now we treat all keys the same, and waste + * the unneded space in the case of EC keys. + * + * Sizes for ASN.1-encoded keys, this may not be exact due to ASN.1 + * INTEGER encoding rules but should be good enough for buffer sizing: + * + * 2048-bit RSA: 1194 bytes + * 4096-bit RSA: 2351 bytes + * 8192-bit RSA: 4655 bytes + * EC P-256: 121 bytes + * EC P-384: 167 bytes + * EC P-521: 223 bytes + * + * Plus we need a bit of AES-keywrap overhead, since we're storing the + * wrapped form (see hal_aes_keywrap_cyphertext_length()). + * + * We also need to store PINs somewhere, so they go into the keystore + * data structure even though they're not keys. Like keys, they're + * stored in a relatively safe form (PBKDF2), so while we would prefer + * to keep them private, they don't require tamper-protected RAM. + */ + +#define HAL_KS_WRAPPED_KEYSIZE ((4655 + 15) & ~7) + +#ifndef HAL_STATIC_PKEY_STATE_BLOCKS +#define HAL_STATIC_PKEY_STATE_BLOCKS 0 +#endif + +typedef struct { + hal_key_type_t type; + hal_curve_name_t curve; + hal_key_flags_t flags; + uint8_t name[HAL_RPC_PKEY_NAME_MAX]; + size_t name_len; + uint8_t der[HAL_KS_WRAPPED_KEYSIZE]; + size_t der_len; + uint8_t in_use; +} hal_ks_key_t; + +#ifndef HAL_PIN_SALT_LENGTH +#define HAL_PIN_SALT_LENGTH 16 +#endif + +typedef struct { + uint32_t iterations; + uint8_t pin[HAL_MAX_HASH_DIGEST_LENGTH]; + uint8_t salt[HAL_PIN_SALT_LENGTH]; +} hal_ks_pin_t; + +typedef struct { + +#if HAL_STATIC_PKEY_STATE_BLOCKS > 0 + hal_ks_key_t keys[HAL_STATIC_PKEY_STATE_BLOCKS]; +#endif + + hal_ks_pin_t wheel_pin; + hal_ks_pin_t so_pin; + hal_ks_pin_t user_pin; + +} hal_ks_keydb_t; + +/* + * Internal functions within the keystore implementation. Think of + * these as concrete methods for the keystore API subclassed onto + * various storage technologies. + */ + +extern const hal_ks_keydb_t *hal_ks_get_keydb(void); + +extern hal_error_t hal_ks_set_keydb(const hal_ks_key_t * const key, + const int loc); + +extern hal_error_t hal_ks_del_keydb(const int loc); + +extern hal_error_t hal_ks_get_kek(uint8_t *kek, + size_t *kek_len, + const size_t kek_max); + +/* + * Keystore API for use by the pkey implementation. + * + * In an attempt to emulate what current theory says will eventually + * be the behavior of the underlying Cryptech Verilog "hardware", + * these functions automatically apply the AES keywrap transformations. + * + * Unclear whether these should also call the ASN.1 encode/decode + * functions. For the moment, the answer is no, but we may need to + * revisit this as the underlying Verilog API evolves. + */ + +extern hal_error_t hal_ks_store(const hal_key_type_t type, + const hal_curve_name_t curve, + const hal_key_flags_t flags, + const uint8_t * const name, const size_t name_len, + const uint8_t * const der, const size_t der_len, + int *hint); + +extern hal_error_t hal_ks_exists(const hal_key_type_t type, + const uint8_t * const name, const size_t name_len, + int *hint); + +extern hal_error_t hal_ks_fetch(const hal_key_type_t type, + const uint8_t * const name, const size_t name_len, + hal_curve_name_t *curve, + hal_key_flags_t *flags, + uint8_t *der, size_t *der_len, const size_t der_max, + int *hint); + +extern hal_error_t hal_ks_delete(const hal_key_type_t type, + const uint8_t * const name, const size_t name_len, + int *hint); + +extern hal_error_t hal_ks_list(hal_pkey_info_t *result, + unsigned *result_len, + const unsigned result_max); + +extern hal_error_t hal_ks_get_pin(const hal_user_t user, + const hal_ks_pin_t **pin); + +extern hal_error_t hal_ks_set_pin(const hal_user_t user, + const hal_ks_pin_t * const pin); + +/* + * RPC lowest-level send and receive routines. These are blocking, and + * transport-specific (sockets, USB). + */ + +extern hal_error_t hal_rpc_send(const uint8_t * const buf, const size_t len); +extern hal_error_t hal_rpc_recv(uint8_t * const buf, size_t * const len); + +extern hal_error_t hal_rpc_sendto(const uint8_t * const buf, const size_t len, void *opaque); +extern hal_error_t hal_rpc_recvfrom(uint8_t * const buf, size_t * const len, void **opaque); + +extern hal_error_t hal_rpc_client_transport_init(void); +extern hal_error_t hal_rpc_client_transport_close(void); + +extern hal_error_t hal_rpc_server_transport_init(void); +extern hal_error_t hal_rpc_server_transport_close(void); + + +/* + * RPC function numbers + */ + +typedef enum { + RPC_FUNC_GET_VERSION = 0, + RPC_FUNC_GET_RANDOM, + RPC_FUNC_SET_PIN, + RPC_FUNC_LOGIN, + RPC_FUNC_LOGOUT, + RPC_FUNC_LOGOUT_ALL, + RPC_FUNC_IS_LOGGED_IN, + RPC_FUNC_HASH_GET_DIGEST_LEN, + RPC_FUNC_HASH_GET_DIGEST_ALGORITHM_ID, + RPC_FUNC_HASH_GET_ALGORITHM, + RPC_FUNC_HASH_INITIALIZE, + RPC_FUNC_HASH_UPDATE, + RPC_FUNC_HASH_FINALIZE, + RPC_FUNC_PKEY_LOAD, + RPC_FUNC_PKEY_FIND, + RPC_FUNC_PKEY_GENERATE_RSA, + RPC_FUNC_PKEY_GENERATE_EC, + RPC_FUNC_PKEY_CLOSE, + RPC_FUNC_PKEY_DELETE, + RPC_FUNC_PKEY_GET_KEY_TYPE, + RPC_FUNC_PKEY_GET_KEY_FLAGS, + RPC_FUNC_PKEY_GET_PUBLIC_KEY_LEN, + RPC_FUNC_PKEY_GET_PUBLIC_KEY, + RPC_FUNC_PKEY_REMOTE_SIGN, + RPC_FUNC_PKEY_REMOTE_VERIFY, + RPC_FUNC_PKEY_LIST, +} rpc_func_num_t; + +#define RPC_VERSION 0x00010000 /* 0.1.0.0 */ + +/* RPC client locality. These have to be defines rather than an enum, + * because they're handled by the preprocessor. + */ +#define RPC_CLIENT_LOCAL 0 +#define RPC_CLIENT_REMOTE 1 +#define RPC_CLIENT_MIXED 2 + +#endif /* _HAL_INTERNAL_H_ */ + +/* + * Local variables: + * indent-tabs-mode: nil + * End: + */ |