path: root/doc/disfluid.texi

\input texinfo
@c -*-texinfo-*-

@c %**start of header
@setfilename disfluid.info
@documentencoding UTF-8
@settitle Demanding Interoperability to Strengthen the Free (Libre) Web: Introducing Disfluid
@c %**end of header

@include version.texi

@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)Decentralized Authentication on the Web
@end direntry

@titlepage
@title Interoperability to Strengthen the Free (Libre) Web: Introducing Disfluid
@author Vivien Kraus

@page
@vskip 0pt plus 1filll
Edition @value{EDITION} @*
@value{UPDATED} @*

@insertcopying
@end titlepage

@contents

@c *********************************************************************
@node Top
@top Disfluid

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
* Decentralized Authentication on the Web:: What is Disfluid?
* Cryptography elements in Disfluid::
@end menu

@c *********************************************************************

@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

@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