Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/finfet/kestrel

File encryption done right
https://github.com/finfet/kestrel

cryptography encryption end-to-end-encryption

Last synced: 17 days ago
JSON representation

File encryption done right

Awesome Lists containing this project

README 

        
Kestrel Logo



**File encryption done right**



## About



Kestrel is a data-at-rest file encryption program that lets you encrypt files

to anyone with a public key.



## Features and Advantages



- Encrypt files using a public key or a password.

- Strong security and privacy guarantees. Uses X25519, ChaCha20-Poly1305

  and the Noise Protocol. Guarantees sender authentication.

- Secure defaults with zero configuration needed.

- Supports files of any size.

- Keys are simple strings that are easy to manage and copy-paste.

- Private keys are always encrypted.

- Single binary that is easy to run anywhere.

- Supports Linux, macOS, Windows.



## Limitations



- Does not handle signatures. You can't sign files with this. However,

  sender authentication is guaranteed.

- Does not solve the key distribution problem. You have to acquire

  known-good public keys through some other means.



## Security Properties



- **Sender authentication**: When you successfully decrypt a file, you can be

  certain that it came from someone that you know and that it hasn't been

  tampered with in any way.

- **Metadata protection**: Encrypted files contain absolutely zero information

  about the sender or recipient.

- **Deniability**: Unlike using a digital signature for authentication, Kestrel

  provides sender authentication without non-repudiation. You are not

  cryptographically bound to the messages that you send. If the recipient tries

  to reveal a message, you are able to deny that you sent that message.

- **Partial forward secrecy**: An attacker must compromise the _recipient's_

  private key in order to decrypt a file. Someone else getting their private

  key compromised doesn't affect the files that they had previously sent to you.



Kestrel uses a combination of the Noise Protocol and a chunked file encryption

scheme. Read the [security documentation](https://getkestrel.com/docs/security-information.html)

for more details.



## Advantages compared to other applications



**GPG**



GPG is a massively complex tool with many use cases, features, and shortcomings.

In general, Kestrel provides better default security guarantees with no

configuration required. In particular, by default, GPG does not provide sender

authentication or metadata protection. Sender authentication can be

added by including signatures, but this removes deniability. In contrast,

Kestrel includes sender authentication while preserving deniability and

protecting metadata.



**age**



age is a newer tool with strong defaults and is much less complex than GPG.

However, age does not provide sender authentication. A successfully decrypted

file could have come from anyone, including from an attacker that replaced the

file with a malicious copy. Kestrel fixes this by showing you the exact sender

of a file.



## Installation



Tested on Linux, macOS, Windows



Download from the [Official Site](https://getkestrel.com)



Or grab the [GitHub release](https://github.com/finfet/kestrel/releases/latest)



If you have cargo you can also use `cargo install --locked kestrel-cli`



## Usage Examples



Generate a new private key

```

$ kestrel key gen -o keyring.txt

Key name: alice

New password:

Confirm password:

$ cat keyring.txt

[Key]

Name = alice

PublicKey = D7ZZstGYF6okKKEV2rwoUza/tK3iUa8IMY+l5tuirmzzkEog

PrivateKey = ZWdrMPEp09tKN3rAutCDQTshrNqoh0MLPnEERRCm5KFxvXcTo+s/Sf2ze0fKebVsQilImvLzfIHRcJuX8kGetyAQL1VchvzHR28vFhdKeq+NY2KT

```



Encrypt a file

```

$ kestrel encrypt example.txt --to alice --from alice -o example.txt.ktl -k keyring.txt

```



Decrypt a file

```

$ kestrel decrypt example.txt.ktl -t alice -o example.txt -k keyring.txt

```



Encrypt a file using a password

```

$ kestrel pass enc example.txt -o example.txt.ktl

```



Set the environment variable `KESTREL_KEYRING` to use a default keyring file.



## Usage



```

USAGE:

    kestrel encrypt [FILE] -t NAME -f NAME [-o FILE] [-k KEYRING]

    kestrel decrypt [FILE] -t NAME [-o FILE] [-k KEYRING]

    kestrel key generate [-o FILE]

    kestrel key change-pass PRIVATE-KEY

    kestrel key extract-pub PRIVATE-KEY

    kestrel password encrypt|decrypt [FILE] [-o FILE]



    Aliases enc, dec, pass, and gen can be used as encrypt, decrypt,

    password, and generate respectively.

    Option -k is required unless KESTREL_KEYRING env var is set.



OPTIONS:

    -t, --to      NAME    Recipient key name. Decrypt requires a private key.

    -f, --from    NAME    Sender key name. Must be a private key.

    -o, --output  FILE    Output file name.

    -k, --keyring KEYRING Location of a keyring file.

    -h, --help            Print help information.

    -v, --version         Print version information.

    --env-pass            Read password from KESTREL_PASSWORD env var

```



## Documentation



View the [documentation](https://getkestrel.com/docs/)



Source code for the documentation can be found in the

[kestrel-doc](https://github.com/finfet/kestrel-doc) repository.



## Contributing



Patches welcome. Please send feedback and bug reports for any issues that

you may have.



## License



BSD 3 Clause



Unless you explicitly state otherwise, any contribution intentionally

submitted for inclusion in this project by you, shall be licensed as

BSD-3-Clause, without any additonal terms or conditions.



> [!WARNING]

> To the best of my knowledge, Kestrel is secure. However, this software has

> not yet undergone a formal security audit. Swim at your own risk.