docs: add all missing docs

Signed-off-by: Ahmed Moussa <[email protected]>

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

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,

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,19 +27,41 @@ 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
     ): ByteArray? {
         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)
     }

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,13 +45,40 @@ 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)
         return bytes
     }
 
     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)
         }

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

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

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

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

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

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

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)