Skip to main content

Renewing Authorizations

Like passwords, user keys (and the authorizations they create) should be renewed regularly to limit their exposure to misuse.

Authorizations can be renewed per private key. Corresponding authorized keys are automatically renewed in the process. Key Manager supports the following key-renewal methods:

  • Direct (default) key renewal: Old keys are replaced with new ones as soon as possible.

  • Staged key renewal: New keys are added for authorization, while old keys are preserved (but not used for authorization) for the duration of a stage period. This key-renewal method allows you to revert to using the old keys if something goes wrong with the new keys.

note

Before renewing any keys, we recommend that you familiarize yourself with the features and the limitations related to key renewal. For a list of known key-renewal features and limitations, see the PrivX Key Manager Product Description or the PrivX Key Manager Installation Manual.

note

When renewing private keys with Zero Trust attribute, only the authorized key relating it to PrivX gets renewed. All other authorized keys relating to the private key are left "orphaned". For more information about Zero Trust, see Configuring the Key Manager Zero Trust.

Direct Key Renewal​

In direct key renewal, selected private keys and all corresponding authorized keys are replaced with newly generated keys.

Key renewal does not affect the availability of the target authorizations: since new keys are added before old keys are removed, authorizations remain functional during the renewal process.

The Key Manager process for direct key renewal is the following:

  1. Generate new private keys on the hosts. The private keys are stored in a temporary location (the temporary files are given unique file names on the host). Create new public key objects. Store the old and new private key file locations and old and new public key IDs in the job context.

  2. Add authorized keys for the new private key (or the new public key actually).

  3. Move the private key files on the host to the original private key locations. Update the private key objects with the new private-key locations and public key IDs.

  4. Remove the authorized keys of the original private key (authorized keys matching the original public key).

To perform direct key renewal via the GUI, navigate to the User keys→Private keys page, and perform a Renew action on the target keys. The selected private keys, and their corresponding authorized keys, are renewed after the key renewal jobs have completed.

You can also perform direct key renewal via the command-line client (described in renew-private-keys):

# ssh-mgr-client renew-private-keys

Staged Key Renewal​

In staged key renewal, new keys are added for authorization, while old keys are preserved (but not used for authorization). Both the old and the new keys exist during a defined stage period. During the stage period, you can choose to continue key-renewal by removing the old keys. Alternatively, you can cancel key-renewal to restore the old keys for authorization.

The Key Manager process for staged key renewal is the following:

  1. Initiate key-renewal to add new keys for authorization.

  2. During the stage period, observe that authorizations can be established successfully with the new keys. It may also be good to check the key-activity logs pertaining to the old keys, to ensure that the old keys are no longer in use.

  3. Any time during the stage period, you can perform one of the following actions to complete the staged key renewal:

    • Continue key renewal to remove the old keys.

    • Cancel key renewal to restore the old keys for authorization, and to remove the new keys.

    If you let the stage period end without performing one of the available actions, Key Manager automatically completes key renewal by removing the old keys.

Staged key renewal is performed via the command-line client:

  1. Use the renew-private-keys command while specifying a stage_period. For example, to renew the private key with the private-key ID 27, and with a 1-month stage period:

    $ ssh-mgr-client renew-private-keys -i 27 -d stage_period=1m

    Key Manager creates jobs to add new keys for authorization. A staged key-renewal job adds the new keys for authorization. After that, the job remains in the pending state until the stage period ends, or until you manually resume renewal.

    You will need the ID of the key-renewal job if you want to manually continue or cancel the key renewal at a later time. The job ID is indicated in the output of the previous command:

    STARTED renew private_key #7: Jobs 484
    STARTED renew-private-key: Job 484
    tip

    Specify target keys using a fingerprint filter to ensure that all copies of the private key are renewed. For example:

    $ ssh-mgr-client renew-private-keys -d stage_period=2m -F \
    "fingerprint_openssh=0f:26:56:d9:ec:21:45:e2:43:06:67:ab:01:6b:58:ec"

  2. Optional: During the stage period, you can manually continue or cancel the pending key-renewal job.

    If the renewal job is continued or canceled before the new keys are generated, the job fails to resume correctly. The job progress can be checked by reviewing its job state. The job state can be displayed with a command like the following:

    $ ssh-mgr-client show-job -i 484 -C state

    If the command returns waiting_stage_check, then it is safe to resume with either of the following actions:

    • Continue the job to remove the old keys. This action can be used, for example, when you are certain that authorizations function correctly using the new keys, and that the old keys are no longer used:

      $ ssh-mgr-client continue-jobs -i 484

    • Cancel the job to restore the old keys. This action can be used if you determine that the new keys do not function correctly. Canceling the job marks it as Failed:

      $ ssh-mgr-client cancel-jobs -i 484

For more instructions about using the renew-private-keys command, see renew-private-keys.

note

During the stage period of staged key renewal, both the new and the old keys are marked as pending operation, which prevents other key-management actions from being run on these keys.

Error Handling in Key Renewals​

In direct key renewal, any failures in key actions will abort the operation, and attempt to rollback any key actions already performed as a part of the renewal operation.

To perform key renewals while allowing some of the key actions to fail, you can use staged key renewal. In this case the renewal operation will stop at the staging point before removing any of the old keys, and allow the operator to decide whether to continue the operation in light of the failures, or to abort it. Note, this only applies to failures in the authorized key actions. Failures to initiate authorized key actions will be logged in the top-level renewal job's log. This can occur, for example, if the hosts where the keys are, are not in managed state. Failures to complete authorized key actions will be visible as failed subjobs of the top level renewal job. This can occur due to many causes, for example, if the host is not reachable, or if the user owning the key has been deleted.