provision command group¶

The provision command group bootstraps tenant services in {{ product_name }}. Its dss subcommand provisions one of a tenant's DSS (eIDAS) signing service instances in one step. A tenant may run several DSS instances (for example an EU and a CH signer), each identified by a --name that is unique per tenant and defaults to dss. The number of instances a tenant may hold is capped by the dss.quota license (assigned separately with tenant license assign; a tenant with no dss.quota claim may hold one instance). Provisioning assigns the dss feature license (idempotent — shared across all the tenant's instances), records the per-instance key-profile quota and the HSM user-partition the tenant will generate keys on, creates the DSS bootstrap record, and returns a one-time bootstrap shared secret the dss-proxy presents on first contact.

Its hsm subcommand group manages the global DSS HSM partition registry — the catalog of deployed Securosys Primus HSM user-partitions the DSS signer uses (Primus is the only supported HSM here because it provides SKA, authorization keys linked to signing keys). A partition holds SKA keys shared by many tenants. provision dss --hsm-partition-user must reference a partition that already exists in this registry.

Commands in this group¶

Typical workflow¶

1. Register the deployed Securosys Primus partition once with provision hsm create (find existing ones with provision hsm list).
2. Find the tenant UUID with tenant search.
3. If the tenant needs more than one DSS instance, entitle the instance cap first with tenant license assign -n dss.quota -V <n> (a tenant with no dss.quota claim may hold one instance).
4. Provision each DSS instance with provision dss, giving it a --name (unique per tenant; defaults to dss), a per-instance key-profile quota, and the registered HSM user-partition.
5. Record the one-time bootstrap secret and the module_uuid from each reply and hand them to that instance's dss-proxy deployment.
6. Confirm the entitlements with tenant license list.
7. If an instance's secret is ever lost, regenerate it with provision dss reset-key --module-uuid <module_uuid>.

Group help¶

bin/admin.sh provision --help

provision dss¶

Provision one of a tenant's DSS (eIDAS) signing service instances. The command assigns the dss feature license (idempotent across the tenant's instances), enforces the tenant's dss.quota instance cap, and creates a named DSS service-module instance (the anchor to which JWT signing keys are later bound at onboarding) plus the t_dss bootstrap record — storing a hash of a server-generated one-time secret, the per-instance key-profile quota, and the HSM user-partition — linked to that instance. It returns the plaintext secret once, along with the module instance UUID (module_uuid) you use to reference this instance later. The active-signing-keys table starts empty; the dss-proxy registers keys as it generates them.

Syntax¶

bin/admin.sh provision dss [options]

Required options¶

Optional options¶

Example¶

# second instance for a tenant already entitled to dss.quota >= 2
bin/admin.sh provision dss \
  -u 6f1d2c3b-4a5e-6789-0abc-def012345678 \
  -n dss-eu \
  -k 3 \
  -P crypto-user-1 \
  -f json

provision dss reset-key¶

Regenerate the bootstrap shared secret of one specific DSS instance, selected by its --module-uuid (the module_uuid returned by provision dss). Because a tenant may run several DSS instances, the module uuid identifies which one to reset — resetting is not tenant-wide. A fresh secret is generated, its hash replaces that instance's stored one, and the used date is cleared so that instance's dss-proxy can onboard again. The reply returns the new secret once, together with the instance identity (tenant, module and dss uuids, the instance name and its HSM user-partition) so you can reconfigure the right proxy.

Syntax¶

bin/admin.sh provision dss reset-key [options]

Required options¶

Optional options¶

Example¶

bin/admin.sh provision dss reset-key \
  -u 6f1d2c3b-4a5e-6789-0abc-def012345678 \
  -m mod-019f1c... \
  -f json

provision hsm create¶

Register a deployed Securosys Primus HSM user-partition in the global DSS partition registry. The --partition-user is the unique SKA crypto user a tenant DSS later references via provision dss --hsm-partition-user. You must supply the partition's Primus host(s) with -H/--host (at least one, repeatable) — they are the endpoints the signer connects to. Proxy credentials, the validation cron and the HSM integrity key are optional; when the cron is omitted the server applies its default schedule.

Syntax¶

bin/admin.sh provision hsm create [options]

Required options¶

Optional options¶

Example¶

bin/admin.sh provision hsm create \
  -N "primus-zrh-1" \
  -P crypto-user-1 \
  --partition-pin "nP3UL-gRQHh-DwxUY-8GKxp-yqdrZ" \
  -H primus-a.example.internal:2300 \
  -H primus-b.example.internal:2300:50 \
  --integrity-key dss-integrity \
  --integrity-algorithm SHA256withECDSA \
  -f json

provision hsm update¶

Update a registered HSM partition, selected by its immutable --partition-user. Only the fields you supply change; the --partition-user itself cannot be changed. Hosts and the integrity key are not updatable here — re-register (or restore) the partition to change those.

Syntax¶

bin/admin.sh provision hsm update [options]

Required options¶

Optional options¶

Example¶

bin/admin.sh provision hsm update \
  -P crypto-user-1 \
  -c "0 0/30 * ? * *" \
  -f json

provision hsm delete¶

Delete a registered HSM partition by --partition-user. The shared registry is only affected by this command — deleting a tenant DSS leaves its partition in place. A partition that is still referenced by any tenant DSS cannot be deleted.

Syntax¶

bin/admin.sh provision hsm delete [options]

Required options¶

Optional options¶

Example¶

bin/admin.sh provision hsm delete -P crypto-user-1 -f json

provision hsm list¶

Search the DSS HSM partition registry. Supports a search term (-q), search mode (-m), and pagination (-n/-s) via the shared query options. The secret PIN fields are never returned by the search.

Syntax¶

bin/admin.sh provision hsm list [options]

Optional options¶

Example¶

bin/admin.sh provision hsm list -q primus -f json

provision hsm backup¶

Back up a single HSM partition to a binary protobuf (.pb) file (or Base64 to the console).

Syntax¶

bin/admin.sh provision hsm backup [options]

Required options¶

Example¶

bin/admin.sh provision hsm backup -P crypto-user-1 -o crypto-user-1.pb

provision hsm restore¶

Restore an HSM partition from a .pb backup. The partition is upserted by partition_user: a new partition is created, or an existing one is overwritten with the backup's values (including the secret PINs and the hosts in the blob).

Syntax¶

bin/admin.sh provision hsm restore [options]

Required options¶

Example¶

bin/admin.sh provision hsm restore -i crypto-user-1.pb -f json

Deployment: HSM reachability¶

Because provision hsm create, update (when the PIN changes) and restore all verify the PIN with a real login, the admin service must be able to reach the Securosys Primus partition and must be configured with an hsm pool-tuning block, for example:

hsm {
  threadsPerKey = 2
  queueCapacityPerKey = 128
  daemonThreads = true
  prestartCoreThreads = false
  threadNamePrefix = "admin-hsm-"
}

If the hsm block is absent, these commands fail closed with a configuration error rather than storing an unverified PIN. The block tunes the shared partition worker pool only; the partition's connection details (user, PIN, proxy and hosts) come from the command options, not configuration.

Standard CLI options, including the global -p/--profile selector, are documented in Global options.

FAQ¶

Related¶

• Admin CLI overview
• Command map
• tenant license command group