PGPainless/pgpainless
PGPainless
/
pgpainless
mirror of https://github.com/pgpainless/pgpainless.git
1
0
Fork 0
Code Issues Releases Wiki Activity

Add information to SOP READMEs

This commit is contained in:
Paul Schaub 2022-01-10 16:44:18 +01:00
parent 2e7a21b5b7
commit fc432901ed
2 changed files with 90 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
pgpainless-sop/README.md
View File

@ -6,7 +6,47 @@ SPDX-License-Identifier: Apache-2.0
# PGPainless-SOP
[![Spec Revision: 3](https://img.shields.io/badge/Spec%20Revision-3-blue)](https://datatracker.ietf.org/doc/html/draft-dkg-openpgp-stateless-cli-03)
[![Maven Central](https://badgen.net/maven/v/maven-central/org.pgpainless/pgpainless-sop)](https://search.maven.org/artifact/org.pgpainless/pgpainless-sop)
[![JavaDoc](https://badgen.net/badge/javadoc/yes/green)](https://pgpainless.org/releases/latest/javadoc/org/pgpainless/sop/package-summary.html)
[![REUSE status](https://api.reuse.software/badge/github.com/pgpainless/pgpainless)](https://api.reuse.software/info/github.com/pgpainless/pgpainless)
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.
If your code depends on `sop-java`, this module can be used as a realization of those interfaces.
## Usage Examples
```java
SOP sop = new SOPImpl();
// Generate an OpenPGP key
byte[] key = sop.generateKey()
.userId("Alice <alice@example.org>")
.generate()
.getBytes();
// Extract the certificate (public key)
byte[] cert = sop.extractCert()
.key(key)
.getBytes();
// Encrypt a message
byte[] message = ...
byte[] encrypted = sop.encrypt()
.withCert(cert)
.signWith(key)
.plaintext(message)
.getBytes();
// Decrypt a message
ByteArrayAndResult<DecryptionResult> messageAndVerifications = sop.decrypt()
.verifyWith(cert)
.withKey(key)
.ciphertext(encrypted)
.toByteArrayAndResult();
byte[] decrypted = messageAndVerifications.getBytes();
// Signature Verifications
DecryptionResult messageInfo = messageAndVerifications.getResult();
List<Verification> signatureVerifications = messageInfo.getVerifications();
```

51
sop-java/README.md
View File

@ -6,13 +6,60 @@ SPDX-License-Identifier: Apache-2.0
# SOP-Java
[![Spec Revision: 3](https://img.shields.io/badge/Spec%20Revision-3-blue)](https://datatracker.ietf.org/doc/html/draft-dkg-openpgp-stateless-cli-03)
[![Maven Central](https://badgen.net/maven/v/maven-central/org.pgpainless/sop-java)](https://search.maven.org/artifact/org.pgpainless/sop-java)
[![JavaDoc](https://badgen.net/badge/javadoc/yes/green)](https://pgpainless.org/releases/latest/javadoc/sop/SOP.html)
[![REUSE status](https://api.reuse.software/badge/github.com/pgpainless/pgpainless)](https://api.reuse.software/info/github.com/pgpainless/pgpainless)
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.
[Stateless OpenPGP Command Line Interface](https://datatracker.ietf.org/doc/html/draft-dkg-openpgp-stateless-cli-03) specification.
This module is not a command line application! For that, see `sop-java-picocli`.
## Usage Examples
The API defined by `sop-java` is super straight forward:
```java
SOP sop = ... // e.g. new org.pgpainless.sop.SOPImpl();
// Generate an OpenPGP key
byte[] key = sop.generateKey()
.userId("Alice <alice@example.org>")
.generate()
.getBytes();
// Extract the certificate (public key)
byte[] cert = sop.extractCert()
.key(key)
.getBytes();
// Encrypt a message
byte[] message = ...
byte[] encrypted = sop.encrypt()
.withCert(cert)
.signWith(key)
.plaintext(message)
.getBytes();
// Decrypt a message
ByteArrayAndResult<DecryptionResult> messageAndVerifications = sop.decrypt()
.verifyWith(cert)
.withKey(key)
.ciphertext(encrypted)
.toByteArrayAndResult();
byte[] decrypted = messageAndVerifications.getBytes();
// Signature Verifications
DecryptionResult messageInfo = messageAndVerifications.getResult();
List<Verification> signatureVerifications = messageInfo.getVerifications();
```
Furthermore, the API is capable of signing messages and verifying unencrypted signed data, as well as adding and removing ASCII armor.
### Limitations
As per the spec, sop-java does not (yet) deal with encrypted OpenPGP keys.
## Why should I use this?
If you need to use OpenPGP functionality like encrypting/decrypting messages, or creating/verifying
@ -30,4 +77,4 @@ by swapping out the dependency with minimal changes to your code.
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.
of the [Sequoia-PGP](https://sequoia-pgp.org/) project.