chore: API docs website and release-ready docs (#21)

Author: sander

.github/workflows/integration.yml

@@ -15,6 +15,12 @@ jobs:
       - uses: "docker://ghcr.io/sethvargo/ratchet@sha256:81af1075dc4ceb54f1c87ac9ff6a9ebe43626c59913f01810f5be77f4eb67301" # ratchet:docker://ghcr.io/sethvargo/ratchet:0.4.0
         with:
           args: "check .github/workflows/codeql.yml"
+      - uses: "docker://ghcr.io/sethvargo/ratchet@sha256:81af1075dc4ceb54f1c87ac9ff6a9ebe43626c59913f01810f5be77f4eb67301" # ratchet:docker://ghcr.io/sethvargo/ratchet:0.4.0
+        with:
+          args: "check .github/workflows/release.yml"
+      - uses: "docker://ghcr.io/sethvargo/ratchet@sha256:81af1075dc4ceb54f1c87ac9ff6a9ebe43626c59913f01810f5be77f4eb67301" # ratchet:docker://ghcr.io/sethvargo/ratchet:0.4.0
+        with:
+          args: "check .github/workflows/pages.yml"
   build:
     runs-on: ubuntu-latest
     steps:

.github/workflows/pages.yml

@@ -0,0 +1,33 @@
+name: Pages
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+concurrency:
+  group: pages
+  cancel-in-progress: false
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@c85c95e3d7251135ab7dc9ce3241c5835cc595a9 # ratchet:actions/checkout@v3
+      - uses: actions/setup-java@5ffc13f4174014e2d4d4572b3d74c3fa61aeb2c2 # ratchet:actions/setup-java@v3
+        with:
+          distribution: zulu
+          java-version: 8
+      - uses: gradle/gradle-build-action@749f47bda3e44aa060e82d7b3ef7e40d953bd629 # ratchet:gradle/gradle-build-action@v2
+      - run: ./gradlew dokkaHtml
+      - uses: actions/configure-pages@f156874f8191504dae5b037505266ed5dda6c382 # ratchet:actions/configure-pages@v3
+      - run: |
+          mkdir -p _site
+          mv build/dokka/html _site/api
+      - uses: actions/upload-pages-artifact@66b63f4a7de003f4f00cc8e9af4b83b8f2abdb96 # ratchet:actions/upload-pages-artifact@v1
+      - uses: actions/deploy-pages@ee48c7b82e077d7b8ef30b50a719e6a792a50c9a # ratchet:actions/deploy-pages@v2
+        id: deployment

README.md

@@ -1,13 +1,12 @@
 # Noise for Kotlin
 
-[![Maven Central](https://maven-badges.herokuapp.com/maven-central/nl.sanderdijkhuis/noise-kotlin/badge.svg?style=flat-square&gav=true)](https://maven-badges.herokuapp.com/maven-central/nl.sanderdijkhuis/noise-kotlin)
+[![Maven Central](https://maven-badges.herokuapp.com/maven-central/nl.sanderdijkhuis/noise-kotlin/badge.svg?style=flat-square&gav=true)](https://central.sonatype.com/artifact/nl.sanderdijkhuis/noise-kotlin/)
 
-**Noise for Kotlin** contains example code for implementing [Noise](https://noiseprotocol.org) protocols based on Diffie-Hellman key agreement. It may evolve into a usable library. [Contact me](mailto:mail@sanderdijkhuis.nl) if you are interested in helping out to realize this.
+**Noise for Kotlin** enables implementation of [Noise](https://noiseprotocol.org) protocols based on Diffie-Hellman key agreement.
 
-> **Warning**: Some reasons why you **may not** use any of this code in production yet:
->
-> - It has not yet been reviewed for secure engineering practices.
-> - It leaves your secrets on the heap, up for grabs.
+## API documentation
+
+See the [API docs](https://sander.github.io/noise-kotlin/api/) about the latest release or use the Gradle `dokkaHtml` task for a local copy about any version.
 
 ## How to build
 
@@ -36,7 +35,9 @@ Then, implement [`Cryptography`](src/main/kotlin/cryptography/Cryptography.kt) f
 - Support only Curve25519, ChaCha20-Poly1305, and SHA-256 to reduce the need to choose and since these are available on most platforms.
     - Consequence: it should be easy to use with [Kotlin Multiplatform](https://kotlinlang.org/docs/multiplatform.html).
 - Use only Kotlin types and functions, and nothing directly from Java SE or libraries.
-    - Consequence: all dangerous cryptography implementation is behind an interface, which users need to implement using native platform functions.
+    - Consequence: all cryptographic function dependency implementation is behind an interface, which users need to implement using native platform functions.
+- Do not include particular masking, encryption, or zeroization functionality for sensitive data, to avoid disproportional complexity.
+    - Consequence: run with sufficiently protected volatile memory and protect heap dump data from unauthorized access.
 
 ## Test vectors
 

SECURITY.md

@@ -1,10 +1,8 @@
 # Security policy
 
-> **Warning**: Do not use this code in production. Expect vulnerabilities. See the [README](README.md) for details.
-
 ## Supported versions
 
-Currently only pre-release and snapshot versions are available. Any vulnerability should be mitigated in a next pre-release version.
+Currently only the latest (pre-)release version is maintained. Any vulnerability should be mitigated in a next pre-release version.
 
 ## Reporting a vulnerability
 

build.gradle.kts

@@ -1,3 +1,5 @@
+import java.net.URL
+import org.jetbrains.dokka.gradle.DokkaTask
 import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
 
 plugins {
@@ -7,6 +9,7 @@ plugins {
     `maven-publish`
     signing
     id("io.github.gradle-nexus.publish-plugin") version "1.3.0"
+    id("org.jetbrains.dokka") version "1.8.20"
 }
 
 group = "nl.sanderdijkhuis"
@@ -42,6 +45,21 @@ tasks.test {
     useJUnitPlatform()
 }
 
+tasks.withType<DokkaTask> {
+    dokkaSourceSets {
+        named("main") {
+            moduleName.set("Noise for Kotlin")
+            includes.from("src/main/README.md")
+            skipDeprecated.set(true)
+            sourceLink {
+                localDirectory.set(file("src/main/kotlin"))
+                remoteUrl.set(URL("https://github.com/sander/noise-kotlin/tree/main/src/main/kotlin"))
+                remoteLineSuffix.set("#L")
+            }
+        }
+    }
+}
+
 tasks.withType<KotlinCompile> {
     kotlinOptions.allWarningsAsErrors = true
     kotlinOptions.jvmTarget = "1.8"

src/main/README.md

@@ -0,0 +1,31 @@
+# Module Noise for Kotlin
+
+A library for implementing [Noise](https://noiseprotocol.org) protocols based on Diffie-Hellman key agreement.
+
+To get started, implement the cryptography dependencies and initialize a Noise handshake. 
+
+# Package nl.sanderdijkhuis.noise
+
+Provides Noise Protocol Framework implementation.
+
+# Package nl.sanderdijkhuis.noise.data
+
+Provides management of generic bounded binary data and state.
+
+All data is handled as immutable.
+
+No particular masking, encryption, or zeroization of sensitive data is implemented. The module assumes that the runtime environment’s volatile memory is sufficiently protected and that only trusted roles can access heap dump data.
+
+# Package nl.sanderdijkhuis.noise.cryptography
+
+Provides means to implement and apply cryptographic function dependencies.
+
+The module depends on the following cryptographic functions:
+
+- ChaCha20-Poly1305 Authenticated Encryption with Associated Data (AEAD) from [RFC 8439](https://www.rfc-editor.org/rfc/rfc8439.html)
+- SHA-256 hashing from [FIPS 180-4](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf)
+- X25519 Diffie-Hellman exchange from [RFC 7748](https://www.rfc-editor.org/rfc/rfc7748)
+
+These can be implemented using for example Java SE 11 or [Bouncy Castle](https://www.bouncycastle.org/java.html).
+
+Note that in some cases we speak of “no-op encryption”. This is to meet the `EncryptWithAd` and `DecryptWithAd` [Noise specification](https://noiseprotocol.org/noise.html#the-cipherstate-object) which provide the identity function when no cipher key is set.

src/main/kotlin/Cipher.kt

@@ -3,6 +3,7 @@ package nl.sanderdijkhuis.noise
 import nl.sanderdijkhuis.noise.cryptography.*
 import nl.sanderdijkhuis.noise.data.State
 
+/** Encompasses all Noise protocol cipher state required to encrypt and decrypt data. */
 data class Cipher(val cryptography: Cryptography, val key: CipherKey? = null, val nonce: Nonce = Nonce.zero) {
 
     fun encrypt(associatedData: AssociatedData, plaintext: Plaintext): State<Cipher, Ciphertext> =
@@ -18,4 +19,4 @@ data class Cipher(val cryptography: Cryptography, val key: CipherKey? = null, va
                 cryptography.decrypt(it, nonce, associatedData, ciphertext)?.let { p -> State(copy(nonce = n), p) }
             } ?: State(this, ciphertext.plaintext)
         }
-}
+}

src/main/kotlin/Handshake.kt

@@ -8,6 +8,16 @@ import nl.sanderdijkhuis.noise.data.Data
 import nl.sanderdijkhuis.noise.data.Size
 import nl.sanderdijkhuis.noise.data.State
 
+/**
+ * Encompasses all Noise protocol handshake state required to read and write messages.
+ *
+ * Start with [initialize], supplying one of the implemented patterns:
+ *
+ * - [Noise_NK_25519_ChaChaPoly_SHA256]
+ * - [Noise_XN_25519_ChaChaPoly_SHA256]
+ *
+ * Proposals to add more patterns or generate correct patterns dynamically are welcomed.
+ */
 data class Handshake(
     val role: Role,
     val symmetry: Symmetry,
@@ -19,12 +29,14 @@ data class Handshake(
     val trustedStaticKeys: Set<PublicKey> = emptySet()
 ) : MessageType {
 
+    /** A handshake pattern. */
     data class Pattern(
         val name: String,
         val preSharedMessagePatterns: List<List<Token>>,
         val messagePatterns: List<List<Token>>
     )
 
+    /** Message pattern token, indicating which keys are sent and which key agreements are performed. */
     enum class Token {
         E, S, EE, ES, SE, SS
     }
@@ -37,6 +49,7 @@ data class Handshake(
     private fun State<Handshake, Data>.append(f: (Symmetry) -> State<Symmetry, Data>?) =
         f(value.symmetry)?.let { s -> State(value.copy(symmetry = s.value), result + s.result) }
 
+    /** Returns a handshake message only if this is appropriate given the pattern and state. */
     fun writeMessage(payload: Payload): State<out MessageType, Data>? =
         messagePatterns.first().fold(State(this, Data.empty) as State<Handshake, Data>?) { state, token ->
             state?.let { s ->
@@ -64,6 +77,7 @@ data class Handshake(
                 else State(s.value.copy(messagePatterns = rest), s.result)
             }
 
+    /** Returns a handshake message payload only if this is appropriate given the pattern and state. */
     fun readMessage(data: Data): State<out MessageType, Payload>? =
         messagePatterns.first().fold(State(this, data) as State<Handshake, Data>?) { state, token ->
             state?.let { s ->
@@ -108,6 +122,7 @@ data class Handshake(
 
     companion object {
 
+        /** Returns initial handshake state only if sufficient keys are provided. */
         fun initialize(
             cryptography: Cryptography,
             pattern: Pattern,

src/main/kotlin/Payload.kt

@@ -2,5 +2,6 @@ package nl.sanderdijkhuis.noise
 
 import nl.sanderdijkhuis.noise.data.Data
 
+/** Plaintext handshake payload. */
 @JvmInline
 value class Payload(val data: Data)

src/main/kotlin/Role.kt

@@ -1,5 +1,6 @@
 package nl.sanderdijkhuis.noise
 
+/** The role of the user holding the handshake state. The initiator is the one who sends the first message. */
 enum class Role {
     INITIATOR, RESPONDER
 }