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_FAILOV       (10) /* Failover admission proof and TLS */
      39           0 : #define FD_KEYGUARD_ROLE_CNT          (11) /* number of known roles */
      40             : 
      41             : /* The failover identity signs admission proofs, TLS, and the
      42             :    admission payload. */
      43           0 : #define FD_KEYGUARD_FAILOVER_CLIENT_DOMAIN "FD_FAILOVER_CLI1"
      44           0 : #define FD_KEYGUARD_FAILOVER_SERVER_DOMAIN "FD_FAILOVER_SRV1"
      45           0 : #define FD_KEYGUARD_FAILOVER_DOMAIN_SZ     (16UL)
      46           0 : #define FD_KEYGUARD_FAILOVER_PROOF_SZ      (FD_KEYGUARD_FAILOVER_DOMAIN_SZ+32UL)
      47             : 
      48             : /* Payload types ******************************************************/
      49             : 
      50           0 : #define FD_KEYGUARD_PAYLOAD_LG_TXN          ( 0)  /* Solana transaction message (e.g. vote) */
      51           0 : #define FD_KEYGUARD_PAYLOAD_LG_GOSSIP       ( 1)  /* Gossip CrdsData */
      52           0 : #define FD_KEYGUARD_PAYLOAD_LG_PRUNE        ( 2)  /* Gossip PruneData */
      53           0 : #define FD_KEYGUARD_PAYLOAD_LG_SHRED        ( 3)  /* Solana legacy or merkle shred */
      54           0 : #define FD_KEYGUARD_PAYLOAD_LG_TLS_CV       ( 4)  /* TLS 1.3 certificate verify payload */
      55           0 : #define FD_KEYGUARD_PAYLOAD_LG_REPAIR       ( 6)  /* RepairProtocol */
      56           0 : #define FD_KEYGUARD_PAYLOAD_LG_PING         ( 7)  /* Gossip ping protocol */
      57           0 : #define FD_KEYGUARD_PAYLOAD_LG_BUNDLE       ( 8)  /* Bundle block producer authentication */
      58           0 : #define FD_KEYGUARD_PAYLOAD_LG_EVENT        ( 9)  /* Event reporter authentication */
      59           0 : #define FD_KEYGUARD_PAYLOAD_LG_PONG         (10)  /* Gossip/Repair ping/pong protocol */
      60           0 : #define FD_KEYGUARD_PAYLOAD_LG_AG_VOTE      (11)  /* Alpenglow BLS vote */
      61           0 : #define FD_KEYGUARD_PAYLOAD_LG_BLS_PUBKEY   (12)  /* Alpenglow BLS public key query */
      62           0 : #define FD_KEYGUARD_PAYLOAD_LG_VOTE_HISTORY (14)  /* Alpenglow vote history file */
      63           0 : #define FD_KEYGUARD_PAYLOAD_LG_FAILOV       (15)  /* Failover admission proof */
      64             : 
      65           0 : #define FD_KEYGUARD_PAYLOAD_TXN          (1UL<<FD_KEYGUARD_PAYLOAD_LG_TXN         )
      66           0 : #define FD_KEYGUARD_PAYLOAD_GOSSIP       (1UL<<FD_KEYGUARD_PAYLOAD_LG_GOSSIP      )
      67           0 : #define FD_KEYGUARD_PAYLOAD_PRUNE        (1UL<<FD_KEYGUARD_PAYLOAD_LG_PRUNE       )
      68           0 : #define FD_KEYGUARD_PAYLOAD_SHRED        (1UL<<FD_KEYGUARD_PAYLOAD_LG_SHRED       )
      69           0 : #define FD_KEYGUARD_PAYLOAD_TLS_CV       (1UL<<FD_KEYGUARD_PAYLOAD_LG_TLS_CV      )
      70           0 : #define FD_KEYGUARD_PAYLOAD_REPAIR       (1UL<<FD_KEYGUARD_PAYLOAD_LG_REPAIR      )
      71           0 : #define FD_KEYGUARD_PAYLOAD_PING         (1UL<<FD_KEYGUARD_PAYLOAD_LG_PING        )
      72           0 : #define FD_KEYGUARD_PAYLOAD_BUNDLE       (1UL<<FD_KEYGUARD_PAYLOAD_LG_BUNDLE      )
      73           0 : #define FD_KEYGUARD_PAYLOAD_EVENT        (1UL<<FD_KEYGUARD_PAYLOAD_LG_EVENT       )
      74           0 : #define FD_KEYGUARD_PAYLOAD_PONG         (1UL<<FD_KEYGUARD_PAYLOAD_LG_PONG        )
      75           0 : #define FD_KEYGUARD_PAYLOAD_AG_VOTE      (1UL<<FD_KEYGUARD_PAYLOAD_LG_AG_VOTE     )
      76           0 : #define FD_KEYGUARD_PAYLOAD_BLS_PUBKEY   (1UL<<FD_KEYGUARD_PAYLOAD_LG_BLS_PUBKEY  )
      77           0 : #define FD_KEYGUARD_PAYLOAD_VOTE_HISTORY (1UL<<FD_KEYGUARD_PAYLOAD_LG_VOTE_HISTORY)
      78           0 : #define FD_KEYGUARD_PAYLOAD_FAILOV       (1UL<<FD_KEYGUARD_PAYLOAD_LG_FAILOV      )
      79             : 
      80             : /* Sign types *********************************************************/
      81             : 
      82           0 : #define FD_KEYGUARD_SIGN_TYPE_ED25519               (0)  /* ed25519_sign(input) */
      83           0 : #define FD_KEYGUARD_SIGN_TYPE_SHA256_ED25519        (1)  /* ed25519_sign(sha256(data)) */
      84           0 : #define FD_KEYGUARD_SIGN_TYPE_PUBKEY_CONCAT_ED25519 (2)  /* ed25519_sign(pubkey-data) */
      85           0 : #define FD_KEYGUARD_SIGN_TYPE_BLS                   (3)  /* bls_sign(vote) */
      86           0 : #define FD_KEYGUARD_SIGN_TYPE_BLS_PUBKEY            (4)  /* ulong authority index -> 48-byte public key, no signing */
      87           0 : #define FD_KEYGUARD_SIGN_TYPE_CNT                   (5)  /* number of sign types */
      88             : 
      89             : /* Type confusion/ambiguity checks ************************************/
      90             : 
      91             : /* fd_keyguard_payload_match returns a bitwise OR of
      92             :    FD_KEYGUARD_PAYLOAD_{...}.
      93             : 
      94             :    [data,data+sz) is the payload that is requested to be signed.
      95             : 
      96             :    sign_type is in FD_KEYGUARD_SIGN_TYPE_{...}.
      97             : 
      98             :    Returns 0 if none matched.  fd_ulong_popcnt(return value) is 1 if the
      99             :    payload is unambiguously of a single type. */
     100             : 
     101             : FD_FN_PURE ulong
     102             : fd_keyguard_payload_match( uchar const * data,
     103             :                            ulong         sz,
     104             :                            int           sign_type );
     105             : 
     106             : /* Authorization ******************************************************/
     107             : 
     108             : struct fd_keyguard_authority {
     109             :   uchar identity_pubkey[32];
     110             :   /* Pack tile is allowed to sign a transaction that invokes these two
     111             :      programs that come from the config.toml.  We need to check these
     112             :      programs, because otherwise an attacker with RCE on pack can make
     113             :      the validator sign a transaction that invokes their malicious
     114             :      program which drains the identity key. */
     115             :   uchar tip_payment_program[32];
     116             :   uchar tip_distribution_program[32];
     117             : };
     118             : 
     119             : typedef struct fd_keyguard_authority fd_keyguard_authority_t;
     120             : 
     121             : /* fd_keyguard_payload_authorize decides whether the keyguard accepts
     122             :    a signing request.
     123             : 
     124             :    [data,data+sz) is the payload that is requested to be signed.
     125             : 
     126             :    role is one of FD_KEYGUARD_ROLE_{...}.  It is assumed that the origin
     127             :    of the request was previously authorized for the given role.
     128             : 
     129             :    Returns 1 if authorized, otherwise 0.
     130             : 
     131             :    This function is more restrictive than the respective
     132             :    fd_keyguard_payload_matches functions. */
     133             : 
     134             : int
     135             : fd_keyguard_payload_authorize( fd_keyguard_authority_t const * authority,
     136             :                                uchar const *                   data,
     137             :                                ulong                           sz,
     138             :                                int                             role,
     139             :                                int                             sign_type );
     140             : 
     141             : FD_PROTOTYPES_END
     142             : 
     143             : #endif /* HEADER_fd_src_disco_keyguard_fd_keyguard_h */