@@ -204,6 +204,34 @@ added: v23.8.0 |
204 | 204 |
|
205 | 205 | True if `endpoint.destroy()` has been called. Read only. |
206 | 206 |
|
| 207 | +### `endpoint.setSNIContexts(entries[, options])` |
| 208 | + |
| 209 | +<!-- YAML |
| 210 | +added: REPLACEME |
| 211 | +--> |
| 212 | + |
| 213 | +* `entries` {object} An object mapping host names to TLS identity options. |
| 214 | + Each entry must include `keys` and `certs`. |
| 215 | +* `options` {object} |
| 216 | + * `replace` {boolean} If `true`, replaces the entire SNI map. If `false` |
| 217 | + (the default), merges the entries into the existing map. |
| 218 | + |
| 219 | +Replaces or updates the SNI TLS contexts for this endpoint. This allows |
| 220 | +changing the TLS identity (key/certificate) used for specific host names |
| 221 | +without restarting the endpoint. Existing sessions are unaffected — only |
| 222 | +new sessions will use the updated contexts. |
| 223 | + |
| 224 | +```mjs |
| 225 | +endpoint.setSNIContexts({ |
| 226 | + 'api.example.com': { keys: [newApiKey], certs: [newApiCert] }, |
| 227 | +}); |
| 228 | + |
| 229 | +// Replace the entire SNI map |
| 230 | +endpoint.setSNIContexts({ |
| 231 | + 'api.example.com': { keys: [newApiKey], certs: [newApiCert] }, |
| 232 | +}, { replace: true }); |
| 233 | +``` |
| 234 | + |
207 | 235 | ### `endpoint.stats` |
208 | 236 |
|
209 | 237 | <!-- YAML |
@@ -1120,15 +1148,16 @@ added: v23.8.0 |
1120 | 1148 |
|
1121 | 1149 | The ALPN protocol identifier. |
1122 | 1150 |
|
1123 | | -#### `sessionOptions.ca` |
| 1151 | +#### `sessionOptions.ca` (client only) |
1124 | 1152 |
|
1125 | 1153 | <!-- YAML |
1126 | 1154 | added: v23.8.0 |
1127 | 1155 | --> |
1128 | 1156 |
|
1129 | 1157 | * Type: {ArrayBuffer|ArrayBufferView|ArrayBuffer\[]|ArrayBufferView\[]} |
1130 | 1158 |
|
1131 | | -The CA certificates to use for sessions. |
| 1159 | +The CA certificates to use for client sessions. For server sessions, CA |
| 1160 | +certificates are specified per-identity in the [`sessionOptions.sni`][] map. |
1132 | 1161 |
|
1133 | 1162 | #### `sessionOptions.cc` |
1134 | 1163 |
|
@@ -1143,15 +1172,16 @@ Specifies the congestion control algorithm that will be used |
1143 | 1172 |
|
1144 | 1173 | This is an advanced option that users typically won't have need to specify. |
1145 | 1174 |
|
1146 | | -#### `sessionOptions.certs` |
| 1175 | +#### `sessionOptions.certs` (client only) |
1147 | 1176 |
|
1148 | 1177 | <!-- YAML |
1149 | 1178 | added: v23.8.0 |
1150 | 1179 | --> |
1151 | 1180 |
|
1152 | 1181 | * Type: {ArrayBuffer|ArrayBufferView|ArrayBuffer\[]|ArrayBufferView\[]} |
1153 | 1182 |
|
1154 | | -The TLS certificates to use for sessions. |
| 1183 | +The TLS certificates to use for client sessions. For server sessions, |
| 1184 | +certificates are specified per-identity in the [`sessionOptions.sni`][] map. |
1155 | 1185 |
|
1156 | 1186 | #### `sessionOptions.ciphers` |
1157 | 1187 |
|
@@ -1163,15 +1193,16 @@ added: v23.8.0 |
1163 | 1193 |
|
1164 | 1194 | The list of supported TLS 1.3 cipher algorithms. |
1165 | 1195 |
|
1166 | | -#### `sessionOptions.crl` |
| 1196 | +#### `sessionOptions.crl` (client only) |
1167 | 1197 |
|
1168 | 1198 | <!-- YAML |
1169 | 1199 | added: v23.8.0 |
1170 | 1200 | --> |
1171 | 1201 |
|
1172 | 1202 | * Type: {ArrayBuffer|ArrayBufferView|ArrayBuffer\[]|ArrayBufferView\[]} |
1173 | 1203 |
|
1174 | | -The CRL to use for sessions. |
| 1204 | +The CRL to use for client sessions. For server sessions, CRLs are specified |
| 1205 | +per-identity in the [`sessionOptions.sni`][] map. |
1175 | 1206 |
|
1176 | 1207 | #### `sessionOptions.groups` |
1177 | 1208 |
|
@@ -1193,7 +1224,7 @@ added: v23.8.0 |
1193 | 1224 |
|
1194 | 1225 | True to enable TLS keylogging output. |
1195 | 1226 |
|
1196 | | -#### `sessionOptions.keys` |
| 1227 | +#### `sessionOptions.keys` (client only) |
1197 | 1228 |
|
1198 | 1229 | <!-- YAML |
1199 | 1230 | added: v23.8.0 |
@@ -1205,7 +1236,8 @@ changes: |
1205 | 1236 |
|
1206 | 1237 | * Type: {KeyObject|KeyObject\[]} |
1207 | 1238 |
|
1208 | | -The TLS crypto keys to use for sessions. |
| 1239 | +The TLS crypto keys to use for client sessions. For server sessions, |
| 1240 | +keys are specified per-identity in the [`sessionOptions.sni`][] map. |
1209 | 1241 |
|
1210 | 1242 | #### `sessionOptions.maxPayloadSize` |
1211 | 1243 |
|
@@ -1288,15 +1320,56 @@ added: v23.8.0 |
1288 | 1320 | Specifies the maximum number of milliseconds a TLS handshake is permitted to take |
1289 | 1321 | to complete before timing out. |
1290 | 1322 |
|
1291 | | -#### `sessionOptions.sni` |
| 1323 | +#### `sessionOptions.servername` (client only) |
1292 | 1324 |
|
1293 | 1325 | <!-- YAML |
1294 | 1326 | added: v23.8.0 |
1295 | 1327 | --> |
1296 | 1328 |
|
1297 | 1329 | * Type: {string} |
1298 | 1330 |
|
1299 | | -The peer server name to target. |
| 1331 | +The peer server name to target (SNI). Defaults to `'localhost'`. |
| 1332 | + |
| 1333 | +#### `sessionOptions.sni` (server only) |
| 1334 | + |
| 1335 | +<!-- YAML |
| 1336 | +added: REPLACEME |
| 1337 | +--> |
| 1338 | + |
| 1339 | +* Type: {Object} |
| 1340 | + |
| 1341 | +An object mapping host names to TLS identity options for Server Name |
| 1342 | +Indication (SNI) support. This is required for server sessions. The |
| 1343 | +special key `'*'` specifies the default/fallback identity used when |
| 1344 | +no other host name matches. Each entry may contain: |
| 1345 | + |
| 1346 | +* `keys` {KeyObject|KeyObject\[]} The TLS private keys. **Required.** |
| 1347 | +* `certs` {ArrayBuffer|ArrayBufferView|ArrayBuffer\[]|ArrayBufferView\[]} |
| 1348 | + The TLS certificates. **Required.** |
| 1349 | +* `ca` {ArrayBuffer|ArrayBufferView|ArrayBuffer\[]|ArrayBufferView\[]} |
| 1350 | + Optional CA certificate overrides. |
| 1351 | +* `crl` {ArrayBuffer|ArrayBufferView|ArrayBuffer\[]|ArrayBufferView\[]} |
| 1352 | + Optional certificate revocation lists. |
| 1353 | +* `verifyPrivateKey` {boolean} Verify the private key. Default: `false`. |
| 1354 | + |
| 1355 | +```mjs |
| 1356 | +const endpoint = await listen(callback, { |
| 1357 | + sni: { |
| 1358 | + '*': { keys: [defaultKey], certs: [defaultCert] }, |
| 1359 | + 'api.example.com': { keys: [apiKey], certs: [apiCert] }, |
| 1360 | + 'www.example.com': { keys: [wwwKey], certs: [wwwCert], ca: [customCA] }, |
| 1361 | + }, |
| 1362 | +}); |
| 1363 | +``` |
| 1364 | + |
| 1365 | +Shared TLS options (such as `ciphers`, `groups`, `keylog`, and `verifyClient`) |
| 1366 | +are specified at the top level of the session options and apply to all |
| 1367 | +identities. Each SNI entry overrides only the per-identity certificate |
| 1368 | +fields. |
| 1369 | + |
| 1370 | +The SNI map can be replaced at runtime using `endpoint.setSNIContexts()`, |
| 1371 | +which atomically swaps the map for new sessions while existing sessions |
| 1372 | +continue to use their original identity. |
1300 | 1373 |
|
1301 | 1374 | #### `sessionOptions.tlsTrace` |
1302 | 1375 |
|
@@ -1338,15 +1411,17 @@ added: v23.8.0 |
1338 | 1411 |
|
1339 | 1412 | True to require verification of TLS client certificate. |
1340 | 1413 |
|
1341 | | -#### `sessionOptions.verifyPrivateKey` |
| 1414 | +#### `sessionOptions.verifyPrivateKey` (client only) |
1342 | 1415 |
|
1343 | 1416 | <!-- YAML |
1344 | 1417 | added: v23.8.0 |
1345 | 1418 | --> |
1346 | 1419 |
|
1347 | 1420 | * Type: {boolean} |
1348 | 1421 |
|
1349 | | -True to require private key verification. |
| 1422 | +True to require private key verification for client sessions. For server |
| 1423 | +sessions, this option is specified per-identity in the |
| 1424 | +[`sessionOptions.sni`][] map. |
1350 | 1425 |
|
1351 | 1426 | #### `sessionOptions.version` |
1352 | 1427 |
|
@@ -1715,3 +1790,5 @@ added: v23.8.0 |
1715 | 1790 | <!-- YAML |
1716 | 1791 | added: v23.8.0 |
1717 | 1792 | --> |
| 1793 | + |
| 1794 | +[`sessionOptions.sni`]: #sessionoptionssni-server-only |