README.md

MACs

Message Authentication Code algorithms for Kotlin Multiplatform

Usage

See HERE for basic usage example for Mac.

// 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

fun main() {
    val key = SecureRandom().nextBytesOf(100)

    HmacSHA224(key)
    HmacSHA256(key)
    HmacSha384(key)
    HmacSHA512(key)

    HmacSHA512_224(key)
    HmacSHA512_256(key)
    HmacSHA512t(key, 504)
    
    key.fill(0)
}

SHA3 Hmac

 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)

See HERE for details on what XOFs are, and a basic usage example for Xof.

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)
}

Get Started

The best way to keep KotlinCrypto dependencies up to date is by using the version-catalog. Alternatively, you can use the BOM as shown below.

// build.gradle.kts
dependencies {
    // define the BOM and its version
    implementation(platform("org.kotlincrypto.macs:bom:0.5.3"))

    // define artifacts without version
    
    // HmacMD5
    implementation("org.kotlincrypto.macs:hmac-md")
    
    // HmacSHA1
    implementation("org.kotlincrypto.macs:hmac-sha1")
    
    // HmacSHA224, HmacSHA256, HmacSHA384, HmacSHA512
    // HmacSHA512/t, HmacSHA512/224, HmacSHA512/256
    implementation("org.kotlincrypto.macs:hmac-sha2")
    
    // HmacKeccak224, HmacKeccak256, HmacKeccak384, HmacKeccak512
    // HmacSHA3-224, HmacSHA3-256, HmacSHA3-384, HmacSHA3-512
    implementation("org.kotlincrypto.macs:hmac-sha3")

    // KMAC128, KMAC256
    implementation("org.kotlincrypto.macs:kmac")
}