diff --git a/pgpainless-cli/README.md b/pgpainless-cli/README.md index f6bb6999..4c014871 100644 --- a/pgpainless-cli/README.md +++ b/pgpainless-cli/README.md @@ -1,15 +1,24 @@ -# PGPainless-SOP +# PGPainless-CLI -PGPainless-SOP is an implementation of the [Stateless OpenPGP Command Line Interface](https://tools.ietf.org/html/draft-dkg-openpgp-stateless-cli-01) specification based on PGPainless. +PGPainless-CLI is an implementation of the [Stateless OpenPGP Command Line Interface](https://tools.ietf.org/html/draft-dkg-openpgp-stateless-cli-01) specification based on PGPainless. + +It plugs `pgpainless-sop` into `sop-java-picocli`. ## Build To build an executable, `gradle jar` should be sufficient. The resulting jar file can be found in `pgpainless-sop/build/libs/`. ## Execute -Alternatively you can use the provided `./pgpainless-cli` script to execute PGPainless' Stateless Command Line Interface from within Gradle. +The jar file produced in the step above is executable as is. + +``` +java -jar pgpainless-cli-XXX.jar help +``` + +Alternatively you can use the provided `./pgpainless-cli` script to directly build and execute PGPainless' Stateless Command Line Interface from within Gradle. To discover all available commands use + ``` ./pgpainless-cli help ``` diff --git a/pgpainless-core/README.md b/pgpainless-core/README.md new file mode 100644 index 00000000..33ae850c --- /dev/null +++ b/pgpainless-core/README.md @@ -0,0 +1,3 @@ +# PGPainless-Core + +Wrapper around Bouncycastle's OpenPGP implementation. \ No newline at end of file diff --git a/pgpainless-sop/README.md b/pgpainless-sop/README.md new file mode 100644 index 00000000..6f7e0984 --- /dev/null +++ b/pgpainless-sop/README.md @@ -0,0 +1,6 @@ +# PGPainless-SOP + +Implementation of the Stateless OpenPGP Protocol using PGPainless. + +This module implements `sop-java` using `pgpainless-core`. +If your code depends on `sop-java`, this module can be used as a realization of those interfaces. \ No newline at end of file diff --git a/sop-java-picocli/README.md b/sop-java-picocli/README.md new file mode 100644 index 00000000..1a8f5e04 --- /dev/null +++ b/sop-java-picocli/README.md @@ -0,0 +1,29 @@ +# SOP-Java-Picocli + +Implementation of the [Stateless OpenPGP Command Line Interface](https://tools.ietf.org/html/draft-dkg-openpgp-stateless-cli-01) specification. +This terminal application allows generation of OpenPGP keys, extraction of public key certificates, +armoring and de-armoring of data, as well as - of course - encryption/decryption of messages and creation/verification of signatures. + +## Install a SOP backend + +This module comes without a SOP backend, so in order to function you need to extend it with an implementation of the interfaces defined in `sop-java`. +An implementation using PGPainless can be found in the module `pgpainless-sop`, but it is of course possible to provide your +own implementation. + +Just install your SOP backend by calling +```java +// static method call prior to execution of the main method +SopCLI.setSopInstance(yourSopImpl); +``` + +## Usage + +To get an overview of available commands of the application, execute +```shell +java -jar sop-java-picocli-XXX.jar help +``` + +If you just want to get started encrypting messages, see the module `pgpainless-cli` which initializes +`sop-java-picocli` with `pgpainless-sop`, so you can get started right away without the need to manually wire stuff up. + +Enjoy! \ No newline at end of file diff --git a/sop-java/README.md b/sop-java/README.md new file mode 100644 index 00000000..e355b086 --- /dev/null +++ b/sop-java/README.md @@ -0,0 +1,27 @@ +# SOP-Java + +Stateless OpenPGP Protocol for Java. + +This module contains interfaces that model the API described by the +[Stateless OpenPGP Command Line Interface](https://datatracker.ietf.org/doc/draft-dkg-openpgp-stateless-cli/) specification. + +This module is not a command line application! For that, see `sop-java-picocli`. + +## Why should I use this? + +If you need to use OpenPGP functionality like encrypting/decrypting messages, or creating/verifying +signatures inside your application, you probably don't want to start from scratch and instead reuse some library. + +Instead of locking yourselves in by depending hard on that one library, you can simply depend on the interfaces from +`sop-java` and plug in a library (such as `pgpainless-sop`) that implements said interfaces. + +That way you don't make yourself dependent from a single OpenPGP library and stay flexible. +Should another library emerge, that better suits your needs (and implements `sop-java`), you can easily switch +by swapping out the dependency with minimal changes to your code. + +## Why should I *implement* this? + +Did you create an [OpenPGP](https://datatracker.ietf.org/doc/html/rfc4880) implementation that can be used in the Java ecosystem? +By implementing the `sop-java` interface, you can turn your library into a command line interface (see `sop-java-picocli`). +This allows you to plug your library into the [OpenPGP interoperability test suite](https://tests.sequoia-pgp.org/) +of the [Sequoia-PGP](https://sequoia-pgp.org/) project. \ No newline at end of file