Define private node registration in detail and move partial definitio…

…n from PoWeb spec

rs000-core.md

@@ -278,10 +278,93 @@ Before the nodes can exchange parcels, the private node MUST register with its g
 
 If the server corresponds to a private gateway, it SHOULD listen on port `276` if it has the appropriate permission to do so or port `13276` if it does not. Alternatively, if using Unix domain sockets, the client SHOULD NOT initiate a connection if the socket is owned by a user other than the administrator (`root` in Unix-like systems).
 
-If the server corresponds to a Internet gateway, it MUST use `awala-gsc` as the service string in the SRV record.
+If the server corresponds to an Internet gateway, it MUST use `awala-gsc` as the service string in the SRV record.
 
 In addition to sending parcels to each other, the client MAY also register [Parcel Delivery Deauthorizations (PDD)](#pdd) with the server.
 
+##### Private node registration
+
+The process to register private nodes is split in two parts, at the end of which -- if successful -- the server will issue a certificate for the private node.
+
+The client MUST initiate the registration process by making a **pre-registration request**.
+This preliminary step is used to give the client a nonce to sign, thus avoiding replay attacks.
+The pre-registration request MUST contain the SHA-256 hexadecimal digest of the private node's public key,
+as well as any additional data required by the concrete binding.
+
+If the server approves the pre-registration,
+it MUST output a single-use **Private Node Registration Authorisation** (PNRA) that expires in less than 10 seconds.
+PNRAs have the following structure:
+
+```asn1
+PrivateNodeRegistrationAuthorisation ::= SEQUENCE {
+    expiryDateUtc DATE-TIME,
+    gatewayData   OCTET STRING,
+    signature     OCTET STRING
+}
+```
+
+Where,
+
+- `expiryDateUtc` is the date and time (UTC) when the PNRA expires.
+- `gatewayData` is an opaque value that the client MUST include in the future registration request. It MUST contain a nonce, as well as any additional data required by the concrete binding.
+- `signature` is the signature of the `expiryDateUtc` and `gatewayData` fields with the server's long-term identity key. The plaintext passed to the signing algorithm MUST be calculated as the DER serialization of the `PrivateNodeRegistrationAuthorisationPlaintext` ASN.1 type below:
+
+    ```asn1
+    PrivateNodeRegistrationAuthorisationPlaintext ::= SEQUENCE {
+         oid           OBJECT IDENTIFIER ::= { awala private-node-registration(2) auth(0) },
+         expiryDateUtc DATE-TIME,
+         gatewayData   OCTET STRING
+    }
+    ```
+
+To complete the registration, the client MUST send a **Private Node Registration Request** (PNRR) to the server,
+which includes the PNRA signed with the private node's key.
+A PNRR has the following structure:
+
+```asn1
+PrivateNodeRegistrationRequest ::= SEQUENCE {
+    privateNodePublicKey  SubjectPublicKeyInfo, -- Per RFC 5280
+    pnra                  PrivateNodeRegistrationAuthorisation,
+    pnraCountersignature  OCTET STRING
+}
+```
+
+Where,
+
+- `privateNodePublicKey` is the public key of the private node.
+- `pnra` is the PNRA previously issued by the server.
+- `pnraCountersignature` is the signature of the PNRA with the private node's key. The plaintext passed to the signing algorithm MUST be calculated as the DER serialization of the `PrivateNodeRegistrationRequestPlaintext` ASN.1 type below:
+
+    ```asn1
+    PrivateNodeRegistrationRequestPlaintext ::= SEQUENCE {
+         oid  OBJECT IDENTIFIER ::= { awala private-node-registration(2) request(1) },
+         pnra PrivateNodeRegistrationAuthorisation
+    }
+    ```
+
+Finally, if successful, the server MUST return a **Private Node Registration** (PNR),
+which includes the certificate issued to the private node.
+A PNR has the following structure:
+
+```asn1
+PrivateNodeRegistration ::= SEQUENCE {
+    privateNodeCertificate         Certificate, -- Per T-REC-X.509
+    gatewayCertificate             Certificate, -- Per T-REC-X.509
+    internetGatewayInternetAddress VisibleString,
+    sessionKey                     SessionKey OPTIONAL -- Per RS-003
+}
+```
+
+Where,
+
+- `privateNodeCertificate` is the certificate issued to the private node.
+- `gatewayCertificate` is the server's self-issued certificate.
+- `internetGatewayInternetAddress` is the Internet address of the server (e.g., `example.com`). If the server is a private gateway, this will be the address of its Internet gateway.
+- `sessionKey` is the session key that the private node MUST use when sending messages to the server.
+  This field MUST only be set when a private gateway is registering with an Internet gateway,
+  as this is the encryption key it will need to use over the gateway channel.
+  Private endpoints that receive this field when registering with their private gateway MUST ignore it.
+
 ##### Parcel collection handshake
 
 As soon as the connection is established, a handshake MUST be performed for the gateway to authenticate the private node(s). The client will be challenged to sign a nonce with the key of each private node it claims to own, as shown in the following sequence diagram.

rs003-key-agreement.md

@@ -154,6 +154,18 @@ Implementations MUST store the recipient's ephemeral key identifier in the `subj
 OriginatorEphemeralKeyId OBJECT IDENTIFIER ::= { awala channel-session(1) 0 }
 ```
 
+## Public Key Representation
+
+When distributing public keys along with their respective ids,
+implementations MAY use the following ASN.1 structure:
+
+```asn1
+SessionKey ::= SEQUENCE {
+  id  OCTET STRING,
+  key SubjectPublicKeyInfo -- Per RFC 5280
+}
+```
+
 ## Limitations
 
 This protocol will not work with unidirectional communication as might be the case between two endpoints (if one of the endpoints is private and does not issue Parcel Delivery Authorizations to its peer). Consequently, an Awala service with one-way communication would not get perfect forward secrecy or future secrecy, unless it enables two-way communication as a workaround until there is an equivalent protocol for unidirectional communication.

rs016-poweb.md

@@ -36,28 +36,29 @@ The server MUST expose each PoWeb endpoint under a common URL prefix ending with
 
 ### Private node registration
 
-The process to register private nodes is split in two parts, at the end of which -- if successful -- the server will issue a certificate for the private node.
+Per [the core spec](rs000-core.md#private-node-registration),
+this process is divided into two steps: pre-registration and registration.
 
-The client MUST initiate the registration process by making a pre-registration request. This preliminary step is used to give the client a nonce to sign, thus avoiding replay attacks. Servers MUST implement the pre-registration endpoint described in this document, unless the server is part of a private gateway on a mobile platform, in which case it MUST implement a platform-specific method that also authenticates the app that owns the endpoint. Pre-registration on mobile platforms is outside the scope of this document.
+#### Pre-registration endpoint
 
-If the server approves the pre-registration, it MUST output a single-use _Private Node Registration Authorisation_ (PNRA) that expires in less than 10 seconds. To complete the registration, the client MUST make a registration request by passing the PNRA signed with the private node's key which, if successful, will result in the server issuing a certificate.
+Servers MUST implement the pre-registration endpoint described in this document, unless the server is part of a private gateway on a mobile platform, in which case it MUST implement a platform-specific method that also authenticates the app that owns the endpoint.
 
-#### Pre-registration endpoint
+To pre-register a private node, the client MUST make a POST request to `/pre-registration` with the SHA-256 hexadecimal digest of the private node's public key. The request Content-Type MUST be `text/plain`.
 
-To pre-register a private node, the client MUST make a POST request to `/pre-registration` with the SHA-256 hexadecimal digest of the private node's public key. The request Content-Type MUST be `text/plain`. The server MUST respond with one of the following:
+The server MUST respond with one of the following:
 
-- A `200 OK` if the pre-registration is authorised. The response body MUST be the PNRA and the Content-Type MUST be `application/vnd.awala.node-registration.authorization`.
+- A `200 OK` if the pre-registration is authorised. The response body MUST be the [Private Node Registration Authorisation (PNRA)](rs000-core.md#private-node-registration). The Content-Type MUST be `application/vnd.awala.node-registration.authorization`.
 - A `400 Bad Request` if the client did not adhere to the requirements above.
 
 Servers SHOULD refuse request bodies larger than 64 octets.
 
 #### Registration endpoint
 
-To complete the registration, the client MUST produce a _Private Node Registration Request_ (PNRR) by signing the PNRA with the key of the node being registered. The PNRR MUST then be sent in the body of a POST request to `/nodes`, using the Content-Type `application/vnd.awala.node-registration.request`.
+To complete the registration, the client MUST send the [Private Node Registration Request (PNRR)](rs000-core.md#private-node-registration) in the body of a POST request to `/nodes`, using the Content-Type `application/vnd.awala.node-registration.request`.
 
 The server MUST respond with one of the following:
 
-- `200 OK` if the registration was successfully completed. The response body MUST be a _Private Node Registration_ (PNR), which encapsulates the newly-issued certificate for the private endpoint, as well as the certificate for the underlying gateway behind the server. The response Content-Type MUST be `application/vnd.awala.node-registration.registration`.
+- `200 OK` if the registration was successfully completed. The response body MUST be a [Private Node Registration (PNR)](rs000-core.md#private-node-registration). The response Content-Type MUST be `application/vnd.awala.node-registration.registration`.
 - `400 Bad Request` if the PNRR sent by the client is malformed or its digital signature is invalid.
 - `403 Forbidden` if the client is using a PNRA issued for a different private node.