mirror of
https://git.numenor-labs.us/dsfx.git
synced 2025-04-29 16:20:34 +00:00
125 lines
4.2 KiB
Markdown
125 lines
4.2 KiB
Markdown
# dsfx: Distributed Secure File Exchange
|
||
|
||
dsfx is a robust, secure, and distributed file exchange system written in Go. Designed from the ground up for safety, performance, and ease of maintenance, dsfx enables encrypted file transfers between nodes in a distributed network. Its streamlined architecture ensures that file exchanges are both secure and efficient.
|
||
|
||
---
|
||
|
||
## Features
|
||
|
||
- **End-to-End Security:** Uses modern cryptographic primitives (ECDSA keys, for example) to ensure that all file exchanges are encrypted and authenticated.
|
||
- **Distributed Architecture:** Designed for secure file exchange across multiple nodes with built-in support for key-based authentication.
|
||
- **High Performance:** Optimized for low latency and high throughput, with a focus on reliable and predictable behavior.
|
||
- **Administrative and Test Tools:** The dsfx client can be used to test connectivity and perform preliminary administrative actions against the dsfx server.
|
||
- **Easy Integration:** Built in Go with minimal external dependencies, dsfx is simple to deploy and integrate into existing systems.
|
||
|
||
---
|
||
|
||
## Installation
|
||
|
||
### Prerequisites
|
||
|
||
- Go 1.24 or later is required.
|
||
- Git
|
||
|
||
### Build from Source
|
||
|
||
Clone the repository:
|
||
|
||
git clone https://koti.casa/numenor-labs/dsfx.git
|
||
cd dsfx
|
||
|
||
Build the project:
|
||
|
||
go build -o dsfx-server ./dsfx-server
|
||
go build -o dsfx-client ./dsfx-client
|
||
|
||
You can also install the executables to your $GOPATH/bin:
|
||
|
||
go install ./dsfx-server
|
||
go install ./dsfx-client
|
||
|
||
---
|
||
|
||
## Usage
|
||
|
||
### Starting the Server
|
||
|
||
The dsfx-server requires a listening host, port, and a master key (ECDSA private key in PEM format). For example:
|
||
|
||
./dsfx-server -host localhost -port 8000 -masterKey /path/to/masterkey.pem
|
||
|
||
> Note, if you need to generate a new ECDSA key, you can use the following command: `go run ./cmd/genid > path/to/masterkey.pem`
|
||
|
||
Command-line flags for dsfx-server:
|
||
|
||
-host (default "localhost")
|
||
The host interface on which the server will listen.
|
||
|
||
-port (default 8000)
|
||
The TCP port on which the server will accept connections.
|
||
|
||
-masterKey (required)
|
||
File path to the PEM-encoded ECDSA private key that serves as the server’s master key.
|
||
|
||
Once started, the server will bind to the specified host and port and wait for incoming secure file exchange (or other test) connections. When a client connects, the initial payload (up to 1024 bytes) from the client is read and logged.
|
||
|
||
### Running the Client
|
||
|
||
The dsfx-client uses a private key for the client (also an ECDSA key in PEM format) and currently supports only the “test” command for checking connectivity to the server.
|
||
|
||
Client command usage:
|
||
|
||
./dsfx-client -key /path/to/clientkey.pem test <remote_addr>
|
||
|
||
Where:
|
||
|
||
-key (required)
|
||
Specifies the file path to your client’s PEM-encoded private key.
|
||
|
||
The command-line arguments for the dsfx-client are as follows:
|
||
|
||
Command: test
|
||
Tests the connection against the remote dsfx-server instance.
|
||
|
||
<remote_addr>:
|
||
The address of the server in the format “dsfx://IP:PORT#PUBLIC_KEY_BASE_64”.
|
||
For example, “dsfx://127.0.0.1:8000#<base64 pubkey>” or “dsfx://127.0.0.1:8000#eyJuIjoiLy8v..."
|
||
|
||
Example:
|
||
|
||
./dsfx-client -key ./dsfx-client/masterkey test dsfx://127.0.0.1:8000#eyJuIjoiLy8v..
|
||
|
||
If no command or an unrecognized command is provided, the client will print a brief usage message and exit.
|
||
|
||
### Help and Usage Information
|
||
|
||
For quick help, simply pass the -h flag:
|
||
|
||
./dsfx-server -h
|
||
./dsfx-client -h
|
||
|
||
This will display the usage information along with available flags.
|
||
|
||
---
|
||
|
||
## Contributing
|
||
|
||
Contributions to dsfx are welcome and encouraged!
|
||
|
||
### How to Contribute
|
||
|
||
1. **Fork the Repository:** Create your own branch from the latest code in `main`.
|
||
2. **Make Your Changes:** Follow the [TigerStyle for Go](./tigerstyle.md) guidelines to ensure code consistency and quality.
|
||
3. **Write Tests:** Ensure that new features and bug fixes include proper tests.
|
||
4. **Submit a Pull Request:** Document your changes clearly in your pull request.
|
||
|
||
### Reporting Issues
|
||
|
||
Please use the Git repository's issue tracker to report bugs or to suggest new features. Provide as much detail as possible to help reproduce and address any issues.
|
||
|
||
---
|
||
|
||
## License
|
||
|
||
dsfx is distributed under the MIT License. See [LICENSE](./LICENSE) for details.
|