From 48d81f257e75d7d876a138f603ad57cc9788a5c8 Mon Sep 17 00:00:00 2001 From: Ugljesa Jovanovic Date: Sat, 14 Nov 2020 13:27:42 +0100 Subject: [PATCH] Add more doc copied from libsodium --- README.md | 2 + doc/res/libsodium_api_mapping.svg | 91 +++++++++++++++++++ .../com.ionspin.kotlin.crypto/box/Box.kt | 36 +++++++- .../kotlin/crypto/sample/DataPackage.kt | 36 ++++++++ .../kotlin/crypto/sample/FileWrapper.kt | 11 +++ .../crypto/sample/ui/LandingController.kt | 1 + .../sample/workbench/WorkbenchController.kt | 7 ++ .../sample/workbench/WorkbenchElement.kt | 10 ++ .../crypto/sample/workbench/WorkbenchView.kt | 10 ++ 9 files changed, 203 insertions(+), 1 deletion(-) create mode 100644 doc/res/libsodium_api_mapping.svg create mode 100644 sample/src/commonMain/kotlin/com/ionspin/kotlin/crypto/sample/DataPackage.kt create mode 100644 sample/src/commonMain/kotlin/com/ionspin/kotlin/crypto/sample/FileWrapper.kt create mode 100644 sample/src/commonMain/kotlin/com/ionspin/kotlin/crypto/sample/workbench/WorkbenchController.kt create mode 100644 sample/src/commonMain/kotlin/com/ionspin/kotlin/crypto/sample/workbench/WorkbenchElement.kt create mode 100644 sample/src/commonMain/kotlin/com/ionspin/kotlin/crypto/sample/workbench/WorkbenchView.kt diff --git a/README.md b/README.md index 5b76552..0abc43b 100644 --- a/README.md +++ b/README.md @@ -108,6 +108,7 @@ And here is the usage sample The functions are mapped from libsodium to kotiln objects, so `crypto_secretstream_xchacha20poly1305_init_push` becomes `SecretStream.xChaCha20Poly1305InitPush` +![Alt text](./doc/res/libsodium_api_mapping.svg) At the moment you should refer to original libsodium documentation for instructions on how to use the library @@ -139,6 +140,7 @@ Currently supported native platforms: - Android testing - Fix browser testing, both locally and in CI/CD - LobsodiumUtil `unpad` and `fromBase64` native implementations use a nasty hack to support shared native sourceset. The hack either needs to be removed and replaced with another solution or additional safeguards need to be added. +- Complete exposing libsodium constants diff --git a/doc/res/libsodium_api_mapping.svg b/doc/res/libsodium_api_mapping.svg new file mode 100644 index 0000000..a4ab378 --- /dev/null +++ b/doc/res/libsodium_api_mapping.svg @@ -0,0 +1,91 @@ + + + + + + + + image/svg+xml + + + + + + + crypto_secretstream_xchacha20poly1305_init_push + SecretStream.xChaCha20Poly1305InitPush + + diff --git a/multiplatform-crypto-libsodium-bindings/src/commonMain/kotlin/com.ionspin.kotlin.crypto/box/Box.kt b/multiplatform-crypto-libsodium-bindings/src/commonMain/kotlin/com.ionspin.kotlin.crypto/box/Box.kt index fdbc907..6afa9b8 100644 --- a/multiplatform-crypto-libsodium-bindings/src/commonMain/kotlin/com.ionspin.kotlin.crypto/box/Box.kt +++ b/multiplatform-crypto-libsodium-bindings/src/commonMain/kotlin/com.ionspin.kotlin.crypto/box/Box.kt @@ -19,6 +19,40 @@ data class BoxEncryptedDataAndTag(val ciphertext: UByteArray, val tag: UByteArra class BoxCorruptedOrTamperedDataException() : RuntimeException("MAC validation failed. Data is corrupted or tampered with.") +/** + * Authenticated encryption (crypto_box_* API) + * + * Using public-key authenticated encryption, Bob can encrypt a confidential message specifically for Alice, using Alice's public key. + * Using Bob's public key, Alice can compute a shared secret key. Using Alice's public key and his secret key, + * Bob can compute the exact same shared secret key. That shared secret key can be used to verify that the encrypted + * message was not tampered with, before eventually decrypting it. + * Alice only needs Bob's public key, the nonce and the ciphertext. Bob should never ever share his secret key, + * even with Alice. + * And in order to send messages to Alice, Bob only needs Alice's public key. Alice should never ever share her secret + * key either, even with Bob. + * Alice can reply to Bob using the same system, without having to generate a distinct key pair. + * The nonce doesn't have to be confidential, but it should be used with just one invocation of crypto_box_easy() for a + * particular pair of public and secret keys. + * One easy way to generate a nonce is to use randombytes_buf(), considering the size of the nonces the risk of any + * random collisions is negligible. For some applications, if you wish to use nonces to detect missing messages or to + * ignore replayed messages, it is also acceptable to use a simple incrementing counter as a nonce. A better alternative + * is to use the crypto_secretstream() API. + * When doing so you must ensure that the same value can never be re-used (for example you may have multiple threads + * or even hosts generating messages using the same key pairs). + * As stated above, senders can decrypt their own messages, and compute a valid authentication tag for any messages + * encrypted with a given shared secret key. This is generally not an issue for online protocols. If this is not + * acceptable, check out the Sealed Boxes section, as well as the Key Exchange section in this documentation. + * + * + * Sealed boxes (crypto_box_seal_* API) + * + * Sealed boxes are designed to anonymously send messages to a recipient given its public key. + * Only the recipient can decrypt these messages, using its private key. While the recipient can verify the integrity + * of the message, it cannot verify the identity of the sender. + * A message is encrypted using an ephemeral key pair, whose secret part is destroyed right after the encryption process. + * Without knowing the secret key used for a given message, the sender cannot decrypt its own message later. + * And without additional data, a message cannot be correlated with the identity of its sender. + */ expect object Box { /** * The crypto_box_keypair() function randomly generates a secret key and a corresponding public key. @@ -87,4 +121,4 @@ expect object Box { fun sealOpen(ciphertext: UByteArray, recipientsPublicKey: UByteArray, recipientsSecretKey: UByteArray) : UByteArray -} \ No newline at end of file +} diff --git a/sample/src/commonMain/kotlin/com/ionspin/kotlin/crypto/sample/DataPackage.kt b/sample/src/commonMain/kotlin/com/ionspin/kotlin/crypto/sample/DataPackage.kt new file mode 100644 index 0000000..b6e85ca --- /dev/null +++ b/sample/src/commonMain/kotlin/com/ionspin/kotlin/crypto/sample/DataPackage.kt @@ -0,0 +1,36 @@ +package com.ionspin.kotlin.crypto.sample + +import com.ionspin.kotlin.crypto.util.encodeToUByteArray +import com.ionspin.kotlin.crypto.util.hexStringToUByteArray + +/** + * Created by Ugljesa Jovanovic + * ugljesa.jovanovic@ionspin.com + * on 30-Oct-2020 + */ +interface DataPackage { + fun getContentAsUByteArray() : UByteArray + fun getStringRepresentation() : String +} + +data class Utf8StringData(val content: String) : DataPackage { + override fun getContentAsUByteArray(): UByteArray { + return content.encodeToUByteArray() + } + + override fun getStringRepresentation(): String { + return content + } +} + +data class HexadecimalStringData(val content: String) : DataPackage { + override fun getContentAsUByteArray(): UByteArray { + return content.hexStringToUByteArray() + } + + override fun getStringRepresentation(): String { + return content + } +} + +data class FileData(val filePath: ) diff --git a/sample/src/commonMain/kotlin/com/ionspin/kotlin/crypto/sample/FileWrapper.kt b/sample/src/commonMain/kotlin/com/ionspin/kotlin/crypto/sample/FileWrapper.kt new file mode 100644 index 0000000..bc3411a --- /dev/null +++ b/sample/src/commonMain/kotlin/com/ionspin/kotlin/crypto/sample/FileWrapper.kt @@ -0,0 +1,11 @@ +package com.ionspin.kotlin.crypto.sample + +/** + * Created by Ugljesa Jovanovic + * ugljesa.jovanovic@ionspin.com + * on 30-Oct-2020 + */ +expect class FileWrapper(path: String) { + fun exists() : Boolean + fun rea +} diff --git a/sample/src/commonMain/kotlin/com/ionspin/kotlin/crypto/sample/ui/LandingController.kt b/sample/src/commonMain/kotlin/com/ionspin/kotlin/crypto/sample/ui/LandingController.kt index 3166bc3..730bfb7 100644 --- a/sample/src/commonMain/kotlin/com/ionspin/kotlin/crypto/sample/ui/LandingController.kt +++ b/sample/src/commonMain/kotlin/com/ionspin/kotlin/crypto/sample/ui/LandingController.kt @@ -7,4 +7,5 @@ package com.ionspin.kotlin.crypto.sample.ui */ class LandingController { + } diff --git a/sample/src/commonMain/kotlin/com/ionspin/kotlin/crypto/sample/workbench/WorkbenchController.kt b/sample/src/commonMain/kotlin/com/ionspin/kotlin/crypto/sample/workbench/WorkbenchController.kt new file mode 100644 index 0000000..3fb409d --- /dev/null +++ b/sample/src/commonMain/kotlin/com/ionspin/kotlin/crypto/sample/workbench/WorkbenchController.kt @@ -0,0 +1,7 @@ +package com.ionspin.kotlin.crypto.sample.workbench + +/** + * Created by Ugljesa Jovanovic + * ugljesa.jovanovic@ionspin.com + * on 30-Oct-2020 + */ diff --git a/sample/src/commonMain/kotlin/com/ionspin/kotlin/crypto/sample/workbench/WorkbenchElement.kt b/sample/src/commonMain/kotlin/com/ionspin/kotlin/crypto/sample/workbench/WorkbenchElement.kt new file mode 100644 index 0000000..95f831f --- /dev/null +++ b/sample/src/commonMain/kotlin/com/ionspin/kotlin/crypto/sample/workbench/WorkbenchElement.kt @@ -0,0 +1,10 @@ +package com.ionspin.kotlin.crypto.sample.workbench + +/** + * Created by Ugljesa Jovanovic + * ugljesa.jovanovic@ionspin.com + * on 30-Oct-2020 + */ +interface WorkbenchElement { + +} diff --git a/sample/src/commonMain/kotlin/com/ionspin/kotlin/crypto/sample/workbench/WorkbenchView.kt b/sample/src/commonMain/kotlin/com/ionspin/kotlin/crypto/sample/workbench/WorkbenchView.kt new file mode 100644 index 0000000..59ad00f --- /dev/null +++ b/sample/src/commonMain/kotlin/com/ionspin/kotlin/crypto/sample/workbench/WorkbenchView.kt @@ -0,0 +1,10 @@ +package com.ionspin.kotlin.crypto.sample.workbench + +/** + * Created by Ugljesa Jovanovic + * ugljesa.jovanovic@ionspin.com + * on 30-Oct-2020 + */ +interface WorkbenchView { + +}