Initial commit

Author: BryanJacobs

.gitignore

@@ -0,0 +1,3 @@
+/.gradle
+/.idea
+/build

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022 BryanJacobs
+Copyright (c) 2022 Bryan Jacobs
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -0,0 +1,77 @@
+# FIDO2 CTAP2 Javacard Applet
+
+## Overview
+
+This repository contains sources for a FIDO2 CTAP2 compatible(-ish)
+applet targeting the Javacard Classic system, version 3.0.4. In a
+nutshell, this lets you take a smartcard, install an app onto it,
+and have it work as a FIDO2 authenticator device with a variety of
+features. You can generate and use OpenSSH `ecdsa-sk` type keys. You
+can securely unlock a LUKS encrypted disk with `systemd-cryptenroll`.
+
+This applet does **not** presently implement U2F support, for
+[valid reasons](docs/FAQ.md).
+
+In order to run this, you will need
+[a compatible smartcard](docs/requirements.md).
+
+You might be interested in [reading about the security model](docs/security.md).
+
+## Building the application
+
+You'll need to get a copy of:
+- com.licel.jcardsim-3.0.5
+- JavacardKit, version 3.0.4 (`jckit_304`)
+
+Drop the jcardsim jar into the root of the repository. Set the
+environment variable `JC_HOME` to point to your jckit folder.
+
+Run `./gradlew buildJavaCard`, which will produce a `.cap` file
+for installation.
+
+## Testing the application
+
+While you can test on an actual smartcard, I prefer to use VSmartCard
+and run JCardSim connected to that. There are a few example JCardSim
+unit tests in the repository, but you'll get much better analysis
+of the behaviour by using real applications or other testing suites
+like SoloKey's `fido2-tests`, which you can run against the simulated
+application.
+
+The `VSim` class might get you started.
+
+## Contributing
+
+If you want to, feel free!
+
+## Where to go Next
+
+I suggest [reading the FAQ](docs/FAQ.md) and perhaps [the security model](docs/security.md).
+
+## Implementation Status
+
+| Feature                        | Status                                                  |
+|--------------------------------|---------------------------------------------------------|
+| CTAP1/U2F                      | Not implemented                                         |
+| CTAP2.0 core                   | Implemented, many caveats                               |
+| CTAP2.0 hmac-secret extension  | Implemented                                             |
+| Resident keys                  | Implemented                                             |
+| CTAP2.1 alwaysUv               | Implemented                                             |
+| CTAP2.1 PIN Protocol 1         | Implemented                                             |
+| User Presence                  | User always considered present: not standards compliant |
+| CTAP2.1 credProtect extension  | Implemented, one caveat                                 |
+| CTAP2.1 credential management  | Mostly implemented - no user update                     |
+| CTAP2.1 PIN Protocol 2         | Not implemented                                         |
+| Attestation certificates       | Not implemented                                         |
+| CTAP2.1 Enterprise attestation | Not implemented                                         |
+| Self attestation               | Implemented                                             |
+| ECDSA (SecP256r1)              | Implemented                                             |
+| CTAP2.1 authenticator config   | Not implemented                                         |
+| CTAP2.1 blob storage           | Not implemented                                         |
+| Other crypto like ed25519      | Not implemented                                         |
+| Extended APDUs                 | Supported                                               |
+| APDU chaining                  | Supported                                               |
+| Performance                    | Adequate                                                |
+| Resource consumption           | Constant, but unoptimized                               |
+| Bugs                           | Yes                                                     |
+| Code quality                   | No                                                      |

build.gradle

@@ -0,0 +1,49 @@
+buildscript {
+    repositories {
+        mavenCentral()
+        maven { url "https://javacard.pro/maven" }
+        maven { url "https://deadcode.me/mvn" }
+    }
+    dependencies {
+        classpath("com.klinec:gradle-javacard:1.8.0")
+    }
+}
+
+plugins {
+    id("java")
+    id("com.klinec.gradle.javacard") version "1.8.0"
+}
+
+group = "us.q3q"
+version = "1.0-SNAPSHOT"
+
+repositories {
+    mavenCentral()
+}
+
+dependencies {
+    testImplementation(files("./jcardsim-3.0.5-SNAPSHOT.jar"))
+
+    testImplementation("org.junit.jupiter:junit-jupiter-api:5.8.1")
+    testRuntimeOnly("org.junit.jupiter:junit-jupiter-engine:5.8.1")
+}
+
+test {
+    useJUnitPlatform()
+}
+
+javacard {
+    config {
+        jckit System.getenv("JC_HOME")
+        cap {
+            packageName 'us.q3q.fido2'
+            version '0.1'
+            aid 'A0:00:00:06:47'
+            output 'FIDO2.cap'
+            applet {
+                className 'us.q3q.fido2.FIDO2Applet'
+                aid 'A0:00:00:06:47:2F:00:01'
+            }
+        }
+    }
+}

docs/FAQ.md

@@ -0,0 +1,40 @@
+# Frequently Asked Questions
+
+## How can you have an FAQ on a newly-created repository? Surely the questions aren't frequent yet.
+
+You caught me, I'm a fraud and these are anticipatory questions.
+
+## What's FIDO2?
+
+If you don't know what that is, you don't need this.
+
+## What's a JavaCard?
+
+If you don't know what that is, you DEFINITELY don't need this.
+
+## Don't you need a CBOR parser to write a CTAP2 authenticator?
+
+Apparently not. Instead of implementing a real CBOR parser I just
+poured more sweat into the implemnentation, and added a topping of
+non-standards-compliance.
+
+As a result of not having a proper CBOR parser, the app will often
+return undesirable error codes on invalid input, but it should
+handle most valid input acceptably.
+
+## Why did you write this, when someone else said they were almost done writing a better version?
+
+Well, they said that, but they hadn't published the source code and I got impatient.
+
+Two is better than zero, right?
+
+## Why did you write this at all?
+
+I was pretty unhappy with the idea of trusting my "two factor" SSH
+keys' security to a closed-source hardware device, and even the
+existing open hardware devices didn't work the way I wanted.
+
+I wanted my password to be used in such a way that without it, the
+authenticator was useless - in other words, a true second factor.
+
+So I wrote a CTAP2 implementation that [had that property](security.md).

docs/requirements.md

@@ -0,0 +1,29 @@
+# Runtime requirements
+
+This app requires Javacard 3.0.4. I really, really, really wanted to
+support Javacard 3.0.1, which runs on cool products like the
+Mclear/NFCRings.com OMNI Ring (seriously nice tech!).
+
+Unfortunately, CTAP2.0 requires an EC diffie-helmann key exchange
+in order to support PINs or the hmac-secret extension, and it uses
+DH with a SHA256 hash. Javacard 3.0.1 supports only ECDH-SHA1.
+Javacard 3.0.4 doesn't support ECDH-SHA256 either... but it provides
+a "plain" variant that returns the raw DH output which you then
+hash yourself - good enough for me.
+
+So it's not possible to make this app work in a meaningful way on
+Javacard 3.0.1 or earlier.
+
+So let's discuss the full requirements:
+
+- Javacard Classic 3.0.4
+- Approximately 2kB of total RAM, of which around 300 bytes will be reserved
+- Support for AES256-CBC
+- Support for ECDH-plain
+- Support for SHA-256 hashing
+- Support for EC with 256-bit keys
+- Approximately 15k of storage by default (very tunable)
+- Ideally, support for EC TRANSIENT_DESELECT keys, as otherwise you'll get flash usage every app selection
+
+An example of a card I've tested working is the NXP J3H145, but many
+others should work fine too.

docs/security.md

@@ -0,0 +1,144 @@
+# Security Model
+
+First off, this application is likely not secure. It hasn't been
+audit, fuzz tested, or even really tested at all. That means
+there's very likely a critical bug that breaks its model.
+
+This page aims to describe the **theoretical** security of the
+app, with that in mind. It focuses on cases where this authenticator
+deviates from what you might expect from the CTAP2 standard.
+
+## Principle: PINs Matter
+
+The core principle of a FIDO2 device is to be one of two factors.
+The authenticator represents "something you have". The PIN represents
+"something you know".
+
+Gaining complete access to the authenticator should not be useful for
+an attacker unless they know your PIN.
+
+Traditional implementations of FIDO2 devices do this by storing the
+PIN on the device "securely", and then relying on the correctness
+of their software and the tamper-proofness of their hardware to
+protect private keying material.
+
+This app is different. In this app, once you set a PIN, the "wrapping
+key" - without which the authenticator is useless - is encrypted using
+a key derived from the PIN. This means no credentials can be created
+or used unless you provide your PIN...
+
+## Details: Security Levels
+
+On boot, the device generates an AES256 key, the "wrapping key".
+
+Each individual credential issued by the app is a SecP256r1 keypoint,
+generated randomly on-device for that credential. The private key
+is then AES256-CBC encrypted along with the RP ID, using a random
+IV, and the result is used as the "credential ID".
+
+This means relying parties are holding their own encrypted private
+keys. The keypair itself provides approximately 128 bits of
+brute-force resistance. The wrapping key provides a strong 256 bits.
+
+The wrapping key is - when a PIN is set - encrypted using a "PIN key"
+produced by running five (by default) rounds of PBKDF2 over the first
+sixteen bytes of a SHA-256 of the user's PIN, with a 28-byte random
+salt. This means that "unwrapping" the wrapping key, were an attacker
+to gain access to it, would require a targeted attack whose brute-force
+difficulty is at most 128 bits, and is likely set by the entropy of
+the user's PIN.
+
+**Use a strong PIN** if you care about security in the event your
+device is entirely compromised. Despite the name, there is no
+requirement that PINs be numeric. You can use any sequence of
+characters up to 64 bytes long.
+
+### hmac-secret keys
+
+The hmac-secret extension keys are made by performing an HMAC-SHA256
+of a particular credential's ECDSA private key, using a unique
+32-byte key. This makes the brute-force resistance of these keys
+dependent on the entropy in a raw ECDSA private key, which is
+somewhat less than 256 bits and likely considerably stronger
+than the ECDSA keypair itself.
+
+## Threat Modeling
+
+### An attacker has my device and knows my PIN
+
+The attacker is you. Do better next time.
+
+### An attacker can intercept traffic to and from my authenticator
+
+Yeah, that's how NFC works.
+
+The important parts of the traffic are encrypted and authenticated
+with ECDH. The attacker cannot reasonably "see" your PIN. They can
+see incidental data like credential IDs being newly created, but
+the security impact is minimal.
+
+If they can forge traffic to the authenticator, they could hard-reset it,
+wiping your keys.
+
+### An attacker has malware on the machine I'm using with my authenticator
+
+- The attacker could reset the authenticator, deleting your keys
+- They could keylog your PIN, removing its additional security, but
+  only when you provide it on the compromised machine
+- They could attempt to guess your PIN, but they only get eight tries
+- If they DO get your PIN, they can use the authenticator as you
+  for the duration it's connected to the compromised machine
+- If you haven't set a PIN, that's the same as them knowing your PIN
+  for this threat model
+
+### An attacker has physical acccess to my smartcard, and I didn't set a PIN
+
+The attacker has fully compromised your security and can use the
+authenticator to pretend to be you in any way it is able.
+
+Resident keys stored on the device will let the attacker see your
+user IDs on different web sites, etc. They can use those to log
+in to those sites.
+
+Non-resident keys are slightly better: the attacker has to guess
+which service you'd registered with, and your username.
+
+### An attacker has physical access to my smartcard, but I set a PIN
+
+If the smartcard itself is physically secure, this is the same as
+the "malware" case above. **If not**, then we are in an interesting
+situation.
+
+The attacker needs to decrypt the on-device wrapping key. Without
+doing that, they can see incidentals like:
+- how many different resident keys you've stored on the device
+- how long each key's RP ID is, if less than 32 characters
+- how long each key's user ID is
+- how many different RPs in total have resident keys on the device
+
+What they can't do without decrypting the wrapping key is get at
+your actual credentials for sites - the private keys, the RP IDs,
+etc. They might - if your device doesn't support transient memory
+for EC private keys AND was inopportunely powered off the last time
+you used it - be able to use the most recently used keypair you did.
+
+#### Decrypting the wrapping key
+
+As described above, the wrapping key is itself encrypted using
+PBKDF2 with a very low iteration count, performed on the first
+sixteen bytes of your PIN's SHA256 hash. This means the attacker is
+unlikely to already HAVE a rainbow table, but they can start
+brute-forcing your PIN.
+
+If you used a strong PIN, you're likely okay for quite a while.
+
+### I left my authenticator plugged into my computer, after entering my PIN
+
+Anyone can use your authenticator as you. Despite what the CTAP2 standard
+says about user presence, it's not readily possible to implement
+a "timeout" on a Javacard 3.0.4 device. Javacard 3.1 introduces an
+(unreliable) uptime counter....
+
+But the implementation currently always assumes user presence.
+
+This Could Be Better.

gradle/wrapper/gradle-wrapper.jar

@@ -0,0 +1,5 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-7.4-bin.zip
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists