diff --git a/apollo/src/androidMain/kotlin/io/iohk/atala/prism/apollo/Platform.kt b/apollo/src/androidMain/kotlin/io/iohk/atala/prism/apollo/Platform.kt index e7a8040c7..e86fc5e4b 100644 --- a/apollo/src/androidMain/kotlin/io/iohk/atala/prism/apollo/Platform.kt +++ b/apollo/src/androidMain/kotlin/io/iohk/atala/prism/apollo/Platform.kt @@ -1,5 +1,19 @@ package io.iohk.atala.prism.apollo +/** + * The `Platform` class represents the platform on which the application is running. + * This class provides information about the operating system of the device. + */ public actual object Platform { + /** + * Represents the operating system on which the application is running. + * + * This variable provides the name and version of the operating system in a string format. + * + * The value of this variable is generated at runtime, and it is only applicable for the Android platform. + * + * Example: + * Android 29 + */ public actual val OS: String = "Android ${android.os.Build.VERSION.SDK_INT}" } diff --git a/apollo/src/androidMain/kotlin/io/iohk/atala/prism/apollo/hashing/PBKDF2SHA512.kt b/apollo/src/androidMain/kotlin/io/iohk/atala/prism/apollo/hashing/PBKDF2SHA512.kt index 1e09f0f52..7b971fd28 100644 --- a/apollo/src/androidMain/kotlin/io/iohk/atala/prism/apollo/hashing/PBKDF2SHA512.kt +++ b/apollo/src/androidMain/kotlin/io/iohk/atala/prism/apollo/hashing/PBKDF2SHA512.kt @@ -2,8 +2,22 @@ package io.iohk.atala.prism.apollo.hashing import org.bitcoinj.crypto.PBKDF2SHA512 +/** + * The PBKDF2SHA512 class provides a platform-specific implementation for + * deriving a key from a password using the PBKDF2 algorithm with SHA-512 + * hash function. + */ actual class PBKDF2SHA512 { actual companion object { + /** + * Derives a key from a password using the PBKDF2 algorithm with SHA-512 hash function. + * + * @param p The password used for key derivation. + * @param s The salt value. + * @param c The iteration count. + * @param dkLen The desired length of the derived key in bytes. + * @return The derived key as a ByteArray. + */ actual fun derive( p: String, s: String, diff --git a/apollo/src/androidMain/kotlin/io/iohk/atala/prism/apollo/secp256k1/Secp256k1Lib.kt b/apollo/src/androidMain/kotlin/io/iohk/atala/prism/apollo/secp256k1/Secp256k1Lib.kt index 73ab01faf..ce357b42e 100644 --- a/apollo/src/androidMain/kotlin/io/iohk/atala/prism/apollo/secp256k1/Secp256k1Lib.kt +++ b/apollo/src/androidMain/kotlin/io/iohk/atala/prism/apollo/secp256k1/Secp256k1Lib.kt @@ -3,7 +3,18 @@ package io.iohk.atala.prism.apollo.secp256k1 import fr.acinq.secp256k1.Secp256k1 import org.kotlincrypto.hash.sha2.SHA256 +/** + * This is an actual implementation of the Secp256k1Lib class. + */ actual class Secp256k1Lib { + /** + * Creates a public key from a given private key. + * + * @param privateKey The private key in byte array format. + * @param compressed A boolean indicating whether the public key should be compressed. + * @return A byte array representing the public key. + * @throws Secp256k1Exception if the public key is invalid. + */ actual fun createPublicKey(privateKey: ByteArray, compressed: Boolean): ByteArray { val pubKey = Secp256k1.pubkeyCreate(privateKey) if (Secp256k1Helper.validatePublicKey(pubKey)) { @@ -16,6 +27,13 @@ actual class Secp256k1Lib { } } + /** + * Derives a new private key from an existing private key and derived bytes. + * + * @param privateKeyBytes The original private key in byte array format. + * @param derivedPrivateKeyBytes The byte array used for deriving the new private key. + * @return A byte array representing the derived private key, or null if derivation fails. + */ actual fun derivePrivateKey( privateKeyBytes: ByteArray, derivedPrivateKeyBytes: ByteArray @@ -23,12 +41,27 @@ actual class Secp256k1Lib { return Secp256k1.privKeyTweakAdd(privateKeyBytes, derivedPrivateKeyBytes) } + /** + * Signs data using a given private key. + * + * @param privateKey The private key used for signing, in byte array format. + * @param data The data to be signed, in byte array format. + * @return A byte array representing the signature. + */ actual fun sign(privateKey: ByteArray, data: ByteArray): ByteArray { val sha = SHA256().digest(data) val compactSignature = Secp256k1.sign(sha, privateKey) return Secp256k1.compact2der(compactSignature) } + /** + * Verifies a signature against a public key and data. + * + * @param publicKey The public key in byte array format. + * @param signature The signature to be verified, in byte array format. + * @param data The data against which the signature will be verified, in byte array format. + * @return A boolean indicating whether the signature is valid. + */ actual fun verify( publicKey: ByteArray, signature: ByteArray, @@ -38,10 +71,22 @@ actual class Secp256k1Lib { return Secp256k1.verify(signature, sha, publicKey) } + /** + * Decompresses a compressed public key. + * + * @param compressed The compressed public key in byte array format. + * @return A byte array representing the uncompressed public key. + */ actual fun uncompressPublicKey(compressed: ByteArray): ByteArray { return Secp256k1.pubkeyParse(compressed) } + /** + * Compresses an uncompressed public key. + * + * @param uncompressed The uncompressed public key in byte array format. + * @return A byte array representing the compressed public key. + */ actual fun compressPublicKey(uncompressed: ByteArray): ByteArray { return Secp256k1.pubKeyCompress(uncompressed) } diff --git a/apollo/src/androidMain/kotlin/io/iohk/atala/prism/apollo/securerandom/SecureRandom.kt b/apollo/src/androidMain/kotlin/io/iohk/atala/prism/apollo/securerandom/SecureRandom.kt index 646be27f0..bbf8aecdf 100644 --- a/apollo/src/androidMain/kotlin/io/iohk/atala/prism/apollo/securerandom/SecureRandom.kt +++ b/apollo/src/androidMain/kotlin/io/iohk/atala/prism/apollo/securerandom/SecureRandom.kt @@ -2,9 +2,34 @@ package io.iohk.atala.prism.apollo.securerandom import android.os.Build +/** + * The SecureRandom class provides a platform-specific implementation for generating secure random numbers. + * + * @property seed The seed value used for initializing the random number generator. + * + * @see [java.security.SecureRandom] + */ actual class SecureRandom actual constructor( actual val seed: ByteArray -) : SecureRandomInterface { +) : SecureRandomInterface, java.security.SecureRandom() { + /** + * The `jvmSecureRandom` property provides a platform-specific implementation for generating secure random numbers. + * + * It returns an instance of `java.security.SecureRandom` that is appropriate for the current Android version. + * + * If the Android build version is equal to or greater than Oreo (Android version 8.0), it uses the `getInstanceStrong()` method of `SecureRandom` class to get an instance of + * the class. + * Otherwise, it uses the `SecureRandom(byte[])` constructor and initializes it with the specified seed value. + * + * Note: The seed value used for initialization is provided through the `seed` property of the containing class. + * + * @return An instance of `java.security.SecureRandom` appropriate for the Android version. + * + * @see [java.security.SecureRandom] + * @see [SecureRandomInterface] + * @see [SecureRandomStaticInterface] + * @see [nextBytes] + */ private val jvmSecureRandom: java.security.SecureRandom get() { return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) { @@ -20,6 +45,12 @@ actual class SecureRandom actual constructor( } } + /** + * Generates a specified number of secure random bytes. + * + * @param size The number of random bytes to generate. + * @return A byte array containing the generated random bytes. + */ override fun nextBytes(size: Int): ByteArray { val bytes = ByteArray(size) jvmSecureRandom.nextBytes(bytes) @@ -27,6 +58,27 @@ actual class SecureRandom actual constructor( } actual companion object : SecureRandomStaticInterface { + /** + * jvmSecureRandom is a private variable that represents a secure random number generator. + * + * It is an instance of the java.security.SecureRandom class, which is used for generating cryptographically strong random numbers. + * The random numbers generated by this variable are suitable for use in security-sensitive applications, such as generating encryption keys or passwords. + * + * This variable is lazy-initialized and its value is determined by the build version of the JVM. + * If the build version is greater than or equal to Build.VERSION_CODES.O, it uses the `getInstanceStrong()` method of SecureRandom to create the instance. + * Otherwise, it creates a new instance of SecureRandom using the default constructor. + * + * The jvmSecureRandom variable implements both the SecureRandomInterface and SecureRandomStaticInterface interfaces. + * The SecureRandomInterface defines the contract for generating secure random bytes using the `nextBytes()` method. + * The SecureRandomStaticInterface defines the contract for generating a random seed of specified length using the `generateSeed()` method. + * + * Example usage: + * ``` + * override fun generateSeed(numBytes: Int): ByteArray { + * return jvmSecureRandom.generateSeed(numBytes) + * } + * ``` + */ private val jvmSecureRandom: java.security.SecureRandom get() { return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) { @@ -36,6 +88,12 @@ actual class SecureRandom actual constructor( } } + /** + * Generates a random seed of the specified length in bytes. + * + * @param numBytes The length of the seed in bytes. + * @return The generated seed as a ByteArray. + */ override fun generateSeed(numBytes: Int): ByteArray { return jvmSecureRandom.generateSeed(numBytes) } diff --git a/apollo/src/androidMain/kotlin/io/iohk/atala/prism/apollo/utils/JVMBigIntegerExt.kt b/apollo/src/androidMain/kotlin/io/iohk/atala/prism/apollo/utils/JVMBigIntegerExt.kt index d230cdc2e..9a373ca80 100644 --- a/apollo/src/androidMain/kotlin/io/iohk/atala/prism/apollo/utils/JVMBigIntegerExt.kt +++ b/apollo/src/androidMain/kotlin/io/iohk/atala/prism/apollo/utils/JVMBigIntegerExt.kt @@ -3,10 +3,21 @@ package io.iohk.atala.prism.apollo.utils import com.ionspin.kotlin.bignum.integer.Sign import java.math.BigInteger +/** + * Converts a BigInteger to an unsigned byte array. + * + * @return The unsigned byte array representation of the BigInteger. + */ fun BigInteger.toUnsignedByteArray(): ByteArray { return toByteArray().dropWhile { it == 0.toByte() }.toByteArray() } +/** + * Converts a `java.math.BigInteger` to a `com.ionspin.kotlin.bignum.integer.BigInteger`. + * + * @return The converted `com.ionspin.kotlin.bignum.integer.BigInteger` representation of the original `BigInteger`. + * @throws IllegalStateException if the original `BigInteger` has an illegal sign. + */ fun BigInteger.toKotlinBigInteger(): com.ionspin.kotlin.bignum.integer.BigInteger { val sign = when (this.signum()) { -1 -> Sign.NEGATIVE @@ -17,6 +28,11 @@ fun BigInteger.toKotlinBigInteger(): com.ionspin.kotlin.bignum.integer.BigIntege return com.ionspin.kotlin.bignum.integer.BigInteger.fromByteArray(this.toUnsignedByteArray(), sign) } +/** + * Converts this Kotlin BigInteger to a Java BigInteger. + * + * @return the Java BigInteger representation of this Kotlin BigInteger. + */ fun com.ionspin.kotlin.bignum.integer.BigInteger.toJavaBigInteger(): BigInteger { return BigInteger(this.signum(), this.toByteArray()) } diff --git a/apollo/src/androidMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMEdKeyPair.kt b/apollo/src/androidMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMEdKeyPair.kt index 30bb9933c..c5e86fdb5 100644 --- a/apollo/src/androidMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMEdKeyPair.kt +++ b/apollo/src/androidMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMEdKeyPair.kt @@ -7,12 +7,23 @@ import org.bouncycastle.crypto.params.Ed25519PublicKeyParameters import java.security.SecureRandom import kotlin.js.ExperimentalJsExport +/** + * Represents a key pair consisting of a private key and a public key. + * + * @property privateKey The private key of the key pair. + * @property publicKey The public key of the key pair. + */ actual class KMMEdKeyPair actual constructor( actual val privateKey: KMMEdPrivateKey, actual val publicKey: KMMEdPublicKey ) { @OptIn(ExperimentalJsExport::class) actual companion object : Ed25519KeyPairGeneration { + /** + * Generates a key pair consisting of a private key and a public key. + * + * @return A [KMMEdKeyPair] instance representing the generated key pair. + */ override fun generateKeyPair(): KMMEdKeyPair { val generator = Ed25519KeyPairGenerator() generator.init(Ed25519KeyGenerationParameters(SecureRandom())) @@ -24,10 +35,23 @@ actual class KMMEdKeyPair actual constructor( } } + /** + * Method to sign a provided message + * + * @param message A ByteArray with the message to be signed + * @return A ByteArray conforming the signed message + */ actual fun sign(message: ByteArray): ByteArray { return privateKey.sign(message) } + /** + * Verifies the signature of a message using the provided public key. + * + * @param message The message to verify. + * @param sig The signature to verify. + * @return true if the signature is valid, false otherwise. + */ actual fun verify(message: ByteArray, sig: ByteArray): Boolean { return publicKey.verify(message, sig) } diff --git a/apollo/src/androidMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMEdPrivateKey.kt b/apollo/src/androidMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMEdPrivateKey.kt index d993f4e55..8a5729ce8 100644 --- a/apollo/src/androidMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMEdPrivateKey.kt +++ b/apollo/src/androidMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMEdPrivateKey.kt @@ -3,13 +3,29 @@ package io.iohk.atala.prism.apollo.utils import org.bouncycastle.crypto.params.Ed25519PrivateKeyParameters import org.bouncycastle.crypto.signers.Ed25519Signer +/** + * Represents a private key for the KMMEd cryptographic system. + * + * @property raw The raw byte array representation of the private key. + */ actual class KMMEdPrivateKey(val raw: ByteArray) { + /** + * Retrieves the public key associated with a KMMEdPrivateKey. + * + * @return The KMMEdPublicKey object representing the public key. + */ fun publicKey(): KMMEdPublicKey { val private = Ed25519PrivateKeyParameters(raw, 0) val public = private.generatePublicKey() return KMMEdPublicKey(public.encoded) } + /** + * Signs a message with the given private key using the Ed25519 cryptographic system. + * + * @param message The message to be signed. + * @return The signature of the message. + */ actual fun sign(message: ByteArray): ByteArray { val privateKeyParameters = Ed25519PrivateKeyParameters(raw, 0) val signer = Ed25519Signer() diff --git a/apollo/src/androidMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMEdPublicKey.kt b/apollo/src/androidMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMEdPublicKey.kt index 1be201853..cc5640e15 100644 --- a/apollo/src/androidMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMEdPublicKey.kt +++ b/apollo/src/androidMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMEdPublicKey.kt @@ -4,7 +4,19 @@ import org.bouncycastle.crypto.params.Ed25519PublicKeyParameters import org.bouncycastle.crypto.signers.Ed25519Signer import java.io.ByteArrayInputStream +/** + * Represents a public key for the KMMEd cryptographic system. + * + * @property raw The raw byte array representation of the public key. + */ actual class KMMEdPublicKey(val raw: ByteArray) { + /** + * Verifies the signature of a message using the provided public key. + * + * @param message The message to verify. + * @param sig The signature to verify. + * @return true if the signature is valid, false otherwise. + */ actual fun verify(message: ByteArray, sig: ByteArray): Boolean { return try { val publicKeyParams = Ed25519PublicKeyParameters(ByteArrayInputStream(raw)) diff --git a/apollo/src/androidMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMX25519KeyPair.kt b/apollo/src/androidMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMX25519KeyPair.kt index 876c7d9b5..f1ce131ac 100644 --- a/apollo/src/androidMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMX25519KeyPair.kt +++ b/apollo/src/androidMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMX25519KeyPair.kt @@ -7,12 +7,23 @@ import org.bouncycastle.crypto.params.X25519PublicKeyParameters import java.security.SecureRandom import kotlin.js.ExperimentalJsExport +/** + * Represents a key pair for the X25519 elliptic curve encryption algorithm. + * + * @property privateKey The private key of the key pair. + * @property publicKey The public key of the key pair. + */ actual class KMMX25519KeyPair actual constructor( actual val privateKey: KMMX25519PrivateKey, actual val publicKey: KMMX25519PublicKey ) { @OptIn(ExperimentalJsExport::class) actual companion object : X25519KeyPairGeneration { + /** + * Generates a key pair for the X25519 elliptic curve encryption algorithm. + * + * @return KMMX25519KeyPair object containing the private and public keys. + */ override fun generateKeyPair(): KMMX25519KeyPair { val generator = X25519KeyPairGenerator() generator.init(X25519KeyGenerationParameters(SecureRandom())) diff --git a/apollo/src/androidMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMX25519PrivateKey.kt b/apollo/src/androidMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMX25519PrivateKey.kt index 78da76f87..6b58540c1 100644 --- a/apollo/src/androidMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMX25519PrivateKey.kt +++ b/apollo/src/androidMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMX25519PrivateKey.kt @@ -2,7 +2,17 @@ package io.iohk.atala.prism.apollo.utils import org.bouncycastle.crypto.params.X25519PrivateKeyParameters +/** + * Represents a private key for the X25519 elliptic curve encryption algorithm. + * + * @property raw The binary representation of the private key. + */ actual class KMMX25519PrivateKey(val raw: ByteArray) { + /** + * Generates a public key from the given private key. + * + * @return The generated public key. + */ fun publicKey(): KMMX25519PublicKey { val private = X25519PrivateKeyParameters(raw, 0) val public = private.generatePublicKey() diff --git a/apollo/src/androidMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMX25519PublicKey.kt b/apollo/src/androidMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMX25519PublicKey.kt index 5c525dc9d..7a38138ca 100644 --- a/apollo/src/androidMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMX25519PublicKey.kt +++ b/apollo/src/androidMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMX25519PublicKey.kt @@ -1,3 +1,8 @@ package io.iohk.atala.prism.apollo.utils +/** + * Represents a public key for the X25519 elliptic curve encryption algorithm. + * + * @property raw The binary representation of the public key. + */ actual class KMMX25519PublicKey(val raw: ByteArray) diff --git a/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/secp256k1/ECDH.kt b/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/secp256k1/ECDH.kt index bb0b8e476..501dca8bf 100644 --- a/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/secp256k1/ECDH.kt +++ b/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/secp256k1/ECDH.kt @@ -2,6 +2,11 @@ package io.iohk.atala.prism.apollo.secp256k1 import fr.acinq.secp256k1.Secp256k1Native +/** + * This class provides the functionality to compute an elliptic curve Diffie-Hellman secret. + * + * @constructor Creates an instance of the ECDH class. + */ class ECDH { /** * Compute an elliptic curve Diffie-Hellman secret. diff --git a/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/secp256k1/ECDSA.kt b/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/secp256k1/ECDSA.kt index 8a28de617..cb389c327 100644 --- a/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/secp256k1/ECDSA.kt +++ b/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/secp256k1/ECDSA.kt @@ -2,6 +2,9 @@ package io.iohk.atala.prism.apollo.secp256k1 import fr.acinq.secp256k1.Secp256k1Native +/** + * ECDSA class for creating and manipulating ECDSA signatures. + */ class ECDSA { /** * Create a normalized ECDSA signature. diff --git a/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/secp256k1/Hex.kt b/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/secp256k1/Hex.kt index 79ffa1e48..c6ff2c75e 100644 --- a/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/secp256k1/Hex.kt +++ b/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/secp256k1/Hex.kt @@ -1,8 +1,18 @@ package io.iohk.atala.prism.apollo.secp256k1 +/** + * The Hex object provides utilities for encoding and decoding hexadecimal strings. + */ internal object Hex { private val hexCode = arrayOf('0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'a', 'b', 'c', 'd', 'e', 'f') + /** + * Decodes a hexadecimal string into a byte array. + * + * @param hex The hexadecimal string to decode. + * @return The decoded byte array. + * @throws IllegalArgumentException if the input contains illegal hex characters or if the length of the input is not divisible by 2. + */ fun decode(hex: String): ByteArray { val input = hex.filterNot { it.isWhitespace() } val offset = @@ -30,6 +40,14 @@ internal object Hex { return out } + /** + * Converts an input byte array to a hexadecimal string representation. + * + * @param input the input byte array to be encoded. + * @param offset the starting offset in the byte array. + * @param len the number of bytes to be encoded. + * @return the hexadecimal string representation of the byte array. + */ fun encode(input: ByteArray, offset: Int, len: Int): String { val r = StringBuilder(len * 2) for (i in 0 until len) { @@ -40,5 +58,11 @@ internal object Hex { return r.toString() } + /** + * Converts an input byte array to a hexadecimal string representation. + * + * @param input the input byte array to be encoded. + * @return the hexadecimal string representation of the byte array. + */ fun encode(input: ByteArray): String = encode(input, 0, input.size) } diff --git a/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/secp256k1/Secp256k1Lib.kt b/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/secp256k1/Secp256k1Lib.kt index d05ceed33..51348b3a0 100644 --- a/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/secp256k1/Secp256k1Lib.kt +++ b/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/secp256k1/Secp256k1Lib.kt @@ -3,7 +3,18 @@ package io.iohk.atala.prism.apollo.secp256k1 import fr.acinq.secp256k1.Secp256k1Native import org.kotlincrypto.hash.sha2.SHA256 +/** + * This class provides various Secp256k1 cryptographic functionalities such as creating public keys, signing data, + * verifying signatures, and compressing or decompressing public keys. + */ actual class Secp256k1Lib { + /** + * Creates a public key from a given private key. + * + * @param privateKey The private key in byte array format. + * @param compressed A boolean indicating whether the public key should be compressed. + * @return A byte array representing the public key. + */ actual fun createPublicKey(privateKey: ByteArray, compressed: Boolean): ByteArray { val pubKey = Secp256k1Native.pubkeyCreate(privateKey) if (Secp256k1Helper.validatePublicKey(pubKey)) { @@ -16,6 +27,13 @@ actual class Secp256k1Lib { } } + /** + * Derives a new private key from an existing private key and derived bytes. + * + * @param privateKeyBytes The original private key in byte array format. + * @param derivedPrivateKeyBytes The byte array used for deriving the new private key. + * @return A byte array representing the derived private key, or null if derivation fails. + */ actual fun derivePrivateKey( privateKeyBytes: ByteArray, derivedPrivateKeyBytes: ByteArray @@ -23,12 +41,27 @@ actual class Secp256k1Lib { return Secp256k1Native.privKeyTweakAdd(privateKeyBytes, derivedPrivateKeyBytes) } + /** + * Signs data using a given private key. + * + * @param privateKey The private key used for signing, in byte array format. + * @param data The data to be signed, in byte array format. + * @return A byte array representing the signature. + */ actual fun sign(privateKey: ByteArray, data: ByteArray): ByteArray { val sha = SHA256().digest(data) val compactSign = Secp256k1Native.sign(sha, privateKey) return Secp256k1Native.compact2der(compactSign) } + /** + * Verifies a signature against a public key and data. + * + * @param publicKey The public key in byte array format. + * @param signature The signature to be verified, in byte array format. + * @param data The data against which the signature will be verified, in byte array format. + * @return A boolean indicating whether the signature is valid. + */ actual fun verify( publicKey: ByteArray, signature: ByteArray, @@ -38,10 +71,22 @@ actual class Secp256k1Lib { return Secp256k1Native.verify(signature, sha, publicKey) } + /** + * Decompresses a compressed public key. + * + * @param compressed The compressed public key in byte array format. + * @return A byte array representing the uncompressed public key. + */ actual fun uncompressPublicKey(compressed: ByteArray): ByteArray { return Secp256k1Native.pubkeyParse(compressed) } + /** + * Compresses an uncompressed public key. + * + * @param uncompressed The uncompressed public key in byte array format. + * @return A byte array representing the compressed public key. + */ actual fun compressPublicKey(uncompressed: ByteArray): ByteArray { return Secp256k1Native.pubKeyCompress(uncompressed) } diff --git a/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/securerandom/SecureRandom.kt b/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/securerandom/SecureRandom.kt index f9daa9331..315017c49 100644 --- a/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/securerandom/SecureRandom.kt +++ b/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/securerandom/SecureRandom.kt @@ -23,6 +23,12 @@ actual class SecureRandom actual constructor( } actual companion object : SecureRandomStaticInterface { + /** + * Generates a random seed of the specified length in bytes. + * + * @param numBytes The length of the seed in bytes. + * @return The generated seed as a ByteArray. + */ override fun generateSeed(numBytes: Int): ByteArray { return IOHKSecureRandomGeneration.randomDataWithLength(numBytes.toLong()).toByteArray() } diff --git a/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/utils/CArrayPointerExt.kt b/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/utils/CArrayPointerExt.kt index e77e69047..5ed18cd2f 100644 --- a/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/utils/CArrayPointerExt.kt +++ b/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/utils/CArrayPointerExt.kt @@ -8,11 +8,23 @@ import kotlinx.cinterop.allocArray import kotlinx.cinterop.get import kotlinx.cinterop.set +/** + * Converts the elements of the CArrayPointer to a UByteArray of specified length. + * + * @param length The length of the UByteArray. + * @return The converted UByteArray. + */ @OptIn(ExperimentalUnsignedTypes::class, ExperimentalForeignApi::class) fun CArrayPointer.toUByteArray(length: Int): UByteArray = UByteArray(length) { this[it] } +/** + * Converts a UByteArray to a CArrayPointer. + * + * @param memScope The memory scope to allocate the CArrayPointer. + * @return The CArrayPointer containing the converted UByteArray. + */ @OptIn(ExperimentalUnsignedTypes::class, ExperimentalForeignApi::class) fun UByteArray.toCArrayPointer(memScope: MemScope): CArrayPointer { val array = memScope.allocArray(this.size) diff --git a/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMEdKeyPair.kt b/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMEdKeyPair.kt index 16083e991..b34a5954d 100644 --- a/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMEdKeyPair.kt +++ b/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMEdKeyPair.kt @@ -2,23 +2,49 @@ package io.iohk.atala.prism.apollo.utils import kotlin.js.ExperimentalJsExport +/** + * Represents a key pair consisting of a private key and a public key. + * + * @property privateKey The private key of the key pair. + * @property publicKey The public key of the key pair. + */ actual class KMMEdKeyPair actual constructor( actual val privateKey: KMMEdPrivateKey, actual val publicKey: KMMEdPublicKey ) { @OptIn(ExperimentalJsExport::class) public actual companion object : Ed25519KeyPairGeneration { + /** + * Generates a key pair consisting of a private key and a public key. + * + * @return A [KMMEdKeyPair] instance representing the generated public and private keys. + */ public override fun generateKeyPair(): KMMEdKeyPair { val privateKey = KMMEdPrivateKey() return KMMEdKeyPair(privateKey, privateKey.publicKey()) } } + /** + * Method to sign a provided message. + * + * @param message A ByteArray with the message to be signed. + * @return A ByteArray containing the signed message. + * @throws RuntimeException if signing fails for any reason. + */ @Throws(RuntimeException::class) actual fun sign(message: ByteArray): ByteArray { return privateKey.sign(message) } + /** + * Method to verify a provided message and signature + * + * @param message A ByteArray with the original message + * @param sig The signature to be verified + * @return A boolean that tells us if the signature matches the original message + * @throws RuntimeException if verification fails or result is null + */ @Throws(RuntimeException::class) actual fun verify(message: ByteArray, sig: ByteArray): Boolean { return publicKey.verify(message, sig) diff --git a/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMEdPrivateKey.kt b/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMEdPrivateKey.kt index af9653ae9..b6361ee6a 100644 --- a/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMEdPrivateKey.kt +++ b/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMEdPrivateKey.kt @@ -3,11 +3,27 @@ package io.iohk.atala.prism.apollo.utils import kotlinx.cinterop.ExperimentalForeignApi import swift.cryptoKit.Ed25519 +/** + * Represents a private key for the KMMEd cryptographic system. + * @property raw The raw byte array representation of the private key. + */ @OptIn(ExperimentalForeignApi::class) public actual class KMMEdPrivateKey(val raw: ByteArray) { + /** + * Represents a private key for the KMMEd cryptographic system. + * + * @property raw The raw byte array representation of the private key. + */ @Throws(RuntimeException::class) public constructor() : this(Ed25519.createPrivateKey().success()?.toByteArray() ?: throw RuntimeException("Null result")) + /** + * Signs a message with a private key using the Ed25519 algorithm. + * + * @param message A ByteArray with the message to be signed. + * @return A ByteArray containing the signed message. + * @throws RuntimeException if signing fails for any reason. + */ @Throws(RuntimeException::class) actual fun sign(message: ByteArray): ByteArray { val result = Ed25519.signWithPrivateKey(raw.toNSData(), message.toNSData()) @@ -15,6 +31,12 @@ public actual class KMMEdPrivateKey(val raw: ByteArray) { return result.success()?.toByteArray() ?: throw RuntimeException("Null result") } + /** + * Retrieves the public key corresponding to this private key. + * + * @return The public key as a [KMMEdPublicKey] object. + * @throws RuntimeException if an error occurs during the public key retrieval. + */ @Throws(RuntimeException::class) fun publicKey(): KMMEdPublicKey { val result = Ed25519.publicKeyWithPrivateKey(raw.toNSData()) diff --git a/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMEdPublicKey.kt b/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMEdPublicKey.kt index f92cd3a26..4c1e67855 100644 --- a/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMEdPublicKey.kt +++ b/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMEdPublicKey.kt @@ -3,8 +3,21 @@ package io.iohk.atala.prism.apollo.utils import kotlinx.cinterop.ExperimentalForeignApi import swift.cryptoKit.Ed25519 +/** + * Represents a public key for the KMMEd cryptographic system. + * + * @property raw The raw byte array representation of the public key. + */ @OptIn(ExperimentalForeignApi::class) public actual class KMMEdPublicKey(val raw: ByteArray = ByteArray(0)) { + /** + * Verifies a message signature using a public key. + * + * @param message A ByteArray containing the original message. + * @param sig A ByteArray containing the signature to be verified. + * @return A boolean indicating whether the signature matches the original message. + * @throws RuntimeException if the verification fails or the result is null. + */ @Throws(RuntimeException::class) actual fun verify(message: ByteArray, sig: ByteArray): Boolean { val result = Ed25519.verifyWithPublicKey(raw.toNSData(), sig.toNSData(), message.toNSData()) diff --git a/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMX25519KeyPair.kt b/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMX25519KeyPair.kt index 837df6992..87b041ff0 100644 --- a/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMX25519KeyPair.kt +++ b/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMX25519KeyPair.kt @@ -2,12 +2,23 @@ package io.iohk.atala.prism.apollo.utils import kotlin.js.ExperimentalJsExport +/** + * Represents a key pair for the X25519 elliptic curve encryption algorithm. + * + * @property privateKey The private key of the key pair. + * @property publicKey The public key of the key pair. + */ actual class KMMX25519KeyPair actual constructor( actual val privateKey: KMMX25519PrivateKey, actual val publicKey: KMMX25519PublicKey ) { @OptIn(ExperimentalJsExport::class) public actual companion object : X25519KeyPairGeneration { + /** + * Generates a key pair using the KMMX25519 algorithm. + * + * @return The generated key pair, consisting of a private key and its corresponding public key. + */ public override fun generateKeyPair(): KMMX25519KeyPair { val privateKey = KMMX25519PrivateKey() return KMMX25519KeyPair(privateKey, privateKey.publicKey()) diff --git a/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMX25519PrivateKey.kt b/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMX25519PrivateKey.kt index 29280c9af..3f3e832fa 100644 --- a/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMX25519PrivateKey.kt +++ b/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMX25519PrivateKey.kt @@ -3,11 +3,27 @@ package io.iohk.atala.prism.apollo.utils import kotlinx.cinterop.ExperimentalForeignApi import swift.cryptoKit.X25519 +/** + * Represents a private key for the X25519 elliptic curve encryption algorithm. + * + * @property raw The binary representation of the private key. + */ @OptIn(ExperimentalForeignApi::class) actual class KMMX25519PrivateKey(val raw: ByteArray) { + /** + * Constructs a new instance of [KMMX25519PrivateKey]. + * + * @throws RuntimeException if the result of [X25519.createPrivateKey] is null. + */ @Throws(RuntimeException::class) public constructor() : this(X25519.createPrivateKey().success()?.toByteArray() ?: throw RuntimeException("Null result")) + /** + * Generates the public key corresponding to a private key using the X25519 elliptic curve encryption algorithm. + * + * @return The generated public key. + * @throws RuntimeException if there is an error generating the public key. + */ @Throws(RuntimeException::class) public fun publicKey(): KMMX25519PublicKey { val result = X25519.publicKeyWithPrivateKey(raw.toNSData()) diff --git a/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMX25519PublicKey.kt b/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMX25519PublicKey.kt index 34d1de8e3..d3e521690 100644 --- a/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMX25519PublicKey.kt +++ b/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMX25519PublicKey.kt @@ -1,3 +1,9 @@ package io.iohk.atala.prism.apollo.utils +/** + * Represents a public key for the X25519 elliptic curve encryption algorithm. + * + * @property raw The binary representation of the public key. + * @constructor Creates a new instance of [KMMX25519PublicKey] with the given raw value. + */ actual class KMMX25519PublicKey(val raw: ByteArray = ByteArray(0)) diff --git a/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/utils/ToPlatform.kt b/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/utils/ToPlatform.kt index 79242f1df..7e2fd6a28 100644 --- a/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/utils/ToPlatform.kt +++ b/apollo/src/appleMain/kotlin/io/iohk/atala/prism/apollo/utils/ToPlatform.kt @@ -15,6 +15,11 @@ import platform.Foundation.numberWithInt import platform.darwin.NSUInteger import platform.posix.memcpy +/** + * Converts a ByteArray to an NSData object. + * + * @return The converted NSData object. + */ @OptIn(ExperimentalForeignApi::class, BetaInteropApi::class) fun ByteArray.toNSData(): NSData = memScoped { NSData.create( @@ -23,6 +28,11 @@ fun ByteArray.toNSData(): NSData = memScoped { ) } +/** + * Converts an NSData object to a ByteArray. + * + * @return The ByteArray representation of the NSData object. + */ @OptIn(ExperimentalForeignApi::class) fun NSData.toByteArray(): ByteArray = ByteArray(this@toByteArray.length.toInt()).apply { if (this@toByteArray.length > 0U) { @@ -32,20 +42,40 @@ fun NSData.toByteArray(): ByteArray = ByteArray(this@toByteArray.length.toInt()) } } +/** + * Converts an integer to an NSNumber object. + * + * @return The converted NSNumber object. + */ @OptIn(ExperimentalForeignApi::class) fun Int.toNSNumber(): NSNumber = memScoped { return NSNumber.numberWithInt(this@toNSNumber) } +/** + * Converts an NSNumber to a Kotlin Int. + * + * @return The converted Kotlin Int value. + */ fun NSNumber.toKotlinInt(): Int { return this.intValue } +/** + * Converts a Kotlin String to an NSString object. + * + * @return The converted NSString object. + */ @OptIn(ExperimentalForeignApi::class, BetaInteropApi::class) fun String.toNSString(): NSString = memScoped { return NSString.create(string = this@toNSString) } +/** + * Converts an NSString to a Kotlin String. + * + * @return The converted Kotlin String. + */ fun NSString.toKotlinString(): String { return this.toString() } diff --git a/apollo/src/commonMain/kotlin/io/iohk/atala/prism/apollo/utils/X25519KeyPairGeneration.kt b/apollo/src/commonMain/kotlin/io/iohk/atala/prism/apollo/utils/X25519KeyPairGeneration.kt index 551e5bc51..56b73dddc 100644 --- a/apollo/src/commonMain/kotlin/io/iohk/atala/prism/apollo/utils/X25519KeyPairGeneration.kt +++ b/apollo/src/commonMain/kotlin/io/iohk/atala/prism/apollo/utils/X25519KeyPairGeneration.kt @@ -9,5 +9,10 @@ import kotlin.js.JsExport @ExperimentalJsExport @JsExport interface X25519KeyPairGeneration { + /** + * Generates a new X25519 key pair. + * + * @return the generated key pair as a [KMMX25519KeyPair] object. + */ fun generateKeyPair(): KMMX25519KeyPair } diff --git a/apollo/src/iosMain/kotlin/io/iohk/atala/prism/apollo/Platform.kt b/apollo/src/iosMain/kotlin/io/iohk/atala/prism/apollo/Platform.kt index a599c8777..e1053534d 100644 --- a/apollo/src/iosMain/kotlin/io/iohk/atala/prism/apollo/Platform.kt +++ b/apollo/src/iosMain/kotlin/io/iohk/atala/prism/apollo/Platform.kt @@ -6,5 +6,19 @@ import platform.UIKit.UIDevice * Provides information about the platform on which the application is running. */ public actual object Platform { + /** + * Represents the operating system of the current device. + * + * This property is platform-specific and its value depends on the device's operating system. + * For iOS devices, the value is a concatenation of the system name and version provided by the `UIDevice` class. + * + * Example usage: + * ```kotlin + * val platformName = OS + * println("Current OS: $platformName") + * ``` + * + * @see UIDevice + */ public actual val OS: String = "${UIDevice.currentDevice.systemName()}-${UIDevice.currentDevice.systemVersion}" } diff --git a/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/Platform.kt b/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/Platform.kt index 6bd78a315..743c6145e 100644 --- a/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/Platform.kt +++ b/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/Platform.kt @@ -4,5 +4,13 @@ package io.iohk.atala.prism.apollo * Provides information about the platform on which the application is running. */ public actual object Platform { + /** + * The current operating system. + * + * This property represents the name of the operating system. It is a string value that indicates the type of operating system + * that the code is running on. + * + * In this implementation, the value is set to "JS" which stands for JavaScript. This indicates that the code is running on a JavaScript platform. + */ public actual val OS: String = "JS" } diff --git a/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/hashing/external/HashJS.kt b/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/hashing/external/HashJS.kt index 50942d733..d5d62e5b9 100644 --- a/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/hashing/external/HashJS.kt +++ b/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/hashing/external/HashJS.kt @@ -1,14 +1,41 @@ package io.iohk.atala.prism.apollo.hashing.external +/** + * The `hash` variable is an instance of the `Hash` interface, which provides access to various hashing algorithms such as HMAC, Ripemd, and SHA. + * You can use this variable to perform cryptographic hashing operations. + * + * @property hmac An instance of the `HmacConstructor` interface, which is used to create HMAC objects for a specified hash algorithm. + * @property ripemd An instance of the `RipemdSet` interface, which provides access to the Ripemd160 hash algorithm. + * @property ripemd160 An instance of the `Ripemd160Constructor` interface, which is used to create Ripemd160 hash objects. + * @property sha An instance of the `ShaSet` interface, which provides access to the SHA hash algorithms (SHA1, SHA224, SHA256, SHA384, SHA512). + * @property sha1 An instance of the `Sha1Constructor` interface, which is used to create SHA1 hash objects. + * @property sha224 An instance of the `Sha224Constructor` interface, which is used to create SHA224 hash objects. + * @property sha256 An instance of the `Sha256Constructor` interface, which is used to create SHA256 hash objects. + * @property sha384 An instance of the `Sha384Constructor` interface, which is used to create SHA384 hash objects. + * @property sha512 An instance of the `Sha512Constructor` interface, which is used to create SHA512 hash objects. + * @property utils An instance of the `Utils` interface, which provides utility methods for converting input and output formats of hash values. + */ @JsModule("hash.js") internal external val hash: Hash +/** + * This interface represents a block hash algorithm. + * + * @param T the type of the block hash algorithm + */ internal external interface BlockHash { var hmacStrength: Number var padLength: Number var endian: String /* "big" | "little" */ } +/** + * The `MessageDigest` interface represents a cryptographic hash function that can be used to digest + * a message and produce a fixed-length output. It provides methods to update the message, retrieve + * the digest as an array of numbers, and retrieve the digest as a hex string. + * + * @param T the type of the implementing class + */ internal external interface MessageDigest { var blockSize: Number var outSize: Number @@ -17,6 +44,9 @@ internal external interface MessageDigest { fun digest(enc: String /* "hex" */): String } +/** + * Interface representing a Hash object. + */ internal external interface Hash { var hmac: HmacConstructor var ripemd: RipemdSet @@ -30,15 +60,24 @@ internal external interface Hash { var utils: Utils } +/** + * The Utils interface provides utility functions for converting data formats. + */ internal external interface Utils { fun toArray(msg: Any, enc: String /* "hex" */): Array fun toHex(msg: Any): String } +/** + * This interface represents a set of functions related to the RIPEMD-160 hashing algorithm. + */ internal external interface RipemdSet { var ripemd160: Ripemd160Constructor } +/** + * A set of SHA hash constructors. + */ internal external interface ShaSet { var sha1: Sha1Constructor var sha224: Sha224Constructor @@ -47,46 +86,86 @@ internal external interface ShaSet { var sha512: Sha512Constructor } +/** + * The interface HmacConstructor represents a constructor for Hmac object. + */ internal external interface HmacConstructor { @nativeInvoke operator fun invoke(hash: BlockHash, key: Any, enc: String /* "hex" */ = definedExternally): Hmac } +/** + * An external interface representing the constructor for the RIPEMD-160 hash function. + * + * This interface allows creating instances of the `Ripemd160` interface, which is both a `BlockHash` and a `MessageDigest`. + * + * The `Ripemd160` interface extends the `BlockHash` interface, which provides properties for the HMAC strength, padding length, and endianess. + * + * The `Ripemd160` interface also extends the `MessageDigest` interface, which provides properties for the block size and output size of the hash function. + * + * @see Ripemd160 + * @see BlockHash + * @see MessageDigest + */ internal external interface Ripemd160Constructor { @nativeInvoke operator fun invoke(): Ripemd160 } +/** + * The `Sha1Constructor` interface represents a constructor function for creating instances of the `Sha1` interface. + */ internal external interface Sha1Constructor { @nativeInvoke operator fun invoke(): Sha1 } +/** + * This interface represents a constructor for the SHA-224 algorithm. + */ internal external interface Sha224Constructor { @nativeInvoke operator fun invoke(): Sha224 } +/** + * An external interface representing a constructor for the SHA256 algorithm. + */ internal external interface Sha256Constructor { @nativeInvoke operator fun invoke(): Sha256 } +/** + * The Sha384Constructor interface represents a constructor function for the Sha384 interface, + * which is an implementation of the BlockHash and MessageDigest interfaces. + */ internal external interface Sha384Constructor { @nativeInvoke operator fun invoke(): Sha384 } +/** + * The `Sha512Constructor` interface represents a constructor function for creating instances of the `Sha512` interface. + */ internal external interface Sha512Constructor { @nativeInvoke operator fun invoke(): Sha512 } +/** + * Represents an HMAC (Hash-based Message Authentication Code). + * The HMAC class is an internal external interface that extends the MessageDigest interface. + * It provides methods for updating the digest with input data, generating the digest, and encoding the digest as a string. + */ internal external interface Hmac : MessageDigest { override var blockSize: Number /* 512 */ override var outSize: Number /* 160 */ } +/** + * The Ripemd160 interface represents the RIPEMD-160 hash function. + */ internal external interface Ripemd160 : BlockHash, MessageDigest { override var blockSize: Number /* 512 */ override var hmacStrength: Number /* 192 */ @@ -95,6 +174,14 @@ internal external interface Ripemd160 : BlockHash, MessageDigest, MessageDigest { override var blockSize: Number /* 512 */ override var hmacStrength: Number /* 80 */ @@ -103,6 +190,12 @@ internal external interface Sha1 : BlockHash, MessageDigest { override var endian: String /* "big" */ } +/** + * The `Sha224` class represents the SHA-224 hash algorithm. It implements the `BlockHash` and `MessageDigest` interfaces. + * + * @see BlockHash + * @see MessageDigest + */ internal external interface Sha224 : BlockHash, MessageDigest { override var blockSize: Number /* 512 */ override var hmacStrength: Number /* 192 */ @@ -111,6 +204,9 @@ internal external interface Sha224 : BlockHash, MessageDigest { override var endian: String /* "big" */ } +/** + * Represents the SHA256 algorithm for hashing and message digest operations. + */ internal external interface Sha256 : BlockHash, MessageDigest { override var blockSize: Number /* 512 */ override var hmacStrength: Number /* 192 */ @@ -119,6 +215,9 @@ internal external interface Sha256 : BlockHash, MessageDigest { override var endian: String /* "big" */ } +/** + * Represents an implementation of the SHA-384 hash function. + */ internal external interface Sha384 : BlockHash, MessageDigest { override var blockSize: Number /* 1024 */ override var hmacStrength: Number /* 192 */ @@ -127,6 +226,15 @@ internal external interface Sha384 : BlockHash, MessageDigest { override var endian: String /* "big" */ } +/** + * Sha512 is an internal external interface that extends both BlockHash and MessageDigest interfaces. + * It represents the SHA-512 hash algorithm. + * + * Please note that this documentation only focuses on the specific properties and methods provided by the Sha512 interface. + * + * @see BlockHash + * @see MessageDigest + */ internal external interface Sha512 : BlockHash, MessageDigest { override var blockSize: Number /* 1024 */ override var hmacStrength: Number /* 192 */ diff --git a/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/hashing/external/PBKD2F.kt b/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/hashing/external/PBKD2F.kt index 6dcb8b377..c5e3dc518 100644 --- a/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/hashing/external/PBKD2F.kt +++ b/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/hashing/external/PBKD2F.kt @@ -8,5 +8,14 @@ package io.iohk.atala.prism.apollo.hashing.external import kotlin.js.* import org.khronos.webgl.* +/** + * Derives a key from a password using the PBKDF2 algorithm. + * + * @param hash The hash function to use for key derivation. + * @param password The password used for key derivation. + * @param salt The salt value. + * @param opts Additional options for key derivation. + * @return The derived key as a Uint8Array. + */ external fun pbkdf2(hash: Any, password: String, salt: String, opts: dynamic): Uint8Array diff --git a/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/hashing/external/SHA512.kt b/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/hashing/external/SHA512.kt index 27a2bb215..c3e62c262 100644 --- a/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/hashing/external/SHA512.kt +++ b/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/hashing/external/SHA512.kt @@ -8,6 +8,16 @@ package io.iohk.atala.prism.apollo.hashing.external import org.khronos.webgl.* // ktlint-disable no-wildcard-imports import kotlin.js.* +/** + * The `Hashe` class is an open external class that represents a hash function. It provides methods for updating the hash state, computing the hash digest, destroying the hash object + *, and cloning the hash object. + * + * @param T the type parameter which must extend `Hashe` + * @property blockLen the length of the hash block + * @property outputLen the length of the hash output + * + * @constructor Creates a new instance of the `Hashe` class. + */ open external class Hashe> { open var blockLen: Number open var outputLen: Number @@ -19,6 +29,16 @@ open external class Hashe> { open fun _cloneInto(to: T = definedExternally): T open fun clone(): T } +/** + * SHA2 is a class that provides methods for computing SHA-2 hash functions. + * + * @param T the type of the subclass that extends SHA2 + * @property blockLen the length of the hash block + * @property outputLen the length of the hash output + * @property padOffset the padding offset + * @property isLE indicates whether the byte order is little endian + * @constructor Creates a SHA2 instance with the specified parameters. + */ open external class SHA2>(blockLen: Number, outputLen: Number, padOffset: Number, isLE: Boolean) : Hashe { override var blockLen: Number @@ -43,6 +63,9 @@ open external class SHA2>(blockLen: Number, outputLen: Number, padOf override fun _cloneInto(to: T): T } +/** + * The SHA512 class is an implementation of the SHA-512 hash algorithm. + */ open external class SHA512 : SHA2 { open var Ah: Number open var Al: Number @@ -67,6 +90,9 @@ open external class SHA512 : SHA2 { override fun destroy() } +/** + * The sha512 class provides a platform-specific implementation for generating SHA-512 hash. + */ external object sha512 { @nativeInvoke operator fun invoke(message: Any): Uint8Array @@ -75,6 +101,8 @@ external object sha512 { fun create(): Any } +/** + * A class representing the SHA-512*/ external object sha512_224 { @nativeInvoke operator fun invoke(message: Any): Uint8Array @@ -83,6 +111,8 @@ external object sha512_224 { fun create(): Any } +/** + * The `sha512_256` class represents an object that can compute SHA-512*/ external object sha512_256 { @nativeInvoke operator fun invoke(message: Any): Uint8Array @@ -91,6 +121,9 @@ external object sha512_256 { fun create(): Any } +/** + * The `sha384` class provides functions for computing the SHA-384 hash. + */ external object sha384 { @nativeInvoke operator fun invoke(message: Any): Uint8Array diff --git a/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/secp256k1/Secp256k1Lib.kt b/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/secp256k1/Secp256k1Lib.kt index 14a23da9f..1f39e53ce 100644 --- a/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/secp256k1/Secp256k1Lib.kt +++ b/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/secp256k1/Secp256k1Lib.kt @@ -11,11 +11,29 @@ import io.iohk.atala.prism.apollo.utils.external.secp256k1.secp256k1 import io.iohk.atala.prism.apollo.utils.toHexString import org.kotlincrypto.hash.sha2.SHA256 +/** + * This class provides utility methods for working with a specific implementation of the secp256k1 elliptic curve cryptography. + * It supports generating public keys, deriving private keys, signing data, verifying signatures, and compressing/uncompressing public keys. + */ actual class Secp256k1Lib actual constructor() { + /** + * Creates a public key from a given private key. + * + * @param privateKey The private key in byte array format. + * @param compressed A boolean indicating whether the public key should be compressed. + * @return A byte array representing the public key. + */ actual fun createPublicKey(privateKey: ByteArray, compressed: Boolean): ByteArray { return secp256k1.getPublicKey(privateKey.asUint8Array(), compressed).asByteArray() } + /** + * Derives a new private key from an existing private key and derived bytes. + * + * @param privateKeyBytes The original private key in byte array format. + * @param derivedPrivateKeyBytes The byte array used for deriving the new private key. + * @return A byte array representing the derived private key, or null if derivation fails. + */ actual fun derivePrivateKey(privateKeyBytes: ByteArray, derivedPrivateKeyBytes: ByteArray): ByteArray? { val privKeyString = privateKeyBytes.toHexString() val derivedPrivKeyString = derivedPrivateKeyBytes.toHexString() @@ -27,6 +45,13 @@ actual class Secp256k1Lib actual constructor() { return added.toByteArray() } + /** + * Signs the given data using the provided private key. + * + * @param privateKey The private key used for signing the data. + * @param data The data to be signed. + * @return The signature of the data in DER format. + */ actual fun sign(privateKey: ByteArray, data: ByteArray): ByteArray { // TODO: "Using noble/secp256k1 would be problematic since it requires a configuration so it can use Sync methods to sign, also it doesnt have DER signatures") val sha = SHA256().digest(data) @@ -37,6 +62,14 @@ actual class Secp256k1Lib actual constructor() { return derSignature.decodeHex() } + /** + * Verifies the signature of the given data using the provided public key. + * + * @param publicKey The public key used for verification. + * @param signature The signature to be verified. + * @param data The data to be verified. + * @return true if the signature is valid, false otherwise. + */ actual fun verify( publicKey: ByteArray, signature: ByteArray, @@ -47,6 +80,12 @@ actual class Secp256k1Lib actual constructor() { return ecjs.verify(sha.toHexString(), signature.toHexString(), publicKey.toHexString(), enc = "hex") } + /** + * Converts a compressed public key to an uncompressed public key. + * + * @param compressed The compressed public key as a byte array. + * @return The uncompressed public key as a byte array. + */ @OptIn(ExperimentalUnsignedTypes::class) actual fun uncompressPublicKey(compressed: ByteArray): ByteArray { val ecjs = ec("secp256k1") @@ -60,6 +99,12 @@ actual class Secp256k1Lib actual constructor() { return byteArrayOf(header) + x + y } + /** + * Compresses an uncompressed public key. + * + * @param uncompressed The uncompressed public key to compress. + * @return The compressed public key. + */ actual fun compressPublicKey(uncompressed: ByteArray): ByteArray { val ecjs = ec("secp256k1") val pubKeyBN = BN(ecjs.keyFromPublic(uncompressed.asUint8Array()).getPublic().encodeCompressed()) diff --git a/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/securerandom/SecureRandom.kt b/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/securerandom/SecureRandom.kt index 67725a84f..3290871d5 100644 --- a/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/securerandom/SecureRandom.kt +++ b/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/securerandom/SecureRandom.kt @@ -28,6 +28,12 @@ actual class SecureRandom actual constructor( } actual companion object : SecureRandomStaticInterface { + /** + * Generates a random seed of specified length in bytes. + * + * @param numBytes The length of the seed in bytes. + * @return The generated seed as a ByteArray. + */ override fun generateSeed(numBytes: Int): ByteArray { val arr = Uint8Array(numBytes) return if (isNode) { diff --git a/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/ArrayBufferExt.kt b/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/ArrayBufferExt.kt index 9acaeab7d..e520efcfb 100644 --- a/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/ArrayBufferExt.kt +++ b/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/ArrayBufferExt.kt @@ -3,4 +3,9 @@ package io.iohk.atala.prism.apollo.utils import js.buffer.ArrayBuffer import js.typedarrays.Int8Array +/** + * Converts a ByteArray to an ArrayBuffer. + * + * @return The resulting ArrayBuffer. + */ fun ByteArray.toArrayBuffer(): ArrayBuffer = this.unsafeCast().buffer diff --git a/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/BufferExt.kt b/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/BufferExt.kt index f9020d047..b556a02e2 100644 --- a/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/BufferExt.kt +++ b/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/BufferExt.kt @@ -3,6 +3,10 @@ package io.iohk.atala.prism.apollo.utils import js.core.get import node.buffer.Buffer +/** + * Converts the Buffer to a ByteArray. + * @return ByteArray - the converted ByteArray. + */ fun Buffer.toByteArray(): ByteArray { val byteArray = ByteArray(length) for (i in byteArray.indices) { diff --git a/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/ByteArrayExt.kt b/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/ByteArrayExt.kt index 7a7cb1045..89ce3961f 100644 --- a/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/ByteArrayExt.kt +++ b/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/ByteArrayExt.kt @@ -4,5 +4,16 @@ import js.buffer.ArrayBuffer import org.khronos.webgl.Int8Array import org.khronos.webgl.Uint8Array +/** + * Converts the ArrayBuffer to a ByteArray. + * + * @return The converted ByteArray. + */ fun ArrayBuffer.toByteArray(): ByteArray = js.typedarrays.Int8Array(this).unsafeCast() +/** + * Converts a ByteArray to a Uint8Array. + * + * @receiver The ByteArray to convert. + * @return The converted Uint8Array. + */ fun ByteArray.asUint8Array() = unsafeCast().run { Uint8Array(buffer, byteOffset, length) } diff --git a/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/Curve25519Parser.kt b/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/Curve25519Parser.kt index ad0d19fb7..adb746576 100644 --- a/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/Curve25519Parser.kt +++ b/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/Curve25519Parser.kt @@ -3,6 +3,13 @@ package io.iohk.atala.prism.apollo.utils import io.iohk.atala.prism.apollo.base64.base64UrlDecodedBytes import node.buffer.Buffer +/** + * The Curve25519Parser object provides methods for parsing byte arrays into raw key values. + * It supports parsing both encoded and raw data. + * + * @property encodedLength The length of the encoded key value. + * @property rawLength The length of the raw key value. + */ @OptIn(ExperimentalJsExport::class) @JsExport object Curve25519Parser { diff --git a/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/Int8ArrayExt.kt b/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/Int8ArrayExt.kt index a1f4bc81b..e06a4b3db 100644 --- a/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/Int8ArrayExt.kt +++ b/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/Int8ArrayExt.kt @@ -3,4 +3,10 @@ package io.iohk.atala.prism.apollo.utils import org.khronos.webgl.Int8Array import org.khronos.webgl.Uint8Array +/** + * Converts a Uint8Array to a ByteArray. + * + * @receiver The Uint8Array to convert. + * @return The converted ByteArray. + */ fun Uint8Array.asByteArray() = Int8Array(buffer, byteOffset, length).unsafeCast() diff --git a/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMECPointJS.kt b/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMECPointJS.kt index 495ae4f86..ecba516e1 100644 --- a/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMECPointJS.kt +++ b/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMECPointJS.kt @@ -2,6 +2,16 @@ package io.iohk.atala.prism.apollo.utils import io.iohk.atala.prism.apollo.utils.external.BN +/** + * Represents a point on an elliptic curve in JavaScript. + * + * @property x The x-coordinate of the point. + * @property y The y-coordinate of the point. + * @constructor Creates a new `KMMECPointJS` object. + * + * @param x The x-coordinate of the point. + * @param y The y-coordinate of the point. + */ @OptIn(ExperimentalJsExport::class) @JsExport data class KMMECPointJS(val x: BN, val y: BN) diff --git a/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMEdKeyPair.kt b/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMEdKeyPair.kt index 3974cda82..4bf6875de 100644 --- a/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMEdKeyPair.kt +++ b/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMEdKeyPair.kt @@ -4,21 +4,45 @@ import io.iohk.atala.prism.apollo.utils.external.eddsa import io.iohk.atala.prism.apollo.utils.external.rand import node.buffer.Buffer +/** + * Represents a pair of cryptographic keys - a private key and a public key. + * + * @property privateKey The private key of the key pair. + * @property publicKey The public key of the key pair. + */ @OptIn(ExperimentalJsExport::class) @JsExport actual class KMMEdKeyPair actual constructor( actual val privateKey: KMMEdPrivateKey, actual val publicKey: KMMEdPublicKey ) { + /** + * Cryptographically sign a given message. + * + * @param message The message to be signed. + * @return The signature of the message. + */ actual fun sign(message: ByteArray): ByteArray { return privateKey.sign(message) } + /** + * Confirms a message signature was signed with the corresponding PrivateKey. + * + * @param message The message that was signed. + * @param sig The signature. + * @return Returns true if the signature matches the original message, false otherwise. + */ actual fun verify(message: ByteArray, sig: ByteArray): Boolean { return publicKey.verify(message, sig) } actual companion object : Ed25519KeyPairGeneration { + /** + * Generates a pair of cryptographic keys - a private key and a public key. + * + * @return The generated key pair. + */ override fun generateKeyPair(): KMMEdKeyPair { val ed25519 = eddsa("ed25519") val rnd = rand(32) diff --git a/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMEdPrivateKey.kt b/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMEdPrivateKey.kt index 3c792750a..35f4b3584 100644 --- a/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMEdPrivateKey.kt +++ b/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMEdPrivateKey.kt @@ -4,6 +4,14 @@ import io.iohk.atala.prism.apollo.base64.base64UrlEncoded import io.iohk.atala.prism.apollo.utils.external.eddsa import node.buffer.Buffer +/** + * Represents a private key in the KMMEd cryptographic system. + * + * @property raw The raw value of the private key. + * @property keyPair The key pair object associated with the private key. + * @constructor Creates a KMMEdPrivateKey object. + * @param bytes The byte array representing the private key. + */ @OptIn(ExperimentalJsExport::class) @JsExport actual class KMMEdPrivateKey(bytes: ByteArray) { diff --git a/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMEdPublicKey.kt b/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMEdPublicKey.kt index 3c0b85e89..92fdae610 100644 --- a/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMEdPublicKey.kt +++ b/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMEdPublicKey.kt @@ -5,6 +5,14 @@ import io.iohk.atala.prism.apollo.utils.external.eddsa import node.buffer.Buffer import node.buffer.BufferEncoding +/** + * Represents a public key in the KMMEd cryptographic system. + * + * @property raw The raw value of the public key. + * @property keyPair The key pair object associated with the public key. + * @constructor Creates a KMMEdPublicKey object. + * @param bytes The byte array representing the public key. + */ @OptIn(ExperimentalJsExport::class) @JsExport actual class KMMEdPublicKey(bytes: ByteArray) { diff --git a/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMX25519KeyPair.kt b/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMX25519KeyPair.kt index 07d165e7f..5a32167f1 100644 --- a/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMX25519KeyPair.kt +++ b/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMX25519KeyPair.kt @@ -2,6 +2,12 @@ package io.iohk.atala.prism.apollo.utils import io.iohk.atala.prism.apollo.utils.external.generateKeyPair as stableLibGenerateKeyPair +/** + * Represents a key pair for the X25519 elliptic curve encryption algorithm. + * + * @property privateKey The private key of the key pair. + * @property publicKey The public key of the key pair. + */ @OptIn(ExperimentalJsExport::class) @JsExport actual class KMMX25519KeyPair actual constructor( @@ -9,6 +15,11 @@ actual class KMMX25519KeyPair actual constructor( actual val publicKey: KMMX25519PublicKey ) { actual companion object : X25519KeyPairGeneration { + /** + * Generates a key pair using the X25519 elliptic curve encryption algorithm. + * + * @return The generated key pair as a [KMMX25519KeyPair] object. + */ override fun generateKeyPair(): KMMX25519KeyPair { val keyPair = stableLibGenerateKeyPair() diff --git a/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMX25519PrivateKey.kt b/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMX25519PrivateKey.kt index e049ffd31..38385b049 100644 --- a/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMX25519PrivateKey.kt +++ b/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMX25519PrivateKey.kt @@ -5,6 +5,11 @@ import io.iohk.atala.prism.apollo.utils.external.KeyPair import io.iohk.atala.prism.apollo.utils.external.generateKeyPairFromSeed import node.buffer.Buffer +/** + * Represents a private key for the X25519 elliptic curve encryption algorithm. + * + * @property raw The binary representation of the private key. + */ @OptIn(ExperimentalJsExport::class) @JsExport actual class KMMX25519PrivateKey(bytes: ByteArray) { @@ -32,6 +37,11 @@ actual class KMMX25519PrivateKey(bytes: ByteArray) { return KMMX25519PublicKey(publicBytes) } + /** + * Retrieves an instance of `KeyPair` by generating it from the given raw private key. + * + * @return The generated `KeyPair` object containing the public key and secret key. + */ private fun getInstance(): KeyPair { return generateKeyPairFromSeed(raw) } diff --git a/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMX25519PublicKey.kt b/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMX25519PublicKey.kt index 710756aec..b7a3a1207 100644 --- a/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMX25519PublicKey.kt +++ b/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMX25519PublicKey.kt @@ -3,6 +3,12 @@ package io.iohk.atala.prism.apollo.utils import io.iohk.atala.prism.apollo.base64.base64UrlEncoded import node.buffer.Buffer +/** + * Represents a public key for the X25519 elliptic curve encryption algorithm. + * + * @property raw The binary representation of the public key. + * @constructor Creates a new instance of [KMMX25519PublicKey] with the given raw value. + */ @OptIn(ExperimentalJsExport::class) @JsExport actual class KMMX25519PublicKey(bytes: ByteArray) { diff --git a/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/external/BIP32.kt b/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/external/BIP32.kt index 0cd1e4278..ce0e3212b 100644 --- a/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/external/BIP32.kt +++ b/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/external/BIP32.kt @@ -7,11 +7,17 @@ package io.iohk.atala.prism.apollo.utils.external import node.buffer.Buffer import kotlin.js.* +/** + * Represents a key pair for BIP32 (Bitcoin Improvement Proposal 32). + */ internal external interface Bip32KeyPair { var public: Number var private: Number } +/** + * Represents a network configuration. + */ internal external interface Network { var wif: Number var bip32: Bip32KeyPair @@ -29,6 +35,20 @@ internal external interface Network { set(value) = definedExternally } +/** + * BIP32Interface represents an interface for working with BIP32 keys. + * + * @property chainCode The chain code associated with the key. + * @property network The network associated with the key. + * @property lowR A flag indicating whether the key uses low R values. + * @property depth The depth of the key in the hierarchical path. + * @property index The index of the key in the hierarchical path. + * @property parentFingerprint The fingerprint of the parent key. + * @property publicKey The public key associated with the key. + * @property privateKey The private key associated with the key. This property can be null. + * @property identifier The identifier of the key. + * @property fingerprint The fingerprint of the key. + */ internal external interface BIP32Interface { var chainCode: Buffer var network: Network @@ -53,10 +73,40 @@ internal external interface BIP32Interface { fun verify(hash: Buffer, signature: Buffer): Boolean } +/** + * Converts a Base58 encoded string to a BIP32Interface object. + * + * @param inString The Base58 encoded string to convert. + * @param network The network to use for the BIP32Interface object. Default is the defined external network. + * @return The BIP32Interface object representing the decoded Base58 string. + */ internal external fun fromBase58(inString: String, network: Network = definedExternally): BIP32Interface +/** + * Creates a BIP32Interface instance from a private key, chain code, and optional network parameter. + * + * @param privateKey the private key as a Buffer + * @param chainCode the chain code as a Buffer + * @param network the optional network parameter, defaults to undefined + * @return a BIP32Interface instance + */ internal external fun fromPrivateKey(privateKey: Buffer, chainCode: Buffer, network: Network = definedExternally): BIP32Interface +/** + * Constructs a BIP32Interface object from a public key, chain code, and network. + * + * @param publicKey The public key. + * @param chainCode The chain code. + * @param network The network (optional). + * @return The BIP32Interface object. + */ internal external fun fromPublicKey(publicKey: Buffer, chainCode: Buffer, network: Network = definedExternally): BIP32Interface +/** + * Creates a BIP32Interface object from the given seed. + * + * @param seed The seed to generate the BIP32Interface object from. + * @param network The network to use for generating the BIP32Interface object. Defaults to the value definedExternally. + * @return The generated BIP32Interface object. + */ internal external fun fromSeed(seed: Buffer, network: Network = definedExternally): BIP32Interface diff --git a/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/external/BIP39.kt b/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/external/BIP39.kt index 5b161a0bb..c1788fdc9 100644 --- a/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/external/BIP39.kt +++ b/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/external/BIP39.kt @@ -7,24 +7,100 @@ package io.iohk.atala.prism.apollo.utils.external import node.buffer.Buffer import kotlin.js.* +/** + * Converts a mnemonic string into a cryptographic seed. + * + * @param mnemonic The mnemonic string to convert. + * @param password The optional password to use during seed conversion. + * @return The cryptographic seed as a `Buffer` object. + */ internal external fun mnemonicToSeedSync(mnemonic: String, password: String = definedExternally): Buffer +/** + * Generates a cryptographic seed from a mnemonic phrase. + * + * @param mnemonic The mnemonic phrase to generate the seed from. + * @param password A string used as an optional password to salt the seed generation. + * + * @return A Promise that resolves to a Buffer containing the generated seed. + */ internal external fun mnemonicToSeed(mnemonic: String, password: String = definedExternally): Promise +/** + * Converts a mnemonic phrase to its corresponding entropy value. + * + * @param mnemonic The mnemonic phrase to be converted to entropy. + * @param wordlist The array of words from which the mnemonic phrase is constructed. + * Defaults to a predefined wordlist if not provided. + * @return The entropy value corresponding to the given mnemonic phrase. + */ internal external fun mnemonicToEntropy(mnemonic: String, wordlist: Array = definedExternally): String +/** + * Converts an entropy buffer to a mnemonic phrase. + * + * @param entropy The entropy buffer used to generate the mnemonic phrase. + * @param wordlist The wordlist to use when generating the mnemonic phrase. By default, it uses the externally defined wordlist. + * @throws Error If the entropy buffer is invalid or if the wordlist is not provided. + * @return The converted mnemonic phrase. + */ internal external fun entropyToMnemonic(entropy: Buffer, wordlist: Array = definedExternally): String +/** + * Converts the given [entropy] to a mnemonic phrase. + * + * @param entropy The entropy to be converted. + * @return The generated mnemonic phrase. + */ internal external fun entropyToMnemonic(entropy: Buffer): String +/** + * Converts the given entropy to a mnemonic phrase using the specified wordlist. + * + * @param entropy The entropy as a string. + * @param wordlist (Optional) The wordlist to use for generating the mnemonic. If not provided, a default wordlist will be used. + * + * @return The generated mnemonic phrase as a string. + */ internal external fun entropyToMnemonic(entropy: String, wordlist: Array = definedExternally): String +/** + * Converts a given entropy string to a corresponding mnemonic string. + * + * @param entropy The entropy string to be converted. + * @return The mnemonic string representing the given entropy. + */ internal external fun entropyToMnemonic(entropy: String): String +/** + * Generates a mnemonic phrase based on the given parameters. + * + * @param strength the strength of the mnemonic (optional) + * @param rng a random number generator function (optional) + * @param wordlist an array of words to be used in the mnemonic (optional) + * @return the generated mnemonic phrase + */ internal external fun generateMnemonic(strength: Number = definedExternally, rng: (size: Number) -> Buffer = definedExternally, wordlist: Array = definedExternally): String +/** + * Validates the provided mnemonic using the specified wordlist. + * + * @param mnemonic The mnemonic to be validated. + * @param wordlist The wordlist to be used for validation. (optional) + * @return `true` if the mnemonic is valid, `false` otherwise. + */ internal external fun validateMnemonic(mnemonic: String, wordlist: Array = definedExternally): Boolean +/** + * Sets the default wordlist for the specified language. + * + * @param language the language for which the default wordlist is to be set. + */ internal external fun setDefaultWordlist(language: String) +/** + * Retrieves the default wordlist. + * + * @return The default wordlist as a String. + */ internal external fun getDefaultWordlist(): String diff --git a/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/external/BNjs.kt b/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/external/BNjs.kt index b9334bff9..c4b666fe4 100644 --- a/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/external/BNjs.kt +++ b/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/external/BNjs.kt @@ -7,12 +7,31 @@ package io.iohk.atala.prism.apollo.utils.external import org.khronos.webgl.* import kotlin.js.* +/** + * The EGCD interface represents an object that holds the result of the Extended Euclidean Algorithm (EGCD) + * for two numbers a and b, along with their greatest common divisor (gcd). + * + * @property a The first number for which the EGCD is computed. + * @property b The second number for which the EGCD is computed. + * @property gcd The greatest common divisor (gcd) of a and b. + */ external interface EGCD { var a: BN var b: BN var gcd: BN } +/** + * The `BN` class is a JavaScript wrapper around the `bn.js` library, which provides + * a fast and efficient implementation of big numbers for cryptographic purposes. + * + * @constructor Creates a new `BN` object. + * + * @param number The number to initialize the `BN` object with. It can be either a + * `Number`, `String`, `Array`, or `Uint8Array`. + * @param base The numeric base of the input number. Defaults to 10. + * @param endian The endianness of the input number. Defaults to "be" (big-endian). + */ @JsModule("bn.js") open external class BN { constructor(number: Number, base: Number = definedExternally, endian: String = definedExternally) @@ -162,6 +181,10 @@ open external class BN { } } +/** + * The RedBN class is a subclass of the BN class. It represents a big number in a redc representation, + * where reduction by a modulus is used for certain mathematical operations. + */ open external class RedBN : BN { constructor(number: Number, base: Number = definedExternally, endian: String = definedExternally) constructor(number: Number) diff --git a/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/external/Curve.kt b/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/external/Curve.kt index c387bac02..1e68b8bc1 100644 --- a/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/external/Curve.kt +++ b/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/external/Curve.kt @@ -8,6 +8,13 @@ package io.iohk.atala.prism.apollo.utils.external import org.khronos.webgl.Uint8Array +/** + * Represents a base curve. + * + * @constructor Creates a base curve with the specified type and configuration options. + * @param type The type of the curve. + * @param conf The configuration options for the curve. + */ open external class base(type: String, conf: BaseCurveOptions) { open var p: Any open var type: String @@ -65,6 +72,15 @@ open external class base(type: String, conf: BaseCurveOptions) { } } +/** + * Represents an Edwards curve. + * + * @property a The `a` parameter of the curve. + * @property c The `c` parameter of the curve. + * @property c2 The `c2` parameter of the curve. + * @property d The `d` parameter of the curve. + * @property dd The `dd` parameter of the curve. + */ open external class edwards(conf: EdwardsConf) : base { open var a: Any open var c: Any @@ -128,6 +144,10 @@ open external class edwards(conf: EdwardsConf) : base { } } +/** + * Represents a short form elliptic curve. + * @param conf The configuration options for the curve. + */ open external class short(conf: ShortConf) : base { open var a: dynamic /* String | BN | Number | Buffer | Uint8Array | ReadonlyArray */ open var b: dynamic /* String | BN | Number | Buffer | Uint8Array | ReadonlyArray */ diff --git a/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/external/Ellipticjs.kt b/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/external/Ellipticjs.kt index 946e73005..e0db9e56b 100644 --- a/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/external/Ellipticjs.kt +++ b/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/external/Ellipticjs.kt @@ -11,17 +11,39 @@ import io.iohk.atala.prism.apollo.utils.external.eddsa.KeyPair as _eddsa_KeyPair import io.iohk.atala.prism.apollo.utils.external.eddsa.KeyPairOptions as _eddsa_KeyPairOptions import io.iohk.atala.prism.apollo.utils.external.eddsa.Signature as _eddsa_Signature +/** + * Utility class for various operations. + */ external var utils: Any +/** + * Generates an array of random numbers. + * + * @param len The length of the array. + * @return An array of random numbers. + */ external fun rand(len: Number): Uint8Array +/** + * The current version of the software. + * This variable is external and holds a numeric value representing the version number. + * It is used to keep track of the software's version for informational purposes. + */ external var version: Number +/** + * Represents a set of coordinates in a two-dimensional space. + */ external interface Coordinates { var x: String var y: String } +/** + * The `curve` class provides methods for working with elliptic curves in cryptography. + * + * @class + */ external object curve { open class base { companion object { @@ -38,6 +60,15 @@ external object curve { } } +/** + * The `ec` class represents an elliptic curve cryptography object. It provides methods for generating key pairs, signing and verifying messages, and recovering public keys. + * + * @property curve the elliptic curve used by the `ec` object + * @property n the order of the elliptic curve group + * @property nh a precomputed value used in the `recoverPubKey` function + * @property g the generator point of the elliptic curve group + * @property hash the hash function used in the `sign` and `verify` functions + */ open external class ec { open var curve: curve.base open var n: BN @@ -220,6 +251,11 @@ open external class ec { } } +/** + * Represents an EdDSA cryptographic system. + * + * @param name The name of the curve ("ed25519"). + */ open external class eddsa(name: String /* "ed25519" */) { open var curve: edwards open fun sign(message: String, secret: String): _eddsa_Signature diff --git a/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/external/PresetCurve.kt b/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/external/PresetCurve.kt index 855ad71eb..2abfe9189 100644 --- a/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/external/PresetCurve.kt +++ b/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/external/PresetCurve.kt @@ -6,6 +6,11 @@ package io.iohk.atala.prism.apollo.utils.external +/** + * A class representing a preset curve. + * + * @param options The options for the preset curve. + */ open external class PresetCurve(options: Options) { open var type: String open var g: Any diff --git a/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/external/Stabelib.kt b/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/external/Stabelib.kt index dc961e0d6..a93efa589 100644 --- a/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/external/Stabelib.kt +++ b/apollo/src/jsMain/kotlin/io/iohk/atala/prism/apollo/utils/external/Stabelib.kt @@ -6,23 +6,89 @@ package io.iohk.atala.prism.apollo.utils.external import js.typedarrays.Uint8Array +/** + * The length of a public key. + * + * This variable represents the length of a public key used in cryptographic algorithms. + * The value of this variable can vary depending on the specific cryptographic algorithm used. + * It is recommended to check the documentation of the cryptographic library or API being used + * to determine the exact value of this variable for a particular algorithm. + * + * @see `T$0` } +/** + * A class representing the `T$2` interface. + * + * @property nBitLength The bit length of `n`. + * @property nByteLength The byte length of `n`. + * @property Fp The value of `Fp`. + * @property n The value of `n`. + * @property h The value of `h`. + * @property hEff The effective value of `h`. + * @property Gx The value of `Gx`. + * @property Gy The value of `Gy`. + * @property allowInfinityPoint A flag indicating whether the infinity point is allowed. + * @property a The value of `a`. + * @property b The value of `b`. + * @property allowedPrivateKeyLengths An array of allowed private key lengths. + * @property wrapPrivateKey A flag indicating whether the private key should be wrapped. + * @property endo The endomorphism parameters. + * @property hash The hashing algorithm. + * @property hmac The HMAC function. + * @property randomBytes The function to generate random bytes. + * @property lowS A flag indicating whether low values of `S` are required. + * @property bits2int The function to convert bits to an integer. + * @property bits2int_modN The function to convert bits to an integer modulo `N`. + * @property p The value of `p`. + */ external interface `T$2` { var nBitLength: Number var nByteLength: Number @@ -72,6 +115,9 @@ external interface `T$2` { var p: Any } +/** + * Represents the interface `T$4`. + */ external interface `T$4` { var normPrivateKeyToScalar: (key: dynamic /* Uint8Array | String | Any */) -> Any fun isValidPrivateKey(privateKey: Uint8Array): Boolean @@ -80,6 +126,9 @@ external interface `T$4` { var randomPrivateKey: () -> Uint8Array } +/** + * Represents an external interface `T$5`. + */ external interface `T$5` { var create: (hash: Any) -> Any var CURVE:`T$2` @@ -93,4 +142,7 @@ external interface `T$5` { } +/** + * Represents the secp256k1 variable. + */ external var secp256k1: `T$5` diff --git a/apollo/src/jvmMain/kotlin/io/iohk/atala/prism/apollo/Platform.kt b/apollo/src/jvmMain/kotlin/io/iohk/atala/prism/apollo/Platform.kt index 31afaaad2..03e4f774a 100644 --- a/apollo/src/jvmMain/kotlin/io/iohk/atala/prism/apollo/Platform.kt +++ b/apollo/src/jvmMain/kotlin/io/iohk/atala/prism/apollo/Platform.kt @@ -4,5 +4,8 @@ package io.iohk.atala.prism.apollo * Provides information about the platform on which the application is running. */ public actual object Platform { + /** + * Represents the operating system on which the application is running. + */ public actual val OS: String = "JVM" } diff --git a/apollo/src/jvmMain/kotlin/io/iohk/atala/prism/apollo/secp256k1/Secp256k1Lib.kt b/apollo/src/jvmMain/kotlin/io/iohk/atala/prism/apollo/secp256k1/Secp256k1Lib.kt index 73ab01faf..0b3e208c4 100644 --- a/apollo/src/jvmMain/kotlin/io/iohk/atala/prism/apollo/secp256k1/Secp256k1Lib.kt +++ b/apollo/src/jvmMain/kotlin/io/iohk/atala/prism/apollo/secp256k1/Secp256k1Lib.kt @@ -3,6 +3,10 @@ package io.iohk.atala.prism.apollo.secp256k1 import fr.acinq.secp256k1.Secp256k1 import org.kotlincrypto.hash.sha2.SHA256 +/** + * This class provides various Secp256k1 cryptographic functionalities such as creating public keys, signing data, + * verifying signatures, and compressing or decompressing public keys. + */ actual class Secp256k1Lib { actual fun createPublicKey(privateKey: ByteArray, compressed: Boolean): ByteArray { val pubKey = Secp256k1.pubkeyCreate(privateKey) @@ -16,6 +20,13 @@ actual class Secp256k1Lib { } } + /** + * Derives a new private key from an existing private key and derived bytes. + * + * @param privateKeyBytes The original private key in byte array format. + * @param derivedPrivateKeyBytes The byte array used for deriving the new private key. + * @return A byte array representing the derived private key, or null if derivation fails. + */ actual fun derivePrivateKey( privateKeyBytes: ByteArray, derivedPrivateKeyBytes: ByteArray @@ -23,12 +34,27 @@ actual class Secp256k1Lib { return Secp256k1.privKeyTweakAdd(privateKeyBytes, derivedPrivateKeyBytes) } + /** + * Signs data using a given private key. + * + * @param privateKey The private key used for signing, in byte array format. + * @param data The data to be signed, in byte array format. + * @return A byte array representing the signature. + */ actual fun sign(privateKey: ByteArray, data: ByteArray): ByteArray { val sha = SHA256().digest(data) val compactSignature = Secp256k1.sign(sha, privateKey) return Secp256k1.compact2der(compactSignature) } + /** + * Verifies a signature against a public key and data. + * + * @param publicKey The public key in byte array format. + * @param signature The signature to be verified, in byte array format. + * @param data The data against which the signature will be verified, in byte array format. + * @return A boolean indicating whether the signature is valid. + */ actual fun verify( publicKey: ByteArray, signature: ByteArray, @@ -38,10 +64,22 @@ actual class Secp256k1Lib { return Secp256k1.verify(signature, sha, publicKey) } + /** + * Decompresses a compressed public key. + * + * @param compressed The compressed public key in byte array format. + * @return A byte array representing the uncompressed public key. + */ actual fun uncompressPublicKey(compressed: ByteArray): ByteArray { return Secp256k1.pubkeyParse(compressed) } + /** + * Compresses an uncompressed public key. + * + * @param uncompressed The uncompressed public key in byte array format. + * @return A byte array representing the compressed public key. + */ actual fun compressPublicKey(uncompressed: ByteArray): ByteArray { return Secp256k1.pubKeyCompress(uncompressed) } diff --git a/apollo/src/jvmMain/kotlin/io/iohk/atala/prism/apollo/securerandom/SecureRandom.kt b/apollo/src/jvmMain/kotlin/io/iohk/atala/prism/apollo/securerandom/SecureRandom.kt index d8515f0ab..86c1b7528 100644 --- a/apollo/src/jvmMain/kotlin/io/iohk/atala/prism/apollo/securerandom/SecureRandom.kt +++ b/apollo/src/jvmMain/kotlin/io/iohk/atala/prism/apollo/securerandom/SecureRandom.kt @@ -2,10 +2,14 @@ package io.iohk.atala.prism.apollo.securerandom /** * The SecureRandom class provides a platform-specific implementation for generating secure random numbers. + * + * @property seed The seed value used for initializing the random number generator. + * + * @see [java.security.SecureRandom] */ actual class SecureRandom actual constructor( actual val seed: ByteArray -) : SecureRandomInterface { +) : SecureRandomInterface, java.security.SecureRandom() { /** * The `jvmSecureRandom` variable is a private property of type `java.security.SecureRandom`. It is used for generating secure random numbers on the JVM platform. * diff --git a/apollo/src/jvmMain/kotlin/io/iohk/atala/prism/apollo/utils/JVMBigIntegerExt.kt b/apollo/src/jvmMain/kotlin/io/iohk/atala/prism/apollo/utils/JVMBigIntegerExt.kt index d230cdc2e..e5db4d329 100644 --- a/apollo/src/jvmMain/kotlin/io/iohk/atala/prism/apollo/utils/JVMBigIntegerExt.kt +++ b/apollo/src/jvmMain/kotlin/io/iohk/atala/prism/apollo/utils/JVMBigIntegerExt.kt @@ -3,10 +3,22 @@ package io.iohk.atala.prism.apollo.utils import com.ionspin.kotlin.bignum.integer.Sign import java.math.BigInteger +/** + * Converts a BigInteger to an unsigned byte array. + * + * @return the unsigned byte array representation of the BigInteger + */ fun BigInteger.toUnsignedByteArray(): ByteArray { return toByteArray().dropWhile { it == 0.toByte() }.toByteArray() } +/** + * Converts a Java BigInteger to the KotlinBigInteger class from the com.ionspin.kotlin.bignum.integer package. + * + * @return The KotlinBigInteger representation of the Java BigInteger. + * @throws IllegalStateException if the signum of the Java BigInteger is not -1, 0, or 1. + * @see BigInteger.toUnsignedByteArray + */ fun BigInteger.toKotlinBigInteger(): com.ionspin.kotlin.bignum.integer.BigInteger { val sign = when (this.signum()) { -1 -> Sign.NEGATIVE @@ -17,6 +29,11 @@ fun BigInteger.toKotlinBigInteger(): com.ionspin.kotlin.bignum.integer.BigIntege return com.ionspin.kotlin.bignum.integer.BigInteger.fromByteArray(this.toUnsignedByteArray(), sign) } +/** + * Converts a `BigInteger` from the `com.ionspin.kotlin.bignum.integer` package to the Java `BigInteger` class. + * + * @return the converted `BigInteger` object. + */ fun com.ionspin.kotlin.bignum.integer.BigInteger.toJavaBigInteger(): BigInteger { return BigInteger(this.signum(), this.toByteArray()) } diff --git a/apollo/src/jvmMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMEdKeyPair.kt b/apollo/src/jvmMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMEdKeyPair.kt index 30bb9933c..33f435223 100644 --- a/apollo/src/jvmMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMEdKeyPair.kt +++ b/apollo/src/jvmMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMEdKeyPair.kt @@ -7,12 +7,23 @@ import org.bouncycastle.crypto.params.Ed25519PublicKeyParameters import java.security.SecureRandom import kotlin.js.ExperimentalJsExport +/** + * Represents a key pair consisting of a private key and a public key. + * + * @property privateKey The private key of the key pair. + * @property publicKey The public key of the key pair. + */ actual class KMMEdKeyPair actual constructor( actual val privateKey: KMMEdPrivateKey, actual val publicKey: KMMEdPublicKey ) { @OptIn(ExperimentalJsExport::class) actual companion object : Ed25519KeyPairGeneration { + /** + * Generates a key pair consisting of a private key and a public key. + * + * @return A [KMMEdKeyPair] instance representing the generated public and private keys. + */ override fun generateKeyPair(): KMMEdKeyPair { val generator = Ed25519KeyPairGenerator() generator.init(Ed25519KeyGenerationParameters(SecureRandom())) @@ -24,10 +35,23 @@ actual class KMMEdKeyPair actual constructor( } } + /** + * Method to sign a provided message. + * + * @param message A ByteArray with the message to be signed. + * @return A ByteArray conforming the signed message. + */ actual fun sign(message: ByteArray): ByteArray { return privateKey.sign(message) } + /** + * Method to verify a provided message and signature + * + * @param message A ByteArray with the original message + * @param sig The signature to be verified + * @return A boolean that tells us if the signature matches the original message + */ actual fun verify(message: ByteArray, sig: ByteArray): Boolean { return publicKey.verify(message, sig) } diff --git a/apollo/src/jvmMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMEdPrivateKey.kt b/apollo/src/jvmMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMEdPrivateKey.kt index 42f1d6ef7..6c2d48b26 100644 --- a/apollo/src/jvmMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMEdPrivateKey.kt +++ b/apollo/src/jvmMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMEdPrivateKey.kt @@ -4,13 +4,29 @@ import org.bouncycastle.crypto.params.Ed25519PrivateKeyParameters import org.bouncycastle.crypto.signers.Ed25519Signer import java.io.ByteArrayInputStream +/** + * Represents a private key for the KMMEd cryptographic system. + * + * @property raw The raw byte array representation of the private key. + */ actual class KMMEdPrivateKey(val raw: ByteArray) { + /** + * Generates a public key corresponding to this private key. + * + * @return The public key as a [KMMEdPublicKey] object. + */ fun publicKey(): KMMEdPublicKey { val private = Ed25519PrivateKeyParameters(raw, 0) val public = private.generatePublicKey() return KMMEdPublicKey(public.encoded) } + /** + * Signs a message using the Ed25519 algorithm. + * + * @param message The message to be signed. + * @return The generated signature as a byte array. + */ actual fun sign(message: ByteArray): ByteArray { val privateKeyParameters = Ed25519PrivateKeyParameters(ByteArrayInputStream(raw)) val signer = Ed25519Signer() diff --git a/apollo/src/jvmMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMEdPublicKey.kt b/apollo/src/jvmMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMEdPublicKey.kt index 1be201853..e5920c419 100644 --- a/apollo/src/jvmMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMEdPublicKey.kt +++ b/apollo/src/jvmMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMEdPublicKey.kt @@ -4,7 +4,19 @@ import org.bouncycastle.crypto.params.Ed25519PublicKeyParameters import org.bouncycastle.crypto.signers.Ed25519Signer import java.io.ByteArrayInputStream +/** + * Represents a public key for the KMMEd cryptographic system. + * + * @property raw The raw byte array representation of the public key. + */ actual class KMMEdPublicKey(val raw: ByteArray) { + /** + * Verifies the signature of a message using the Ed25519 algorithm. + * + * @param message The message to be verified. + * @param sig The signature to be verified. + * @return Returns `true` if the signature matches the message, `false` otherwise. + */ actual fun verify(message: ByteArray, sig: ByteArray): Boolean { return try { val publicKeyParams = Ed25519PublicKeyParameters(ByteArrayInputStream(raw)) diff --git a/apollo/src/jvmMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMX25519KeyPair.kt b/apollo/src/jvmMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMX25519KeyPair.kt index 876c7d9b5..c19c4a32f 100644 --- a/apollo/src/jvmMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMX25519KeyPair.kt +++ b/apollo/src/jvmMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMX25519KeyPair.kt @@ -7,12 +7,23 @@ import org.bouncycastle.crypto.params.X25519PublicKeyParameters import java.security.SecureRandom import kotlin.js.ExperimentalJsExport +/** + * Represents a key pair for the X25519 elliptic curve encryption algorithm. + * + * @property privateKey The private key of the key pair. + * @property publicKey The public key of the key pair. + */ actual class KMMX25519KeyPair actual constructor( actual val privateKey: KMMX25519PrivateKey, actual val publicKey: KMMX25519PublicKey ) { @OptIn(ExperimentalJsExport::class) actual companion object : X25519KeyPairGeneration { + /** + * Generates a new key pair for the X25519 elliptic curve encryption algorithm. + * + * @return the generated key pair as a [KMMX25519KeyPair] object. + */ override fun generateKeyPair(): KMMX25519KeyPair { val generator = X25519KeyPairGenerator() generator.init(X25519KeyGenerationParameters(SecureRandom())) diff --git a/apollo/src/jvmMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMX25519PrivateKey.kt b/apollo/src/jvmMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMX25519PrivateKey.kt index 78da76f87..31e152816 100644 --- a/apollo/src/jvmMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMX25519PrivateKey.kt +++ b/apollo/src/jvmMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMX25519PrivateKey.kt @@ -2,7 +2,17 @@ package io.iohk.atala.prism.apollo.utils import org.bouncycastle.crypto.params.X25519PrivateKeyParameters +/** + * Represents a private key for the X25519 elliptic curve encryption algorithm. + * + * @property raw The binary representation of the private key. + */ actual class KMMX25519PrivateKey(val raw: ByteArray) { + /** + * Generates a public key from the private key using the X25519 elliptic curve encryption algorithm. + * + * @return A `KMMX25519PublicKey` object representing the generated public key. + */ fun publicKey(): KMMX25519PublicKey { val private = X25519PrivateKeyParameters(raw, 0) val public = private.generatePublicKey() diff --git a/apollo/src/jvmMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMX25519PublicKey.kt b/apollo/src/jvmMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMX25519PublicKey.kt index 5c525dc9d..604688bdf 100644 --- a/apollo/src/jvmMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMX25519PublicKey.kt +++ b/apollo/src/jvmMain/kotlin/io/iohk/atala/prism/apollo/utils/KMMX25519PublicKey.kt @@ -1,3 +1,9 @@ package io.iohk.atala.prism.apollo.utils +/** + * Represents a public key for the X25519 elliptic curve encryption algorithm. + * + * @property raw The binary representation of the public key. + * @constructor Creates a new instance of [KMMX25519PublicKey] with the given [raw] value. + */ actual class KMMX25519PublicKey(val raw: ByteArray) diff --git a/apollo/src/macosMain/kotlin/io/iohk/atala/prism/apollo/Platform.kt b/apollo/src/macosMain/kotlin/io/iohk/atala/prism/apollo/Platform.kt index b5b02dd3b..9d46a275a 100644 --- a/apollo/src/macosMain/kotlin/io/iohk/atala/prism/apollo/Platform.kt +++ b/apollo/src/macosMain/kotlin/io/iohk/atala/prism/apollo/Platform.kt @@ -7,6 +7,9 @@ import kotlin.native.Platform * Provides information about the platform on which the application is running. */ actual object Platform { + /** + * Represents the operating system on which the application is running. + */ @OptIn(ExperimentalNativeApi::class) actual val OS: String get() = "macOS-${Platform.osFamily.name}"