coosld/kubo
1
0
Fork 0
mirror of https://github.com/ipfs/kubo.git synced 2026-02-21 18:37:45 +08:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

docs(config): add security considerations for rpc (#10739)
Some checks are pending
CodeQL / codeql (push) Waiting to run
Details
Docker Build / docker-build (push) Waiting to run
Details
Gateway Conformance / gateway-conformance (push) Waiting to run
Details
Gateway Conformance / gateway-conformance-libp2p-experiment (push) Waiting to run
Details
Go Build / go-build (push) Waiting to run
Details
Go Check / go-check (push) Waiting to run
Details
Go Lint / go-lint (push) Waiting to run
Details
Go Test / go-test (push) Waiting to run
Details
Interop / interop-prep (push) Waiting to run
Details
Interop / helia-interop (push) Blocked by required conditions
Details
Interop / ipfs-webui (push) Blocked by required conditions
Details
Sharness / sharness-test (push) Waiting to run
Details
Spell Check / spellcheck (push) Waiting to run
Details

Browse Source 
* 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.
This commit is contained in:
Marcin Rataj 2025-03-04 21:12:15 +01:00 committed by GitHub
parent 4c29169aa5
commit 5a3ec3a728
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 56 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
docs/config.md
View File

@ -225,6 +225,19 @@ Supported Transports:
* tcp/ip{4,6} - `/ipN/.../tcp/...`
* unix - `/unix/path/to/socket`
> [!CAUTION]
> **NEVER EXPOSE UNPROTECTED ADMIN RPC TO LAN OR THE PUBLIC INTERNET**
>
> The RPC API grants admin-level access to your Kubo IPFS node, including
> configuration and secret key management.
>
> By default, it is bound to localhost for security reasons. Exposing it to LAN
> or the public internet is highly risky—similar to exposing a SQL database or
> backend service without authentication middleware
>
> - 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.
> - If you are looking for an interface designed for browsers and public internet, use [`Addresses.Gateway`](#addressesgateway) port instead.
Default: `/ip4/127.0.0.1/tcp/5001`
Type: `strings` ([multiaddrs][multiaddr])
@ -255,6 +268,9 @@ Supported Transports:
* quicv1 (RFC9000) - `/ipN/.../udp/.../quic-v1` - can share the same two tuple with `/quic-v1/webtransport`
* webtransport `/ipN/.../udp/.../quic-v1/webtransport` - can share the same two tuple with `/quic-v1`
> [!IMPORTANT]
> Make sure your firewall rules allow incoming connections on both TCP and UDP ports defined here.
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).
Default:
@ -329,7 +345,7 @@ The `API.Authorizations` field defines user-based access restrictions for the
[Kubo RPC API](https://docs.ipfs.tech/reference/kubo/rpc/), which is located at
`Addresses.API` under `/api/v0` paths.
By default, the RPC API is accessible without restrictions as it is only
By default, the admin-level RPC API is accessible without restrictions as it is only
exposed on `127.0.0.1` and safeguarded with Origin check and implicit
[CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) headers that
block random websites from accessing the RPC.
@ -339,6 +355,15 @@ unless a corresponding secret is present in the HTTP [`Authorization` header](ht
and the requested path is included in the `AllowedPaths` list for that specific
secret.
> [!CAUTION]
> **NEVER EXPOSE UNPROTECTED ADMIN RPC TO LAN OR THE PUBLIC INTERNET**
>
> The RPC API is vast. It grants admin-level access to your Kubo IPFS node, including
> configuration and secret key management.
>
> - 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).
> - If you are looking for an interface designed for browsers and public internet, use [`Addresses.Gateway`](#addressesgateway) port instead.
Default: `null`
Type: `object[string -> object]` (user name -> authorization object, see below)

30
docs/experimental-features.md
View File

@ -65,6 +65,14 @@ Experimental.
### How to enable
> [!WARNING]
> **SECURITY CONSIDERATION**
>
> This feature provides the IPFS [`add` command](https://docs.ipfs.tech/reference/kubo/cli/#ipfs-add) with access to
> 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
> files from the local filesystem with the same permissions as the Kubo daemon.
> 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.
Modify your ipfs config:
```
ipfs config --json Experimental.FilestoreEnabled true
@ -96,6 +104,14 @@ v0.4.17
### How to enable
> [!WARNING]
> **SECURITY CONSIDERATION**
>
> This feature provides the IPFS [`add` CLI command](https://docs.ipfs.tech/reference/kubo/cli/#ipfs-add) with access to
> 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
> files from the local filesystem with the same permissions as the Kubo daemon.
> 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.
Modify your ipfs config:
```
ipfs config --json Experimental.UrlstoreEnabled true
@ -190,6 +206,13 @@ Experimental, will be stabilized in 0.6.0
### How to enable
> [!WARNING]
> **SECURITY CONSIDERATION**
>
> This feature provides CLI and HTTP RPC user with ability to set up port forwarding for all localhost and LAN ports.
> If you enable this and plan to expose CLI or HTTP RPC to other users or machines,
> secure RPC API using [`API.Authorizations`](https://github.com/ipfs/kubo/blob/master/docs/config.md#apiauthorizations) or custom auth middleware.
The `p2p` command needs to be enabled in the config:
```sh
@ -297,6 +320,13 @@ Experimental
### How to enable
> [!WARNING]
> **SECURITY CONSIDERATION**
>
> This feature provides CLI and HTTP RPC user with ability to set up HTTP forwarding for all localhost and LAN ports.
> If you enable this and plan to expose CLI or HTTP RPC to other users or machines,
> secure RPC API using [`API.Authorizations`](https://github.com/ipfs/kubo/blob/master/docs/config.md#apiauthorizations) or custom auth middleware.
The `p2p` command needs to be enabled in the config:
```sh