5.5. Code Signing Helper Functions¶
PTXdist provides various bash helper functions to be used in code signing providers and code signing consumers.
PTXdist stores URIs and CA keyrings using these helpers in
$(PTXDIST_SYSROOT_HOST)/var/lib/keys/<signing-provider>/<role>/{uri,ca.pem}.
SoftHSM Provider Functions¶
These helpers initialize and import public/private keys and certificates into the SoftHSM.
cs_import_cert_from_der¶
Usage:
cs_import_cert_from_der <role> <DER>
Import certificate from a given DER file for role. To be used with SoftHSM only.
Preconditions:
- the role must have been defined (see cs_define_role)
- SoftHSM must have been initialized (see cs_init_softhsm)
cs_import_cert_from_pem¶
Usage:
cs_import_cert_from_pem <role> <PEM>
Import certificate from a given PEM file for role. To be used with SoftHSM only.
Preconditions:
- the role must have been defined (see cs_define_role)
- SoftHSM must have been initialized (see cs_init_softhsm)
cs_import_pubkey_from_pem¶
Usage:
cs_import_pubkey_from_pem <role> <PEM>
Import public key from a given PEM file for role. To be used with SoftHSM only.
Preconditions:
- the role must have been defined (see cs_define_role)
- SoftHSM must have been initialized (see cs_init_softhsm)
cs_import_privkey_from_pem¶
Usage:
cs_import_privkey_from_pem <role> <PEM>
Import private key from a given PEM file for role. To be used with SoftHSM only.
Preconditions:
- the role must have been defined (see cs_define_role)
- SoftHSM must have been initialized (see cs_init_softhsm)
cs_import_key_from_pem¶
Usage:
cs_import_key_from_pem <role> <PEM>
Import private/public key pair from a given PEM file for role. To be used with SoftHSM only.
Preconditions:
- the role must have been defined (see cs_define_role)
- SoftHSM must have been initialized (see cs_init_softhsm)
Generic Provider Functions¶
These helpers allow to define roles, set PKCS#11 URIs and handle certificate authorities (CAs). HSM as well as SoftHSM code signing providers should use them.
cs_define_role¶
Usage:
cs_define_role <role>
Define new key role.
A default PKCS#11 URI is set implicitly as convenience for SoftHSM use cases.
cs_set_uri¶
Usage:
cs_set_uri <role> <URI>
Set given PKCS#11 URI for role.
Preconditions:
- the role must have been defined (see cs_define_role)
cs_append_ca_from_pem¶
Usage:
cs_append_ca_from_pem <role> <PEM>
Append certificate from a given PEM file to the role’s CA keyring. If no CA keyring exists yet it is created as an empty file before.
Preconditions:
- the role must have been defined (see cs_define_role)
cs_append_ca_from_der¶
Usage:
cs_append_ca_from_der <role> <DER>
Append certificate from a given DER file to the role’s CA keyring. If no CA keyring exists yet it is created as an empty file before.
Preconditions:
- the role must have been defined (see cs_define_role)
cs_append_ca_from_uri¶
Usage:
cs_append_ca_from_uri <role> [<URI>]
Append certificate from a given PKCS#11 URI to the role’s CA keyring. If URI is omitted the already set URI for role is used. If no CA keyring exists yet it is created as an empty file before.
Preconditions:
- the role must have been defined (see cs_define_role)
- when used with SoftHSM, certificates must have been imported before (see cs_import_cert_from_der, cs_import_cert_from_pem)
Consumer Functions¶
Packages that want to sign something or need access to keys/CAs can retrieve PKCS#11 URIs and CA keyrings with these helpers.
cs_get_uri¶
Usage:
cs_get_uri <role>
Get PKCS#11 URI for role.
Preconditions:
- the URI must have been set (see cs_set_uri)
cs_get_ca¶
Usage:
cs_get_ca <role>
Get path to the CA keyring in PEM format for role.
Preconditions:
- a certificate must have been appended to the CA keyring (see cs_append_ca_from_pem, cs_append_ca_from_der, cs_append_ca_from_uri)