RFC 6940
REsource LOcation And Discovery (RELOAD) Base Protocol
11. Enrollment and Bootstrap
The section defines the format of the configuration data as well the process to join a new overlay.11.1. Overlay Configuration
This specification defines a new content type "application/p2p-overlay+xml" for a MIME entity that contains overlay information. An example document is shown below: <?xml version="1.0" encoding="UTF-8"?> <overlay xmlns="urn:ietf:params:xml:ns:p2p:config-base" xmlns:ext="urn:ietf:params:xml:ns:p2p:config-ext1" xmlns:chord="urn:ietf:params:xml:ns:p2p:config-chord"> <configuration instance-name="overlay.example.org" sequence="22" expiration="2002-10-10T07:00:00Z" ext:ext-example="stuff" > <topology-plugin> CHORD-RELOAD </topology-plugin> <node-id-length>16</node-id-length> <root-cert> MIIDJDCCAo2gAwIBAgIBADANBgkqhkiG9w0BAQUFADBwMQswCQYDVQQGEwJVUzET MBEGA1UECBMKQ2FsaWZvcm5pYTERMA8GA1UEBxMIU2FuIEpvc2UxDjAMBgNVBAoT BXNpcGl0MSkwJwYDVQQLEyBTaXBpdCBUZXN0IENlcnRpZmljYXRlIEF1dGhvcml0 eTAeFw0wMzA3MTgxMjIxNTJaFw0xMzA3MTUxMjIxNTJaMHAxCzAJBgNVBAYTAlVT MRMwEQYDVQQIEwpDYWxpZm9ybmlhMREwDwYDVQQHEwhTYW4gSm9zZTEOMAwGA1UE
ChMFc2lwaXQxKTAnBgNVBAsTIFNpcGl0IFRlc3QgQ2VydGlmaWNhdGUgQXV0aG9y
aXR5MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDDIh6DkcUDLDyK9BEUxkud
+nJ4xrCVGKfgjHm6XaSuHiEtnfELHM+9WymzkBNzZpJu30yzsxwfKoIKugdNUrD4
N3viCicwcN35LgP/KnbN34cavXHr4ZlqxH+OdKB3hQTpQa38A7YXdaoz6goW2ft5
Mi74z03GNKP/G9BoKOGd5QIDAQABo4HNMIHKMB0GA1UdDgQWBBRrRhcU6pR2JYBU
bhNU2qHjVBShtjCBmgYDVR0jBIGSMIGPgBRrRhcU6pR2JYBUbhNU2qHjVBShtqF0
pHIwcDELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNhbGlmb3JuaWExETAPBgNVBAcT
CFNhbiBKb3NlMQ4wDAYDVQQKEwVzaXBpdDEpMCcGA1UECxMgU2lwaXQgVGVzdCBD
ZXJ0aWZpY2F0ZSBBdXRob3JpdHmCAQAwDAYDVR0TBAUwAwEB/zANBgkqhkiG9w0B
AQUFAAOBgQCWbRvv1ZGTRXxbH8/EqkdSCzSoUPrs+rQqR0xdQac9wNY/nlZbkR3O
qAezG6Sfmklvf+DOg5RxQq/+Y6I03LRepc7KeVDpaplMFGnpfKsibETMipwzayNQ
QgUf4cKBiF+65Ue7hZuDJa2EMv8qW4twEhGDYclpFU9YozyS1OhvUg==
</root-cert>
<root-cert> YmFkIGNlcnQK </root-cert>
<enrollment-server>https://example.org</enrollment-server>
<enrollment-server>https://example.net</enrollment-server>
<self-signed-permitted
digest="sha1">false</self-signed-permitted>
<bootstrap-node address="192.0.0.1" port="6084" />
<bootstrap-node address="192.0.2.2" port="6084" />
<bootstrap-node address="2001:DB8::1" port="6084" />
<turn-density> 20 </turn-density>
<clients-permitted> false </clients-permitted>
<no-ice> false </no-ice>
<chord:chord-update-interval>
400</chord:chord-update-interval>
<chord:chord-ping-interval>30</chord:chord-ping-interval>
<chord:chord-reactive> true </chord:chord-reactive>
<shared-secret> password </shared-secret>
<max-message-size>4000</max-message-size>
<initial-ttl> 30 </initial-ttl>
<overlay-reliability-timer> 3000 </overlay-reliability-timer>
<overlay-link-protocol>TLS</overlay-link-protocol>
<configuration-signer>47112162e84c69ba</configuration-signer>
<kind-signer> 47112162e84c69ba </kind-signer>
<kind-signer> 6eba45d31a900c06 </kind-signer>
<bad-node> 6ebc45d31a900c06 </bad-node>
<bad-node> 6ebc45d31a900ca6 </bad-node>
<ext:example-extension> foo </ext:example-extension>
<mandatory-extension>
urn:ietf:params:xml:ns:p2p:config-ext1
</mandatory-extension>
<required-kinds>
<kind-block>
<kind name="SIP-REGISTRATION">
<data-model>SINGLE</data-model>
<access-control>USER-MATCH</access-control>
<max-count>1</max-count>
<max-size>100</max-size>
</kind>
<kind-signature>
VGhpcyBpcyBub3QgcmlnaHQhCg==
</kind-signature>
</kind-block>
<kind-block>
<kind id="2000">
<data-model>ARRAY</data-model>
<access-control>NODE-MULTIPLE</access-control>
<max-node-multiple>3</max-node-multiple>
<max-count>22</max-count>
<max-size>4</max-size>
<ext:example-kind-extension> 1
</ext:example-kind-extension>
</kind>
<kind-signature>
VGhpcyBpcyBub3QgcmlnaHQhCg==
</kind-signature>
</kind-block>
</required-kinds>
</configuration>
<signature> VGhpcyBpcyBub3QgcmlnaHQhCg== </signature>
<configuration instance-name="other.example.net">
</configuration>
<signature> VGhpcyBpcyBub3QgcmlnaHQhCg== </signature>
</overlay>
The file MUST be a well-formed XML document, and it SHOULD contain an
encoding declaration in the XML declaration. The file MUST use the
UTF-8 character encoding. The namespaces for the elements defined in
this specification are urn:ietf:params:xml:ns:p2p:config-base and
urn:ietf:params:xml:ns:p2p:config-chord.
Note that elements or attributes that are defined as type xsd:boolean
in the RELAX NG schema (Section 11.1.1) have two lexical
representations, "1" or "true" for the concept true, and "0" or
"false" for the concept false. Whitespace and case processing
follows the rules of [OASIS.relax_ng] and XML Schema Datatypes
[W3C.REC-xmlschema-2-20041028].
The file MAY contain multiple "configuration" elements, where each
one contains the configuration information for a different overlay.
Each configuration element MAY be followed by signature elements that
provide a signature over the preceding configuration element. Each
configuration element has the following attributes:
instance-name
The name of the overlay (referred to as "overlay name" in this
specification)
expiration
Time in the future at which this overlay configuration is no
longer valid. The node SHOULD retrieve a new copy of the
configuration at a randomly selected time that is before the
expiration time. Note that if the certificates expire before a
new configuration is retried, the node will not be able to
validate the configuration file. All times MUST conform to the
Internet date/time format defined in [RFC3339] and be specified
using UTC.
sequence
A monotonically increasing sequence number between 0 and 2^16-2.
Inside each overlay element, the following elements can occur:
topology-plug-in
This element defines the overlay algorithm being used. If
missing, the default is "CHORD-RELOAD".
node-id-length
This element contains the length of a NodeId (NodeIdLength), in
bytes. This value MUST be between 16 (128 bits) and 20 (160
bits). If this element is not present, the default of 16 is used.
root-cert
This element contains a base-64-encoded X.509v3 certificate that
is a root trust anchor used to sign all certificates in this
overlay. There can be more than one root-cert element.
enrollment-server
This element contains the URL at which the enrollment server can
be reached in a "url" element. This URL MUST be of type "https:".
More than one enrollment-server element MAY be present. Note that
there is no necessary relationship between the overlay name/
configuration server name and the enrollment server name.
self-signed-permitted
This element indicates whether self-signed certificates are
permitted. If it is set to "true", then self-signed certificates
are allowed, in which case the enrollment-server and root-cert
elements MAY be absent. Otherwise, it SHOULD be absent, but MAY
be set to "false". This element also contains an attribute
"digest", which indicates the digest to be used to compute the
Node-ID. Valid values for this parameter are "sha1" and "sha256",
representing SHA-1 [RFC3174] and SHA-256 [RFC6234], respectively.
Implementations MUST support both of these algorithms.
bootstrap-node
This element represents the address of one of the bootstrap nodes.
It has an attribute called "address" that represents the IP
address (either IPv4 or IPv6, since they can be distinguished) and
an optional attribute called "port" that represents the port and
defaults to 6084. The IPv6 address is in typical hexadecimal form
using standard period and colon separators as specified in
[RFC5952]. More than one bootstrap-node element MAY be present.
turn-density
This element is a positive integer that represents the approximate
reciprocal of density of nodes that can act as TURN servers. For
example, if 5% of the nodes can act as TURN servers, this element
would be set to 20. If it is not present, the default value is 1.
If there are no TURN servers in the overlay, it is set to zero.
clients-permitted
This element represents whether clients are permitted or whether
all nodes must be peers. If clients are permitted, the element
MUST be set to "true" or be absent. If the nodes are not allowed
to remain clients after the initial join, the element MUST be set
to "false". There is currently no way for the overlay to enforce
this.
no-ice
This element represents whether nodes are REQUIRED to use the
"No-ICE" Overlay Link protocols in this overlay. If it is absent,
it is treated as if it were set to "false".
chord-update-interval
The update frequency for the CHORD-RELOAD Topology Plug-in (see
Section 10).
chord-ping-interval
The Ping frequency for the CHORD-RELOAD Topology Plug-in (see
Section 10).
chord-reactive
Whether reactive recovery SHOULD be used for this overlay. It is
set to "true" or "false". If missing, the default is "true" (see
Section 10).
shared-secret
If shared secret mode is used, this element contains the shared
secret. The security guarantee here is that any agent which is
able to access the Configuration Document (presumably protected by
some sort of HTTP access control or network topology) is able to
recover the shared secret and hence join the overlay.
max-message-size
Maximum size, in bytes, of any message in the overlay. If this
value is not present, the default is 5000.
initial-ttl
Initial default TTL for messages (see Section 6.3.2). If this
value is not present, the default is 100.
overlay-reliability-timer
Default value for the end-to-end retransmission timer for
messages, in milliseconds. If not present, the default value is
3000. The value MUST be at least 200 milliseconds, which means
the minimum time delay before dropping a link is 1000
milliseconds.
overlay-link-protocol
Indicates a permissible overlay link protocol (see Section 6.6.1
for requirements for such protocols). An arbitrary number of
these elements may appear. If none appear, then this implies the
default value, "TLS", which refers to the use of TLS and DTLS. If
one or more elements appear, then no default value applies.
kind-signer
This contains a single Node-ID in hexadecimal and indicates that
the certificate with this Node-ID is allowed to sign Kinds.
Identifying kind-signer by Node-ID instead of certificate allows
the use of short-lived certificates without constantly having to
provide an updated configuration file.
configuration-signer
This contains a single Node-ID in hexadecimal and indicates that
the certificate with this Node-ID is allowed to sign
configurations for this instance-name. Identifying the signer by
Node-ID instead of certificate allows the use of short-lived
certificates without constantly having to provide an updated
configuration file.
bad-node
This contains a single Node-ID in hexadecimal and indicates that
the certificate with this Node-ID MUST NOT be considered valid.
This allows certificate revocation. An arbitrary number of these
elements can be provided. Note that because certificates may
expire, bad-node entries need be present only for the lifetime of
the certificate. Technically speaking, bad Node-IDs may be reused
after their certificates have expired. The requirement for
Node-IDs to be pseudorandomly generated gives this event a
vanishing probability.
mandatory-extension
This element contains the name of an XML namespace that a node
joining the overlay MUST support. The presence of a mandatory-
extension element does not require the extension to be used in the
current configuration file, but can indicate that it may be used
in the future. Note that the namespace is case-sensitive, as
specified in Section 2.3 of [w3c-xml-namespaces]. More than one
mandatory-extension element MAY be present.
Inside each configuration element, the required-kinds element MAY
also occur. This element indicates the Kinds that members MUST
support and contains multiple kind-block elements that each define a
single Kind that MUST be supported by nodes in the overlay. Each
kind-block consists of a single kind element and a kind-signature.
The kind element defines the Kind. The kind-signature is the
signature computed over the kind element.
Each kind element has either an id attribute or a name attribute.
The name attribute is a string representing the Kind (the name
registered to IANA), while the id is an integer Kind-ID allocated out
of private space.
In addition, the kind element MUST contain the following elements:
max-count
The maximum number of values which members of the overlay must
support.
data-model
The data model to be used.
max-size
The maximum size of individual values.
access-control
The access control model to be used.
The kind element MAY also contain the following element:
max-node-multiple
If the access control is NODE-MULTIPLE, this element MUST be
included. This indicates the maximum value for the i counter. It
MUST be an integer greater than 0.
All of the non-optional values MUST be provided. If the Kind is
registered with IANA, the data-model and access-control elements MUST
match those in the Kind registration, and clients MUST ignore them in
favor of the IANA versions. Multiple kind-block elements MAY be
present.
The kind-block element also MUST contain a "kind-signature" element.
This signature is computed across the kind element from the beginning
of the first < of the kind element to the end of the last > of the
kind element in the same way as the signature element described later
in this section. kind-block elements MUST be signed by a node listed
in the kind-signers block of the current configuration. Receivers
MUST verify the signature prior to accepting a kind-block.
The configuration element MUST be treated as a binary blob that
cannot be changed -- including any whitespace changes -- or the
signature will break. The signature MUST be computed by taking each
configuration element and starting from, and including, the first <
at the start of <configuration> up to and including the > in </
configuration> and treating this as a binary blob that MUST be signed
using the standard SecurityBlock defined in Section 6.3.4. The
SecurityBlock MUST be base-64 encoded using the base64 alphabet from
[RFC4648] and MUST be put in the signature element following the
configuration object in the configuration file. Any configuration
file MUST be signed by one of the configuration-signer elements from
the previous extant configuration. Recipients MUST verify the
signature prior to accepting the configuration file.
When a node receives a new configuration file, it MUST change its
configuration to meet the new requirements. This may require the
node to exit the DHT and rejoin. If a node is not capable of
supporting the new requirements, it MUST exit the overlay. If some
information about a particular Kind changes from what the node
previously knew about the Kind (for example, the max size), the new
information in the configuration files overrides any previously
learned information. If any Kind data was signed by a node that is
no longer allowed to sign Kinds, that Kind MUST be discarded along
with any stored information of that Kind. Note that forcing an
avalanche restart of the overlay with a configuration change that
requires rejoining the overlay may result in serious performance
problems, including total collapse of the network if configuration
parameters are not properly considered. Such an event may be necessary in case of a compromised CA or similar problem, but for large overlays, it should be avoided in almost all circumstances.11.1.1. RELAX NG Grammar
The grammar for the configuration data is: namespace chord = "urn:ietf:params:xml:ns:p2p:config-chord" namespace local = "" default namespace p2pcf = "urn:ietf:params:xml:ns:p2p:config-base" namespace rng = "http://relaxng.org/ns/structure/1.0" anything = (element * { anything } | attribute * { text } | text)* foreign-elements = element * - (p2pcf:* | local:* | chord:*) { anything }* foreign-attributes = attribute * - (p2pcf:*|local:*|chord:*) { text }* foreign-nodes = (foreign-attributes | foreign-elements)* start = element p2pcf:overlay { overlay-element } overlay-element &= element configuration { attribute instance-name { xsd:string }, attribute expiration { xsd:dateTime }?, attribute sequence { xsd:long }?, foreign-attributes*, parameter }+ overlay-element &= element signature { attribute algorithm { signature-algorithm-type }?, xsd:base64Binary }* signature-algorithm-type |= "rsa-sha1" signature-algorithm-type |= xsd:string # signature alg extensions parameter &= element topology-plugin { topology-plugin-type }? topology-plugin-type |= xsd:string # topo plugin extensions parameter &= element max-message-size { xsd:unsignedInt }? parameter &= element initial-ttl { xsd:int }? parameter &= element root-cert { xsd:base64Binary }*
parameter &= element required-kinds { kind-block* }?
parameter &= element enrollment-server { xsd:anyURI }*
parameter &= element kind-signer { xsd:string }*
parameter &= element configuration-signer { xsd:string }*
parameter &= element bad-node { xsd:string }*
parameter &= element no-ice { xsd:boolean }?
parameter &= element shared-secret { xsd:string }?
parameter &= element overlay-link-protocol { xsd:string }*
parameter &= element clients-permitted { xsd:boolean }?
parameter &= element turn-density { xsd:unsignedByte }?
parameter &= element node-id-length { xsd:int }?
parameter &= element mandatory-extension { xsd:string }*
parameter &= foreign-elements*
parameter &=
element self-signed-permitted {
attribute digest { self-signed-digest-type },
xsd:boolean
}?
self-signed-digest-type |= "sha1"
self-signed-digest-type |= xsd:string # signature digest extensions
parameter &= element bootstrap-node {
attribute address { xsd:string },
attribute port { xsd:int }?
}*
kind-block = element kind-block {
element kind {
( attribute name { kind-names }
| attribute id { xsd:unsignedInt } ),
kind-parameter
} &
element kind-signature {
attribute algorithm { signature-algorithm-type }?,
xsd:base64Binary
}?
}
kind-parameter &= element max-count { xsd:int }
kind-parameter &= element max-size { xsd:int }
kind-parameter &= element max-node-multiple { xsd:int }?
kind-parameter &= element data-model { data-model-type }
data-model-type |= "SINGLE"
data-model-type |= "ARRAY"
data-model-type |= "DICTIONARY"
data-model-type |= xsd:string # data model extensions
kind-parameter &= element access-control { access-control-type }
access-control-type |= "USER-MATCH"
access-control-type |= "NODE-MATCH"
access-control-type |= "USER-NODE-MATCH"
access-control-type |= "NODE-MULTIPLE"
access-control-type |= xsd:string # access control extensions
kind-parameter &= foreign-elements*
kind-names |= "TURN-SERVICE"
kind-names |= "CERTIFICATE_BY_NODE"
kind-names |= "CERTIFICATE_BY_USER"
kind-names |= xsd:string # kind extensions
# Chord specific parameters
topology-plugin-type |= "CHORD-RELOAD"
parameter &= element chord:chord-ping-interval { xsd:int }?
parameter &= element chord:chord-update-interval { xsd:int }?
parameter &= element chord:chord-reactive { xsd:boolean }?
11.2. Discovery through Configuration Server
When a node first enrolls in a new overlay, it starts with a
discovery process to find a configuration server.
The node MAY start by determining the overlay name. This value MUST
be provided by the user or some other out-of-band provisioning
mechanism. The out-of-band mechanism MAY also provide an optional
URL for the configuration server. If a URL for the configuration
server is not provided, the node MUST do a DNS SRV query using a
Service name of "reload-config" and a protocol of TCP to find a
configuration server and form the URL by appending a path of
"/.well-known/reload-config" to the overlay name. This uses the
"well-known URI" framework defined in [RFC5785]. For example, if the
overlay name was example.com, the URL would be
"https://example.com/.well-known/reload-config".
Once an address and URL for the configuration server are determined,
the peer MUST form an HTTPS connection to that IP address. If an
optional URL for the configuration server was provided, the
certificate MUST match the domain name from the URL as described in
[RFC2818]; otherwise, the certificate MUST match the overlay name as
described in [RFC2818]. If the HTTPS certificates pass the name
matching, the node MUST fetch a new copy of the configuration file.
To do this, the peer performs a GET to the URL. The result of the
HTTP GET is an XML configuration file described above. If the XML is
not valid or the instance-name attribute of the overlay-element in
the XML does not match the overlay name, this configurations file
SHOULD be discarded. Otherwise, the new configuration MUST replace any previously learned configuration file for this overlay. For overlays that do not use a configuration server, nodes MUST obtain the configuration information needed to join the overlay through some out-of-band approach, such as an XML configuration file sent over email.11.3. Credentials
If the Configuration Document contains an enrollment-server element, credentials are REQUIRED to join the Overlay Instance. A peer which does not yet have credentials MUST contact the enrollment server to acquire them. RELOAD defines its own trivial certificate request protocol. We would have liked to have used an existing protocol, but were concerned about the implementation burden of even the simplest of those protocols, such as [RFC5272] and [RFC5273]. The objective was to have a protocol which could be easily implemented in a Web server which the operator did not control (e.g., in a hosted service) and which was compatible with the existing certificate-handling tooling as used with the Web certificate infrastructure. This means accepting bare PKCS#10 requests and returning a single bare X.509 certificate. Although the MIME types for these objects are defined, none of the existing protocols support exactly this model. The certificate request protocol MUST be performed over HTTPS. The server certificate MUST match the overlay name as described in [RFC2818]. The request MUST be an HTTP POST with the parameters encoded as described in [RFC2388] and with the following properties: o If authentication is required, there MUST be form parameters of "password" and "username" containing the user's account name and password in the clear (hence the need for HTTPS). The username and password strings MUST be UTF-8 strings compared as binary objects. Applications using RELOAD SHOULD define any needed string preparation as per [RFC4013] or its successor documents. o If more than one Node-ID is required, there MUST be a form parameter of "nodeids" containing the number of Node-IDs required. o There MUST be a form parameter of "csr" with a content type of "application/pkcs10", as defined in [RFC2311], that contains the certificate signing request (CSR). o The Accept header MUST contain the type "application/pkix-cert", indicating the type that is expected in the response.
The enrollment server MUST authenticate the request using the provided account name and password. The reason for using the RFC 2388 "multipart/form-data" encoding is so that the password parameter will not be encoded in the URL, to reduce the chance of accidental leakage of the password. If the authentication succeeds and the requested user name in the CSR is acceptable, the server MUST generate and return a certificate for the CSR in the "csr" parameter of the request. The SubjectAltName field in the certificate MUST contain the following values: o One or more Node-IDs which MUST be cryptographically random [RFC4086]. Each MUST be chosen by the enrollment server in such a way that it is unpredictable to the requesting user. For example, the user MUST NOT be informed of potential (random) Node-IDs prior to authenticating. Each is placed in the subjectAltName using the uniformResourceIdentifier type, each MUST contain RELOAD URI, as described in Section 14.15, and each MUST contain a Destination List with a single entry of type "node_id". The enrollment server SHOULD maintain a mapping of users to Node-IDs and if the same user returns (e.g., to have their certificate re-issued), the enrollment server should return the same Node-IDs, thus avoiding the need for implementations to re-store all their data when their certificates expire. o A single name (the "user name") that this user is allowed to use in the overlay, using type rfc822Name. Enrollment servers SHOULD take care to allow only legal characters in the name (e.g., no embedded NULs), rather than simply accepting any name provided by the user. In some usages, the right side of the user name will match the overlay name, but there is no requirement for this match in this specification. Applications using this specification MAY define such a requirement or MAY otherwise limit the allowed range of allowed user names. The SubjectAltName field in the certificate MUST NOT contain any identities other than those listed above. The subject distinguished name in the certificate MUST be empty. The certificate MUST be returned as type "application/pkix-cert", as defined in [RFC2585], with an HTTP status code of 200 OK.
Certificate processing errors SHOULD result in an HTTP return code of
403 Forbidden, along with a body of type "text/plain" and body that
consists of one of the tokens defined in the following list:
failed_authentication
The account name and password combination used in the HTTPS
request was not valid.
username_not_available
The requested user name in the CSR was not acceptable.
Node-IDs_not_available
The number of Node-IDs requested was not acceptable.
bad_CSR
There was some other problem with the CSR.
If the client receives an unknown token in the body, it SHOULD treat
it as a failure for an unknown reason.
The client MUST check that the returned certificate chains back to
one of the certificates received in the "root-cert" list of the
overlay configuration data (including PKIX BasicConstraints checks).
The node then reads the certificate to find the Node-ID it can use.
11.3.1. Self-Generated Credentials
If the "self-signed-permitted" element is present in the
configuration and is set to "true", then a node MUST generate its own
self-signed certificate to join the overlay. The self-signed
certificate MAY contain any user name of the user's choice.
For self-signed certificates containing only one Node-ID, the Node-ID
MUST be computed by applying the digest specified in the self-signed-
permitted element to the DER representation of the user's public key
(more specifically, the subjectPublicKeyInfo) and taking the high-
order bits. For self-signed certificates containing multiple
Node-IDs, the index of the Node-ID (from 1 to the number of Node-IDs
needed) must be prepended as a 4-byte big-endian integer to the DER
representation of the user's public key and taking the high-order
bits. When accepting a self-signed certificate, nodes MUST check
that the Node-ID and public keys match. This prevents Node-ID theft.
Once the node has constructed a self-signed certificate, it MAY join
the overlay. It MUST store its certificate in the overlay
(Section 8), but SHOULD look to see if the user name is already taken
and, if so, choose another user name. Note that this provides
protection only against accidental name collisions. Name theft is
still possible. If protection against name theft is desired, then the enrollment service MUST be used.11.4. Contacting a Bootstrap Node
In order to join the overlay, the Joining Node MUST contact a node in the overlay. Typically this means contacting the bootstrap nodes, since they are reachable by the local peer or have public IP addresses. If the Joining Node has cached a list of peers that it has previously been connected with in this overlay, as an optimization it MAY attempt to use one or more of them as bootstrap nodes before falling back to the bootstrap nodes listed in the configuration file. When contacting a bootstrap node, the Joining Node MUST first form the DTLS or TLS connection to the bootstrap node and then send an Attach request over this connection with the destination Resource-ID set to the Joining Node's Node-ID plus 1. When the requester node finally does receive a response from some responding node, it MUST use the Node-ID in the response to start sending requests to join the Overlay Instance as described in Section 6.4. After a node has successfully joined the overlay network, it will have direct connections to several peers. Some MAY be added to the cached bootstrap nodes list and used in future boots. Peers that are not directly connected MUST NOT be cached. The suggested number of peers to cache is 10. Algorithms for determining which peers to cache are beyond the scope of this specification.12. Message Flow Example
The following abbreviations are used in the message flow diagrams: JN = Joining Node, AP = Admitting Peer, NP = next peer after the AP, NNP = next next peer which is the peer after NP, PP = previous peer before the AP, PPP = previous previous peer which is the peer before the PP, BP = bootstrap node. In the following example, we assume that JN has formed a connection to one of the bootstrap nodes. JN then sends an Attach through that peer to a Resource-ID of itself plus 1 (JN+1). It gets routed to the AP, because JN is not yet part of the overlay. When AP responds, JN and the AP use ICE to set up a connection and then set up DTLS. Once AP has connected to JN, AP sends to JN an Update to populate its Routing Table. The following example shows the Update happening after the DTLS connection is formed, but it could also happen before, in which case the Update would often be routed through other nodes.
JN PPP PP AP NP NNP BP | | | | | | | | | | | | | | | | | | | | | |AttachReq Dest=JN+1| | | | | |---------------------------------------------------------->| | | | | | | | | | | | | | | | | | |AttachReq Dest=JN+1| | | | | |<----------------------------| | | | | | | | | | | | | | | | | | |AttachAns | | | | | |---------------------------->| | | | | | | | | | | | | | | |AttachAns | | | | | |<----------------------------------------------------------| | | | | | | | |ICE | | | | | | |<===========================>| | | | | | | | | | | |TLS | | | | | | |<...........................>| | | | | | | | | | | | | | | | | | | | | | | | | |UpdateReq| | | | | | |<----------------------------| | | | | | | | | | | | | | | | | | |UpdateAns| | | | | | |---------------------------->| | | | | | | | | | | | | | | | | | | | | | | | | Figure 1
The JN then forms connections to the appropriate neighbors, such as NP, by sending an Attach which gets routed via other nodes. When NP responds, JN and NP use ICE and DTLS to set up a connection. JN PPP PP AP NP NNP BP | | | | | | | | | | | | | | | | | | | | | |AttachReq NP | | | | | |---------------------------->| | | | | | | | | | | | | | | | | | | | | |AttachReq NP | | | | | |-------->| | | | | | | | | | | | | | | | | | | | |AttachAns| | | | | | |<--------| | | | | | | | | | | | | | | | | |AttachAns| | | | | | |<----------------------------| | | | | | | | | | | | | | | | | | |ICE | | | | | | |<=====================================>| | | | | | | | | | | | | | | | | |TLS | | | | | | |<.....................................>| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Figure 2
The JN also needs to populate its Finger Table (for the Chord-based DHT). It issues an Attach to a variety of locations around the overlay. The diagram below shows JN sending an Attach halfway around the Chord ring to the JN + 2^127. JN NP XX TP | | | | | | | | | | | | |AttachReq JN+2<<126| | |-------->| | | | | | | | | | | | |AttachReq JN+2<<126| | |-------->| | | | | | | | | | | | |AttachReq JN+2<<126 | | |-------->| | | | | | | | | | | |AttachAns| | | |<--------| | | | | | | | | | |AttachAns| | | |<--------| | | | | | | | | | |AttachAns| | | |<--------| | | | | | | |ICE | | | |<===========================>| | | | | |TLS | | | |<...........................>| | | | | | | | | Figure 3
Once JN has a reasonable set of connections, it is ready to take its place in the DHT. It does this by sending a Join to AP. AP sends a series of Store requests to JN to store the data that JN will be responsible for. AP then sends JN an Update that explicitly labels JN as its predecessor. At this point, JN is part of the ring and is responsible for a section of the overlay. AP can now forget any data which is assigned to JN and not to AP. JN PPP PP AP NP NNP BP | | | | | | | | | | | | | | | | | | | | | |JoinReq | | | | | | |---------------------------->| | | | | | | | | | | | | | | | | | |JoinAns | | | | | | |<----------------------------| | | | | | | | | | | | | | | | | | |StoreReq Data A | | | | | |<----------------------------| | | | | | | | | | | | | | | | | | |StoreAns | | | | | | |---------------------------->| | | | | | | | | | | | | | | | | | |StoreReq Data B | | | | | |<----------------------------| | | | | | | | | | | | | | | | | | |StoreAns | | | | | | |---------------------------->| | | | | | | | | | | | | | | | | | |UpdateReq| | | | | | |<----------------------------| | | | | | | | | | | | | | | | | | |UpdateAns| | | | | | |---------------------------->| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Figure 4
In Chord, JN's Neighbor Table needs to contain its own predecessors.
It couldn't connect to them previously, because it did not yet know
their addresses. However, now that it has received an Update from
AP, as in the previous diagram, it has AP's predecessors, which are
also its own, so it sends Attaches to them. Below, it is shown
connecting only to AP's closest predecessor, PP.
JN PPP PP AP NP NNP BP
| | | | | | |
| | | | | | |
| | | | | | |
|AttachReq Dest=PP | | | | |
|---------------------------->| | | |
| | | | | | |
| | | | | | |
| | |AttachReq Dest=PP | | |
| | |<--------| | | |
| | | | | | |
| | | | | | |
| | |AttachAns| | | |
| | |-------->| | | |
| | | | | | |
| | | | | | |
|AttachAns| | | | | |
|<----------------------------| | | |
| | | | | | |
| | | | | | |
|TLS | | | | | |
|...................| | | | |
| | | | | | |
| | | | | | |
|UpdateReq| | | | | |
|------------------>| | | | |
| | | | | | |
| | | | | | |
|UpdateAns| | | | | |
|<------------------| | | | |
| | | | | | |
| | | | | | |
|UpdateReq| | | | | |
|---------------------------->| | | |
| | | | | | |
| | | | | | |
|UpdateAns| | | | | |
|<----------------------------| | | |
| | | | | | |
| | | | | | |
|UpdateReq| | | | | |
|-------------------------------------->| | | | | | | | | | | | | | | | | |UpdateAns| | | | | | |<--------------------------------------| | | | | | | | | | | | | | | | | Figure 5 Finally, now that JN has a copy of all the data and is ready to route messages and receive requests, it sends Updates to everyone in its Routing Table to tell them it is ready to go. Below, it is shown sending such an update to TP. JN NP XX TP | | | | | | | | | | | | |UpdateReq| | | |---------------------------->| | | | | | | | | |UpdateAns| | | |<----------------------------| | | | | | | | | | | | | | | | | Figure 613. Security Considerations
13.1. Overview
RELOAD provides a generic storage service, albeit one designed to be useful for P2PSIP. In this section, we discuss security issues that are likely to be relevant to any usage of RELOAD. More background information can be found in [RFC5765]. In any Overlay Instance, any given user depends on a number of peers with which they have no well-defined relationship except that they are fellow members of the Overlay Instance. In practice, these other nodes may be friendly, lazy, curious, or outright malicious. No security system can provide complete protection in an environment where most nodes are malicious. The goal of security in RELOAD is to
provide strong security guarantees of some properties even in the face of a large number of malicious nodes and to allow the overlay to function correctly in the face of a modest number of malicious nodes. P2PSIP deployments require the ability to authenticate both peers and resources (users) without the active presence of a trusted entity in the system. We describe two mechanisms. The first mechanism is based on public key certificates and is suitable for general deployments. The second is an admission control mechanism based on an overlay-wide shared symmetric key.13.2. Attacks on P2P Overlays
The two basic functions provided by overlay nodes are storage and routing: some peer is responsible for storing a node's data and for allowing a third node to fetch this stored data, while other peers are responsible for routing messages to and from the storing nodes. Each of these issues is covered in the following sections. P2P overlays are subject to attacks by subversive nodes that may attempt to disrupt routing, corrupt or remove user registrations, or eavesdrop on signaling. The certificate-based security algorithms we describe in this specification are intended to protect overlay routing and user registration information in RELOAD messages. To protect the signaling from attackers pretending to be valid nodes (or nodes other than themselves), the first requirement is to ensure that all messages are received from authorized members of the overlay. For this reason, RELOAD MUST transport all messages over a secure channel (TLS and DTLS are defined in this document) which provides message integrity and authentication of the directly communicating peer. In addition, messages and data MUST be digitally signed with the sender's private key, providing end-to-end security for communications.13.3. Certificate-Based Security
This specification stores users' registrations and possibly other data in an overlay network. This requires a solution both to securing this data and to securing, as well as possible, the routing in the overlay. Both types of security are based on requiring that every entity in the system (whether user or peer) authenticate cryptographically using an asymmetric key pair tied to a certificate. When a user enrolls in the Overlay Instance, they request or are assigned a unique name, such as "alice@dht.example.net". These names MUST be unique and are meant to be chosen and used by humans much like a SIP address-of-record (AOR) or an email address. The user
MUST also be assigned one or more Node-IDs by the central enrollment
authority. Both the name and the Node-IDs are placed in the
certificate, along with the user's public key.
Each certificate enables an entity to act in two sorts of roles:
o As a user, storing data at specific Resource-IDs in the Overlay
Instance corresponding to the user name.
o As a overlay peer with the Node-IDs listed in the certificate.
Note that since only users of this Overlay Instance need to validate
a certificate, this usage does not require a global Public Key
Infrastructure (PKI). Instead, certificates MUST be signed by a
central enrollment authority which acts as the certificate authority
for the Overlay Instance. This authority signs each node's
certificate. Because each node possesses the CA's certificate (which
they receive upon enrollment), they can verify the certificates of
the other entities in the overlay without further communication.
Because the certificates contain the user's/node's public key,
communications from the user/node can, in turn, be verified.
If self-signed certificates are used, then the security provided is
significantly decreased, since attackers can mount Sybil attacks. In
addition, attackers cannot trust the user names in certificates
(although they can trust the Node-IDs, because they are
cryptographically verifiable). This scheme may be appropriate for
some small deployments, such as a small office or an ad hoc overlay
set up among participants in a meeting where all hosts on the network
are trusted. Some additional security can be provided by using the
shared secret admission control scheme as well.
Because all stored data is signed by the owner of the data, the
storing node can verify that the storer is authorized to perform a
store at that Resource-ID and also can allow any consumer of the data
to verify the provenance and integrity of the data when it retrieves
it.
Note that RELOAD does not itself provide a revocation/status
mechanism (although certificates may, of course, include Online
Certificate Status Protocol [OCSP] responder information). Thus,
certificate lifetimes SHOULD be chosen to balance the compromise
window versus the cost of certificate renewal. Because RELOAD is
already designed to operate in the face of some fraction of malicious
nodes, this form of compromise is not fatal.
All implementations MUST implement certificate-based security.
13.4. Shared-Secret Security
RELOAD also supports a shared secret admission control scheme that relies on a single key that is shared among all members of the overlay. It is appropriate for small groups that wish to form a private network without complexity. In shared secret mode, all the peers MUST share a single symmetric key which is used to key TLS-PSK or TLS-SRP mode. A peer which does not know the key cannot form TLS connections with any other peer and therefore cannot join the overlay. One natural approach to a shared-secret scheme is to use a user- entered password as the key. The difficulty with this is that in TLS-PSK mode, such keys are very susceptible to dictionary attacks. If passwords are used as the source of shared keys, then TLS-SRP is a superior choice, because it is not subject to dictionary attacks.13.5. Storage Security
When certificate-based security is used in RELOAD, any given Resource-ID/Kind-ID pair is bound to some small set of certificates. In order to write data, the writer must prove possession of the private key for one of those certificates. Moreover, all data is stored, signed with the same private key that was used to authorize the storage. This set of rules makes questions of authorization and data integrity, which have historically been thorny for overlays, relatively simple.13.5.1. Authorization
When a node wants to store some value, it MUST first digitally sign the value with its own private key. It then sends a Store request that contains both the value and the signature towards the storing peer (which is defined by the Resource Name construction algorithm for that particular Kind of value). When the storing peer receives the request, it MUST determine whether the storing node is authorized to store at this Resource-ID/Kind-ID pair. Determining this requires comparing the user's identity to the requirements of the access control model (see Section 7.3). If it satisfies those requirements, the user is authorized to write, pending quota checks, as described in the next section. For example, consider a certificate with the following properties: User name: alice@dht.example.com Node-ID: 013456789abcdef Serial: 1234
If Alice wishes to Store a value of the "SIP Location" Kind, the Resource Name will be the SIP AOR "sip:alice@dht.example.com". The Resource-ID will be determined by hashing the Resource Name. Because SIP Location uses the USER-NODE-MATCH policy, it first verifies that the user name in the certificate hashes to the requested Resource-ID. It then verifies that the Node-ID in the certificate matches the dictionary key being used for the store. If both of these checks succeed, the Store is authorized. Note that because the access control model is different for different Kinds, the exact set of checks will vary.13.5.2. Distributed Quota
Being a peer in an Overlay Instance carries with it the responsibility to store data for a given region of the Overlay Instance. However, allowing nodes to store unlimited amounts of data would create unacceptable burdens on peers and would also enable trivial denial-of-service (DoS) attacks. RELOAD addresses this issue by requiring configurations to define maximum sizes for each Kind of stored data. Attempts to store values exceeding this size MUST be rejected. (If peers are inconsistent about this, then strange artifacts will happen when the zone of responsibility shifts and a different peer becomes responsible for overlarge data.) Because each Resource-ID/Kind-ID pair is bound to a small set of certificates, these size restrictions also create a distributed quota mechanism, with the quotas administered by the central configuration server. Allowing different Kinds of data to have different size restrictions allows new usages the flexibility to define limits that fit their needs without requiring all usages to have expansive limits.13.5.3. Correctness
Because each stored value is signed, it is trivial for any retrieving node to verify the integrity of the stored value. More care needs to be taken to prevent version rollback attacks. Rollback attacks on storage are prevented by the use of store times and lifetime values in each store. A lifetime represents the latest time at which the data is valid and thus limits (although does not completely prevent) the ability of the storing node to perform a rollback attack on retrievers. In order to prevent a rollback attack at the time of the Store request, it is REQUIRED that storage times be monotonically increasing. Storing peers MUST reject Store requests with storage times smaller than or equal to those that they are currently storing. In addition, a fetching node which receives a data value with a storage time older than the result of the previous fetch knows that a rollback has occurred.
13.5.4. Residual Attacks
The mechanisms described here provide a high degree of security, but some attacks remain possible. Most simply, it is possible for storing peers to refuse to store a value (i.e., they reject any request). In addition, a storing peer can deny knowledge of values which it has previously accepted. To some extent, these attacks can be ameliorated by attempting to store to and retrieve from replicas, but a retrieving node does not know whether or not it should try this, as there is a cost to doing so. The certificate-based authentication scheme prevents a single peer from being able to forge data owned by other peers. Furthermore, although a subversive peer can refuse to return data resources for which it is responsible, it cannot return forged data, because it cannot provide authentication for such registrations. Therefore, parallel searches for redundant registrations can mitigate most of the effects of a compromised peer. The ultimate reliability of such an overlay is a statistical question based on the replication factor and the percentage of compromised peers. In addition, when a Kind is multivalued (e.g., an array data model), the storing peer can return only some subset of the values, thus biasing its responses. This can be countered by using single values rather than sets, but that makes coordination between multiple storing agents much more difficult. This is a trade-off that must be made when designing any usage.13.6. Routing Security
Because the storage security system guarantees (within limits) the integrity of the stored data, routing security focuses on stopping the attacker from performing a DoS attack that misroutes requests in the overlay. There are a few obvious observations to make about this. First, it is easy to ensure that an attacker is at least a valid node in the Overlay Instance. Second, this is a DoS attack only. Third, if a large percentage of the nodes on the Overlay Instance are controlled by the attacker, it is probably impossible to perfectly secure against this.
13.6.1. Background
In general, attacks on DHT routing are mounted by the attacker arranging to route traffic through one or two nodes that it controls. In the Eclipse attack [Eclipse], the attacker tampers with messages to and from nodes for which it is on-path with respect to a given victim node. This allows it to pretend to be all the nodes that are reachable through it. In the Sybil attack [Sybil], the attacker registers a large number of nodes and is therefore able to capture a large amount of the traffic through the DHT. Both the Eclipse and Sybil attacks require the attacker to be able to exercise control over her Node-IDs. The Sybil attack requires the creation of a large number of peers. The Eclipse attack requires that the attacker be able to impersonate specific peers. In both cases, RELOAD attempts to mitigate these attacks by the use of centralized, certificate-based admission control.13.6.2. Admissions Control
Admission to a RELOAD Overlay Instance is controlled by requiring that each peer have a certificate containing its Node-ID. The requirement to have a certificate is enforced by using certificate- based mutual authentication on each connection. (Note: the following applies only when self-signed certificates are not used.) Whenever a peer connects to another peer, each side automatically checks that the other has a suitable certificate. These Node-IDs MUST be randomly assigned by the central enrollment server. This has two benefits: o It allows the enrollment server to limit the number of Node-IDs issued to any individual user. o It prevents the attacker from choosing specific Node-IDs. The first property allows protection against Sybil attacks (provided that the enrollment server uses strict rate-limiting policies). The second property deters but does not completely prevent Eclipse attacks. Because an Eclipse attacker must impersonate peers on the other side of the attacker, the attacker must have a certificate for suitable Node-IDs, which requires him to repeatedly query the enrollment server for new certificates, which will match only by chance. From the attacker's perspective, the difficulty is that if the attacker has only a small number of certificates, the region of the Overlay Instance he is impersonating appears to be very sparsely populated by comparison to the victim's local region.
13.6.3. Peer Identification and Authentication
In general, whenever a peer engages in overlay activity that might affect the Routing Table, it must establish its identity. This happens in two ways. First, whenever a peer establishes a direct connection to another peer, it authenticates via certificate-based mutual authentication. All messages between peers are sent over this protected channel, and therefore the peers can verify the data origin of the last-hop peer for requests and responses without further cryptography. In some situations, however, it is desirable to be able to establish the identity of a peer with whom one is not directly connected. The most natural case is when a peer Updates its state. At this point, other peers may need to update their view of the overlay structure, but they need to verify that the Update message came from the actual peer rather than from an attacker. To prevent having a peer accept Update messages from an attacker, all overlay routing messages are signed by the peer that generated them. For messages that impact the topology of the overlay, replay is typically prevented by having the information come directly from, or be verified by, the nodes that claimed to have generated the update. Data storage replay detection is done by signing the time of the node that generated the signature on the Store request, thus providing a time-based replay protection, but the time synchronization is needed only between peers that can write to the same location.13.6.4. Protecting the Signaling
The goal here is to stop an attacker from knowing who is signaling what to whom. An attacker is unlikely to be able to observe the activities of a specific individual, given the randomization of IDs and routing based on the present peers discussed above. Furthermore, because messages can be routed using only the header information, the actual body of the RELOAD message can be encrypted during transmission. There are two lines of defense here. The first is the use of TLS or DTLS for each communications link between peers. This provides protection against attackers who are not members of the overlay. The second line of defense is to digitally sign each message. This prevents adversarial peers from modifying messages in flight, even if they are on the routing path.
13.6.5. Routing Loops and DoS Attacks
Source-routing mechanisms are known to create the possibility for DoS amplification, especially by the induction of routing loops [RFC5095]. In order to limit amplification, the initial-ttl value in the configuration file SHOULD be set to a value slightly larger than the longest expected path through the network. For Chord, experience has shown that log(2) of the number of nodes in the network + 5 is a safe bound. Because nodes are required to enforce the initial-ttl as the maximum value, an attacker cannot achieve an amplification factor greater than initial-ttl, thus limiting the additional capabilities provided by source routing. In order to prevent the use of loops for targeted implementation attacks, implementations SHOULD check the Destination List for duplicate entries and discard such records with an "Error_Invalid_Message" error. This does not completely prevent loops, but it does require that at least one attacker node be part of the loop.13.6.6. Residual Attacks
The routing security mechanisms in RELOAD are designed to contain rather than eliminate attacks on routing. It is still possible for an attacker to mount a variety of attacks. In particular, if an attacker is able to take up a position on the overlay routing between A and B, it can make it appear as if B does not exist or is disconnected. It can also advertise false network metrics in an attempt to reroute traffic. However, these are primarily DoS attacks. The certificate-based security scheme secures the namespace, but if an individual peer is compromised or if an attacker obtains a certificate from the CA, then a number of subversive peers can still appear in the overlay. While these peers cannot falsify responses to resource queries, they can respond with error messages, effecting a DoS attack on the resource registration. They can also subvert routing to other compromised peers. To defend against such attacks, a resource search must still consist of parallel searches for replicated registrations.
(next page on part 7)
