Add more documentation

2025-09-10 18:59:39 +02:00 · 2022-07-11 16:11:40 +02:00 · 2022-07-11 16:11:40 +02:00 · df7505eadb
commit df7505eadb
parent 50d31eb463
7 changed files with 213 additions and 22 deletions
--- a/docs/source/pgpainless-core/generate_keys.md
+++ b/docs/source/pgpainless-core/generate_keys.md
@ -0,0 +1,101 @@
+# PGPainless In-Depth: Generate Keys
+
+There are two API endpoints for generating OpenPGP keys using `pgpainless-core`:
+
+`PGPainless.generateKeyRing()` presents a selection of pre-configured OpenPGP key archetypes:
+
+```java
+// Modern, EC-based OpenPGP key with dedicated primary certification key
+// This method is recommended by the authors
+PGPSecretKeyRing secretKey = PGPainless.generateKeyRing()
+        .modernKeyRing(
+                "Alice <alice@pgpainless.org>",
+                Passphrase.fromPassword("sw0rdf1sh"));
+
+// Simple, EC-based OpenPGP key with combined certification and signing key
+// plus encryption subkey
+PGPSecretKeyRing secretKey = PGPainless.generateKeyRing()
+        .simpleEcKeyRing(
+                "Alice <alice@pgpainless.org>",
+                Passphrase.fromPassword("0r4ng3"));
+
+// Simple, RSA OpenPGP key made of a single RSA key used for all operations
+PGPSecretKeyRing secretKey = PGPainless.generateKeyRing()
+        .simpleRsaKeyRing(
+                "Alice <alice@pgpainless.org>",
+                RsaLength._4096, Passphrase.fromPassword("m0nk3y")):
+```
+
+If you have special requirements on algorithms you can use `PGPainless.buildKeyRing()` instead, which offers more
+control over parameters:
+
+```java
+// Customized key
+
+// Specification for primary key
+KeySpecBuilder primaryKeySpec = KeySpec.getBuilder(
+        KeyType.RSA(RsaLength._8192),                               // 8192 bits RSA key
+        KeyFlag.CERTIFY_OTHER)                                      // used for certification
+        // optionally override algorithm preferences
+        .overridePreferredCompressionAlgorithms(CompressionAlgorithm.ZLIB)
+        .overridePreferredHashAlgorithms(HashAlgorithm.SHA512, HashAlgorithm.SHA384)
+        .overridePreferredSymmetricKeyAlgorithms(SymmetricKeyAlgorithm.AES256);
+
+// Specification for a signing subkey
+KeySpecBuilder signingSubKeySpec = KeySpec.getBuilder(
+        KeyType.ECDSA(EllipticCurve._P256),                         // P-256 ECDSA key
+        KeyFlag.SIGN_DATA);                                         // Used for signing
+
+// Specification for an encryption subkey
+KeySpecBuilder encryptionSubKeySpec = KeySpec.getBuilder(
+        KeyType.ECDH(EllipticCurve._P256),
+        KeyFlag.ENCRYPT_COMMS, KeyFlag.ENCRYPT_STORAGE);
+
+// Build the key itself
+PGPSecretKeyRing secretKey = PGPainless.buildKeyRing()
+        .setPrimaryKey(primaryKeySpec)
+        .addSubkey(signingSubKeySpec)
+        .addSubkey(encryptionSubKeySpec)
+        .addUserId("Juliet <juliet@montague.lit>")                  // Primary User-ID
+        .addUserId("xmpp:juliet@capulet.lit")                       // Additional User-ID
+        .setPassphrase(Passphrase.fromPassword("romeo_oh_Romeo<3")) // passphrase protection
+        .build();
+```
+
+To specify, which algorithm to use for a single (sub) key, `KeySpec.getBuilder(_)` can be used, passing a `KeyType`,
+as well as some `KeyFlag`s as argument.
+
+`KeyType` defines an algorithm and its parameters, e.g. RSA with a certain key size, or ECDH over a certain
+elliptic curve.
+Currently, PGPainless supports the following `KeyType`s:
+* `KeyType.RSA(_)`: Signing, Certification, Encryption
+* `KeyType.ECDH(_)`: Encryption
+* `KeyType.ECDSA(_)`: Signing, Certification
+* `KeyType.EDDSA(_)`: Signing, Certification
+* `KeyType.XDH(_)`: Encryption
+
+The `KeyFlag`s are used to specify, how the key will be used later on. A signing key can only be used for signing,
+if it carries the `KeyFlag.SIGN_DATA`.
+A key can carry multiple key flags.
+
+It is possible to override the default algorithm preferences used by PGPainless with custom preferences.
+An algorithm preference list contains algorithms from most to least preferred.
+
+Every OpenPGP key MUST have a primary key. The primary key MUST be capable of certification, so you MUST use an
+algorithm that can be used to generate signatures.
+The primary key can be set by calling `setPrimaryKey(primaryKeySpec)`.
+
+Furthermore, an OpenPGP key can contain zero or more subkeys.
+Those can be set by repeatedly calling `addSubkey(subkeySpec)`.
+
+OpenPGP keys are usually bound to User-IDs like names and/or email addresses.
+There can be multiple user-ids bound to a key, in which case the very first User-ID will be marked as primary.
+To add a User-ID to the key, call `addUserId(userId)`.
+
+By default, keys do not have an expiration date. This can be changed by setting an expiration date using
+`setExpirationDate(date)`.
+
+To enable password protection for the OpenPGP key, you can call `setPassphrase(passphrase)`.
+If this method is not called, or if the passed in `Passphrase` is empty, the key will be unprotected.
+
+Finally, calling `build()` will generate a fresh OpenPGP key according to the specifications given.