diff --git a/README.md b/README.md new file mode 100644 index 0000000..0559d83 --- /dev/null +++ b/README.md @@ -0,0 +1,88 @@ +# Stateless OpenPGP Protocol Implementation using Bouncy Castle + +This repository contains an implementation of the [Stateless OpenPGP Protocol](https://datatracker.ietf.org/doc/draft-dkg-openpgp-stateless-cli/) +using [sop-java](https://github.com/pgpainless/sop-java) and [Bouncy Castle](https://www.bouncycastle.org/). + +There are two modules in this repository: +* [bc-sop-api] contains a high-level JAVA API of the SOP protocol using Bouncy Castle +* [bc-sop-cli] contains a CLI app implementing the SOP protocol following the spec. + +# Build + +Currently, this build depends on an open development branch of Bouncy Castle, which can be found in an external repository [here](https://github.com/pgpainless/bc-java/tree/valiadateAPI). +To make this code available to bcsop, you need to clone the repository and locally install the custom BC build: + +```bash +git clone git@github.com:pgpainless/bc-java.git +cd bc-java +git checkout valiadateAPI +gradle publishToMavenLocal +``` + +In order to build the GraalVM native-image of the CLI app, you need to have graalvm 21.0.5 installed and `GRAALVM_HOME` pointing to it. +The easiest way to accomplish this is using [sdkman](https://sdkman.io). + +Afterwards, you can navigate to your clone of this repository and build the CLI app as a GraalVM native-image using this command: +```bash +mvn clean install -Dmaven.test.skip +``` + +The CLI binary can then be found as `bc-sop-cli/target/bcsop`. + +``` +$ ./bcsop help +Stateless OpenPGP Protocol +Usage: bcsop [--stacktrace] [COMMAND] + +Options: + --stacktrace Print stacktrace + +Commands: + version Display version information about the tool + list-profiles Emit a list of profiles supported by the identified + subcommand + generate-key Generate a secret key + change-key-password Update the password of a key + revoke-key Generate revocation certificates + extract-cert Extract a public key certificate from a secret key + sign Create a detached message signature + verify Verify a detached signature + encrypt Encrypt a message from standard input + decrypt Decrypt a message + inline-detach Split signatures from a clearsigned message + inline-sign Create an inline-signed message + inline-verify Verify an inline-signed message + armor Add ASCII Armor to standard input + dearmor Remove ASCII Armor from standard input + help Stateless OpenPGP Protocol + +Exit Codes: + 0 Successful program execution + 1 Generic program error + 3 Verification requested but no verifiable signature found + 13 Unsupported asymmetric algorithm + 17 Certificate is not encryption capable + 19 Usage error: Missing argument + 23 Incomplete verification instructions + 29 Unable to decrypt + 31 Password is not human-readable + 37 Unsupported Option + 41 Invalid data or data of wrong type encountered + 53 Non-text input received where text was expected + 59 Output file already exists + 61 Input file does not exist + 67 Cannot unlock password protected secret key + 69 Unsupported subcommand + 71 Unsupported special prefix (e.g. "@ENV/@FD") of indirect parameter + 73 Ambiguous input (a filename matching the designator already exists) + 79 Key is not signing capable + 83 Options were supplied that are incompatible with each other + 89 The requested profile is unsupported, or the indicated subcommand does + not accept profiles + 97 The implementation supports some form of hardware-backed secret keys, + but could not identify the hardware device + 101 The implementation tried to use a hardware-backed secret key, but the + cryptographic hardware refused the operation for some reason other + than a bad PIN or password +Powered by picocli +```