coldcard/firmware
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

MOre

Browse Source
This commit is contained in:
Peter D. Gray 2019-07-29 10:55:30 -04:00
parent a62c010f51
commit cef4669c15
1 changed files with 68 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

92
docs/pin-entry.md
View File

@ -183,6 +183,13 @@ This double-hashed value is what's stored inside the secure element
as it travels on the bus. Because of the inclusion of the pairing
secret, the hashes generated by each Coldcard will be different.
With Mark3 hardware, we've added a key-streching step, which starts
with the above value, and does HMAC-SHA256 using a secret key known
only to the 608a (repeatedly). That value is used directly to check the
duress PIN, and if that doesn't match, it is HMAC-SHA256'ed again,
using a key that is usage limited. This limits actual PIN login attempts
to a set value and is enfoced by the 608a internally.
## Genuine vs. Caution Lights
The green light will be lit **only** if the entire flash memory contents
@ -304,7 +311,7 @@ Idea: Find or steal a Coldcard. Load your trojan firmware onto it. Profit.
## Four Types of wallets, one Coldcard
The Coldcard effectively supports four independent wallets:
The Coldcard before Mark 3, effectively supported four independent wallets:
primary (main), secondary, main duress, secondary duress.
The secondary wallet is a little less capable than the main one,
@ -315,9 +322,14 @@ wallet has the same secret protection, PIN retry counters and so on.
The intention is that main and secondary wallets are completely
independent of each other, in terms of funds and wallet seeds.
### Duress Wallets
In Mark 3, we removed the secondary wallet because we could not
support PIN retry limits like the main wallet. We now recommend
BIP39 passphrases to introduce an unlimited number of secondary
wallets.
Duress wallets could store any 72-byte secret, and it's as well
### Duress Wallet
Duress wallet could store any 72-byte secret, and it's as well
protected as the main/secondary secrets, but we only enable use of
the duress wallet when attempting access to the corresponding
main/secondary wallet. The PIN failure and retry delays are linked
@ -362,7 +374,7 @@ Where:
## Problems with changing PIN codes on Duress Wallets
We want users (and thugs) who are logged-in with the duress PIN to
experience a complete wallet experience. However, there are some
have a complete wallet experience. However, there are some
problems when they start to change PIN codes like a normal user would.
If they try to change the main PIN code, we can detect that and change
the "duress" PIN code instead. To them, it looks like the main PIN
@ -443,8 +455,8 @@ weaker 4-digit PIN prefix, that's only 30k of data. If this type
of attack is your concern, we suggest using the longest possible
PIN prefix.
(For mark 2 )
We are rate-limiting this as follows: 150ms response time for first
For Mark 2 and earlier, we
are rate-limiting this as follows: 150ms response time for first
10 values, then 2.5 seconds each for the next 15 (up to 25). At
25 tries, we crash the system and a power cycle will be required
to continue. With about 9,999 combinations to cover all 4-digit
@ -454,7 +466,9 @@ firmware and get it onto the device. Any successful login resets
the rate limiting, so normal users will never see the impact of
this limiting.
(mark 3) See section below on new rate-limiting approach.
For Mark 3 hardware, the rate is fixed to 2 seconds per
value. See section below on how we assure this by performing
multiple rounds of HMAC-SHA256.
# How It Works
@ -467,7 +481,12 @@ The full datasheet recently has been made public after being under NDA for
years. To get further into our design, you will need to understand the chip's
capabilities.
## Background
Unfortunately, the datasheet for the ATECC608A is still under NDA.
There is nothing we can do about this, and we want the powerful new
features enabled by this part. We have explained to Microchip why
security by obscurity is bad idea, but they have business reasons.
## Mark 2 and Earlier Key Layout
The 508a (Microchip ATECC508A) has 16 key slots. Each can be
configured in numerous ways. The chip has two two high-endurance
@ -533,6 +552,27 @@ zone is not read-protected and it can be read very easily. It can
be done from Micropython level or your could connect directly to
the chip.
## Mark 3 Key Layout
The 608a (Microchip ATECC608A) also has 16 key slots. Unlike the
508a, one of those slots can be used to dynamically change
the usage limit of another key. In Mark 3 we removed secondary wallet
support, and use a new keyslot for key stretching.
pairing 1 Shared secret with bootloader code.
pin_strech 2 Random value used for anti-phishing feature and key stretching
main_pin 3 PIN for main wallet
lastgood 5 Last successful login attempt (main PIN)
match_count 6 Holds max value for counter0 (or else be a brick)
duress_pin 7 Duress PIN for main wallet
long_secret 8 Long secret: 416 bytes of secret value (new in Mark 3)
secret 9 Wallet seed (main): 72 bytes of ultra secrets
duress_secret 10 Wallet seed (duress): 72 bytes of fake secrets
duress_lastgood 11 Fake 'last good' counter updated when duress PIN used
brickme 13 "Brickme" PIN storage
firmware 14 Hash of flash contents, controls red/green light
The remainder of the background information above applies to the 608a as well.
## "Knowledge of" Keys
@ -567,7 +607,7 @@ in the hashes. Of course, every single bit must be correct or nothing
works, and a meaningless error is returned.
## Securely rate-limiting PIN retries
## Securely Rate-Limiting PIN Retries
In our system, we do not trust the main firmware with any secrets...
at least until it proves it knows the PIN. To achieve this separation,
@ -605,7 +645,7 @@ by an HMAC generated by the bootloader. The HMAC includes both the
pairing secret and also a unique value-per-boot to prevent replays.
### Delay Policy (before Mk3)
### Delay Policy (before Mark 3)
Here is the delay you'll be forced into based on the
number of failed PIN attempts, since your last successful login:
@ -621,8 +661,9 @@ number of failed PIN attempts, since your last successful login:
| more | 8 hours
In Mark 3, no extra delay is enforced, but a warning and confirmation
is shown every 5 attempts so that you don't burn through you limited
attempts too causually.
is shown after 3 failed attempts, so that you don't burn through
your limited attempts too causually. When all attempts have been
consumed, the unit bricks itself and must be recycled as e-waste.
## Limitation
@ -658,10 +699,10 @@ improve Coldcard security as follows:
perform. The previous delay/rate limit policy was removed, in
favour of the delay enforced by this process.
- Anti-phishing words are calculated with same HMAC-SHA256 chain, but with lower
- Anti-phishing words are calculated with same HMAC-SHA256 chain, but with higher
iteration count, and a different starting value.
- An addition 416 bytes of secrets storage is enabled (in addition to 72 bytes of storage
- An additional 416 bytes of secrets storage is enabled (in addition to 72 bytes of storage
previously stored).
- The secondary wallet feature had to be removed, because there is only one limited-use
@ -671,17 +712,19 @@ improve Coldcard security as follows:
This is a defense against any unknown security issues which compromise the secrets in
the 608a and not the main micro itself.
- Successfully using the duress PIN will not cost an attempt on the real PIN. If the duress
PIN works, we show zero login failures, but the number of PIN attempts has not
actually been reset.
- Successfully using the duress PIN will not cost an attempt on the real PIN. If the
duress PIN works, we show zero login failures, but the number of PIN attempts has
not actually been reset.
## Rate Limiting Method
The user enters a short pin code and we need to convert that into
a 32-byte value used to unlock the secrets. We want to understand
the upper bounds on the rate at which those "pin attempts" can be done.
the upper bounds on the rate at which those "pin attempts" can be
done, even though on Mark 3, only a few attempts can be done
before it bricks itself.
Here are the steps in peusdo code. We've also written it in Python
Here are the steps in pseudo code. We've also written it in Python
to check our work, see `stm32/bootloader/mathcheck.py`, and of
course the code actually being used is written in 'C' and available in
`stm32/bootloader/{ae,pins}.[ch]`.
@ -721,7 +764,7 @@ course the code actually being used is written in 'C' and available in
(result is upper 22 bits of md)
Of course we all heat our homes with fast SHA256 hashing chips... but
the rate limiting factor here is the communication time in and out
the rate limiting factor here is the communication data rate, in and out
of the secure element. That can't be avoided since only it knows the HMAC
key being applied.
@ -751,13 +794,13 @@ bits, and at 230400 bps, this takes 8ms. The secure element isn't
too fast with it's processing either, so it is adding at least 22ms
(best case times, as documented). In total, looks like 30ms is
best-case time to complete a single iteration of the stretching.
For the main PIN, we are using 8 iterations, so max rate is about
one second.
For the main PIN, we are using 8 iterations, so max theoretical
rate is about 240ms.
Unfortunately, what isn't shown above is all the SHA256 operations
that are needed to do the above dance. Those are implemented in the
main micro and are not very fast. As a result, the actual pin-entry
delay is about 4 seconds as measured.
delay is about 4 seconds (measured).
It's important to understand that all PIN attempts are further
limited by a monotonically-increasing counter implemented in
@ -765,6 +808,7 @@ the secure element. Brute forcing PIN codes are also blocked
by that process, which limits failed PIN attempts to just 13.
The rate-limiting is more important for the "anti-phsishing" prefix
words, see discussion above.
words, see discussion above. For that case, we use 16 iterations,
and it runs at about 2 seconds realtime.