Extend sphinx documentation
This commit is contained in:
parent
3842aa9ced
commit
a131fe32aa
GPG Key ID:
62BEE9264BF17311
|
|
@ -15,7 +15,10 @@ release = latest_tag
|
|||
version = release
|
||||
|
||||
myst_substitutions = {
|
||||
"repo_host" : "codeberg.org" # or 'github.com'
|
||||
"repo_host" : "codeberg.org", # or 'github.com'
|
||||
# "repo_host" : "github.com",
|
||||
"repo_pgpainless_src" : "codeberg.org/pgpainless/pgpainless/src/branch",
|
||||
# "repo_pgpainless_src" : "github.com/pgpainless/pgpainless/tree",
|
||||
}
|
||||
|
||||
# -- General configuration
|
||||
|
|
|
|||
|
|
@ -1,31 +1,125 @@
|
|||
## PGPainless API with pgpainless-core
|
||||
|
||||
Coming soon.
|
||||
The `pgpainless-core` module contains the bulk of the actual OpenPGP implementation.
|
||||
|
||||
:::{note}
|
||||
This chapter is work in progress.
|
||||
:::
|
||||
|
||||
### Setup
|
||||
bla
|
||||
|
||||
PGPainless' releases are published to and can be fetched from Maven Central.
|
||||
To get started, you first need to include `pgpainless-core` in your projects build script:
|
||||
|
||||
```
|
||||
// If you use Gradle
|
||||
...
|
||||
dependencies {
|
||||
...
|
||||
implementation "org.pgpainless:pgpainless-core:XYZ"
|
||||
...
|
||||
}
|
||||
|
||||
// If you use Maven
|
||||
...
|
||||
<dependencies>
|
||||
...
|
||||
<dependency>
|
||||
<groupId>org.pgpainless</groupId>
|
||||
<artifactId>pgpainless-core</artifactId>
|
||||
<version>XYZ</version>
|
||||
</dependency>
|
||||
...
|
||||
</dependencies>
|
||||
```
|
||||
|
||||
This will automatically pull in PGPainless' dependencies, such as Bouncy Castle.
|
||||
|
||||
:::{important}
|
||||
Replace `XYZ` with the current version, in this case {{ env.config.version }}!
|
||||
:::
|
||||
|
||||
The entry point to the API is the `PGPainless` class.
|
||||
For many common use-cases, examples can be found in the
|
||||
{{ '[examples package](https://{}/main/pgpainless-core/src/test/java/org/pgpainless/example)'.format(repo_pgpainless_src) }}.
|
||||
There is a very good chance that you can find code examples there that fit your needs.
|
||||
|
||||
### Read and Write Keys
|
||||
Reading keys from ASCII armored strings or from binary files is easy:
|
||||
|
||||
```java
|
||||
String key = "-----BEGIN PGP PRIVATE KEY BLOCK-----\n"...;
|
||||
PGPSecretKeyRing secretKey = PGPainless.readKeyRing()
|
||||
.secretKeyRing(key);
|
||||
```
|
||||
|
||||
Similarly, keys or certificates can quickly be exported:
|
||||
|
||||
```java
|
||||
// ASCII armored key
|
||||
PGPSecretKeyRing secretKey = ...;
|
||||
String armored = PGPainless.asciiArmor(secretKey);
|
||||
|
||||
// binary (unarmored) key
|
||||
byte[] binary = secretKey.getEncoded();
|
||||
```
|
||||
|
||||
### Generate a Key
|
||||
bla
|
||||
PGPainless comes with a simple to use `KeyRingBuilder` class that helps you to quickly generate modern OpenPGP keys.
|
||||
There are some predefined key archetypes, but it is possible to fully customize the key generation to fit your needs.
|
||||
|
||||
```java
|
||||
// EdDSA primary key with EdDSA signing- and XDH encryption subkeys
|
||||
PGPSecretKeyRing secretKeys = PGPainless.generateKeyRing()
|
||||
.modernKeyRing("Romeo <romeo@montague.lit>", "thisIsAPassword");
|
||||
|
||||
// RSA key without additional subkeys
|
||||
PGPSecretKeyRing secretKeys = PGPainless.generateKeyRing()
|
||||
.simpleRsaKeyRing("Juliet <juliet@montague.lit>", RsaLength._4096);
|
||||
```
|
||||
|
||||
To generate a customized key, use `PGPainless.buildKeyRing()` instead:
|
||||
|
||||
```java
|
||||
// Customized key
|
||||
PGPSecretKeyRing keyRing = PGPainless.buildKeyRing()
|
||||
.setPrimaryKey(KeySpec.getBuilder(
|
||||
RSA.withLength(RsaLength._8192),
|
||||
KeyFlag.SIGN_DATA, KeyFlag.CERTIFY_OTHER)
|
||||
.overrideCompressionAlgorithms(CompressionAlgorithm.ZLIB)
|
||||
).addSubkey(
|
||||
KeySpec.getBuilder(ECDSA.fromCurve(EllipticCurve._P256), KeyFlag.SIGN_DATA)
|
||||
).addSubkey(
|
||||
KeySpec.getBuilder(
|
||||
ECDH.fromCurve(EllipticCurve._P256),
|
||||
KeyFlag.ENCRYPT_COMMS, KeyFlag.ENCRYPT_STORAGE)
|
||||
).addUserId("Juliet <juliet@montague.lit>")
|
||||
.addUserId("xmpp:juliet@capulet.lit")
|
||||
.setPassphrase(Passphrase.fromPassword("romeo_oh_Romeo<3"))
|
||||
.build();
|
||||
```
|
||||
|
||||
As you can see, it is possible to generate all kinds of different keys.
|
||||
|
||||
### Extract a Certificate
|
||||
bla
|
||||
If you have a secret key, you might want to extract a public key certificate from it:
|
||||
|
||||
```java
|
||||
PGPSecretKeyRing secretKey = ...;
|
||||
PGPPublicKeyRing certificate = PGPainless.extractCertificate(secretKey);
|
||||
```
|
||||
|
||||
### Apply / Remove ASCII Armor
|
||||
bla
|
||||
TODO
|
||||
|
||||
### Encrypt a Message
|
||||
bla
|
||||
TODO
|
||||
|
||||
### Decrypt a Message
|
||||
bla
|
||||
TODO
|
||||
|
||||
### Sign a Message
|
||||
bla
|
||||
TODO
|
||||
|
||||
### Verify a Signature
|
||||
bla
|
||||
TODO
|
||||
|
|
|
|||
|
|
@ -239,7 +239,7 @@ If you provided the senders certificate for the purpose of signature verificatio
|
|||
probably want to check, if the message was actually signed by the sender by checking `result.getVerifications()`.
|
||||
|
||||
:::{note}
|
||||
Signature verification will be discussed in more detail in section [](#verifications)
|
||||
Signature verification will be discussed in more detail in section "Verifications".
|
||||
:::
|
||||
|
||||
If the message was encrypted symmetrically using a password, you can also decrypt is symmetrically by calling
|
||||
|
|
|
|||
Loading…
Reference in New Issue