Line data Source code
1 : #ifndef HEADER_fd_src_disco_keyguard_fd_keyguard_client_h
2 : #define HEADER_fd_src_disco_keyguard_fd_keyguard_client_h
3 :
4 : /* A simple blocking client to a remote signing server, based on a pair
5 : of (input, output) mcaches and data regions.
6 :
7 : For maximum security, the caller should ensure a few things before
8 : using,
9 :
10 : (a) The request mcache and data region are placed in a shared memory
11 : map that is accessible exclusively to the calling tile, and the
12 : keyguard tile. The keyguard tile should map the memory as read
13 : only.
14 :
15 : (b) The response mcache and data region are placed in a shared
16 : memory map that is accessible exclusively to the calling tile,
17 : and the keyguard tile. The calling tile should map the memory
18 : as read only.
19 :
20 : (c) No other data is placed in these shared memory maps, and no
21 : other tiles have access to them.
22 :
23 : (d) Each input/output mcache correspond to a single role, and the
24 : keyguard tile verifies that all incoming requests are
25 : specifically formatted for that role. */
26 :
27 : #include "../../tango/fd_tango_base.h"
28 : #include "../sleep/fd_sleep.h"
29 :
30 : #define FD_KEYGUARD_CLIENT_ALIGN (128UL)
31 : #define FD_KEYGUARD_CLIENT_FOOTPRINT (256UL)
32 :
33 : struct __attribute__((aligned(FD_KEYGUARD_CLIENT_ALIGN))) fd_keyguard_client {
34 : fd_frag_meta_t * request;
35 : ulong request_seq;
36 : ulong request_depth;
37 : fd_wksp_t * request_mem;
38 : ulong request_chunk;
39 : ulong request_chunk0;
40 : ulong request_wmark;
41 : ulong request_mtu;
42 :
43 : fd_frag_meta_t * response;
44 : ulong response_seq;
45 : ulong response_depth;
46 : fd_wksp_t * response_mem;
47 : ulong response_chunk0;
48 : ulong response_wmark;
49 : ulong response_mtu;
50 :
51 : fd_sleep_t * sleep;
52 : ulong request_link_id;
53 : fd_sleep_wake_t wake;
54 : };
55 : typedef struct fd_keyguard_client fd_keyguard_client_t;
56 :
57 : FD_PROTOTYPES_BEGIN
58 :
59 : void *
60 : fd_keyguard_client_new( void * shmem,
61 : fd_frag_meta_t * request_mcache,
62 : uchar * request_dcache,
63 : fd_frag_meta_t * response_mcache,
64 : uchar * response_dcache,
65 : ulong request_mtu,
66 : ulong response_mtu,
67 : fd_sleep_t * sleep,
68 : ulong request_link_id,
69 : ulong sign_tile_id );
70 :
71 : static inline fd_keyguard_client_t *
72 0 : fd_keyguard_client_join( void * shclient ) { return (fd_keyguard_client_t*)shclient; }
73 :
74 : static inline void *
75 0 : fd_keyguard_client_leave( fd_keyguard_client_t * client ) { return (void*)client; }
76 :
77 : static inline void *
78 0 : fd_keyguard_client_delete( void * shclient ) { return shclient; }
79 :
80 : /* fd_keyguard_client_sign sends a remote signing request to the signing
81 : server, and blocks (spins) until the response is received.
82 :
83 : Signing is treated as infallible, and there are no error codes or
84 : results. If the remote signer is stuck or not running, this function
85 : will not timeout and instead hangs forever waiting for a response.
86 : This is currently by design.
87 :
88 : sign_data should be a pointer to a buffer, with length sign_data_len
89 : that will be signed. The data should correspond to one of the
90 : roles described in fd_keyguard.h. If the remote signing tile
91 : receives a malformed signing request, or one for a role that does
92 : not correspond to the role assigned to the receiving mcache, it
93 : will abort the whole program with a critical error.
94 :
95 : FD_KEYGUARD_SIGN_TYPE_BLS_PUBKEY is a public-key query: sign_data
96 : contains a ulong authority index and no signing is performed.
97 :
98 : The response is written into the signature buffer, which must be at
99 : least FD_BLS_SIG_SZ (192) bytes for FD_KEYGUARD_SIGN_TYPE_BLS,
100 : FD_BLS_PUB_COMPRESSED_SZ (48) bytes for FD_KEYGUARD_SIGN_TYPE_BLS_PUBKEY,
101 : or 64 bytes for every other type.
102 :
103 : sign_type is in FD_KEYGUARD_SIGN_TYPE_{...}. */
104 :
105 : void
106 : fd_keyguard_client_sign( fd_keyguard_client_t * client,
107 : uchar * signature,
108 : uchar const * sign_data,
109 : ulong sign_data_len,
110 : int sign_type );
111 :
112 : /* fd_keyguard_client_ag_vote_sign is fd_keyguard_client_sign for an
113 : Alpenglow BLS vote with a choice of key. authority_idx is ULONG_MAX
114 : to sign with the BLS key derived from the identity, or else the index
115 : in [0,FD_KEYGUARD_AUTH_VOTERS_MAX) of the authorized voter the caller
116 : passes into the toml whose derived BLS key signs. signature must
117 : have capacity for FD_BLS_SIG_SZ bytes. */
118 :
119 : void
120 : fd_keyguard_client_ag_vote_sign( fd_keyguard_client_t * client,
121 : uchar * signature,
122 : ulong authority_idx,
123 : uchar const * sign_data,
124 : ulong sign_data_len );
125 :
126 : /* fd_keyguard_client_bls_pubkey returns the compressed BLS public key
127 : held by the sign tile. authority_idx is ULONG_MAX for the identity,
128 : or an index in [0,FD_KEYGUARD_AUTH_VOTERS_MAX) of a loaded authorized
129 : voter, as in fd_keyguard_client_ag_vote_sign. public_key must have
130 : room for FD_BLS_PUB_COMPRESSED_SZ bytes. Uses the same blocking
131 : request/response channel as signing; only the public key is returned. */
132 :
133 : void
134 : fd_keyguard_client_bls_pubkey( fd_keyguard_client_t * client,
135 : uchar * public_key,
136 : ulong authority_idx );
137 :
138 : /* fd_keyguard_client_vote_txn_sign sends a remote signing request to
139 : the signing server, and blocks (spins) until the response is
140 : received.
141 :
142 : Signing is treated as infallible, and there are no error codes or
143 : results. If the remote signer is stuck or not running, this function
144 : will not timeout and instead hangs forever waiting for a response.
145 : This is currently by design.
146 :
147 : A vote transaction can have up to 2 signers: either just the identity
148 : key or the combination of the identity key and an authorized voter.
149 :
150 : sign_data should be a pointer to a buffer, with length sign_data_len
151 : that will be signed. The data should correspond to one of the
152 : roles described in fd_keyguard.h. If the remote signing tile
153 : receives a malformed signing request, or one for a role that does
154 : not correspond to the role assigned to the receiving mcache, it
155 : will abort the whole program with a critical error.
156 :
157 : The authority_idx is the index of the second signer on the vote
158 : transaction where the index corresponds to the authorized voter
159 : the caller passes into the toml. If there is no second signer
160 : (the case where the identity is the only signer) then the
161 : authority_idx should be ULONG_MAX.
162 :
163 : The response will be either 1 or 2 64 byte signatures which will be
164 : written into the signature buffer which must have the capacity to
165 : hold the maximum number of signatures, which is 2. There will be
166 : 2 signatures if authority_idx!=ULONG_MAX and 1 otherwise.
167 : authority_idx should be in the range [0,FD_KEYGUARD_AUTH_VOTERS_MAX). */
168 :
169 : void
170 : fd_keyguard_client_vote_txn_sign( fd_keyguard_client_t * client,
171 : uchar * signatures,
172 : ulong authority_idx,
173 : uchar const * sign_data,
174 : ulong sign_data_len );
175 : FD_PROTOTYPES_END
176 :
177 : #endif /* HEADER_fd_src_disco_keyguard_fd_keyguard_client_h */
|
