Add peer credentials authenticator

This authenticator uses peer credentials for authentication. The
specific type of peer credentials in mind at the moment are Unix peer
credentials, but this can be extended in the future.

Unix peer credentials provide direct access to the (effective) uid/gid
on the other end of a domain socket connect, without cooperation between
the endpoints. This means that we can trivially determine the uid/gid of
the connecting process, which we can then use for authentication.

This authenticator:

- grabs the (uid, gid) pair of the connecting process.
- grabs the self-declared uid sent in the authentication request.
- verifies that authentication is successful by checking that the
  self-declared uid in the authentication request is equal to the actual
  uid from the peer credentials.
- if authentication was successful, creates an `ApplicationName` based
  on the uid.

The authenticator is hidden behind the Cargo feature
`peer-credentials-authenticator`.

Note that gid is currently unused by the authenticator.

Also note that this patch depends on the following PR being merged:

    rust-lang/rust#75148

At the time of writing, this PR is currently under review and is not
merged into the Rust stdlib. This patch therefore will not build with
the current a stable/nightly compiler.

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

Author: Joe Ellis

src/authenticators/mod.rs

@@ -8,11 +8,11 @@
 //! used throughout the service for identifying the request initiator. The input to an authentication
 //! is the `RequestAuth` field of a request, which is parsed by the authenticator specified in the header.
 //! The authentication functionality is abstracted through an `Authenticate` trait.
-//!
-//! Currently only a simple Direct Authenticator component is implemented.
 
 pub mod direct_authenticator;
 
+pub mod unix_peer_credentials_authenticator;
+
 use crate::front::listener::ConnectionMetadata;
 use parsec_interface::operations::list_authenticators;
 use parsec_interface::requests::request::RequestAuth;
@@ -35,7 +35,7 @@ pub trait Authenticate {
     /// Authenticates a `RequestAuth` payload and returns the `ApplicationName` if successful. A
     /// optional `ConnectionMetadata` object is passed in too, since it is sometimes possible to
     /// perform authentication based on the connection's metadata (i.e. as is the case for UNIX
-    /// domain sockets with peer credentials).
+    /// domain sockets with Unix peer credentials).
     ///
     /// # Errors
     ///

src/authenticators/unix_peer_credentials_authenticator/mod.rs

@@ -0,0 +1,181 @@
+// Copyright 2020 Contributors to the Parsec project.
+// SPDX-License-Identifier: Apache-2.0
+//! Unix peer credentials authenticator
+//!
+//! The `UnixPeerCredentialsAuthenticator` uses Unix peer credentials to perform authentication. As
+//! such, it uses the effective Unix user ID (UID) to authenticate the connecting process. Unix
+//! peer credentials also allow us to access the effective Unix group ID (GID) of the connecting
+//! process, although this information is currently unused.
+//!
+//! Currently, the stringified UID is used as the application name.
+
+use super::ApplicationName;
+use super::Authenticate;
+use crate::front::listener::ConnectionMetadata;
+use log::error;
+use parsec_interface::operations::list_authenticators;
+use parsec_interface::requests::request::RequestAuth;
+use parsec_interface::requests::AuthType;
+use parsec_interface::requests::{ResponseStatus, Result};
+use parsec_interface::secrecy::ExposeSecret;
+use std::convert::TryInto;
+
+/// Unix peer credentials authenticator.
+#[derive(Copy, Clone, Debug)]
+pub struct UnixPeerCredentialsAuthenticator;
+
+impl Authenticate for UnixPeerCredentialsAuthenticator {
+    fn describe(&self) -> Result<list_authenticators::AuthenticatorInfo> {
+        Ok(list_authenticators::AuthenticatorInfo {
+            description: String::from(
+                "Uses Unix peer credentials to authenticate the client. Verifies that the self-declared \
+                Unix user identifier (UID) in the request's authentication header matches that which is \
+                found from the peer credentials."
+            ),
+            version_maj: 0,
+            version_min: 1,
+            version_rev: 0,
+            id: AuthType::PeerCredentials,
+        })
+    }
+
+    fn authenticate(
+        &self,
+        auth: &RequestAuth,
+        meta: Option<ConnectionMetadata>,
+    ) -> Result<ApplicationName> {
+        // Parse authentication request.
+        let expected_uid_bytes = auth.buffer.expose_secret();
+        if expected_uid_bytes.is_empty() {
+            error!("Expected UID in authentication request, but it is empty.");
+            return Err(ResponseStatus::AuthenticationError);
+        }
+
+        const EXPECTED_UID_SIZE_BYTES: usize = 4;
+        let expected_uid: [u8; 4] = expected_uid_bytes.as_slice().try_into().map_err(|_| {
+            error!(
+                "UID in authentication request is not the right size (expected: {}, got: {}).",
+                EXPECTED_UID_SIZE_BYTES,
+                expected_uid_bytes.len()
+            );
+            ResponseStatus::AuthenticationError
+        })?;
+        let expected_uid = u32::from_le_bytes(expected_uid);
+
+        let meta = meta.ok_or_else(|| {
+            error!("Authenticator did not receive any metadata; cannot perform authentication.");
+            ResponseStatus::AuthenticationError
+        })?;
+
+        let (uid, _gid) = match meta {
+            ConnectionMetadata::UnixPeerCredentials { uid, gid } => (uid, gid),
+            // TODO: add wildcard pattern when `ConnectionMetadata` has more possibilities.
+        };
+
+        // Authentication is successful if the _actual_ UID from the Unix peer credentials equals
+        // the self-declared UID in the authentication request.
+        if uid == expected_uid {
+            Ok(ApplicationName(uid.to_string()))
+        } else {
+            error!("Declared UID in authentication request does not match the process's UID.");
+            Err(ResponseStatus::AuthenticationError)
+        }
+    }
+}
+
+#[cfg(test)]
+mod test {
+    use super::super::Authenticate;
+    use super::UnixPeerCredentialsAuthenticator;
+    use crate::front::listener::ConnectionMetadata;
+    use parsec_interface::requests::request::RequestAuth;
+    use parsec_interface::requests::ResponseStatus;
+    use rand::Rng;
+    use std::os::unix::net::UnixStream;
+    use users::get_current_uid;
+
+    #[test]
+    fn successful_authentication() {
+        // This test should PASS; we are verifying that our username gets set as the application
+        // secret when using Unix peer credentials authentication with Unix domain sockets.
+
+        // Create two connected sockets.
+        let (sock_a, _sock_b) = UnixStream::pair().unwrap();
+        let (cred_a, _cred_b) = (sock_a.peer_cred().unwrap(), _sock_b.peer_cred().unwrap());
+
+        let authenticator = UnixPeerCredentialsAuthenticator {};
+
+        let req_auth_data = cred_a.uid.to_le_bytes().to_vec();
+        let req_auth = RequestAuth::new(req_auth_data);
+        let conn_metadata = Some(ConnectionMetadata::UnixPeerCredentials {
+            uid: cred_a.uid,
+            gid: cred_a.gid,
+        });
+
+        let auth_name = authenticator
+            .authenticate(&req_auth, conn_metadata)
+            .expect("Failed to authenticate");
+
+        assert_eq!(auth_name.get_name(), get_current_uid().to_string());
+    }
+
+    #[test]
+    fn unsuccessful_authentication_wrong_declared_uid() {
+        // This test should FAIL; we are trying to authenticate, but we are declaring the wrong
+        // UID.
+
+        // Create two connected sockets.
+        let (sock_a, _sock_b) = UnixStream::pair().unwrap();
+        let (cred_a, _cred_b) = (sock_a.peer_cred().unwrap(), _sock_b.peer_cred().unwrap());
+
+        let authenticator = UnixPeerCredentialsAuthenticator {};
+
+        let wrong_uid = cred_a.uid + 1;
+        let wrong_req_auth_data = wrong_uid.to_le_bytes().to_vec();
+        let req_auth = RequestAuth::new(wrong_req_auth_data);
+        let conn_metadata = Some(ConnectionMetadata::UnixPeerCredentials {
+            uid: cred_a.uid,
+            gid: cred_a.gid,
+        });
+
+        let auth_result = authenticator.authenticate(&req_auth, conn_metadata);
+        assert_eq!(auth_result, Err(ResponseStatus::AuthenticationError));
+    }
+
+    #[test]
+    fn unsuccessful_authentication_garbage_data() {
+        // This test should FAIL; we are sending garbage (random) data in the request.
+
+        // Create two connected sockets.
+        let (sock_a, _sock_b) = UnixStream::pair().unwrap();
+        let (cred_a, _cred_b) = (sock_a.peer_cred().unwrap(), _sock_b.peer_cred().unwrap());
+
+        let authenticator = UnixPeerCredentialsAuthenticator {};
+
+        let garbage_data = rand::thread_rng().gen::<[u8; 32]>().to_vec();
+        let req_auth = RequestAuth::new(garbage_data);
+        let conn_metadata = Some(ConnectionMetadata::UnixPeerCredentials {
+            uid: cred_a.uid,
+            gid: cred_a.gid,
+        });
+
+        let auth_result = authenticator.authenticate(&req_auth, conn_metadata);
+        assert_eq!(auth_result, Err(ResponseStatus::AuthenticationError));
+    }
+
+    #[test]
+    fn unsuccessful_authentication_no_metadata() {
+        let authenticator = UnixPeerCredentialsAuthenticator {};
+        let req_auth = RequestAuth::new("secret".into());
+
+        let conn_metadata = None;
+        let auth_result = authenticator.authenticate(&req_auth, conn_metadata);
+        assert_eq!(auth_result, Err(ResponseStatus::AuthenticationError));
+    }
+
+    #[test]
+    fn unsuccessful_authentication_wrong_metadata() {
+        // TODO: this test needs implementing when we have more than one metadata type. At the
+        // moment, the compiler just complains with an 'unreachable branch' message.
+    }
+}

src/front/domain_socket.rs

@@ -5,8 +5,8 @@
 //! Expose Parsec functionality using Unix domain sockets as an IPC layer.
 //! The local socket is created at a predefined location.
 use super::listener;
-use listener::Connection;
 use listener::Listen;
+use listener::{Connection, ConnectionMetadata, GetMetadata};
 use log::error;
 #[cfg(not(feature = "no-parsec-user-and-clients-group"))]
 use std::ffi::CString;
@@ -16,6 +16,7 @@ use std::io::{Error, ErrorKind, Result};
 use std::os::unix::fs::PermissionsExt;
 use std::os::unix::io::FromRawFd;
 use std::os::unix::net::UnixListener;
+use std::os::unix::net::UnixStream;
 use std::path::Path;
 use std::time::Duration;
 
@@ -202,11 +203,10 @@ impl Listen for DomainSocketListener {
                     format_error!("Failed to set stream as blocking", err);
                     None
                 } else {
+                    let metadata = stream.metadata();
                     Some(Connection {
                         stream: Box::new(stream),
-                        // TODO: when possible, we want to replace this with the (uid, gid, pid)
-                        // triple for peer credentials. See listener.rs.
-                        metadata: None,
+                        metadata,
                     })
                 }
             }
@@ -248,3 +248,23 @@ impl DomainSocketListenerBuilder {
         })?)
     }
 }
+
+impl GetMetadata for UnixStream {
+    fn metadata(&self) -> Option<ConnectionMetadata> {
+        let ucred = self
+            .peer_cred()
+            .map_err(|err| {
+                format_error!(
+                    "Failed to grab peer credentials metadata from UnixStream",
+                    err
+                );
+                err
+            })
+            .ok()?;
+
+        Some(ConnectionMetadata::UnixPeerCredentials {
+            uid: ucred.uid,
+            gid: ucred.gid,
+        })
+    }
+}

src/front/listener.rs

@@ -34,7 +34,13 @@ pub struct ListenerConfig {
 /// Specifies metadata associated with a connection, if any.
 #[derive(Copy, Clone, Debug)]
 pub enum ConnectionMetadata {
-    // TODO: nothing here right now. Metadata types will be added as needed.
+    /// Unix peer credentials metadata for Unix domain sockets.
+    UnixPeerCredentials {
+        /// The effective UID of the connecting process.
+        uid: u32,
+        /// The effective GID of the connecting process.
+        gid: u32,
+    },
 }
 
 /// Represents a connection to a single client
@@ -70,3 +76,9 @@ pub trait Listen {
     /// If the listener has not been initialised before, with the `init` method.
     fn accept(&self) -> Option<Connection>;
 }
+
+/// Get metadata for a particular object.
+pub trait GetMetadata {
+    /// Get the metadata associated with this object.
+    fn metadata(&self) -> Option<ConnectionMetadata>;
+}