Updated jvm jna libraries, README
This commit is contained in:
parent
4833eaaea2
commit
3bb56115f3
@ -5,7 +5,7 @@
|
|||||||
|
|
||||||
# Libsodium bindings for Kotlin Multiplatform
|
# Libsodium bindings for Kotlin Multiplatform
|
||||||
|
|
||||||
Libsodium bindings project uses libsodium c sources and libsodium.js to provide a kotlin multiplatform wrapper library for libsodium.
|
Libsodium bindings project uses libsodium c sources and libsodium.js to provide a kotlin multiplatform wrapper library for libsodium. The library is feature complete and usable.
|
||||||
|
|
||||||
## Warning
|
## Warning
|
||||||
While this library is just a wrapper around the well known Libsodium library it still comes with high potential of introducing new
|
While this library is just a wrapper around the well known Libsodium library it still comes with high potential of introducing new
|
||||||
|
@ -1,4 +1,4 @@
|
|||||||
/*
|
/*
|
||||||
* Copyright 2019 Ugljesa Jovanovic
|
* Copyright 2019 Ugljesa Jovanovic
|
||||||
*
|
*
|
||||||
* Licensed under the Apache License, Version 2.0 (the "License");
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
||||||
@ -40,7 +40,6 @@ object Versions {
|
|||||||
|
|
||||||
object ReleaseInfo {
|
object ReleaseInfo {
|
||||||
val group = "com.ionspin.kotlin"
|
val group = "com.ionspin.kotlin"
|
||||||
val version = "0.1.0-SNAPSHOT"
|
|
||||||
val bindingsVersion = "0.8.5-SNAPSHOT"
|
val bindingsVersion = "0.8.5-SNAPSHOT"
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@ -1,288 +1 @@
|
|||||||
[](https://travis-ci.com/ionspin/kotlin-multiplatform-crypto)
|
This is just used to get kotlin to download appropriate konan tools.
|
||||||

|
|
||||||
|
|
||||||
# Kotlin Multiplatform Crypto Library
|
|
||||||
|
|
||||||
|
|
||||||
Kotlin Multiplatform Crypto is a library for various cryptographic applications.
|
|
||||||
|
|
||||||
The library comes in two flavors `multiplatform-crypto` and `multiplatform-crypto-delegated`.
|
|
||||||
|
|
||||||
* `multiplatform-crypto` contains pure kotlin implementations, is not reviewed, should be considered unsafe and only
|
|
||||||
for prototyping or experimentation purposes.
|
|
||||||
|
|
||||||
* `multiplatform-crypto-delegated` relies on platform specific implementations, mostly libsodium, but care should still be taken that the kotlin code is not reviewed or proven safe.
|
|
||||||
|
|
||||||
APIs of both variants are identical.
|
|
||||||
|
|
||||||
|
|
||||||
### Table of contents
|
|
||||||
1. [Supported platforms](#supported-platforms-by-variant)
|
|
||||||
2. [API](#api)
|
|
||||||
3. TODO
|
|
||||||
|
|
||||||
## Supported platforms by variant
|
|
||||||
|Platform|Pure variant| Delegated variant|
|
|
||||||
|--------|------------|------------------|
|
|
||||||
|Linux X86 64| :heavy_check_mark: | :heavy_check_mark: |
|
|
||||||
|Linux Arm 64| :heavy_check_mark: | :heavy_check_mark: |
|
|
||||||
|Linux Arm 32| :heavy_check_mark: | :x: |
|
|
||||||
|macOS X86 64| :heavy_check_mark: | :heavy_check_mark: |
|
|
||||||
|iOS x86 64 | :heavy_check_mark: | :heavy_check_mark: |
|
|
||||||
|iOS Arm 64 | :heavy_check_mark: | :heavy_check_mark: |
|
|
||||||
|iOS Arm 32 | :heavy_check_mark: | :heavy_check_mark: |
|
|
||||||
|watchOS X86 32 | :heavy_check_mark: | :heavy_check_mark: |
|
|
||||||
|watchOS Arm 64(_32) | :heavy_check_mark: | :heavy_check_mark: |
|
|
||||||
|watchos Arm 32 | :heavy_check_mark: | :heavy_check_mark: |
|
|
||||||
|tvOS X86 64 | :heavy_check_mark: | :heavy_check_mark: |
|
|
||||||
|tvOS Arm 64 | :heavy_check_mark: | :heavy_check_mark: |
|
|
||||||
|minGW X86 64| :heavy_check_mark: | :heavy_check_mark: |
|
|
||||||
|minGW X86 32| :x: | :x: |
|
|
||||||
|
|
||||||
## Sample project
|
|
||||||
The library includes sample project that shows usage on different platforms
|
|
||||||
- NOTE: Currently only linux, macOs and windows are included.
|
|
||||||
|
|
||||||
## Notes & Roadmap
|
|
||||||
|
|
||||||
**The API will move fast and break often until v1.0**
|
|
||||||
|
|
||||||
Next steps:
|
|
||||||
- Expand API (ECC, Signing ...)
|
|
||||||
|
|
||||||
## Should I use this in production?
|
|
||||||
**NO.**
|
|
||||||
The library is under HEAVY development. Until development is done it will not be reviewed and therefore it shouldn't be used.
|
|
||||||
Contributions are still welcome!
|
|
||||||
|
|
||||||
## Why?
|
|
||||||
|
|
||||||
This is an experimental implementation, mostly for expanding personal understanding of cryptography.
|
|
||||||
It's not peer reviewed, not guaranteed to be bug free, and not guaranteed to be secure.
|
|
||||||
|
|
||||||
## API for Pure and Delegated flavours
|
|
||||||
|
|
||||||
### Hashing functions
|
|
||||||
* Blake2b
|
|
||||||
* SHA512
|
|
||||||
* SHA256
|
|
||||||
|
|
||||||
### Key Derivation
|
|
||||||
|
|
||||||
* Argon2
|
|
||||||
|
|
||||||
### Authenticated symmetric encryption (AEAD)
|
|
||||||
|
|
||||||
* XChaCha20-Poly1305
|
|
||||||
|
|
||||||
|
|
||||||
### Delegated flavor dependancy table
|
|
||||||
The following table describes which library is used for particular cryptographic primitive
|
|
||||||
|
|
||||||
| Primitive | JVM | JS | Native |
|
|
||||||
| ----------|-----|----|--------|
|
|
||||||
| Blake2b | LazySodium | libsodium.js | libsodium |
|
|
||||||
| SHA256 | LazySodium | libsodium.js | libsodium |
|
|
||||||
| SHA512 | LazySodium | libsodium.js | libsodium |
|
|
||||||
| XChaCha20-Poly1305 | LazySodium | libsodium.js | libsodium |
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
## Integration
|
|
||||||
|
|
||||||
NOTE: Latest version of the library is built with Kotlin 1.4-M2 and therefore only SNAPSHOT variant is available. Next
|
|
||||||
stable version will be released when Kotlin 1.4. is released
|
|
||||||
|
|
||||||
#### Gradle
|
|
||||||
Kotlin
|
|
||||||
```kotlin
|
|
||||||
implementation("com.ionspin.kotlin:multiplatform-crypto:0.1.0")
|
|
||||||
|
|
||||||
or
|
|
||||||
|
|
||||||
implementation("com.ionspin.kotlin:multiplatform-crypto-delegated:0.1.0")
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Snapshot builds
|
|
||||||
```kotlin
|
|
||||||
repositories {
|
|
||||||
maven {
|
|
||||||
url = uri("https://oss.sonatype.org/content/repositories/snapshots")
|
|
||||||
}
|
|
||||||
}
|
|
||||||
implementation("com.ionspin.kotlin:multiplatform-crypto:0.1.0-SNAPSHOT")
|
|
||||||
|
|
||||||
```
|
|
||||||
|
|
||||||
## Usage
|
|
||||||
|
|
||||||
### Helper functions
|
|
||||||
|
|
||||||
All API take `UByteArray` as message/key/nonce/etc parameter. For convenience when working with strings we provide
|
|
||||||
`String.enocdeToUbyteArray()` extensions function, and `UByteArray.toHexString` extension function.
|
|
||||||
|
|
||||||
More convenience functions will be added.
|
|
||||||
|
|
||||||
### Hashes
|
|
||||||
|
|
||||||
Hashes are provided in two versions, "stateless", usually the companion object of the hash,
|
|
||||||
which takes the data to be hashed in one go, and "updatable" which can be fed data in chunks.
|
|
||||||
|
|
||||||
|
|
||||||
#### Blake2b
|
|
||||||
|
|
||||||
You can use Blake 2b in two modes
|
|
||||||
|
|
||||||
##### Stateless version
|
|
||||||
You need to deliver the complete data that is to be hashed in one go
|
|
||||||
|
|
||||||
```kotlin
|
|
||||||
val input = "abc"
|
|
||||||
val result = Crypto.Blake2b.stateless(input.encodeToUByteArray())
|
|
||||||
```
|
|
||||||
|
|
||||||
Result is returned as a `UByteArray`
|
|
||||||
|
|
||||||
##### Updatable instance version
|
|
||||||
You can create an instance and feed the data by using `update(input : UByteArray)` call. Once all data is supplied,
|
|
||||||
you should call `digest()`.
|
|
||||||
|
|
||||||
If you want to use Blake2b with a key, you should supply it when creating the `Blake2b` instance.
|
|
||||||
|
|
||||||
```kotlin
|
|
||||||
val test = "abc"
|
|
||||||
val key = "key"
|
|
||||||
val blake2b = Crypto.Blake2b.updateable(key.encodeToUByteArray())
|
|
||||||
blake2b.update(test.encodeToUByteArray())
|
|
||||||
val result = blake2b.digest().toHexString()
|
|
||||||
```
|
|
||||||
|
|
||||||
After digest is called, the instance is reset and can be reused (Keep in mind key stays the same for the particular instance).
|
|
||||||
#### SHA2 (SHA256 and SHA512)
|
|
||||||
|
|
||||||
##### Stateless version
|
|
||||||
|
|
||||||
You need to deliver the complete data that is to be hashed in one go. You can either provide the `UByteArray` as input
|
|
||||||
or `String`. Result is always returned as `UByteArray` (At least in verision 0.0.1)
|
|
||||||
|
|
||||||
```kotlin
|
|
||||||
val input = "abc"
|
|
||||||
val result = Crypto.Sha256.stateless(input.encodeToUByteArray())
|
|
||||||
```
|
|
||||||
|
|
||||||
```kotlin
|
|
||||||
val input ="abc"
|
|
||||||
val result = Crypto.Sha512.stateless(input.encodeToUByteArray())
|
|
||||||
```
|
|
||||||
|
|
||||||
Result is returned as a `UByteArray`
|
|
||||||
|
|
||||||
##### Updateable version
|
|
||||||
|
|
||||||
Or you can use the updatable instance version
|
|
||||||
|
|
||||||
```kotlin
|
|
||||||
val sha256 = Crypto.Sha256.updateable()
|
|
||||||
sha256.update("abc".encodeToUByteArray())
|
|
||||||
val result = sha256.digest()
|
|
||||||
```
|
|
||||||
|
|
||||||
```kotlin
|
|
||||||
val sha512 = Crypto.Sha512.updateable()
|
|
||||||
sha512.update("abc".encodeToUByteArray())
|
|
||||||
val result = sha512.digest()
|
|
||||||
```
|
|
||||||
|
|
||||||
### Key derivation
|
|
||||||
|
|
||||||
#### Argon2
|
|
||||||
|
|
||||||
NOTE: This implementation is tested against KAT generated by reference Argon2 implementation, which does not follow
|
|
||||||
specification completely. See this issue https://github.com/P-H-C/phc-winner-argon2/issues/183
|
|
||||||
|
|
||||||
```kotlin
|
|
||||||
val argon2Instance = Argon2(
|
|
||||||
password = "Password",
|
|
||||||
salt = "RandomSalt",
|
|
||||||
parallelism = 8,
|
|
||||||
tagLength = 64U,
|
|
||||||
requestedMemorySize = 256U, //4GB
|
|
||||||
numberOfIterations = 4U,
|
|
||||||
key = "",
|
|
||||||
associatedData = "",
|
|
||||||
argonType = ArgonType.Argon2id
|
|
||||||
)
|
|
||||||
val tag = argon2Instance.derive()
|
|
||||||
val tagString = tag.map { it.toString(16).padStart(2, '0') }.joinToString(separator = "")
|
|
||||||
val expectedTagString = "c255e3e94305817d5e09a7c771e574e3a81cc78fef5da4a9644b6df0" +
|
|
||||||
"0ba1c9b424e3dd0ce7e600b1269b14c84430708186a8a60403e1bfbda935991592b9ff37"
|
|
||||||
println("Tag: ${tagString}")
|
|
||||||
assertEquals(tagString, expectedTagString)
|
|
||||||
```
|
|
||||||
|
|
||||||
### Symmetric encryption (OUTDATED, won't be exposed in next release, no counterpart in delegated flavor - 0.1.1)
|
|
||||||
|
|
||||||
#### AES
|
|
||||||
|
|
||||||
Aes is available with CBC and CTR mode through `AesCbc` and `AesCtr` classes/objects.
|
|
||||||
Similarly to hashes you can either use stateless or updateable version.
|
|
||||||
|
|
||||||
Initialization vector, or counter states are chosen by the SDK automaticaly, and returned alongside encrypted data
|
|
||||||
|
|
||||||
##### Stateless AesCbc and AesCtr
|
|
||||||
|
|
||||||
AesCtr
|
|
||||||
|
|
||||||
```kotlin
|
|
||||||
val keyString = "4278b840fb44aaa757c1bf04acbe1a3e"
|
|
||||||
val key = AesKey.Aes128Key(keyString)
|
|
||||||
val plainText = "6bc1bee22e409f96e93d7e117393172aae2d8a571e03ac9c9eb76fac45af8e5130c81c46a35ce411e5fbc1191a0a52eff69f2445df4f9b17ad2b417be66c3710"
|
|
||||||
|
|
||||||
val encryptedDataAndInitializationVector = AesCtr.encrypt(key, plainText.hexStringToUByteArray())
|
|
||||||
val decrypted = AesCtr.decrypt(
|
|
||||||
key,
|
|
||||||
encryptedDataAndInitializationVector.encryptedData,
|
|
||||||
encryptedDataAndInitializationVector.initialCounter
|
|
||||||
)
|
|
||||||
plainText == decrypted.toHexString()
|
|
||||||
```
|
|
||||||
|
|
||||||
AesCbc
|
|
||||||
|
|
||||||
```kotlin
|
|
||||||
|
|
||||||
val keyString = "4278b840fb44aaa757c1bf04acbe1a3e"
|
|
||||||
val key = AesKey.Aes128Key(keyString)
|
|
||||||
|
|
||||||
val plainText = "3c888bbbb1a8eb9f3e9b87acaad986c466e2f7071c83083b8a557971918850e5"
|
|
||||||
|
|
||||||
val encryptedDataAndInitializationVector = AesCbc.encrypt(key, plainText.hexStringToUByteArray())
|
|
||||||
val decrypted = AesCbc.decrypt(
|
|
||||||
key,
|
|
||||||
encryptedDataAndInitializationVector.encryptedData,
|
|
||||||
encryptedDataAndInitializationVector.initilizationVector
|
|
||||||
)
|
|
||||||
plainText == decrypted.toHexString()
|
|
||||||
|
|
||||||
```
|
|
||||||
|
|
||||||
## Libsodium bindings
|
|
||||||
|
|
||||||
* Under development
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
@ -32,7 +32,7 @@ repositories {
|
|||||||
mavenCentral()
|
mavenCentral()
|
||||||
}
|
}
|
||||||
group = ReleaseInfo.group
|
group = ReleaseInfo.group
|
||||||
version = ReleaseInfo.version
|
version = "0.1" //Irrelevant
|
||||||
|
|
||||||
val ideaActive = System.getProperty("idea.active") == "true"
|
val ideaActive = System.getProperty("idea.active") == "true"
|
||||||
|
|
||||||
@ -83,105 +83,30 @@ kotlin {
|
|||||||
}
|
}
|
||||||
|
|
||||||
|
|
||||||
}
|
|
||||||
|
|
||||||
runningOnLinuxArm64 {
|
|
||||||
|
|
||||||
}
|
|
||||||
|
|
||||||
runningOnLinuxArm32 {
|
|
||||||
|
|
||||||
}
|
}
|
||||||
|
|
||||||
runningOnMacos {
|
runningOnMacos {
|
||||||
iosX64() {
|
iosX64()
|
||||||
binaries {
|
iosArm64()
|
||||||
framework {
|
iosArm32()
|
||||||
optimized = true
|
iosSimulatorArm64()
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
iosArm64() {
|
|
||||||
binaries {
|
|
||||||
framework {
|
|
||||||
optimized = true
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
iosArm32() {
|
|
||||||
binaries {
|
|
||||||
framework {
|
|
||||||
optimized = true
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
macosX64() {
|
macosX64()
|
||||||
binaries {
|
macosArm64()
|
||||||
framework {
|
|
||||||
optimized = true
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
tvosX64() {
|
tvosX64()
|
||||||
binaries {
|
tvosArm64()
|
||||||
framework {
|
tvosSimulatorArm64()
|
||||||
optimized = true
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
tvosArm64() {
|
watchosArm64()
|
||||||
binaries {
|
watchosArm32()
|
||||||
framework {
|
watchosX86()
|
||||||
optimized = true
|
watchosSimulatorArm64()
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
watchosArm64() {
|
|
||||||
binaries {
|
|
||||||
framework {
|
|
||||||
optimized = true
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
watchosArm32() {
|
|
||||||
binaries {
|
|
||||||
framework {
|
|
||||||
optimized = true
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
watchosX86() {
|
|
||||||
binaries {
|
|
||||||
framework {
|
|
||||||
optimized = true
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
}
|
}
|
||||||
runningOnWindows {
|
runningOnWindows {
|
||||||
|
mingwX64()
|
||||||
mingwX64() {
|
mingwX86()
|
||||||
binaries {
|
|
||||||
staticLib {
|
|
||||||
optimized = true
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
mingwX86() {
|
|
||||||
binaries {
|
|
||||||
staticLib {
|
|
||||||
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|
||||||
|
@ -15,7 +15,7 @@ actual object LibsodiumInitializer {
|
|||||||
private fun loadLibrary() : JnaLibsodiumInterface {
|
private fun loadLibrary() : JnaLibsodiumInterface {
|
||||||
val libraryFile = when {
|
val libraryFile = when {
|
||||||
Platform.isMac() -> {
|
Platform.isMac() -> {
|
||||||
SharedLibraryLoader.get().load("dynamic-macos-x86-64.dylib", JnaLibsodiumInterface::class.java)
|
SharedLibraryLoader.get().load("dynamic-macos.dylib", JnaLibsodiumInterface::class.java)
|
||||||
}
|
}
|
||||||
Platform.isLinux() -> {
|
Platform.isLinux() -> {
|
||||||
if (Platform.isARM()) {
|
if (Platform.isARM()) {
|
||||||
|
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Loading…
x
Reference in New Issue
Block a user