pcp.h raw

   1  // Copyright (c) 2024-present The Bitcoin Core developers
   2  // Distributed under the MIT software license, see the accompanying
   3  // file COPYING or https://www.opensource.org/licenses/mit-license.php.
   4  
   5  #ifndef BITCOIN_COMMON_PCP_H
   6  #define BITCOIN_COMMON_PCP_H
   7  
   8  #include <netaddress.h>
   9  #include <util/threadinterrupt.h>
  10  
  11  #include <variant>
  12  
  13  // RFC6886 NAT-PMP and RFC6887 Port Control Protocol (PCP) implementation.
  14  // NAT-PMP and PCP use network byte order (big-endian).
  15  
  16  //! Mapping nonce size in bytes (see RFC6887 section 11.1).
  17  constexpr size_t PCP_MAP_NONCE_SIZE = 12;
  18  
  19  //! PCP mapping nonce. Arbitrary data chosen by the client to identify a mapping.
  20  typedef std::array<uint8_t, PCP_MAP_NONCE_SIZE> PCPMappingNonce;
  21  
  22  //! Unsuccessful response to a port mapping.
  23  enum class MappingError {
  24      NETWORK_ERROR,  ///< Any kind of network-level error.
  25      PROTOCOL_ERROR, ///< Any kind of protocol-level error, except unsupported version or no resources.
  26      UNSUPP_VERSION, ///< Unsupported protocol version.
  27      NO_RESOURCES,   ///< No resources available (port probably already mapped).
  28  };
  29  
  30  //! Successful response to a port mapping.
  31  struct MappingResult {
  32      MappingResult(uint8_t version, const CService &internal_in, const CService &external_in, uint32_t lifetime_in):
  33          version(version), internal(internal_in), external(external_in), lifetime(lifetime_in) {}
  34      //! Protocol version, one of NATPMP_VERSION or PCP_VERSION.
  35      uint8_t version;
  36      //! Internal host:port.
  37      CService internal;
  38      //! External host:port.
  39      CService external;
  40      //! Granted lifetime of binding (seconds).
  41      uint32_t lifetime;
  42  
  43      //! Format mapping as string for logging.
  44      std::string ToString() const;
  45  };
  46  
  47  //! Try to open a port using RFC 6886 NAT-PMP. IPv4 only.
  48  //!
  49  //! * gateway: Destination address for PCP requests (usually the default gateway).
  50  //! * port: Internal port, and desired external port.
  51  //! * lifetime: Requested lifetime in seconds for mapping. The server may assign as shorter or longer lifetime. A lifetime of 0 deletes the mapping.
  52  //! * num_tries: Number of tries in case of no response.
  53  //!
  54  //! Returns the external_ip:external_port of the mapping if successful, otherwise a MappingError.
  55  std::variant<MappingResult, MappingError> NATPMPRequestPortMap(const CNetAddr &gateway, uint16_t port, uint32_t lifetime, CThreadInterrupt& interrupt, int num_tries = 3, std::chrono::milliseconds timeout_per_try = std::chrono::milliseconds(1000));
  56  
  57  //! Try to open a port using RFC 6887 Port Control Protocol (PCP). Handles IPv4 and IPv6.
  58  //!
  59  //! * nonce: Mapping cookie. Keep this the same over renewals.
  60  //! * gateway: Destination address for PCP requests (usually the default gateway).
  61  //! * bind: Specific local bind address for IPv6 pinholing. Set this as INADDR_ANY for IPv4.
  62  //! * port: Internal port, and desired external port.
  63  //! * lifetime: Requested lifetime in seconds for mapping. The server may assign as shorter or longer lifetime. A lifetime of 0 deletes the mapping.
  64  //! * num_tries: Number of tries in case of no response.
  65  //!
  66  //! Returns the external_ip:external_port of the mapping if successful, otherwise a MappingError.
  67  std::variant<MappingResult, MappingError> PCPRequestPortMap(const PCPMappingNonce &nonce, const CNetAddr &gateway, const CNetAddr &bind, uint16_t port, uint32_t lifetime, CThreadInterrupt& interrupt, int num_tries = 3, std::chrono::milliseconds timeout_per_try = std::chrono::milliseconds(1000));
  68  
  69  #endif // BITCOIN_COMMON_PCP_H
  70