From 762df1301272f874f069fdd2312421eabd1f7d83 Mon Sep 17 00:00:00 2001 From: Frederic Jacobs Date: Wed, 6 Apr 2016 00:59:50 +0200 Subject: [PATCH] Readme updates. --- README.md | 129 ++++++++++++++++++++---------------------------------- 1 file changed, 47 insertions(+), 82 deletions(-) diff --git a/README.md b/README.md index c433160..2a33f3f 100644 --- a/README.md +++ b/README.md @@ -1,65 +1,35 @@ # Rusty Secrets -This program is an implementation of -[Shamir's secret sharing](https://en.wikipedia.org/wiki/Shamir%27s_Secret_Sharing). -A secret can be split into N shares in a way so that -a selectable number of shares K (with K ≤ N) is required -to reconstruct the secret again. +Rusty Secrets is an implementation of a threshold [Shamir's secret sharing scheme](https://en.wikipedia.org/wiki/Shamir%27s_Secret_Sharing). -**Warning**: I don't yet recommend the serious use of this tool. The -encoding of the shares might change in a newer version in which case -you would have trouble decoding secrets that have been shared using -an older version of the program. For now, this is experimental. +## Design goals -# Example +The main use for this library is to split a secret of an arbitrary length in n different shares and t-out-of-n shares are required to recover it. The dealer is assumed to be honest (and competent). We further assume that our adversary will only be able to compromise at most k-1 shares. -Passing a secret to secretshare for encoding: +## Choosing a scheme -``` -$ echo My secret | ./secretshare -e2,5 -2-1-1YAYwmOHqZ69jA -2-2-YJZQDGm22Y77Gw -2-3-+G9ovW9SAnUynQ -2-4-F7rAjX3UOa53KA -2-5-j0P4PHsw4lW+rg -``` +The Shamir's Secret Sharing scheme has been chosen for this implementation for the following reasons. -The parameters following the `-e` option tell `secretshare` to create 5 shares of which 2 will be necessary for decoding. +### Information-theoretic security -Decoding a subset of shares (one share per line) can be done like this: +Shamir's secret sharing is known to have the perfect secrecy property. +In the context of (K,N)-threshold schemes this means that if you have +less than K shares available, you have absolutely no information about +what the secret is except for its length (typical secrets would be an AES-256 key, all have the same length). -``` -$ echo -e "2-2-YJZQDGm22Y77Gw \n 2-4-F7rAjX3UOa53KA" | ./secretshare -d -My secret -``` +Information-theoretic security gives us strong guarantees: -# Building +1) That there are provably no faster attacks than brute force exhaustion of key space. +2) An encryption protocol that has information-theoretic security does not depend for its effectiveness on unproven assumptions about computational hardness, and such an algorithm is not vulnerable to future developments in computer power such as quantum computing. Source: [Wikipedia]( https://en.wikipedia.org/wiki/Information-theoretic_security “Information Theoretic Security”) -This project is Cargo-enabled. So, you should be able to build it with -``` -$ cargo build --release -``` +### Peer-review -once you have made sure that `rustc` (the compiler) and `cargo` -(the build and dependency management tool) are installed. -Visit the [Rust homepage](http://www.rust-lang.org/) if you are -don't know where to get these tools. +The Shamir secret sharing scheme has been around since 1979 and has been [well studied](https://scholar.google.ch/scholar?cites=12714240754634232446&as_sdt=2005&sciodt=0,5&hl=en). -# I/O +## Implementation -The secret data does not have to be text. `secretshare` treats it as -binary data. But, of course, you can feed it text as well. In the above -example the echo command terminated the string with a line feed which -is actually part of the secret and output as well after decoding. -Note that, while `secretshare` supports secrets of up to 64 KiB -it makes little sense to use such large secrets directly. In situations -where you want to share larger secrets, you would usually pick a random -password for encryption and use that password as secret for `secretshare`. - -The generated shares are lines of ASCII text. - -# Structure of the shares +### Structure of the shares ``` 2-1-LiTyeXwEP71IUA @@ -67,48 +37,43 @@ The generated shares are lines of ASCII text. K N D ``` -A share is built out of three or four parts separated with a minus: K-N-D-C. -The last part is optional. K is one of the encoding parameters that tell you -how many distinct -shares of a specific secret are necessary to be able to recover the -secret. The number N identifies the share (ranging from 1 to the number -of shares that have been created). The D part is a Base64 encoding of -a specific share's raw data. +A share is built out of three parts separated with a dash: K-N-D. -# A word on the secrecy +- K specifies the number of shares necessary to recover the secret. +- N is the identifier of the share and varies between 1 and n where n is the total number of generated shares. +- The D part is a Base64 encoding of a specific share's raw data. -Shamir's secret sharing is known to have the perfect secrecy property. -In the context of (K,N)-threshold schemes this means that if you have -less than K shares available, you have absolutely no information about -what the secret is except for its length. The checksums that are included -in the shares -also don't reveal anything about the secret. -They are just a simple integrity protection of the shares themselves. -In other words, given a share without checksum, we can derive a share -with a checksum. This obviously does not add any new information. +### Command-line encoding -# Galois field +Passing a secret to rustysecrets for encoding: -Shamir's secret sharing algorithm requires the use of polynomials over -a finite field. One easy way of constructing a finite field is to pick -a prime number p, use the integers 0, 1, 2, ..., p-1 as field elements -and simply use modular arithmetic (mod p) for the field operations. +``` +$ echo My secret | ./rusty_secrets_bin -e2,5 +2-1-1YAYwmOHqZ69jA +2-2-YJZQDGm22Y77Gw +2-3-+G9ovW9SAnUynQ +2-4-F7rAjX3UOa53KA +2-5-j0P4PHsw4lW+rg +``` -So, you *could* pick a prime like 257 to apply Shamir's algorithm -byte-wise. The downside of this is that the shares would consist of -sequences of values each between 0 and 256 *inclusive*. So, you would -need more than 8 bits to encode each of them. +The parameters following the `-e` option tell rustysecrets to create 5 shares of which 2 will be necessary for decoding. -But there is another way. We are not restricted to so-called -prime fields. There are also non-prime fields where the number of -elements is a *power* of a prime, for example 2^8=256. It's just -a bit harder to explain how they are constructed. The finite -field I used is the same as the one you can find in the RAID 6 -implementation of the Linux kernel or the Anubis block cipher: -Gf(2^8) reduction polynomial is x^8 + x^4 + x^3 + x^2 + 1 or -alternatively 11D in hex. +Decoding a subset of shares (one share per line) can be done like this: + +``` +$ echo -e "2-2-YJZQDGm22Y77Gw \n 2-4-F7rAjX3UOa53KA" | ./rusty_secrets_bin -d +My secret +``` + +### Library + +Documentation to come for the library interface. + +## Vocabulary + +- Dealer: Entity that will perform key splitting from a master secret +- Shares: Part of the split secret distributed ## Credits Rusty Secrets was forked off [sellibitze's secretshare.](https://github.com/sellibitze/secretshare) -