You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
## Install the __dependencies__ depending on your Linux distribution:
37
34
38
-
##Overview
39
-
40
-
The Keyfactor C-Agent provides secure communication between IoT devices and the Keyfactor Control Platform. This guide walks you through building and configuring the agent for different modes.
35
+
#### Debian based (e.g., Poky, Ubuntu, Raspian, Raspberry Pi OS, etc.)
#### The Agent uses a config.json file to provide inputs into the system.
168
+
#### For this reference example, we use unencrypted passwords, usernames, and the like.
169
+
#### In a full implementation, this data is either secured in trusted element space and/or encrypted and stored as a blob.
170
+
#### To allow easier exploration, this is not done here & is implemented depending on physical hardware and business requirements.
171
+
172
+
---
172
173
173
174
### Run the Agent
174
175
```bash
@@ -178,23 +179,83 @@ cd ~/Keyfactor-CAgent
178
179
179
180
---
180
181
181
-
## Appendix
182
+
#
183
+
# APPENDIX A: Agent switches
182
184
183
-
### Agent Switches
184
-
[List all switches here with examples.]
185
+
./agent -l <switch_see_below> enables logging (default is info)
186
+
./agent -l t is the greatest detail mode and includes traced curl output
187
+
./agent -l d lists all message details other than trace details
188
+
./agent -l v lists all verbose and below messages
189
+
./agent -l i lists all info, warn, and error messages
190
+
./agent -l w lists all warning and error messages
191
+
./agent -l e lists only error messages
192
+
./agent -l o turns off all output messages
185
193
186
-
### Complete Configuration File Data
187
-
[Include detailed explanations of configuration fields.]
194
+
./agent -c <path_and_filename> overrides the default configuration file
188
195
189
-
---
196
+
./agent -h overrides the agent name with $HOSTNAME_$DATETIME
190
197
191
-
## Troubleshooting
198
+
./agent -a adds the client certificate presented for mTLS into a header field named X-ARR-ClientCert
199
+
Use this (along with client certificate authentication) in Keyfactor if the platform
200
+
is configured to look for this certificate header.
192
201
193
-
-**Dependency Installation Errors**: Ensure your system package manager is updated.
194
-
-**Build Errors**: Verify all dependencies are installed and compatible.
195
-
-**Runtime Issues**: Check logs with `-l t` for detailed output.
202
+
./agent -e <engine> the crypto engine to use (e.g., tpm2tss) NOTE:
203
+
must compile the TPM version of the agent
196
204
197
-
---
205
+
# APPENDIX B: Complete Configuration file data
206
+
__AgentID__ : Assigned by Keyfactor Control. Please leave blank.
207
+
208
+
__AgentName__ : <optional> Leave blank if using the `-h` argument with the agent. This is <required> if not using the `-h` switch.
209
+
210
+
__ClientParameterPath__ : <optional> Used to pass optional client parameters to the Registration session.
211
+
212
+
__Hostname__ : <required> Either the IP address or the FQDN of the Keyfactor Control Web Address
213
+
214
+
__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.
215
+
216
+
__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.
217
+
218
+
__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.
219
+
220
+
__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.
221
+
222
+
__AgentCert__ : <required> The (eventual) location of the Agent's certificate. This is the certificate used by the Agent to call into the platform.
223
+
224
+
__AgentKey__ : <required> The (eventual) location of the Agent's private key. This is the key used by the Agent to call into the platform.
225
+
226
+
__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**.
227
+
228
+
__CSRKeyType__ : <required> The Key type for the AgentKey (ECC or RSA). This must match the template defined in the Keyfactor Platform.
229
+
230
+
__CSRKeySize__ : <required> The Key size for the AgentKey. This must be equal to or greater than the minimum size defined in the template.
231
+
232
+
__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.
233
+
234
+
__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.
235
+
236
+
__UseBootstrapCert__ : <optional> true = Use a bootstrap certificate when registering with the platform. false = otherwise.
237
+
238
+
__BootstrapCert__ : <optional/required> If UseBootstrapCert is true, this is required & is the path/filename for the certificate.
239
+
240
+
__BootstrapKey__ : <optional/required> If UseBootstrapCert is false, this is required & is the path/filename of the private key for the bootstrap certificate.
241
+
242
+
__BootstrapKeyPassword__ : <optional> An optional passphrase used to decode the bootstrap key.
243
+
244
+
__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.
245
+
246
+
__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) )
247
+
248
+
__SerialFile__ : <optional> The location of a mounted nfs file store & file to use in the serialization operation.
249
+
250
+
__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)
251
+
252
+
__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.
253
+
254
+
__retryInterval__ : <required> The time delay (in seconds) between httpRetries.
255
+
256
+
__LogFileIndex__ : <AgentUseOnly> This is used as an index into the LogFile to allow for a rolling maximum sized log file.
257
+
258
+
#### __WARNING:__ if the Agent's LogFile is deleted, this **has** to be set to zero (0).
198
259
199
260
## Contributing
200
261
@@ -204,4 +265,4 @@ Contributions are welcome! Submit issues or pull requests on [GitHub](https://gi
204
265
205
266
## License
206
267
207
-
This project is licensed under the MIT License. See the `LICENSE` file for details.
268
+
This project is licensed under the Apache-2.0 License. See the `README-LICENSE.txt` file for details.
0 commit comments