microsoft / securedeviceconnectionprotocol

Secure Device Conneciton Protocol sample and documentation

Secure Device Connection Protocol

The Secure Device Connection Protocol (SDCP), is designed to enable secure biometrics with fingerprint sensors, providing a mechanism to ensure that:

1. The device is trusted.
2. The device is healthy.
3. The input from the device is protected.

Thorough documentation can be found on the wiki.

Sample Client Implementation

This repository contains a sample client implementation of the protocol documented in the wiki, using the mbed TLS library, which must be obtained and installed prior to building the sample.

Build

To build this sample, the mbed TLS library must have already been built and installed on your system. CMake and a C compiler for your platform are required.

Linux (Tested on Windows Subsystem for Linux, using Ubuntu)

git clone https://github.com/Microsoft/SecureDeviceConnectionProtocol.git
cd SecureDeviceConnectionProtocol
mkdir build
cd build
cmake ..
make

Windows (With Visual Studio)

git clone https://github.com/Microsoft/SecureDeviceConnectionProtocol.git
cd SecureDeviceConnectionProtocol
mkdir build
cd build
cmake ..

And then open sdcp.sln with Visual Studio

Test

This repository contains a test executable, sdcptest, that can be used to generate test vectors for your own client implementation of the protocol, and can be used as a reference for the expected calling pattern of the client functions. Example output:

Model and device keys:
----------------------

pk_m:
  04c5eb2c24de08a4dd9cfd42c5bc5610277d492111f151bf33ad71ad9525401d
  00d9320976c3c83980fab279d04d1fc9f4196da4d68a2f3b6891189af231bf50
  88
sk_m:
  5496111c965ef41c9cf91e54b38d714b4e7d7c482dcb34a3ec5e7265cf6ec800

Factory provisioning:
---------------------

pk_d:
  04840f109357fbf397e44c895cbfaff6b27527866828c94353120941b6020b1d
  be75ffd7b22b7ee2b7a57e8e89007f06eee43b7b8fceb382f8a6e78b812ed437
  f9
sk_d:
  d9aaf63632d61fa52da80260fdc0bb3ddbc33822cc2fb26fa962828b9bdb4e67
s_m:
  e9782b0e27729276810f3f1a5dfeaa5852e817e1a5cf1cadf20afbc7fc64b282
  a8371b36cb975c9b3bce16c92a40308b3651fccfb6fdca0dd3c850c22109b23f

Device bootloader:
------------------

firmware:
  6669726d77617265
h_f:
  c3bf47ea1f4a4a605470313cacb3a44f4a461f68c6faeab07e737610cb5ac835
pk_f:
  04083cb5e7ece3a8ffa2b6d2d52e2c1721f7d8de6eaaca7fad08267e289e97ec
  a18f3bf8afe57e528b6ad07023df442621c4ad8294816d12852339848eb1196d
  16
sk_f:
  1bdd42b6567101a59ef03e342138f506c83f27ecf21418cd9eaee223af7f3193
s_d:
  fd914d22d2fcb199a4d988d091d3ab9b1d50863dd4f118218045ccd3fa6609fa
  f11c6d0290ade334d0f5c954241828bc3723c015a4f4adcb2aede261f347fbfa

Connect:
--------

h_r:
  4916be80a96b552fe4d10793e8cebcc8cb883216ecf051f2b230b16c1a475329
pk_h:
  0462bbb45097fe85ae781de1e1f2b580b49f63fc6a00f7c2d85d909c52369a56
  e4bcee09dc05bf3500a7974d95f92b7a920dcab8fb31507867f453d887d336a3
  06
r_d:
  353eb43ffb422fc96c857140d5c399d588feef46f62bd363b97c823975bb27e7
ms:
  dfffeed23e848c194ae46dda671d0d86a7eea1eac904e7ed3f8c4d7c67a23c42
s:
  073d33268aa9551954a06564784dd7e4f8d6cc29d9fa350c4e2266204ec4e15d
k:
  dec9bb8e35338fb353a597f6243bcc006cb9a72fbd87b8d38a42f5827d48fabc
H(c):
  e3f50f7e6fe4a13eb9d6f631e7e1fbd1ee01aacfc27a23f5130af6a0dc310a6c
m:
  25e4744839cd2fe1e8e136e5175c69ddc016cfddc989c5e285be1aec12d7fe85

Reconnect:
----------

r:
  a65b26a3b441ae724a4730e62672e222a32b4a7edb90aa8389ab282668c16b76
m:
  5f253842eaaa026e8ccc82f1dbc6a5ea885c3abc08b2b1e7f32e9a8b08e1e364

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

securedeviceconnectionprotocol's Issues

[Question] Host validate the certification

The wiki mention:

Verifies the claim :

• pk_m <- Validate(cert_m)
• Verify(pk_m, H(pk_d), s_m)
• Verify(pk_d, H(C001||h_f||pk_f), s_d)
• Validate(h_f)

I don't understand how cert_m could become public key of model (pk_m).

I saw that the source code mention:

   // There is no support for real certificate validation yet.
   // For now, just pass in the model public key in place of the
   // ASN.1 DER encoded X509 cert.
   uint8_t claim_hash[SDCP_DIGEST_SIZE_V1] = { 0 };
   ASSERT_EQUAL(0, sdcpcli_hash_claim(
       g_model_pub_key, sizeof(g_model_pub_key), // Pub key in place of cert for now.
       device_key.pk, sizeof(device_key.pk),
       firmware_key.pk, sizeof(firmware_key.pk),
       &firmware_signature,
       &model_signature,
       claim_hash, sizeof(claim_hash)));
   print_bytes("H(c)", claim_hash, sizeof(claim_hash));

It is hard to understand how the real product should response both pk_m and cert_m or just response cert_m from the device to host.

Could anyone explain that?

[Question] EngineAdapterIdntifyFeatureSetAuthenticated during start enrollment

Hi,

Starting the Windows Hello Enrollment first time after secure connect, EngineAdapterIdntifyFeatureSetAuthenticated is called as there is no template enrolled i return WINBIO_E_UNKNOWN_ID which results in event "Windows Biometric service could not complete an identification process" with no Error and windows hello show "some error occured". How to make this function pass? i tried returning S_OK, WINBIO_E_NO_MATCH, WINBIO_E_ENROLLMENT_IN_PROGRESS all of them returns some error event in event viewer.

Thanks

The size of ECDH shared secret z may not must be 32 bytes long, netiher the EC private key size

Hi, as in the line 159 and line 315 of sample code client.c , there is two assert to make sure that the mpi big num lenght is equal to 32 bytes long.

I've checked the SEC 1 V2, it seems there is no any requirement on the private key length and the ecdh shared secret length.

In line 159, as follows:

In line 315, as follows:

secure connect failure

can you let us know the possible error values and reasons for secure connect response failure.
We are seeing 0x80070057(invalid argument) error from event viewer bio-metric log with EventId as 1609.
We have used mbedtls+github(secureDeviceConnectionProtocol) sources to generate secure connect response to sensor adapter library.
We are using Test signing machine with bio-metric service enable and observed that windows event viewer detected secure connect response and returned above error.

sdcp.sln

Hi,

It is mentioned to use sdcp.sln to build the test executable for windows environment, couldn't locate sdcp.sl file. Is this environment can still run on windows?
"And then open sdcp.sln with Visual Studio"

Thanks,
Prafulla Kota

Documentation is needed in the source code

Currently, none of the functions are documented, which is not very helpful for sample code...

Missing of "0x00" in KDF, compared to NIST SP800-108(Revised, OCT 2009)

I want to confirm whether the SDCP is designed to be different from SP-800, as to discard "0x00" in KDF ?

KDF described by wiki.

However, in NIST SP800-108, it is as follows:

Questions about SDCP

Hello,
After reading the SDCP wiki documentation, I have some questions about SDCP.

1. Match on host is not supported for SDCP?
2. How can I program to generate vsmEngineAdapterBinary, vsmSensorAdapterBinary, and vsmStorageAdapterBinary, Is there any document about how to guide us program in the trusted execution environment?
3. Any requirements for platform to do SDCP demo? Because I program a version 6 SensorAdapter Interface demo which implements nothing in new api, for example,

//
// Additional methods available in V6.0 and later
//
static HRESULT 
WINAPI
SensorAdapterConnectSecure(
        _Inout_ PWINBIO_PIPELINE Pipeline,
	_In_ const WINBIO_SECURE_CONNECTION_PARAMS* ConnectionParams,
	_Outptr_ WINBIO_SECURE_CONNECTION_DATA** ConnectionData
)
{
	TRACE(_T("SensorAdapter-> SensorAdapterConnectSecure\n"));
	return S_OK;
}

depending on the log infomation it seems that WBS does not call the new API SensorAdapterConnectSecure.
Event viewer report the information as the following, I suspect this may impact the SDCP and some requirements does not meet the SDCP.

Could anyone explain those? Thank you.

Inquiring about SecureBIO's Test Vector Certificate

While developing the SecureBIO Driver by referring to SecureDeviceConnectionProtocol on GitHub,
I'm sending you an email with any questions about the Test Vector you have posted on GitHub.

Here is our status of developing Fingerprint Driver with SecureBiometrics.

1. Using Lenovo T14s (Intel) NotePC and Enable Enhanced sign-in security (set SecureBiometrics on Registry and enabled SecureBIO SDEV )
   (I checked operation of Synaptics UWP WBDI on Lenovo NotePC T14s with SecureBiometrics - Secured-Core ready PC)

2. Windows 10 Build 20190.1000 (Preview Build), also checked it in 20161, 20170, 20180, 20185 Builds

3. Enable Test Signing Mode (TestSigning On / NoIntegrityChecks On / Debug On)

4. Using TestVector (Model Certificate / Model Private Key) on our fingerprint sensor

5. Implement all necessory SDCP Functions on our device

• Set SecureBIO attributes on INF file
• SensorAdapter

  SecureAdapterConnectSecure

• EngineAdapter

  EngineAdapterCreateKeyAuthenticated
  EngineAdapterCommitEnrollment
  EngineAdapterIdentifyFeatureSetAuthenticated
  and necessory functions (CheckForDuplicate)

When our sensor and driver are connected to the T14s, the creation of the Biometric Unit is normal, but the following error is displayed in the Event Viewer at the actual ConnectSecure stage and does not work.

"The Windows Biometric Service secure component failed to establish a secure connection with sensor. Error Code : 0xc0000428"

https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-erref/596a1078-e883-4972-9bbc-49e60bebca55
0xc0000428 STATUS_INVALID_IMAGE_HASH : The hash for image %hs cannot be found in the system catalogs. The image is likely corrupt or the victim of tampering.

Q1. Can I use the Test Vector (Certificate / Secret Key) on GitHub for development?
When checked in Event Viewer, the certificate is displayed as invalid.
Also, if TestVector has expired, I would like to get a new TestVector Certificate and Private Key.

Q2. Is there a way to check the Event Log related to BioISO (Bio Trustlet)?

Q3. If possible, I would like to know the contact point for SDCP development.

[Question] Reconnect processing at sample code

In sample code, reconnect just generate the host random for device to generate a MAC,

    // Now simulate a reconnect. The host will send new random bytes for
    // the client to MAC.
    puts("\nReconnect:\n----------\n");
    ASSERT_EQUAL(0, sdcpcli_gen_rand(host_random, sizeof(host_random)));
    print_bytes("r", host_random, sizeof(host_random));

    ASSERT_EQUAL(0, sdcpcli_mac_reconnect(
        &app_keys,
        host_random, sizeof(host_random),
        mac, sizeof(mac)));
    print_bytes("m", mac, sizeof(mac));

But it should derives application keys before generate a MAC that wiki described, right?

3. Device:
   i. Derives application keys:
   - (s, k) <- KDF(ms, "application keys")
   ii. Generates a MAC over the r_h:
   - m <- MAC(s, "reconnect"||r_h)
   iii. Sends the ReconnectResponse message, containing m.

I wonder dose one secure connect have a timeliness?

I am testing secure connect on system (20H2, 20128/20140) with fingerprint device. I found one confusing case.

One complete fingerprint enroll needs user to touch 12 times. During enrollment, I leave for other work for about 5 min (maybe I just touch 5 times, for example) . When I came back to continue to finish the left 7 times, the windows hello unit showed: something went wrong.

I was confused and then test more. I ensure that the fingerprint device remains in its working state. I found if the time I leave was limited within about 4 mins, I can finish enrollment successfully. Leaving more than 5 mins would lead to an unsuccessful enrollment. (Always show "something went wrong".

I doubt whether the secure connection has a timeliness? Is there a document explaining this case?

Creating Secure Bio Certificates from Test Vectors

Hi,

I am using "Appendix A" Model Certificate(846 Bytes)/IntermediateCA1(1025 Bytes)/IntermediateCA2(1114 Bytes) in our fingerprint device and writing them to SecureConnect response in the sensor adapter driver, But the event log reports 0x80070057. Do I need to convert these 3 Test vectors to certificates CA and install on Windows 10? I don't see any "Secure Bio Sensor" certificate in "Trusted root certificates Authority" or "Intermediate certification" on my windows 10 machine.

1. Do I need to create 3 certificates each from the model/Ca1/Ca2 test vector?
2. Are these prebuilt or locattion to download?
3. Or the Process/Tool to how to create certificates from Test Vectors.
4. How "Microsoft ECC Root Certificate Authority 2017 " is different then "Microsoft ECC Device Root Certificate Authority 2017"?

Thanks

[Question] Process of SensorAdapterConnectSecure with IOCTL_BIOMETRIC_CONNECT_SECURE

[Question] removed

removed

Missing sdcp.sln file when finish all the compile steps on Windows

When i finished all the compile steps following the instructions on the README.md, and all the steps turned out successful, but i can't find the sdcp.sln file in the "SecureDeviceConnectionProtocol" folder or any of its sub folders.
Pls check my compile steps shown in the attached picture.

Does is that right ?

ios security

connecting security protocols

[Question] Default sensor/storage adapters for secure device

Hello,

INF Changes section indicates vendor sensor and sensor adapters must be provided when enabling SDCP.

Can we expect inbox adapters supporting SDCP? If not, is there some code available (or library) to limit errors/bugs (and spare me some time) in re-codding those adapters with their default behavior (or an updated version)?

Assuming the answer is no, can you confirm is it would be ok to remove WBDI driver and do all the sensor control logic from the sensor adapter?

Thanks you!

Regards,
Paul

Add detail about the counter "i" in IV generation

https://github.com/Microsoft/SecureDeviceConnectionProtocol/blob/1f891d44ed7517e8a246b0b86789dea1bbf29184/src/client/client.c#L639

Change "i" to 64 bits in the client code, and specify lifetime in the wiki.

[question] Securing templates and Enroll()/Identify() implementation with match-on-host sensor

Hello,

I have some questions regarding Secure Biometric with basic/advanced sensor. I hope it is an acceptable place to ask them. I apologize if not.

Looking at https://github.com/Microsoft/SecureDeviceConnectionProtocol/wiki/Secure-Device-Connection-Protocol#sample-collection-and-template-storage-layer-one it is said:

For basic, match-on-host senor in VSM, the biometric trustlet secures the templates, which are encrypted to VSM at rest. The remaining gap at this layer is raw biometric samples, which must pass through the untrusted OS on their way to the matcher.

In this scenario, the EngineAdapter will get the encrypted sample. It can decrypt it with WbioFrameworkVsmDecryptSample(), extract features and generate or load template using the default WinBio storage adapter.

• Can I considered the EngineAdapter to be secured since dll is signed (even if OS is compromised), or should I rely on a TEE (Intel SGX) for processing the sample data?

In case of a advanced, match-off-host sensors, templates should be stored on the device.

• Is there a requirements on the number of templates the device should be able to store?
• If device don't have sufficient memory, could we consider doing the matching on the device while retrieving templates stored in the host? Documentation does not suggest this scenario but somewhat maybe could be achievable...

Thanks to anyone that can provides some input!

Regards,
Paul

[Questio] HLK and device certification process for SecureBio

Hello,

Can you confirm if HLK for Windows 17763.rs5_release and more specifically, the FingerprintReaderTest properly supports advanced device with SecureBio?

Also, is the statement in wiki (https://github.com/Microsoft/SecureDeviceConnectionProtocol/wiki/Secure-Device-Connection-Protocol#footnotes) saying the certification process for the device bootloader/firmware is not yet define is still true at this date? If not, any inputs how to get this kind of information?

Thanks a lot.

[question] Clarification about `EngineAdapterIdentifyFeatureSetAuthenticated()` return values

Hello,

When doing an enrollment from Windows Hello, it starts by doing an identify by calling EngineAdapterIdentifyFeatureSetAuthenticated(), even when no finger are yet enroll on the device and the system.

In this case, and according to my understanding of the documentation of EngineAdapterIdentifyFeatureSetAuthenticated(), I return:

• Identity data set to zero
• SubFactor set to WINBIO_SUBTYPE_NO_INFORMATION
• AuthenticationSize set to zero.
• Return S_OK as HRESULT

This will cause Windows Hello to fail with “Something went wrong” message. The system event viewer indicates identification has failed with error E_INVALIDARG.

If I return WINBIO_E_NO_MATCH, the system event viewer indicates identification has failed with error WINBIO_E_NO_MATCH.

What should I return in case of failed authentication (because of no template on the device or wrong finger detected) ?

This blocks enrollment in Windows Hello but I would think it is expected to have a failed authentication in this case...

When doing enrollment from a test application using WBF Client Application APIs (skipping identification before starting enrollment), I can successfully complete an enrollment according to event viewer messages.

However, when attempting an identification, I will get the error WINBIO_E_DATABASE_NO_RESULTS event if finger is properly match and the secure id reported to the host. All HMAC checks are good on FW side.

Error is reported by the service after EngineAdapterIdentifyFeatureSetAuthenticated() has returned with all outputs set as follow:

• Identity->Value.SecureId set to the value given by EngineAdapterCommitEnrollment()
• SubFactor set to the value given in EngineAdapterCommitEnrollment()
• AuthenticationSize set to WINBIO_SCP_DIGEST_SIZE_V1
• Authentication set to pointer to internal engine adapter buffer containing the HMAC from the device
• Return S_OK as HRESULT

I have also check FW hash and device public key was consistent between secure connection.

Am I missing something?

I am testing using build 17754.

Thanks for any input!

Regards,
Paul

Add a test executable

Test code needs to be added to show usage of the client library.

[Question] Expected output for IOCTL_BIOMETRIC_CONNECT_SECURE

Hello,

The SDCP wiki documentation indicates IOCTL_BIOMETRIC_CONNECT_SECURE will be added to WBF and the expected output is WINBIO_SECURE_CONNECTION_RESPONSE which nests WINBIO_SECURE_CONNECTION_DATA.

However, after updating WDK and looking at the updated winbio headers for RS4, there is no structure WINBIO_SECURE_CONNECTION_RESPONSE defined.

So, what does the framework really expects? WINBIO_SECURE_CONNECTION_RESPONSE or WINBIO_SECURE_CONNECTION_DATA?

If the later, as there is no WinBioHresult field, how to report a failure in case the request to the device was unsuccessful?

Thank you!

Regards,
Paul

This repo is missing important files

There are important files that Microsoft projects should all have that are not present in this repository. A pull request has been opened to add the missing file(s). When the pr is merged this issue will be closed automatically.

Microsoft teams can learn more about this effort and share feedback within the open source guidance available internally.

Merge this pull request