Rotating NIA credentials

Network Identity AttestorNetwork Identity Attestor: Network Identity Attestor is an Aembit Edge component deployed in VMware vSphere environments that verifies VM identity through the vCenter API and issues signed attestation documents for workload authentication.Learn more (NIA) manages three types of credentials, each with its own rotation procedure:

• Attestation signing certificate: Uses the rotate-signing-credentials subcommand; requires a manual service restart after rotation.
• TLS certificate: Uses the rotate-tls-credentials subcommand; requires a manual service restart after rotation.
• vCenter API credentials: Uses the rotate-vcenter-credentials subcommand; requires a manual service restart after rotation.

Before you begin

• Network Identity Attestor must be deployed and running.
• You need shell access to the NIA host as root or a user with sudo access.
• Stage new credential files on the NIA host before starting rotation.

Rotate attestation signing certificates

The rotate-signing-credentials subcommand validates the new certificate and key pair, updates the encrypted systemd credential store, and retains the previous credentials as comments for rollback. You must restart the NIA service manually after running the subcommand.

Version requirement

rotate-signing-credentials requires NIA v1.29.307 or later.

Certificate requirements

The new signing certificate must meet all the following requirements. See Network Identity Attestation reference for full details.

• Key type: RSA (ECDSA and Ed25519 aren’t supported)
• Key usage: Must include digitalSignature
• CA constraint: Must not be a Certificate Authority (CA) certificate
• Key match: The certificate and private key must belong to the same key pair

Steps

Register the new certificate in your Trust Provider first

Before rotating, register the new signing certificate’s public key in the Aembit Trust Provider. NIA signs new attestation documents with the new certificate immediately after restart. If the Trust Provider doesn’t trust the new certificate at that point, it rejects newly signed documents.

1. Register the new signing certificate in the Aembit Trust Provider before proceeding.

2. Run rotate-signing-credentials with the paths to your new signing key and certificate files:

   sudo aembit_netid_attestor rotate-signing-credentials \
     --signing-key-path /path/to/new-signing-key.pem \
     --signing-cert-path /path/to/new-signing-cert.pem

   The subcommand displays the new certificate’s metadata:

   The new signing certificate:
   
       Fingerprint: E3:91:F2:2C:38:8D:A6:7C:69:59:A4:C0:AE:A8:3B:FE:CC:A9:D2:89:0C:D2:63:25:1C:AF:77:AC:63:CD:A6:3E
       Subject: C=US, O=Aembit, OU=Edge, CN=Aembit Customer Signing
       Issuer: C=US, O=Aembit, OU=Edge, CN=Aembit Customer CA Intermediate
       Valid from: May 11 20:39:25 2026 +00:00
       Valid until: Sep 25 20:39:25 2053 +00:00
   
   Please verify that the fingerprint number displayed here also appears in the configuration of your Trust Provider.
   
   Do you want to continue? [yes/no]

3. Verify the fingerprint matches the signing certificate you registered in the Trust Provider.

4. Enter yes at the prompt. The subcommand updates /etc/systemd/system/aembit_netid_attestor.service.d/50-credentials.conf and retains the previous credentials as comments.

5. Reload the systemd configuration to pick up the updated drop-in file:

   sudo systemctl daemon-reload

6. Restart the NIA service:

   sudo systemctl restart aembit_netid_attestor.service

7. Verify the service is healthy:

   curl -k 'https://localhost:443/health'

   Expected response:

   {"status":"Healthy","version":"1.29.307"}

Rollback

If you need to revert to the previous signing certificate:

1. Open the systemd credential file:

   sudo nano /etc/systemd/system/aembit_netid_attestor.service.d/50-credentials.conf

2. Remove the new attestation_signing_key and attestation_signing_certificate entries, then uncomment the previous entries with the same names.

3. Reload and restart the service:

   sudo systemctl daemon-reload
   sudo systemctl restart aembit_netid_attestor.service

Common errors

Caution

The subcommand validates the credential pair before making any changes. If validation fails, the credential store is not modified.

Swapped key and certificate files: If you pass the certificate file where the subcommand expects the key:

The private key file must be in the unencrypted PKCS8 format; Expected header: PRIVATE KEY; Observed header: CERTIFICATE

Mismatched key and certificate: If the key and certificate don’t belong to the same key pair:

The signing key and the signing certificate do not match.

Rotate TLS certificates

The rotate-tls-credentials subcommand validates the new certificate and key, replaces the installed tls.crt and tls.key files in place while preserving their original ownership and permissions, and keeps timestamped backups of the previous files for rollback. You must restart the NIA service manually after running the subcommand.

Version requirement

rotate-tls-credentials requires NIA v1.29.439 or later.

Certificate requirements

The subcommand validates the new certificate and key before making any changes, loading them through the same TLS configuration the NIA uses to serve its API. The subcommand catches common problems up front, before it disturbs the running service:

• Private key format: The key must be an unencrypted PKCS#8 PEM file. If your key is in PKCS#1 (traditional RSA) format, convert it first:

  openssl pkey -in your-key.pem -out your-key.pkcs8.pem

• Certificate and key must match: They must belong to the same key pair. The certificate must be a valid PEM file, and may also include intermediate certificates.

• Files must already exist: The subcommand replaces the existing tls.crt and tls.key files. For first-time setup, use the installer instead.

Steps

1. Copy the new TLS certificate and key files to the NIA host.

2. Run rotate-tls-credentials with the paths to your new certificate and key files:

   sudo aembit_netid_attestor rotate-tls-credentials \
     --tls-cert-path /path/to/new-tls-cert.pem \
     --tls-key-path /path/to/new-tls-key.pem

   The subcommand displays the new certificate’s metadata, lists the files it replaces, and prompts you to confirm before changing anything:

   The new TLS certificate:
   
       Fingerprint: <SHA-256 fingerprint>
       Subject: <subject>
       Issuer: <issuer>
       Valid from: <date>
       Valid until: <date>
   
   About to replace the installed TLS files with the contents of the new files:
   
       /opt/aembit/edge/netid_attestor/tls.crt <- /path/to/new-tls-cert.pem
       /opt/aembit/edge/netid_attestor/tls.key <- /path/to/new-tls-key.pem
   
   Do you want to continue? [yes/no]

   The subcommand also warns you before the confirmation prompt if the new certificate has expired, isn’t yet valid, or has chain problems such as a missing intermediate certificate. These warnings don’t stop the rotation, but resolve them before you continue. Otherwise, clients such as the Agent Proxy can reject connections after the restart.

3. Verify the certificate metadata, then enter yes at the prompt. The subcommand replaces tls.crt and tls.key in the NIA install directory (/opt/aembit/edge/netid_attestor/), preserving their original owner, group, and mode, and saves the previous files as timestamped backups (tls.crt.<timestamp>.bak and tls.key.<timestamp>.bak) in the same directory. It then prints the backup paths and the exact commands to apply and to roll back the change.

   Don’t restart if the key replacement fails

   If the subcommand replaces the certificate but then fails to replace the key, the installed tls.crt and tls.key no longer match. The running service keeps working until you restart it, but the restart then fails to load the mismatched pair. When this happens, the subcommand prints a DO NOT restart warning in bold red, along with the exact mv command that restores the previous certificate. Run that command, then re-run rotate-tls-credentials before you restart the service.

4. Restart the NIA service to load the new certificate:

   sudo systemctl restart aembit_netid_attestor.service

5. Verify the service is healthy:

   curl -k 'https://localhost:443/health'

Rollback

If you need to revert to the previous TLS certificate, restore the timestamped backup files the subcommand created. Use the exact mv commands the subcommand printed when it rotated the credentials. They contain the real timestamped backup file names:

1. Restore the previous certificate and key by moving the backup files back into place:

   sudo mv /opt/aembit/edge/netid_attestor/tls.crt.<timestamp>.bak /opt/aembit/edge/netid_attestor/tls.crt
   sudo mv /opt/aembit/edge/netid_attestor/tls.key.<timestamp>.bak /opt/aembit/edge/netid_attestor/tls.key

2. Restart the service:

   sudo systemctl restart aembit_netid_attestor.service

Rotate vCenter API credentials

The rotate-vcenter-credentials subcommand validates the new credentials by logging in to the vCenter API, encrypts them with systemd-creds, updates the encrypted systemd credential store, and retains the previous credentials as comments for rollback. You must restart the NIA service manually after running the subcommand.

Version requirement

rotate-vcenter-credentials requires NIA v1.29.439 or later.

Steps

1. Create a new credentials file on the NIA host. The file must contain a single line in the format username:password:

   vcenter-service-account@vsphere.local:password

2. Run rotate-vcenter-credentials with the vCenter URL and the path to your new credentials file:

   sudo aembit_netid_attestor rotate-vcenter-credentials \
     --vcenter-url https://vcenter.example.com \
     --vcenter-credentials-file /path/to/new-vcenter-credentials

   The subcommand logs in to the vCenter API with the new credentials to confirm they work before changing anything. If the login fails, it reports the error and leaves the credential store unchanged. On success, it reports the result:

   The new vCenter credentials authenticated successfully:
   
       URL:      https://vcenter.example.com/
       Username: vcenter-service-account@vsphere.local
   
   The credentials file has been updated to use the new vCenter credentials. The previous credentials are retained as comments in:
   
       /etc/systemd/system/aembit_netid_attestor.service.d/50-credentials.conf
   
   To make the Aembit Network Identity Attestor use these new credentials, you need to run:
   
       systemctl daemon-reload
       systemctl restart aembit_netid_attestor.service
   
   To roll back to the previous credentials, manually edit the file to remove the 'vcenter_credentials' credential and uncomment the previous credential with the same name. Then re-run the systemctl commands above.

   The subcommand encrypts the new credentials with systemd-creds and retains the previous vcenter_credentials entry as a comment.

3. Reload the systemd configuration to pick up the updated drop-in file:

   sudo systemctl daemon-reload

4. Restart the NIA service:

   sudo systemctl restart aembit_netid_attestor.service

5. Verify the service is healthy:

   curl -k 'https://localhost:443/health'

Rollback

If you need to revert to the previous vCenter credentials:

1. Open the systemd credential file:

   sudo nano /etc/systemd/system/aembit_netid_attestor.service.d/50-credentials.conf

2. Remove the new vcenter_credentials entry, then uncomment the previous vcenter_credentials entry.

3. Reload and restart the service:

   sudo systemctl daemon-reload
   sudo systemctl restart aembit_netid_attestor.service

High availability considerations

You can deploy multiple NIA instances in the same network segment. When you configure the Agent Proxy with AEMBIT_NETWORK_ATTESTOR_URLS, you can rotate credentials on each NIA with no impact to workload attestation.

Agent Proxy version requirement

High-availability NIA rotation requires Agent Proxy v1.31.4871 or later with AEMBIT_NETWORK_ATTESTOR_URLS configured.

Rotate one NIA at a time. The Agent Proxy distributes requests across all configured NIA instances, shuffling on each refresh cycle. When you restart one NIA for credential rotation, the Agent Proxy continues serving attestation requests through the remaining instances. Workloads experience no attestation interruption during a rolling rotation.

When rotating attestation signing certificates across a pool of NIA instances, coordinate Trust Provider updates with the rotation sequence:

• All NIA instances share one signing certificate: Publish the new certificate to the Trust Provider before restarting any NIA. During the rollout window, the Trust Provider should trust both the old and the new certificate. Rotate one NIA at a time.
• Each NIA has its own signing certificate: Publish each replacement certificate to the Trust Provider before restarting that NIA. Rotate one NIA at a time.

For TLS and vCenter credential rotation, rotate one NIA at a time using the subcommand procedure in the relevant preceding section.