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             : 
      29             : #define FD_KEYGUARD_CLIENT_ALIGN (128UL)
      30             : #define FD_KEYGUARD_CLIENT_FOOTPRINT (128UL)
      31             : 
      32             : struct __attribute__((aligned(FD_KEYGUARD_CLIENT_ALIGN))) fd_keyguard_client {
      33             :   fd_frag_meta_t * request;
      34             :   ulong            request_seq;
      35             :   ulong            request_depth;
      36             :   fd_wksp_t *      request_mem;
      37             :   ulong            request_chunk;
      38             :   ulong            request_chunk0;
      39             :   ulong            request_wmark;
      40             :   ulong            request_mtu;
      41             : 
      42             :   fd_frag_meta_t * response;
      43             :   ulong            response_seq;
      44             :   ulong            response_depth;
      45             :   fd_wksp_t *      response_mem;
      46             :   ulong            response_chunk0;
      47             :   ulong            response_wmark;
      48             :   ulong            response_mtu;
      49             : };
      50             : typedef struct fd_keyguard_client fd_keyguard_client_t;
      51             : 
      52             : FD_PROTOTYPES_BEGIN
      53             : 
      54             : void *
      55             : fd_keyguard_client_new( void *           shmem,
      56             :                         fd_frag_meta_t * request_mcache,
      57             :                         uchar *          request_dcache,
      58             :                         fd_frag_meta_t * response_mcache,
      59             :                         uchar *          response_dcache,
      60             :                         ulong            request_mtu,
      61             :                         ulong            response_mtu );
      62             : 
      63             : static inline fd_keyguard_client_t *
      64           0 : fd_keyguard_client_join( void * shclient ) { return (fd_keyguard_client_t*)shclient; }
      65             : 
      66             : static inline void *
      67           0 : fd_keyguard_client_leave( fd_keyguard_client_t * client ) { return (void*)client; }
      68             : 
      69             : static inline void *
      70           0 : fd_keyguard_client_delete( void * shclient ) { return shclient; }
      71             : 
      72             : /* fd_keyguard_client_sign sends a remote signing request to the signing
      73             :     server, and blocks (spins) until the response is received.
      74             : 
      75             :     Signing is treated as infallible, and there are no error codes or
      76             :     results. If the remote signer is stuck or not running, this function
      77             :     will not timeout and instead hangs forever waiting for a response.
      78             :     This is currently by design.
      79             : 
      80             :     sign_data should be a pointer to a buffer, with length sign_data_len
      81             :     that will be signed.  The data should correspond to one of the
      82             :     roles described in fd_keyguard.h.  If the remote signing tile
      83             :     receives a malformed signing request, or one for a role that does
      84             :     not correspond to the role assigned to the receiving mcache, it
      85             :     will abort the whole program with a critical error.
      86             : 
      87             :     The response is written into the signature buffer, which must be at
      88             :     least that large: FD_KEYGUARD_BLS_SIG_SZ (192) bytes for
      89             :     FD_KEYGUARD_SIGN_TYPE_BLS, 64 bytes for every other type.
      90             : 
      91             :     sign_type is in FD_KEYGUARD_SIGN_TYPE_{...}. */
      92             : 
      93             : void
      94             : fd_keyguard_client_sign( fd_keyguard_client_t * client,
      95             :                          uchar *                signature,
      96             :                          uchar const *          sign_data,
      97             :                          ulong                  sign_data_len,
      98             :                          int                    sign_type );
      99             : 
     100             : /* fd_keyguard_client_vote_txn_sign sends a remote signing request to
     101             :    the signing server, and blocks (spins) until the response is
     102             :    received.
     103             : 
     104             :    Signing is treated as infallible, and there are no error codes or
     105             :    results. If the remote signer is stuck or not running, this function
     106             :    will not timeout and instead hangs forever waiting for a response.
     107             :    This is currently by design.
     108             : 
     109             :    A vote transaction can have up to 2 signers: either just the identity
     110             :    key or the combination of the identity key and an authorized voter.
     111             : 
     112             :    sign_data should be a pointer to a buffer, with length sign_data_len
     113             :    that will be signed.  The data should correspond to one of the
     114             :    roles described in fd_keyguard.h.  If the remote signing tile
     115             :    receives a malformed signing request, or one for a role that does
     116             :    not correspond to the role assigned to the receiving mcache, it
     117             :    will abort the whole program with a critical error.
     118             : 
     119             :    The authority_idx is the index of the second signer on the vote
     120             :    transaction where the index corresponds to the authorized voter
     121             :    the caller passes into the toml.  If there is no second signer
     122             :    (the case where the identity is the only signer) then the
     123             :    authority_idx should be ULONG_MAX.
     124             : 
     125             :    The response will be either 1 or 2 64 byte signatures which will be
     126             :    written into the signature buffer which must have the capacity to
     127             :    hold the maximum number of signatures, which is 2.  There will be
     128             :    2 signatures if authority_idx!=ULONG_MAX and 1 otherwise.
     129             :    authority_idx should be in the range [0,16). */
     130             : 
     131             : void
     132             : fd_keyguard_client_vote_txn_sign( fd_keyguard_client_t * client,
     133             :                                   uchar *                signatures,
     134             :                                   ulong                  authority_idx,
     135             :                                   uchar const *          sign_data,
     136             :                                   ulong                  sign_data_len );
     137             : FD_PROTOTYPES_END
     138             : 
     139             : #endif /* HEADER_fd_src_disco_keyguard_fd_keyguard_client_h */