diff --git a/sop-java-picocli.md b/sop-java-picocli.md new file mode 100644 index 00000000..30691406 --- /dev/null +++ b/sop-java-picocli.md @@ -0,0 +1,12 @@ +# SOP-Java-Picocli + +`sop-java-picocli` implements a command line interface for SOP implementations. + +## Backend Installation +In order to enable OpenPGP operations, you need to set an implementation of [`sop-java`](sop-java.html): +```java +// static method call prior to execution of the main method +SopCLI.setSopInstance(yourSopImpl); +``` + +## Usage diff --git a/sop-java.md b/sop-java.md new file mode 100644 index 00000000..03a9c43f --- /dev/null +++ b/sop-java.md @@ -0,0 +1,54 @@ +# SOP-Java +The [Stateless OpenPGP Protocol (SOP)](https://datatracker.ietf.org/doc/draft-dkg-openpgp-stateless-cli/) specification defines a straightforward interface for common OpenPGP operations. +The Java library `sop-java` contains abstract interfaces reproducing the SOP API. This enables tight integration of OpenPGP functionality. + +The point of defining the SOP protocol as an abstract Java library is to enable consumers to decouple their application from the used OpenPGP backend. + +In the example below, replacing the backend would accomplished simply by swapping out the first line. + +## Usage Examples +```java +SOP sop = new FooSOP(); + +// Generate an OpenPGP key +// This needs to be kept secret +byte[] key = sop.generateKey() + .userId("Alice ") + .generate() + .getBytes(); + +// Extract the certificate (public key) +// This can be published and shared with others +byte[] cert = sop.extractCert() + .key(key) + .getBytes(); + +// Encrypt a message +byte[] bobsCert = ... +byte[] message = ... +byte[] encrypted = sop.encrypt() + .withCert(cert) + .withCert(bobsCert) + .signWith(key) + .plaintext(message) + .getBytes(); + +// Decrypt a message +ByteArrayAndResult messageAndVerifications = sop.decrypt() + .verifyWith(cert) + .withKey(key) + .ciphertext(encrypted) + .toByteArrayAndResult(); +byte[] decrypted = messageAndVerifications.getBytes(); + +// Signature Verifications +DecryptionResult messageInfo = messageAndVerifications.getResult(); +List signatureVerifications = messageInfo.getVerifications(); +``` + + +## Known Implementations +`PGPainless` provides an implementation of the `sop-java` library, named `pgpainless-sop`. Unsurprisingly, this library makes use of `pgpainless-core` to implement `sop-java`. + +## CLI +If you need a command line interface for your `sop-java` implementation, see [sop-java-picocli](sop-java-picocli.html). \ No newline at end of file diff --git a/sop.md b/sop.md new file mode 100644 index 00000000..ed0b9880 --- /dev/null +++ b/sop.md @@ -0,0 +1,10 @@ +# Stateless OpenPGP Protocol +The [Stateless OpenPGP Protocol (SOP)](https://datatracker.ietf.org/doc/draft-dkg-openpgp-stateless-cli/) specification defines a straightforward interface for commonly used OpenPGP operations. + +## Java API +While the aforementioned document specifies a command line interface, shelling out to a CLI is not an ideal way of incorporating functionality into an application. +A dedicated Java API is easier to consume and less error prone. + +For that reason, `sop-java` was created as a general definition of such API. `sop-java` itself does not have any dependencies on cryptographic libraries, so it is possible to + +## Command Line Application