Nathaniel Fredericks 413328392d

chore(README.md): Fix macOS bin directory

2019-03-15 16:27:22 -03:00

21 KiB

Raw Blame History

ffsend [WIP]

Easily and securely share files from the command line. A fully featured Firefox Send client.

Easily and securely share files and directories from the command line through a safe, private and encrypted link using a single simple command. Files are shared using the Send service and may be up to 2GB. Others are able to download these files with this tool, or through their web browser.

No demo visible here? View it on asciinema.

All files are always encrypted on the client, and secrets are never shared with the remote host. An optional password may be specified, and a default file lifetime of 1 (up to 20) download or 24 hours is enforced to ensure your stuff does not remain online forever. This provides a secure platform to share your files. Find out more about security here.

Features
Usage
Requirements
Install (Linux, macOS, Windows, Other OS/arch)
Build
Configuration and environment
Security
Help
Special thanks
License

The public Send service that is used as default host is provided by Mozilla.
This application is not affiliated with Mozilla, Firefox or Firefox Send in any way.

Note: this tool is currently in alpha

Features

Fully featured and friendly command line tool
Upload and download files and directories securely
Always encrypted on the client
Additional password protection, generation and configurable download limits
File and directory archiving and extraction
Built-in share URL shortener and QR code generator
Supports old and new Firefox Send server versions
History tracking your files for easy management
Ability to use custom Send hosts
Inspect or delete shared files
Accurate error reporting
Streaming encryption and uploading/downloading, very low memory footprint
Intended for use in scripts without interaction
Upcoming: Firefox Account integration (higher download counts, longer expiry times)

For a list of upcoming features and ideas, take a look at the current open issues over on GitLab.

Usage

Easily upload and download:

# Simple upload
$ ffsend upload my-file.txt
Share link: https://send.firefox.com/#sample-share-url

# Advanced upload
# - Specify a download limit of 20
# - Enter a password to encrypt the file
# - Archive the file before uploading
# - Copy the shareable link to your clipboard
# - Open the shareable link in your browser
$ ffsend upload --downloads 20 --password --archive --copy --open my-file.txt
Password: ******
Share link: https://send.firefox.com/#sample-share-url

# Upload to your own host
$ ffsend u -h https://example.com/ my-file.txt
Share link: https://example.com/#sample-share-url

# Simple download
$ ffsend download https://send.firefox.com/#sample-share-url

Inspect remote files:

# Check if a file exists
$ ffsend exists https://send.firefox.com/#sample-share-url
Exists: yes

# Fetch remote file info
$ ffsend info https://send.firefox.com/#sample-share-url
ID:         b087066715
Name:       my-file.txt
Size:       12 KiB
MIME:       text/plain
Downloads:  0 of 10
Expiry:     18h2m (64928s)

Other commands include:

# View your file history
$ ffsend history
#  LINK                                        EXPIRY  OWNER TOKEN
1  https://send.firefox.com/#sample-share-url  23h57m  eea9f544f6d5df8a5afd
2  https://send.firefox.com/#other-sample-url  17h38m  1e9fef63fee3baaf54ce
3  https://example.com/#sample-share-url       37m30s  8eb28bc1bc85cfdab0e4

# Change the password after uploading
$ ffsend password https://send.firefox.com/#sample-share-url
Password: ******

# Delete a file
$ ffsend delete https://send.firefox.com/#sample-share-url

Use the --help flag, help subcommand, or see the help section for all available subcommands.

Requirements

Linux, Windows or macOS
A terminal 😎
Internet connection for uploading and downloading
Linux specific:
- OpenSSL & CA certificates:
  - Ubuntu, Debian and derivatives: apt install openssl ca-certificates
- Optional: xclip for clipboard support
  - Ubuntu, Debian and derivatives: apt install xclip
  - CentOS/Red Hat/openSUSE/Fedora: yum install xclip
  - Arch: pacman -S xclip
Windows specific:
- OpenSSL v1.1.0j: » Installer
macOS specific:
- OpenSSL: brew install openssl@1.1

Install

Because ffsend is still in alpha, only limited installation options are available right now.

Make sure you meet and install the requirements.

See the operating system specific instructions below:

Linux
macOS
Windows
Other OS or architecture

Linux (all distributions)

Using the snap package is recommended if supported.
Alternatively you may install it manually using the prebuilt binaries.

Only 64-bit (x86_64) packages and binaries are provided. For other architectures and configurations you may compile from source.

More packages options will be coming soon.

Linux: snap package

Note: The ffsend snap package is isolated, and can only access files in your home directory. Use a different installation option instead if you don't want this.

» ffsend

snap install ffsend
ffsend --help

Linux: Arch AUR packages

» ffsend (binary package)
» ffsend-git (compile from source package)

yaourt -S ffsend
# or
yay ffsend
# or
aurget -S ffsend
# or using any other AUR installer

ffsend --help

Linux: Prebuilt binaries

Check out the latest release assets for Linux binaries.
Use the ffsend-v*-linux-x64-static binary, to minimize the chance for issues.

Make sure you meet and install the requirements before you continue.

You must make the binary executable, and may want to move it into /usr/bin to make it easily executable:

# Rename binary to ffsend
mv ./ffsend-* ./ffsend

# Mark binary as executable
chmod a+x ./ffsend

# Move binary into path, to make it easily usable
sudo mv ./ffsend /usr/local/bin/

ffsend --help

macOS

Currently only a prebuilt binary is available for macOS.

A homebrew package will be coming soon.

macOS: Prebuilt binaries

Check out the latest release assets for a macOS binary.

You must install openssl through homebrew which ffsend depends on.

Then, mark the downloaded binary as an executable. You then may want to move it into /usr/local/bin/ to make the ffsend command globally available:

# Install openssl dependency
brew install openssl@1.1

# Rename file to ffsend
mv ./ffsend-* ./ffsend

# Mark binary as executable
chmod a+x ./ffsend

# Move binary into path, to make it easily usable
sudo mv ./ffsend /usr/local/bin/

ffsend

Windows

Using the scoop package is recommended.
Alternatively you may install it manually using the prebuilt binaries.

If you're using the Windows Subsystem for Linux, it's highly recommended to install the prebuilt Linux binary instead.

Only 64-bit (x86_64) binaries are provided. For other architectures and configurations you may compile from source.

A chocolatey package along with an .msi installer will be coming soon.

Windows: scoop package

Make sure you've scoop installed, and run:

scoop install ffsend
ffsend --help

Windows: Prebuilt binaries

Check out the latest release assets for Windows binaries. Use the ffsend-v*-windows-x64-static binary, to minimize the chance for issues.

You must install OpenSSL 1.1.0j which ffsend depends on. The installer for this can be found here: » Installer

You can use ffsend from the command line in the same directory:

.\ffsend.exe --help

To make it globally invokable as ffsend, you must make the binary available in your systems PATH. The easiest solution is to move it into System32:

move .\ffsend.exe C:\Windows\System32\ffsend.exe

Other OS or architecture

If your system runs Docker, you can use the docker image. There are currently no other binaries or packages available.

You can build the project from source instead.

Docker image

A Docker image is available for using ffsend running in a container. Mount a directory to /data, so it's accessible for ffsend in the container, and use the command as you normally would.

» timvisee/ffsend

# Run container with no parameters
docker run --rm -it -v $PWD:/data timvisee/ffsend

# Upload a file
docker run --rm -it -v $PWD:/data timvisee/ffsend upload my-file.txt

# Download a file
docker run --rm -it -v $PWD:/data timvisee/ffsend download https://send.firefox.com/#sample-share-url

# View help
docker run --rm -it -v $PWD:/data timvisee/ffsend help

Build

To build and install ffsend yourself, you meet the following requirements before proceeding:

Build requirements

Regular requirements
git
rust v1.32 or higher (install using rustup)
OpenSSL or LibreSSL libraries and headers must be available
- Linux:
  - Ubuntu, Debian and derivatives: apt install build-essential cmake pkg-config libssl-dev
  - CentOS/Red Hat/openSUSE: yum install gcc gcc-c++ make cmake openssl-devel
  - Arch: pacman -S openssl base-devel
- Gentoo: emerge -a dev-util/pkgconfig dev-util/cmake dev-libs/openssl
  - Fedora: dnf install gcc gcc-c++ make cmake openssl-devel
  - Or see instructions here
- Windows:
  - See instructions here here
- macOS:
  - Using brew: brew install cmake pkg-config openssl
  - Or see instructions here

Compile and install

Then, walk through one of the following steps to compile and install ffsend:

Compile and install it directly from cargo:

# Compile and install from cargo
cargo install ffsend -f

# Start using ffsend
ffsend --help

Or clone the repository and install it with cargo:

# Clone the project
git clone https://github.com/timvisee/ffsend.git
cd ffsend

# Compile and install
cargo install -f

# Start using ffsend
ffsend --help

# or run it directly from cargo
cargo run --release -- --help

Or clone the repository and invoke the binary directly (Linux/macOS):

# Clone the project
git clone https://github.com/timvisee/ffsend.git
cd ffsend

# Build the project (release version)
cargo build --release

# Start using ffsend
./target/release/ffsend --help

Compile features / use flags

Different use flags are available for ffsend to toggle whether to include various features. The following features are available, some of which are enabled by default:

Feature	Enabled	Description
`send2`	Default	Support for Firefox Send v2 servers
`send3`	Default	Support for Firefox Send v3 servers
`clipboard`	Default	Support for copying links to the clipboard
`history`	Default	Support for tracking files in history
`archive`	Default	Support for archiving and extracting uploads and downloads
`qrcode`	Default	Support for rendering a QR code for a share URL
`urlshorten`	Default	Support for shortening share URLs
`no-color`		Compile without color support in error and help messages

To enable features during building or installation, specify them with --features <features...> when using cargo. You may want to disable default features first using --no-default-features. Here are some examples:

# Defaults set of features with no-color, one of
cargo install --features no-color
cargo build --release --features no-color

# None of the features
cargo install --no-default-features

# Only history and clipboard support
cargo install --no-default--features --features history,clipboard

For Windows systems it is recommended to provide the no-color flag, as color support in Windows terminals is flaky.

Configuration and environment

The following environment variables may be used to configure the following defaults. The CLI flag is shown along with it, to better describe the relation to command line arguments:

Variable	CLI flag	Description
`FFSEND_HISTORY`	`--history <FILE>`	History file path
`FFSEND_HOST`	`--host <URL>`	Upload host
`FFSEND_TIMEOUT`	`--timeout <SECONDS>`	Request timeout (0 to disable)
`FFSEND_TRANSFER_TIMEOUT`	`--transfer-timeout <SECONDS>`	Transfer timeout (0 to disable)
`FFSEND_API`	`--api <VERSION>`	Server API version, `-` to lookup

These environment variables may be used to toggle a flag, simply by making them available. The actual value of these variables is ignored, and variables may be empty.

Variable	CLI flag	Description
`FFSEND_FORCE`	`--force`	Force operations
`FFSEND_NO_INTERACT`	`--no-interact`	No interaction for prompts
`FFSEND_YES`	`--yes`	Assume yes for prompts
`FFSEND_INCOGNITO`	`--incognito`	Incognito mode, don't use history
`FFSEND_OPEN`	`--open`	Open share link of uploaded file
`FFSEND_ARCHIVE`	`--archive`	Archive files uploaded
`FFSEND_EXTRACT`	`--extract`	Extract files downloaded
`FFSEND_COPY`	`--copy`	Copy share link to clipboard
`FFSEND_COPY_CMD`	`--copy-cmd`	Copy download command to clipboard
`FFSEND_QUIET`	`--quiet`	Log quiet information
`FFSEND_VERBOSE`	`--verbose`	Log verbose information

At this time, no configuration or dotfile file support is available. This will be something added in a later release.

Security

In short; the ffsend tool and the Send service can be considered secure, and may be used to share sensitive files. Note though that the created share link for an upload will allow anyone to download the file. Make sure you don't share this link with unauthorized people.

For more detailed information on encryption, please read the rest of the paragraphs in this security section.

Note: even though the encryption method is considered secure, this ffsend tool does not provide any warranty in any way, shape or form for files that somehow got decrypted without proper authorization.

Client side encryption

ffsend uses client side encryption, to ensure your files are securely encrypted before they are uploaded to the remote host. This makes it impossible for third parties to decrypt your file without having the secret (encryption key). The file and its metadata are encrypted using 128-bit AES-GCM, and a HMAC SHA-256 signing key is used for request authentication. This is consistent with the encryption documentation provided by the Send service, ffsend is a tool for.

A detailed list on the encryption/decryption steps, and on what encryption is exactly used can be found here in the official service documentation.

The encryption secret, that is used to decrypt the file when downloading, is included in the share URL behind the # (hash). This secret is never sent the remote server directly when using the share link in your browser. It would be possible however for a webpage to load some malicious JavaScript snippet that eventually steals the secret from the link once the page is loaded. Although this scenario is extremely unlikely, there are some options to prevent this from happening:

Only use this ffsend tool, do not use the share link in your browser.
Add additional protection by specifying a password using --password while uploading, or using the password subcommand afterwards.
Host a secure Send service instance yourself.

A complete overview on encryption can be found in the official service documentation here.

Help

$ ffsend help

ffsend 0.2.33
Tim Visee <timvisee.com>
Easily and securely share files from the command line.
A fully featured Firefox Send client.

USAGE:
    ffsend [FLAGS] [OPTIONS] [SUBCOMMAND]

FLAGS:
    -f, --force          Force the action, ignore warnings
    -h, --help           Prints help information
    -i, --incognito      Don't update local history for actions
    -I, --no-interact    Not interactive, do not prompt
    -q, --quiet          Produce output suitable for logging and automation
    -V, --version        Prints version information
    -v, --verbose        Enable verbose information and logging
    -y, --yes            Assume yes for prompts

OPTIONS:
    -H, --history <FILE>                Use the specified history file [env: FFSEND_HISTORY]
    -t, --timeout <SECONDS>             Request timeout (0 to disable) [env: FFSEND_TIMEOUT]
    -T, --transfer-timeout <SECONDS>    Transfer timeout (0 to disable) [env: FFSEND_TRANSFER_TIMEOUT]

SUBCOMMANDS:
    upload        Upload files [aliases: u, up]
    download      Download files [aliases: d, down]
    debug         View debug information [aliases: dbg]
    delete        Delete a shared file [aliases: del]
    exists        Check whether a remote file exists [aliases: e]
    help          Prints this message or the help of the given subcommand(s)
    history       View file history [aliases: h]
    info          Fetch info about a shared file [aliases: i]
    parameters    Change parameters of a shared file [aliases: params]
    password      Change the password of a shared file [aliases: pass, p]
    version       Determine the Send server version [aliases: v]

The public Send service that is used as default host is provided by Mozilla.
This application is not affiliated with Mozilla, Firefox or Firefox Send.

Special thanks

to Mozilla for building and hosting the amazing Firefox Send service
to everyone involved with asciinema and svg-term for providing tools to make great visual demos
to everyone involved in all crate dependencies used

License

This project is released under the GNU GPL-3.0 license. Check out the LICENSE file for more information.

21 KiB Raw Blame History