Update docs.

Author: atholbro

README.md

@@ -5,17 +5,17 @@ import kotlin.contracts.ExperimentalContracts
 import kotlin.contracts.InvocationKind
 import kotlin.contracts.contract
 
-sealed interface PasetoFooter
+sealed interface Footer
 
 @JvmInline
-value class StringFooter internal constructor(val value: String) : PasetoFooter
+value class StringFooter internal constructor(val value: String) : Footer
 
 @ConsistentCopyVisibility
 data class ClaimFooter internal constructor(
     val keyId: String?, // kid
     val wrappedKey: String?, // wpk
     val claims: ClaimObject,
-) : PasetoFooter
+) : Footer
 
 @PasetoDslMarker
 class ClaimFooterBuilder @PublishedApi internal constructor() {
@@ -54,30 +54,30 @@ inline fun footer(init: ClaimFooterBuilder.() -> Unit): ClaimFooter {
 
 /**
  * A Paseto footer extracted from a token which has not been cryptographically verified. It is therefore possible that
- * a [TaintedPasetoFooter] has been tampered with.
+ * a [TaintedFooter] has been tampered with.
  *
  * This is useful when the footer is used to carry information required to verify the key, like a key id (kid) claim.
  */
-sealed interface TaintedPasetoFooter
+sealed interface TaintedFooter
 
 @JvmInline
-value class TaintedStringFooter(val value: String) : TaintedPasetoFooter
+value class TaintedStringFooter(val value: String) : TaintedFooter
 
 @ConsistentCopyVisibility
 data class TaintedClaimFooter internal constructor(
     val keyId: String?, // kid
     val wrappedKey: String?, // wpk
     val claims: ClaimObject,
-) : TaintedPasetoFooter
+) : TaintedFooter
 
 /**
- * Converts a [PasetoFooter] to it's [TaintedPasetoFooter] variant.
+ * Converts a [Footer] to it's [TaintedFooter] variant.
  *
  * This can be used to compare an [TaintedClaimFooter] against a [ClaimFooter] built using the [footer] builder.
- * @receiver A [PasetoFooter] instance to turn taint.
- * @return A [TaintedPasetoFooter] representation of the given [PasetoFooter].
+ * @receiver A [Footer] instance to turn taint.
+ * @return A [TaintedFooter] representation of the given [Footer].
  */
-fun PasetoFooter.taint(): TaintedPasetoFooter? = when (this) {
+fun Footer.taint(): TaintedFooter = when (this) {
     is ClaimFooter -> TaintedClaimFooter(keyId, wrappedKey, claims)
     is StringFooter -> TaintedStringFooter(value)
 }

paseto/src/main/kotlin/net/aholbrook/paseto/Footer.kt

@@ -69,7 +69,7 @@ class FooterOptionsBuilder @PublishedApi internal constructor() {
     )
 }
 
-internal fun Json.encodeFooter(footerOptions: FooterOptions, footer: PasetoFooter): String {
+internal fun Json.encodeFooter(footerOptions: FooterOptions, footer: Footer): String {
     val encoded = when (footer) {
         is ClaimFooter -> encodeToString(ClaimFooterSerializer, footer)
         is StringFooter -> footer.value
@@ -79,7 +79,7 @@ internal fun Json.encodeFooter(footerOptions: FooterOptions, footer: PasetoFoote
     return encoded
 }
 
-internal fun Json.decodeFooter(footerOptions: FooterOptions, footer: String): PasetoFooter {
+internal fun Json.decodeFooter(footerOptions: FooterOptions, footer: String): Footer {
     footerOptions.validateFooter(footer)
 
     return when (footerOptions.parseMode) {

paseto/src/main/kotlin/net/aholbrook/paseto/FooterSerde.kt

@@ -18,7 +18,7 @@ data class Token internal constructor(
     val issuedAt: Instant?, // iat
     val tokenId: String?, // jti
     val claims: ClaimObject,
-    val footer: PasetoFooter,
+    val footer: Footer,
 )
 
 @PasetoDslMarker
@@ -31,7 +31,7 @@ class TokenBuilder @PublishedApi internal constructor(clock: Clock) {
     var issuedAt: Instant? = clock.instant() // iat
     var tokenId: String? = null // jti
     private var claims: ClaimObject = ClaimObject()
-    private var footer: PasetoFooter = StringFooter("")
+    private var footer: Footer = StringFooter("")
 
     @OptIn(ExperimentalContracts::class)
     fun claims(init: ClaimObjectBuilder.() -> Unit) {
@@ -46,7 +46,7 @@ class TokenBuilder @PublishedApi internal constructor(clock: Clock) {
         this.claims = claims
     }
 
-    fun footer(footer: PasetoFooter) {
+    fun footer(footer: Footer) {
         this.footer = footer
     }
 

paseto/src/main/kotlin/net/aholbrook/paseto/Token.kt

@@ -19,8 +19,8 @@ import kotlin.contracts.InvocationKind
 import kotlin.contracts.contract
 
 sealed interface Purpose {
-    class Public(val keyProvider: () -> KeyPair) : Purpose
-    class Local(val keyProvider: () -> SymmetricKey) : Purpose
+    class Public(val keyProvider: (footer: TaintedFooter) -> KeyPair) : Purpose
+    class Local(val keyProvider: (footer: TaintedFooter) -> SymmetricKey) : Purpose
 }
 
 @PasetoDslMarker
@@ -81,23 +81,23 @@ inline fun tokenService(version: Version, purpose: Purpose, init: TokenServiceBu
 
 sealed interface TokenService {
     fun encode(token: Token, implicitAssertion: String = ""): String
-    fun decode(token: String, footer: PasetoFooter? = null, implicitAssertion: String = ""): Token
+    fun decode(token: String, footer: Footer? = null, implicitAssertion: String = ""): Token
 
     /**
      * Decode the token's footer without verifying the token.
      *
-     * This is useful if the token footer contains data required to decode the token. Returns an [TaintedPasetoFooter]
+     * This is useful if the token footer contains data required to decode the token. Returns an [TaintedFooter]
      * to prevent misuse as this footer should **never** be used when checking the footer during decoding.
      *
      * @param [token] paseto token to decode the footer of.
-     * @return [TaintedPasetoFooter] with the decoded footer contents.
+     * @return [TaintedFooter] with the decoded footer contents.
      */
-    fun insecureGetFooter(token: String): TaintedPasetoFooter?
+    fun insecureGetFooter(token: String): TaintedFooter
 }
 
 internal class LocalTokenService internal constructor(
     private val paseto: Paseto,
-    private val keyProvider: () -> SymmetricKey,
+    private val keyProvider: (footer: TaintedFooter) -> SymmetricKey,
     private val rules: Rules,
     private val footerOptions: FooterOptions,
     private val json: Json = Json { explicitNulls = false },
@@ -112,20 +112,20 @@ internal class LocalTokenService internal constructor(
         val encodedFooter = json.encodeFooter(footerOptions, token.footer)
         return paseto.encrypt(
             m = encoded.toByteArray(Charsets.UTF_8),
-            key = keyProvider(),
-            footer = encodedFooter ?: "",
+            key = keyProvider(token.footer.taint()),
+            footer = encodedFooter,
             implicitAssertion = implicitAssertion,
         )
     }
 
-    override fun decode(token: String, footer: PasetoFooter?, implicitAssertion: String): Token {
+    override fun decode(token: String, footer: Footer?, implicitAssertion: String): Token {
         if (implicitAssertion.isNotEmpty() && !paseto.supportsImplicitAssertion) {
             throw ImplicitAssertionsNotSupportedException(paseto.version)
         }
 
         val (encoded, footer) = paseto.decrypt(
             token = token,
-            key = keyProvider(),
+            key = keyProvider(insecureGetFooter(token)),
             footer = footer?.let { json.encodeFooter(footerOptions, it) },
             implicitAssertion = implicitAssertion,
         )
@@ -136,13 +136,13 @@ internal class LocalTokenService internal constructor(
         return decoded
     }
 
-    override fun insecureGetFooter(token: String): TaintedPasetoFooter? =
+    override fun insecureGetFooter(token: String): TaintedFooter =
         json.decodeFooter(footerOptions, extractFooter(token)).taint()
 }
 
 internal class PublicTokenService internal constructor(
     private val paseto: Paseto,
-    private val keyProvider: () -> KeyPair,
+    private val keyProvider: (footer: TaintedFooter) -> KeyPair,
     private val rules: Rules,
     private val footerOptions: FooterOptions,
     private val json: Json = Json { explicitNulls = false },
@@ -156,27 +156,27 @@ internal class PublicTokenService internal constructor(
         rules.verifyAll(token, Rule.Mode.ENCODE)
         val encoded = json.encodeToString(PasetoTokenSerializer, token)
         val encodedFooter = json.encodeFooter(footerOptions, token.footer)
-        val keyPair = keyProvider()
+        val keyPair = keyProvider(token.footer.taint())
         if (keyPair.secretKey == null) {
             throw CannotSignWithoutSecretKey()
         }
         return paseto.sign(
             m = encoded.toByteArray(Charsets.UTF_8),
             secretKey = keyPair.secretKey,
-            footer = encodedFooter ?: "",
+            footer = encodedFooter,
             implicitAssertion = implicitAssertion,
         )
     }
 
-    override fun decode(token: String, footer: PasetoFooter?, implicitAssertion: String): Token {
+    override fun decode(token: String, footer: Footer?, implicitAssertion: String): Token {
         // TODO expand service-test-vectors for v4 with implicit assertions
         if (implicitAssertion.isNotEmpty() && !paseto.supportsImplicitAssertion) {
             throw ImplicitAssertionsNotSupportedException(paseto.version)
         }
 
         val (encoded, footer) = paseto.verify(
             token = token,
-            publicKey = keyProvider().publicKey,
+            publicKey = keyProvider(insecureGetFooter(token)).publicKey,
             footer = footer?.let { json.encodeFooter(footerOptions, it) },
             implicitAssertion = implicitAssertion,
         )
@@ -187,6 +187,6 @@ internal class PublicTokenService internal constructor(
         return decoded
     }
 
-    override fun insecureGetFooter(token: String): TaintedPasetoFooter? =
+    override fun insecureGetFooter(token: String): TaintedFooter =
         json.decodeFooter(footerOptions, extractFooter(token)).taint()
 }

paseto/src/main/kotlin/net/aholbrook/paseto/TokenService.kt

@@ -15,7 +15,7 @@ import java.nio.charset.Charset
  * @param expected The expected byte array.
  * @return true if the arrays are equal, false if not.
  */
-internal fun ByteArray.constantTimeEquals(expected: ByteArray): Boolean {
+fun ByteArray.constantTimeEquals(expected: ByteArray): Boolean {
     if (size != expected.size) {
         var result = 0
         for (i in indices) {
@@ -44,5 +44,5 @@ internal fun ByteArray.constantTimeEquals(expected: ByteArray): Boolean {
  * @param expected The expected byte array.
  * @return true if the arrays are equal, false if not.
  */
-internal fun String.constantTimeEquals(expected: String, charset: Charset = Charsets.UTF_8): Boolean =
+fun String.constantTimeEquals(expected: String, charset: Charset = Charsets.UTF_8): Boolean =
     toByteArray(charset).constantTimeEquals(expected.toByteArray(charset))

paseto/src/main/kotlin/net/aholbrook/paseto/crypto/ConstantTimeEquals.kt

@@ -33,7 +33,7 @@ class DecryptionException @InternalApi constructor(token: String) :
 open class InvalidFooterException @InternalApi constructor(msg: String, cause: Throwable? = null) :
     PasetoException(msg, cause)
 
-class GenericInvalidFooterException @InternalApi constructor(val given: String?, val expected: String) :
+class IncorrectFooterException @InternalApi constructor(val given: String?, val expected: String) :
     PasetoException("Invalid footer in token: \"$given\" expected: \"$expected\".")
 
 class FooterExceedsMaxLengthException @InternalApi constructor(val length: Int, val max: Int) :

paseto/src/main/kotlin/net/aholbrook/paseto/exception/Exceptions.kt

@@ -12,8 +12,8 @@ class KeyPurposeException @InternalApi constructor(val expected: String, val act
 class KeyVersionException @InternalApi constructor(val expected: Version, val actual: Version) :
     PasetoException("Got wrong Key version: $actual given, expected: $expected.")
 
-class KeyReuseException @InternalApi constructor() :
-    PasetoException("Key has already been used and cleared, please reload for each operation.")
+class KeyClearedException @InternalApi constructor() :
+    PasetoException("Key instance has already been consumed and cleared. Lpad a new key for each operation.")
 
 class KeyPemUnsupportedTypeException @InternalApi constructor(val type: String) :
     PasetoException("Unsupported PEM type: $type")

paseto/src/main/kotlin/net/aholbrook/paseto/exception/KeyExceptions.kt

@@ -7,7 +7,7 @@ import net.aholbrook.paseto.crypto.ED25519_PUBLICKEYBYTES
 import net.aholbrook.paseto.crypto.ED25519_SECRETKEYBYTES
 import net.aholbrook.paseto.crypto.constantTimeEquals
 import net.aholbrook.paseto.decodeOrNull
-import net.aholbrook.paseto.exception.GenericInvalidFooterException
+import net.aholbrook.paseto.exception.IncorrectFooterException
 import net.aholbrook.paseto.exception.PasetoParseException
 import net.aholbrook.paseto.protocol.key.AsymmetricPublicKey
 import net.aholbrook.paseto.protocol.key.AsymmetricSecretKey
@@ -117,7 +117,7 @@ internal fun decodeFooter(token: String, sections: PasetoSections, expectedFoote
         ?: throw PasetoParseException(PasetoParseException.Reason.INVALID_BASE64, token)
 
     if (expectedFooter != null && !decodedFooter.constantTimeEquals(expectedFooter)) {
-        throw GenericInvalidFooterException(decodedFooter, expectedFooter)
+        throw IncorrectFooterException(decodedFooter, expectedFooter)
     }
 
     return decodedFooter

paseto/src/main/kotlin/net/aholbrook/paseto/protocol/Paseto.kt

@@ -64,7 +64,7 @@ internal object PasetoV1 : Paseto {
                     ".${Base64.UrlSafeNoPadding.encode(f)}"
                 }
         } finally {
-            key.clear()
+            key.internalClear()
             cleanup.forEach { it.run() }
         }
     }
@@ -121,7 +121,7 @@ internal object PasetoV1 : Paseto {
 
             return Pair(m.toString(Charsets.UTF_8), f)
         } finally {
-            key.clear()
+            key.internalClear()
             cleanup.forEach { it.run() }
         }
     }
@@ -147,7 +147,7 @@ internal object PasetoV1 : Paseto {
                     ".${Base64.UrlSafeNoPadding.encode(f)}"
                 }
         } finally {
-            secretKey.clear()
+            secretKey.internalClear()
         }
     }