# Dono Rust crate

[![Build Status](https://travis-ci.org/dono-app/dono-crate.svg?branch=develop)](https://travis-ci.org/dono-app/dono-crate)
[![codecov](https://codecov.io/gh/dono-app/dono-crate/branch/develop/graph/badge.svg)](https://codecov.io/gh/dono-app/dono-crate)
[![crates.io version](http://meritbadge.herokuapp.com/dono)](https://crates.io/crates/dono)
[![license](https://img.shields.io/badge/license-GPLv3-blue.svg)](LICENSE)

🚚 Rust crate for Dono Key Derivation Function

## About Dono

Dono is a password derivation tool which derives passwords from a master Key by
using short descriptions of the destination service.

You can read more about the project in it's
[whitepaper repository](https://github.com/dono-app/whitepaper) or
[download the PDF](https://github.com/dono-app/whitepaper/blob/master/dono.pdf).

## Usage

To use this crate add the following to your `Cargo.toml` file:

```toml
[dependencies]
dono = "2.0.0"
```

Then in your rust code:

```rust
extern crate dono;
```

This will give you access to the `Dono` and `DonoError` structs.

### Dono

The `Dono` struct provides the basic password hashing implementation.

A new instance of `Dono` can be created with the `new()` function. This gives
you access to the `compute_password` function.

```rust
extern crate dono;

fn main() {
  let dono = dono::Dono::new();

  let key = "this_is_a_long_test_key".to_string();
  let label = "test".to_string();

  let password = dono.compute_password(&key, &label).unwrap();

  println!("password: {}", password);
}
```

### Label

The `Label` struct provides an easy-to-use way to index, create, update and
destroy labels from the store.

Labels have the following attributes:

* `title` - Holds the current title, represented as a String
* `previous_title` - Holds the last saved title, represented as a String
* `persisted` - Holds a bool value thet indicates if the Label is persisted in
the store

Abailable public methods are:

* `new(label: &String) -> Label` - creates a new Label with the given title
* `new_saved(label: &String) -> Label` - same as `new` but sets `persisted` to
_true_
* `changed() -> bool` - returns true if the current and previous title are the
same
* `save() -> Result<&Label, DonoError>` - save the label to the store
* `destroy() -> Result<&Label, DonoError>` - destroys the label from the store

Module methods:

* `labels::all()` - returns a _Vec_ with all prebuild Label structs from the
store

Example:

```rust
extern crate dono;

fn main() {
  /* Initial state of the store:
   * github
   * facebook
   * twitter
   */

  // Return a Vec<Label> containing the github, facebook and twitter Labels
  let mut labels = dono::labels::all();

  // Get the twitter Label
  let mut twitter_label = labels.last_mut().unwrap();

  // Change the title from twitter to gitter
  twitter_label.title = "gitter".to_string();

  // Check if the value has changed
  println!("Value has changed? {}", twitter_label.changed());

  // Persist the changes
  twitter_label.save().unwrap();

  /* Current state of the store:
   * github
   * facebook
   * gitter
   */

  // Delete the gitter label
  twitter_label.destroy();

  /* Current state of the store:
   * github
   * facebook
   */

  // Create a new label
  let mut label  = dono::labels::Label::new(&"test".to_string());

  // Save the new label
  label.save();

  /* Current state of the store:
   * github
   * facebook
   * test
   */
}
```

## Errors

This library has a custom error called `DonoError` that has the
following string fields in it:

* `field` - Indicates which parameter caused the error
* `code` - A code associated with that error
* `description` - Detailed description of what went wrong with possible solution
* `message` - Short description of what went wrong

__Error codes:__

* `CP001` - The key is too short
* `CP002` - Desired password length is too long
* `SV001` - Could not open store file
* `SV002` - Could not write to store file

## OSS used

* [rust-crypto](https://github.com/DaGenix/rust-crypto) - PBKDF2 and SHA256
algorithm impementations
* [regex](https://github.com/rust-lang-nursery/regex) - General regex matching and string replacement
* [rustc-serialize](https://github.com/rust-lang-nursery/rustc-serialize) - Object serialization

## Contributing

__Contributions are always welcome!__ Please note that new features and bugfixes
get added on the `develop` branch first. So all pull requests should be made
from and to the `develop` branch. Also, please check the issues and pull request
pages for simmilar issues and solutions before submitting your own.

__When you submit a bug report__ always add a minimal working example and
specify which version of the crate you are using.

__Testing is important!__ Always test the code you submit in a pull request.

## License

This project is licensed under the GPLv3. The full license text is available
[here](LICENSE).