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 (32768UL)
      16             : 
      17             : 
      18             : /* FD_KEYGUARD_AUTH_VOTERS_MAX is the maximum number of authorized voter
      19             :    keys the sign tile holds besides the identity.  An authority_idx is
      20             :    ULONG_MAX for the identity or in [0,FD_KEYGUARD_AUTH_VOTERS_MAX).
      21             :    Vote transaction and Alpenglow vote signing requests encode
      22             :    authority_idx in 4 bits of the frag sig. */
      23             : 
      24           0 : #define FD_KEYGUARD_AUTH_VOTERS_MAX (16UL)
      25             : FD_STATIC_ASSERT( FD_KEYGUARD_AUTH_VOTERS_MAX<=16UL, auth_voters_max_fits_sign_request );
      26             : 
      27             : /* Role definitions ***************************************************/
      28             : 
      29           0 : #define FD_KEYGUARD_ROLE_TXSEND       (0)  /* vote transaction sender */
      30           0 : #define FD_KEYGUARD_ROLE_GOSSIP       (1)  /* gossip participant */
      31           0 : #define FD_KEYGUARD_ROLE_LEADER       (2)  /* block producer (shreds) */
      32           0 : #define FD_KEYGUARD_ROLE_REPAIR       (4)  /* Repair tile */
      33           0 : #define FD_KEYGUARD_ROLE_BUNDLE       (5)  /* Bundle tile */
      34           0 : #define FD_KEYGUARD_ROLE_EVENT        (6)  /* Event tile */
      35           0 : #define FD_KEYGUARD_ROLE_BUNDLE_CRANK (7)  /* Sign cranking transactions for bundle tips */
      36           0 : #define FD_KEYGUARD_ROLE_RSERVE       (8)  /* Repair server tile */
      37           0 : #define FD_KEYGUARD_ROLE_VOTOR        (9)  /* Alpenglow votor tile (QUIC TLS, vote history file) */
      38           0 : #define FD_KEYGUARD_ROLE_TOWER        (10) /* Tower tile (tower file) */
      39           0 : #define FD_KEYGUARD_ROLE_CNT          (11) /* number of known roles */
      40             : 
      41             : /* Payload types ******************************************************/
      42             : 
      43           0 : #define FD_KEYGUARD_PAYLOAD_LG_TXN          ( 0)  /* Solana transaction message (e.g. vote) */
      44           0 : #define FD_KEYGUARD_PAYLOAD_LG_GOSSIP       ( 1)  /* Gossip CrdsData */
      45           0 : #define FD_KEYGUARD_PAYLOAD_LG_PRUNE        ( 2)  /* Gossip PruneData */
      46           0 : #define FD_KEYGUARD_PAYLOAD_LG_SHRED        ( 3)  /* Solana legacy or merkle shred */
      47           0 : #define FD_KEYGUARD_PAYLOAD_LG_TLS_CV       ( 4)  /* TLS 1.3 certificate verify payload */
      48           0 : #define FD_KEYGUARD_PAYLOAD_LG_REPAIR       ( 6)  /* RepairProtocol */
      49           0 : #define FD_KEYGUARD_PAYLOAD_LG_PING         ( 7)  /* Gossip ping protocol */
      50           0 : #define FD_KEYGUARD_PAYLOAD_LG_BUNDLE       ( 8)  /* Bundle block producer authentication */
      51           0 : #define FD_KEYGUARD_PAYLOAD_LG_EVENT        ( 9)  /* Event reporter authentication */
      52           0 : #define FD_KEYGUARD_PAYLOAD_LG_PONG         (10)  /* Gossip/Repair ping/pong protocol */
      53           0 : #define FD_KEYGUARD_PAYLOAD_LG_AG_VOTE      (11)  /* Alpenglow BLS vote */
      54           0 : #define FD_KEYGUARD_PAYLOAD_LG_BLS_PUBKEY   (12)  /* Alpenglow BLS public key query */
      55           0 : #define FD_KEYGUARD_PAYLOAD_LG_TOWER        (13)  /* Tower file */
      56           0 : #define FD_KEYGUARD_PAYLOAD_LG_VOTE_HISTORY (14)  /* Alpenglow vote history file */
      57             : 
      58           0 : #define FD_KEYGUARD_PAYLOAD_TXN          (1UL<<FD_KEYGUARD_PAYLOAD_LG_TXN         )
      59           0 : #define FD_KEYGUARD_PAYLOAD_GOSSIP       (1UL<<FD_KEYGUARD_PAYLOAD_LG_GOSSIP      )
      60           0 : #define FD_KEYGUARD_PAYLOAD_PRUNE        (1UL<<FD_KEYGUARD_PAYLOAD_LG_PRUNE       )
      61           0 : #define FD_KEYGUARD_PAYLOAD_SHRED        (1UL<<FD_KEYGUARD_PAYLOAD_LG_SHRED       )
      62           0 : #define FD_KEYGUARD_PAYLOAD_TLS_CV       (1UL<<FD_KEYGUARD_PAYLOAD_LG_TLS_CV      )
      63           0 : #define FD_KEYGUARD_PAYLOAD_REPAIR       (1UL<<FD_KEYGUARD_PAYLOAD_LG_REPAIR      )
      64           0 : #define FD_KEYGUARD_PAYLOAD_PING         (1UL<<FD_KEYGUARD_PAYLOAD_LG_PING        )
      65           0 : #define FD_KEYGUARD_PAYLOAD_BUNDLE       (1UL<<FD_KEYGUARD_PAYLOAD_LG_BUNDLE      )
      66           0 : #define FD_KEYGUARD_PAYLOAD_EVENT        (1UL<<FD_KEYGUARD_PAYLOAD_LG_EVENT       )
      67           0 : #define FD_KEYGUARD_PAYLOAD_PONG         (1UL<<FD_KEYGUARD_PAYLOAD_LG_PONG        )
      68           0 : #define FD_KEYGUARD_PAYLOAD_AG_VOTE      (1UL<<FD_KEYGUARD_PAYLOAD_LG_AG_VOTE     )
      69           0 : #define FD_KEYGUARD_PAYLOAD_BLS_PUBKEY   (1UL<<FD_KEYGUARD_PAYLOAD_LG_BLS_PUBKEY  )
      70           0 : #define FD_KEYGUARD_PAYLOAD_TOWER        (1UL<<FD_KEYGUARD_PAYLOAD_LG_TOWER       )
      71           0 : #define FD_KEYGUARD_PAYLOAD_VOTE_HISTORY (1UL<<FD_KEYGUARD_PAYLOAD_LG_VOTE_HISTORY)
      72             : 
      73             : /* Sign types *********************************************************/
      74             : 
      75           0 : #define FD_KEYGUARD_SIGN_TYPE_ED25519               (0)  /* ed25519_sign(input) */
      76           0 : #define FD_KEYGUARD_SIGN_TYPE_SHA256_ED25519        (1)  /* ed25519_sign(sha256(data)) */
      77           0 : #define FD_KEYGUARD_SIGN_TYPE_PUBKEY_CONCAT_ED25519 (2)  /* ed25519_sign(pubkey-data) */
      78           0 : #define FD_KEYGUARD_SIGN_TYPE_BLS                   (3)  /* bls_sign(vote) */
      79           0 : #define FD_KEYGUARD_SIGN_TYPE_BLS_PUBKEY            (4)  /* ulong authority index -> 48-byte public key, no signing */
      80           0 : #define FD_KEYGUARD_SIGN_TYPE_CNT                   (5)  /* number of sign types */
      81             : 
      82             : /* Type confusion/ambiguity checks ************************************/
      83             : 
      84             : /* fd_keyguard_payload_match returns a bitwise OR of
      85             :    FD_KEYGUARD_PAYLOAD_{...}.
      86             : 
      87             :    [data,data+sz) is the payload that is requested to be signed.
      88             : 
      89             :    sign_type is in FD_KEYGUARD_SIGN_TYPE_{...}.
      90             : 
      91             :    Returns 0 if none matched.  fd_ulong_popcnt(return value) is 1 if the
      92             :    payload is unambiguously of a single type. */
      93             : 
      94             : FD_FN_PURE ulong
      95             : fd_keyguard_payload_match( uchar const * data,
      96             :                            ulong         sz,
      97             :                            int           sign_type );
      98             : 
      99             : /* Authorization ******************************************************/
     100             : 
     101             : struct fd_keyguard_authority {
     102             :   uchar identity_pubkey[32];
     103             :   /* Pack tile is allowed to sign a transaction that invokes these two
     104             :      programs that come from the config.toml.  We need to check these
     105             :      programs, because otherwise an attacker with RCE on pack can make
     106             :      the validator sign a transaction that invokes their malicious
     107             :      program which drains the identity key. */
     108             :   uchar tip_payment_program[32];
     109             :   uchar tip_distribution_program[32];
     110             : };
     111             : 
     112             : typedef struct fd_keyguard_authority fd_keyguard_authority_t;
     113             : 
     114             : /* fd_keyguard_payload_authorize decides whether the keyguard accepts
     115             :    a signing request.
     116             : 
     117             :    [data,data+sz) is the payload that is requested to be signed.
     118             : 
     119             :    role is one of FD_KEYGUARD_ROLE_{...}.  It is assumed that the origin
     120             :    of the request was previously authorized for the given role.
     121             : 
     122             :    Returns 1 if authorized, otherwise 0.
     123             : 
     124             :    This function is more restrictive than the respective
     125             :    fd_keyguard_payload_matches functions. */
     126             : 
     127             : int
     128             : fd_keyguard_payload_authorize( fd_keyguard_authority_t const * authority,
     129             :                                uchar const *                   data,
     130             :                                ulong                           sz,
     131             :                                int                             role,
     132             :                                int                             sign_type );
     133             : 
     134             : FD_PROTOTYPES_END
     135             : 
     136             : #endif /* HEADER_fd_src_disco_keyguard_fd_keyguard_h */