Prepare 0.6.0 release

Author: 05nelsonm

CHANGELOG.md

@@ -1,5 +1,40 @@
 # CHANGELOG
 
+## Version 0.6.0 (2025-01-15)
+ - `@Throws` annotation removed from `Updatable.update` (it is documented).
+ - Finalizes `Digest` internal API and removes `InternalKotlinCryptoApi` opt-in requirement from constructors.
+     - Drops usage of `DigestState` in favor of secondary constructor which takes 
+       `Digest` as an argument (for `copy` function implementations).
+     - `Copyable.copy` override is now passed through to implementations so that the proper 
+       return type can be defined (instead of requiring API consumers to cast from `Digest`).
+     - `protected` functions renamed:
+         - `compress` >> `compressProtected`
+         - `digest` >> `digestProtected`
+         - `updateDigest` >> `updateProtected`
+         - `resetDigest` >> `resetProtected`
+     - `digestProtected` (previously `digest`) now only provides the buffered input and position as 
+       arguments; `bitLength` is no longer tracked by `Digest`.
+ - `Digest.digest` now zero's out stale buffered input from `bufPos` to `buf.size` before passing it to 
+   `digestProtected` (previously `digest`) as an argument.
+ - Finalizes `Mac` internal API and removes `InternalKotlinCryptoApi` opt-in requirement from constructors.
+     - Provides secondary constructor which takes `Mac` as an argument (for `copy` function implementations).
+     - `Copyable.copy` override is now passed through to `Mac` implementations so that the proper 
+       return type can be defined (instead of requiring API consumers to cast from `Mac`).
+     - Adds ability to reinitialize `Mac` with a new `key` parameter via `reset(newKey)` (or clear it after use).
+     - Adds `Mac.clearKey` helper function for zeroing out key material before dereferencing the `Mac` (if desired).
+     - Removes `Mac.Engine.State` in favor of secondary constructor which takes `Mac.Engine` as an argument 
+       (for `copy` function implementation).
+     - Adds abstract function `Mac.Engine.reset(newKey)` for reinitialization functionality.
+ - Finalizes `Xof` and `XofFactory` internal API and removes `InternalKotlinCryptoApi` opt-in 
+   requirement from constructors.
+     - `Xof.Reader.readProtected` no longer passes `bytesRead` as an argument.
+ - Adds `ReKeyableXofAlgorithm` interface for `Xof` implementations who's backing delegate is a `Mac`.
+ - Adds `Xof.Companion.reset(newKey)` extension function which allows API consumers the ability to 
+   reinitialize the `Xof` with a new `key` parameter when that `Xof` is backed by an instance of 
+   `ReKeyableXofAlgorithm` (i.e. a `Mac` implementation).
+ - `Xof.use` and `Xof.Reader.use` functions are now inlined.
+ - Removes usage of `KotlinCrypto.endians` library (deprecated) from `Xof.Utils`.
+
 ## Version 0.5.5 (2024-12-20)
  - Fixes optimization issues with `Digest.update` internals [[#70]][70]
 

README.md

@@ -116,6 +116,14 @@ fun main() {
 
     val hash = mac.doFinal()
     val hash2 = copy.doFinal(bytes)
+
+    // Reinitialize Mac instance with a new key
+    // to use for something else.
+    val newKey = SecureRandom().nextBytesOf(100)
+    mac.reset(newKey = newKey)
+
+    // Zero out key material before dereferencing
+    copy.clearKey()
 }
 ```
 
@@ -204,6 +212,27 @@ fun main() {
 }
 ```
 
+```kotlin
+// Using KMAC128 from MACs repo as an example
+import org.kotlincrypto.macs.kmac.KMAC128
+// Using SecureRandom from the secure-random repo as an example
+import org.kotlincrypto.SecureRandom
+
+fun main() {
+    val key = SecureRandom().nextBytesOf(100)
+    val kmacXof: Xof<KMAC128> = KMAC128.xOf(key)
+
+    // If Xof is for a Mac that implements ReKeyableXofAlgorithm,
+    // reinitialize the instance via the `Xof.Companion.reset`
+    // extension function for reuse.
+    val newKey = SecureRandom().nextBytesOf(100)
+    kmacXof.reset(newKey = newKey)
+
+    // Or zero out key material before dereferencing
+    kmacXof.reset(newKey = ByteArray(1))
+}
+```
+
 </details>
 
 ### Get Started
@@ -216,27 +245,15 @@ The best way to keep `KotlinCrypto` dependencies up to date is by using the
 ```kotlin
 // build.gradle.kts
 dependencies {
-    val core = "0.5.5"
+    val core = "0.6.0"
     implementation("org.kotlincrypto.core:digest:$core")
     implementation("org.kotlincrypto.core:mac:$core")
     implementation("org.kotlincrypto.core:xof:$core")
 }
 ```
 
 <!-- TAG_VERSION -->
-
-```groovy
-// build.gradle
-dependencies {
-    def core = "0.5.5"
-    implementation "org.kotlincrypto.core:digest:$core"
-    implementation "org.kotlincrypto.core:mac:$core"
-    implementation "org.kotlincrypto.core:xof:$core"
-}
-```
-
-<!-- TAG_VERSION -->
-[badge-latest-release]: https://img.shields.io/badge/latest--release-0.5.5-blue.svg?style=flat
+[badge-latest-release]: https://img.shields.io/badge/latest--release-0.6.0-blue.svg?style=flat
 [badge-license]: https://img.shields.io/badge/license-Apache%20License%202.0-blue.svg?style=flat
 
 <!-- TAG_DEPENDENCIES -->

gradle.properties

@@ -30,7 +30,7 @@ POM_DEVELOPER_ID=KotlinCrypto
 POM_DEVELOPER_NAME=Kotlin Crypto
 POM_DEVELOPER_URL=https://github.com/KotlinCrypto/
 
-VERSION_NAME=0.6.0-SNAPSHOT
+VERSION_NAME=0.6.0
 # 0.1.0-alpha01 = 00 01 00 11
 # 0.1.0-beta01  = 00 01 00 21
 # 0.1.0-rc01    = 00 01 00 31

library/digest/src/commonMain/kotlin/org/kotlincrypto/core/digest/internal/DigestState.kt

@@ -15,5 +15,5 @@
  **/
 package org.kotlincrypto.core.digest.internal
 
-@Deprecated("Replaced by Digest.State since 1.0.0")
+@Deprecated("Removed from usage in Digest copy implementation in 0.6.0")
 public sealed class DigestState