Certificate management

Create, configure, validate, and rotate the SEB configuration-encryption identity — the certificate that decides which devices can open a configuration.

By default, deployments encrypt generated .seb files to a configured public X.509 certificate. The service holds only the public certificate; the matching private identity is installed only on approved exam devices. This is one of the two independent protections — encryption stops an unapproved device from opening a configuration at all, while Config Key proof stops an access code from being released against stale settings.

Compatibility mode is a deliberate trade-off

An instance may set SEB_CONFIG_ENCRYPTION_ENABLED=false when it cannot distribute a private identity. Config Key proof remains required, but the downloaded file is not device-specific and is plaintext unless an instructor sets a start password. Approve and document that lower-assurance posture; never introduce it as a shortcut during a certificate incident.

Trust model

Component	Holds	Must not hold
Application runtime	Public certificate (or permitted local public-key fallback)	Private key, `.p12`, passphrase
Secret manager	Public certificate PEM	Private key or `.p12`
Device-management system / vault	Private identity + its protection material	Broad user or runtime access
Approved SEB client	Non-extractable, SEB-scoped private identity	An exportable identity available to a student account or unrelated app

Generate an identity

The repository generator writes private artifacts under the git-ignored .local/ directory. Put the passphrase in a protected file — never in a command argument or environment variable.

umask 077
mkdir -p .local
openssl rand -base64 48 > .local/seb-cert-p12-password

SEB_CERT_NAME=seb-config-encryption \
SEB_CERT_SUBJECT="/CN=Safe Online Exam Configuration Encryption/O=Organization" \
bash scripts/generate-seb-config-cert.sh \
  .local/seb-certs \
  .local/seb-cert-p12-password

It produces:

seb-config-encryption.crt.pem

seb-config-encryption.cer

seb-config-encryption.key.pem

seb-config-encryption.p12

Move the private artifacts immediately

Move the private PEM, .p12, and passphrase into approved restricted storage, then remove workstation copies once the vault upload and client deployment are verified. Never commit, log, email, attach, or pass these through command arguments, tickets, or chat.

Configure the service

Store the public certificate in Secret Manager and inject it as SEB_CONFIG_ENCRYPTION_CERT_PEM. The Cloud Run release-bundle installer creates the instance-prefixed Secret Manager secret and pins the deployed revision to its numbered version; follow the Google Cloud guide rather than reusing a shared development/production secret name.

The service validates the certificate at startup and at every download. When encryption is enabled in a hardened runtime, a valid public X.509 certificate is required and a public-key-only fallback is not sufficient. In local development, a public-key fallback remains available for configuration work.

The configured certificate is served for verification at:

${TOOL_URL}/seb/config-encryption-certificate.pem
${TOOL_URL}/seb/config-encryption-certificate.cer

These never serve private material. Their x-seb-public-key-hash response header is what you compare against the client identity during rollout checks. In explicit plaintext compatibility mode, neither endpoint is served.

Client deployment (summary)

Prefer your device-management platform's native certificate/profile mechanism. The profile should install the PKCS#12 identity into the intended scope, mark the private key non-extractable where supported, restrict it to the approved SEB application, prevent removal by an ordinary student account, and be scoped to a test group first.

For a managed macOS fleet whose MDM cannot install the needed identity in the user keychain, the release bundle includes a controlled staged-file fallback. The MDM must stage the .p12 and its passphrase only in root-owned, mode-0600 files, then run install-seb-config-identity-user-keychain.sh as root after the intended user has logged in. The helper verifies the identity fingerprint and private-key match, validates the approved SEB application, and imports through that user's GUI security session without exposing the private identity to the student account or passing the passphrase to security import.

Never put the identity, passphrase, or login-keychain password in an MDM script parameter. If a user session or keychain is not ready, the helper returns a retryable status instead of weakening the installation. A signed in-house package is the preferred Jamf School fallback when its native payload cannot reach the required user keychain; build and scope it from a secured administrator workflow only. It is a compatibility path for managed standard-user Macs, not a substitute for hardware-backed device identity. Full platform controls are in Device deployment.

Pre-assessment validation when encryption is enabled

Before a rollout window:

Confirm the active revision has encryption enabled and the expected certificate secret version or mounted file.

Request the public certificate endpoint and record its x-seb-public-key-hash.

Confirm the client profile reports installed on every intended test device.

On an approved test device, run the setup check and open the encrypted setup configuration.

Confirm Config Key proof succeeds after SEB starts.

Confirm a device without the identity cannot open the encrypted configuration.

Confirm an unrelated app and an ordinary student account cannot export or use the private key.

Confirm the certificate remains valid for the assessment and recovery window.

Rotation

Perform routine rotation outside active assessments:

Generate and secure a replacement identity.

Create the matching non-extractable, SEB-restricted client profile.

Deploy it to a test group and pass the setup check.

Deploy it to all intended clients, with a planned overlap period if needed.

Add the replacement public certificate to the service secret and deploy a new revision.

Verify the active public-key hash and download fresh configurations.

Remove the old profile and revoke/delete the old private material after the overlap window.

Any relevant SEB settings change invalidates old configurations — tell students to download a fresh .seb file after rotation. If the private identity is suspected compromised, pause the affected workflow, rotate, deploy the replacement public certificate, invalidate affected settings through the normal flow, and require fresh configurations. Do not switch to plaintext compatibility mode reactively during an incident; treat it as a separately reviewed deployment decision.

Troubleshooting

Symptom	Check
SEB cannot open a downloaded configuration	Confirm a fresh download, the profile is installed in the correct scope, and the public-key hash matches the active service certificate.
A working device fails after rotation	Confirm the new profile arrived before the service switched certificates, then download a fresh configuration.
Service fails startup or download creation	Confirm encryption is enabled, the certificate is a currently valid X.509, and the secret value retained its PEM line breaks.
A private key is exportable or usable by unrelated apps	Stop the rollout and correct the device-management profile. Do not weaken application restrictions.

More symptoms are in Troubleshooting → SEB configuration.