diff --git a/README.md b/README.md index 629cd72..499bf85 100644 --- a/README.md +++ b/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 } } diff --git a/crypto-auditing/src/types.rs b/crypto-auditing/src/types.rs index 5241899..f9cccf2 100644 --- a/crypto-auditing/src/types.rs +++ b/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(), diff --git a/docs/architecture.md b/docs/architecture.md index bb98e51..dff850d 100644 --- a/docs/architecture.md +++ b/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) ## 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 - diff --git a/docs/architecture.odg b/docs/architecture.odg index b200f01..2629fed 100644 Binary files a/docs/architecture.odg and b/docs/architecture.odg differ diff --git a/docs/architecture.svg b/docs/architecture.svg index 5af5bbd..3f1ccd5 100644 --- a/docs/architecture.svg +++ b/docs/architecture.svg @@ -1,6 +1,6 @@ - + @@ -11,50 +11,59 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + - + @@ -101,294 +110,208 @@ - - - - Kernel + + + - - - - crypto-auditingagent + + + + Kernel - - - - - + + + + crypto-auditingagent - - - - - + + + + crau-query - - - - crypto-auditingevent broker + + + + + + Log file(CBOR) - - - - - - Primary log storage + + + + BPF program - - - - BPF program + + + + Shared library - - - - Shared library + + + + Target program - - - - Insights sink + + + + Target program - - - - Real-time auditsink + + + + Shared library - - - - Target program + + + + Target program - - - - Target program + + + + Target program - + - - - - Shared library + + + + Read - + - - - - - - Statistics for Insights(daily) + + + + Attach - + - - - - Insights client + + + + Attach - - - - Target program + - - - - Target program + + + + crau-agent - + - - - - Write + - - - - Read + + + - - - - Attach + + + - - - - Attach + + + - - - - Subscribe + + + - - - - - - - - - - - - - - - - - Use - - - - - - BPF ring buffer - - - - - - io_uring + + + - - + + + + + USDT - - - - - crypto-auditingagent + + + + + USDT - - - - - - - - - - - - - - - - - - - - - - - - Use - - - - - - - - - - - - - - + + + + + crau-monitor - - - - - - - - - - - - USDT - - - - - - - - USDT + + + + + Write diff --git a/docs/logging-format.md b/docs/logging-format.md index 9c2ae6d..278136d 100644 --- a/docs/logging-format.md +++ b/docs/logging-format.md @@ -75,7 +75,7 @@ a more efficient (binary) format will be used in practical deployment. { "type": "string_data", "context": "00..02", - "name": "tls::certificate_verify" + "name": "tls::verify" }, { "type": "word_data", @@ -94,7 +94,7 @@ This can be conceptually represented as a tree of events: - `tls::handshake_client` (00..01) - `tls::protocol_version` = 0x0304 - - `tls::certificate_verify` (00..02) + - `tls::verify` (00..02) - `tls::signature_algorithm` = 0x0804 - `pk::bits` = 3072 @@ -159,7 +159,7 @@ like the following, preserving the same semantics: }, { "type": "string_data", - "name": "tls::certificate_verify" + "name": "tls::verify" }, { "type": "word_data", @@ -210,13 +210,13 @@ and TLS probe points. ##### TLS context names -| name | description | -|---------------------------|------------------------------------------------------------------| -| `tls::handshake_client` | TLS handshake for client | -| `tls::handshake_server` | TLS handshake for server | -| `tls::certificate_sign` | Digital signature is created using certificate in TLS handshake | -| `tls::certificate_verify` | Digital signature is verified using certificate in TLS handshake | -| `tls::key_exchange` | Shared secret derivation in TLS handshake | +| name | description | +|-------------------------|------------------------------------------------------------------| +| `tls::handshake_client` | TLS handshake for client | +| `tls::handshake_server` | TLS handshake for server | +| `tls::sign` | Digital signature is created using certificate in TLS handshake | +| `tls::verify` | Digital signature is verified using certificate in TLS handshake | +| `tls::key_exchange` | Shared secret derivation in TLS handshake | ##### TLS keys @@ -286,7 +286,7 @@ These contexts are only useful when a public key operation cannot be determined from the outer context. If it is obvious from the outer context, the probe point provider may choose to not create a new context. For example, when the parent context is -`tls::certificate_verify`, there is no need to create a new context +`tls::verify`, there is no need to create a new context with `pk::verify`. | name | description | diff --git a/monitor/src/monitor.rs b/monitor/src/monitor.rs index bd0868e..8a7ba6b 100644 --- a/monitor/src/monitor.rs +++ b/monitor/src/monitor.rs @@ -153,7 +153,7 @@ async fn shutdown( if let Err(e) = maybe_value { info!(error = %e, "error receiving ctrl-c") } - info!("shutting down event broker"); + info!("shutting down event monitor"); if let Err(e) = shutdown_sender.send(()) { info!(error = %e, "unable to send shutdown"); }