Skip to content

Commit 140282a

Browse files
rlillbackrlillback
committed
Release v3.0.0.0
1 parent 637f7f7 commit 140282a

48 files changed

Lines changed: 15340 additions & 13341 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitignore‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,3 +73,13 @@ valgrind.log
7373
# Sig files
7474
signature/
7575
.idea/
76+
.clang-format
77+
78+
# Claude Code
79+
.claude/
80+
.claude/settings.local.json
81+
CLAUDE.md
82+
.mcp.json
83+
84+
# Build artifiacts and structure
85+
build/

‎README.md‎

Lines changed: 44 additions & 248 deletions
Original file line numberDiff line numberDiff line change
@@ -1,272 +1,68 @@
1-
# C-Agent
2-
![Build Status](https://img.shields.io/badge/build-passing-brightgreen) ![License](https://img.shields.io/badge/license-Apache%20License%202.0-blue)
1+
# Keyfactor C-Agent
32

4-
The C-Agent is a reference implementation of a Keyfactor Remote Agent geared toward use in IoT based solutions.
5-
The Keyfactor-CAgent can be built for three (3) different modes:
6-
- **openSSL**
7-
- **wolfSSL**
8-
- **Raspberry Pi SPI TPM** (Coming Soon)
9-
---
10-
## Table of Contents
11-
1. [Overview](#overview)
12-
2. [OpenSSL Build](#openssl-build)
13-
- [Install Dependencies](#install-dependencies)
14-
- [Clone the Repository](#clone-the-repository)
15-
- [Build the Agent](#build-the-agent)
16-
3. [WolfSSL Build](#wolfssl-build)
17-
- [Install Dependencies](#install-dependencies-1)
18-
- [Build WolfSSL](#build-wolfssl)
19-
- [Build cURL](#build-curl)
20-
- [Build the Agent](#build-the-agent-1)
21-
4. [TPM Build (Coming Soon)](#tpm-build-coming-soon)
22-
5. [Common Configuration Steps](#common-configuration-steps)
23-
- [Set Up Directories and Trust Store](#set-up-directories-and-trust-store)
24-
- [Modify Configuration File](#modify-configuration-file)
25-
- [Run the Agent](#run-the-agent)
26-
6. [Appendix](#appendix)
27-
- [Agent Switches](#agent-switches)
28-
- [Complete Configuration File Data](#complete-configuration-file-data)
29-
7. [License](#license)
30-
8. [Contributing](#contributing)
31-
---
32-
## OpenSSL build
33-
## Install the __dependencies__ depending on your Linux distribution:
3+
![License](https://img.shields.io/badge/license-Apache%202.0-blue)
344

35-
#### Debian based (e.g., Poky, Ubuntu, Raspian, Raspberry Pi OS, etc.)
36-
sudo apt update
37-
sudo apt install -y build-essential git libcurl4-gnutls-dev curl libssl-dev
5+
A reference implementation of a Keyfactor Command remote agent written
6+
in C, aimed at IoT and embedded Linux deployments. The agent registers
7+
a session with the Keyfactor Command platform, runs any PEM inventory,
8+
management, or reenrollment jobs the platform assigns, and exits.
389

39-
#### RHEL based (RHEL, CentOS, Rocky, etc.)
40-
sudo dnf update
41-
sudo dnf install -y "Development Tools"
42-
sudo dnf install -y git curl-devel curl openssl-devel
10+
Current version: **3.0.0.0** (see
11+
[`agent.h`](agent.h)). Supported crypto backends:
4312

44-
## Clone the git repository
45-
cd ~
46-
git clone https://github.com/Keyfactor/Keyfactor-CAgent
13+
- OpenSSL
14+
- wolfSSL
15+
- OpenSSL + `tpm2tss` engine (TPM-backed private keys)
4716

48-
## Build the agent against the OpenSSL target (64-bit OSes - not Raspberry Pi)
49-
cd ~/Keyfactor-CAgent
50-
make clean
51-
make opentest -j$(nproc)
17+
## Quick start
5218

53-
## Build the agent against the openSSL target for 32-bit OSes like RaspOS
54-
cd ~/Keyfactor-CAgent
55-
make clean
56-
make openpi -j$(nproc)
57-
58-
## Configure and run the Agent (see below)
59-
60-
---
61-
62-
## WolfSSL Build
63-
64-
### Install Dependencies
65-
66-
#### Debian-based Distributions
6719
```bash
20+
# 1. Install host dependencies (Debian/Ubuntu example).
6821
sudo apt update
69-
sudo apt install -y build-essential git automake autoconf libtool pkg-config wget
70-
```
71-
72-
#### RHEL-based Distributions
73-
```bash
74-
sudo dnf update
75-
sudo dnf groupinstall -y "Development Tools"
76-
sudo dnf install -y build-essential git automake autoconf libtool pkg-config wget
77-
```
78-
79-
### Build WolfSSL
80-
```bash
81-
cd ~
82-
wget https://github.com/wolfSSL/wolfssl/archive/v5.0.0-stable.tar.gz
83-
tar -xzf v5.0.0-stable.tar.gz
84-
cd wolfssl-5.0.0-stable
85-
./autogen.sh
86-
./configure --enable-tls13 --enable-all
87-
make
88-
sudo make install
89-
sudo ldconfig -v | grep libwolfssl
90-
```
91-
92-
Ensure the output includes:
93-
```
94-
libwolfssl.so.30 -> libwolfssl.so.30.0.0
95-
```
96-
97-
### Build cURL with WolfSSL
98-
```bash
99-
cd ~
100-
wget https://github.com/curl/curl/archive/refs/tags/curl-7_81_0.tar.gz
101-
tar -xvf curl-7_81_0.tar.gz
102-
cd curl-curl-7_81_0/
103-
autoreconf -fi
104-
./configure --with-wolfssl
105-
make -j$(nproc)
106-
sudo make install
107-
sudo ldconfig
108-
```
109-
110-
### Build the Agent
22+
sudo apt install -y build-essential git curl libcurl4-gnutls-dev libssl-dev
11123

112-
#### 64-bit OSes
113-
```bash
24+
# 2. Clone and build against OpenSSL (64-bit host).
25+
git clone https://github.com/keyfactor-iot/Keyfactor-CAgent ~/Keyfactor-CAgent
11426
cd ~/Keyfactor-CAgent
11527
make clean
116-
make wolftest -j$(nproc)
117-
```
118-
119-
#### 32-bit OSes
120-
```bash
121-
cd ~/Keyfactor-CAgent
122-
make clean
123-
make wolftest -j$(nproc)
124-
```
125-
126-
---
127-
128-
## TPM Build (Coming Soon)
28+
make CRYPTO=openssl OUT=exec -j$(nproc)
12929

130-
This feature is under development. Stay tuned for updates.
131-
132-
---
133-
## Common Configuration Steps
134-
135-
### Set Up Directories and Trust Store
136-
```bash
137-
sudo mkdir --parents /home/keyfactor/Keyfactor-CAgent/certs/
30+
# 3. Set up trust store and config.
31+
sudo mkdir -p /home/keyfactor/Keyfactor-CAgent/certs
13832
sudo chown $(whoami):$(whoami) /home/keyfactor/Keyfactor-CAgent/certs
139-
nano /home/keyfactor/Keyfactor-CAgent/certs/trust.store
140-
```
141-
Copy the PEM-formatted certificate into the `trust.store` file.
142-
143-
### Modify Configuration File
144-
```bash
145-
cd ~/Keyfactor-CAgent
146-
nano config.json
147-
```
148-
#### Add these data lines into the file, replacing the Hostname, Username, and Password entries with the relevant data from your Marketplace instance.
149-
#### Also replace the Agent name and CSR Subject with a unique name to your Marketplace instance.
150-
#### Also note this file is case senstivive!
151-
{
152-
"AgentId": "",
153-
"AgentName": "UniqueName",
154-
"Hostname": "www.yourtestdrive.com",
155-
"Username": "testdrive\\yourusername",
156-
"Password": "yourpassword",
157-
"VirtualDirectory": "KeyfactorAgents",
158-
"TrustStore": "/home/keyfactor/Keyfactor-CAgent/certs/trust.store",
159-
"AgentCert": "/home/keyfactor/Keyfactor-CAgent/certs/Agent-cert.pem",
160-
"AgentKey": "/home/keyfactor/Keyfactor-CAgent/certs/Agent-key.pem",
161-
"CSRKeyType": "ECC",
162-
"CSRKeySize": 256,
163-
"CSRSubject": "CN=UniqueName",
164-
"EnrollOnStartup": true,
165-
"UseSsl": true,
166-
"LogFile": "agent.log"
167-
}
168-
169-
#### The Agent uses a config.json file to provide inputs into the system.
170-
#### For this reference example, we use unencrypted passwords, usernames, and the like.
171-
#### In a full implementation, this data is either secured in trusted element space and/or encrypted and stored as a blob.
172-
#### To allow easier exploration, this is not done here & is implemented depending on physical hardware and business requirements.
33+
$EDITOR /home/keyfactor/Keyfactor-CAgent/certs/trust.store # paste PEM CA bundle
34+
cp config.json.example config.json # or create from the template in docs/configuration.md
35+
$EDITOR config.json # set Hostname, AgentName, credentials, cert paths
17336

174-
---
175-
176-
### Run the Agent
177-
```bash
178-
cd ~/Keyfactor-CAgent
179-
./agent -l t
37+
# 4. Run.
38+
./agent -l i
18039
```
18140

182-
---
183-
184-
#
185-
# APPENDIX A: Agent switches
186-
187-
./agent -l <switch_see_below> enables logging (default is info)
188-
./agent -l t is the greatest detail mode and includes traced curl output
189-
./agent -l d lists all message details other than trace details
190-
./agent -l v lists all verbose and below messages
191-
./agent -l i lists all info, warn, and error messages
192-
./agent -l w lists all warning and error messages
193-
./agent -l e lists only error messages
194-
./agent -l o turns off all output messages
195-
196-
./agent -c <path_and_filename> overrides the default configuration file
197-
198-
./agent -h overrides the agent name with $HOSTNAME_$DATETIME
199-
200-
./agent -a adds the client certificate presented for mTLS into a header field named X-ARR-ClientCert
201-
Use this (along with client certificate authentication) in Keyfactor if the platform
202-
is configured to look for this certificate header.
203-
204-
./agent -e <engine> the crypto engine to use (e.g., tpm2tss) NOTE:
205-
must compile the TPM version of the agent
206-
207-
# APPENDIX B: Complete Configuration file data
208-
__AgentID__ : Assigned by Keyfactor Control. Please leave blank.
209-
210-
__AgentName__ : <optional> Leave blank if using the `-h` argument with the agent. This is <required> if not using the `-h` switch.
211-
212-
__ClientParameterPath__ : <optional> Used to pass optional client parameters to the Registration session.
213-
214-
__Hostname__ : <required> Either the IP address or the FQDN of the Keyfactor Control Web Address
215-
216-
__Password__ : <optional> If using basic authentication to the Keyfactor Control Platform, then the password for the user. This can also be omitted if a reverse proxy is injecting authentication credentials into the HTTP header.
217-
218-
__Username__ : <optional> If using basic authentication to the Keyfactor Control Platform, then the domain and username to log into the Keyfactor Control Platform (remember, the \ character must be escaped -- e.g., KEYFACTOR\\Administrator). This can also be omitted if a reverse proxy is injecting authentication credentials into the HTTP header.
219-
220-
__VirtualDirectory__ : <required> Set this to KeyfactorAgents if you are not using a reverse proxy. If you are using a reverse-proxy, set it to the virtual directory that is mapped to KeyfactorAgents.
221-
222-
__TrustStore__ : <required> The location of additional certificates that are trusted by the Agent. This list is appended to the standard CA certificate store located in `/etc/ssl/certs/ca-certificates.crt` for Ubuntu.
223-
224-
__UseAgentCert__ : <optional> Defaults to true if not supplied. True = use an agent managed cert for mTLS. False = only use 1-way TLS for the agent. */
225-
226-
__AgentCert__ : <optional/required> The (eventual) location of the Agent's certificate. This is the certificate used by the Agent to call into the platform.
41+
For wolfSSL, 32-bit targets, shared-library packaging, and TPM builds,
42+
see [`docs/build.md`](docs/build.md).
22743

228-
__AgentKey__ : <optional/required> The (eventual) location of the Agent's private key. This is the key used by the Agent to call into the platform.
44+
## Documentation
22945

230-
__AgentKeyPassword__ : <optional> An optional passphrase for decoding the Agent Key. Note, if a TPM, Secure Element, or secure area is used, this **must be defined**.
46+
The `docs/` directory contains the full, code-derived documentation:
23147

232-
__CSRKeyType__ : <required> The Key type for the AgentKey (ECC or RSA). This must match the template defined in the Keyfactor Platform.
48+
| Document | Purpose |
49+
|----------------------------------------------------------------------|---------|
50+
| [`docs/overview.md`](docs/overview.md) | What the agent is, supported capabilities, session lifecycle at a glance, non-goals. |
51+
| [`docs/installation.md`](docs/installation.md) | Host prerequisites (Debian/Ubuntu, RHEL family) and how to clone the repo. |
52+
| [`docs/build.md`](docs/build.md) | Every `makefile` target (OpenSSL, wolfSSL, shared library, TPM), 32-bit vs 64-bit, build flags. |
53+
| [`docs/configuration.md`](docs/configuration.md) | Full `config.json` reference aligned to the in-code `ConfigData_t`, trust store setup, `ClientParameterPath` / `params.json` explained. |
54+
| [`docs/cli.md`](docs/cli.md) | Command-line switches (`-a`, `-c`, `-e`, `-h`, `-l`, `-v`, `-?`) with examples. |
55+
| [`docs/architecture.md`](docs/architecture.md) | Module-by-module map, session lifecycle, job dispatch, chained jobs, crypto abstraction, DTO layer. |
56+
| [`docs/logging.md`](docs/logging.md) | Log levels, the 5 MB rolling log file, and the self-healing `.index` sidecar. |
57+
| [`docs/enrollment-and-certificates.md`](docs/enrollment-and-certificates.md) | Managed vs bootstrap cert flows, CSR generation, two-step first registration, cert renewal. |
58+
| [`docs/development.md`](docs/development.md) | Code style, compiler flags, versioning, memory hygiene, contributing. |
23359

234-
__CSRKeySize__ : <required> The Key size for the AgentKey. This must be equal to or greater than the minimum size defined in the template.
235-
236-
__CSRSubject__ : <optional> If the `-h` command line switch is used, this field is not used. This field is <required> if the command line switch is not used.
237-
238-
__EnrollOnStartup__ : <required> true = The agent will register itself with the platform. The agent will set this to false once the agent has registered and been approved.
239-
240-
__UseBootstrapCert__ : <optional> true = Use a bootstrap certificate when registering with the platform. false = otherwise.
241-
242-
__BootstrapCert__ : <optional/required> If UseBootstrapCert is true, this is required & is the path/filename for the certificate.
243-
244-
__BootstrapKey__ : <optional/required> If UseBootstrapCert is false, this is required & is the path/filename of the private key for the bootstrap certificate.
245-
246-
__BootstrapKeyPassword__ : <optional> An optional passphrase used to decode the bootstrap key.
247-
248-
__UseSsl__ : <required> true = https:// is used. false = http:// is used. Both refer to the Keyfactor Control Platform communications. Really, this should always be true in a production environment.
249-
250-
__Serialize__ : <optional> true = use a shared network file to grab a serial number/name combination for the AgentName and CN. false = otherwise.Typically this is an nfs file store that is on the production line. Most IoT implementations do not use this method, as UKIDs and names are defined by the host and UKID chips (e.g., [1-wire EEPROM with 64-bit UKID](https://www.microchip.com/wwwproducts/en/AT21CS01) )
251-
252-
__SerialFile__ : <optional> The location of a mounted nfs file store & file to use in the serialization operation.
253-
254-
__LogFile__ : <required> The path/filename of a log file for the agent. **NOTE:** This log file uses the same logging level as the agent. (See command line arguments for the agent)
255-
256-
__httpRetries__ : <required> The number of times the agent will attempt to connect to the Keyfactor Control platform before recording an error. Minimum value is 1.
257-
258-
__retryInterval__ : <required> The time delay (in seconds) between httpRetries.
259-
260-
__LogFileIndex__ : <AgentUseOnly> This is used as an index into the LogFile to allow for a rolling maximum sized log file.
60+
## License
26161

262-
#### __WARNING:__ if the Agent's LogFile is deleted, this **has** to be set to zero (0).
62+
Apache-2.0. Full license text in
63+
[`README-LICENSE.txt`](README-LICENSE.txt).
26364

26465
## Contributing
26566

266-
Contributions are welcome! Submit issues or pull requests on [GitHub](https://github.com/Keyfactor/Keyfactor-CAgent).
267-
268-
---
269-
270-
## License
271-
272-
This project is licensed under the Apache-2.0 License. See the `README-LICENSE.txt` file for details.
67+
Issues and pull requests: <https://github.com/keyfactor-iot/Keyfactor-CAgent>.
68+
See [`docs/development.md`](docs/development.md) before opening a PR.

0 commit comments

Comments
 (0)