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 # 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. Implementation of the Stateless OpenPGP Protocol using PGPainless.
This module implements `sop-java` using `pgpainless-core`. 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 # 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. Stateless OpenPGP Protocol for Java.
This module contains interfaces that model the API described by the 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`. 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? ## Why should I use this?
If you need to use OpenPGP functionality like encrypting/decrypting messages, or creating/verifying 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? 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`). 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/) 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.