Update documentation

README.md

@@ -8,6 +8,14 @@ using BPF USDT probes to intercept specific entry points in crypto libraries,
 as they are used by user space processes on the system, and collect data so that
 it can be analyzed later.
 
+The primary use-case of this project is to facilitate the migration of
+organizations to post-quantum cryptography. Since post-quantum
+algorithms are relatively new and not all applications are immediately
+compatible, mandatory switch from classical cryptography is
+impractical. To enable a smoother transition, crypto-auditing can be
+employed at run time to identify any instances where classical
+cryptography is still in use.
+
 The design documents can be found from the following links:
 
 - [Objectives and high-level design](docs/objectives.md)
@@ -19,23 +27,15 @@ The design documents can be found from the following links:
 ## Installation
 
 1. Install the latest Rust toolchain
-2. Install the instrumented crypto libraries, such as GnuTLS:
-```console
-$ git clone --depth=1 -b wip/usdt https://gitlab.com/gnutls/gnutls.git
-$ ./bootstrap
-$ ./configure --prefix=/path/to/installation --enable-crypto-auditing
-$ make -j$(nproc)
-$ sudo make install
-```
-3. Install the dependencies (note that libbpf 1.1.1 or later is required)
+2. Install the dependencies (note that libbpf 1.1.1 or later is required)
 ```console
 $ sudo dnf install bpftool make libbpf-devel llvm-devel rustfmt
 ```
-4. Build the programs with `make`
+3. Build the programs with `make`
 ```console
 $ make
 ```
-5. Install the programs with `make install`
+4. Install the programs with `make install`
 ```console
 $ sudo make install
 ```
@@ -72,7 +72,7 @@ $ sudo systemctl start crau-agent.service
 ```console
 $ crau-monitor
 ```
-7. On another terminal, run any commands using the instrumented library
+7. On another terminal, run any commands using the instrumented library, such as GnuTLS in Fedora Linux 43 or later
 ```console
 $ gnutls-serv --x509certfile=doc/credentials/x509/cert-rsa-pss.pem --x509keyfile=doc/credentials/x509/key-rsa-pss.pem &
 $ gnutls-cli --x509cafile=doc/credentials/x509/ca.pem localhost -p 5556
@@ -103,7 +103,7 @@ $ crau-query --log-file audit.cborseq
         "start": 49431631956782,
         "end": 49431631963209,
         "events": {
-          "name": "tls::certificate_verify",
+          "name": "tls::verify",
           "tls::signature_algorithm": 2057
         }
       }
@@ -124,7 +124,7 @@ $ crau-query --log-file audit.cborseq
         "start": 49431628203429,
         "end": 49431628207396,
         "events": {
-          "name": "tls::certificate_verify",
+          "name": "tls::verify",
           "tls::signature_algorithm": 2057
         }
       }
@@ -145,7 +145,7 @@ $ crau-query --log-file audit.cborseq
         "start": 49434509684783,
         "end": 49434509694813,
         "events": {
-          "name": "tls::certificate_verify",
+          "name": "tls::verify",
           "tls::signature_algorithm": 2057
         }
       }
@@ -166,7 +166,7 @@ $ crau-query --log-file audit.cborseq
         "start": 49434503929186,
         "end": 49434503940540,
         "events": {
-          "name": "tls::certificate_verify",
+          "name": "tls::verify",
           "tls::signature_algorithm": 2057
         }
       }

crypto-auditing/src/types.rs

@@ -124,7 +124,7 @@ impl ContextTracker {
                     if !self.all_contexts.contains_key(group.context()) {
                         // Either this library did not do a new_context for this context, or the
                         // log we have is truncated at the beginning. Just assume that this context
-                        // has no parent and create a new one so we don't loose the information in
+                        // has no parent and create a new one so we don't lose the information in
                         // this message.
                         let context_obj = Rc::new(RefCell::new(Context {
                             id: *group.context(),

docs/architecture.md

@@ -4,8 +4,8 @@
 - [Summary](#summary)
 - [Design Details](#design-details)
   - [Architecture](#architecture)
-  - [crypto-auditing agent](#crypto-auditing-agent)
-  - [crypto-auditing event broker](#crypto-auditing-event-broker)
+  - [crau-agent](#crau-agent)
+  - [Log analysis tools](#log-analysis-tools)
 <!-- /toc -->
 
 ## Summary
@@ -19,48 +19,35 @@ The following figure illustrates the proposed architecture.
 
 ![](architecture.svg)
 
-At the highest level, the architecture can be seen as a variant of
-[MQTT] (Message Queuing Telemetry Transport): the programs being
-monitored acts as a publisher, the programs consume the collected
-information act as a subscriber, and there will be intermediate
-components that coordinate the communication flow between them.
+At the highest level, the architecture consists of two parts:
+crau-agent and log analysis tools (crau-query, crau-monitor).
 
-- **crypto-auditing agent**: A program that receives events from publishers and write them onto the primary log storage
-- **crypto-auditing event broker**: A program that accesses the primary log storage and notify the subscribers
+crau-agent runs as a system service, receives cryptographic events
+from the kernel through eBPF, and writes them onto the primary log
+file.
 
-### crypto-auditing agent
+Log analysis tools provide users with access to the primary log
+storage.
 
-The responsibilities of crypto-auditing agent include:
+### crau-agent
 
-- Install BPF program to monitor USDT
-- Get notified an event when USDT is reached
-- Write events to primary log storage
+The responsibilities of crau-agent include:
 
-The agent is meant to work as fast as possible, while it shouldn't be
-resource intensive, by utilizing asynchronous I/O mechanisms for
-communicating with the publishers, through the kernel ([BPF ring
-buffer] and [io_uring]).
+- Install BPF program to monitor USDT events
+- Receive notification events on execution reaching USDT probes
+- Write received events to primary log file
 
-### crypto-auditing event broker
+The agent is meant to work as fast as possible with minimal resource
+consumption. The current implementation leverages [eBPF ring buffers]
+and [io_uring] for asynchronous I/O.
 
-The event broker is the only process which has direct access to the
-primary log storage on behalf of the subscribers.  The
-responsibilities of event broker include:
+### Log analysis tools
 
-- Subscription management
-  - Accept connections from subscribers
-  - Deliver events to subscribers
-  - For each event, ensure every subscriber receives it at most once
-- Event management
-  - Read events from primary log storage
-  - Truncate primary log storage based on policies, such as certain time has elapsed, and/or all subscribers have read (or skipped) certain range of event sequence
+The log analysis tools provides ways to access the primary log file,
+either at any later time or at real-time.
 
-The event broker caters for multiple types of subscribers: some may
-periodically (daily, for example) check the log and calculate
-statistics, and others may immediately consume events and provide
-real-time diagnostics.
+The current implementation contains crau-query for the former, and
+crau-monitor for the latter.
 
-[MQTT]: https://mqtt.org
 [BPF ring buffer]: https://www.kernel.org/doc/html/latest/bpf/ringbuf.html
 [io_uring]: https://en.wikipedia.org/wiki/Io_uring
-