From c056cfcb06e60fed9480d3983e0ee219f0e2a610 Mon Sep 17 00:00:00 2001 From: Jean-Paul Calderone <exarkun@twistedmatrix.com> Date: Tue, 15 Aug 2023 13:43:40 -0400 Subject: [PATCH] add some introductory documentation --- README.md | 28 ++++++++++++++++++++++++++++ tahoe-capabilities.cabal | 4 +++- 2 files changed, 31 insertions(+), 1 deletion(-) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..9573180 --- /dev/null +++ b/README.md @@ -0,0 +1,28 @@ +# Tahoe-Capabilities + +## What is it? + +Tahoe-LAFS LIT, CHK, SDMF, and MDMF capabilities offer varying functionality for interacting with encrypted data. +This library provides abstractions for functionality common to all of these capability types. + +All responsibility for implementing these abstractions is left to the capability-specific libraries. + +### What is the current state? + +* The `ConfidentialShowable` type class provides a uniform way for losslessly converting a capability to a string. + +### What is planned? + +Sufficient abstraction so that general encoding, decoding, upload, and download functions could be implemented independent of the specific capability type in use. + +## Why does it exist? + +Each specific Tahoe-LAFS capability type supports certain operations and offers certain security properties. +At a high level, +an application will often want to select among the available capability types to satisfy its particular security and/or privacy requirements. +A lower level exists encompassing such details of a capability type as which hash function is used or the size or alignment of certain fields. +Applications should typically not be required to make choices at this lower level. +By using a set of operations that abstract over these details, +application code can be kept simpler and more general-purpose. +By allowing some centralization of the choice of which concrete capability type to use, +applications can also be made more secure over time at a lower maintenance cost. diff --git a/tahoe-capabilities.cabal b/tahoe-capabilities.cabal index 063c604..67a6c22 100644 --- a/tahoe-capabilities.cabal +++ b/tahoe-capabilities.cabal @@ -54,7 +54,9 @@ category: Codec build-type: Simple -- Extra doc files to be distributed with the package, such as a CHANGELOG or a README. -extra-doc-files: CHANGELOG.md +extra-doc-files: + CHANGELOG.md + README.md -- Extra source files to be distributed with the package, such as examples, or a tutorial module. -- extra-source-files: -- GitLab