diff options
Diffstat (limited to 'doc/disfluid.texi')
| -rw-r--r-- | doc/disfluid.texi | 119 |
1 files changed, 110 insertions, 9 deletions
diff --git a/doc/disfluid.texi b/doc/disfluid.texi index 9c152f6..862280d 100644 --- a/doc/disfluid.texi +++ b/doc/disfluid.texi @@ -4,7 +4,7 @@ @c %**start of header @setfilename disfluid.info @documentencoding UTF-8 -@settitle Disfluid Reference Manual +@settitle Demanding Interoperability to Strengthen the Free (Libre) Web: Introducing Disfluid @c %**end of header @include version.texi @@ -12,21 +12,23 @@ @copying Copyright @copyright{} 2022 Vivien Kraus +@quotation Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License''. +@end quotation @end copying @dircategory The Algorithmic Language Scheme @direntry -* Disfluid: (disfluid). +* Disfluid: (disfluid)Decentralized Authentication on the Web @end direntry @titlepage -@title The Disfluid Manual +@title Interoperability to Strengthen the Free (Libre) Web: Introducing Disfluid @author Vivien Kraus @page @@ -43,18 +45,117 @@ Edition @value{EDITION} @* @node Top @top Disfluid -This document describes Disfluid version @value{VERSION}. +Disfluid is an independent implementation of a web stack focusing on +interoperability. In this implementation, the users control what +programs run in their computers. They also choose who to trust for +online data storage and processing, without needing any permission, or +can self-host their data. + +The software is available at +@url{https://labo.planete-kraus.eu/disfluid.git}. @menu -* Introduction:: Why Disfluid? +* Decentralized Authentication on the Web:: What is Disfluid? +* Cryptography elements in Disfluid:: @end menu @c ********************************************************************* -@node Introduction -@chapter Introduction -INTRODUCTION HERE +@node Decentralized Authentication on the Web +@chapter Decentralized Authentication on the Web + +Authentication on the web is currently handled in the following way: +anyone can install a server that will authenticate users on the +web. The problem is interoperability. If a client (an application) +wants to authenticate a user, it has to be approved by the +authentication server. In other words, if @var{useful-program} wants +to authenticate @var{MegaCorp} users, then @var{useful-program} has to +register to @var{MegaCorp} first, and get approved. This goes against +the principle of permission-less innovation, which is at the heart of +the web. + +In the decentralized authentication web, the best attempt so far is +that of ActivityPub. All servers are interoperable with respect to +authentication: if user A emits an activity, it is forwarded by A's +server to its recipients, and A's server is responsible for A's +identity. + +The problem with that approach is that the data is tied to the +application. It is not possible to use another application to process +the data differently, or to use multiple data sources, in an +interoperable way (without the ActivityPub server knowing). This means +that on Activitypub, microblogging applications will not present +different activities correctly. This also means that it is difficult +to write a free replacement to a non-free application program, because +it would need to manage the data. + +In the Solid ecosystem, there is a clear distinction between servers +and applications. An application is free to read data from all places +at the same time, using a permission-less authentication system. Since +the applications do not need to store data, the cost of having users +is neglectible, so users do not need prior approval before using them +(making captchas and the like a thing of the past). Servers do not +have a say in which applications the user uses. + +The authentication used is a slight modification of the +well-established OpenID Connect. It is intended to work in a web +browser, but this package demonstrates that it also works without a +web browser. + +@node Cryptography elements in Disfluid +@chapter Cryptography elements in Disfluid +Disfluid works with the JWA algorithms (RFC 7518) for signatures. + +@menu +* Key management:: +@end menu -This documentation is a stub. +@node Key management +@section Key management + +The @emph{(disfluid jwk)} module provides tools to manage keys, +according to the conventions presented in RFC 7517. + +@deftp {Class} <jwk> @var{kid} @var{key} +A class composed of a @var{key} (managed by gcrypt) and some +meta-data. For now, only the @dfn{key identifier} @var{kid}: a string +uniquely identifying a key or a key pair. A default value is always +provided. + +You can construct a new key with the following keyword arguments: +@table @code +@item #:n-size +This argument is used to generate a new RSA key pair. It is the number +of bits for the RSA key. Pass less than 1024 to raise an error. +@item #:e +This argument is used to generate a new RSA key pair, but it is +optional. Pass a value of 0 (the default) to let gcrypt pick a +suitable value. Pass 1 to set it to 65537. As with gcrypt, 2 is a +reserved value. Other than that, the value passed is used. If this is +a string, it is decoded from base64url first. +@item #:kid +Override the key identifier. By default, a new value is computed. +@end table +@end deftp + +@deftypefn {Generic method} @code{SRFI-180 alist} jwk->json (@var{key} @code{<jwk>}) +@deftypefnx {Generic method} @code{SRFI-180 alist} jwk-public->json (@var{key} @code{<jwk>}) +Extract and encode the key parameters of @var{key} into an +alist. @code{jwk->json} also encodes the private key, while +@code{jwk-public->json} only encodes the public key. Using +@code{jwk->json} is not recommended if you don’t need the private key, +because it leaks the private key to the guile garbage collection. +@end deftypefn + +@deftypefn {Generic method} @code{<string>} jkt (@var{key} @code{<jwk>}) +Compute the JWK Thumbprint (RFC 7638) of @var{key}. +@end deftypefn + +@deftp {Exception type} &invalid-key-parameters +An exception of this type is raised when the parameters cannot be used +to build a valid cryptographic key. It can also be raised when +generating a new key pair, if the key generation parameters are not +valid, or too unsafe. +@end deftp @bye |