From bc680c8151dd858fb99745493c63310fc66ce221 Mon Sep 17 00:00:00 2001 From: Matthew Nelson Date: Tue, 4 Feb 2025 23:37:30 -0500 Subject: [PATCH] Add `dokka` documentation at `https://macs.kotlincrypto.org` (#73) --- .gitignore | 3 + README.md | 101 ++---------------- build-logic/build.gradle.kts | 1 + .../main/kotlin/-KmpConfigurationExtension.kt | 9 +- build-logic/src/main/kotlin/dokka.gradle.kts | 48 +++++++++ build.gradle.kts | 1 + gh-pages/publish.sh | 37 +++++++ gradle/libs.versions.toml | 75 ++++++------- library/blake2/README.md | 25 +++++ .../org/kotlincrypto/macs/blake2/BLAKE2Mac.kt | 4 +- .../org/kotlincrypto/macs/blake2/BLAKE2b.kt | 2 + .../org/kotlincrypto/macs/blake2/BLAKE2s.kt | 2 + library/hmac/hmac-md/README.md | 22 ++++ library/hmac/hmac-sha1/README.md | 22 ++++ library/hmac/hmac-sha2/README.md | 32 ++++++ library/hmac/hmac-sha3/README.md | 36 +++++++ library/hmac/hmac/README.md | 4 + library/kmac/README.md | 44 ++++++++ .../org/kotlincrypto/macs/kmac/KMAC128.kt | 2 + .../org/kotlincrypto/macs/kmac/KMAC256.kt | 5 +- .../kotlin/org/kotlincrypto/macs/kmac/Kmac.kt | 4 +- 21 files changed, 339 insertions(+), 140 deletions(-) create mode 100644 build-logic/src/main/kotlin/dokka.gradle.kts create mode 100755 gh-pages/publish.sh create mode 100644 library/blake2/README.md create mode 100644 library/hmac/hmac-md/README.md create mode 100644 library/hmac/hmac-sha1/README.md create mode 100644 library/hmac/hmac-sha2/README.md create mode 100644 library/hmac/hmac-sha3/README.md create mode 100644 library/hmac/hmac/README.md create mode 100644 library/kmac/README.md diff --git a/.gitignore b/.gitignore index 54278b2..a1a289b 100644 --- a/.gitignore +++ b/.gitignore @@ -4,3 +4,6 @@ build/ .idea/ local.properties .kotlin/ + +gh-pages/* +!gh-pages/publish.sh diff --git a/README.md b/README.md index c19e58d..9a0d2c9 100644 --- a/README.md +++ b/README.md @@ -24,97 +24,19 @@ Message Authentication Code algorithms for Kotlin Multiplatform -### Usage +### Modules -See [HERE][url-core-usage] for basic usage example for `Mac`. + - [hmac](library/hmac/hmac/README.md) + - [hmac-md](library/hmac/hmac-md/README.md) + - [hmac-sha1](library/hmac/hmac-sha1/README.md) + - [hmac-sha2](library/hmac/hmac-sha2/README.md) + - [hmac-sha3](library/hmac/hmac-sha3/README.md) + - [blake2](library/blake2/README.md) + - [kmac](library/kmac/README.md) -```kotlin -// Using SecureRandom from the secure-random repo as an example -import org.kotlincrypto.SecureRandom -// ... - -fun main() { - val key = SecureRandom().nextBytesOf(100) - - // Hmacs that may be needed for backward compatibility but - // should no longer be utilized because they have been broken. - HmacMD5(key) - HmacSHA1(key) - - key.fill(0) -} -``` - -`SHA2 Hmac` - -```kotlin -fun main() { - val key = SecureRandom().nextBytesOf(100) - - HmacSHA224(key) - HmacSHA256(key) - HmacSha384(key) - HmacSHA512(key) - - HmacSHA512t(key, 224) // HmacSHA512/224 - HmacSHA512t(key, 256) // HmacSHA512/256 - - key.fill(0) -} -``` - -`SHA3 Hmac` - -```kotlin - fun main() { - val key = SecureRandom().nextBytesOf(100) - - HmacKeccak224(key) - HmacKeccak256(key) - HmacKeccak384(key) - HmacKeccak512(key) - HmacSHA3_224(key) - HmacSHA3_256(key) - HmacSHA3_384(key) - HmacSHA3_512(key) - - key.fill(0) -} -``` - -`SHA3 KMAC & XOFs` (i.e. [Extendable-Output Functions][url-pub-xof]) - -See [HERE][url-core-usage] for details on what `XOFs` are, and a basic usage example for `Xof`. +### API Docs -```kotlin -fun main() { - val key = SecureRandom().nextBytesOf(100) - - val S = "My Customization".encodeToByteArray() - - // Macs - KMAC128(key) - KMAC256(key, S, outputLength = 123) // returns 123 bytes instead of the default when doFinal() is invoked - - // Xofs - KMAC128.xOf(key, S) - KMAC256.xOf(key) - - key.fill(0) -} -```` - -`BLAKE2 Macs` - -```kotlin -fun main() { - val key64 = SecureRandom().nextBytesOf(64) - val key32 = SecureRandom().nextBytesOf(32) - - BLAKE2b(key64, 512) - BLAKE2s(key32, 256) -} -``` + - [https://macs.kotlincrypto.org][url-docs] ### Get Started @@ -185,7 +107,6 @@ dependencies { [url-license]: https://www.apache.org/licenses/LICENSE-2.0.txt [url-kotlin]: https://kotlinlang.org [url-core]: https://github.com/KotlinCrypto/core -[url-core-usage]: https://github.com/KotlinCrypto/core#usage [url-hash]: https://github.com/KotlinCrypto/hash -[url-pub-xof]: https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.202.pdf [url-version-catalog]: https://github.com/KotlinCrypto/version-catalog +[url-docs]: https://macs.kotlincrypto.org diff --git a/build-logic/build.gradle.kts b/build-logic/build.gradle.kts index 65d83f0..ec02fd7 100644 --- a/build-logic/build.gradle.kts +++ b/build-logic/build.gradle.kts @@ -18,6 +18,7 @@ plugins { } dependencies { + implementation(libs.gradle.dokka) implementation(libs.gradle.kmp.configuration) implementation(libs.gradle.kotlin) implementation(libs.gradle.publish.maven) diff --git a/build-logic/src/main/kotlin/-KmpConfigurationExtension.kt b/build-logic/src/main/kotlin/-KmpConfigurationExtension.kt index 77a7eef..aed6087 100644 --- a/build-logic/src/main/kotlin/-KmpConfigurationExtension.kt +++ b/build-logic/src/main/kotlin/-KmpConfigurationExtension.kt @@ -25,10 +25,9 @@ fun KmpConfigurationExtension.configureShared( publish: Boolean = false, action: Action ) { -// TODO: Enable once module :library:hmac:hmac-md5 is removed -// if (publish) { -// require(!java9ModuleName.isNullOrBlank()) { "publications must specify a module-info name" } -// } + if (publish) { + require(!java9ModuleName.isNullOrBlank()) { "publications must specify a module-info name" } + } configure { options { @@ -76,7 +75,7 @@ fun KmpConfigurationExtension.configureShared( mingwAll() common { - if (publish) pluginIds("publication") + if (publish) pluginIds("publication", "dokka") sourceSetTest { dependencies { diff --git a/build-logic/src/main/kotlin/dokka.gradle.kts b/build-logic/src/main/kotlin/dokka.gradle.kts new file mode 100644 index 0000000..0d8fd5c --- /dev/null +++ b/build-logic/src/main/kotlin/dokka.gradle.kts @@ -0,0 +1,48 @@ +/* + * Copyright (c) 2025 Matthew Nelson + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + **/ +import org.jetbrains.dokka.DokkaConfiguration.Visibility +import org.jetbrains.dokka.gradle.DokkaTaskPartial +import java.net.URI + +plugins { + id("org.jetbrains.dokka") +} + +tasks.withType().configureEach { + suppressInheritedMembers = true + + dokkaSourceSets.configureEach { + includes.from("README.md") + noStdlibLink = true + + externalDocumentationLink { + url = URI("https://core.kotlincrypto.org/").toURL() + } + externalDocumentationLink { + url = URI("https://hash.kotlincrypto.org/").toURL() + } + + sourceLink { + localDirectory = rootDir + remoteUrl = URI("https://github.com/KotlinCrypto/MACs/tree/master").toURL() + remoteLineSuffix = "#L" + } + + documentedVisibilities.set(setOf( + Visibility.PUBLIC, + )) + } +} diff --git a/build.gradle.kts b/build.gradle.kts index e97b809..1c81486 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -21,6 +21,7 @@ plugins { alias(libs.plugins.android.library) apply(false) alias(libs.plugins.benchmark) apply(false) alias(libs.plugins.binary.compat) + alias(libs.plugins.dokka) alias(libs.plugins.kotlin.multiplatform) apply(false) } diff --git a/gh-pages/publish.sh b/gh-pages/publish.sh new file mode 100755 index 0000000..f1b3fe2 --- /dev/null +++ b/gh-pages/publish.sh @@ -0,0 +1,37 @@ +#!/usr/bin/env bash +# Copyright (c) 2025 Matthew Nelson +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# https://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +set -e + +readonly DIR_SCRIPT="$( cd "$( dirname "$0" )" >/dev/null && pwd )" +readonly REPO_NAME="MACs" + +trap 'rm -rf "$DIR_SCRIPT/$REPO_NAME"' EXIT + +cd "$DIR_SCRIPT" +git clone -b gh-pages --single-branch https://github.com/KotlinCrypto/$REPO_NAME.git +rm -rf "$DIR_SCRIPT/$REPO_NAME/"* +echo "$REPO_NAME.kotlincrypto.org" > "$DIR_SCRIPT/$REPO_NAME/CNAME" + +cd .. +./gradlew clean -DKMP_TARGETS_ALL +./gradlew dokkaHtmlMultiModule --no-build-cache -DKMP_TARGETS_ALL +cp -aR build/dokka/htmlMultiModule/* gh-pages/$REPO_NAME + +cd "$DIR_SCRIPT/$REPO_NAME" +sed -i "s|module:|module:library/|g" "package-list" + +git add --all +git commit -S --message "Update dokka docs" +git push diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml index 202cf56..8da260c 100644 --- a/gradle/libs.versions.toml +++ b/gradle/libs.versions.toml @@ -1,48 +1,51 @@ [versions] -androidx-test-runner = "1.5.2" +androidx-test-runner = "1.5.2" -bouncy-castle = "1.73" +bouncy-castle = "1.73" -encoding = "2.3.1" +encoding = "2.3.1" -gradle-android = "8.2.2" -gradle-benchmark = "0.4.11" -gradle-binary-compat = "0.16.3" -gradle-kmp-configuration = "0.3.2" -gradle-kotlin = "1.9.24" -gradle-publish-maven = "0.29.0" +gradle-android = "8.2.2" +gradle-benchmark = "0.4.11" +gradle-binary-compat = "0.16.3" +gradle-dokka = "1.9.20" +gradle-kmp-configuration = "0.3.2" +gradle-kotlin = "1.9.24" +gradle-publish-maven = "0.29.0" -kotlincrypto-bitops = "0.1.2" -kotlincrypto-core = "0.6.1-SNAPSHOT" -kotlincrypto-hash = "0.6.1-SNAPSHOT" -kotlincrypto-sponges = "0.3.4" +kotlincrypto-bitops = "0.1.2" +kotlincrypto-core = "0.6.1-SNAPSHOT" +kotlincrypto-hash = "0.6.1-SNAPSHOT" +kotlincrypto-sponges = "0.3.4" [libraries] -gradle-kmp-configuration = { module = "io.matthewnelson:gradle-kmp-configuration-plugin", version.ref = "gradle-kmp-configuration" } -gradle-kotlin = { module = "org.jetbrains.kotlin:kotlin-gradle-plugin", version.ref = "gradle-kotlin" } -gradle-publish-maven = { module = "com.vanniktech:gradle-maven-publish-plugin", version.ref = "gradle-publish-maven" } - -kotlincrypto-core-digest = { module = "org.kotlincrypto.core:digest", version.ref = "kotlincrypto-core" } -kotlincrypto-core-mac = { module = "org.kotlincrypto.core:mac", version.ref = "kotlincrypto-core" } -kotlincrypto-core-xof = { module = "org.kotlincrypto.core:xof", version.ref = "kotlincrypto-core" } -kotlincrypto-hash-blake2 = { module = "org.kotlincrypto.hash:blake2", version.ref = "kotlincrypto-hash" } -kotlincrypto-hash-md = { module = "org.kotlincrypto.hash:md", version.ref = "kotlincrypto-hash" } -kotlincrypto-hash-sha1 = { module = "org.kotlincrypto.hash:sha1", version.ref = "kotlincrypto-hash" } -kotlincrypto-hash-sha2 = { module = "org.kotlincrypto.hash:sha2", version.ref = "kotlincrypto-hash" } -kotlincrypto-hash-sha3 = { module = "org.kotlincrypto.hash:sha3", version.ref = "kotlincrypto-hash" } +gradle-dokka = { module = "org.jetbrains.dokka:dokka-gradle-plugin", version.ref = "gradle-dokka" } +gradle-kmp-configuration = { module = "io.matthewnelson:gradle-kmp-configuration-plugin", version.ref = "gradle-kmp-configuration" } +gradle-kotlin = { module = "org.jetbrains.kotlin:kotlin-gradle-plugin", version.ref = "gradle-kotlin" } +gradle-publish-maven = { module = "com.vanniktech:gradle-maven-publish-plugin", version.ref = "gradle-publish-maven" } + +kotlincrypto-core-digest = { module = "org.kotlincrypto.core:digest", version.ref = "kotlincrypto-core" } +kotlincrypto-core-mac = { module = "org.kotlincrypto.core:mac", version.ref = "kotlincrypto-core" } +kotlincrypto-core-xof = { module = "org.kotlincrypto.core:xof", version.ref = "kotlincrypto-core" } +kotlincrypto-hash-blake2 = { module = "org.kotlincrypto.hash:blake2", version.ref = "kotlincrypto-hash" } +kotlincrypto-hash-md = { module = "org.kotlincrypto.hash:md", version.ref = "kotlincrypto-hash" } +kotlincrypto-hash-sha1 = { module = "org.kotlincrypto.hash:sha1", version.ref = "kotlincrypto-hash" } +kotlincrypto-hash-sha2 = { module = "org.kotlincrypto.hash:sha2", version.ref = "kotlincrypto-hash" } +kotlincrypto-hash-sha3 = { module = "org.kotlincrypto.hash:sha3", version.ref = "kotlincrypto-hash" } # tests & tools -androidx-test-runner = { module = "androidx.test:runner", version.ref = "androidx-test-runner" } -benchmark-runtime = { module = "org.jetbrains.kotlinx:kotlinx-benchmark-runtime", version.ref = "gradle-benchmark" } -bouncy-castle = { module = "org.bouncycastle:bcprov-ext-jdk15to18", version.ref = "bouncy-castle" } -encoding-base16 = { module = "io.matthewnelson.encoding:base16", version.ref = "encoding" } -encoding-base64 = { module = "io.matthewnelson.encoding:base64", version.ref = "encoding" } -kotlincrypto-bitops-bits = { module = "org.kotlincrypto.bitops:bits", version.ref = "kotlincrypto-bitops" } -kotlincrypto-bitops-endian = { module = "org.kotlincrypto.bitops:endian", version.ref = "kotlincrypto-bitops" } +androidx-test-runner = { module = "androidx.test:runner", version.ref = "androidx-test-runner" } +benchmark-runtime = { module = "org.jetbrains.kotlinx:kotlinx-benchmark-runtime", version.ref = "gradle-benchmark" } +bouncy-castle = { module = "org.bouncycastle:bcprov-ext-jdk15to18", version.ref = "bouncy-castle" } +encoding-base16 = { module = "io.matthewnelson.encoding:base16", version.ref = "encoding" } +encoding-base64 = { module = "io.matthewnelson.encoding:base64", version.ref = "encoding" } +kotlincrypto-bitops-bits = { module = "org.kotlincrypto.bitops:bits", version.ref = "kotlincrypto-bitops" } +kotlincrypto-bitops-endian = { module = "org.kotlincrypto.bitops:endian", version.ref = "kotlincrypto-bitops" } kotlincrypto-sponges-keccak = { module = "org.kotlincrypto.sponges:keccak", version.ref = "kotlincrypto-sponges" } [plugins] -android-library = { id = "com.android.library", version.ref = "gradle-android" } -benchmark = { id = "org.jetbrains.kotlinx.benchmark", version.ref = "gradle-benchmark" } -binary-compat = { id = "org.jetbrains.kotlinx.binary-compatibility-validator", version.ref = "gradle-binary-compat" } -kotlin-multiplatform = { id = "org.jetbrains.kotlin.multiplatform", version.ref = "gradle-kotlin" } +android-library = { id = "com.android.library", version.ref = "gradle-android" } +benchmark = { id = "org.jetbrains.kotlinx.benchmark", version.ref = "gradle-benchmark" } +binary-compat = { id = "org.jetbrains.kotlinx.binary-compatibility-validator", version.ref = "gradle-binary-compat" } +dokka = { id = "org.jetbrains.dokka", version.ref = "gradle-dokka" } +kotlin-multiplatform = { id = "org.jetbrains.kotlin.multiplatform", version.ref = "gradle-kotlin" } diff --git a/library/blake2/README.md b/library/blake2/README.md new file mode 100644 index 0000000..47cd068 --- /dev/null +++ b/library/blake2/README.md @@ -0,0 +1,25 @@ +# Module blake2 + +`Mac` implementations for BLAKE2 Keyed Hashing + +Implementations for: + - BLAKE2b + - BLAKE2s + +See [HERE][url-mac-usage] for basic usage example of `Mac`. + +```kotlin +// Using SecureRandom from the secure-random repo as an example +import org.kotlincrypto.SecureRandom +// ... + +fun main() { + val key64 = SecureRandom().nextBytesOf(64) + val key32 = SecureRandom().nextBytesOf(32) + + BLAKE2b(key64, 512) + BLAKE2s(key32, 256) +} +``` + +[url-mac-usage]: https://core.kotlincrypto.org/library/mac/index.html diff --git a/library/blake2/src/commonMain/kotlin/org/kotlincrypto/macs/blake2/BLAKE2Mac.kt b/library/blake2/src/commonMain/kotlin/org/kotlincrypto/macs/blake2/BLAKE2Mac.kt index 0297cc0..c35f8e5 100644 --- a/library/blake2/src/commonMain/kotlin/org/kotlincrypto/macs/blake2/BLAKE2Mac.kt +++ b/library/blake2/src/commonMain/kotlin/org/kotlincrypto/macs/blake2/BLAKE2Mac.kt @@ -20,9 +20,7 @@ import org.kotlincrypto.core.mac.Mac import org.kotlincrypto.hash.blake2.BLAKE2Digest /** - * Core abstraction for BLAKE2 Keyed Hashing in the form of Message Authentication - * - * Code implementations: + * Core abstraction for: * - [BLAKE2b] * - [BLAKE2s] * */ diff --git a/library/blake2/src/commonMain/kotlin/org/kotlincrypto/macs/blake2/BLAKE2b.kt b/library/blake2/src/commonMain/kotlin/org/kotlincrypto/macs/blake2/BLAKE2b.kt index 74424aa..4b388f2 100644 --- a/library/blake2/src/commonMain/kotlin/org/kotlincrypto/macs/blake2/BLAKE2b.kt +++ b/library/blake2/src/commonMain/kotlin/org/kotlincrypto/macs/blake2/BLAKE2b.kt @@ -21,6 +21,8 @@ import org.kotlincrypto.core.InternalKotlinCryptoApi * BLAKE2b Keyed Hashing implementation * * https://datatracker.ietf.org/doc/rfc7693/ + * + * https://www.blake2.net/blake2.pdf * */ public class BLAKE2b: BLAKE2Mac { diff --git a/library/blake2/src/commonMain/kotlin/org/kotlincrypto/macs/blake2/BLAKE2s.kt b/library/blake2/src/commonMain/kotlin/org/kotlincrypto/macs/blake2/BLAKE2s.kt index fe5459d..46c6e94 100644 --- a/library/blake2/src/commonMain/kotlin/org/kotlincrypto/macs/blake2/BLAKE2s.kt +++ b/library/blake2/src/commonMain/kotlin/org/kotlincrypto/macs/blake2/BLAKE2s.kt @@ -21,6 +21,8 @@ import org.kotlincrypto.core.InternalKotlinCryptoApi * BLAKE2s Keyed Hashing implementation * * https://datatracker.ietf.org/doc/rfc7693/ + * + * https://www.blake2.net/blake2.pdf * */ public class BLAKE2s: BLAKE2Mac { diff --git a/library/hmac/hmac-md/README.md b/library/hmac/hmac-md/README.md new file mode 100644 index 0000000..0fb2847 --- /dev/null +++ b/library/hmac/hmac-md/README.md @@ -0,0 +1,22 @@ +# Module hmac-md + +`Hmac` implementations for MD Hash-based Message Authentication Codes + +Implementations for: + - HmacMD5 + +See [HERE][url-mac-usage] for basic usage example of `Mac`. + +```kotlin +// Using SecureRandom from the secure-random repo as an example +import org.kotlincrypto.SecureRandom +// ... + +fun main() { + val key = SecureRandom().nextBytesOf(100) + + HmacMD5(key) +} +``` + +[url-mac-usage]: https://core.kotlincrypto.org/library/mac/index.html diff --git a/library/hmac/hmac-sha1/README.md b/library/hmac/hmac-sha1/README.md new file mode 100644 index 0000000..564abac --- /dev/null +++ b/library/hmac/hmac-sha1/README.md @@ -0,0 +1,22 @@ +# Module hmac-sha1 + +`Hmac` implementations for SHA1 Hash-based Message Authentication Codes + +Implementations for: + - HmacSHA1 + +See [HERE][url-mac-usage] for basic usage example of `Mac`. + +```kotlin +// Using SecureRandom from the secure-random repo as an example +import org.kotlincrypto.SecureRandom +// ... + +fun main() { + val key = SecureRandom().nextBytesOf(100) + + HmacSHA1(key) +} +``` + +[url-mac-usage]: https://core.kotlincrypto.org/library/mac/index.html diff --git a/library/hmac/hmac-sha2/README.md b/library/hmac/hmac-sha2/README.md new file mode 100644 index 0000000..869af2e --- /dev/null +++ b/library/hmac/hmac-sha2/README.md @@ -0,0 +1,32 @@ +# Module hmac-sha2 + +`Hmac` implementations for SHA2 Hash-based Message Authentication Codes + +Implementations for: + - HmacSHA224 + - HmacSHA256 + - HmacSHA384 + - HmacSHA512 + - HmacSHA512/t + +See [HERE][url-mac-usage] for basic usage example of `Mac`. + +```kotlin +// Using SecureRandom from the secure-random repo as an example +import org.kotlincrypto.SecureRandom +// ... + +fun main() { + val key = SecureRandom().nextBytesOf(100) + + HmacSHA224(key) + HmacSHA256(key) + HmacSha384(key) + HmacSHA512(key) + + HmacSHA512t(key, t = 224) // HmacSHA512/224 + HmacSHA512t(key, t = 256) // HmacSHA512/256 +} +``` + +[url-mac-usage]: https://core.kotlincrypto.org/library/mac/index.html diff --git a/library/hmac/hmac-sha3/README.md b/library/hmac/hmac-sha3/README.md new file mode 100644 index 0000000..b79d34a --- /dev/null +++ b/library/hmac/hmac-sha3/README.md @@ -0,0 +1,36 @@ +# Module hmac-sha3 + +`Hmac` implementations for SHA3 Hash-based Message Authentication Codes + +Implementations for: + - HmacKeccak224 + - HmacKeccak256 + - HmacKeccak384 + - HmacKeccak512 + - HmacSHA3-224 + - HmacSHA3-256 + - HmacSHA3-384 + - HmacSHA3-512 + +See [HERE][url-mac-usage] for basic usage example of `Mac`. + +```kotlin +// Using SecureRandom from the secure-random repo as an example +import org.kotlincrypto.SecureRandom +// ... + +fun main() { + val key = SecureRandom().nextBytesOf(100) + + HmacKeccak224(key) + HmacKeccak256(key) + HmacKeccak384(key) + HmacKeccak512(key) + HmacSHA3_224(key) + HmacSHA3_256(key) + HmacSHA3_384(key) + HmacSHA3_512(key) +} +``` + +[url-mac-usage]: https://core.kotlincrypto.org/library/mac/index.html diff --git a/library/hmac/hmac/README.md b/library/hmac/hmac/README.md new file mode 100644 index 0000000..ac799dc --- /dev/null +++ b/library/hmac/hmac/README.md @@ -0,0 +1,4 @@ +# Module hmac + +Core abstraction for Hash-based Message Authentication Code that +other `hmac` modules use. diff --git a/library/kmac/README.md b/library/kmac/README.md new file mode 100644 index 0000000..3b1632c --- /dev/null +++ b/library/kmac/README.md @@ -0,0 +1,44 @@ +# Module kmac + +`Kmac` implementations for Keccak-based Message Authentication Codes + +Implementations for: + - KMAC128 + - KMAC256 + +See [HERE][url-mac-usage] for basic usage example of `Mac`. + +```kotlin +// Using SecureRandom from the secure-random repo as an example +import org.kotlincrypto.SecureRandom +// ... + +fun main() { + val key = SecureRandom().nextBytesOf(100) + + // NIST.SP.800-185 derived functions + val S = "My Customization".encodeToByteArray() + + // Macs + KMAC128(key) + // Return 123 bytes instead of the default + // whenever doFinal() is called. + KMAC256(key, S, outputLength = 123) +} +``` + +See [HERE][url-xof-usage] for basic usage example of `Xof` (i.e. [Extendable-Output Functions][url-pub-xof]). + +```kotlin +fun main() { + // NIST.SP.800-185 derived functions + val S = "My Customization".encodeToByteArray() + + val xof: Xof = KMAC128.xOf(key, S) + KMAC256.xOf(key) +} +``` + +[url-mac-usage]: https://core.kotlincrypto.org/library/mac/index.html +[url-xof-usage]: https://core.kotlincrypto.org/library/xof/index.html +[url-pub-xof]: https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.202.pdf diff --git a/library/kmac/src/commonMain/kotlin/org/kotlincrypto/macs/kmac/KMAC128.kt b/library/kmac/src/commonMain/kotlin/org/kotlincrypto/macs/kmac/KMAC128.kt index 09741ab..462acb9 100644 --- a/library/kmac/src/commonMain/kotlin/org/kotlincrypto/macs/kmac/KMAC128.kt +++ b/library/kmac/src/commonMain/kotlin/org/kotlincrypto/macs/kmac/KMAC128.kt @@ -26,6 +26,8 @@ import kotlin.jvm.JvmStatic /** * KMAC128 implementation * + * https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-185.pdf#4%20KMAC + * * @see [xOf] * */ public class KMAC128: Kmac { diff --git a/library/kmac/src/commonMain/kotlin/org/kotlincrypto/macs/kmac/KMAC256.kt b/library/kmac/src/commonMain/kotlin/org/kotlincrypto/macs/kmac/KMAC256.kt index 008825a..a044fad 100644 --- a/library/kmac/src/commonMain/kotlin/org/kotlincrypto/macs/kmac/KMAC256.kt +++ b/library/kmac/src/commonMain/kotlin/org/kotlincrypto/macs/kmac/KMAC256.kt @@ -26,6 +26,8 @@ import kotlin.jvm.JvmStatic /** * KMAC128 implementation * + * https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-185.pdf#4%20KMAC + * * @see [xOf] * */ public class KMAC256: Kmac { @@ -36,7 +38,6 @@ public class KMAC256: Kmac { * * @throws [IllegalArgumentException] if [key] is empty. * */ - @Throws(IllegalArgumentException::class) public constructor( key: ByteArray, ): this(key, null) @@ -50,7 +51,6 @@ public class KMAC256: Kmac { * empty or null value. (e.g. "My Customization".encodeToByteArray()). * @throws [IllegalArgumentException] if [key] is empty. * */ - @Throws(IllegalArgumentException::class) public constructor( key: ByteArray, S: ByteArray?, @@ -66,7 +66,6 @@ public class KMAC256: Kmac { * @throws [IllegalArgumentException] if [key] is empty, or [outputLength] * is negative. * */ - @Throws(IllegalArgumentException::class) public constructor( key: ByteArray, S: ByteArray?, diff --git a/library/kmac/src/commonMain/kotlin/org/kotlincrypto/macs/kmac/Kmac.kt b/library/kmac/src/commonMain/kotlin/org/kotlincrypto/macs/kmac/Kmac.kt index e71e15b..4274907 100644 --- a/library/kmac/src/commonMain/kotlin/org/kotlincrypto/macs/kmac/Kmac.kt +++ b/library/kmac/src/commonMain/kotlin/org/kotlincrypto/macs/kmac/Kmac.kt @@ -25,9 +25,7 @@ import org.kotlincrypto.hash.sha3.CSHAKE128 import org.kotlincrypto.hash.sha3.CSHAKE256 /** - * Core abstraction for Keccak-based Message Authentication - * - * Code implementations: + * Core abstraction for: * - [KMAC128] * - [KMAC256] * */