Store dynamic keys on the VPN server

[emohandesi]

Is there an existing issue that is already proposing this?

• I have searched the existing issues

Application

Outline Manager

What are you trying to do? What is your use case?

Storing the dynamic keys on the VPN server removes a 3rd party dynamic key storage server, which has the benefit of reducing an additional single point of failure.
For example, when the internet shutdown happened in Iran during the 2025 Iran-Israel war, well-known web addresses such as AWS, Google Docs, etc., were blocked, and users could not get the dynamic keys to connect to the VPN server. Storing the keys on the server removes the dependence on such 3rd party services.

Is your feature request related to a problem? Please describe it.

Described above.

Describe the solution you'd like.

Create an HTTPS server on the VPN server when the install_server.sh is run on it to provide the dynamic keys using that.

• The default port of the HTTPS server can be 8443 since users usually use port 443 for the VPN server. In addition, an option can be given to the user to set the port number.
• Creating an HTTPS server requires a bunch of questions that are asked from the user. The same prompts can be shown to the user to respond. This needs to be streamlined so that the user is asked those questions right after the install_server.sh script is run.
• A new option needs to be added to the install_server.sh script to enable HTTPS server creation. By default, the HTTPS server creation should be turned off.
• In addition to the new option added to install_server.sh script, a question is added that asks the user to see if they want to set up the HTTPS server when install_server.sh script is run.
• When an access key is created on the Outline Manager, a corresponding dynamic key is also created. The path of the key is the password of the static key. The following is a sample dynamic key address. Please note that Dds9Aghq5rxnsu3Yye9jNn is the password of the key which is used both in this URL and the password field inside the dynamic key content, or when the static key is Base64 decoded.

ssconf://sub1.domain.com/Dds9Aghq5rxnsu3Yye9jNn

• When an access key is viewed on the Outline Manager, the dynamic key is also shown in addition to the static key, and you have the option of copying either of them to the clipboard, as shown below:

Describe alternatives you've considered

#2539 can be an alternative to this solution, but support for both of them is needed, as they are complementary to each other.

[fortuna]

See https://github.com/fortuna/OutlineDistribution on how it can be deployed as a web service on the side of the Outline server, without requiring changes.

[zonescape]

@fortuna you are talking strange things. Google Apps Script is an example of 3rd party single point of failure this issue aims to remove.

[fortuna]

This proposal outlines a shift from static to dynamic access keys to improve the user experience and add flexibility. The core idea is to have keys fetch their connection configuration from a server URL instead of containing all the information statically.

Key Management and User Experience 🔑

The server must support both static and dynamic keys for backward compatibility. To avoid confusing users, keys in the Outline Manager should be either one type or another, not both as suggested. We probably want to differentiate them visually, either with different appearance, or by putting them on different blocks.

All new keys should be dynamic by default once this feature is enabled. We should consider including a non-prominent option in the UI for creating legacy static keys if necessary.

The proposed flow for creating a new key is:

1. A user in the Outline Manager clicks to create a new key.
2. This action calls a new API endpoint designed to generate a dynamic key.
3. The output is a single, shareable access key using a new format, likely $ssconf://...$.

The Shadowsocks credentials could either be fixed, or generated at fetch time. No matter which option, we will need to save the credentials while its active, so we need to think about the data modeling.

Technical Implementation

Dynamic Key Hosting

The configuration data for dynamic keys needs to be hosted on a webserver. The decision on whether to host this on the existing API webserver or a separate, dedicated server is yet to be determined (TBD).

TLS Validation

To ensure secure connections, we need a reliable way for the client to validate the server's TLS certificate. Two potential solutions are:

• Adding support for a certificate fingerprint directly into the dynamic key. This needs client support.
• Enabling IP-based TLS certificate provisioning, which would allow the server to automatically obtain a valid certificate for its IP address.

Endpoint Migration

The server must support seamless migration from one endpoint (e.g., IP address and port) to another.

• The server will maintain a list of valid endpoints and listen for connections on all of them simultaneously.
• To migrate, an administrator would add the new endpoint to the list. Once all clients have switched over, the old endpoint can be removed. Note that endpoints for static keys can never be removed without breaking the keys. We should enforce no key is assigned to the endpoint before being able to delete it.
• Supported endpoint protocols include TCP, UDP, and WebSocket streams/packets. The implementation of the WebSocket endpoint can either remain separate or be reverse-proxied through another server (TBD).

A robust API will be required to manage all these functions, including key generation and endpoint management.

Ephemeral Keys ⏳

Looking ahead, this dynamic key infrastructure could be extended to support ephemeral keys. Instead of fetching a static configuration, the client could fetch temporary, single-session credentials upon connecting.

This would provide forward secrecy (a compromised key couldn't be used to decrypt past traffic) and allow the server to automatically prune inactive credentials, strengthening the trial decryption authentication process. This concept is out of scope for the current proposal but represents a valuable future enhancement.

[fortuna]

As you can see. It's not straightforward. I propose an incremental approach, starting by adding support for IP-based TLS certificates in the server. I believe ZeroSSL and soon Let's Encrypt support it.

[emohandesi]

This proposal outlines a shift from static to dynamic access keys to improve the user experience and add flexibility. The core idea is to have keys fetch their connection configuration from a server URL instead of containing all the information statically.

Key Management and User Experience 🔑

The server must support both static and dynamic keys for backward compatibility. To avoid confusing users, keys in the Outline Manager should be either one type or another, not both as suggested. We probably want to differentiate them visually, either with different appearance, or by putting them on different blocks.

All new keys should be dynamic by default once this feature is enabled. We should consider including a non-prominent option in the UI for creating legacy static keys if necessary.

The proposed flow for creating a new key is:

1. A user in the Outline Manager clicks to create a new key.

2. This action calls a new API endpoint designed to generate a dynamic key.

3. The output is a single, shareable access key using a new format, likely $ssconf://...$.

The Shadowsocks credentials could either be fixed, or generated at fetch time. No matter which option, we will need to save the credentials while its active, so we need to think about the data modeling.

Technical Implementation

Dynamic Key Hosting

The configuration data for dynamic keys needs to be hosted on a webserver. The decision on whether to host this on the existing API webserver or a separate, dedicated server is yet to be determined (TBD).

Dynamic keys should be hosted on the outline server to remove an additional single point of failure. That is the whole point of the introduction of this new feature.

TLS Validation

To ensure secure connections, we need a reliable way for the client to validate the server's TLS certificate. Two potential solutions are:

* Adding support for a certificate fingerprint directly into the dynamic key. This needs client support.

* Enabling IP-based TLS certificate provisioning, which would allow the server to automatically obtain a valid certificate for its IP address.

If the user does not want to use a domain name and use the IP of the server, then they have to create a free account on ZeroSSL, which gives them a 90-day certificate, or they have the option to pay and get a 1-year certificate.

• The unpaid certificate expires after 90 days, and the user needs to renew it. What could we do to avoid this and not need a renewal? Manual renewal of the certificate is not feasible.
  • One way to get around it is to allow the Outline client to fetch the IP-based key content even if its certificate is expired, but it compromises security.
  • The paid version of ZeroSSL gives you an API which seems to allow the user to renew the certificate automatically.

Endpoint Migration

The server must support seamless migration from one endpoint (e.g., IP address and port) to another.

* The server will maintain a list of valid endpoints and listen for connections on all of them simultaneously.

* To migrate, an administrator would add the new endpoint to the list. Once all clients have switched over, the old endpoint can be removed. Note that endpoints for static keys can never be removed without breaking the keys. We should enforce no key is assigned to the endpoint before being able to delete it.

* Supported endpoint protocols include TCP, UDP, and WebSocket streams/packets. The implementation of the WebSocket endpoint can either remain separate or be reverse-proxied through another server (TBD).

A robust API will be required to manage all these functions, including key generation and endpoint management.

If the dynamic key is supposed to be stored on the outline server and the server has an IP based certificate, then when the IP of the server changes, a new TLS certificate has to be acquired and stored on it which cannot be done automatically and needs to be done manually by the user, for example, if ZeroSSL is to be used. Therefore, my suggestion is to only use a domain-based TLS certificate when the IP is supposed to change.

• In addition, even when a VPN provider has created a server, he/she might switch its IP, and then, if the default scheme is using dynamic keys, the key content cannot be retrieved because the TLS cannot verify the source, and the following error is seen. This can be part of the API that @fortuna suggested, but it needs to update the TLS certificate files, too.

		SessionConfigFetchFailed: failed to fetch the URL
		Details: {
		"url": " https://SERVER_IP/report.yaml"
		}
		Cause: ERR_INTERNAL_ERROR: Get " https://SERVER_IP/report.yaml": tls: failed to verify certificate: x509: cannot validate certificate for [SERVER_IP](https://20.102.96.157/) because it doesn't contain any IP SANs

The endpoint migration can be either of the following:

• Server IP/domain and port for accepting VPN connections
• Server IP/domain and port for fetching dynamic access keys

When the IP of the server is migrated and dynamic keys are used:

• The dynamic key retrieval will remain the same as long as the port remains the same because it is based on the domain, and as explained earlier, it should not be IP-based.
• The VPN connection will not be affected because the new key content has been fetched successfully.

Ephemeral Keys ⏳

Looking ahead, this dynamic key infrastructure could be extended to support ephemeral keys. Instead of fetching a static configuration, the client could fetch temporary, single-session credentials upon connecting.

This would provide forward secrecy (a compromised key couldn't be used to decrypt past traffic) and allow the server to automatically prune inactive credentials, strengthening the trial decryption authentication process. This concept is out of scope for the current proposal but represents a valuable future enhancement.