Add documentation for Unix domain socket authenticator

Signed-off-by: Joe Ellis <[email protected]>

Author: Joe Ellis

src/parsec_client/api_overview.md

@@ -146,8 +146,12 @@ Clients present their identity strings to the service on each API call. As set o
 protocol specification**](wire_protocol.md), they do this using the **authentication** field of the
 API request.
 
-There are two ways in which the client can use the authentication field to share its identity with
-the service: **direct authentication** and **authentication tokens**.
+There are currently three ways in which the client can use the authentication field to share its
+identity with the service:
+
+- **direct authentication**.
+- **authentication tokens**.
+- **peer credentials**.
 
 With **direct authentication**, the client authenticates the request by directly copying the
 application identity string into the **authentication** field of the request.
@@ -159,6 +163,12 @@ extracted by the service after verifying the authenticity of the token. A more d
 of authentication tokens and their lifecycle is present in the [**sytem architecture
 specification**](../parsec_service/system_architecture.md).
 
+With **peer credentials**, the client authenticates by self-declaring its UID inside the
+**authentication** field of the request. The Parsec service verifies that this self-declared UID
+matches the actual UID of the connecting process using some peer credentials mechanism. For example,
+Unix domain sockets support peer credentials, allowing the endpoints to get each other's effective
+UIDs and GIDs via the operating system, which is trusted implicitly.
+
 When it makes an API request, the client needs to tell the server which kind of authentication is
 being used. This is so that the server knows how to interepret the bytes in the **authentication**
 field of the request. As described in the [**wire protocol specification**](wire_protocol.md), the
@@ -177,6 +187,10 @@ permitted numerical values for this field are given as follows:-
 - A value of 2 (`0x02`) indicates authentication tokens. The service will expect the
    **authentication** field to contain a JWT token. Tokens must be signed with the private key of
    the identity provider and their validity period must cover the moment when the check is done.
+- A value of 3 (`0x03`) indicates peer credentials authentication. The service will expect the
+   **authentication** field to contain the stringified UID of the connecting process. The Parsec
+   service will verify that this self-declared UID is consistent with the UID from the peer
+   credentials.
 
 Other values are unsupported and will be rejected by the service.
 

src/parsec_service/authenticators.md

@@ -5,6 +5,23 @@
 The direct authenticator, [currently
 named](https://github.com/parallaxsecond/parsec-interface-rs/issues/22) "simple authenticator" in
 the code, directly parse the authentication field as a UTF-8 string and uses that as application
-identity. The direct authenticator is the one currently used by the Parsec service.
+identity.
+
+## Peer Credentials Authenticator
+
+The peer credentials authenticator uses peer credentials to authenticate the client. In this
+context, 'peer credentials' refers to metadata about the connection between client and server that
+contains the effective user ID (UID) and group ID (GID) of the connecting process.
+
+To use this authenticator, the application must self-declare its UID in the authentication field of
+the request as a UTF-8 string. This authenticator will then verify that the UID sourced from the
+peer credentials matches the one self-declared in the request. If they match up, authentication is
+successful and the application identity is set to the UID.
+
+Currently, the peer credentials authenticator only supports authentication via the peer credentials
+sourced from a Unix domain socket. However, the authenticator will likely support different
+transports in the future.
+
+GID is currently unused by the peer credentials authenticator.
 
 *Copyright 2019 Contributors to the Parsec project.*

src/parsec_service/diagrams/interfaces_and_dataflow.drawio

@@ -1 +1 @@
-<mxfile modified="2020-02-10T15:11:10.440Z" host="www.draw.io" agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:72.0) Gecko/20100101 Firefox/72.0" etag="FkZW2A3bjEKAokGpyY6v" version="12.6.6" type="device"><diagram id="r3fCkxUuyQpxchEkL19v" name="Page-1">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</diagram></mxfile>
+<mxfile modified="2020-08-11T09:38:52.879Z" host="app.diagrams.net" agent="5.0 (Macintosh; Intel Mac OS X 10_15_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/84.0.4147.105 Safari/537.36" etag="YgjPYXcEKpH_Ape6CRQq" version="13.6.2" type="device"><diagram id="r3fCkxUuyQpxchEkL19v" name="Page-1">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</diagram></mxfile>

src/parsec_service/system_architecture.md

@@ -284,7 +284,9 @@ receipt by the identity provider. The orchestrator will use its own private key
 verification will be via the shared public key. See the section above on trust relationships for
 details of how these keys are generated and shared.
 
-### Authentication Tokens
+### Authentication
+
+#### Authentication Tokens
 
 When client applications invoke API operations in the security service, they must include their
 application identity string somehow. This allows the security service to provide the required level
@@ -301,7 +303,7 @@ purpose). This is simple, and works well in a demo or proof-of-concept environme
 suitable for a deployed system architecture, because it does not fulfil the stated design goal of
 secretless communication.
 
-The solution to this problem is for the authentication header to contain a payload that not only
+One solution to this problem is for the authentication header to contain a payload that not only
 includes the application identity, but also proves cryptographically that it is from a valid client.
 This payload takes the form of a [**signed JSON Web Token
 (JWT)**](https://tools.ietf.org/html/rfc7519).
@@ -318,6 +320,18 @@ private key to sign the JWT. The security service has the public part of this ke
 to perform the verification. The identity provider and the security service share one of the trust
 relationships that were defined above.
 
+#### Peer Credentials
+
+Another solution to the authentication problem is to use peer credentials with the [peer credentials
+authenticator](authenticators.md). Peer credentials are connection metadata which specifies the user
+ID (UID) and group ID (GID) of the connecting process. For example, Unix domain sockets support peer
+credentials, allowing the endpoints to get each other's UID and GID via the operating system.
+
+In peer credential authentication, the connecting process self-declares its (effective) UID inside
+the authentication header of the request. The Parsec service validates that the self-declared UID
+matches the actual UID from the peer credentials. If they match, authentication was successful, and
+the application identity is set to the stringified UID.
+
 ## Block Architecture Summary
 
 Refer to the figure below for a block representation of the key architectural components.