README_Register_and_Authenticate.md

Register and Authenticate

To be secure, it is recommended to use a separate implementation for server and client.

Register

1. create Challenge

Correct implementation is done on the server side.

let challenge = verifier::create_challenge();

2. create MakeCredentialArgs

• need rpid(string) and challenge
• set pin(string)

let make_credential_args = MakeCredentialArgsBuilder::new(&rpid, &challenge)
  .pin(pin)
  .build();

3. create FidoKeyHid

let device = FidoKeyHidFactory::create(&cfg)?;

4. get Attestation Object

let attestation = device.make_credential_with_args(&make_credential_args)?;

5. verify Attestation Object

Correct implementation is done on the server side.

• need rpid(string) and challenge and Attestation

let verify_result = verifier::verify_attestation(rpid, &challenge, &attestation);
if verify_result.is_success {
  println!("-- Verify Attestation Success");
} else {
  println!("-- ! Verify Attestation Failed");
}

6. store Credential Id and Publickey

Correct implementation is done on the server side.

let userdata.credential_id = verify_result.credential_id;
let userdata.credential_public_key = verify_result.credential_public_key;

store(&userdata); <- ex.store to database

Authenticate

1. restore Credential Id and Publickey

Correct implementation is done on the server side.

let userdata = restore(userid); <- ex.restore from database

userdata.credential_id;
userdata.credential_public_key;

2. create Challenge

Correct implementation is done on the server side.

let challenge = verifier::create_challenge();

3. create GetAssertionArgs

• need rpid(string) and challenge
• set pin(string) and Credential Id

let get_assertion_args = GetAssertionArgsBuilder::new(rpid, &challenge)
  .pin(pin)
  .credential_id(&userdata.credential_id)
  .build();

4. get Assertion Object

let assertions = device.get_assertion_with_args(&get_assertion_args)?;

5. verify Assertion Object

Correct implementation is done on the server side.

• need rpid(string) and PublicKey and challenge and Assertion

let is_success = verifier::verify_assertion(
  rpid,
  &userdata.credential_public_key,
  &challenge,
  &assertions[0],
);
if is_success {
  println!("-- Verify Assertion Success");
} else {
  println!("-- ! Verify Assertion Failed");
}

Examples

non-discoverable credentials/non-resident-key

• non-discoverable credentials/non-resident-key

  • Most common use to specify PIN.

• with UV

  • to use Yubikey bio for fingerprint authentication.

• with Key Type

  • Specify the algorithm(Ecdsa256/Ed25519).

• with HMAC Secret Extension

• with HMAC Secret Extension (use optional salt)

  • I do not know the correct use of this option.

• with Large Blob Key Extension

  • Used with Large Blob Command.
  • Spec: 6.10.5. Writing per-credential large-blob data for a new credential

• with Min Pin Length Extension

  • Get Min Pin Length Policy.
  • RPID must be set in Authenticator Config. → Authenticator Config
  • Spec: 12.4. Minimum PIN Length Extension (minPinLength)

• without PIN

  • For security reasons, this feature is deprecated

  • Use without_pin_and_uv to run with an Authenticator that does not have a PIN set.

  • Using without_pin_and_uv on an Authenticator with a PIN set may result in an error (behavior depends on Authenticator type).

  • Get whether PIN is set in Authenticator with enable_info_option()

    • Example

• with PIN/UV Auth Protocol Two

  • use device.set_pin_uv_auth_protocol_two().

discoverable credentials/resident-key

• discoverable credentials/resident-key
  • User data can be stored in the authenticator.
  • user_name and user_display_name are set only when multiple Assertions are acquired.
• with Credential Blob Extension
  • This extension enables RPs to provide a small amount of extra credential configuration.
  • This extension only works if CTAP 2.1 is implemented.

Legacy Pattern Examples

Legacy patterns are deprecated. They will be removed in a future version.

• non-discoverable credentials/non-resident-key

• with Key Type

• discoverable credentials/resident-key