artabramov/hidden-s3 repository overview

⁠Hidden S3 — encrypted self-hosted S3 storage

Hidden S3 is S3-compatible object storage for sensitive data on privately managed infrastructure. It provides filesystem-level encryption independently of the S3 layer while maintaining full S3 compatibility.

Built on gocryptfs and VersityGW, the system combines encrypted storage with an S3-compatible gateway. VersityGW provides the S3 API, IAM, and WebGUI, while a REST management API controls the encrypted storage lifecycle.

⁠References

• GitHub repository⁠
• GitHub pages⁠

⁠Quick start

Prepare the host directory for application secrets:

sudo mkdir -p /mnt/hidden/secrets
sudo mount --bind /mnt/hidden /mnt/hidden
sudo mount --make-shared /mnt/hidden

For stronger separation, mount removable media or remote storage at /mnt/hidden/secrets before starting the container.

Download the latest image:

docker pull artabramov/hidden:latest

Create and run the container:

docker run -d \
  --init \
  --restart unless-stopped \
  --cap-add SYS_ADMIN \
  --device /dev/fuse \
  --security-opt apparmor:unconfined \
  -p 8081:8081 \
  -p 9000:9000 \
  -p 8080:8080 \
  -v hidden-cipherdir:/var/lib/cipherdir \
  --mount type=bind,source=/mnt/hidden,target=/var/lib/hidden,bind-propagation=rslave \
  --name hidden \
  artabramov/hidden:latest

Open the management interface to initialize and mount encrypted storage:

REST API: http://localhost:8081/docs⁠

Once storage is mounted:

S3 API: http://localhost:9000⁠
WebGUI: http://localhost:8080⁠

⁠How it works

S3 data and IAM state reside within the encrypted filesystem. Decrypted data is available only while the filesystem is mounted and is accessible externally only through the S3 API.

Initialization, mounting, unmounting, and other operations on the encrypted storage require both the secrets volume to be available and the master password to be provided. If either is unavailable, the storage remains protected.

As an additional protection layer, a watchdog monitors critical runtime conditions. If the application process fails, the secrets volume becomes unavailable, or the storage itself becomes inaccessible, it automatically unmounts the decrypted filesystem and stops the S3 gateway.

⁠What is protected

The protection model covers physical access to stored data, storage volumes, or the host system. Encryption remains independent of the S3 layer and application-level access controls.

• Stolen host or unauthorized disk access. The cipherdir contains encrypted data only. Physical access to the host or storage, raw disk access, filesystem recovery tools, or direct inspection of the encrypted volume do not expose plaintext file contents or names.

• Leaked volume data. The cipherdir and secrets volumes are protected independently. A copied or exposed cipherdir remains encrypted without the corresponding gocryptfs passphrase, while the passphrase stored in secrets is itself encrypted and cannot be used without the master password. Even possession of both volumes is insufficient to access the stored data without the master password.

• Unexpected runtime conditions. A watchdog monitors the application process, the secrets volume, and the encrypted storage. If a critical condition is detected, it unmounts the decrypted filesystem and stops the S3 gateway.

• Container loss or replacement. Persistent data and secrets are stored outside the application container, allowing the container to be replaced without affecting the stored data. The cipherdir can also be mounted directly with gocryptfs using the decrypted passphrase, providing access to its POSIX files and directories independently of the application.

⁠What is not protected against

The protection model does not cover compromised runtime environments or recovery from a lost master password.

• Runtime host or container compromise. While the encrypted filesystem is mounted, decrypted data exists inside the container. An attacker with sufficient privileges on the host or inside the container may be able to access the decrypted filesystem directly.

• Forgotten master password. The master password is not stored anywhere. If lost, the encrypted passphrase cannot be unlocked and the storage cannot be recovered.

• Unsecured network access. The application does not encrypt network traffic. TLS must be configured at the infrastructure level. Without it, an attacker with access to the trusted network may intercept sensitive information transmitted over the network.

⁠License

Apache License 2.0