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 "../fd_disco_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             :   uchar          * request_data;
      37             : 
      38             :   fd_frag_meta_t * response;
      39             :   ulong            response_seq;
      40             :   ulong            response_depth;
      41             :   uchar          * response_data;
      42             : };
      43             : typedef struct fd_keyguard_client fd_keyguard_client_t;
      44             : 
      45             : FD_PROTOTYPES_BEGIN
      46             : 
      47             : void *
      48             : fd_keyguard_client_new( void *           shmem,
      49             :                         fd_frag_meta_t * request_mcache,
      50             :                         uchar *          request_data,
      51             :                         fd_frag_meta_t * response_mcache,
      52             :                         uchar *          response_data );
      53             : 
      54             : static inline fd_keyguard_client_t *
      55           0 : fd_keyguard_client_join( void * shclient ) { return (fd_keyguard_client_t*)shclient; }
      56             : 
      57             : static inline void *
      58           0 : fd_keyguard_client_leave( fd_keyguard_client_t * client ) { return (void*)client; }
      59             : 
      60             : static inline void *
      61           0 : fd_keyguard_client_delete( void * shclient ) { return shclient; }
      62             : 
      63             : /* fd_keyguard_client_sign sends a remote signing request to the signing
      64             :     server, and blocks (spins) until the response is received.
      65             : 
      66             :     Signing is treated as infallible, and there are no error codes or
      67             :     results. If the remote signer is stuck or not running, this function
      68             :     will not timeout and instead hangs forever waiting for a response.
      69             :     This is currently by design.
      70             : 
      71             :     sign_data should be a pointer to a buffer, with length sign_data_len
      72             :     that will be signed.  The data should correspond to one of the
      73             :     roles described in fd_keyguard.h.  If the remote signing tile
      74             :     receives a malformed signing request, or one for a role that does
      75             :     not correspond to the role assigned to the receiving mcache, it
      76             :     will abort the whole program with a critical error.
      77             : 
      78             :     The response, a 64 byte signature, will be written into the signature
      79             :     buffer, which must be at least this size.
      80             : 
      81             :     sign_type is in FD_KEYGUARD_SIGN_TYPE_{...}. */
      82             : 
      83             : void
      84             : fd_keyguard_client_sign( fd_keyguard_client_t * client,
      85             :                          uchar *                signature,
      86             :                          uchar const *          sign_data,
      87             :                          ulong                  sign_data_len,
      88             :                          int                    sign_type );
      89             : 
      90             : FD_PROTOTYPES_END
      91             : 
      92             : #endif /* HEADER_fd_src_disco_keyguard_fd_keyguard_client_h */