docs: add Software Cryptography Provider integration guide#289
Conversation
ivosh
left a comment
ivosh
left a comment
There was a problem hiding this comment.
Good job! Thank you for the write up.
Please address my review comments and then you are good to go.
| | ML-DSA | Lattice-based, NIST FIPS 204 | Sign, Verify | | ||
| | SLH-DSA | Hash-based, NIST FIPS 205 | Sign, Verify | | ||
| | FALCON | 512 and 1024 degrees | Sign, Verify | | ||
| | ML-KEM | Lattice-based, NIST FIPS 203 | Encrypt, Decrypt | |
There was a problem hiding this comment.
ML-KEM is a Key Exchange Mechanism. It supports operations encapsulate and decapsulate (or more colloquially: wrap and unwrap).
|
|
||
| Before you begin, ensure you have: | ||
| - Docker installed and running | ||
| - A PostgreSQL 12+ instance accessible from the connector container |
There was a problem hiding this comment.
If the PostgreSQL database instance is shared with Core, then align with the PostgreSQL version used by Core. Or state explicitly that the lowest supported PostgreSQL version by the SCP connector is 12+ (actually: why not 11+)?
| ```bash | ||
| docker run -d \ | ||
| --name software-cryptography-provider \ | ||
| -p 8080:8080 \ |
There was a problem hiding this comment.
Port 8080 is typically used by Core itself when running in the local development environment. Use the value from https://github.com/OmniTrustILM/development-environment/blob/main/czertainly-compose.yml#L304 (8230).
| | `<db-password>` | Database password | | ||
| | `tagname` | Connector version tag (see [releases](https://github.com/CZERTAINLY/CZERTAINLY-Software-Cryptography-Provider/releases)) | | ||
|
|
||
| Optional environment variables: |
There was a problem hiding this comment.
For optional env. variables, you could point to an existing documentation: https://github.com/OmniTrustILM/software-cryptography-provider
| - Configure key usage policies as required | ||
| - Click **Save** | ||
|
|
||
| ## Create a cryptographic key |
There was a problem hiding this comment.
Because you reference private and public keys later in this section, the title shall mention "key pair":
"Create a cryptographic key pair".
|
|
||
| ## Issue a certificate using a token key | ||
|
|
||
| The cryptographic key created in the token can be used as the signing key during certificate issuance. The platform will automatically generate a CSR using the private key stored in the token. |
There was a problem hiding this comment.
This statement is not entirely correct. Issued certificate is signed by the private key which belongs to the issuing certificate authority, which is typically private to the CA and not exposed.
| # Integration Guide | ||
|
|
||
| :::info | ||
| This integration guide is intended for **development and testing purposes**. The Software Cryptography Provider stores cryptographic keys in software (backed by a PostgreSQL database) and should not be used in production environments. For production use cases, consider hardware security module (HSM) based connectors. |
There was a problem hiding this comment.
You should mention that for this software cp, the private key is encrypted inside the database and never leaves the connector - simulating what a typical HSM would do.
| @@ -0,0 +1,7 @@ | |||
| { | |||
| "label": "Software Cryptography Provider", | |||
| "position": 10, | |||
There was a problem hiding this comment.
Why position 10? I can see only 7 integration guides present currently.
2 participants
Summary
Why this was missing
The platform supports EJBCA, HashiCorp Vault, AD CS, and other connectors with dedicated integration guides. The Software Cryptography Provider — despite being the recommended connector for development and testing — had no setup guide. Users had to rely on concept-level documentation only.
What is covered
Test plan
Inventory → Tokens,Profiles → Token Profiles,Keys)🤖 Generated with Claude Code