libpcpd — port-control-protocol server library
#include <pcpd.h>
int pcpd_cgn_init( |
pcpd_t *pcpd, |
int argc, | |
char *argv[]) ; |
int pcpd_cgn_close( |
pcpd_t *pcpd) ; |
int pcpd_cgn_register( |
pcpd_t *pcpd, |
pcpd_announce type * announce_callback, | |
pcpd_update type * update_callback, | |
pcpd_uncache type *
uncache_callback) ; |
int pcpd_lib_init( |
pcpd_t *pcpd) ; |
int pcpd_lib_close( |
const pcpd_t *pcpd) ; |
int pcpd_lib_runonce( |
const pcpd_t *pcpd, |
const pcpctx_t *ctx) ; |
void pcpd_announce( |
const pcpd_t *pcpd, |
const pcpctx_t *ctx, | |
const time_t epoch) ; |
void pcpd_update( |
const pcpd_t *pcpd, |
const pcpctx_t *ctx, | |
const uint8_t protocol, | |
const uint8_t *intaddr, | |
const uint8_t *extaddr, | |
const uint16_t extport, | |
const uint32_t lifetime) ; |
void pcpd_update_recycle( |
const pcpd_t *pcpd, |
const pcpctx_t *ctx, | |
const size_t length, | |
const uint8_t *extaddr, | |
const uint16_t extport, | |
const uint32_t lifetime) ; |
void pcpd_uncache( |
const pcpd_t *pcpd, |
const pcpctx_t *ctx) ; |
const char *pcpd_strerror( |
int error) ; |
const char *pcpd_id2str( |
const pcpd_t *pcpd, |
const uint8_t *sid) ; |
pcpd_t object
size_t (*pcpd_recvrequest)( |
const pcpd_t *pcpd, |
const pcpctx_t *ctx) ; |
void (*pcpd_sendresponse)( |
const pcpd_t *pcpd, |
const pcpctx_t *ctx, | |
const size_t length) ; |
int (*pcpd_getsubscriber)( |
const pcpd_t *pcpd, |
const pcpctx_t *ctx, | |
time_t *epoch) ; |
int (*pcpd_authorize)( |
const pcpd_t *pcpd, |
const pcpctx_t *ctx, | |
const size_t length, | |
const size_t off3rdpty) ; |
int (*pcpd_addmapping)( |
const pcpd_t *pcpd, |
const pcpctx_t *ctx, | |
const uint8_t flags, | |
const uint8_t proto, | |
const uint8_t *intaddr, | |
const uint16_t intport, | |
uint8_t *extaddr, | |
uint16_t *extport, | |
uint32_t *lifetime) ; |
int (*pcpd_delmapping)( |
const pcpd_t *pcpd, |
const pcpctx_t *ctx, | |
const uint8_t proto, | |
const uint8_t *intaddr, | |
const uint16_t intport) ; |
int (*pcpd_adddynamic)( |
const pcpd_t *pcpd, |
const pcpctx_t *ctx, | |
const uint8_t proto, | |
const uint8_t *intaddr, | |
const uint16_t intport, | |
const uint8_t *peeraddr, | |
const uint16_t peerport, | |
uint8_t *extaddr, | |
uint16_t *extport, | |
uint32_t *lifetime) ; |
int (*pcpd_filter)( |
const pcpd_t *pcpd, |
const pcpctx_t *ctx, | |
const uint8_t proto, | |
const uint8_t *intaddr, | |
const uint16_t intport, | |
const uint8_t flags, | |
const uint8_t count, | |
const filter_t *filters) ; |
void (*pcpd_incrcounter)( |
const pcpd_t *pcpd, |
const pcpstat_t code, | |
const uint8_t idx) ; |
The _cgn_ functions are for the active/master mode of the library,
i.e., when the main loop is run by the library itself. The _lib_
functions are for the passive/slave mode of the library, i.e., when the
main loop is run by the CGN and pcpd_lib_runonce
is called called when a PCP packet is intercepted.
pcpd_cgn_init
calls for a PCP server handler
initialization with stripped command line parameters.
pcpd_cgn_close
releases a PCP server handler.
pcpd_cgn_register
registers the
pcpd_announce
,
pcpd_update
, and
pcpd_uncache
callbacks.
pcpd_lib_init
is called for a PCP server handler
initialization. Note: this handler points to an object which must not
be changed in its public part.
pcpd_lib_close
is called to release a PCP
server handler.
pcpd_lib_runonce
is called to receive a PCP
request, process it and send the response.
The ctx
is either a pointer to a context
provided by the caller (note it is its responsibility to clear it
between calls) or NULL (and the context will be allocated on
the stack).
pcpd_announce
callback is called when the CGN
wants to notify subscribers that it has restarted or otherwise lost
state. The pcpd_sendresponse
method is used to
send the ANNOUNCE response packet. If the packet is to be multicast,
the pcpd_sendresponse
method must take whatever
steps are necessary to identify and route the packet - it might
examine the ctx->client
address, or it might
look at the memory address of the ctx
structure itself, or it might even have a separate
pcpd_t
instance for sending multicast, with a
different pcpd_sendresponse
method.
pcpd_update
callback is called when the CGN
has changed the external address of a mapping and wants to notify
the client by sending an updated response.
ctx->response
must point to a buffer of
at least 68 octets - large enough to hold a MAP response and a
possible THIRD_PARTY option.
pcpd_update_recycle
is called when the CGN
has changed the external address of a mapping and wants to
notify the client by sending an updated response. In this
variant, ctx
contains a pointer to a
previous response (with a valid version/first byte) or a
matching request. pcpd_update
updates the
response with the provided extaddr
and extport
.
pcpd_uncache
callback is called when the CGN
has destroyed or reset a subscriber so it must be removed from the
cache.
pcpd_strerror
(weak reference) translates an
error to its human friendly description.
pcpd_id2str
(weak reference) translates an
subscriber identifier to its human friendly description
(in fact IPv6 or IPv4 address).
pcpd_recvrequest
blocks until a PCP request is
available then returns it. On error the returned length is set to 0.
pcpd_sendresponse
sends a PCP response.
pcpd_getsubscriber
checks if a subscriber
is authorized and fills the associated epoch (relative to now).
It can create by side-effect the corresponding state in the CGN.
pcpd_authorize
checks if a syntaxically
correct request is authorized. off3rdpty
in the ctx
argument is the offset to
the THIRD_PARTY option if present in the request or zero if not.
pcpd_addmapping
creates if it doesn't already
exist an explicit dynamic mapping. flags
The PCPD_PREFER_FAILURE
flag raise an error if
the requested external port is not available, the
PCPD_CREATE_AS_LOCKED
flag modifies the returned
code into PCPD_NEWMAPPING
and postpones the
activation of a new explicit dynamic mapping to the successful
call to pcpd_filter
.
pcpd_delmapping
deletes matching explicit
dynamic mapping. It never fails as no recovery is possible.
pcpd_adddynamic
creates if it doesn't already
exist an implicit dynamic mapping. It can raise an error if the
requested external port is not available. On an EIM/EIF CGN
remote peer address and port are ignored.
pcpd_filter
associates remote filters to
an explicit dynamic mapping. The
PCPD_DELETE_FILTERS
flag deletes first
existing filters, the PCPD_UNLOCK_ON_SUCCESS
flag activates new created explicit dynamic mappings on success,
on failure they must be cleaned up.
pcpd_incrcounter
increments the
idx
counter for the
code
(in PCPS_OPERATION
,
PCPS_RESULT
and
PCPS_OPTION
) vector (abstract interface).
the CGN is a plain mode DS-Lite AFTR
the CGN is the ISP part of a NAT444
the CGN is a NAT64 (IPv6 to IPv4 translator)
the CGN is a NAT46 (IPv4 to IPv6 translator)
the CGN is a NPTv6 (IPv6/IPv6 NAT 1:1)
the CGN is an IPv4 firewall
the CGN is an IPv6 firewall
the CGN is a layer2 extended DS-Lite NAT
the ANNOUNCE opcode is supported
the MAP opcode is supported
the PEER opcode is supported
converts source addresses from/to IPv4 mapped
IPv6 address format. Note this flag and related flags are used
to check the syntax of requests, for instance a filter option
with a 33 bit prefix length is rejected during parsing only
when PCPD_MAPDST
is set
converts internal addresses from/to IPv4 mapped IPv6 address format
converts external addresses from/to IPv4 mapped IPv6 address format
converts destination/remote peer addresses from/to IPv4 mapped IPv6 address format
allows other protocols than TCP and UDP (and zero)
allows internal port zero in not delete MAP request
(requires PCPD_OTHERPROTO
allows 1:1 style, i.e., protocol and internal
port zero in not delete MAP request (requires
PCPD_OTHERPROTO
and
PCPD_PORT0
the CGN is a firewall so internal and external ports and addresses must match (requires no PEER support and consistent (none or all) mapped address support)
allows third party options in PCP requests. Note: this flag must be set for the other related third party option flags
allows third party options in PCP requests only when the source address is 192.0.0.2
allows third party options in PCP requests only when they are all-zeroes.
enables the optional ANNOUNCE callback
enables the optional MAP update callback
enables the optional subscriber caching by the PCP engine
already existing static mapping
a new mapping was created
OK
invalid arguments
base for protocol errors
unsupported version
not authorized
malformed request
unsupported opcode
unsupported option
malformed option
network failure
out of resources
unsupported protocol
user exceeded quota
cannot provide external address or port
address mismatch
excessive number of remote peers
generic CGN processing error