keystonehq/keystone3-firmware

The best open source hardware wallet

Keystone3 Firmware

Description

The Keystone3 Firmware is an advanced, highly secure software specifically crafted for the Keystone3 product, a state-of-the-art crypto hardware wallet. This project is laser-focused on delivering an exceptionally secure and intuitive user experience. It boasts cutting-edge features like PCI level anti-tamper protection, ensuring the highest security against physical and digital threats. Additionally, it supports Multi Seed Phrase functionality, which enhances security and recovery options, and includes safeguards against blind signing to protect against unauthorized transactions. The firmware also offers extensive support for a wide range of cryptocurrencies, catering to the diverse needs of crypto users.

Its standout features include:

1. Triple-layer security with Three Secure Element Chips, ensuring top-notch protection of your digital assets.
2. Advanced PCI level anti-tamper features, providing robust defense against physical tampering and hacking attempts.
3. A user-friendly interface offering an intuitive user experience, making it accessible even for those new to crypto hardware wallets.

Getting Started

Installation

MacOS

Follow these steps to set up your development environment on MacOS:

# Install GCC
brew install armmbed/formulae/arm-none-eabi-gcc
# If you encounter issues with Brew when installing GCC, switch to manual installation:
# Visit https://developer.arm.com/downloads/-/gnu-rm, and select the `9-2020-q2-update`

# Install Rust
# For instructions, visit https://www.rust-lang.org/tools/install
rustup install nightly-2023-06-26
rustup target add thumbv7em-none-eabihf
cargo install bindgen-cli
cargo install cbindgen

# Clone the repository
git clone https://github.com/KeystoneHQ/keystone3-firmware --recursive

Docker

Alternatively, use Docker to build the required environment:

docker build -t keystone3-baker:local .

Building the Firmware

Here's how to build the Keystone3 Firmware:

Building multi-coins firmware

# Run the build script at the root of the project.
python3 build.py

Building btc-only firmware

# Run the build script at the root of the project.
python build.py -t btc_only

Building img to C file

Please move the "img" file to the corresponding directory under the "images" directory.

The program will convert underscores in the file names to camel case, and add the appropriate prefix to the files.

Here are two ways to run it.

The first way is to execute the command below.

# Run the build script at the root of the project.
python img_converter.py

The second way is already integrated in the "build.py" file, so you can simply use it.

python3 build.py

# or
python build.py -t btc_only

Contributing

We welcome contributions! Here's how you can contribute:

• Fork the repository.
• Create your feature branch: git checkout -b feature/AmazingFeature.
• Commit your changes: git commit -m 'Add some AmazingFeature'.
• Push to the branch: git push origin feature/AmazingFeature.
• Submit a pull request.

Before submitting, ensure your code follows our formatting standards:

brew install astyle
cd tools && astyle -A3nrUpHcQ --exclude=../src/cm_backtrace/Languages "../src/*.c" "../src/*.h" && cd ..

FAQ

Q. How to build and verify the firmware?

A. Please check the detail guide on docs/verify.md

License

Please see the LICENSE.md file for details.

Contact

For support or inquiries, please contact us at [email protected]

keystone3-firmware's Issues

Custom BIP44 derivation paths

Hi,

Are there any plans to support custom BIP44 derivation paths? Keystone is an awesome device, but it's currently impossible to use it with custom derivation paths.

Basiclly, I'd like to input an arbitrarily long string, i.e. m/44'/x'/y'/z'/....'/0 , and have the addresses generated from the path.

Solflare Solana raw message in swap confirmation

Hi,
in SOLANA using Solflare, when i swap from token to token i get only raw message.
how can i trust transaction ?

Can i place SOLANA token address database in sdcard folder to give information to Keystone ?
like ERC20
any guide for this please ?

Thanks.

Customizing TRX derivation path in Ledger format

Hi. I was wondering whether there is an option to customize the derivation path for TRX to match the Ledger format, specifically "44'/195'/X'/0/0". Is there a way to configure this, and if so, could you guide me through the process? Appreciate any help you can provide.

Metamask Optimism sending USDT to other address error

Hi,

trying to send 30 usdt to other wallet, i get error.

the Keystone not support Optimism network ?
(latest firmware 1.2.8)

Thanks.

error: ctaes.h: No such file when building keystore.c

Using Docker, python build.py runs for some time getting and building stuff, but bombs out with...

[ 11%] Building C object CMakeFiles/mh1903.elf.dir/src/managers/power_manager.c.obj
[ 11%] Building C object CMakeFiles/mh1903.elf.dir/src/managers/screen_manager.c.obj
[ 11%] Building C object CMakeFiles/mh1903.elf.dir/src/msg/general_msg.c.obj
/root/work/src/managers/keystore.c:12:10: fatal error: ctaes.h: No such file or directory
   12 | #include "ctaes.h"
      |          ^~~~~~~~~
compilation terminated.
make[2]: *** [CMakeFiles/mh1903.elf.dir/build.make:1337: CMakeFiles/mh1903.elf.dir/src/managers/keystore.c.obj] Error 1
make[2]: *** Waiting for unfinished jobs....
[ 11%] Building C object CMakeFiles/mh1903.elf.dir/src/msg/user_msg.c.obj
[ 11%] Building C object CMakeFiles/mh1903.elf.dir/src/managers/se_manager.c.obj
[ 11%] Building C object CMakeFiles/mh1903.elf.dir/src/presetting.c.obj
[ 12%] Building C object CMakeFiles/mh1903.elf.dir/src/ram/psram_heap_4.c.obj
/root/work/src/managers/fingerprint_process.c:13:10: fatal error: ctaes.h: No such file or directory
   13 | #include "ctaes.h"
      |          ^~~~~~~~~
compilation terminated.
make[2]: *** [CMakeFiles/mh1903.elf.dir/build.make:1324: CMakeFiles/mh1903.elf.dir/src/managers/fingerprint_process.c.obj] Error 1
make[1]: *** [CMakeFiles/Makefile2:114: CMakeFiles/mh1903.elf.dir/all] Error 2
make: *** [Makefile:84: all] Error 2

I'm using docker for the build env. Docker is running in Ubuntu 22.04 (on PC hardware).

my clone is as of 703e885

docker build concluded with ...

 => => writing image sha256:103800ba852f985f487a998026a8f5e32a14521079c2237109ad74de64720428             0.0s
 => => naming to docker.io/library/keystone3-baker:local                                                 0.0s

Suggestion: Signing Commits

Merely a suggestion / discussion point, so please don't take this as a criticism!

Has the Keystone firmware development team considered making signed commits mandatory for the firmware related repositories?

Since this is some pretty critical code, it would add some further re-assurance if the core developers were utilising GPG (Yubikey, etc) hardware keys to sign their commits, lowering the likelihood of a (compromised) developer compromising any of the code (accidentally or not).

Your team and code complexity are growing pretty rapidly, so managing these sorts of easy to solve "attack" surfaces earlier, rather than later can prevent bigger security headaches later on, in my opinion (and experience).

Curious what your thoughts on this are, or hearing more on what your current policy is.

Custom entropy, ex Dices not available for 2nd wallet.

Only the first wallet let us change entropy source.

BTW the entropy form dices cannot be verified (according to Wicked) is this fixed?
https://www.youtube.com/watch?v=mVgPoQrbi7A

Test Issue

When changing derivation path from Ethereum accounts, derivation path remains unchanged in Connect Software Wallet

Observed on V3 hardware with fw 1.2.8

When I go through the Ethereum account menu and change the derivation path for the accounts, that settings change is not reflected in 3dots>Connect Software Wallet>MetaMask. I have to change the derivation path in the 3 dots menu available from Connect MetaMask a second time, to actually see the animated QR and add the addresses from the selected derivation path to MetaMask.

Should these two paths to the same setting remain in sync, so that when changed in one path that the change is reflected in both?

Reproduction steps:

1. Unlock Keystone
2. Enable Ethereum assets if not previously enabled
3. Tap Ethereum from the main landing page to be on Receive Eth
4. Tap 3 dots menu
5. Tap Change Derivation Path
6. Select Ledger Live
7. Tap checkmark to save (@~11 seconds in recording below)
8. Tap X to return to main landing page
9. Tap 3 dots menu
10. Tap Connect Software Wallet
11. Tap MetaMask
12. Tap 3 dots menu from Connect MetaMask
13. Note that derivation path change in step 6 is not reflected (@~16 seconds in recording below)

Recording: https://recordit.co/RPPWYxRRyX

Unable to clone this repo

When attempting to clone I get an error "ERROR: Repository not found." followed by "fatal: Could not read from remote repository."

wink@imacpro clones % git clone [email protected]:KeystoneHQ/keystone3-firmware --recursive
Cloning into 'keystone3-firmware'...
remote: Enumerating objects: 19978, done.
remote: Counting objects: 100% (3401/3401), done.
remote: Compressing objects: 100% (1124/1124), done.
remote: Total 19978 (delta 2459), reused 2935 (delta 2264), pack-reused 16577
Receiving objects: 100% (19978/19978), 118.79 MiB | 22.90 MiB/s, done.
Resolving deltas: 100% (13118/13118), done.
Submodule 'external/ctaes' (https://github.com/bitcoin-core/ctaes) registered for path 'external/ctaes'
Submodule 'keystone3-firmware-release' ([email protected]:KeystoneHQ/keystone3-firmware-release.git) registered for path 'keystone3-firmware-release'
Cloning into '/Users/wink/prgs/clones/keystone3-firmware/external/ctaes'...
remote: Enumerating objects: 108, done.        
remote: Counting objects: 100% (18/18), done.        
remote: Compressing objects: 100% (14/14), done.        
remote: Total 108 (delta 8), reused 4 (delta 4), pack-reused 90        
Receiving objects: 100% (108/108), 49.22 KiB | 323.00 KiB/s, done.
Resolving deltas: 100% (53/53), done.
Cloning into '/Users/wink/prgs/clones/keystone3-firmware/keystone3-firmware-release'...
ERROR: Repository not found.
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.
fatal: clone of '[email protected]:KeystoneHQ/keystone3-firmware-release.git' into submodule path '/Users/wink/prgs/clones/keystone3-firmware/keystone3-firmware-release' failed
Failed to clone 'keystone3-firmware-release'. Retry scheduled
Cloning into '/Users/wink/prgs/clones/keystone3-firmware/keystone3-firmware-release'...
ERROR: Repository not found.
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.
fatal: clone of '[email protected]:KeystoneHQ/keystone3-firmware-release.git' into submodule path '/Users/wink/prgs/clones/keystone3-firmware/keystone3-firmware-release' failed
Failed to clone 'keystone3-firmware-release' a second time, aborting

I also tried gh but I get the same error.

Suggestions on how to resolve?

suggestion : flag for silent erase of wallet

Keystone wallet can record up to 3 wallet, and the number of registered wallet is discoverable by trying to add new wallet. So for attacker with some knowledge he can know if we have hidden wallet or not. Would be nice when we setup a wallet we can set 1 non erasable wallet and 2 erasable wallet. These 2 will be silently erased when user add new wallet.
This is just an idea , maybe there is other solution, it might do more bad than good...

suggestion: been able to attach a pin to a passphrase

Hello,
Would be nice if we can enter twice the same seed mnemonic, but on one wallet we put an other passphrase, that's way we can easily unlock 2 different wallets, one with and one without passphrase

Dymension: can't vote, signing never finishes

How to reproduce:

1- Visit https://portal.dymension.xyz/dymension/governance
2- Try to vote
3- Scan QR code.
4- Press sign
5- The signing process never finishes ❌

Feature request: add FIDO U2F via USB

Add a way to use the Keystore 3 as a FIDO U2F device.

Similar to:
https://support.ledger.com/hc/en-us/articles/115005198545-FIDO-U2F?docs=true

When Scanning a QR code from keplr, keystone hangs

When interacting with a smart contract, the wallet hangs and restarts itself.

Firmware:

version 1.2.4

Example message:

{
  "txBody": {
    "messages": [
      {
        "typeUrl": "/cosmwasm.wasm.v1.MsgExecuteContract",
        "value": {
          "sender": "MY WALLET ADDRESS HERE",
          "contract": "kujira1e224c8ry0nuun5expxm00hmssl8qnsjkd02ft94p3m2a33xked2qypgys3",
          "msg": "eyJkZXBvc2l0Ijp7fX0=",
          "funds": [
            {
              "denom": "ibc/295548A78785A1007F232DE286149A6FF512F180AF5657780FC89C009E2C348F",
              "amount": "500000000"
            }
          ]
        }
      }
    ],
    "memo": "",
    "timeoutHeight": "0",
    "extensionOptions": [],
    "nonCriticalExtensionOptions": []
  },
  "authInfo": {
    "signerInfos": [
      {
        "publicKey": {
          "typeUrl": "/cosmos.crypto.secp256k1.PubKey",
          "value": "THIS ONE I ALSO REMOVE"
        },
        "modeInfo": {
          "single": {
            "mode": "SIGN_MODE_DIRECT"
          }
        },
        "sequence": "6"
      }
    ],
    "fee": {
      "amount": [
        {
          "denom": "ukuji",
          "amount": "3054"
        }
      ],
      "gasLimit": "305306",
      "payer": "",
      "granter": ""
    }
  },
  "chainId": "kaiyo-1",
  "accountNumber": "88399"
}

Other steps how to reproduce:

• Connect Keystone to Keplr
• Visit https://ghost.kujira.network/lend
• Try to lend or withdraw funds.
• Keplr will present a QR code to scan
• Scan the code
• See the wallet hangs or reset itself

What should happen:

• The user can sign the contract integration.

Side effects of boot img patch.

After applying boot logo typo patch below, distortion and blurring are visible in both the boot logo image and font.
c773983
And the resolution has also significantly decreased.

sha256 hash does not match for 1.2.0 keystone3.bin

FW release 1.2.0 stated hash 8fe42cfdfa80dd810acd51b1dd656cf81410373e9c892bc335d66d0e9e86ec3c
at https://github.com/KeystoneHQ/keystone3-firmware/releases/tag/1.2.0 is not correct.

When calculating hash for keystone3.bin file locally I'm getting:
SHA256 (keystone3.bin) = 8153dcf2391512ecd57a9fc1727a114d829a82f86fe8f94205616fff7920855

This does not match: 8fe42cfdfa80dd810acd51b1dd656cf81410373e9c892bc335d66d0e9e86ec3c as published

If I go into HW wallet settings and run verification from there then it shows the hash as stated for the release correctly

Permissioned `keystone3-firmware-release` access - unable to clone

I cannot recursively clone the keystone3-firmware repository because the keystone3-firmware-release submodule is permissioned.

➜  dev git clone https://github.com/KeystoneHQ/keystone3-firmware --recursive
Cloning into 'keystone3-firmware'...
remote: Enumerating objects: 34717, done.
remote: Counting objects: 100% (8508/8508), done.
remote: Compressing objects: 100% (2804/2804), done.
remote: Total 34717 (delta 6346), reused 7448 (delta 5666), pack-reused 26209
Receiving objects: 100% (34717/34717), 137.87 MiB | 9.18 MiB/s, done.
Resolving deltas: 100% (24743/24743), done.
Submodule 'external/ctaes' (https://github.com/bitcoin-core/ctaes) registered for path 'external/ctaes'
Submodule 'keystone3-firmware-release' ([email protected]:KeystoneHQ/keystone3-firmware-release.git) registered for path 'keystone3-firmware-release'
Cloning into '/home/fmorency/dev/keystone3-firmware/external/ctaes'...
remote: Enumerating objects: 108, done.        
remote: Counting objects: 100% (18/18), done.        
remote: Compressing objects: 100% (14/14), done.        
remote: Total 108 (delta 8), reused 4 (delta 4), pack-reused 90        
Receiving objects: 100% (108/108), 49.22 KiB | 1008.00 KiB/s, done.
Resolving deltas: 100% (53/53), done.
Cloning into '/home/fmorency/dev/keystone3-firmware/keystone3-firmware-release'...
ERROR: Repository not found.
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.

If I click on the submodule in GitHub I get

Request for more information about FMC tool

Hello, I'm Daniel and I work with walletscrutiny.com.

Following instructions on the Keystone3 Pro project, found here:

It would appear that the checksums of the built file and the downloaded unsigned binary are identical:

------------------------
(SIGNED) Binary from Keystone Website :
b85edf5bd058028e708437c125ad3d67ab6da520b402d9aec59b47705f3a5509  keystone3.bin
------------------------
------------------------
Binary from build process:
427e41a1b0bb25d122e06884464f1cebd7b526b35c975a39151a8e6ffc2fc352  ./build/mh1903.bin
------------------------
------------------------
Unsigned Binary from Keystone Website :
Firmware checksum sha256: 427e41a1b0bb25d122e06884464f1cebd7b526b35c975a39151a8e6ffc2fc352 
You can check this value on your device.
------------------------
Unsigned .bin hash must be the same as mh1903.bin.

The unsigned binary has the same checksum with mh1903.bin IF you use fmc to compare them.

However, I tried to run $ sha256sum keystone3-unsigned.bin and came up with a different result:

$ sha256sum keystone3-unsigned.bin 
28ed8ee1f31f53dbb83bc4d83d64b596b6033a13fe04ba9baae5863c85b1fb5f

I'm struggling to find information about the FMC tool itself. Would be happy to receive guidance. Thank you.

Keystone fails to sign EIP-3009/EIP-712 message related to Polygon bridge

We have come across an issue that is specific to Keystone hardware wallet, and this wallet only. Currently repeatable on firmware 1.2.4 but likely all firmware affected.

• Ethereum has a signing standard called EIP-712 which is used to sign various messages
• Most popular messages are related to token swaps and transfers
• One of the implementations is EIP-3009 "transferWithAuthorization" that is implemented by USDC, many bridged tokens
• Polygon has a particular implementation of this standard for their bridged tokens called UChildAdministrableERC20

What happens

• Our TradingStrategy.ai is a Dapp EIP-3009 is used to to do deposits (instead of two transaction ERC-20 approve() + transferFrom(), saving one transaction)
• The deposits work on every other wallet, except with Keystone

Root cause

• EIP-712 message signing is a "flexible" standard and its implementations vary a bit
• Poygon's UChildAdministrableERC20 implements this standard partially, namely having some issues related to the chainId and such parameters - we are not sure if these should be optionally or not
• All other wallets handle these parameters, or the lack of them, correctly
• Keystone doesn't work this particular implementation of EIP-712 message signing Polygon's UChildAdministrableERC20 is using

We believe this bug is specific to Polygon's EIP-3009/EIP-712 implementation, but it likely concerns other smart contracts and chains as well. There are working smart contracts that accept EIP-712 messages from Keystone.

We have tested

• Rabby + Keystone
• Rabby only
• Rabby + MetaMask
• TrustWallet
• Uniswap wallet
• etc.

Only Keystone has the issue.

How to repeat

• Have Rabby, Keysyone, some MATIC on Polygon
• Swap some MATIC to USDC.e (Polygon bridged USDC, not native one)
• Go here and click deposit
• The transaction fails in the simulation before being broadcasted

GasAbstraction: invalid signature is the revert message from UChildAdministrableERC20 when it tries to verify the signature signed with Keystone.

[Typo] Typo on the boot screen. (Keystone 3 Pro Bitcoin-Only Firmware)

When updating the Keystone 3 Pro Bitcoin-Only Firmware (released on April 2, 2024), there is a typo on the boot screen.
It says 'Bitcion Only' instead of 'Bitcoin Only'.

Suggest a valid 12th or 24th word.

There are many custom entropy technique that produce 11 or 23 words and requires the wallet to generate a valid checksum word.

Request for ERC20 approvals to be displayed in decimal rather than hex

When signing a spending approval on an ERC20, the details tab will represent the approval amount in hex. This could be more clear for users if this value was displayed in decimal.

In the attached screenshot, I submitted and approval for 1.2345 on a 4 decimal ERC20 that I had deployed on a testnet. However, in firmware 1.2.4 on hardware v3 this value was shown as 3039.

Reproduction steps:

1. Setup Keystone v3
2. Bind to MetaMask (v11.7.2 tested with Chrome 117.0.5938.92)
3. Select Keystone address as active
4. Be on testnet
5. Go to test dapp
6. Connect
7. Scroll down to Send tokens section and tap CREATE TOKEN
8. Once confirmed, Add it to wallet with ADD TOKEN(S) TO WALLET
9. tap APPROVE TOKENS cta in test dapp
10. edit the amount if you chose
11. Tap Next in MetaMask
12. Tap Approve in MetaMask
13. Open MetaMask again bc open issue
14. Scan QR with Keystone
15. Tap details tab and scroll down

Seeking slip39 tests

I'm trying to implement a recent revision of the SLIP-39 specification.

I would like to ask

• whether you have tests covering slip39 mnemonic generation and recovery and
• (if so) what the easiest way is to run them.

Problem with enlarging Bitcoin QR code on the device after certain actions

Problem with enlarging Bitcoin QR CODE on the device after certain actions

Steps to reproduce the bug:

Assume that a wallet has already been created on the device:

Activate Bitcoin if it is not active

Click on Bitcoin

The QR of the Bitcoin address will be displayed.

You will be able to enlarge said QR with a tap on the screen

Next, press the 3 dots at the top

Press "Export xPUB"

The xPUB will be displayed in extended form

Then, go back

The previously displayed Bitcoin address will be displayed

Press on the screen to enlarge the QR

Abnormal behavior highlighted:

The device will not enlarge the QR and will not respond

Expected behavior:

The device enlarges the QR without any problems

Tested on firmwares: 1.30 and 1.28

feat: Cosmos: add multiple accounts (derivation paths)

Feature request: add multiple derivation paths inside a single seed phrase.

Request: Screen timeout when plugged in

Currently when the Keystone Pro 3 is plugged in and the screen is on, it never turns off even if a timeout is set. This is potentially a security concern, but also can result in screen burn-in if left on for extended periods of time.

Following the practice of mobile phone it would be convenient if the following options were available:

• A separate screen timeout for when the keystone is plugged in vs. on battery
• A separate screen timeout for when the screen should turn off (but leaving the keystone unlocked) vs. when the device should lock.

Ultimately giving the user 4 different timeouts that they can configure.