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