Cryptography

Every aspect of RADKit is designed with security in mind. Both RADKit Cloud and the RADKit endpoints (Client/Service and related applications) follow Cisco’s Secure Development Lifecycle (CSDL).

Database & secrets 

The entire RADKit Service database is AES-128/SHA-256 encrypted with a strong unique random key.

RADKit Service handles three types of secrets:

Private keys: For various certificates (Service identity, Service webserver, E2EE). Stored on disk as PKCS#8 files; each file is AES-256/SHA-256 encrypted with a strong unique random key.
Device credentials: Including passwords and SSH private keys. Stored in the Service database. Doubly encrypted (stored in the database as ciphertext protected by a key derived from the superadmin password).
Local account credentials: All account passwords are salted and hashed with SHA-512. Service admin account password hashes are stored in the Service database, while the superadmin password hash is stored together with the vault (see below).

The encryption keys for the private keys and database are stored in a vault file which is in turn AES-128/SHA-256 encrypted using a key derived from the superadmin password. In other words, the superadmin password acts as the master key for all RADKit Service secrets. If it is lost, the database and secrets cannot be recovered.

Exporting secrets 

The database and vault contents can be exported and decrypted for inspection by using the following subcommands:

radkit-service export-db [--decrypt-secrets]
radkit-service export-secrets

Warning

These two commands will output decrypted data. Do not use them in a production environment and exercise proper care so that plaintext data does not find its way on disk, in a session log, in a scrollback buffer, …

Importing secrets 

Secrets that were exported using radkit-service export-secrets can be imported again using radkit-service import-secrets. Use the --overwrite flag when some secrets already exist in the vault, but have a different value and need to be replaced. The superadmin password will be asked both when exporting and when importing secrets. For the import, please ensure that radkit-service is not running while doing the import, otherwise, the vault’s content might be overwritten again.

# Export secrets first.
radkit-service export-secrets --output decrypted-secrets.json

# Import again.
radkit-service import-secrets --input decrypted-secrets.json

Importing database data 

Database data can be exported as described in the Exporting section, and later on imported by using the following subcommands:

# Import the secrets encryption key for the content of the imported database JSON
radkit-service import-secrets --input imported-secrets.json

# Now import the data
radkit-service import-db --input database_export.json

TLS 

Versions

TLS 1.3 for all connections between RADKit components (Client to Cloud, Service to Cloud, direct RPC from Client to Service, E2EE between Client and Service, Control to Service);
TLS 1.2 or higher for all other connections.

Trusted roots

RADKit ships with its own sets of trusted roots (see Truststores). It does not rely on the trusted roots installed on the system for TLS server certificate validation.

Ciphers

By default, only those TLS ciphers marked as Mandatory or Recommended by Cisco CSDL are enabled on TLS sockets in RADKit. For connections to managed devices, it is also possible to allow ciphers marked as Optional on a per-device basis. PSK ciphers are not supported.

Revocation

All connections to RADKit Cloud and other cloud services are checked for certificate revocation using the Online Certificate Status Protocol (OCSP). OCSP queries are proxied through RADKit Cloud over HTTPS; all OCSP responses are verified and processed by RADKit Client/Service. See Certificate revocation below for details and related settings.

Identity certificates 

Identity certificates are issued to RADKit Service and Client instances during the enrollment process. Those certificates are granted by RADKit Access (a component of RADKit Cloud) and signed by a domain-specific private CA. The current parameters for RADKit Access identity certificates are:

key type/size: RSA 4096-bit
signature: ECDSA with SHA512
revocation: CRL + OCSP

Truststores 

RADKit includes curated root certificate bundles maintained by Cisco’s Security & Trust Organization to verify TLS connections instead of relying on system-provided certificates. There are three different sets of root certificates (also known as truststores) in RADKit:

Domain root certificates: a strictly restricted set of root certificates that are specifically used for TLS connections to RADKit Cloud.
Cisco root certificates: a curated set of root certificates that are used for TLS connections to Cisco-operated services such as CXD.
Public root certificates: a curated set of root certificates that are used for all other TLS connections, such as HTTP or Swagger connections to devices.

Updating the truststores 

Cisco may publish updates to the Cisco and Public root bundles; if you wish to install those updates, follow the instructions below. The Domain root bundle is internal to RADKit and can only be updated by installing a newer RADKit version.

Note

To perform these operations, you will need a recent version of the OpenSSL CLI. The examples below are for macOS or Linux.

Download the updated certificate bundle(s) from the Cisco PKI index:
- for Cisco root certificates, use the Cisco Trusted Core Root Bundle;
- for Public root certificates, use the Cisco Trusted External Root Bundle.
Convert each bundle to a set of PEM certificates:
```
$ openssl cms -purpose any -verify -inform der -in FILE.p7b | openssl pkcs7 -inform der -print_certs -quiet -out FILE.pem
```
where FILE.p7b should be replaced with the actual file name for the bundle that your are converting (normally ios_core.p7b or ios.p7b), and FILE.pem should be replaced with the desired output file name with the .pem extension (normally ios_core.pem or ios.pem).
Move the resulting .pem file(s) to an appropriate location, for example the root of the RADKit data directory:
```
$ mv ios_core.pem ios.pem ~/.radkit/
```

Specify the path to the new bundle in the TOML settings, for example:

[truststore]
cisco_root_store = "~/.radkit/ios_core.pem"
public_root_store = "~/.radkit/ios.pem"

Warning

Do not forget to do this for every RADKit application (Service, Client, Control) through its dedicated TOML settings file. See Settings management and Settings reference for more information.

Certificate revocation 

Certificate revocation checks are carried out after each TLS handshake performed by RADKit. These checks are dictated by the settings within the active SSL/TLS context. Each TLS connection operates within its own SSL/TLS context, as described in Truststores. The revocation status of the certificate chain presented by the peer during the TLS handshake is verified up to the first recognized and trusted Certificate Authority (CA) from the truststore tied to that SSL/TLS context.

Within the RADKit settings, users can adjust:

the revocation method(s) used to check the status of each certificate;
the fail-open/fail-close policy;
the settings of specific revocation methods.

RADKit enables the selection and ordering of methods for checking revocation status, as outlined in ocsp.methods. If issues like network interruptions occur during the verification of the certificate chain, RADKit will switch to the next available method. If a certificate is confirmed as revoked, the TLS connection is immediately cut off, with no switch to another method. If an error unrelated to certificate revocation is encountered and no other methods are left to try, the TLS connection will be terminated. Including the PASS method at the end allows non-revocation related errors to be overlooked as part of a fail-open policy.

Available methods:

STAPLER: Leverages the RADKit Proxy Stapler (a service in RADKit Cloud) to conduct OCSP revocation checks on the user’s behalf. Its main benefit is that it connects to the same host as the Forwarder and Access services, instead of a multitude of remote OCSP endpoints.
DIRECT: Directly carries out OCSP revocation checks by connecting to the OCSP servers listed in the certificates received during the TLS handshake. Uses the HTTP protocol as per the standard.
DIRECT_HTTPS: Functions the same as DIRECT, but forces the use of HTTPS for OCSP queries instead of HTTP.
PASS: Ignores all errors except those related to the revocation of a certificate. This should be added last if a fail-open policy is desired.