Line data    Source code

       1             : #ifndef HEADER_fd_src_disco_keyguard_fd_keyguard_h
       2             : #define HEADER_fd_src_disco_keyguard_fd_keyguard_h
       3             : 
       4             : /* fd_keyguard creates digital signatures on behalf of validator
       5             :    components. */
       6             : 
       7             : #include "../fd_disco_base.h"
       8             : 
       9             : FD_PROTOTYPES_BEGIN
      10             : 
      11             : /* FD_KEYGUARD_SIGN_REQ_MTU is the maximum size (inclusive) of a signing
      12             :    request payload.  The payload in this case is the message byte array
      13             :    passed to fd_ed25519_sign. */
      14             : 
      15           0 : #define FD_KEYGUARD_SIGN_REQ_MTU (2048UL)
      16             : 
      17             : /* Role definitions ***************************************************/
      18             : 
      19           0 : #define FD_KEYGUARD_ROLE_SEND         (0)  /* vote transaction sender */
      20           0 : #define FD_KEYGUARD_ROLE_GOSSIP       (1)  /* gossip participant */
      21           0 : #define FD_KEYGUARD_ROLE_LEADER       (2)  /* block producer (shreds) */
      22           0 : #define FD_KEYGUARD_ROLE_REPAIR       (4)  /* Repair tile */
      23           0 : #define FD_KEYGUARD_ROLE_BUNDLE       (5)  /* Bundle tile */
      24           0 : #define FD_KEYGUARD_ROLE_EVENT        (6)  /* Event tile */
      25           0 : #define FD_KEYGUARD_ROLE_BUNDLE_CRANK (7)  /* Sign cranking transactions for bundle tips */
      26             : #define FD_KEYGUARD_ROLE_CNT          (8)  /* number of known roles */
      27             : 
      28             : /* Payload types ******************************************************/
      29             : 
      30           0 : #define FD_KEYGUARD_PAYLOAD_LG_TXN    ( 0)  /* Solana transaction message (e.g. vote) */
      31           0 : #define FD_KEYGUARD_PAYLOAD_LG_GOSSIP ( 1)  /* Gossip CrdsData */
      32           0 : #define FD_KEYGUARD_PAYLOAD_LG_PRUNE  ( 2)  /* Gossip PruneData */
      33           0 : #define FD_KEYGUARD_PAYLOAD_LG_SHRED  ( 3)  /* Solana legacy or merkle shred */
      34           0 : #define FD_KEYGUARD_PAYLOAD_LG_TLS_CV ( 4)  /* TLS 1.3 certificate verify payload */
      35           0 : #define FD_KEYGUARD_PAYLOAD_LG_REPAIR ( 6)  /* RepairProtocol */
      36           0 : #define FD_KEYGUARD_PAYLOAD_LG_PING   ( 7)  /* Gossip ping protocol */
      37           0 : #define FD_KEYGUARD_PAYLOAD_LG_BUNDLE ( 8)  /* Bundle block producer authentication */
      38           0 : #define FD_KEYGUARD_PAYLOAD_LG_EVENT  ( 9)  /* Event reporter authentication */
      39           0 : #define FD_KEYGUARD_PAYLOAD_LG_PONG   (10)  /* Gossip/Repair ping/pong protocol */
      40             : 
      41           0 : #define FD_KEYGUARD_PAYLOAD_TXN    (1UL<<FD_KEYGUARD_PAYLOAD_LG_TXN   )
      42           0 : #define FD_KEYGUARD_PAYLOAD_GOSSIP (1UL<<FD_KEYGUARD_PAYLOAD_LG_GOSSIP)
      43           0 : #define FD_KEYGUARD_PAYLOAD_PRUNE  (1UL<<FD_KEYGUARD_PAYLOAD_LG_PRUNE )
      44           0 : #define FD_KEYGUARD_PAYLOAD_SHRED  (1UL<<FD_KEYGUARD_PAYLOAD_LG_SHRED )
      45           0 : #define FD_KEYGUARD_PAYLOAD_TLS_CV (1UL<<FD_KEYGUARD_PAYLOAD_LG_TLS_CV)
      46           0 : #define FD_KEYGUARD_PAYLOAD_REPAIR (1UL<<FD_KEYGUARD_PAYLOAD_LG_REPAIR)
      47           0 : #define FD_KEYGUARD_PAYLOAD_PING   (1UL<<FD_KEYGUARD_PAYLOAD_LG_PING  )
      48           0 : #define FD_KEYGUARD_PAYLOAD_BUNDLE (1UL<<FD_KEYGUARD_PAYLOAD_LG_BUNDLE)
      49           0 : #define FD_KEYGUARD_PAYLOAD_EVENT  (1UL<<FD_KEYGUARD_PAYLOAD_LG_EVENT )
      50           0 : #define FD_KEYGUARD_PAYLOAD_PONG   (1UL<<FD_KEYGUARD_PAYLOAD_LG_PONG  )
      51             : 
      52             : /* Sign types *********************************************************/
      53             : 
      54           9 : #define FD_KEYGUARD_SIGN_TYPE_ED25519                          (0)  /* ed25519_sign(input) */
      55           0 : #define FD_KEYGUARD_SIGN_TYPE_SHA256_ED25519                   (1)  /* ed25519_sign(sha256(data)) */
      56           0 : #define FD_KEYGUARD_SIGN_TYPE_PUBKEY_CONCAT_ED25519            (2)  /* ed25519_sign(pubkey-data) */
      57           0 : #define FD_KEYGUARD_SIGN_TYPE_FD_METRICS_REPORT_CONCAT_ED25519 (3)  /* ed25519_sign(FD_METRICS_REPORT-data)) */
      58             : 
      59             : /* Type confusion/ambiguity checks ************************************/
      60             : 
      61             : /* fd_keyguard_payload_match returns a bitwise OR of
      62             :    FD_KEYGUARD_PAYLOAD_{...}.
      63             : 
      64             :    [data,data+sz) is the payload that is requested to be signed.
      65             : 
      66             :    sign_type is in FD_KEYGUARD_SIGN_TYPE_{...}.
      67             : 
      68             :    Returns 0 if none matched.  fd_ulong_popcnt(return value) is 1 if the
      69             :    payload is unambiguously of a single type. */
      70             : 
      71             : FD_FN_PURE ulong
      72             : fd_keyguard_payload_match( uchar const * data,
      73             :                            ulong         sz,
      74             :                            int           sign_type );
      75             : 
      76             : /* Authorization ******************************************************/
      77             : 
      78             : struct fd_keyguard_authority {
      79             :   uchar identity_pubkey[32];
      80             : };
      81             : 
      82             : typedef struct fd_keyguard_authority fd_keyguard_authority_t;
      83             : 
      84             : /* fd_keyguard_payload_authorize decides whether the keyguard accepts
      85             :    a signing request.
      86             : 
      87             :    [data,data+sz) is the payload that is requested to be signed.
      88             : 
      89             :    role is one of FD_KEYGUARD_ROLE_{...}.  It is assumed that the origin
      90             :    of the request was previously authorized for the given role.
      91             : 
      92             :    Returns 1 if authorized, otherwise 0.
      93             : 
      94             :    This function is more restrictive than the respective
      95             :    fd_keyguard_payload_matches functions. */
      96             : 
      97             : int
      98             : fd_keyguard_payload_authorize( fd_keyguard_authority_t const * authority,
      99             :                                uchar const *                   data,
     100             :                                ulong                           sz,
     101             :                                int                             role,
     102             :                                int                             sign_type );
     103             : 
     104             : FD_PROTOTYPES_END
     105             : 
     106             : #endif /* HEADER_fd_src_disco_keyguard_fd_keyguard_h */