Preshared Keys

You can optionally enhance the security of a WireGuard connection between two hosts by configuring it to use a secret, randomly-generated preshared key. This secret should be 256 bits (32 bytes) long, and be supplied as a base64-encoded string (when base64 encoded, it will appear as 44 alphanumeric characters, ending with an equals sign). It should not be reused for a connection between any other two hosts.

On Linux, you can generate a random preshared key with the following WireGuard command:

$ wg genpsk
/UwcSPg38hW/D9Y3tcS1FOV0K1wuURMbS0sesJEP5ak=

Copy and paste the output of this command into the Preshared Key field in Pro Custodibus (or as the “PresharedKey” setting in a wg-quick-style configuration file).

If you configure one side of a WireGuard connection with a preshared key, you must configure the other side of the connection with the exact same key.

Why?

The connection between two WireGuard peers is secured by the Noise protocol, using ChaCha20-Poly1305 encryption with an ephemeral symmetric key derived via ECDH from the X25519 public-key pairs of the two peers. While there are no known practical attacks against this, eventually it might become practical for quantum computers to “crack” this encryption, by calculating the private key of one peer from its paired public key.

To hedge against this possibility (or the possibility that one of the private keys might be stolen by conventional means), you can configure the connection between two peers with a secret preshared key. WireGuard will mix this key into the derivation process for its ephemeral encryption keys.

So when using a preshared key, for an attacker to be able to decrypt the data exchanged between the two peers, she would not only have to steal or crack the private key used by one of the peers, she would also have to steal the preshared key (a randomly-generated preshared key will not be “crackable” by quantum computers, nor by any other means).

Corresponding Endpoints

In order for two hosts to communicate over WireGuard, they must be configured with corresponding endpoints. Each host must have an interface configured with a unique public-key pair, representing the interface’s own peer identity; and each interface must have an endpoint configured with the other interface’s peer identity (ie the other interface’s public key).

From the perspective of the first host, its own interface is the local side of the connection, and this interface’s public-key pair is its local peer identity. The second host’s public-key pair is the remote peer identity, and that peer is connected to the first host’s interface as a remote endpoint of that interface.

The perspective of the second host is the mirror image. To the second host, its own local interface, using its own local peer identity, is the local side of the connection; and the endpoint of its local interface configured with the first host’s peer identity represents the remote side of the connection.

So the first host is configured with Peer 1 for its local interface, with a remote endpoint to Peer 2. The second host is configured with Peer 2 for its local interface, with a remote endpoint to Peer 1. These two endpoints represent the two sides of the same connection — each endpoint corresponds to the other. The first endpoint is the remote endpoint from the perspective of the first host; and the second endpoint is the remote endpoint from the perspective of the second host.

Two hosts connected via corresponding endpoints

These two corresponding endpoints must either be configured with the exact same preshared key, or they must be configured with no preshared key at all.

SHA-256 Hash

Because a preshared key is useful only if it remains secret, the Pro Custodibus UI will not display the key directly (except on the page that allows you to change the key, or on the page that allows you to download the configuration settings for an interface). Instead it will display the SHA-256 hash of the preshared key (which reveals nothing about the content of the key, yet identifies it pseudo-uniquely).

The hash that Pro Custodibus displays is calculated from the raw, unencoded preshared key itself — not the base64-encoded version of the key (although the hash itself, once calculated, is displayed with base64 encoding). On Linux, you can calculate the SHA-256 hash of a base64-encoded preshared key the same way as Pro Custodibus, with the following command:

$ echo /UwcSPg38hW/D9Y3tcS1FOV0K1wuURMbS0sesJEP5ak= | base64 -d | sha256sum | cut -d' ' -f1 | xxd -r -p | base64
zsi4Ky9Kp0JVWkdDozwfDBQUZoRJUpPRVEj+7cuxxAg=

Key Synchronization

If the two corresponding endpoints of a WireGuard connection are using different preshared keys, they will not be able to communicate. The preshared key of one endpoint must be synchronized to match the other endpoint in order to re-establish communication.

To synchronize the preshared key of one endpoint to match its corresponding endpoint, follow these steps:

  1. Click the Hosts link in the app header.

  2. Find the host containing the endpoint’s interface in the list, and click the host’s name to view the host’s main status page.

  3. Find the endpoint in the Endpoints panel, and click its name to view the endpoint’s main status page.

  4. Scroll down to the Preshared Key panel, and click the “circle-on-shield” (Synchronize Key) icon on the right side of panel to modify the endpoint’s preshared key.

Pro Custodibus can synchronize the preshared keys of corresponding endpoints only if both endpoints are on monitored hosts. If one endpoint is not on a monitored host, or if both endpoints are already using the same preshared key (or if a change to their preshared key is pending), the “Synchronize Key” icon will be disabled.

When you click the “Synchronize Key” icon, Pro Custodibus will queue a change for the endpoint to update its preshared key to match the value as its corresponding endpoint. The next time the Pro Custodibus agent on the endpoint’s host pings the Pro Custodibus servers, the agent will receive the information about the endpoint update, and execute it.

Key Rotation

To rotate the preshared key used by an endpoint, follow these steps:

  1. Click the Hosts link in the app header.

  2. Find the host containing the endpoint’s interface in the list, and click the host’s name to view the host’s main status page.

  3. Find the endpoint in the Endpoints panel, and click its name to view the endpoint’s main status page.

  4. Scroll down to the Preshared Key panel, and click the “key-on-shield” (Manage Key) icon on the right side of panel to modify the endpoint’s preshared key.

Preshared Key

The preshared key currently used by the endpoint will be displayed in the Preshared Key field. It will be blank if no preshared key is used; or will display “[Key Not Stored]” if a preshared key is used but not stored with Pro Custodibus.

Click the Regenerate button next to the field to generate a new random preshared key. Alternately, you can generate a new preshared key with the following WireGuard command:

$ wg genpsk
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=

(But do not use the above example key, as it is all zeros.) If you generate (or manually enter) a new key, the SHA-256 Hash for the new key will be displayed below it.

To stop using a preshared key with the endpoint, delete the content of the Preshared Key field.

Update corresponding endpoint

If the corresponding endpoint to the endpoint you’re modifying is registered with Pro Custodibus, you will be able to select the Update corresponding endpoint checkbox. If checked, Pro Custodibus will also queue a change to update the preshared key for the corresponding endpoint to match this endpoint’s preshared key.

Preshared Key of Corresponding Endpoint

If the corresponding endpoint to the endpoint you’re modifying is registered with Pro Custodibus, Pro Custodibus will display the SHA-256 Hash of the preshared key currently used by the corresponding endpoint (or if the corresponding endpoint is not using a preshared key, it will be blank).

If you enter a new key in the Preshared Key field, make sure the SHA-256 hash displayed for that key matches the SHA-256 hash of its corresponding endpoint. If it does not match, the two endpoints will not be able to connect.

If the SHA-256 hash of the preshared key of the corresponding endpoint does not match the SHA-256 hash of the key in the Preshared Key field, select the Update corresponding endpoint checkbox. Pro Custodibus will update the corresponding endpoint to make it match.

Form Submit

Click the Update button to submit the form and queue the changes for the endpoint (and optionally the corresponding endpoint, as well).

The next time the Pro Custodibus agent on the endpoint’s host pings the Pro Custodibus servers, the agent will receive the information about the endpoint update, and execute it.

The connection between this endpoint and its corresponding endpoint will be interrupted until the preshared key has been updated on both sides of the connection. On monitored hosts, this should take less than two minutes.

If one side of the connection is not to a monitored host, you will have to update that side manually with the new preshared key.

Bulk Rotation

To rotate all the preshared keys used by all the endpoints of a peer, follow these steps:

  1. Navigate to the main page for the peer.

  2. Click the “key-on-shield” icon on the right side of the Peer panel.

  3. Click the “Select All” checkbox at the top of the checkboxes column in the Peer Connections panel (or click individual checkboxes for connections from the list).

  4. Click the Rotate Preshared Keys button at the bottom of the panel.

  5. Click the OK button in the “Rotate Preshared Keys” confirmation dialog.

A progress bar will be displayed at the bottom of the “Rotate Preshared Keys” dialog while a new preshared key is generated for each connection, and changes queued to update the connections' endpoints. When all the changes have been queued, the page will reload to list the queued changes.

Each connection will be interrupted until the key rotation process completes on both sides of the connection. On monitored hosts, this should take less than two minutes.

If one side of the connection is not to a monitored host, you will have to update that side manually with the new preshared key. See the Manual Rotation section for details.

Automatic Rotation

Pro Custodibus can be configured to automatically rotate preshared keys at pre-defined intervals via key-rotation policies.

Each connection between two peers may have at most one key-rotation policy applied to it. Peers from either end of a connection may be assigned to a policy. If more than one policy could be applied to a connection, the policy with the lowest ordinal is applied (and among policies with the same ordinal, the policy that was created first is applied).

Add Policy

To create a key-rotation policy, follow these steps:

  1. Click the Admin link in the app header.

  2. Click the Key Rotation link in the Administration panel.

  3. Click the “plus” icon on the right side of the Policies panel.

Description

Optionally enter a description for the policy, like “Prod Infra-to-Infra”, in the Description field. This description will be displayed alongside the policy in various places in the UI.

Policy Ordinal

Enter a ordinal for the policy, like “101”, in the Policy Ordinal field. Policies with lower ordinal are applied in preference to policies with a higher ordinal. The minimum ordinal is 1.

Rotation Interval

Enter the interval at which to rotate preshared keys, like “0 days, 1 hours, 30 minutes” (meaning rotate every 1.5 hours), in the Rotation Interval field. The minimum rotation interval is 5 minutes.

An interval value of “0 days, 0 hours, 0 minutes” means that the policy will not rotate keys. This can be useful to override key-rotation policies with higher ordinals, in the case of a few specific peers to which you do not want to apply key rotation.

MFA

To use this policy to enforce WireGuard multi-factor authentication (MFA), select the Rotate server-side only checkbox.

MFA policies rotate preshared keys only on the “server” side of each connection. On the “client” side of the connection, a human user has to log into Pro Custodibus to synchronize the key.

Unmonitored

To apply this policy to connections even when one side of the connection is not to a monitored host, select the Rotate even when one side is unmonitored checkbox.

If one side of the connection is not to a monitored host, you will have to update that side manually with the new preshared key whenever the other side is rotated automatically. See the Manual Rotation section for details.

Form Submit

Click the Add button to submit the form and create the policy.

Add Peer

To add a peer to a key-rotation policy, first navigate to the page for key-rotation policy (if you just created the policy, you will be viewing this page).

To add a peer to an MFA policy, first decide whether the peer you will add will represent the “server” side of connections, or the “client” side. If the peer will represent the server side, click the “plus” icon on the right side of the Server Peers panel; if the peer will represent the client side, click the “plus” icon on the right side of the Client Peers panel.

Otherwise, for a non-MFA policy, click the “plus” icon on the right side of the Peers panel.

Peer

Select the peer to add from the Peer field. You can type part of a name in the Peer field to filter the displayed list of peers from which to choose. Use the up and down arrow keys to highlight a peer from the list, and use the tab or enter key to select the highlighted peer.

Form Submit

Click the Add button to submit the form and add the selected peer.

Manual Rotation

When you use the Bulk Rotation tool to rotate the preshared key of a connection between a monitored host and an unmonitored host, you will have to manually update the rotated key on the unmonitored host.

Such hosts will have a blank (or old) “Last Ping” value in the Peer Connections panel (and the host, interface, and endpoint columns also may be blank). For each such connection, follow these steps:

  1. Click the link to the endpoint used by the monitored host (it will be named with the peer used by the unmonitored host).

  2. If the endpoint’s State is listed as “Update Pending”, wait until all its pending updates have been applied (this should take less than two minutes).

  3. Scroll down to the Preshared Key panel, and click the “key-on-shield” icon on the right side of panel to view the endpoint’s newly-rotated preshared key.

  4. Copy the value of the Preshared Key field and transfer it to the unmonitored host (for example, SSH into the unmonitored host, or send a secure message to a colleague who has physical access to the unmonitored host).

  5. On the unmonitored host, open the WireGuard configuration for the host, and paste the transferred preshared key into the PresharedKey setting for the [Peer] entry that represents the endpoint to the monitored host.

  6. Save the WireGuard configuration change, and restart WireGuard on the unmonitored host.

To perform steps 4-6 above, you will need to either have physical access to the unmonitored host, or have a remote connection to the unmonitored host that isn’t itself tunneled through a WireGuard connection which you’re in the process of updating (for example, an SSH connection to the unmonitored host that doesn’t go through WireGuard, or an RDP connection through WireGuard to the unmonitored host from a host other than the monitored host, etc).