aboutsummaryrefslogtreecommitdiff
path: root/hal_internal.h
blob: 59efbffe7899619af547f4320d69d92f3c68d215 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
/*
 * 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 <string.h>

#include "hal.h"
#include "verilog_constants.h"

/*
 * 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.
 */

/*
 * htonl is not available in arm-none-eabi headers or libc.
 */
#ifndef STM32F4XX
#include <arpa/inet.h>
#else
#ifdef __ARMEL__                /* little endian */
inline uint32_t htonl(uint32_t w)
{
    return
        ((w & 0x000000ff) << 24) +
        ((w & 0x0000ff00) << 8) +
        ((w & 0x00ff0000) >> 8) +
        ((w & 0xff000000) >> 24);
}
#else                           /* big endian */
#define htonl(x) (x)
#endif
#define ntohl htonl
#endif

/*
 * 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

/*
 * 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.
 *
 * ...Except that for PKCS #11 we also have to handle the case of
 * "session keys", ie, keys which are not stored on the HSM.
 * Apparently people really do use these, mostly for public keys, in
 * order to conserve expensive memory on the HSM.  So this is another
 * feature of mixed mode: keys with HAL_KEY_FLAG_PROXIMATE set live on
 * the host, not in the HSM, and the mixed-mode pkey handlers deal
 * with the routing.  In the other two modes we ignore the flag and
 * send everything where we were going to send it anyway.  Restricting
 * the fancy key handling to mixed mode lets us drop this complexity
 * out entirely for applications which have no use for it.
 */

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,
                       hal_uuid_t *name,
                       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_uuid_t * const name,
                       const hal_key_flags_t flags);

  hal_error_t  (*generate_rsa)(const hal_client_handle_t client,
                               const hal_session_handle_t session,
                               hal_pkey_handle_t *pkey,
                               hal_uuid_t *name,
                               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,
                              hal_uuid_t *name,
                              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_key_flags_t flags);

} 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;

/*
 * See code in rpc_pkey.c for how this flag fits into the pkey handle.
 */

#define HAL_PKEY_HANDLE_TOKEN_FLAG  (1 << 31)

/*
 * Mostly used by the local_pkey code, but the mixed_pkey code needs
 * it to pad hashes for RSA PKCS #1.5 signatures.  This may indicate
 * that we need a slightly more general internal API here, but not
 * worth worrying about as long as we can treat RSA as a special case
 * and just pass the plain hash for everything else.
 */

extern hal_error_t hal_rpc_pkcs1_construct_digestinfo(const hal_hash_handle_t handle,
                                                      uint8_t *digest_info, size_t *digest_info_len,
                                                      const size_t digest_info_max);

/*
 * UUID stuff.  All UUIDs we use (or are likely to use) are type 4 "random" UUIDs
 */

#define HAL_UUID_TEXT_SIZE	(sizeof("00112233-4455-6677-8899-aabbccddeeff"))

static inline int hal_uuid_cmp(const hal_uuid_t * const a, const hal_uuid_t * const b)
{
  return memcmp(a, b, sizeof(hal_uuid_t));
}

extern hal_error_t hal_uuid_gen(hal_uuid_t *uuid);

extern hal_error_t hal_uuid_parse(hal_uuid_t *uuid, const char * const string);

extern hal_error_t hal_uuid_format(const hal_uuid_t * const uuid, char *buffer, const size_t buffer_len);

/*
 * Keystore API.
 */

/*
 * The first chunk of this is stuff that's really internal to the
 * keystore implementation(s), and perhaps should move to a separate
 * ks_internal.h.
 */

/*
 * 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
 * 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)

/*
 * hal_ks_key_t probably should not be here, or perhaps even exist at
 * all, since it's really a relic of an older design from before we
 * understood how the keystore flash fit into this picture.  Leaving
 * it in place for now, but expect it to go away once the new ks_index
 * stuff is ready to use.
 *
 * This struct is ordered such that all metadata appears before the
 * big buffers, in order for all metadata to be loaded with a single
 * page read from e.g. the ks_flash module.
 */

typedef struct {
  hal_key_type_t type;
  hal_curve_name_t curve;
  hal_key_flags_t flags;
  uint8_t in_use;
  size_t der_len;
  hal_uuid_t name;
  uint8_t der[HAL_KS_WRAPPED_KEYSIZE];
} 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;

extern hal_error_t hal_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.
 *
 * hal_pkey_slot_t is defined here too, so that keystore drivers can
 * piggyback on the pkey database for storage related to keys on which
 * the user currently has an active pkey handle.  Nothing outside the
 * pkey and keystore code should touch this.
 */

typedef struct {
  hal_client_handle_t client_handle;
  hal_session_handle_t session_handle;
  hal_pkey_handle_t pkey_handle;
  hal_key_type_t type;
  hal_curve_name_t curve;
  hal_key_flags_t flags;
  hal_uuid_t name;

  /*
   * We used to stash a "hint" value here for the keystore driver to
   * speed things up when we had multiple operations on the same key.
   * Removed as premature optimization during keystore rewrite, but we
   * may want to put something like this back once the new API has
   * stablized.  If so, form would probably be a union containing
   * keystore-driver-specific data, which everything else (including
   * the pkey code) should treat as opaque: making it really opaque
   * would complicate memory allocation and isn't worth it for an
   * internal API.
   */

  /*
   * This might be where we'd stash a (hal_core_t *) pointing to a
   * core which has already been loaded with the key, if we were
   * trying to be clever about using multiple signing cores.  Moot
   * point (ie, no way we could possibly test such a thing) as long as
   * the FPGA is too small to hold more than one modexp core and ECDSA
   * is entirely software, so skip it for now, but the implied
   * semantics are interesting: a pkey handle starts to resemble an
   * initialized signing core, and once all the cores are in use, one
   * can't load another key without closing an existing pkey handle.
   */
} hal_pkey_slot_t;

typedef struct hal_ks_driver hal_ks_driver_t;

typedef struct hal_ks hal_ks_t;

struct hal_ks_driver {

  hal_error_t (*open)(const hal_ks_driver_t * const driver,
                      hal_ks_t **ks);

  hal_error_t (*close)(hal_ks_t *ks);

  hal_error_t (*store)(hal_ks_t *ks,
                       const hal_pkey_slot_t * const slot,
		       const uint8_t * const der,  const size_t der_len);

  hal_error_t (*fetch)(hal_ks_t *ks,
                       hal_pkey_slot_t *slot,
		       uint8_t *der, size_t *der_len, const size_t der_max);

  hal_error_t (*delete)(hal_ks_t *ks,
                        const hal_pkey_slot_t * const slot);

  hal_error_t (*list)(hal_ks_t *ks,
		      hal_pkey_info_t *result,
		      unsigned *result_len,
		      const unsigned result_max);
};


struct hal_ks {
  const hal_ks_driver_t *driver;
  /*
   * Any other common portions of hal_ks_t go here.
   */

  /*
   * Driver-specific stuff is handled by a form of subclassing:
   * driver module embeds this structure at the head of whatever
   * else it needs, and performs casts as needed.
   */
};

extern const hal_ks_driver_t
   hal_ks_volatile_driver[1],
   hal_ks_token_driver[1];

static inline hal_error_t hal_ks_open(const hal_ks_driver_t * const driver,
			       hal_ks_t **ks)
{
  if (driver == NULL || driver->open == NULL || ks == NULL)
    return HAL_ERROR_BAD_ARGUMENTS;

  return driver->open(driver, ks);
}

static inline hal_error_t hal_ks_close(hal_ks_t *ks)
{
  if (ks == NULL || ks->driver == NULL || ks->driver->close == NULL)
    return HAL_ERROR_BAD_ARGUMENTS;

  return ks->driver->close(ks);
}

static inline hal_error_t hal_ks_store(hal_ks_t *ks,
                                       hal_pkey_slot_t *slot,
                                       const uint8_t * const der,  const size_t der_len)
{
  if (ks == NULL || ks->driver == NULL || ks->driver->store == NULL || slot == NULL || der == NULL)
    return HAL_ERROR_BAD_ARGUMENTS;

  return ks->driver->store(ks, slot, der, der_len);
}

static inline hal_error_t hal_ks_fetch(hal_ks_t *ks,
                                       hal_pkey_slot_t *slot,
                                       uint8_t *der, size_t *der_len, const size_t der_max)
{
  if (ks == NULL || ks->driver == NULL || ks->driver->fetch == NULL || slot == NULL)
    return HAL_ERROR_BAD_ARGUMENTS;

  return ks->driver->fetch(ks, slot, der, der_len, der_max);
}

static inline hal_error_t hal_ks_delete(hal_ks_t *ks,
                                        hal_pkey_slot_t *slot)
{
  if (ks == NULL || ks->driver == NULL || ks->driver->delete == NULL || slot == NULL)
    return HAL_ERROR_BAD_ARGUMENTS;

  return ks->driver->delete(ks, slot);
}

static inline hal_error_t hal_ks_list(hal_ks_t *ks,
                                      hal_pkey_info_t *result,
                                      unsigned *result_len,
                                      const unsigned result_max)
{
  if (ks == NULL || ks->driver == NULL || ks->driver->list == NULL)
    return HAL_ERROR_BAD_ARGUMENTS;

  return ks->driver->list(ks, result, result_len, result_max);
}

/*
 * Keystore index.  This is intended to be usable by both memory-based
 * (in-memory, mmap(), ...) keystores and keystores based on raw flash.
 * Some of the features aren't really necessary for memory-based keystores,
 * but should be harmless.
 *
 * 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 contains nothing but flags and block numbers, and
 * is deliberately a small data structure so that moving data around
 * 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-ones 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.
 *
 * At the moment, this design leaves no room for "continuation" blocks
 * (additional blocks for keys so large that they won't fit in a
 * single flash sub-sector, or whatever).  Not sure we need that, but
 * if we do, adding it would be fairly simple: change the keyname
 * array to be an array of two-element structures, the first of which
 * is the name UUID, the second of which is the offset within the
 * series of blocks sharing that name (usually just one block, so the
 * offset would usually just be zero).  Implement that if and when we
 * need it.
 *
 * Note that this API deliberately says nothing about how the keys
 * themselves are stored, that's up to the keystore driver.  This
 * portion of the API is only concerned with allocation and naming.
 */

typedef struct {
  unsigned size;                /* Array length */
  unsigned used;                /* How many blocks are in use */
  uint16_t *index;              /* Index/freelist array */
  hal_uuid_t *names;            /* Keyname array */
} hal_ks_index_t;

/*
 * Finish setting up key index.  Caller must populate index, free
 * list, and name array.
 *
 * This function checks a few things then sorts the index proper.
 *
 * If driver cares about wear leveling, driver must supply the free
 * list in the desired order (FIFO); figuring out what that order is a
 * problem for the keystore driver.
 */
extern hal_error_t hal_ks_index_setup(hal_ks_index_t *ksi);

/*
 * Find a key block, return its block number.
 */
extern hal_error_t hal_ks_index_find(hal_ks_index_t *ksi,
                                     const hal_uuid_t * const name,
                                     unsigned *blockno);

/*
 * Add a key block, return its block number.
 */
extern hal_error_t hal_ks_index_add(hal_ks_index_t *ksi,
                                    const hal_uuid_t * const name,
                                    unsigned *blockno);

/*
 * Delete a key block, returns its block number (driver may need it).
 */
extern hal_error_t hal_ks_index_delete(hal_ks_index_t *ksi,
                                       const hal_uuid_t * const name,
                                       unsigned *blockno);

/*
 * This stuff might want renaming, eg, to hal_pin_*().
 */

extern hal_error_t hal_set_pin_default_iterations(const hal_client_handle_t client,
                                                  const uint32_t iterations);

extern hal_error_t hal_get_pin(const hal_user_t user,
                               const hal_ks_pin_t **pin);

extern hal_error_t hal_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_SIGN,
    RPC_FUNC_PKEY_VERIFY,
    RPC_FUNC_PKEY_LIST,
    RPC_FUNC_PKEY_RENAME,
} rpc_func_num_t;

#define RPC_VERSION 0x01010000          /* 1.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
#define RPC_CLIENT_NONE         3

/*
 * Maximum size of a HAL RPC packet.
 */

#ifndef HAL_RPC_MAX_PKT_SIZE
#define HAL_RPC_MAX_PKT_SIZE    4096
#endif

/*
 * Location of AF_UNIX socket for RPC client mux daemon.
 */

#ifndef HAL_CLIENT_DAEMON_DEFAULT_SOCKET_NAME
#define HAL_CLIENT_DAEMON_DEFAULT_SOCKET_NAME   "/tmp/cryptech_rpcd.socket"
#endif

/*
 * Default device name and line speed for HAL RPC serial connection to HSM.
 */

#ifndef HAL_CLIENT_SERIAL_DEFAULT_DEVICE
#define HAL_CLIENT_SERIAL_DEFAULT_DEVICE 	"/dev/ttyUSB0"
#endif

#ifndef HAL_CLIENT_SERIAL_DEFAULT_SPEED
#define HAL_CLIENT_SERIAL_DEFAULT_SPEED         921600
#endif

/*
 * Names of environment variables for setting the above in RPC clients.
 */

#define	HAL_CLIENT_SERIAL_DEVICE_ENVVAR		"CRYPTECH_RPC_CLIENT_SERIAL_DEVICE"
#define	HAL_CLIENT_SERIAL_SPEED_ENVVAR		"CRYPTECH_RPC_CLIENT_SERIAL_SPEED"

#endif /* _HAL_INTERNAL_H_ */

/*
 * Local variables:
 * indent-tabs-mode: nil
 * End:
 */