feat: add set_enabled and set_pid helpers

The `enable_events` is convenient for a process that enables the audit
daemon once. However, when there is a need to disable/enable at will,
it does not work well.

For example, take something like this:

```
let (connection, handle, receiver) = new_connection().unwrap();
tokio::task::spawn(connection);

// Works well
handle.enable_events().await.unwrap();

...

// Now disable audit:
drop((handle, receiver));

// Now we want to re-enable audit:
let (connection, handle, receiver) = new_connection().unwrap();
tokio::task::spawn(connection);

// This fails on errno: -17, ie EEXIST
handle.enable_events().await.unwrap();
```

The reason this fails is because, while the drop did disable audit,
the pid is still set. The second call to enable_events thus fails
because the "AUDIT_SET_PID" call returns EEXIST (pid is already set to
this exact pid).

Now, it could be possible to handle the EEXIST error on `enable_events`
and consider that this is OK. However, it's not necessarily clear on
which parameter this error is returned (the SET_PID or the SET_ENABLED).
In addition, there is still the issue that we disabled audit,
while letting the pid set, which is a bit ugly.

By adding the two lower levels helpers (set_enabled, set_pid), it is
possible to do things more cleanly:

```
let (connection, handle, receiver) = new_connection().unwrap();
tokio::task::spawn(connection);

// Works well
handle.set_pid(std::process::id()).await.unwrap();
handle.set_enabled(true).await.unwrap();

// Now disable audit:
handle.set_pid(0).await.unwrap();
handle.set_enabled(false).await.unwrap();
drop((handle, receiver));

// Now we want to re-enable audit:
let (connection, handle, receiver) = new_connection().unwrap();
tokio::task::spawn(connection);
// Works well
handle.set_pid(std::process::id()).await.unwrap();
handle.set_enabled(true).await.unwrap();
```

Author: vthib

src/handle.rs

@@ -126,7 +126,14 @@ impl Handle {
         }
     }
 
-    /// Enable receiving audit events
+    /// Enable receiving events in this process.
+    ///
+    /// This function enable events and set the PID in a single message.
+    ///
+    /// This works well if done once in the process life. If however you need to
+    /// disable and enable events, you will want to call the
+    /// `Handle::set_enabled` and `Handle::set_pid` directly, so as to
+    /// handle the errors in a more granular manner.
     pub async fn enable_events(&mut self) -> Result<(), Error> {
         let mut status = StatusMessage::new();
         status.enabled = 1;
@@ -137,6 +144,38 @@ impl Handle {
         self.acked_request(req).await
     }
 
+    /// Set whether to enable the audit daemon or not.
+    ///
+    /// When enabling the audit daemon with this function, you should ensure
+    /// that you set the PID of the current process already with a call to
+    /// `Handle::set_pid`.
+    ///
+    /// See `Handle::enable_events` for a more convenient helper to enable
+    /// events in a single call.
+    pub async fn set_enabled(&mut self, value: bool) -> Result<(), Error> {
+        let mut status = StatusMessage::new();
+        status.enabled = if value { 1 } else { 0 };
+        status.mask = AUDIT_STATUS_ENABLED;
+        let mut req = NetlinkMessage::from(AuditMessage::SetStatus(status));
+        req.header.flags = NLM_F_REQUEST | NLM_F_ACK;
+        self.acked_request(req).await
+    }
+
+    /// Set the PID to which audit messages should be addressed.
+    ///
+    /// You probably want to use either:
+    /// - Your own pid, to receive audit events
+    /// - 0, to unset the PID restriction, for example when disabling the audit
+    ///   connection.
+    pub async fn set_pid(&mut self, pid: u32) -> Result<(), Error> {
+        let mut status = StatusMessage::new();
+        status.pid = pid;
+        status.mask = AUDIT_STATUS_PID;
+        let mut req = NetlinkMessage::from(AuditMessage::SetStatus(status));
+        req.header.flags = NLM_F_REQUEST | NLM_F_ACK;
+        self.acked_request(req).await
+    }
+
     /// Get current audit status
     pub async fn get_status(&mut self) -> Result<StatusMessage, Error> {
         let mut req = NetlinkMessage::from(AuditMessage::GetStatus(None));