1 files changed, 120 insertions, 0 deletions
diff --git a/doc/webid-oidc.texi b/doc/webid-oidc.texi
new file mode 100644
index 0000000..c8219c6
--- /dev/null
+++ b/doc/webid-oidc.texi
@@ -0,0 +1,120 @@
+\input texinfo @c -*-texinfo-*-
+@comment $Id@w{$}
+@documentlanguage en
+@comment %**start of header
+@include version.texi
+@settitle Webid-oidc manual
+@syncodeindex pg cp
+@syncodeindex fn cp
+@syncodeindex vr cp
+@syncodeindex tp cp
+@comment %**end of header
+
+@copying
+This is the manual of webid-oidc (version @value{VERSION}, @value{UPDATED}), an implementation of the Solid authentication protocol for guile, client and server.
+
+Copyright @copyright{} 2020, 2021 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, with no Front-Cover Texts, and with no Back-Cover
+Texts. A copy of the license is included in the section entitled ``GNU
+Free Documentation License''
+@end quotation
+@end copying
+
+@dircategory Software libraries
+
+@direntry
+* webid-oidc: (webid-oidc)Decentralized Authentication on the Web.
+@end direntry
+
+@titlepage
+@title Webid-oidc manual
+@subtitle for version @value{VERSION}, @value{UPDATED}
+@author Vivien Kraus (@email{vivien@@planete-kraus.eu})
+@page
+@vskip 0pt plus 1fill
+@insertcopying
+@end titlepage
+
+@contents
+@ifnottex
+@node Top
+@top Webid-oidc
+@end ifnottex
+
+@menu
+* Decentralized Authentication on the Web::
+* The Json Web Token::
+* GNU Free Documentation License::
+* Index::
+@end menu
+
+@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 The Json Web Token
+@chapter The Json Web Token
+
+The Json Web Token, or @dfn{JWT}, is a terse representation of a pair
+of JSON objects: the @dfn{header}, and the @dfn{payload}. The JWT can
+be @dfn{encoded} as a Json Web Signature (@dfn{JWS}), in which case
+the header is encoded to base64 with the URL alphabet, and without
+padding characters, the payload is also encoded to base64, and the
+concatenation of the encoding of the header, a dot, and the encoding
+of the payload is signed with some cryptography algorithm. In the
+following, we will only be interested by public-key cryptography. The
+concatenation of header, dot, payload, dot and signature in base64 is
+the encoding of the JWT.
+
+@node GNU Free Documentation License
+@appendix GNU Free Documentation License
+
+@include fdl.texi
+
+@node Index
+@unnumbered Index
+
+@printindex cp
+
+@bye