bishop.rs

+----[drunken]----+ |..+.. oo+o. | | *.* o +.o. | |= = o * .E+ | |+. ..+ = +.. | |o ...+ S.o | | .o .....= . | |.. o .+ + | |. = + | | ..= | +----[bishop]-----+

Library and CLI app for visualizing data using The Drunken Bishop algorithm implemented in Rust

Drunken Bishop is the algorithm used in OpenSSH's ssh-keygen for visualising generated keys

Table of Contents:

• Crates
• Install
• Examples
  • Using as command-line app
    • Note on char list
  • Using as library
    • Cargo.toml
    • For AsRef<u8> (slices, vectors)
    • Drawing options and result reusing
    • For Read (file, stdin, etc)
• License
  • Contribution

Crates

Crate	Description	Version
bishop	Library
bishop-cli (source)	Command-line app

Install

Rust library lives on crates.io

CLI app:

Platform	Package
Arch Linux
Prebuilts for Linux	Github releases

Examples

Using as command-line app

some_data=$(printf foobar | sha256sum | cut -d' ' -f1)
# we are using cut here to crop the filename from sha256sum output

printf $some_data | bishop -sI hex
# `-s` tells bishop to take data from stdin
#
# `-I hex` tells bishop that input data will be in HEX format.
# As an alternative, you might use xxd to turn hex data into binary:

printf $some_data | xxd -r -p | bishop -s
# `-I bin` is implied by default

bishop -i <(printf $some_data) -I hex
# `-i` tells bishop to take data from specified file.
# We are using bash command substitution here, but
# any valid path is allowed, like `bishop -i ~/some.file`

bishop $some_data
# Without `-i` or `-s` bishop expects HEX encoded input in the first argument.
# Note that `-I` is not supported if data is provided as argument

printf foobar | bishop -sI hash
# `-I hash` tells bishop to hash all of its input
# using sha256 before making a randomart.
# Since maximum effective size of input data for random art with default size (17x9)
# is somwhere around 64-128 bytes, this option is extremely useful for large inputs  

All these bishop calls would print this art to console:

Fingerprint of:
c3ab8ff13720e8ad9047dd39466b3c8974e592c2fa383d4a3960714caef0c4f2

+-----------------+
|    .     .      |
| . + .   +       |
|o + + + = .      |
| * + + O =       |
|  E o.o S        |
| . +.=.o.=       |
|  o.B.=...       |
|   +.+.*  o      |
|    o.o.o. .     |
+-----------------+

Note that input will be echoed only if data is provided as argument or with -I hash. This behavior can be disabled using -q option.

You can read full usage for cli app (also available by --help option) here

Note on char list

You can provide custom char list wich -c option. This is a vector of chars used for fingerprint (represened as string).

Each char is treated as:

Index	Description	Default
0	Field background
1..n	Chars used for drawing	.o+=*BOX@%&#/^
n+1	Char for start position	S
n+2	Char for last position	E

Each non-background char indicates how many times bishop has been on this position.

Start and end chars overwrites the real value.

Char list must be at least 4 chars long, but secure char list is at least 18 chars long and only consists of clearly distinguishable symbols.

Using as library

Cargo.toml

bishop = "0.2.0"

Use latest version as stated on cargo badge above

For AsRef<u8> (slices, vectors)

extern crate bishop;
use bishop::*;

fn main() {
    let data1 = [0u8; 16];
    let data2 = vec![0u8; 16];

    let mut art = BishopArt::new();
    art.input(&data1);
    art.input(&data2);
    println!("{}", art.draw());

    // Using chaining:

    let drawn_art: String = BishopArt::new()
        .chain(&data1)
        .chain(&data2)
        .draw();
    println!("{}", drawn_art);
}

Drawing options and result reusing

use bishop::*;

fn random_art(data: &[u8]) {
    let opts1 = DrawingOptions { top_text: "pass 1".to_string(), ..Default::default() };
    let opts2 = DrawingOptions { bottom_text: "pass 2".to_string(), ..Default::default() };

    // compute field once
    let field = BishopArt::new().chain(data).result();

    // then draw it multiple times with different options
    println!("{}", field.draw_with_opts(&opts1));
    println!("{}", field.draw_with_opts(&opts2));
}

For Read (file, stdin, etc)

use bishop::*;
use std::io::{self, Read};

fn main() {
    // BishopArt implements Write trait
    let mut art = BishopArt::new();
    io::copy(&mut io::stdin(), &mut art);
    println!("{}", art.draw());
}

Full API documentation is available on docs.rs

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.