PCP server - CGN API

VERSION

Full explicit dynamic management by the PCP server, strict randomized
external port by the CGN.

ERRORS:

 For all routines, internal error and invalid argument error, even
both should never happen...

ROUTINES

 list_pcp_pool:
   - IN: none
   - OUT: a list of pool entry structure with
     * external address
     * protocol (tcp or udp)
     * start of the external port range (aka minimum port)
     * end of the external port range (aka maximum port)
   - ERRORS: none
   - DESCRIPTION: provides at startup to the PCP server
    the external port pool reserved for explicit dynamic mappings
   - COMMENTS: the list should not be empty, one range per protocol
    and external address

 get_subscriber:
  - IN: subscriber ID
  - OUT: subscriber handle
  - ERRORS: not authorized, resources exhaution
  - DESCRIPTION: maps the subscriber ID to a handle for further references
  - COMMENTS: the subscriber handle must give access to
   the (*stable*) external address associated with the subscriber

 create_subscriber:
  - IN: subscriber ID
  - IN: external address
  - OUT: subscriber handle
  - ERRORS: same than get_subscriber + already exists with a different
   external address
  - DESCRIPTION: same than get_subscriber but enforcing the external address
  - COMMENTS: used by the PCP server to recover from CGN crash,
   the idea is to enforce the stability of the external address
   for all known (i.e., already seen) subscribers

Note there is no delete_subscriber as this function is not part of PCP
but a callback with a similar name

 create_pcp_mapping:
  - IN: subscriber handle
  - IN: protocol (tcp or udp)
  - IN: internal address
  - IN: internal port
  - IN: external address
  - IN: external port
  - OUT: pcp_map handle
  - ERRORS:
   * internal address not authorized
   * bad external address (cf create_subscriber, shouldn't happen)
   * collision with a mapping of another type
   * resources exhaution (not including quota)
  - DESCRIPTION: create if not already exists with the same parameters
   an explicit dynamic mapping
  - COMMENTS: idempotent operation, shouldn't fail for a bad/inuse
   external port

 delete_pcp_mapping:
  - IN: pcp_map handle
  - OUT: none
  - ERRORS: none
  - DESCRIPTION: delete an explicit dynamic mapping
  - COMMENTS: can't fail (no possible recovery), the handle is no
   longer usable after this operation

 unlock_dynamic:
  - IN: none
  - OUT: none
  - ERRORS: none?
  - DESCRIPTION: unlock the creation of new implicit dynamic mappings
  - COMMENTS: when the PCP server crashes the CGN must detect this
   condition and:
    - flush all the explicit dynamic mappings created by the PCP server
    - block the creation of new implicit dynamic mappings so traffic
     from clients, in particular UDP traffic, can't create conflicting
     implicit dynamic mappings

 add_dynamic_map:
  - IN: subscriber handle
  - IN: protocol (tcp or udp)
  - IN: internal address
  - IN: internal port
  - IN: destination address
  - IN: destination port
  - IN: external address
  - IN: external port
  - IN: lifetime
  - OUT: external port
  - OUT: lifetime
  - ERRORS:
   * internal address not authorized
   * bad external address (cf create_subscriber, shouldn't happen)
   * collision with a mapping of another type
   * resources exhaution (including quota, i.e., 2 different errors)   
  - DESCRIPTION: create if not already exists with the same parameters
   (at the exception of the lifetime) an implicit dynamic mapping
  - COMMENTS: the external port is always (randomly) allocated by
   the CGN, the behavior for the lifetime is CGN dependent

 replace_filter: automic delete_filter + create_filter

 delete_filter:
  - IN: pcp_map handle
  - OUT: none
  - ERRORS: none
  - DESCRIPTION: delete the filter if it exists associated with the
   explicit dynamic mapping
  - COMMENTS: can't fail (no possible recovery), filters are supported
   only for explicit dynamic mappings and at most one filter is supported
   per explicit dynamic mapping

 create_filter:
  - IN: pcp_map handle
  - IN: destination prefix length
  - IN: destination address
  - IN: destination port
  - OUT: none
  - ERRORS:
   * collision, i.e., there was already a filter
   * resources exhaution (including quota if the API is extended
    to multiple filters)
  - DESCRIPTION: create a new filter and associates it with the
   explicit dynamic mapping
  - COMMENTS: destination port zero means than any port matches

CALLBACKS

 callback deleted_subscriber:
  - IN: subscriber handle
  - OUT: none
  - DESCRIPTION: called by the CGN when a subscriber is deleted
   (through an administration interface)
  - COMMENTS: as all the mappings of a subscriber are deleted
   at the same time than the subscriber themself, all the corresponding
   pcp_map handles must be flushed
  
SOCKETS

 - local TCP/IPv4 control channel with the CGN:
  * local for limiting the access
  * TCP for detecting PCP server crash

 - Either for the PCP service for DS-Lite:
  * in plain mode a UDP/IPv6 service on port 5351

  * in encapsulation mode a local UDP/IPv4 channel with the CGN,
   the format of messages is the subscriber ID (B4 IPv6 address)
   followed by the decapsulated UDP/IPv4 PCP message

COMMENTS

actions by the PCP server in its initialization phase:
 - open a communication channel with the CGN
 - register the deleted_subscriber callback
 - get the PCP pool via list_pcp_pool
 - restore from stable storage subscribers (create_subscriber),
  explicit dynamic mappings (create_pcp_mapping) and filters
  (replace_filter)
 - unlock the creation of new implicit dynamic mappings (unlock_dynamic)
 - setup the PCP service

hold down:
 - the PCP server deletes expired explicit dynamic entries
 - the PCP server keeps the pcp_map data structure (but without
  the handle) for a hold down/possible host reuse delay, then free it

the PCP server needs PCP requests, the subscriber ID if it is not
part of IP packets carrying PCP requests, the type of subscriber IDs,
the address families supported by the CGN and a way to send back
PCP responses to subscribers.

the subscriber ID authorization and the internal address validation
is handled by the CGN (i.e., in the same way than for standard traffic)
