diff options
Diffstat (limited to 'hal.h')
| -rw-r--r-- | hal.h | 356 |
1 files changed, 305 insertions, 51 deletions
@@ -4,7 +4,7 @@ * Memory map, access functions, and HAL for Cryptech cores. * * Authors: Joachim Strombergson, Paul Selkirk, Rob Austein - * Copyright (c) 2015, NORDUnet A/S All rights reserved. + * Copyright (c) 2015-2016, 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 @@ -36,15 +36,19 @@ #ifndef _HAL_H_ #define _HAL_H_ +#include <stdint.h> +#include <sys/types.h> +#include <stdlib.h> + /* * A handy macro from cryptlib. */ #ifndef bitsToBytes -#define bitsToBytes(x) (x / 8) +#define bitsToBytes(x) ((x) / 8) #endif /* - * Current name and version values. + * Current name and version values for crypto cores. * * Should these even be here? Dunno. * Should the versions be here even if the names should be? @@ -114,6 +118,17 @@ DEFINE_HAL_ERROR(HAL_ERROR_KEY_NOT_ON_CURVE, "EC key is not on its purported curve") \ DEFINE_HAL_ERROR(HAL_ERROR_INVALID_SIGNATURE, "Invalid signature") \ DEFINE_HAL_ERROR(HAL_ERROR_CORE_NOT_FOUND, "Requested core not found") \ + DEFINE_HAL_ERROR(HAL_ERROR_KEYSTORE_ACCESS, "Could not access keystore") \ + DEFINE_HAL_ERROR(HAL_ERROR_KEY_NOT_FOUND, "Key not found") \ + DEFINE_HAL_ERROR(HAL_ERROR_KEY_NAME_IN_USE, "Key name in use") \ + DEFINE_HAL_ERROR(HAL_ERROR_NO_KEY_SLOTS_AVAILABLE, "No key slots available") \ + DEFINE_HAL_ERROR(HAL_ERROR_PIN_INCORRECT, "PIN incorrect") \ + DEFINE_HAL_ERROR(HAL_ERROR_NO_CLIENT_SLOTS_AVAILABLE, "No client slots available") \ + DEFINE_HAL_ERROR(HAL_ERROR_FORBIDDEN, "Forbidden") \ + DEFINE_HAL_ERROR(HAL_ERROR_XDR_BUFFER_OVERFLOW, "XDR buffer overflow") \ + DEFINE_HAL_ERROR(HAL_ERROR_RPC_TRANSPORT, "RPC transport error") \ + DEFINE_HAL_ERROR(HAL_ERROR_RPC_PACKET_OVERFLOW, "RPC packet overflow") \ + DEFINE_HAL_ERROR(HAL_ERROR_RPC_BAD_FUNCTION, "Bad RPC function number") \ END_OF_HAL_ERROR_LIST /* Marker to forestall silly line continuation errors */ @@ -125,24 +140,21 @@ typedef enum { HAL_ERROR_LIST N_HAL_ERRORS } hal_error_t; #undef DEFINE_HAL_ERROR /* - * Public functions. + * Error translation. */ -#include <stdint.h> -#include <sys/types.h> +extern const char *hal_error_string(const hal_error_t err); /* - * Typedef to isolate code from our current choice of representation - * for a Cryptech bus address. + * Very low level public API for working directly with crypto cores. */ -typedef off_t hal_addr_t; - /* - * Error translation. + * Typedef to isolate code from our current choice of representation + * for a Cryptech bus address. */ -extern const char *hal_error_string(const hal_error_t err); +typedef off_t hal_addr_t; /* * Opaque structure representing a core. @@ -186,7 +198,7 @@ extern hal_addr_t hal_core_base(const hal_core_t *core); extern const hal_core_t * hal_core_iterate(const hal_core_t *core); /* - * Higher level public API. + * Slightly higher level public API, still working directly with cores. */ /* @@ -200,13 +212,6 @@ extern hal_error_t hal_get_random(const hal_core_t *core, void *buffer, const si */ /* - * 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 - -/* * Opaque driver structure for digest algorithms. */ @@ -221,7 +226,18 @@ typedef struct hal_hash_driver hal_hash_driver_t; * problem. */ +typedef enum { + hal_digest_algorithm_none, + hal_digest_algorithm_sha1, + hal_digest_algorithm_sha256, + hal_digest_algorithm_sha512_224, + hal_digest_algorithm_sha512_256, + hal_digest_algorithm_sha384, + hal_digest_algorithm_sha512 +} hal_digest_algorithm_t; + typedef struct { + hal_digest_algorithm_t digest_algorithm; size_t block_length; size_t digest_length; size_t hash_state_length; @@ -284,6 +300,10 @@ extern void hal_hash_cleanup(hal_hash_state_t **state); extern void hal_hmac_cleanup(hal_hmac_state_t **state); +extern const hal_hash_descriptor_t *hal_hash_get_descriptor(const hal_hash_state_t * const state); + +extern const hal_hash_descriptor_t *hal_hmac_get_descriptor(const hal_hmac_state_t * const state); + /* * AES key wrap functions. */ @@ -326,10 +346,27 @@ extern hal_error_t hal_modexp(const hal_core_t *core, /* - * RSA. + * Key types and curves, used in various places. */ -typedef enum { HAL_RSA_PRIVATE, HAL_RSA_PUBLIC } hal_rsa_key_type_t; +typedef enum { + HAL_KEY_TYPE_NONE, + HAL_KEY_TYPE_RSA_PRIVATE, + HAL_KEY_TYPE_RSA_PUBLIC, + HAL_KEY_TYPE_EC_PRIVATE, + HAL_KEY_TYPE_EC_PUBLIC +} hal_key_type_t; + +typedef enum { + HAL_CURVE_NONE, + HAL_CURVE_P256, + HAL_CURVE_P384, + HAL_CURVE_P521 +} hal_curve_name_t; + +/* + * RSA. + */ typedef struct hal_rsa_key hal_rsa_key_t; @@ -356,7 +393,7 @@ extern hal_error_t hal_rsa_key_load_public(hal_rsa_key_t **key, const uint8_t * const e, const size_t e_len); extern hal_error_t hal_rsa_key_get_type(const hal_rsa_key_t * const key, - hal_rsa_key_type_t *key_type); + hal_key_type_t *key_type); extern hal_error_t hal_rsa_key_get_modulus(const hal_rsa_key_t * const key, uint8_t *modulus, @@ -386,24 +423,27 @@ extern hal_error_t hal_rsa_key_gen(const hal_core_t *core, const unsigned key_length, const uint8_t * const public_exponent, const size_t public_exponent_len); -extern hal_error_t hal_rsa_key_to_der(const hal_rsa_key_t * const key, - uint8_t *der, size_t *der_len, const size_t der_max); +extern hal_error_t hal_rsa_private_key_to_der(const hal_rsa_key_t * const key, + uint8_t *der, size_t *der_len, const size_t der_max); -extern size_t hal_rsa_key_to_der_len(const hal_rsa_key_t * const key); +extern size_t hal_rsa_private_key_to_der_len(const hal_rsa_key_t * const key); -extern hal_error_t hal_rsa_key_from_der(hal_rsa_key_t **key, - void *keybuf, const size_t keybuf_len, - const uint8_t * const der, const size_t der_len); +extern hal_error_t hal_rsa_private_key_from_der(hal_rsa_key_t **key, + void *keybuf, const size_t keybuf_len, + const uint8_t * const der, const size_t der_len); -/* - * ECDSA. - */ +extern hal_error_t hal_rsa_public_key_to_der(const hal_rsa_key_t * const key, + uint8_t *der, size_t *der_len, const size_t der_max); -typedef enum { HAL_ECDSA_PRIVATE, HAL_ECDSA_PUBLIC } hal_ecdsa_key_type_t; +extern size_t hal_rsa_public_key_to_der_len(const hal_rsa_key_t * const key); -typedef enum { HAL_ECDSA_CURVE_P256, HAL_ECDSA_CURVE_P384, HAL_ECDSA_CURVE_P521 } hal_ecdsa_curve_t; +extern hal_error_t hal_rsa_public_key_from_der(hal_rsa_key_t **key, + void *keybuf, const size_t keybuf_len, + const uint8_t * const der, const size_t der_len); -typedef enum { HAL_ECDSA_SIGNATURE_FORMAT_ASN1, HAL_ECDSA_SIGNATURE_FORMAT_PKCS11 } hal_ecdsa_signature_format_t; +/* + * ECDSA. + */ typedef struct hal_ecdsa_key hal_ecdsa_key_t; @@ -413,22 +453,22 @@ extern void hal_ecdsa_set_debug(const int onoff); extern hal_error_t hal_ecdsa_key_load_private(hal_ecdsa_key_t **key, void *keybuf, const size_t keybuf_len, - const hal_ecdsa_curve_t curve, + const hal_curve_name_t curve, const uint8_t * const x, const size_t x_len, const uint8_t * const y, const size_t y_len, const uint8_t * const d, const size_t d_len); extern hal_error_t hal_ecdsa_key_load_public(hal_ecdsa_key_t **key, void *keybuf, const size_t keybuf_len, - const hal_ecdsa_curve_t curve, + const hal_curve_name_t curve, const uint8_t * const x, const size_t x_len, const uint8_t * const y, const size_t y_len); extern hal_error_t hal_ecdsa_key_get_type(const hal_ecdsa_key_t * const key, - hal_ecdsa_key_type_t *key_type); + hal_key_type_t *key_type); extern hal_error_t hal_ecdsa_key_get_curve(const hal_ecdsa_key_t * const key, - hal_ecdsa_curve_t *curve); + hal_curve_name_t *curve); extern hal_error_t hal_ecdsa_key_get_public(const hal_ecdsa_key_t * const key, uint8_t *x, size_t *x_len, const size_t x_max, @@ -439,16 +479,25 @@ extern void hal_ecdsa_key_clear(hal_ecdsa_key_t *key); extern hal_error_t hal_ecdsa_key_gen(const hal_core_t *core, hal_ecdsa_key_t **key, void *keybuf, const size_t keybuf_len, - const hal_ecdsa_curve_t curve); + const hal_curve_name_t curve); + +extern hal_error_t hal_ecdsa_private_key_to_der(const hal_ecdsa_key_t * const key, + uint8_t *der, size_t *der_len, const size_t der_max); -extern hal_error_t hal_ecdsa_key_to_der(const hal_ecdsa_key_t * const key, - uint8_t *der, size_t *der_len, const size_t der_max); +extern size_t hal_ecdsa_private_key_to_der_len(const hal_ecdsa_key_t * const key); -extern size_t hal_ecdsa_key_to_der_len(const hal_ecdsa_key_t * const key); +extern hal_error_t hal_ecdsa_private_key_from_der(hal_ecdsa_key_t **key, + void *keybuf, const size_t keybuf_len, + const uint8_t * const der, const size_t der_len); -extern hal_error_t hal_ecdsa_key_from_der(hal_ecdsa_key_t **key, - void *keybuf, const size_t keybuf_len, - const uint8_t * const der, const size_t der_len); +extern hal_error_t hal_ecdsa_public_key_to_der(const hal_ecdsa_key_t * const key, + uint8_t *der, size_t *der_len, const size_t der_max); + +extern size_t hal_ecdsa_public_key_to_der_len(const hal_ecdsa_key_t * const key); + +extern hal_error_t hal_ecdsa_public_key_from_der(hal_ecdsa_key_t **key, + void *keybuf, const size_t keybuf_len, + const uint8_t * const der, const size_t der_len); extern hal_error_t hal_ecdsa_key_to_ecpoint(const hal_ecdsa_key_t * const key, uint8_t *der, size_t *der_len, const size_t der_max); @@ -458,19 +507,224 @@ extern size_t hal_ecdsa_key_to_ecpoint_len(const hal_ecdsa_key_t * const key); extern hal_error_t hal_ecdsa_key_from_ecpoint(hal_ecdsa_key_t **key, void *keybuf, const size_t keybuf_len, const uint8_t * const der, const size_t der_len, - const hal_ecdsa_curve_t curve); + const hal_curve_name_t curve); extern hal_error_t hal_ecdsa_sign(const hal_core_t *core, const hal_ecdsa_key_t * const key, const uint8_t * const hash, const size_t hash_len, - uint8_t *signature, size_t *signature_len, const size_t signature_max, - const hal_ecdsa_signature_format_t signature_format); + uint8_t *signature, size_t *signature_len, const size_t signature_max); extern hal_error_t hal_ecdsa_verify(const hal_core_t *core, const hal_ecdsa_key_t * const key, const uint8_t * const hash, const size_t hash_len, - const uint8_t * const signature, const size_t signature_len, - const hal_ecdsa_signature_format_t signature_format); + const uint8_t * const signature, const size_t signature_len); + +/* + * Higher level RPC-based mechanism for working with HSM at arm's + * length, using handles instead of direct access to the cores. + * + * Session handles are pretty much as in PKCS #11: from our viewpoint, + * a session is a lock-step stream of operations, so while operations + * from different sessions can interleave, operations within a single + * session cannot. + * + * Client handles are a small extension to the PKCS #11 model, + * intended to support multiple PKCS #11 using applications sharing a + * single HSM. Technically, sessions are per-client, but in practice + * there's no sane reason why we'd use the same session handle + * concurrently in multiple clients. Mostly, the client abstraction + * is to handle login and logout against the HSM's PIN. Clients add + * nothing whatsoever to the security model (the HSM has no way of + * knowing whether the host is lumping multiple applications into a + * single "client"), the point of the exercise is just to make the + * C_Login()/C_Logout() semantics work as expected in the presence of + * multiple applications. + * + * NB: Unlike the other handles used in this protocol, session and + * client handles are created by the client (host) side of the RPC + * mechanism, not the server (HSM) side. + */ + +#define HAL_HANDLE_NONE (0) + +typedef struct { uint32_t handle; } hal_client_handle_t; +typedef struct { uint32_t handle; } hal_session_handle_t; + +typedef enum { HAL_USER_NONE, HAL_USER_NORMAL, HAL_USER_SO, HAL_USER_WHEEL } hal_user_t; + +extern hal_error_t hal_rpc_set_pin(const hal_client_handle_t client, + const hal_user_t user, + const char * const newpin, const size_t newpin_len); + +extern hal_error_t hal_rpc_login(const hal_client_handle_t client, + const hal_user_t user, + const char * const pin, const size_t pin_len); + +extern hal_error_t hal_rpc_logout(const hal_client_handle_t client); + +extern hal_error_t hal_rpc_logout_all(void); + +extern hal_error_t hal_rpc_is_logged_in(const hal_client_handle_t client, + const hal_user_t user); + +/* + * Get the version number of the remote RPC server. + */ + +extern hal_error_t hal_rpc_get_version(uint32_t *version); + +/* + * Get random bytes. + */ + +extern hal_error_t hal_rpc_get_random(void *buffer, const size_t length); + +/* + * Combined hash and HMAC functions: pass NULL key for plain hashing. + */ + +typedef struct { uint32_t handle; } hal_hash_handle_t; + +extern const hal_hash_handle_t hal_hash_handle_none; + +extern hal_error_t hal_rpc_hash_get_digest_length(const hal_digest_algorithm_t alg, size_t *length); + +extern hal_error_t hal_rpc_hash_get_digest_algorithm_id(const hal_digest_algorithm_t alg, + uint8_t *id, size_t *len, const size_t len_max); + +extern hal_error_t hal_rpc_hash_get_algorithm(const hal_hash_handle_t hash, hal_digest_algorithm_t *alg); + +/* + * Once started, a hash or HMAC operation is bound to a particular + * session, so we only need the client and session arguments to initialize. + */ + +extern hal_error_t hal_rpc_hash_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); + +extern hal_error_t hal_rpc_hash_update(const hal_hash_handle_t hash, + const uint8_t * data, const size_t length); + +extern hal_error_t hal_rpc_hash_finalize(const hal_hash_handle_t hash, + uint8_t *digest, const size_t length); + +/* + * Public key functions. + * + * The _sign() and _verify() methods accept a hash OR an input string; + * either "hash" should be hal_hash_handle_none or input should be NULL, + * but not both. + * + * Use of client and session handles here needs a bit more thought. + * + * Client handles are straightforward: basically, anything that + * creates a new pkey handle should take a client handle, which should + * suffice, as object handles never cross clients. + * + * Session handles are more interesting, as PKCS #11's versions of + * session and object handles do in effect allow one session to hand + * an object handle to another session. So any action which can do + * significant work (ie, which is complicated enough that we can't + * guarantee an immediate response) needs to take a session handle. + * + * There will probably be a few cases where a session handle isn't + * strictly required but we ask for one anyway because the API turns + * out to be easier to understand that way (eg, we probably want to + * ask for a session handle anywhere we ask for a client handle, + * whether we need the session handle or not, so that users of this + * API don't have to remember which pkey-handle-creating calls require + * a session handle and which ones don't...). + */ + +#define HAL_RPC_PKEY_NAME_MAX 128 + +typedef struct { uint32_t handle; } hal_pkey_handle_t; + +typedef uint32_t hal_key_flags_t; + +#define HAL_KEY_FLAG_USAGE_DIGITALSIGNATURE (1 << 0) +#define HAL_KEY_FLAG_USAGE_KEYENCIPHERMENT (1 << 1) +#define HAL_KEY_FLAG_USAGE_DATAENCIPHERMENT (1 << 2) + +extern hal_error_t hal_rpc_pkey_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); + +extern hal_error_t hal_rpc_pkey_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); + +extern hal_error_t hal_rpc_pkey_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); + +extern hal_error_t hal_rpc_pkey_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); + +extern hal_error_t hal_rpc_pkey_close(const hal_pkey_handle_t pkey); + +extern hal_error_t hal_rpc_pkey_delete(const hal_pkey_handle_t pkey); + +extern hal_error_t hal_rpc_pkey_get_key_type(const hal_pkey_handle_t pkey, + hal_key_type_t *type); + +extern hal_error_t hal_rpc_pkey_get_key_flags(const hal_pkey_handle_t pkey, + hal_key_flags_t *flags); + +extern size_t hal_rpc_pkey_get_public_key_len(const hal_pkey_handle_t pkey); + +extern hal_error_t hal_rpc_pkey_get_public_key(const hal_pkey_handle_t pkey, + uint8_t *der, size_t *der_len, const size_t der_max); + +extern hal_error_t hal_rpc_pkey_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); + +extern hal_error_t hal_rpc_pkey_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); + +typedef struct { + hal_key_type_t type; + hal_curve_name_t curve; + hal_key_flags_t flags; + char name[HAL_RPC_PKEY_NAME_MAX]; + size_t name_len; + /* ... */ +} hal_pkey_info_t; + +extern hal_error_t hal_rpc_pkey_list(hal_pkey_info_t *result, + unsigned *result_len, + const unsigned result_max); + +extern hal_error_t hal_rpc_client_init(void); +extern hal_error_t hal_rpc_client_close(void); +extern hal_error_t hal_rpc_server_init(void); +extern hal_error_t hal_rpc_server_close(void); +extern void hal_rpc_server_dispatch(const uint8_t * const ibuf, const size_t ilen, uint8_t * const obuf, size_t * const olen); +extern void hal_rpc_server_main(void); #endif /* _HAL_H_ */ |