Skip to content

Commit 0a187ec

Browse files
RoRoJRoRoJ
committed
fix(s2svpn): add more doc
1 parent 02e78bb commit 0a187ec

File tree

3 files changed

+85
-25
lines changed

3 files changed

+85
-25
lines changed

‎pages/site-to-site-vpn/index.mdx‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -31,18 +31,18 @@ meta:
3131
url="/site-to-site-vpn/reference-content/understanding-s2svpn/"
3232
/>
3333
<SummaryCard
34-
title="Concepts"
34+
title="Site-to-Site VPN statuses"
3535
icon="info"
36-
description="Core concepts that give you a better understanding of Site-to-Site VPN."
37-
label="View Concepts"
38-
url="/site-to-site-vpn/concepts/"
36+
description="Understand VPN statuses."
37+
label="View Doc"
38+
url="/site-to-site-vpn/reference-content/statuses/"
3939
/>
4040
<SummaryCard
41-
title="TODO"
42-
icon="book-open-outline"
43-
description="TODO"
44-
label="TODO"
45-
url="TODO"
41+
title="Security proposals"
42+
icon="info"
43+
description="Encryption and authentication explained"
44+
label="View Doc"
45+
url="/site-to-site-vpn/reference-content/security-proposals/"
4646
/>
4747
</Grid>
4848

‎pages/site-to-site-vpn/reference-content/index.mdx‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
---
22
meta:
3-
title: InterLink - Additional content
4-
description: InterLink additional content
3+
title: Site-to-Site VPN - Additional content
4+
description: Site-to-Site VPN additional content
55
content:
6-
h1: InterLink - Additional content
7-
paragraph: InterLink additional content
6+
h1: Site-to-Site VPN - Additional content
7+
paragraph: Site-to-Site VPN additional content
88
---

‎pages/site-to-site-vpn/reference-content/security-proposals.mdx‎

Lines changed: 72 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -18,21 +18,81 @@ dates:
1818
Site-to-Site VPN is currently in Private Beta, and available to selected testers only via the Scaleway API. [Request an invitation](https://www.scaleway.com/en/betas/#site-to-site-vpn).
1919
</Message>
2020

21-
When creating a VPN [connection](/site-to-site-vpn/reference-content/understanding-s2svpn/#connection), you must define a security proposal (aka IPSec proposal). The security proposal defines the encryption and authentication methods used to secure the IPSec VPN tunnel.
21+
When creating a VPN [connection](/site-to-site-vpn/reference-content/understanding-s2svpn/#connection), you must define a **security proposal** (aka IPSec proposal). The security proposal defines the encryption and authentication methods used to secure the IPSec VPN tunnel.
22+
23+
A security proposal is made up of several parts, each with definable algorithms or settings. You should define these bearing in mind the use case of your Site-to-Site VPN, balancing **security**, **performance** and **compatibility**.
24+
25+
It is important to find the optimal trade-off between these elements: the strongest possible security may be overkill for your use-case, and slow down performance to unacceptable levels. Some algorithms are outdated and not optimal for modern VPNs, but may be the only compatible option for legacy VPNs.
26+
27+
In this document, we explain the different elements of a security protocol, and describe the different algorithms and security options available with Scaleway Site-to-Site VPN, giving advice to help you choose the best options for your use-case.
28+
29+
## Defining a security proposal
2230

2331
There are two parts to a security proposal:
2432

2533
- **IKEv2** (Internet Key Exchange): Establishes a secure connection between the VPN gateway and the customer gateway
2634
- **ESP** (Encapsulating Security Payload): Encrypts and authenticates the payload of the IP data packets traveling through the tunnel.
2735

28-
When defining your Site-to-Site VPN security proposal, you need to define the options to be used for the following elements:
29-
30-
| Protocol | Element | Description | Options |
31-
|-----------------|-----------------|----------------------------------------------------|--------------------|
32-
| **IKEv2** | **Encryption** | Algorithm to encrypt IKE negotiation messages | `aes` (AEAD and non-AEAD) |
33-
| **IKEv2** | **Integrity** | HMAC-based algorithm to verify IKE negotiation messages have not been tampered with | `sha` |
34-
| **IKEv2** | **Key Exchange Method** | DH group to define strength of key exchange | `ecp`, `curve`, `modp` |
35-
| **ESP** | **Encryption** | Algorithm to encrypt traffic's data payloads | `aes` (AEAD and non-AEAD) |
36-
| **ESP** | **Integrity** | Only set an HMAC-based algorithm to verify integrity of data payloads if **not** using an AEAD algorithm for ESP encryption. Otherwise, integrity is built-in, and this option does not need to be set. | `sha` |
37-
38-
?? Pseudorandom function ??
36+
When defining your Site-to-Site VPN security proposal, you must define the algorithms/ options to be used for IKEv2 and ESP as described below:
37+
38+
| Protocol | Element | Description | User must define? |
39+
|-----------------|-----------------|----------------------------------------------------|----------------------------|
40+
| **IKEv2** | **Encryption** | Algorithm to encrypt IKE negotiation messages | ✅ Yes |
41+
| **IKEv2** | **Integrity** | HMAC-based algorithm to verify IKE negotiation messages have not been tampered with | ✅ Yes |
42+
| **IKEv2** | **Key Exchange Method** | DH group to define strength of key exchange | ✅ Yes |
43+
44+
| Protocol | Element | Description | User must define? |
45+
|-----------------|-----------------|----------------------------------------------------|----------------------------|
46+
| **ESP** | **Encryption** | Algorithm to encrypt traffic's data payloads | ✅ Yes |
47+
| **ESP** | **Integrity** | HMAC-based algorithm to verify data payloads have not been tampered with. <br/><br/>Only set an HMAC integrity algorithm if **not** using an AEAD algorithm for ESP encryption (see below). Otherwise, integrity is built in, and you do not need to set an ESP integrity algorithm. | ❓ Depends |
48+
| **ESP** | **Key Exchange Method** | Not applicable to ESP. | ❌ No |
49+
50+
?? Pseudorandom function ??
51+
52+
## Encryption algorithms
53+
54+
The following encryption algorithms are available.
55+
56+
| Algorithm | AEAD / non-AEAD* | Key Size (bits)| Security Level | Notes | Recommended? |
57+
|-------------------------|------------------|----------------|----------------|-----------------------------------------------|---------------------|
58+
| `aes256gcm16` (AES-GCM) | AEAD | 256 | ✅ Very Strong | Generally the best choice for IPSec ESP & IKE | ✅ Recommended |
59+
| `aes192gcm16` (AES-GCM) | AEAD | 192 | ✅ Strong | Suitable for high-performance VPNs | 👍 Acceptable |
60+
| `aes128gcm16` (AES-GCM) | AEAD | 128 | ✅ Strong | Suitable for high-performance VPNs | 👍 Acceptable |
61+
| `aes256ccm16` (AES-CCM) | AEAD | 256 | ✅ Strong | Alternative to AES-GCM, but GCM is preferred | 👍 Acceptable |
62+
| `aes128ccm16` (AES-CCM) | AEAD | 128 | ⚠️ Medium | Alternative to AES-GCM, but GCM is preferred | 👍 Acceptable |
63+
| `chacha20poly1305` | AEAD | 256 | ✅ Strong | Performance-sensitive (mobile, embedded), best choice for low-power devices | ✅ Recommended |
64+
| `aes256` (AES-CBC) | non-AEAD | 256 | ✅ Strong | Suitable for legacy VPNs. Use only with HMAC (e.g. `sha256`)| ⚠️ Use with caution |
65+
| `aes192` (AES-CBC) | non-AEAD | 192 | ⚠️ Medium | Rarely used, `aes256` is preferred. | ⚠️ Use with caution |
66+
| `aes128` (AES-CBC) | non-AEAD | 128 | ⚠️ Medium | Suitable for performance-sensitive VPNs, where constraints don't allow `aes256` | ⚠️ Use with caution |
67+
68+
\* **A**uthenticated **E**ncryption with **A**ssociated **D**ata (**AEAD**) algorithms provide both encryption and authentication in a single step. They are more secure and efficient than non-AEAD algorithms, but are not supported by all legacy devices. We recommend that you always prefer AEAD algorithms (`aes256gcm16` or `chacha20poly1305`) for performance and security. Choosing an AEAD algorithm for ESP encryption means you do **not** need to define an algorithm for ESP integrity.
69+
70+
## Integrity algorithms
71+
72+
Integrity is based on **H**ash-based **M**essage **A**uthentication **C**ode (HMAC). The following algorithms are available:
73+
74+
| Algorithm | Output Size (bits)| Security Level | Notes | Recommended? |
75+
|-------------------------|--------------------|-----------------|---------------------------------------------------------|---------------------|
76+
| `sha512` | 512 | ✅ Very Strong | Suitable for high security environments. Use for long term security. | ✅ Recommended |
77+
| `sha384` | 384 | ✅ Strong | Balanced security/performance. Good alternative to `sha-512` | ✅ Recommended |
78+
| `sha256` | 256 | ✅ Strong | Default for most VPNs. Recommended baseline. | ✅ Recommended |
79+
80+
## Key exchange methods
81+
82+
Key exchange is **D**iffie-**H**ellman-based. The following DH groups can be set to determine the strength and performance of the key exchange:
83+
84+
| DH Group | Bit Size | Security Level | Use Case | Recommended? |
85+
|------------------------|-----------|-----------------|------------------------------------------------------------------|------------------|
86+
| `ecp521` | 521 | ✅ Very Strong | Suitable for high security environments. May be overkill (lowers performance) |👍 Acceptable |
87+
| `ecp384` | 384 | ✅ Strong | Both strong and fast. **Our top choice for modern VPNs.** |✅ Recommended |
88+
| `ecp256` | 256 | ✅ Strong | Suitable for performance-sensitive VPNs. |✅ Recommended |
89+
| `curve25519` (X25519) | 256 | ✅ Very Strong | Both strong and fast. **Our top choice for performance**. |✅ Recommended |
90+
| `modp4096` | 4096 | ✅ Strong | Strong but slow. May be suitable for legacy VPNs. |👍 Acceptable |
91+
| `modp3072` | 3072 | ✅ Medium-Strong | May be suitable for legacy VPNs. |👍 Acceptable |
92+
| `modp2048` | 2048 | ⚠️ Minimum | Use for older VPNs only if absolutely needed |⚠️ Use with caution |
93+
94+
95+
96+
97+
98+

0 commit comments

Comments
 (0)