aboutsummaryrefslogtreecommitdiff
path: root/hal.h
diff options
context:
space:
mode:
Diffstat (limited to 'hal.h')
-rw-r--r--hal.h276
1 files changed, 245 insertions, 31 deletions
diff --git a/hal.h b/hal.h
index eb1e253..3fcf813 100644
--- a/hal.h
+++ b/hal.h
@@ -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,10 @@
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") \
END_OF_HAL_ERROR_LIST
/* Marker to forestall silly line continuation errors */
@@ -125,24 +133,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 +191,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.
*/
/*
@@ -221,7 +226,17 @@ typedef struct hal_hash_driver hal_hash_driver_t;
* problem.
*/
+typedef enum {
+ 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 +299,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 +345,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 +392,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,
@@ -399,12 +435,6 @@ extern hal_error_t hal_rsa_key_from_der(hal_rsa_key_t **key,
* ECDSA.
*/
-typedef enum { HAL_ECDSA_PRIVATE, HAL_ECDSA_PUBLIC } hal_ecdsa_key_type_t;
-
-typedef enum { HAL_ECDSA_CURVE_P256, HAL_ECDSA_CURVE_P384, HAL_ECDSA_CURVE_P521 } hal_ecdsa_curve_t;
-
-typedef enum { HAL_ECDSA_SIGNATURE_FORMAT_ASN1, HAL_ECDSA_SIGNATURE_FORMAT_PKCS11 } hal_ecdsa_signature_format_t;
-
typedef struct hal_ecdsa_key hal_ecdsa_key_t;
extern const size_t hal_ecdsa_key_t_size;
@@ -413,22 +443,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,7 +469,7 @@ 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_key_to_der(const hal_ecdsa_key_t * const key,
uint8_t *der, size_t *der_len, const size_t der_max);
@@ -458,19 +488,203 @@ 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.
+ */
+
+typedef struct { uint32_t handle; } hal_rpc_client_handle_t;
+typedef struct { uint32_t handle; } hal_rpc_session_handle_t;
+
+typedef enum { HAL_RPC_USER_NONE, HAL_RPC_USER_NORMAL, HAL_RPC_USER_SO } hal_rpc_user_t;
+
+extern hal_error_t hal_rpc_set_pin(const hal_rpc_user_t which,
+ const char * const newpin, const size_t newpin_len);
+
+extern hal_error_t hal_rpc_login(const hal_rpc_client_handle_t client,
+ const hal_rpc_user_t user,
+ const char * const pin, const size_t pin_len);
+
+extern hal_error_t hal_rpc_logout(const hal_rpc_client_handle_t client);
+
+/*
+ * 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_rpc_hash_handle_t;
+
+extern const hal_rpc_hash_handle_t hal_rpc_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_rpc_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_rpc_client_handle_t client,
+ const hal_rpc_session_handle_t session,
+ hal_rpc_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_rpc_hash_handle_t hash,
+ const uint8_t * data, const size_t length);
+
+extern hal_error_t hal_rpc_hash_finalize(const hal_rpc_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_rpc_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_rpc_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_rpc_client_handle_t client,
+ const hal_rpc_session_handle_t session,
+ hal_rpc_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_rpc_client_handle_t client,
+ const hal_rpc_session_handle_t session,
+ hal_rpc_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_rpc_client_handle_t client,
+ const hal_rpc_session_handle_t session,
+ hal_rpc_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_rpc_client_handle_t client,
+ const hal_rpc_session_handle_t session,
+ hal_rpc_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_rpc_pkey_handle_t pkey);
+
+extern hal_error_t hal_rpc_pkey_delete(const hal_rpc_pkey_handle_t pkey);
+
+extern hal_error_t hal_rpc_pkey_get_key_type(const hal_rpc_pkey_handle_t pkey,
+ hal_key_type_t *type);
+
+extern hal_error_t hal_rpc_pkey_get_key_flags(const hal_rpc_pkey_handle_t pkey,
+ hal_key_flags_t *flags);
+
+extern size_t hal_rpc_pkey_get_public_key_len(const hal_rpc_pkey_handle_t pkey);
+
+extern hal_error_t hal_rpc_pkey_get_public_key(const hal_rpc_pkey_handle_t pkey,
+ uint8_t *der, size_t *der_len, const size_t der_len_max);
+
+extern hal_error_t hal_rpc_pkey_sign(const hal_rpc_session_handle_t session,
+ const hal_rpc_pkey_handle_t pkey,
+ const hal_rpc_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_rpc_session_handle_t session,
+ const hal_rpc_pkey_handle_t pkey,
+ const hal_rpc_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_rpc_pkey_key_info_t;
+
+extern hal_error_t hal_rpc_pkey_list(hal_rpc_pkey_key_info_t *result,
+ unsigned *result_len,
+ const unsigned result_max);
#endif /* _HAL_H_ */