Line data Source code
1 : // Copyright (c) 2024 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 66 : struct MappingResult {
32 33 : MappingResult(uint8_t version, const CService &internal_in, const CService &external_in, uint32_t lifetime_in):
33 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
|