# Rotating NIA credentials > How to rotate attestation signing certificates, TLS certificates, and vCenter API credentials for Network Identity Attestor Network Identity Attestor (NIA) manages three types of credentials, each with its own rotation procedure: * [Attestation signing certificate](#rotate-attestation-signing-certificates): Uses the `rotate-signing-credentials` subcommand; requires a manual service restart after rotation. * [TLS certificate](#rotate-tls-certificates): Uses the `rotate-tls-credentials` subcommand; requires a manual service restart after rotation. * [vCenter API credentials](#rotate-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](/user-guide/deploy-install/virtual-envs/set-up-network-identity-attestor). * 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](/user-guide/deploy-install/virtual-envs/reference-network-identity-attestation#attestation-signing-certificate) 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: ```shell 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: ```plaintext 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: ```shell sudo systemctl daemon-reload ``` 6. **Restart the NIA service:** ```shell sudo systemctl restart aembit_netid_attestor.service ``` 7. **Verify the service is healthy:** ```shell curl -k 'https://localhost:443/health' ``` Expected response: ```json {"status":"Healthy","version":"1.29.307"} ``` ### Rollback If you need to revert to the previous signing certificate: 1. **Open the systemd credential file:** ```shell 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:** ```shell 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: > > ```plaintext > 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: > > ```plaintext > 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: ```shell 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: ```shell 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: ```plaintext The new TLS certificate: Fingerprint: Subject: Issuer: Valid from: Valid until: 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..bak` and `tls.key..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: ```shell sudo systemctl restart aembit_netid_attestor.service ``` 5. **Verify the service is healthy:** ```shell 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: ```shell sudo mv /opt/aembit/edge/netid_attestor/tls.crt..bak /opt/aembit/edge/netid_attestor/tls.crt sudo mv /opt/aembit/edge/netid_attestor/tls.key..bak /opt/aembit/edge/netid_attestor/tls.key ``` 2. **Restart the service:** ```shell 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`: ```plaintext vcenter-service-account@vsphere.local:password ``` 2. **Run `rotate-vcenter-credentials`** with the vCenter URL and the path to your new credentials file: ```shell 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: ```plaintext 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: ```shell sudo systemctl daemon-reload ``` 4. **Restart the NIA service:** ```shell sudo systemctl restart aembit_netid_attestor.service ``` 5. **Verify the service is healthy:** ```shell curl -k 'https://localhost:443/health' ``` ### Rollback If you need to revert to the previous vCenter credentials: 1. **Open the systemd credential file:** ```shell 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:** ```shell 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.