Fix mermaid-cli cmd

.gitignore

@@ -32,4 +32,4 @@ pgpainless-core/.settings/
 
 push_html.sh
 
-docs/node_modules
+node_modules

.readthedocs.yaml

@@ -8,12 +8,22 @@ version: 2
 # Set the version of Python and other tools you might need
 build:
   os: ubuntu-20.04
+  # apt_packages:
+    # - libgtk-3-0
+    # - libasound2
+    # - libnss3
+    # - libxss1
+    # - libgbm1
+    # - libxshmfence1
   tools:
     python: "3.9"
     # You can also specify other tool versions:
-    nodejs: "16"
+    # nodejs: "16"
     # rust: "1.55"
     # golang: "1.17"
+  # jobs:
+    # post_install:
+      # - npm install -g @mermaid-js/mermaid-cli
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:

.reuse/dep5

@@ -9,6 +9,15 @@ Source: https://pgpainless.org
 # Copyright: $YEAR $NAME <$CONTACT>
 # License: ...
 
+# Documentation
+Files: docs/*
+Copyright: 2022 Paul Schaub <info@pgpainless.org>
+License: CC-BY-3.0
+
+Files: .readthedocs.yaml
+Copyright: 2022 Paul Schaub <info@pgpainless.org>
+License: CC0-1.0
+
 # Gradle build tool
 Files: gradle*
 Copyright: 2015 the original author or authors.

docs/package.json

@@ -1,5 +0,0 @@
-{
-  "dependencies": {
-    "@mermaid-js/mermaid-cli": "^9.1.3"
-  }
-}

docs/source/conf.py

@@ -48,7 +48,6 @@ html_theme = 'sphinx_rtd_theme'
 #epub_show_urls = 'footnote'
 latex_show_urls = 'footnote'
 
-mermaid_cmd = "./node_modules/.bin/mmdc"
 # 'raw' does not work for epub and pdf, neither does 'svg'
 mermaid_output_format = 'png'
-mermaid_params = ['--theme', 'default', '--width', '800', '--backgroundColor', 'transparent']
+mermaid_params = ['--theme', 'default', '--width', '1600', '--backgroundColor', 'transparent']

docs/source/ecosystem.md

@@ -4,44 +4,11 @@ PGPainless consists of an ecosystem of different libraries and projects.
 
 The diagram below shows, how the different projects relate to one another.
 
-```{mermaid}
-flowchart LR
-    subgraph SOP-JAVA
-    sop-java-picocli-->sop-java
-    end
-    subgraph PGPAINLESS
-    pgpainless-sop-->pgpainless-core
-    pgpainless-sop-->sop-java
-    pgpainless-cli-->pgpainless-sop
-    pgpainless-cli-->sop-java-picocli
-    end
-    subgraph WKD-JAVA
-    wkd-java-cli-->wkd-java
-    wkd-test-suite-->wkd-java
-    wkd-test-suite-->pgpainless-core
-    end
-    subgraph CERT-D-JAVA
-    pgp-cert-d-java-->pgp-certificate-store
-    pgp-cert-d-java-jdbc-sqlite-lookup-->pgp-cert-d-java
-    end
-    subgraph CERT-D-PGPAINLESS
-    pgpainless-cert-d-->pgpainless-core
-    pgpainless-cert-d-->pgp-cert-d-java
-    pgpainless-cert-d-cli-->pgpainless-cert-d
-    pgpainless-cert-d-cli-->pgp-cert-d-java-jdbc-sqlite-lookup
-    end
-    subgraph VKS-JAVA
-    vks-java-cli-->vks-java
-    end
-    subgraph PGPEASY
-    pgpeasy-->pgpainless-cli
-    pgpeasy-->wkd-java-cli
-    pgpeasy-->vks-java-cli
-    pgpeasy-->pgpainless-cert-d-cli
-    end
-    wkd-java-cli-->pgpainless-cert-d
-    wkd-java-->pgp-certificate-store
+![Ecosystem](ecosystem_dia.*)
+<!--
+```{include} ecosystem_dia.md
 ```
+-->
 
 ## Libraries and Tools
 

docs/source/ecosystem_dia.md

@@ -0,0 +1,38 @@
+```mermaid
+flowchart LR
+    subgraph SOP-JAVA
+    sop-java-picocli-->sop-java
+    end
+    subgraph PGPAINLESS
+    pgpainless-sop-->pgpainless-core
+    pgpainless-sop-->sop-java
+    pgpainless-cli-->pgpainless-sop
+    pgpainless-cli-->sop-java-picocli
+    end
+    subgraph WKD-JAVA
+    wkd-java-cli-->wkd-java
+    wkd-test-suite-->wkd-java
+    wkd-test-suite-->pgpainless-core
+    end
+    subgraph CERT-D-JAVA
+    pgp-cert-d-java-->pgp-certificate-store
+    pgp-cert-d-java-jdbc-sqlite-lookup-->pgp-cert-d-java
+    end
+    subgraph CERT-D-PGPAINLESS
+    pgpainless-cert-d-->pgpainless-core
+    pgpainless-cert-d-->pgp-cert-d-java
+    pgpainless-cert-d-cli-->pgpainless-cert-d
+    pgpainless-cert-d-cli-->pgp-cert-d-java-jdbc-sqlite-lookup
+    end
+    subgraph VKS-JAVA
+    vks-java-cli-->vks-java
+    end
+    subgraph PGPEASY
+    pgpeasy-->pgpainless-cli
+    pgpeasy-->wkd-java-cli
+    pgpeasy-->vks-java-cli
+    pgpeasy-->pgpainless-cert-d-cli
+    end
+    wkd-java-cli-->pgpainless-cert-d
+    wkd-java-->pgp-certificate-store
+```

docs/source/index.rst

@@ -20,6 +20,6 @@ Contents
 
 .. toctree::
 
-   quickstart.md
    ecosystem.md
+   quickstart.md
    sop.md

docs/source/pgpainless-core/quickstart.md

@@ -2,6 +2,10 @@
 
 Coming soon.
 
+:::{note}
+This chapter is work in progress.
+:::
+
 ### Setup
 bla
 

docs/source/pgpainless-sop/quickstart.md

@@ -35,7 +35,7 @@ dependencies {
 ```
 
 :::{important}
-Replace `XYZ` with the current version, e.g. {{ env.config.version }}!
+Replace `XYZ` with the current version, in this case {{ env.config.version }}!
 :::
 
 The entry point to the API is the `SOP` interface, for which `pgpainless-sop` provides a concrete implementation
@@ -366,4 +366,101 @@ prior to calling `data(_)`.
 
 The `SigningResult` object you got back in both cases contains information about the signature.
 
-### Verify a Signature
+### Verify a Signature
+
+In order to verify signed messages, there are two API endpoints available.
+
+#### Inline and Cleartext Signatures
+
+To verify inline-signed messages, or messages that make use of the cleartext signature framework,
+use the `inlineVerify()` API:
+
+```java
+byte[] signingCert = ...;
+byte[] signedMessage = ...;
+
+ReadyWithResult<List<Verification>> readyWithResult = sop.inlineVerify()
+        .cert(signingCert)
+        .data(signedMessage);
+```
+
+The `cert(_)` method MUST be called at least once. It takes either a byte array or an `InputStream` containing
+an OpenPGP certificate.
+If you are not sure, which certificate was used to sign the message, you can provide multiple certificates.
+
+It is also possible to reject signatures that were not made within a certain time window by calling
+`notBefore(Date timestamp)` and/or `notAfter(Date timestamp)`.
+Signatures made before the `notBefore(_)` or after the `notAfter(_)` constraints will be rejected.
+
+You can now either write out the plaintext message to an `OutputStream`...
+
+```java
+OutputStream out = ...;
+List<Verifications> verifications = readyWithResult.writeTo(out);
+```
+
+... or you can acquire the plaintext message as a byte array directly:
+
+```java
+ByteArrayAndResult<List<Verifications>> bytesAndResult = readyWithResult.toByteArrayAndResult();
+byte[] plaintextMessage = bytesAndResult.getBytes();
+List<Verifications> verifications = bytesAndResult.getResult();
+```
+
+In both cases, the plaintext message will have the signatures stripped.
+
+#### Detached Signatures
+
+To verify detached signatures (signatures that come separate from the message itself), you can use the
+`detachedVerify()` API:
+
+```java
+byte[] signingCert = ...;
+byte[] message = ...;
+byte[] detachedSignature = ...;
+
+List<Verification> verifications = sop.detachedVerify()
+        .cert(signingCert)
+        .signatures(detachedSignature)
+        .data(signedMessage);
+```
+
+You can provide one or more OpenPGP certificates using `cert(_)`, providing either a byte array or an `InputStream`.
+
+The detached signatures need to be provided separately using the `signatures(_)` method call.
+You can provide as many detached signatures as you like, and those can be binary or ASCII armored.
+
+Like with Inline Signatures, you can constrain the time window for signature validity using
+`notAfter(_)` and `notBefore(_)`.
+
+#### Verifications
+
+In all above cases, the `verifications` list will contain `Verification` objects for each verifiable, valid signature.
+Those objects contain information about the signatures:
+`verification.getSigningCertFingerprint()` will return the fingerprint of the certificate that created the signature.
+`verification.getSigningKeyFingerprint()` will return the fingerprint of the used signing subkey within that certificate.
+
+### Detach Signatures from Messages
+
+It is also possible, to detach inline or cleartext signatures from signed messages to transform them into
+detached signatures.
+The same way you can turn inline or cleartext signed messages into plaintext messages.
+
+To detach signatures from messages, use the `inlineDetach()` API:
+
+```java
+byte[] signedMessage = ...;
+
+ReadyWithResult<Signatures> readyWithResult = sop.inlineDetach()
+        .message(signedMessage);
+ByteArrayAndResult<Signatures> bytesAndResult = readyWithResult.toByteArrayAndResult();
+
+byte[] plaintext = bytesAndResult.getBytes();
+Signatures signatures = bytesAndResult.getResult();
+byte[] encodedSignatures = signatures.getBytes();
+```
+
+By default, the signatures output will be ASCII armored. This can be disabled by calling `noArmor()`
+prior to `message(_)`.
+
+The detached signatures can now be verified like in the section above.

docs/source/sop.md

@@ -1,3 +1,10 @@
 # Stateless OpenPGP Protocol (SOP)
 
-Lorem ipsum dolor sit amet.
+The [Stateless OpenPGP Protocol](https://datatracker.ietf.org/doc/draft-dkg-openpgp-stateless-cli/)
+(short *SOP*) is a specification of a standardized command line interface for a limited set of OpenPGP operations.
+
+By standardizing the interface, users are able to choose between different, compatible implementations.
+
+:::{note}
+This chapter is work in progress.
+:::