The C-Agent is a reference implementation of a Keyfactor Remote Agent geared toward use in IoT based solutions. The Keyfactor-CAgent can be built for three (3) different modes:
- openSSL
- wolfSSL
- Raspberry Pi SPI TPM (e.g., SLB9760 or STPM4RasPI)
sudo apt update
sudo apt install -y build-essential git libcurl4-gnutls-dev curl libssl-dev
sudo dnf update -y
sudo dnf groupinstall -y "Development Tools"
sudo dnf install -y curl-devel curl openssl-devel
cd ~
git clone https://github.com/Keyfactor/Keyfactor-CAgent
cd ~/Keyfactor-CAgent
make clean
make opentest -j$(nproc)
cd ~/Keyfactor-CAgent
make clean
make openpi -j$(nproc)
sudo apt update
sudo apt install -y build-essential git automake autoconf libtool pkg-config wget
sudo yum update
sudo yum install -y build-essential git automake autoconf libtool pkg-config wget
Make sure the Wolf dependencies are loaded. Then clone the latest wolfSSL version (minimum v4.4.0), configure and build the version as follows:
cd ~
wget https://github.com/wolfSSL/wolfssl/archive/v5.0.0-stable.tar.gz
tar -xzf v5.0.0-stable.tar.gz
cd wolfssl-5.0.0-stable
./autogen.sh
./configure --enable-tls13 --enable-all
make
sudo make install
sudo ldconfig -v | grep libwolfssl
libwolfssl.so.30 -> libwolfssl.so.30.0.0
cd ~
wget https://github.com/curl/curl/archive/refs/tags/curl-7_81_0.tar.gz
tar -xvf curl-7_81_0.tar.gz
cd ~/
cd curl-curl-7_81_0/
autoreconf -fi
./configure --enable-warnings --enable-werror --enable-headers-api --with-wolfssl --enable-debug
make -j$(nproc)
sudo make install
sudo ldconfig
cd ~
git clone https://github.com/Keyfactor/Keyfactor-CAgent
cd ~/Keyfactor-CAgent
make clean
make wolftest -j$(nproc)
cd ~/Keyfactor-CAgent
make clean
make wolftest -j$(nproc)
Coming soon
sudo mkdir --parents /home/keyfactor/Keyfactor-CAgent/certs/
sudo chown $(whoami):$(whoami) /home/keyfactor/Keyfactor-CAgent/certs
First get your Test Instance's Root Certificate by navigating to the Marketplace instance web site & downloading the certificate as a PEM file.
nano /home/keyfactor/Keyfactor-CAgent/certs/trust.store
cd ~/Keyfactor-CAgent
nano config.json
Add these data lines into the file, replacing the Hostname, Username, and Password entries with the relevant data from your Marketplace instance.
{
"AgentId": "",
"AgentName": "UniqueName",
"Hostname": "www.yourtestdrive.com",
"Username": "testdrive\\yourusername",
"Password": "yourpassword",
"VirtualDirectory": "KeyfactorAgents",
"TrustStore": "/home/keyfactor/Keyfactor-CAgent/certs/trust.store",
"AgentCert": "/home/keyfactor/Keyfactor-CAgent/certs/Agent-cert.pem",
"AgentKey": "/home/keyfactor/Keyfactor-CAgent/certs/Agent-key.pem",
"CSRKeyType": "ECC",
"CSRKeySize": 256,
"CSRSubject": "CN=UniqueName",
"EnrollOnStartup": true,
"UseSsl": true,
"LogFile": "agent.log"
}
In a full implementation, this data is either secured in trusted element space and/or encrypted and stored as a blob.
To allow easier exploration, this is not done here & is implemented depending on physical hardware and business requirements.
cd ~/Keyfactor-CAgent
./agent -l t
./agent -l <switch_see_below> enables logging (default is info)
./agent -l t is the greatest detail mode and includes traced curl output
./agent -l d lists all message details other than trace details
./agent -l v lists all verbose and below messages
./agent -l i lists all info, warn, and error messages
./agent -l w lists all warning and error messages
./agent -l e lists only error messages
./agent -l o turns off all output messages
./agent -c <path_and_filename> overrides the default configuration file
./agent -h overrides the agent name with $HOSTNAME_$DATETIME
./agent -a adds the client certificate presented for mTLS into a header field named X-ARR-ClientCert
Use this (along with client certificate authentication) in Keyfactor if the platform
is configured to look for this certificate header.
./agent -e <engine> the crypto engine to use (e.g., tpm2tss) NOTE:
must compile the TPM version of the agent
AgentID : Assigned by Keyfactor Control. Please leave blank.
AgentName : Leave blank if using the -h argument with the agent. This is if not using the -h switch.
ClientParameterPath : Used to pass optional client parameters to the Registration session.
Hostname : Either the IP address or the FQDN of the Keyfactor Control Web Address
Password : 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.
Username : 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.
VirtualDirectory : 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.
TrustStore : 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.
AgentCert : The (eventual) location of the Agent's certificate. This is the certificate used by the Agent to call into the platform.
AgentKey : The (eventual) location of the Agent's private key. This is the key used by the Agent to call into the platform.
AgentKeyPassword : An optional passphrase for decoding the Agent Key. Note, if a TPM, Secure Element, or secure area is used, this must be defined.
CSRKeyType : The Key type for the AgentKey (ECC or RSA). This must match the template defined in the Keyfactor Platform.
CSRKeySize : The Key size for the AgentKey. This must be equal to or greater than the minimum size defined in the template.
CSRSubject : If the -h command line switch is used, this field is not used. This field is if the command line switch is not used.
EnrollOnStartup : true = The agent will register itself with the platform. The agent will set this to false once the agent has registered and been approved.
UseBootstrapCert : true = Use a bootstrap certificate when registering with the platform. false = otherwise.
BootstrapCert : <optional/required> If UseBootstrapCert is true, this is required & is the path/filename for the certificate.
BootstrapKey : <optional/required> If UseBootstrapCert is false, this is required & is the path/filename of the private key for the bootstrap certificate.
BootstrapKeyPassword : An optional passphrase used to decode the bootstrap key.
UseSsl : 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.
Serialize : 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 )
SerialFile : The location of a mounted nfs file store & file to use in the serialization operation.
LogFile : 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)
httpRetries : The number of times the agent will attempt to connect to the Keyfactor Control platform before recording an error. Minimum value is 1.
retryInterval : The time delay (in seconds) between httpRetries.
LogFileIndex : This is used as an index into the LogFile to allow for a rolling maximum sized log file.