challenge_response 0.5.1

# challenge-response

[![Latest Version]][crates.io] [![Documentation]][docs.rs] [![Build Status]][CI on Master] [![Dependency Status]][deps.rs] [![MIT licensed]][MIT] [![Apache-2.0 licensed]][APACHE]

[Documentation]: https://docs.rs/challenge_response/badge.svg
[docs.rs]: https://docs.rs/challenge-response/
[Latest Version]: https://img.shields.io/crates/v/challenge-response.svg
[crates.io]: https://crates.io/crates/challenge-response
[MIT licensed]: https://img.shields.io/badge/License-MIT-blue.svg
[MIT]: ./LICENSE-MIT
[Apache-2.0 licensed]: https://img.shields.io/badge/License-Apache%202.0-blue.svg
[APACHE]: ./LICENSE-APACHE
[Dependency Status]: https://deps.rs/repo/github/louib/challenge-response/status.svg
[deps.rs]: https://deps.rs/repo/github/louib/challenge-response
[Build Status]: https://github.com/louib/challenge-response/actions/workflows/merge.yml/badge.svg?branch=master
[CI on Master]: https://github.com/louib/challenge-response/actions/workflows/merge.yml

`challenge-response` is a Rust library for performing [challenge-response](https://wiki.archlinux.org/index.php/yubikey#Function_and_Application_of_Challenge-Response) operations (hashing and encryption) using security keys like the YubiKey and the OnlyKey.

## Current features

- [HMAC-SHA1 Challenge-Response](https://datatracker.ietf.org/doc/html/rfc2104)
- [Yubico OTP Challenge-Response encryption](https://docs.yubico.com/yesdk/users-manual/application-otp/yubico-otp.html)
- Challenge-Response configuration

## Supported devices

- YubiKey 2.2 and later
- OnlyKey (**untested**)

## Usage

Add this to your Cargo.toml

```toml
[dependencies]
challenge_response = "0"
```

### Configure Yubikey (HMAC-SHA1 mode)

Note, please read about the [initial configuration](https://wiki.archlinux.org/index.php/yubikey#Initial_configuration)
Alternatively you can configure the yubikey with the official [Yubikey Personalization GUI](https://developers.yubico.com/yubikey-personalization-gui/).

```rust
extern crate challenge_response;
extern crate rand;

use challenge_response::config::{Command, Config};
use challenge_response::configure::DeviceModeConfig;
use challenge_response::hmacmode::HmacKey;
use challenge_response::ChallengeResponse;
use rand::distributions::Alphanumeric;
use rand::{thread_rng, Rng};

fn main() {
    let mut challenge_response = match ChallengeResponse::new() {
        Ok(y) => y,
        Err(e) => {
            eprintln!("{}", e.to_string());
            return;
        }
    };

    if let Ok(device) = challenge_response.find_device() {
        println!(
            "Vendor ID: {:?} Product ID {:?}",
            device.vendor_id, device.product_id
        );

        let config = Config::new_from(device).set_command(Command::Configuration2);

        let mut rng = thread_rng();

        // Secret must have 20 bytes
        // Used rand here, but you can set your own secret: let secret: &[u8; 20] = b"my_awesome_secret_20";
        let secret: Vec<u8> = rng.sample_iter(&Alphanumeric).take(20).collect();
        let hmac_key: HmacKey = HmacKey::from_slice(&secret);

        let mut device_config = DeviceModeConfig::default();
        device_config.challenge_response_hmac(&hmac_key, false, false);

        if let Err(err) = challenge_response.write_config(config, &mut device_config) {
            println!("{:?}", err);
        } else {
            println!("Device configured");
        }
    } else {
        println!("Device not found");
    }
}
```

### Example Challenge-Response (HMAC-SHA1 mode)

Configure the yubikey with [Yubikey Personalization GUI](https://developers.yubico.com/yubikey-personalization-gui/)

```rust
extern crate challenge_response;
extern crate hex;

use challenge_response::config::{Config, Mode, Slot};
use challenge_response::ChallengeResponse;
use std::ops::Deref;

fn main() {
    let mut challenge_response = match ChallengeResponse::new() {
        Ok(y) => y,
        Err(e) => {
            eprintln!("{}", e.to_string());
            return;
        }
    };

    if let Ok(device) = challenge_response.find_device() {
        println!(
            "Vendor ID: {:?} Product ID {:?}",
            device.vendor_id, device.product_id
        );

        let config = Config::new_from(device)
            .set_variable_size(true)
            .set_mode(Mode::Sha1)
            .set_slot(Slot::Slot2);

        // Challenge can not be greater than 64 bytes
        let challenge = String::from("mychallenge");
        // In HMAC Mode, the result will always be the SAME for the SAME provided challenge
        let hmac_result = challenge_response
            .challenge_response_hmac(challenge.as_bytes(), config)
            .unwrap();

        // Just for debug, lets check the hex
        let v: &[u8] = hmac_result.deref();
        let hex_string = hex::encode(v);

        println!("{}", hex_string);
    } else {
        println!("Device not found");
    }
}
```

## Credits

This library was originally a fork of the [yubico_manager](https://crates.io/crates/yubico_manager) library.