docs(config): add security considerations for rpc (#10739)
* docs(config): add security considerations for rpc we already had big red box at https://docs.ipfs.tech/reference/kubo/rpc/, however users reading kubo docs could miss it. this ensures it is not possible to miss these basic notes.
Marcin Rataj committed
Mar 4, 2025 at 21:12 UTC
5a3ec3a72878df11cbe76cb0fd7c14ef397f2e87
2 files changed
+56
-1
docs/config.md
+26
-1
@@ -225,6 +225,19 @@ Supported Transports:
225
* tcp/ip{4,6} - `/ipN/.../tcp/...`
226
* unix - `/unix/path/to/socket`
227
228
+> [!CAUTION]
229
+> **NEVER EXPOSE UNPROTECTED ADMIN RPC TO LAN OR THE PUBLIC INTERNET**
230
+>
231
+> The RPC API grants admin-level access to your Kubo IPFS node, including
232
+> configuration and secret key management.
233
+>
234
+> By default, it is bound to localhost for security reasons. Exposing it to LAN
235
+> or the public internet is highly risky—similar to exposing a SQL database or
236
+> backend service without authentication middleware
237
+>
238
+> - If you need secure access to a subset of RPC, secure it with [`API.Authorizations`](#apiauthorizations) or custom auth middleware running in front of the localhost-only RPC port defined here.
239
+> - If you are looking for an interface designed for browsers and public internet, use [`Addresses.Gateway`](#addressesgateway) port instead.
240
+
241
Default: `/ip4/127.0.0.1/tcp/5001`
242
243
Type: `strings` ([multiaddrs][multiaddr])
@@ -255,6 +268,9 @@ Supported Transports:
268
* quicv1 (RFC9000) - `/ipN/.../udp/.../quic-v1` - can share the same two tuple with `/quic-v1/webtransport`
269
* webtransport `/ipN/.../udp/.../quic-v1/webtransport` - can share the same two tuple with `/quic-v1`
270
271
+> [!IMPORTANT]
272
+> Make sure your firewall rules allow incoming connections on both TCP and UDP ports defined here.
273
+
274
Note that quic (Draft-29) used to be supported with the format `/ipN/.../udp/.../quic`, but has since been [removed](https://github.com/libp2p/go-libp2p/releases/tag/v0.30.0).
275
276
Default:
@@ -329,7 +345,7 @@ The `API.Authorizations` field defines user-based access restrictions for the
345
[Kubo RPC API](https://docs.ipfs.tech/reference/kubo/rpc/), which is located at
346
`Addresses.API` under `/api/v0` paths.
347
332
-By default, the RPC API is accessible without restrictions as it is only
348
+By default, the admin-level RPC API is accessible without restrictions as it is only
349
exposed on `127.0.0.1` and safeguarded with Origin check and implicit
350
[CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) headers that
351
block random websites from accessing the RPC.
@@ -339,6 +355,15 @@ unless a corresponding secret is present in the HTTP [`Authorization` header](ht
355
and the requested path is included in the `AllowedPaths` list for that specific
356
secret.
357
358
+> [!CAUTION]
359
+> **NEVER EXPOSE UNPROTECTED ADMIN RPC TO LAN OR THE PUBLIC INTERNET**
360
+>
361
+> The RPC API is vast. It grants admin-level access to your Kubo IPFS node, including
362
+> configuration and secret key management.
363
+>
364
+> - If you need secure access to a subset of RPC, make sure you understand the risk, block everything by default and and allow basic auth access with [`API.Authorizations`](#apiauthorizations) or custom auth middleware running in front of the localhost-only port defined in [`Addresses.API`](#addressesapi).
365
+> - If you are looking for an interface designed for browsers and public internet, use [`Addresses.Gateway`](#addressesgateway) port instead.
366
+
367
Default: `null`
368
369
Type: `object[string -> object]` (user name -> authorization object, see below)
docs/experimental-features.md
+30
@@ -65,6 +65,14 @@ Experimental.
65
66
### How to enable
67
68
+> [!WARNING]
69
+> **SECURITY CONSIDERATION**
70
+>
71
+> This feature provides the IPFS [`add` command](https://docs.ipfs.tech/reference/kubo/cli/#ipfs-add) with access to
72
+> the local filesystem. Consequently, any user with access to CLI or the HTTP [`/v0/add` RPC API](https://docs.ipfs.tech/reference/kubo/rpc/#api-v0-add) can read
73
+> files from the local filesystem with the same permissions as the Kubo daemon.
74
+> If you enable this, secure your RPC API using [`API.Authorizations`](https://github.com/ipfs/kubo/blob/master/docs/config.md#apiauthorizations) or custom auth middleware.
75
+
76
Modify your ipfs config:
77
```
78
ipfs config --json Experimental.FilestoreEnabled true
@@ -96,6 +104,14 @@ v0.4.17
104
105
### How to enable
106
107
+> [!WARNING]
108
+> **SECURITY CONSIDERATION**
109
+>
110
+> This feature provides the IPFS [`add` CLI command](https://docs.ipfs.tech/reference/kubo/cli/#ipfs-add) with access to
111
+> the local filesystem. Consequently, any user with access to the CLI or HTTP [`/v0/add` RPC API](https://docs.ipfs.tech/reference/kubo/rpc/#api-v0-add) can read
112
+> files from the local filesystem with the same permissions as the Kubo daemon.
113
+> If you enable this, secure your RPC API using [`API.Authorizations`](https://github.com/ipfs/kubo/blob/master/docs/config.md#apiauthorizations) or custom auth middleware.
114
+
115
Modify your ipfs config:
116
```
117
ipfs config --json Experimental.UrlstoreEnabled true
@@ -190,6 +206,13 @@ Experimental, will be stabilized in 0.6.0
206
207
### How to enable
208
209
+> [!WARNING]
210
+> **SECURITY CONSIDERATION**
211
+>
212
+> This feature provides CLI and HTTP RPC user with ability to set up port forwarding for all localhost and LAN ports.
213
+> If you enable this and plan to expose CLI or HTTP RPC to other users or machines,
214
+> secure RPC API using [`API.Authorizations`](https://github.com/ipfs/kubo/blob/master/docs/config.md#apiauthorizations) or custom auth middleware.
215
+
216
The `p2p` command needs to be enabled in the config:
217
218
```sh
@@ -297,6 +320,13 @@ Experimental
320
321
### How to enable
322
323
+> [!WARNING]
324
+> **SECURITY CONSIDERATION**
325
+>
326
+> This feature provides CLI and HTTP RPC user with ability to set up HTTP forwarding for all localhost and LAN ports.
327
+> If you enable this and plan to expose CLI or HTTP RPC to other users or machines,
328
+> secure RPC API using [`API.Authorizations`](https://github.com/ipfs/kubo/blob/master/docs/config.md#apiauthorizations) or custom auth middleware.
329
+
330
The `p2p` command needs to be enabled in the config:
331
332
```sh