xecrets / xecrets-cli

Xecrets Cli - A feature-rich cross platform AxCrypt-compatible file encryption command line toolbox using a fork of original AxCrypt 2.x for cryptography. https://www.axantum.com/xecrets-ez is an easy to use graphical frontend for Windows, Linux and macOS using it, and https://www.nuget.org/packages/Xecrets.Sdk/ is a .NET SDK for it.

README

Xecrets Cli 2.x - A Cross Platform AxCrypt compatible Open Source Encryption command line tool in C# for .NET 8+

Xecrets Cli (aka "the command line", "the command line tool", or "the CLI") is built on top of AxCrypt 2.1.x as released under GNU GPL version 3 or later by AxCrypt AB.

As we're using the original code from AxCrypt, Xecrets Cli is 100% compatible with AxCrypt.

The motivation for providing Xecrets Cli is to once again provide the community with a free truly open source encryption and decryption command line tool exposing the functionality in a way easily consumable by scripts and code as well as humans. We also believe it's time to get back to basics, and remove a lot of the complexity present in AxCrypt with it's server integration, business license handling, and an overly ambitious user interface.

Xecrets Cli does not in any way communicate with any server or other infrastructure over the Internet. It is entirely run and executed locally on your system.

Starting with Xecrets Cli, we've since released a nuget SDK package for direct integration with .NET code, as well as radically simplified desktop application Xecrets Ez.

Command Line Arguments

Xecrets Cli is intended to be called from the command line by humans, scripts or code. It has a large number of options, making it a very powerful toolbox, but the basic usage is still very simple. Check out the documentation for details and examples.

Quick Start

To encrypt a file:

XecretsCli --password xecret --encrypt-to Document.txt Document-txt.axx

To decrypt a file:

XecretsCli --password xecret --decrypt-to Document-txt.axx Document.txt

There are numerous other options and features such as generating and using public key pairs, JSON output logging for programmatic use, wiping files, passing options from files or via environment variables and more. See the full help with:

XecretsCli --stdout --help --help --help | more

Maintenance Subscription for Axantum Builds

If you're using a build published by us, there are a few restrictions unless you buy a maintenance subscription. Most features are free even there, but some features intended for programmatic use such as JSON logging and taking options from files and environment variables will restrict the size of files possible to encrypt to 1 MB if you don't have a maintenance subscription valid for the build. You can always decrypt any size of file.

If you're doing your own GPL build from the sources, no restrictions apply.

Software Development Kit

To call Xecrets Cli from a .NET application as a .NET library, use the SDK which is available as nuget package Xecrets.Sdk. It comes with intellisense documentation.

Support Development

If you represent a business, please purchase your maintenance subscription for the build from us at https://www.axantum.com/ or if you're a private individual, get and build it from source but if you'd like to support us, do purchase a premium subscription for the desktop app. It's also very useful.

Xecrets Cli is free software, licensed under the GNU GPL Version 3 or later license. This means you can use it anywhere and any way you like for free, and you are also free to modify it as you wish as long as you do not redistribute it. If you do redistribute it, please check with the Free Software Foundation how this works, https://www.gnu.org/licenses/ .

Naturally this also applies to us, so we're not requiring you to pay anything to use the Xecrets Cli software.

However, we do spend time and money to develop, maintain and distribute the software for you, so if you are a business and are using the business-oriented features for programmatic integration of the software, there is a maintenance subscription required for use of the ready-built and tested software from https://www.axantum.com/ .

Nothing prevents you from downloading the source code from github where we keep the code, and building it yourself. It's maybe even a good idea to try it out. But in the long run, by getting the ready-built software from us your project is spared all the time to keep your tooling updated, building, updating the source code etc. We believe we provide a low cost service that is worth it for any business using our software!

Xecrets Cli 2.x status

The software is still in beta, API:s may break and options change at any moment. Use with care.

The AxCrypt fork xecrets-net

The only modifications we've done are to update the code to work with .NET 8 and compile with Visual Studio 2022, keep dependencies updated, a few minor bugfixes and finally another very few minor changes to be able to work well with the command line tool code. No changes to the core cryptography has been made.

How To Build?

Download the xecrets-cli and xecrets-net repositories side by side. The solution expects to find the source code for the original, slightly modified, AxCrypt there. Open the Xecrets Cli solution in Visual Studio or the workspace in Visual Studio Code and build. There are no external dependencies that are not resolved with Nuget.

Unit tests require a NUnit-compatible unit test runner.

How to Contribute

Talk to us. Due to the nature of the application, pull requests are audited very carefully. Before requesting a pull it's best if we discuss things.

Minimum requirement is that there are no compiler warnings.

Contact

Contact us via our support or through github .

xecrets-cli's Issues

Support clearer messages about license status

Improve the call signatures for LicenseBlurb so it's more useful in more cases.

Minor update to documentation and texts

Make opcode for CliVersion fixed, so it is stable across all versions

To be more resilient to version changes, set the opcode for CliVersion to a small number and never change it, so it doesn't be a part of the general more flexible op code numbering.

Update to .NET 8

Fix docs/index.md CLI documentation

It's not shown very nicely on GitHub, the markdown needs some work.

Provide Ez with stack trace on exception

When Cli is called from Ez, and there's an unhandled exception, the stack trace should be made available for display to Ez.

Improve handling of collisions with trailing (n) file names

When a file is to be written, and overwriting is disallowed, a new name is generated with a trailing pattern like "... (n).ext". If the original name already has this pattern, don't add another one, instead extract the pattern and continue increasing within that pattern until a free name is found. I.e. attempting to write "File (1).ext" when it already exists, results in for example "File (2).ext" instead of "File (1) (1).ext" as the current code does.

Update Xecrets.Licensing to 1.0.13

Pure non-functional refactoring

Add comments, remove unnecessary usings, other non-functional pure refactoring.

Tweak license blurb texts

Update Microsoft.IdentityModel.JsonWebTokens

Upgrade dependencies

Missing support for Windows-1252

.NET Core no longer has built-in support for all encodings that .NET Framework did.

Support for pre-check of finding Cli Tool and it's compatibility

Add appropriate status codes.

Support version specific license for free version of ez

Implement string encryption with ASCII armor

Implement a simple function to encrypt/decrypt a string under a password, outputting the encrypted data as ASCII armored text. It's ca. 300 bytes overhead, but that's not really of any consequence. Possibly we could in the future do a slimmed down version with less overhead. Since it starts with a GUID, we don't need to wrap it with marker lines, but perhaps
we should anyway to make it easy for humans to know what it is.

It's almost the most common question asked in all forums "How do I encrypt a string" - and this would be a good way to once and for all implement some good reference code to illustrate the actual magnitude of the problem.

Support original names when encrypting files

When a file is temporarily decrypted, there may be a collision with the file name in the temporary folder, and then a ...(n) suffix is used to disambiguate. However, when this file is re-encrypted, the original name in the encrypted file should be retained instead of using the name that was generated for disambiguation.
The syntax for now is to extend the standardio naming, which already supports -:[OriginalName] and +:[OriginalName], to support [ActualFullName]-:[OriginalName] and [ActualFullName]-:[OriginalName] . This strategy may need to be modified in the future, since there is a risk of someone actually naming a file with "-:" in the name, at least on Linux/macOS. The challenge is that the only forbidden character in a file name in Linux is '/', and this makes it impossible to reliably parse a string to separate the file name part from the path-part. It should work on Windows, because a ':' should not be able to used in a conflicting name context (although there might be some case with alternate data streams where it's used on Windows...).
For now, we'll use "-:" and "+:" and handle this when/if it's reported as an actual problem somewhere.
The alternative for original name might be to just add a third optional parameter to the encryption option.

Update Microsoft.IdentityModel.JsonWebTokens to 6.32.0

Update Microsoft.AspNetCore.* to 7.0.12

Update SDK documentation

Fix crash with reading from named stdio

When using named standard io input, there's a crash due to trying to validate a path that is empty.

Consistent naming for Xecrets File Ez, Sdk, Cli etc.

The name is "Xecrets File Cli", If used in running text, the term "the CLI" may also be used or "the command line" or "the command line tool" (never "the command line interface"). It's a tool for developers, it doesn't have to be verbose and easy to understand, and it gets very cumbersome with "Xecrets File Command Line"... So Xecrets File Cli it is. But it's still "the CLI", it's just in the name that only the first letter is capitalized.

For the SDK, the name is "Xecrets File Sdk" or "Xecrets.File.Sdk", but in running text the term "the SDK" may be used. It's written "Sdk" when naming it, and "SDK" when referring to it as "a software development kit" or "the software development kit" etc.

The desktop app is named "Xecrets File Ez", but may also be referred to as "the desktop app", "the GUI" (not preferred), "the graphical user interface" etc.

Update Microsoft.AspNetCore.DataProtection

Move work folder location to sub directory

The work folder location is set to the user temp folder, but it's better to avoid collisions by having it in a XecretsFileCli-specific sub directory.

Add option for random password

Since the file format unfortunately requires a password field, even if using public key cryptography, there should be an option
to use a random password - effectively not having a password. It should only be allowed if at least one public key is used at the same time.

Allow non-email jwt subject

Microsoft.IdentityModel.JsonWebTokens to 7.0.3

Update Xecrets.Licensing to 1.0.6

Differentiate error conditions

Several completely different situations end up in CLI reporting XfStatusCode.Error. This complicates tracking down problems when they are reported via Ez, since the original stack trace is lost then. Create new distinct error codes for the various situations.

Update various nuget packages

Ignore multiple passwords on encryption, use only first

Enable json-logging on crashes during parsing

Ensure logging is configured during parsing, so even if that goes south, the caller gets json if requested.

Configure VS Code

Add SDK documentation

Ensure proper exit code is set

Overwrite flag is not correctly handled

It's set and reset only during the Dry phase. It should be set etc during the Dry phase, then restored to original default, then set in the same way again for the Real phase.

Update nuget dependencies

Display build and license times in local time

Do not crash if a .txt file is not readable when scanning for licenses

During startup of the tool, a scan is made for possible license files. This file may be locked, if so, just ignore it - don't crash. This can be caused by redirecting stdout to a .txt file when invoking the command line.

Update copyright year

Update all relevant copyright notices to Copyright © 2022-2023 etc.

Upgrade Xecrets.Licensing to 1.0.10

Fix calculation of unlicensed encryption limit

Implement import/export via ASCII armor of public keys

Break out Xecrets.File.Licensing

Fix regression bug in original name handling

Upgrade Xecrets.Licensing to 1.0.7

Bug with named stdio

There's a crash if named stdin is used.

Always include the owner email of a key file in the list of public keys to use

When an encrypted key file is successfully loaded, it contains both the private and the public key as well as the email moniker for that user. Change so that email/public key is always used when encrypting, ensuring that the file session master key is encrypted with that public key, as well as the password.

Fix problems when testing for file writeability

When testing if a file can be written to, we'll create one if it's not already there, thereby checking that we really can write to the file. However, we then delete the file unconditionally, even if it existed before. This is not right and apparently also causes problems with Norton, which will claim this as "suspicious" activity by a "file protection" "feature", and just block the delete causing a crash. Although the Norton behavior is stupid, it's nonetheless incorrect behavior to delete a file just because we're testing it for writeability.

Change to maintenance subscription, only limit for programmatic use

Change so the prebuilt binaries will work without restriction in regular command line mode, when not using options intended for programmatic use such as --json-log, --file and --environment, but using them will require a maintenance subscription - or a GPL build of course.