feat: document the latest development (#115)

hyperledger · Nov 28, 2023 · d435148 · d435148
1 parent 854fc70
commit d435148
Show file tree

Hide file tree

Showing 9 changed files with 153 additions and 0 deletions.
diff --git a/...mmonMain/kotlin/io/iohk/atala/prism/walletsdk/domain/models/keyManagement/DerivableKey.kt b/...mmonMain/kotlin/io/iohk/atala/prism/walletsdk/domain/models/keyManagement/DerivableKey.kt
@@ -2,6 +2,14 @@ package io.iohk.atala.prism.walletsdk.domain.models.keyManagement
 
 import io.iohk.atala.prism.apollo.derivation.DerivationPath
 
+/**
+ * This interface defines the functionality of a derivable key.
+ */
 interface DerivableKey {
+    /**
+     * Method to derive a key
+     * @param derivationPath the derivation path used to dervie a key
+     * @return a PrivateKey after being derived
+     */
     fun derive(derivationPath: DerivationPath): PrivateKey
 }
diff --git a/...tlin/io/iohk/atala/prism/walletsdk/domain/models/keyManagement/ExportableImportableKey.kt b/...tlin/io/iohk/atala/prism/walletsdk/domain/models/keyManagement/ExportableImportableKey.kt
@@ -4,21 +4,50 @@ import io.iohk.atala.prism.apollo.base64.base64PadEncoded
 import io.iohk.atala.prism.apollo.base64.base64UrlDecodedBytes
 import kotlinx.serialization.Serializable
 
+/**
+ * This interface defines what is required for a key to be exportable
+ */
 interface ExportableKey {
+    /**
+     * The key exported in PEM (Privacy-Enhanced Mail) format.
+     * @return PEM string
+     */
     fun getPem(): String
+
+    /**
+     * They key exported as a JWK (JSON Web Key)
+     * @return JWD instance
+     */
     fun getJwk(): JWK
 
+    /**
+     * Returns the key as a JWD with a specific kid (key identifier)
+     * @return JWK instnace
+     */
     fun jwkWithKid(kid: String): JWK
 }
 
+/**
+ * This interface defines what is required for a key to be importable
+ */
 interface ImportableKey {
+    /**
+     * Initializes key from PEM string
+     * @param pem string
+     */
     @Throws(Exception::class)
     fun initializeFromPem(pem: String)
 
+    /**
+     * Initializes key from JWK
+     */
     @Throws(Exception::class)
     fun initializeFromJwk(jwk: JWK)
 }
 
+/**
+ * Representation of a JWK (JSON Web Key)
+ */
 @Serializable
 data class JWK(
     val kty: String,
@@ -39,9 +68,16 @@ data class JWK(
     val k: String? = null
 )
 
+/**
+ * Representation of a cryptographic key in PEM format.
+ */
 data class PEMKey(val keyType: PEMKeyType, val keyData: ByteArray) {
     constructor(keyType: PEMKeyType, keyData: String) : this(keyType, keyData.base64UrlDecodedBytes)
 
+    /**
+     * Encodes the PEM into base 64
+     * @return pem encoded string
+     */
     fun pemEncoded(): String {
         val base64Data = keyData.base64PadEncoded.chunked(64).joinToString("\n")
         val beginMarker = "-----BEGIN $keyType-----"
@@ -76,6 +112,9 @@ data class PEMKey(val keyType: PEMKeyType, val keyData: ByteArray) {
     }
 }
 
+/**
+ * Definition of the PEM key types available
+ */
 enum class PEMKeyType(val value: Pair<String, String>) {
     EC_PRIVATE_KEY(Pair("-----BEGIN EC PRIVATE KEY-----", "-----END EC PRIVATE KEY-----")),
     EC_PUBLIC_KEY(Pair("-----BEGIN EC PUBLIC KEY-----", "-----END EC PUBLIC KEY-----"));

diff --git a/...dk/src/commonMain/kotlin/io/iohk/atala/prism/walletsdk/domain/models/keyManagement/Key.kt b/...dk/src/commonMain/kotlin/io/iohk/atala/prism/walletsdk/domain/models/keyManagement/Key.kt
@@ -5,6 +5,9 @@ import io.iohk.atala.prism.walletsdk.domain.models.ApolloError
 import io.iohk.atala.prism.walletsdk.domain.models.Curve
 import io.iohk.atala.prism.walletsdk.domain.models.KeyCurve
 
+/**
+ * Abstraction defining the base of what a Key is.
+ */
 abstract class Key {
     abstract val type: KeyTypes
     abstract val keySpecification: MutableMap<String, String>
@@ -34,43 +37,70 @@ abstract class Key {
         return result
     }
 
+    /**
+     * Returns the encoded raw value into base 64 url
+     */
     fun getEncoded(): ByteArray {
         return raw.base64UrlEncoded.encodeToByteArray()
     }
 
+    /**
+     * Evaluates if this key implements ExportableKey
+     */
     fun isExportable(): Boolean {
         return this is ExportableKey
     }
 
+    /**
+     * Evaluates if this key implements ImportableKey
+     */
     fun isImportable(): Boolean {
         return this is ImportableKey
     }
 
+    /**
+     * Evaluates if this key implements SignableKey
+     */
     fun isSignable(): Boolean {
         return this is SignableKey
     }
 
+    /**
+     * Evaluates if this key implements DerivableKey
+     */
     fun isDerivable(): Boolean {
         return this is DerivableKey
     }
 
+    /**
+     * Evaluates if this key implements VerifiableKey
+     */
     fun canVerify(): Boolean {
         return this is VerifiableKey
     }
 
+    /**
+     * Searches the value based on the input key, if it exists
+     */
     fun getProperty(name: String): String {
         if (!keySpecification.containsKey(name)) {
             throw Exception("KeySpecification do not contain $name")
         }
         return this.keySpecification[name].toString()
     }
 
+    /**
+     *  Evaluates if the input curve matches the actual curve this key has
+     */
     fun isCurve(curve: String): Boolean {
         val keyCurve = keySpecification[CurveKey().property]
         return keyCurve == curve
     }
 }
 
+/**
+ *  Method to get a KeyCurve instance based on a key String name.
+ */
 fun getKeyCurveByNameAndIndex(name: String, index: Int?): KeyCurve {
     return when (name) {
         Curve.X25519.value -> {

diff --git a/...onMain/kotlin/io/iohk/atala/prism/walletsdk/domain/models/keyManagement/KeyRestoration.kt b/...onMain/kotlin/io/iohk/atala/prism/walletsdk/domain/models/keyManagement/KeyRestoration.kt
@@ -1,12 +1,37 @@
 package io.iohk.atala.prism.walletsdk.domain.models.keyManagement
 
+/**
+* This interface defines the functionality to verify and restore cryptographic keys
+*/
 interface KeyRestoration {
 
+    /**
+     * Determines if the input data corresponds to a private key
+     * @param identifier a string that identifies the key
+     * @param data a ByteArray that represents the raw data
+     * @return a boolean value that tells if the identifier represents the private key
+     */
     fun isPrivateKeyData(identifier: String, data: ByteArray): Boolean
 
+    /**
+     * Determines if the input data corresponds to a public key
+     * @param identifier a string that identifies the key
+     * @param data a ByteArray that represents the raw data
+     * @return a boolean value that tells if the identifier represents the public key
+     */
     fun isPublicKeyData(identifier: String, data: ByteArray): Boolean
 
+    /**
+     * A method to restore a private key from a StorableKey
+     * @param key a StorableKey instance
+     * @return a PrivateKey
+     */
     fun restorePrivateKey(key: StorableKey): PrivateKey
 
+    /**
+     * A method to restore a public key from a StorableKey
+     * @param key a StorableKey instance
+     * @return a PublicKey
+     */
     fun restorePublicKey(key: StorableKey): PublicKey
 }
diff --git a/...commonMain/kotlin/io/iohk/atala/prism/walletsdk/domain/models/keyManagement/PrivateKey.kt b/...commonMain/kotlin/io/iohk/atala/prism/walletsdk/domain/models/keyManagement/PrivateKey.kt
@@ -2,12 +2,21 @@ package io.iohk.atala.prism.walletsdk.domain.models.keyManagement
 
 import io.iohk.atala.prism.walletsdk.domain.models.Curve
 
+/**
+ * Abstraction of what a PrivateKey is and what functionality provides.
+ */
 abstract class PrivateKey : Key() {
 
+    /**
+     * Returns the value of the key curve for this private key
+     */
     fun getCurve(): String {
         return this.getProperty(CurveKey().property)
     }
 
+    /**
+     * Returns an instance of the key curve for this private key
+     */
     fun getCurveInstance(): Curve? {
         return try {
             Curve.valueOf(this.getProperty(CurveKey().property))
@@ -16,13 +25,22 @@ abstract class PrivateKey : Key() {
         }
     }
 
+    /**
+     * Returns the index for this private key
+     */
     fun getIndex(): String {
         return this.getProperty(IndexKey().property)
     }
 
+    /**
+     * Returns the value of this private key
+     */
     fun getValue(): ByteArray {
         return this.raw
     }
 
+    /**
+     * Defines a method to fetch the public key of this private key
+     */
     abstract fun publicKey(): PublicKey
 }
diff --git a/.../commonMain/kotlin/io/iohk/atala/prism/walletsdk/domain/models/keyManagement/PublicKey.kt b/.../commonMain/kotlin/io/iohk/atala/prism/walletsdk/domain/models/keyManagement/PublicKey.kt
@@ -2,12 +2,21 @@ package io.iohk.atala.prism.walletsdk.domain.models.keyManagement
 
 import io.iohk.atala.prism.walletsdk.domain.models.Curve
 
+/**
+ * Abstraction of what a PublicKey is and the functionality it provides.
+ */
 abstract class PublicKey : Key() {
 
+    /**
+     * Returns the value of the key curve for this private key
+     */
     fun getCurve(): String {
         return this.getProperty(CurveKey().property)
     }
 
+    /**
+     * Returns an instance of the key curve for this private key
+     */
     fun getCurveInstance(): Curve? {
         return try {
             Curve.valueOf(this.getProperty(CurveKey().property))
@@ -16,6 +25,9 @@ abstract class PublicKey : Key() {
         }
     }
 
+    /**
+     * Returns the value of this private key
+     */
     fun getValue(): ByteArray {
         return this.raw
     }

diff --git a/...ommonMain/kotlin/io/iohk/atala/prism/walletsdk/domain/models/keyManagement/SignableKey.kt b/...ommonMain/kotlin/io/iohk/atala/prism/walletsdk/domain/models/keyManagement/SignableKey.kt
@@ -1,5 +1,14 @@
 package io.iohk.atala.prism.walletsdk.domain.models.keyManagement
 
+/**
+ * This interface defines the functionality of a signable key.
+ */
 interface SignableKey {
+
+    /**
+     * Method to sign a message using a key.
+     * @param message the ByteArray to be signed
+     * @return the signed message as a ByteArray
+     */
     fun sign(message: ByteArray): ByteArray
 }
diff --git a/...ommonMain/kotlin/io/iohk/atala/prism/walletsdk/domain/models/keyManagement/StorableKey.kt b/...ommonMain/kotlin/io/iohk/atala/prism/walletsdk/domain/models/keyManagement/StorableKey.kt
@@ -1,5 +1,8 @@
 package io.iohk.atala.prism.walletsdk.domain.models.keyManagement
 
+/**
+ * This interface defines what a key requires to be storable.
+ */
 interface StorableKey {
     val storableData: ByteArray
     val restorationIdentifier: String

diff --git a/...monMain/kotlin/io/iohk/atala/prism/walletsdk/domain/models/keyManagement/VerifiableKey.kt b/...monMain/kotlin/io/iohk/atala/prism/walletsdk/domain/models/keyManagement/VerifiableKey.kt
@@ -1,5 +1,14 @@
 package io.iohk.atala.prism.walletsdk.domain.models.keyManagement
 
+/**
+ * This interface defines the functionality of a verifiable key.
+ */
 interface VerifiableKey {
+    /**
+     * Method to verify a message with a signature.
+     * @param message in ByteArray
+     * @param signature in byteArray
+     * @return a boolean which tell us if message and signature match
+     */
     fun verify(message: ByteArray, signature: ByteArray): Boolean
 }