Kotlin BIP-39

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

License

License

Categories

Categories

Kotlin Languages
GroupId

GroupId

cash.z.ecc.android
ArtifactId

ArtifactId

kotlin-bip39
Last Version

Last Version

1.0.2
Release Date

Release Date

Type

Type

pom.sha512
Description

Description

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

Project URL

https://github.com/zcash/kotlin-bip39/
Source Code Management

Source Code Management

https://github.com/zcash/kotlin-bip39/

Download kotlin-bip39

Dependencies

runtime (1)

Group / Artifact Type Version
org.jetbrains.kotlin : kotlin-stdlib-jdk8 jar 1.4.30

Project Modules

There are no modules declared in this project.

kotlin-bip39

license @gmale Bintray

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 bintray badge, above, for latest version number such as 1.0.1):

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

repository {
    jcenter()
}

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)

Test Results

Screenshot from 2020-06-06 15-14-39

Credits

  • zcash/ebfull - Zcash core dev and BIP-0039 co-author who inspired me to create 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

License

MIT

cash.z.ecc.android

Zcash

Internet Money

Versions

Version
1.0.2