From 01e88ea7c5a952c1050298b3c06a79c19ff2f4b6 Mon Sep 17 00:00:00 2001 From: jbenet Date: Sun, 26 Feb 2017 08:18:14 -0800 Subject: [PATCH] improving copy --- content/index.md | 36 +++++++++++++++++++++++++----------- content/multihash.md | 31 ++++++++++++++++++++++++++++++- layouts/_default/single.html | 1 + versions/history | 1 + 4 files changed, 57 insertions(+), 12 deletions(-) diff --git a/content/index.md b/content/index.md index 36d813f..6adacfe 100644 --- a/content/index.md +++ b/content/index.md @@ -7,7 +7,22 @@ stars = "multiformats/multiformats" Every choice in computing has a tradeoff. This includes formats, algorithms, encodings, and so on. And even with a great deal of planning, decisions may lead to breaking changes down the road, or to solutions which are no longer optimal. Allowing systems to evolve and grow is important. -Multiformats is a collection of protocols which aim to future-proof systems, today. They do this mainly by enhancing format values with self-description. This allows interoperability, protocol agility, and helps us avoid lock in. +- [What are Multiformats?](#what-are-multiformats) +- [Multiformat protocols](#multiformat-protocols) +- [Projects using Multiformats](#projects-using-multiformats) +- [Contribute & Community](#contribute-community) + +## What are Multiformats? + +The Multiformats Project is a collection of protocols which aim to future-proof systems, today. They do this mainly by enhancing format values with self-description. This allows interoperability, protocol agility, and helps us avoid lock in. + +The self-describing aspects of the protocols have a few stipulations: + +- They MUST be _in-band_ (with the value); not _out-of-band_ (in context). +- They MUST avoid _lock-in_ and promote _extensibility_. +- They MUST be compact and have a _binary-packed_ representation. +- They MUST have a _human-readable_ representation. + ## Multiformat protocols @@ -24,23 +39,20 @@ Currently, we have the following multiformat protocols: - [multikey](https://github.com/ipfs/specs/issues/58) (WIP) - self-describing keys and proofs --> -Several of the multiformats have stable specs and stable implementations. We're are working on the others. We prioritize their usage as soon as possible, as what they offer -- protocol interoperability and future-proofing -- has real-world consequences today. +Each of the projects has its list of implementations in various languages. -Towards that end, we are encouraging improvements to WIP protocols, and implementations of all. Please contribute to the projects on Github. +### Project Status -The self-describing aspects of the protocols have a few stipulations: +Several of the multiformats have stable specs and stable implementations. We're are working on the others. We prioritize their usage as soon as possible, as what they offer -- protocol interoperability and future-proofing -- has real-world consequences today. -- They MUST be _in-band_ (with the value); not _out-of-band_ (in context). -- They MUST avoid _lock-in_ and promote _extensibility_. -- They MUST be compact and have a _binary-packed_ representation. -- They MUST have a _human-readable_ representation. +Towards that end, we are encouraging improvements to WIP protocols, and implementations of all. Please contribute to the projects on Github. ### A note on the word Multiformats Multiformats is the name for the organization, but it can also be used to refer to protocols; for instance, in the sentence "Use one of the multiformats". Formats is interchangeable with protocols, here. We try to capitalize Multiformats when it refers to the organization, on GitHub. -### Projects using Multiformats +## Projects using Multiformats The Multiformats project began through [the IPFS Project](https://ipfs.io). It is used extensively in projects like @@ -59,13 +71,15 @@ The Multiformats project began through [the IPFS Project](https://ipfs.io). It i -### Community +## Contribute & Community -The Multiformats Project is an Open Source software project. It is built by a large community of contributors. +The Multiformats Project is an Open Source software project. It is built by a large community of contributors. Please join us on Github or IRC to request features, file bugs, contribute code, improve documentation, and ask questions. We have a very open and welcoming community. - [Github Project](https://github.com/multiformats/multiformats) - [Website Repository](https://github.com/multiformats/website) - IRC Channel: `#ipfs` on irc.freenode.org +- [Code of Conduct](https://github.com/ipfs/community/blob/master/code-of-conduct.md) +- [Contributing Guide](https://github.com/multiformats/multiformats/blob/master/contributing.md) Multiformats was started and is sponsored by: diff --git a/content/multihash.md b/content/multihash.md index 3ecb1f2..230048f 100644 --- a/content/multihash.md +++ b/content/multihash.md @@ -8,6 +8,19 @@ stars = "multiformats/multihash" Multihash is a protocol for differentiating outputs from various well-established hash functions, addressing size + encoding considerations. It is useful to write applications that future-proof their use of hashes, and allow multiple hash functions to coexist. + + +- [Safer, easier cryptographic hash function upgrades](#safer-easier-cryptographic-hash-function-upgrades) +- [The Multihash Format](#the-multihash-format) +- [Implementations](#implementations) +- [Examples](#examples) +- [F.A.Q.](#f-a-q) +- [About](#about) + - [Specification](#specification) + - [Credits](#credits) + - [Open Source](#open-source) + - [Part of the Multiformats Project](#part-of-the-multiformats-project) + ### Safer, easier cryptographic hash function upgrades Multihash is particularly important in systems which depend on [**cryptographically secure hash functions**](https://en.wikipedia.org/wiki/Cryptographic_hash_function). Attacks [may break](https://en.wikipedia.org/wiki/Hash_function_security_summary) the cryptographic properties of secure hash functions. These [_cryptographic breaks_](https://en.wikipedia.org/wiki/Cryptanalysis) are particularly painful in large tool ecosystems, where tools may have made assumptions about hash values, such as function and digest size. Upgrading becomes a nightmare, as all tools which make those assumptions would have to be upgraded to use the new hash function and new hash digest length. Tools may face serious interoperability problems or error-prone special casing. @@ -174,6 +187,22 @@ The multihash examples are chosen to show different hash functions and different ## F.A.Q. +> #### Q: Why have digest length as a separate number? + +Because combining hash function code and hash digest length ends up with a function code really meaning "function-and-digest-size-code". Makes using custom digest sizes annoying, and much less flexible. We would need hundreds of codes for all the combinations people would want to use. + +> #### Q: Why varints (variable integers)? + +So that we have no limitation on functions or lengths. + +> #### Q: What kind of varints? + +A Most Significant Bit unsigned varint, as defined by the [multiformats/unsigned-varint](https://github.com/multiformats/unsigned-varint) doc. + +> #### Q: Don't we have to agree on a table of functions? + +Yes, but we already have to agree on functions, so this is not hard. The table even leaves some room for custom function codes. + > #### Q: Why not use `"sha256:"`? For three reasons: @@ -204,7 +233,7 @@ Three options to add custom hash functions: > #### Q. I want to upgrade a large system to use Multihash. Could you help me figure out how? -Sure, ask for help in IRC, github, or other fora. See the [Multiformats Community](../#community) listing. +Sure, ask for help in IRC, github, or other fora. See the [Multiformats Community](../#contribute-community) listing. > #### Q. I wish Multihash would _______. I really hate _______. diff --git a/layouts/_default/single.html b/layouts/_default/single.html index 2606a0a..9e1d73e 100644 --- a/layouts/_default/single.html +++ b/layouts/_default/single.html @@ -39,6 +39,7 @@
+ {{ .Content }}
diff --git a/versions/history b/versions/history index 58a95d0..4e2052f 100644 --- a/versions/history +++ b/versions/history @@ -1,3 +1,4 @@ QmXzJcnFHXErv8iAd8W5vMYWp8bLBpvU1CFNpmGu2nKB3W QmdQmEzVEJ16eP5DpHwGf6WDCtKXC8DpwxnP4eosPFgDC9 Qmf38duto7uZtQdP4svfSJnuU7oXs4hfwaC1KQQbjN99Cp +QmU7EbHymE3LCbJPen3EzkQuYMPF89TLpbvhLRZqx5MqCx