electric-coin-company / kotlin-bip39 Goto Github PK

A concise implementation of BIP-0039 in Kotlin for Android. In order, it prioritizes being secure, concise and idiomatic.

License: MIT License

Kotlin 100.00%

zcash android bip39 bip39-mnemonic-codes mnemonic kotlin library aar ecc

kotlin-bip39's Introduction

kotlin-bip39

Introduction

A concise implementation of BIP-0039 in Kotlin for Android.

Only about 30kB in total size. For comparison, the entire library is about 3X the size of this README file (because there are no dependencies)!

Motivation

There are not many bip-39 implementations for android
Most that do exist are not Kotlin
- or they are not idiomatic (because they are direct Java ports to Kotlin)
- or they have restrictive licenses
Most implementations fail to validate the checksum, which can easily lead to loss of funds!
- validating the checksum prevents: leading/trailing white space, valid words in the wrong order, mistyping a valid word (like chief instead of chef) and other similar issues that could invalidate a backup or lose funds.
No other implementation uses CharArrays, from the ground up, for added security and lower chances of accidentally logging sensitive info.

Consequently, this library strives to use both idiomatic Kotlin and CharArrays whenever possible. It also aims to be concise and thoroughly tested. As a pure kotlin library, it probably also works outside of Android but that is not an explicit goal (Update: confirmed to also work on a Ktor server).

Plus, it uses a permissive MIT license and no dependencies beyond Kotlin's stdlib!

Getting Started

Gradle

Add dependencies (see Maven badge above for latest version number):

dependencies {
    implementation "cash.z.ecc.android:kotlin-bip39:${latestVersion}"
}

repository {
    mavenCentral()
}

Usage

This library prefers CharArrays over Strings for added security.
Note: If strings or lists are desired, it is very easy (but not recommended) to convert to/from a CharArray via String(charArray) or String(charArray).split(' ').

Create new 24-word mnemonic phrase

import cash.z.ecc.android.bip39.Mnemonics.MnemonicCode

val mnemonicCode: MnemonicCode = MnemonicCode(WordCount.COUNT_24)

// assert: mnemonicCode.wordCount == 24, mnemonicCode.languageCode == "en"

Generate seed

val seed: ByteArray = mnemonicCode.toSeed()

Generate seed from existing mnemonic

val preExistingPhraseString = "scheme spot photo card baby mountain device kick cradle pact join borrow"
val preExistingPhraseChars = validPhraseString.toCharArray()

// from CharArray
seed = MnemonicCode(preExistingPhraseChars).toSeed()

// from String
seed = MnemonicCode(preExistingPhraseString).toSeed()

Generate seed with passphrase

// normal way
val passphrase = "bitcoin".toCharArray()
mnemonicCode.toSeed(passphrase)

// more private way (erase at the end)
charArrayOf('z', 'c', 'a', 's', 'h').let { passphrase ->
    mnemonicCode.toSeed(passphrase)
    passphrase.fill('0') // erased!
}

Generate raw entropy for a corresponding word count

val entropy: ByteArray = WordCount.COUNT_18.toEntropy()

// this can be used to directly generate a mnemonic:
val mnemonicCode = MnemonicCode(entropy)

// note: that gives the same result as calling:
MnemonicCode(WordCount.COUNT_18)

Validate pre-existing or user-provided mnemonic
(NOTE: mnemonics generated by the library "from scratch" are valid, by definition)

// throws a typed exception when invalid:
//     ChecksumException - when checksum fails, usually meaning words are swapped
//     WordCountException(count) - invalid number of words
//     InvalidWordException(word) - contains a word not found on the list
mnemonicCode.validate()

Iterate over words

// mnemonicCodes are iterable
for (word in mnemonicCode) {
    println(word)
}

mnemonicCode.forEach { word ->
    println(word)
}

Clean up!

mnemonicCode.clear() // code words are deleted and no longer available for attacker

Advanced Usage

These generated codes are compatible with kotlin's scoped resource usage

Leverage use to automatically clean-up after use

MnemonicCode(WordCount.COUNT_24).use {
    // Do something with the words (wordCount == 24)
}
// memory has been cleared at this point (wordCount == 0)

Generate original entropy that was used to create the mnemonic (or throw exception if the mnemonic is invalid).
- Note: Calling this function only succeeds when the entropy is valid so it also can be used, indirectly, for validation. In fact, currently, it is called as part of the MnemonicCode::validate() function.

val entropy: ByteArray = MnemonicCode(preExistingPhraseString).toEntropy()

Mnemonics generated by the library do not need to be validated while creating the corresponding seed. That step can be skipped for a little added speed and security (because validation generates strings on the heap--which might get improved in a future release).

seed = MnemonicCode(WordCount.COUNT_24).toSeed(validate = false)

Other languages are not yet supported but the API for them is in place. It accepts any ISO 639-1 language code. For now, using it with anything other than "en" will result in an UnsupportedOperationException.

// results in exception, for now
val mnemonicCode = MnemonicCode(WordCount.COUNT_24, languageCode = Locale.GERMAN.language)

// english is the only language that doesn't crash
val mnemonicCode = MnemonicCode(WordCount.COUNT_24, languageCode = Locale.ENGLISH.language)

Known issues

When publishing the library, a Gradle warning will be printed. This is a known issue in Kotlin Multiplatform and can be safely ignored.

Credits

zcash/ebfull - Zcash core dev and BIP-0039 co-author who inspired creation of this library
bitcoinj - Java implementation from which much of this code was adapted
Trezor - for their OG test data set that has excellent edge cases
Cole Barnes - whose PBKDF2SHA512 Java implementation is floating around everywhere online
Ken Sedgwick - who adapted Cole Barnes' work to use SHA-512

kotlin-bip39's People

Contributors

Stargazers

Watchers

Forkers

myhush jarmokukkola malachid jorisobert luca992 burnoo vaginessa assadipeyman

kotlin-bip39's Issues

Configure detekt

This should come after #18.

Update readme to remove reference to Jcenter

The artifact is published in Maven Central, so the readme can be updated to reflect this. There are two changes:

Replace jcenter with maven central
Bump the version in the readme, since maven central only has a slightly newer version.

Enhancement: add support for 6 and 9 words

Verify that 6 and 9 words work as expected, add tests to confirm the behavior and then merge the change made here:

JarmoKukkola@3f5100a

Fetch dependencies from MavenCentral

jcenter is deprecated, so migrate our build scripts to get dependencies from MavenCentral.

Block plugins from adding maven repositories

Is your feature request related to a problem? Please describe.

When Gradle plugins are applied, they can define their own Maven repositories. This could allow dependencies to come from sources that we don't trust.

Describe the solution you'd like

In settings.gradle.kts, configure

repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)

This is likely blocked until this is resolved: https://youtrack.jetbrains.com/issue/KT-52383/Kotlin-Multiplatform-Gradle-Plugin-Unable-to-disable-project-rep

Consider Using Kotlin Explicit API

Is your feature request related to a problem? Please describe.

Some Kotlin idols idioms can make it more likely to introduce accidental API changes or leakage of internals via the public API.

Describe the solution you'd like

https://kotlinlang.org/docs/whatsnew14.html#explicit-api-mode-for-library-authors

Convert build scripts to kts

For consistency with our other Gradle and Kotlin projects, convert our build scripts to kts.

This should likely be implemented after #15 and #16 since those have some syntax changes for build scripts.

GitHub Cache Action 3.0.4

https://github.com/actions/cache/releases/tag/v3.0.4

Configure Dependabot for GitHub Actions Versions

Is your feature request related to a problem? Please describe.

It is annoying to keep GitHub Actions dependencies updated.

Describe the solution you'd like

Although dependabot does not support Gradle yet, it does support GitHub Actions. So we can configure dependabot to help with this.

Switch to Adoptium JDK

Is your feature request related to a problem? Please describe.

Gradle toolchains only support Adoptium JDKs, however we have been recommending Zulu. This means different developers may have inconsistent JVMs. Although they should be compatible, it would be great to eliminate this variability in builds.

Describe the solution you'd like

Now that Adoptium publishes a Mac ARM JDK 11, we can remove using Zulu.

Update readme to remove references to Azul
Update GitHub Actions to use Adoptium

Binaries attached to GitHub Actions are empty

Describe the issue

The binaries generated from the GitHub Actions are empty when attached to the build.

Can you reliably reproduce the issue?

If so, please list the steps to reproduce below:

Run the staging deployment
Look at the output e.g. https://github.com/zcash/kotlin-bip39/actions/runs/2501530576

Expected behaviour

The output should have the JAR files.

Actual behavior + errors

The attached binaries are 22 bytes, e.g. they are empty.

Configure Deployment through GitHub Actions

Is your feature request related to a problem? Please describe.

In order to be able to release updates to the library, we should have automated deployments.

Describe the solution you'd like

Create an automated deployment with GitHub Actions, similar to the deployment configured in the Zcash Android SDK.

Steps that need to be completed:

Add markdown documentation on how CI works in this repo
Add documentation on how to consume snapshot deployments
Add secrets to GitHub for the main branch deployments. The necessary secrets are defined here: https://github.com/zcash/kotlin-bip39/blob/main/.github/workflows/deploy-release.yml
Test the deployments

Configure build-conventions

See https://github.com/zcash/zcash-android-wallet-sdk and https://github.com/zcash/secant-android-wallet for examples of what build conventions would look like.

Specific conventions would be:

Kotlin multiplatform
Android
...

Use version catalogs for dependencies

Migrate to using a toml-based version catalog for dependencies.

Update Contributing Guidelines "Commit Messages" section to reflect the changes on iOS SDK

Configure for included builds

Is your feature request related to a problem? Please describe.

When doing multiple included builds with build-conventions, things can break when modules or conventions have the same name.

This will be a problem if trying to use an included build for both bip-39 and the Android SDK.

Describe the solution you'd like

Rename the build-conventions folder to have a namespace.

Stop running ktlint under Java 11

Adding this to the ktlintFormat Gradle task should solve it:

jvmArgs("--add-opens", "java.base/java.lang=ALL-UNNAMED")

Coroutines 1.6.3

For a Gradle dependency:

Update the dependency version in the root gradle.properties
Update the dependency locks
1. For Gradle dependencies: ./gradlew resolveAll --write-locks
Verify no unexpected entries appear in the lockfiles. A supply chain attack could occur during this stage. The lockfile narrows the supply chain attack window to this very moment (as opposed to every time a build occurs).
Are there any new APIs or possible migrations for this dependency?
1. Minor update
2. https://github.com/Kotlin/kotlinx.coroutines/releases/tag/1.6.3

Enhancement: Add unit test to demonstrate that uppercase/lowercase words are handled properly

As a library user, I'd like to clearly understand how uppercase and lowercase letters are handled. This should be included in the readme, confirmed with a unit test, and future-proof for other languages. In other words, whatever approach that is taken should also work for every common language used for bip39 word lists.

jcenter shutting down

Hello,

jcenter repo is shutting down. Do you have any plans to migrate?

Add Contributor Setup Documentation

Is your feature request related to a problem? Please describe.

We have a number of ECC team members who are not familiar with IntelliJ and Kotlin. To help them be able to build this project from source, we should have easy to follow setup instructions.

Describe the solution you'd like

GitHub Setup Java Action 3.3.0

Are there any new APIs or possible migrations for this dependency?
1. https://github.com/actions/setup-java/releases/tag/v3.3.0

Configure Code Coverage Reports

Is your feature request related to a problem? Please describe.

Developers have a hard time understanding how well the tests cover the library.

Describe the solution you'd like

Introduce code coverage, most likely with the JetBrains Kover Gradle plugin.

Alternatives you've considered

We can manually apply Jacoco to generate coverage, although Kover will be more robust.

Configure Gradle Task to Identify Dependency Updates

Is your feature request related to a problem? Please describe.

Although we don't really include dependencies in the library, having a dependencyUpdates task to identify Gradle, Kotlin, and plugin updates would be helpful.

Describe the solution you'd like

https://github.com/ben-manes/gradle-versions-plugin

Add issue templates to this repo

See the https://github.com/zcash/zcash-android-wallet-sdk or https://github.com/zcash/secant-android-wallet for examples of the templates we'd use for bugs, features, and dependency updates.

Duplicate Gradle Wrapper

There's a duplicate copy of the Gradle wrapper under lib/. We just need the copies of these in the repo root. To resolve this, delete the following paths:

lib/gradle
lib/gradlew
lib/gradlew.bat

NoSuchMethodError: 'double kotlin.time.TimeMark.elapsedNow()'

From a clean checkout:

./gradlew clean
./gradlew test

Results in the stack trace identified here
kotest/kotest#1600

Update to Gradle 7.4.2

MnemonicCode Doesn't Implement Iterator Interface Correctly

Running detekt points out:

kotlin-bip39/lib/src/jvmMain/kotlin/cash/z/ecc/android/bip39/Mnemonics.kt:85:53: This implementation of Iterator does not correctly implement the next() method as it doesn't throw a NoSuchElementException when no elements remain in the Iterator. [IteratorNotThrowingNoSuchElementException]

Note that the detekt baseline will suppress this warning. When implementing this change, be sure to update the detekt baseline file to remove this suppression.

GitHub Actions Upload Artifact 3.1.0

Are there any new APIs or possible migrations for this dependency?
1. https://github.com/actions/upload-artifact/releases/tag/v3.1.0

Add Contributing Guidelines

Add contributing Guidelines present on the other projects like ZcashLightClientKit or secant-ios-wallet

Improve performance initializing Mnemonics

When Mnemonics is first touched, it performs an initialization of SecureRandom which is known to be slow.

While documenting this could be helpful, it doesn't give clients using this library a lot of options to work around it. That's because Mnemonics is an object, so initialization is effectively a JVM static initializer when means it runs as soon as something touches the object.

Possible alternative implementations:

Defer SecureRandom initialization until it is needed, giving clients better control over timing
Convert Mnemonics to a class, so that initialization happens during construction which allows clients better control over timing of the initialization
Create a companion object initializer. This could be a suspend function, allowing secure random injection into a private constructor for Mnemonics
... There may be other options to consider as well

Run tests on GitHub Actions

As a followup to #23, configure tests to also run on GitHub Actions.

GitHub Actions Cache 3.0.3

Are there any new APIs or possible migrations for this dependency?
1. https://github.com/actions/cache/releases/tag/v3.0.3

Update to Kotlin 1.6.21

Configure GitHub Actions

Create a basic GitHub action script to validate the gradle wrapper, compile the library, run ktlint, and detekt.

#24 is a followup issue to run the tests. Note that tests aren't being configured in this issue, because running the Android tests on CI can be complex. If we migrate to Multiplatform, then running those tests would be easier.

Configure dependency locking

Is your feature request related to a problem? Please describe.

To reduce the risk of software supply chain issues, we should enable dependency locking.

Although the published library itself doesn't depend on third party libraries, the Gradle build does rely on some plug-ins and the tests rely on some third party libraries.

Describe the solution you'd like

Enable dependency locking for the build scripts, build-conventions, as well as add a new dependency locking convention similar to https://github.com/zcash/secant-android-wallet/blob/main/build-convention/src/main/kotlin/zcash.dependency-conventions.gradle.kts

Fix environment for GitHub Actions Jobs

Our deployment jobs in GitHub actions are missing environment: deployment so they aren't able to read the secrets necessary for deployment.

Kotlin 1.7.0

For a Gradle dependency:

Update the dependency version in the root gradle.properties
Update the dependency locks
1. For Gradle plugins: ./gradlew dependencies --write-locks
2. For Gradle dependencies: ./gradlew resolveAll --write-locks
Verify no unexpected entries appear in the lockfiles. A supply chain attack could occur during this stage. The lockfile narrows the supply chain attack window to this very moment (as opposed to every time a build occurs).
Are there any new APIs or possible migrations for this dependency?
1. This should be relatively minor for our library
2. There are some new regex APIs
3. min/max are back on collections
4. https://kotlinlang.org/docs/whatsnew17.html

Configure ktlint

This depends on #20 to be implemented first.

Dependabot doesn't run on composite workflows

We need to explicitly add the path to the setup action.

ktlint 0.46.0

Update the dependency version in the root gradle.properties
Update the dependency locks
1. For Gradle plugins: ./gradlew dependencies --write-locks
Verify no unexpected entries appear in the lockfiles. A supply chain attack could occur during this stage. The lockfile narrows the supply chain attack window to this very moment (as opposed to every time a build occurs)
Are there any new APIs or possible migrations for this dependency?
1. Note there are some new rules introduced with this update that will require formatting changes or new @Suppress statements.

Prepare for 1.0.3 release

We need to prepare for a future release by:

Bumping the version to 1.0.3
Updating the Maven properties
Updating the changelog
Adding documentation on deployment
Testing out automated deployment

Configure Kotlin compiler warnings to be considered errors

To prevent compiler warnings from being introduced, they should be configured to be considered build errors. To implement this, add a property to gradle.properties so that this option can be turned off during local development if desired.

This should be implemented after #20

See https://github.com/zcash/secant-android-wallet for an example of how this was implemented.

Prepare development for next release (1.0.4)

This is a followup for after 1.0.3 is released, basically this is just a version bump for now.

Delete "run demo app" from review checklist

Since there's no demo app, this line should be deleted from the review checklist:

Run the app: Did you run the demo app and try the changes?

Dokka 1.6.21

For a Gradle dependency:

Update the dependency version in the root gradle.properties
Update the dependency locks

Are there any new APIs or possible migrations for this dependency?

Rename default branch

Is your feature request related to a problem? Please describe.

Our default branch names are not consistent for our Android projects.

Describe the solution you'd like

Align branch names for consistency, changing the default branch to main.

required changes include:

Setting the GitHub setting for the default branch
Verifying that branch protection/security rules are still in place and that deployment secrets are only available to the branch called main
Updating the deploy-snapshot.yml and deploy-release.yml to run on the main branch instead of master

Configure Java-only Multiplatform Build

Migrate to the Kotlin Multiplatform Gradle plugin, but without any actual multiplatform implementation.

Issue template for feature request mentions "secant wallet"

Visit the GitHub New Issue template chooser
Look at the description for the new feature template

electric-coin-company / kotlin-bip39 Goto Github PK

kotlin-bip39's Introduction

kotlin-bip39

Introduction

Motivation

Getting Started

Gradle

Usage

Advanced Usage

Known issues

Credits

kotlin-bip39's People

Contributors

Stargazers

Watchers

Forkers

kotlin-bip39's Issues

Is your feature request related to a problem? Please describe.

Describe the solution you'd like

Is your feature request related to a problem? Please describe.

Describe the solution you'd like

Is your feature request related to a problem? Please describe.

Describe the solution you'd like

Is your feature request related to a problem? Please describe.

Describe the solution you'd like

Describe the issue

Can you reliably reproduce the issue?

If so, please list the steps to reproduce below:

Expected behaviour

Actual behavior + errors

Is your feature request related to a problem? Please describe.

Describe the solution you'd like

Is your feature request related to a problem? Please describe.

Describe the solution you'd like

Is your feature request related to a problem? Please describe.

Describe the solution you'd like

Is your feature request related to a problem? Please describe.

Describe the solution you'd like

Alternatives you've considered

Is your feature request related to a problem? Please describe.

Describe the solution you'd like

Is your feature request related to a problem? Please describe.

Describe the solution you'd like

Is your feature request related to a problem? Please describe.

Describe the solution you'd like

Recommend Projects

Recommend Topics

Recommend Org