Add documentation for Unix domain socket authenticator

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**.
+- **Unix 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,11 @@ 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 **Unix peer credentials**, the client authenticates by self-declaring its Unix user identifier
+(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 via the Unix peer credentials
+mechanism.
+
 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 +186,11 @@ 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 Unix peer credentials authentication. The service expects the
+   **authentication** field to contain the Unix user identifier (UID, **not** username) of the
+   connecting process as a zero-padded little-endian 32-bit unsigned integer. The Parsec service
+   will verify that this self-declared UID is consistent with the UID from the Unix peer
+   credentials.
 
 Other values are unsupported and will be rejected by the service.
 

src/parsec_service/authenticators.md

@@ -5,6 +5,25 @@
 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.
+
+## Unix Peer Credentials Authenticator
+
+The Unix peer credentials authenticator uses Unix peer credentials to authenticate the client. Here
+'Unix peer credentials' refers to metadata about the connection between client and server that
+contains the effective Unix user identifier (UID) and Unix group identifier (GID) of the connecting
+process.
+
+To use this authenticator, the application must self-declare its UID (**not** username) in the
+authentication field of the request as a zero-padded little-endian 32-bit unsigned integer. 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.
+
+Note that a Unix domain socket transport is not limited to the Unix peer credentials authenticator;
+this transport can be used with a different authenticator if required.
+
+The GID and PID components of the Unix peer credentials are 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,19 @@ 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.
 
+#### Unix Peer Credentials
+
+Another solution to the authentication problem is to use Unix peer credentials with the [Unix peer
+credentials authenticator](authenticators.md). Unix peer credentials are connection metadata which
+specify the effective Unix user ID (UID) and group ID (GID) of the connecting process. When using a
+Unix domain sockets tranport, the endpoints can get each other's UID and GID via the operating
+system.
+
+In Unix peer credential authentication, the connecting process self-declares its 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.