This is an automated email from the ASF dual-hosted git repository.
brianspector pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-milagro.git
The following commit(s) were added to refs/heads/master by this push:
new ae7ab86 update docs
ae7ab86 is described below
commit ae7ab86c3a320acceaed5a0fe711fe5052b8a9da
Author: Brian Spector <[email protected]>
AuthorDate: Tue Jun 25 14:56:19 2019 +0100
update docs
---
.dockerignore | 2 +
.gitignore | 12 +
Dockerfile | 10 +
docker-compose.yml | 18 +
docs/amcl-c-api.md | 19 +
docs/amcl-javascript-api.md | 14 +
docs/amcl-overview.md | 175 +++++++++
docs/contributor-guide.md | 15 +
docs/d-ta-api.md | 14 +
docs/d-ta-overview.md | 14 +
docs/doc2.md | 7 +
docs/doc3.md | 13 +
docs/milagro-crypto.md | 98 +++++
docs/milagro-design.md | 157 ++++++++
docs/milagro-intro.md | 95 +++++
docs/milagro-protocols.md | 870 ++++++++++++++++++++++++++++++++++++++++++++
docs/zkp-mfa-api.md | 14 +
docs/zkp-mfa-overview.md | 14 +
18 files changed, 1561 insertions(+)
diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 0000000..27d2dae
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,2 @@
+*/node_modules
+*.log
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..5395ea7
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,12 @@
+.DS_Store
+
+node_modules
+
+lib/core/metadata.js
+lib/core/MetadataBlog.js
+
+website/translated_docs
+website/build/
+website/yarn.lock
+website/node_modules
+website/i18n/*
diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 0000000..d369844
--- /dev/null
+++ b/Dockerfile
@@ -0,0 +1,10 @@
+FROM node:8.11.4
+
+WORKDIR /app/website
+
+EXPOSE 3000 35729
+COPY ./docs /app/docs
+COPY ./website /app/website
+RUN yarn install
+
+CMD ["yarn", "start"]
diff --git a/docker-compose.yml b/docker-compose.yml
new file mode 100644
index 0000000..6711192
--- /dev/null
+++ b/docker-compose.yml
@@ -0,0 +1,18 @@
+version: "3"
+
+services:
+ docusaurus:
+ build: .
+ ports:
+ - 3000:3000
+ - 35729:35729
+ volumes:
+ - ./docs:/app/docs
+ - ./website/blog:/app/website/blog
+ - ./website/core:/app/website/core
+ - ./website/i18n:/app/website/i18n
+ - ./website/pages:/app/website/pages
+ - ./website/static:/app/website/static
+ - ./website/sidebars.json:/app/website/sidebars.json
+ - ./website/siteConfig.js:/app/website/siteConfig.js
+ working_dir: /app/website
diff --git a/docs/amcl-c-api.md b/docs/amcl-c-api.md
new file mode 100644
index 0000000..7659f94
--- /dev/null
+++ b/docs/amcl-c-api.md
@@ -0,0 +1,19 @@
+---
+id: amcl-c-api
+title: AMCL C API
+sidebar_label: AMCL C API
+---
+
+Doxygen support is available for Milagro Crypto Library.
+
+An online version of the Doxygen output is available for viewing in a web
browser <a href="http://docs.milagro.io/en/doxygen/index.html";
target="_blank">here</a>.
+
+PDF of the Doxygen output is available for download <a
href="https://s3.amazonaws.com/docs.milagro.io/amcl-doxygen.pdf";
target="_blank">here</a>.
+
+:::caution THIS DOCUMENTATION IS OUT OF DATE
+This documentation is being updated.
+:::
+
+<!--
+Supported admonition types are: caution, note, important, tip, warning.
+-->
\ No newline at end of file
diff --git a/docs/amcl-javascript-api.md b/docs/amcl-javascript-api.md
new file mode 100644
index 0000000..498f037
--- /dev/null
+++ b/docs/amcl-javascript-api.md
@@ -0,0 +1,14 @@
+---
+id: amcl-javascript-api
+title: AMCL JavaScript API
+sidebar_label: AMCL JavaScript API
+---
+
+:::tip WE NEED HELP DOCUMENTING!
+Interested in becoming a contributor? Milagro is looking for you.
+[CONTRIBUTOR'S GUIDE](/docs/contributor-guide.html).
+:::
+
+<!--
+Supported admonition types are: caution, note, important, tip, warning.
+-->
\ No newline at end of file
diff --git a/docs/amcl-overview.md b/docs/amcl-overview.md
new file mode 100644
index 0000000..c2253de
--- /dev/null
+++ b/docs/amcl-overview.md
@@ -0,0 +1,175 @@
+---
+id: amcl-overview
+title: Apache Milagro Crypto Library (AMCL)
+sidebar_label: AMCL Overview
+---
+## Introduction
+One of the major mysteries in the real-world of crypto is resistance to the
exploitation of new research ideas. Its not that cryptographic research has
failed to throw up new ideas that have the potential for commercial
exploitation -- far from it. But in the real-world, 1970's crypto rules
supreme, and very little happens that isn't PKI/RSA based. The reasons for this
are many and varied. However one part of the puzzle might be the
non-availability of easy-to-use open source cryptograph [...]
+
+There are many crypto libraries out there. Many offer a bewildering variety of
cryptographic primitives, at different levels of security. Many use extensive
assembly language in order to be as fast as possible. Many are very **BIG**,
even bloated. Some rely on other external libraries. Many were designed by
academics for academics, and so are not really suitable for commercial use.
Many are otherwise excellent, but not written in our favorite language.
+
+The Apache Milagro Crypto Library (AMCL) is different; AMCL is completely
self-contained, except for the requirement for an external entropy source for
random number generation.
+
+AMCL is portable - there is no assembly language. The original version is
written in C, Java, Javascript, Go and Swift using only generic programming
constructs, but AMCL is truly multi-lingual, as compatible versions will be
available in many other languages. These versions will be identical in that for
the same inputs they will not only produce the same outputs, but all internal
calculations will also be the same.
+
+AMCL is fast, but does not attempt to set speed records (a particular academic
obsession). There are of course contexts where speed is of the essence; for
example for a server farm which must handle multiple SSL connections, and where
a 10% speed increase implies the need for 10% less servers, with a a 10% saving
on electricity. But in the Internet of Things we would suggest that this is
less important. In general the speed is expected to be "good enough". However
AMCL is small. Some lib [...]
+
+The C version of AMCL is configured at compile time for 16, 32 or 64 bit
processors, and for a specific elliptic curve. The Java and Javascript versions
are (obviously) processor agnostic, but the same choices of elliptic curve are
available.
+
+AMCL is written with an awareness of the abilities of modern pipelined
processors. In particular there was an awareness that the unpredictable program
branch should be avoided at all costs, not only as it slows down the processor,
but as it may open the door to side-channel attacks. The innocuous looking
```if``` statement - unless its outcome can be accurately predicted - is the
enemy of quality crypto software.
+
+In the sequel we refer to the C version of AMCL, unless otherwise specified.
We emphasis that all AMCL versions are completely self-contained. No external
libraries or packages are required to implement all of the supported
cryptographic functionality (other than for an external entropy source).
+
+## Library Structure
+
+The modules that make up AMCL are shown below, with some indication of how
they interact. Several example APIs will be provided to implement common
protocols. Note that all interaction with the API is via machine-independent
endian-indifferent arrays of bytes (a.k.a. octet strings). Therefore the
underlying workings of the library are invisible to the consumer of its
services.
+
+
+<figure>
+ <caption><strong>Figure 1.</strong> AMCL Library </caption>
+</figure>
+
+## Handling **BIG** Numbers
+
+### Representation
+
+One of the major design decisions is how to represent the 256-bit field
elements required for the elliptic curve and pairing-based cryptography. Here
there are two different approaches.
+
+One is to pack the bits as tightly as possible into computer words. For
example on a 64-bit computer 256-bit numbers can be stored in just 4 words.
However to manipulate numbers in this form, even for simple addition, requires
handling of carry bits if overflow is to be avoided, and a high-level language
does not have direct access to carry flags. It is possible to emulate the
flags, but this would be inefficient. In fact this approach is only really
suitable for an assembly language imp [...]
+
+The alternative idea is to use extra words for the representation, and then
try to offset the additional cost by taking full advantage of the "spare" bits
in every word. This idea follows a "corner of the literature"[^first] which has
been promoted by Bernstein and his collaborators in several publications. Refer
to Figure 2, where each digit of the representation is stored as a signed
integer which is the size of the processor word-length.
+
+[^first]: [Curve41417 Karatsuba revisited](http://eprint.iacr.org/2014/526)
+
+Note that almost all arithmetic takes place modulo a 256-bit prime number, the
modulus representing the field over which the elliptic curve is defined, here
denoted as \\( p \\).
+
+On 64-bit processors, AMCL represents numbers to the base \\( 2^{56} \\) in a
5 element array, the Word Excess is 7 bits, and for a 256-bit modulus the Field
Excess is 24 bits.
+
+On 32-bit processors, AMCL represents numbers to the base \\( 2^{29} \\) in a
9 element array, the Word Excess is 2 bits, and for a 256-bit modulus the Field
Excess is 5 bits.
+
+On 16-bit processors, AMCL represents numbers to the base \\( 2^{13} \\) in a
20 element array, the Word Excess is 2 bits, and for a 256-bit modulus the
Field Excess is 4 bits.
+
+Such a representation of a 256-bit number is referred to as a **BIG**.
Addition or subtraction of a pair of **BIG**s, results in another **BIG**.
+
+The Java version uses exactly the same 32-bit representation as above.
+
+For Javascript (where all numbers are stored as 64-bit floating point with a
52-bit mantissa, but mostly manipulated as 32-bit integers), numbers are
represented to the base \\( 2^{24} \\) in an 11 element array, the Word Excess
is 7 bits, and the Field Excess for a 256-bit modulus is 8 bits.
+
+### Addition and Subtraction
+
+The existence of a word excess means for example that multiple field elements
can be added together digit by digit, without processing of carries, before
overflow can occur.
+
+Only occasionally will there be a requirement to _normalize_ these _extended_
values, that is to force them back into the original format. Note that this is
independent of the modulus.
+
+The existence of a field excess means that, independent of the word excess,
multiple field elements can be added together before it is required to reduce
the sum with respect to the modulus. In the literature this is referred to as
lazy, or delayed, reduction. In fact we allow the modulus to be as small as 254
bits, which obviously increases the field excess.
+
+Note that these two mechanisms associated with the word excess and the field
excess (often confused in the literature) operate largely independently of each
other.
+
+AMCL has no support for negative numbers. Therefore subtraction will be
implemented as field negation followed by addition. However a field element \\(
x \\) can be negated by simply calculating \\( −x = e.p − x \\), where \\( e
\\) is the current excess associated with \\( x \\). Therefore subtraction will
be implemented as field negation followed by addition. In practice it is more
convenient to round \\( e \\) up to next highest power of 2, in which case \\(
e.p \\) can be calculated [...]
+
+
+<figure>
+ <caption><strong>Figure 2.</strong> AMCL Library</caption>
+</figure>
+<br>
+Normalization of extended numbers requires the word excess of each digit to be
shifted right by the number of base bits, and added to the next digit, working
right to left. Note that when numbers are subtracted digit-by-digit individual
digits may become negative. However since we are avoiding using the sign bit,
due to the magic of 2's complement arithmetic, this all works fine without any
conditional branches.
+
+Final full reduction of unreduced field elements is carried out using a simple
shift-and-subtract of the modulus, with one subtraction needed for every bit in
the actual field excess. Such reductions will rarely be required, as they are
slow and hard to do in constant time. Ideally it should only be required at the
end of a complex operation like an elliptic curve point multiplication.
+
+So with careful programming we avoid any unpredictable program branches. Since
the length of field elements is fixed at compile time, it is expected that the
compiler will unroll most of the time-critical loops. In any case the
conditional branch required at the foot of a fixed-size loop can be accurately
predicted by modern hardware.
+
+Worst case field excesses are easy to calculate. If two elements \\( a \\) and
\\( b \\) are to be added, and if their current field excesses are \\( e_{a}
\\) and \\( e_{b} \\) respectively, then clearly their sum will have a
worst-case field excess of \\( e_{a}+e_{b} \\). By careful programming and
choice of number base, full reductions can be largely eliminated[^second].
+
+[^second]: [Slothful Reduction](http://eprint.iacr.org/2017/437)
+
+### Multiplication and Reduction
+
+To support multiplication of **BIG**s, we will require a double-length
***DBIG*** type. Also the partial products that arise in the process of long
multiplication will require a double-length data type. Fortunately many popular
C compilers, like Gnu GCC, always support an integer type that is double the
native word-length. For Java the "int" type is 32-bits and there is a
double-length "long" type which is 64-bit. Of course for Javascript a double
length type is not possible, and so the [...]
+
+Multiprecision multiplication is performed column by column, propagating the
carries, working from right-to-left, but using the fast method described
in[^third]. At the foot of each column the total is split into the sum for that
column, and the carry to the next column. If the numbers are normalized prior
to the multiplication, then with the word excesses that we have chosen, this
will not result in overflow. The DBIG product will be automatically normalized
as a result of this process. [...]
+
+[^third]:[Missing a trick: Karatsuba
variations](http://eprint.iacr.org/2015/1247)
+
+The method used for full reduction of a **DBIG** back to a **BIG** depends on
the form of the modulus. We choose to support three distinct types of modulus,
(a) pseudo Mersenne of the form \\( 2^n-c \\) where \\( c \\) is small and $n$
is the size of the modulus in bits, (b) Montgomery-friendly of the form \\(
k.2^n-1 \\), and (c) moduli of no special form. For cases (b) and (c) we
convert all field elements to Montgomery's \\( n \\)-residue form, and use
Montgomery's fast method for mod [...]
+
+In all cases the **DBIG** number to be reduced \\( y \\) must be in the range
\\( 0<y<pR \\) (a requirement of Montgomery's method), and the result \\( x \\)
is guaranteed to be in the range \\( 0<x<2p \\) , where \\( R=2^{256+FE} \\)
for a 256-bit modulus. Note that the **BIG** result will be (nearly) fully
reduced. The fact than we allow \\( x \\) to be larger than \\( p \\) means
that we can avoid the notorious Montgomery "final subtraction". Independent of
the method used for reducti [...]
+
+Observe how unreduced numbers involved in complex calculations tend to be
(nearly fully) reduced if they are involved in a modular multiplication. So for
example if field element \\( x \\) has a large field excess, and if we
calculate \\( x=x.y \\), then as long as the unreduced product is less than \\(
pR \\), the result will be a nearly fully reduced \\( x \\). So in many cases
there is a natural tendency for field excesses not to grow without limit, and
not to overflow, without requir [...]
+
+Consider now a sequence of code that adds, subtracts and multiplies field
elements, as might arise in elliptic curve additions and doublings. Assume that
the code has been analysed and that normalisation code has been inserted where
needed. Assume that the reduction code that activates if there is a possibility
of an element overflowing its field excess, while present, never in fact is
triggered (due to the behaviour described above). Then we assert that once a
program has initialised no [...]
+
+## Extension Field arithmetic
+
+To support cryptographic pairings we will need support for extension fields.
We use a towering of extensions as required for BN curves and as required for
higher security BLS curves. An element of the quadratic extension field will be
represented as \\( f=a+ib \\), where \\( i \\) is the square root of the
quadratic non-residue -1. To add, subtract and multiply them we use the obvious
methods.
+
+However for negation we can construct \\( -f=-a-ib \\) as \\(
b-(a+b)+i.(a-(a+b) \\) which requires only one base field negation. A similar
idea can be used recursively for higher order extensions, so that only one base
field negation is ever required.
+
+## Elliptic Curves
+
+Three types of Elliptic curve are supported for the implementation of Elliptic
Curve Cryptography (ECC), but curves are limited to popular families that
support faster implementation. Weierstrass curves are supported using the Short
Weierstrass representation:
+
+$$y^2=x^3+Ax+B$$
+
+where \\( A=0 \\) or \\( A=-3 \\). Edwards curves are supported using both
regular and twisted Edwards format:
+
+$$Ax^2+y^2=1+Bx^2y^2$$
+
+where \\( A=1 \\) or \\( A=-1 \\). Montgomery curves are represented as:
+
+$$y^2=x^3+Ax^2+x$$
+
+where \\( A \\) must be small. As mentioned in the introduction, in all cases
we use exception-free formulae if available, as this facilitates constant time
imple- mentation, even if this invokes a significant performance penalty.
+
+In the particular case of elliptic curve point multiplication, there are
potentially a myriad of very dangerous side-channel attacks that arise from
using the classic double-and-add algorithm and its variants. Vulnerabilities
arise if branches are taken that depend on secret bits, or if data is even
accessed using secret values as indices. Many types of counter-measures have
been suggested. The simplest solution is to use a constant-time algorithm like
the Montgomery ladder, which has a [...]
+
+If using a Montgomery representation of the elliptic curve the Montgomery
ladder is in fact the optimal algorithm for point multiplication. For other
representations we use a fixed-sized signed window method.
+
+AMCL has built-in support for most standardised elliptic curves, along with
many curves that have been proposed for standardisation. Specifically it
supports the NIST256 curve, the well known Curve25519, the 256-bit Brain- pool
curve, the ANSSI curve, and six NUMS (Nothing-Up-My-Sleeve) curves proposed by
Bos et al. At higher levels of security the NIST384 and NIST521 curves are
supported, also Curve41417 as well as the Goldilocks curve, and our own HiFive
curve.
+Some of these proposals support only a Weierstrass representation, but many
also allow an Edwards or Montgomery form. Tools are provided to allow easy
integration of more curves.
+
+## Support for classic Finite Field Methods
+
+Before Elliptic Curves, cryptography depended on methods based on simple
finite fields. The most famous of these would be the well known RSA method.
These methods have the advantage of being effectively parameterless, and
therefore the issue of trust in parameters that arises for elliptic curves, is
not an issue.
+
+However these methods are subject to index calculus based methods of
cryptanalysis, and so fields and keys are typically much larger. So how to
support for example a 2048-bit implementation of RSA based on a library
designed for optimized 256-bit operations? The idea is simple; use AMCL as a
virtual 256-bit machine, and build 2048-bit arithmetic on top of that.
+
+And to claw back some decent performance use the Karatsuba method so that for
example 2048-bit multiplication recurses efficiently right down to 256-bit
operations. Of course the downside of the Karatsuba method is that while it
saves on multiplications, the number of additions and subtractions is greatly
increased. However the existence of generous word excesses in our
representation makes this less of a problem, as most additions can be carried
out without normalization.
+
+Secret key operations like RSA decryption use the Montgomery ladder to achieve
side-channel-attack resistance.
+
+The implementation can currently support \\( 1024.2^n \\) bit fields, so for
example 2048-bit RSA can be used to get reasonably close to the AES-128-bit
level of security, and if desired 4096 bit RSA can be used to comfortably
exceed it.
+
+Note that this code is supported independently of the elliptic curve code. So
for example RSA and ECC can be run together within a single application.
+
+However we regard these methods as "legacy" as in our view ECC based methods
are a much better fit for the IoT.
+
+## Multi-Lingual support
+
+It is a **BIG** ask to develop and maintain multiple versions of a crypto
library written in radically different languages such as C, Java, Javascript,
Go and Swift. This has discouraged the use of language specific methods (which
are in any case of little relevance here), and strongly encouraged the use of
simple, generic computer language constructs.
+
+This approach brings a surprising bonus: AMCL can be automatically converted
to many other languages using available translator tools. For example Tangible
Software Solutions market a Java to C# converter. This generated an efficient
fully functional C# version of AMCL within minutes. The same company market a
Java to Visual Basic converter.
+
+Google have a Java to Objective C converter specifically designed to convert
Android apps developed in Java, to iOS apps written in Objective C.
+
+Of course not all languages can be supported in this way, so support for some
will be developed manually. In particular a Rust version is currently under
development.
+
+## Discussion
+
+We found in our code that, with few exceptions, reductions due to possible
overflow of the field excess of a **BIG** were very rare, especially for the
64-bit version of the library. Similarly normalization was rarely needed for
the 64-bit code. This is due to the much greater excesses that apply in the
64-bit representation. In some experiments we calculated thousands of random
pairings, and reduction due to field excess overflow detection never happened.
+
+In general in developing AMCL we tried to use optimal methods, without going
to what we (very subjectively) regarded as extremes in order to maximize
performance. Algorithms that require less memory were generally preferred if
the impact on performance was not large. Some optimizations, while perfectly
valid, are hard to implement without having a significant impact on program
readability and maintainability. Deciding which optimizations to use and which
to reject (on the grounds of cod [...]
+readability and maintainability) is admittedly rather arbitrary!
+
+One notable omission from AMCL is the use of pre-computation on fixed
parameters in order to speed up certain calculations. We try to justify this,
rather unconvincingly, by pointing out that pre-computation must of necessity
increase code size. Furthermore such methods are more sensitive to side-channel
attacks and much of their speed advantage will be lost if they are to be fully
side-channel protected. Also pre-computation on secret values clearly increases
the amount of secret data t [...]
+
+However the development roadmap view might change in later versions depending
on the project supporters in-the-field experiences of using AMCL.
+
+---
+
+:::note See an error in this documentation?
+Submit a pull request on the development branch of [Milagro Website
Repo](https://github.com/apache/incubator-milagro).
+:::
+
+<!--
+Supported admonition types are: caution, note, important, tip, warning.
+-->
\ No newline at end of file
diff --git a/docs/contributor-guide.md b/docs/contributor-guide.md
new file mode 100644
index 0000000..69d5015
--- /dev/null
+++ b/docs/contributor-guide.md
@@ -0,0 +1,15 @@
+---
+id: contributor-guide
+title: Contributor's Guide
+sidebar_label: Contributor's Guide
+---
+
+# Become a contributor
+
+<p>Keeping with our spartan theme, for now, it's best to send an email to <a
href="mailto:[email protected]?Subject=Subscribe";
target="_top">dev-subscribe @ milagro.apache.org</a> to join our mailing
list.</p>
+
+More information will be available here shortly.
+
+<!--
+Supported admonition types are: caution, note, important, tip, warning.
+-->
\ No newline at end of file
diff --git a/docs/d-ta-api.md b/docs/d-ta-api.md
new file mode 100644
index 0000000..9ed0111
--- /dev/null
+++ b/docs/d-ta-api.md
@@ -0,0 +1,14 @@
+---
+id: d-ta-api
+title: D-TA Node API
+sidebar_label: D-TA Node API
+---
+
+:::tip WE NEED HELP DOCUMENTING!
+Interested in becoming a contributor? Milagro is looking for you.
+[CONTRIBUTOR'S GUIDE](/docs/contributor-guide.html).
+:::
+
+<!--
+Supported admonition types are: caution, note, important, tip, warning.
+-->
\ No newline at end of file
diff --git a/docs/d-ta-overview.md b/docs/d-ta-overview.md
new file mode 100644
index 0000000..861f91a
--- /dev/null
+++ b/docs/d-ta-overview.md
@@ -0,0 +1,14 @@
+---
+id: d-ta-overview
+title: Decentralized Trust Authority Overview
+sidebar_label: D-TA Node Overview
+---
+
+:::tip WE NEED HELP DOCUMENTING!
+Interested in becoming a contributor? Milagro is looking for you.
+[CONTRIBUTOR'S GUIDE](/docs/contributor-guide.html).
+:::
+
+<!--
+Supported admonition types are: caution, note, important, tip, warning.
+-->
\ No newline at end of file
diff --git a/docs/doc2.md b/docs/doc2.md
new file mode 100644
index 0000000..20c0c95
--- /dev/null
+++ b/docs/doc2.md
@@ -0,0 +1,7 @@
+---
+id: doc2
+title: document number 2
+---
+
+This is a link to [another document.](doc3.md)
+This is a link to an [external page.](http://www.example.com)
diff --git a/docs/doc3.md b/docs/doc3.md
new file mode 100644
index 0000000..bcb9054
--- /dev/null
+++ b/docs/doc3.md
@@ -0,0 +1,13 @@
+---
+id: doc3
+title: This is document number 3
+---
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. In ac euismod odio,
eu consequat dui. Nullam molestie consectetur risus id imperdiet. Proin sodales
ornare turpis, non mollis massa ultricies id. Nam at nibh scelerisque, feugiat
ante non, dapibus tortor. Vivamus volutpat diam quis tellus elementum bibendum.
Praesent semper gravida velit quis aliquam. Etiam in cursus neque. Nam lectus
ligula, malesuada et mauris a, bibendum faucibus mi. Phasellus ut interdum
felis. Phasellus in odi [...]
+
+Duis et egestas libero, imperdiet faucibus ipsum. Sed posuere eget urna vel
feugiat. Vivamus a arcu sagittis, fermentum urna dapibus, congue lectus. Fusce
vulputate porttitor nisl, ac cursus elit volutpat vitae. Nullam vitae ipsum
egestas, convallis quam non, porta nibh. Morbi gravida erat nec neque bibendum,
eu pellentesque velit posuere. Fusce aliquam erat eu massa eleifend tristique.
+
+Sed consequat sollicitudin ipsum eget tempus. Integer a aliquet velit. In
justo nibh, pellentesque non suscipit eget, gravida vel lacus. Donec odio ante,
malesuada in massa quis, pharetra tristique ligula. Donec eros est, tristique
eget finibus quis, semper non nisl. Vivamus et elit nec enim ornare placerat.
Sed posuere odio a elit cursus sagittis.
+
+Phasellus feugiat purus eu tortor ultrices finibus. Ut libero nibh, lobortis
et libero nec, dapibus posuere eros. Sed sagittis euismod justo at consectetur.
Nulla finibus libero placerat, cursus sapien at, eleifend ligula. Vivamus elit
nisl, hendrerit ac nibh eu, ultrices tempus dui. Nam tellus neque, commodo non
rhoncus eu, gravida in risus. Nullam id iaculis tortor.
+
+Nullam at odio in sem varius tempor sit amet vel lorem. Etiam eu hendrerit
nisl. Fusce nibh mauris, vulputate sit amet ex vitae, congue rhoncus nisl. Sed
eget tellus purus. Nullam tempus commodo erat ut tristique. Cras accumsan massa
sit amet justo consequat eleifend. Integer scelerisque vitae tellus id
consectetur.
diff --git a/docs/milagro-crypto.md b/docs/milagro-crypto.md
new file mode 100644
index 0000000..732665f
--- /dev/null
+++ b/docs/milagro-crypto.md
@@ -0,0 +1,98 @@
+---
+id: milagro-crypto
+title: Milagro Crypto
+sidebar_label: Milagro Crypto
+---
+
+One of the critical points about information security is to give access to
resources only to authorized entities and deny access to unauthorized ones.
+Preventing unauthorized access very often comes down to making it ___almost
impossible___, i.e., tough, expensive, complicated, and time-consuming for the
unauthorized entities to get access to resources.
+
+The same principles apply to cryptography. In most cases, a suitable
encryption mechanism satisfies at least two basic requirements:
+1. It is possible to give easy access to encrypted, cryptographically
protected content to authorized entities.
+2. It is possible to make it extremely challenging for unauthorized entities
to access encrypted (ditto) content.
+
+Using the above, we can define an operation: Encryption that is tough to
reverse without possessing a particular parameter, for example, a decryption
key.
+In RSA-based encryption two prime numbers, the private key, are multiplied to
generate a public key, so that it is almost impossible to reverse the operation
and retrieve the original prime numbers.
+
+Multiple sources are available online to read more on the topic. We recommend
this short paper from [Cal Berkeley at this
link](https://math.berkeley.edu/~kpmann/encryption.pdf).
+
+As noted in the mentioned paper, with RSA, we need enormous prime numbers to
make it ___almost impossible___ to break the encryption, hence to find the two
big prime numbers.
+On elliptic curves, multiplication of a point by a number can be defined so
that much shorter numbers than in the big prime number case are needed to reach
the same level of ___almost impossibility___.
+
+## Elliptic Curve Cryptography
+Elliptic curves are another way to do encryption. Elliptic curves are
mathematical structures, on which operations like addition and multiplications
of points are easily defined.
+In particular, multiplication of a point by a number is a relatively easy
operation to compute, while it is ___almost impossible___ to reverse the
process, that is, to determine
+the multiplier knowing the result of the multiplication.
+
+The problem of reversing the multiplication is known as the Discrete Logarithm
Problem on elliptic curves (ECDLP).
+The difference in computational complexity (between performing the
multiplication and reversing the result to retrieve the multiplier) is one of
the essential cornerstones of elliptic curve cryptography.
+
+## Pairing Based Cryptography
+Using elliptic curves we can now define on some elliptic curve a bilinear
function called a ___pairing___, which enables a mapping from two points on the
same curve (or points on two related curves) into a different mathematical
structure called a finite field. The bilinearity of the pairing is the key
characteristic that makes pairing interesting and widely used in cryptography.
+
+A ___bilinear pairing___ \\( e \\) maps a pair of points (hence the name
pairing) on an elliptic curve \\( E \\), defined over some field \\( F_{q} \\)
to an element of the multiplicative group of a finite extension of \\(
{F}_{q^k} \\).
+
+$$ e(mA+B, nP + Q) = e(A,P)^{mn} e(B, Q) $$
+
+The elements \\( P \\) and \\( Q \\) lie in two different groups, respectively
\\( G_{1} \\) and \\( G_{2} \\). The choice of those two different group
determines a different ___types___ of pairing.
+
+Let \\( E \\) an ordinary elliptic curve, take \\( G_{1} \neq G_{2} \\), and
if there is not an efficiently computable isomorphism \\( \phi:G_{1}\to G_{2}
\\) then the pairing is said to be of ___Type\\( -3 \\)___.
+
+Currently, most of the state-of-the-art implementations of pairings take place
on ordinary curves that assume the ___Type\\( -3 \\)___ scenario for reasons of
efficiency and secure implementation.
+
+
+## Identity Based Encryption
+Pairing-based cryptography builds on elliptic curve-based cryptography, but
the extra functionality of the pairing enables us to design schemes which would
otherwise be impossible to realize, or would be prohibitively expensive to do
using RSA-based cryptosystems.
+
+Identity-based encryption (IBE) is one such scheme that has received a large
of amount of attention from the crypto community, and where commercially
available products have been on the market for some time and are in wide use
today.
+
+IBE is similar to classical asymmetric key cryptography, in that each user has
a public key for encryption and a private key for decryption. But there are
many differences:
+
+1. IBE allows public keys to be set to the value of a pre-existing identifier,
such as an email address, while in PKI the public key does not contain the
notion of an identity, and the association with an identifier is created by a
certificate signed by a third party (Certification Authority).
+2. Clients or individual users do not generate private keys, but must instead
download them from a trusted third party known as the Trust Authority (TA).
+3. In IBE, to encrypt messages, the sender must obtain public “system
parameters” from the Trust Authority (TA). These system parameters are used in
combination with the intended recipient’s identity string (e.g. email address)
to generate an encrypted message.
+
+## Post-Quantum Cryptography
+
+"Post-quantum cryptography (sometimes referred to as quantum-proof,
quantum-safe or quantum-resistant) refers to cryptographic algorithms (usually
public-key algorithms) that are thought to be secure against an attack by a
quantum computer. As of 2018, this is not true for the most popular public-key
algorithms, which can be efficiently broken by a sufficiently strong
hypothetical quantum computer.
+
+The problem with currently popular algorithms is that their security relies on
one of three hard mathematical problems: the integer factorization problem, the
discrete logarithm problem or the elliptic-curve discrete logarithm problem.
All of these problems can be easily solved on a sufficiently powerful quantum
computer running Shor's algorithm.
+
+Even though current, publicly known, experimental quantum computers lack
processing power to break any real cryptographic algorithm, many cryptographers
are designing new algorithms to prepare for a time when quantum computing
becomes a threat."[^first]
+
+[^first]: [Wikipedia
article](https://en.wikipedia.org/wiki/Post-quantum_cryptography)
+
+## Zero Knowledge Proof
+
+"In cryptography, a **zero-knowledge proof** or **zero-knowledge protocol** is
a method by which one party (the _prover_) can prove to another party (the
_verifier_) that a given statement is true, without conveying any information
apart from the fact that the statement is indeed true.
+
+If proving the statement requires knowledge of some secret information on the
part of the prover, the definition implies that the verifier will not be able
to prove the statement in turn to anyone else, since the verifier does not
possess the secret information.
+
+Notice that the statement being proved must include the assertion that the
prover has such knowledge (otherwise, the statement would not be proved in
zero-knowledge, since at the end of the protocol the verifier would gain the
additional information that the prover has knowledge of the required secret
information).
+
+If the statement consists _only_ of the fact that the prover possesses the
secret information, it is a special case known as _zero-knowledge proof of
knowledge_, and it nicely illustrates the essence of the notion of
zero-knowledge proofs: proving that one has knowledge of certain information is
trivial if one is allowed to simply reveal that information; the challenge is
proving that one has such knowledge without revealing the secret information or
anything else."[^second]
+
+[^second]: [Wikipedia
article](https://en.wikipedia.org/wiki/Zero-knowledge_proof)
+## Summary
+
+**Elliptic curve cryptography** is an attractive alternative to conventional
public key cryptography for implementation on constrained devices, where the
significant computational resources i.e. speed, memory are limited and
low-power wireless communication protocols is essential. It attains the same
security levels as traditional cryptosystems using smaller parameter sizes.
+
+**Pairing-based cryptography** builds on elliptic curve-based cryptography,
but the extra functionality of the pairing enables us to design schemes which
would otherwise be impossible to realize, or would be prohibitively expensive.
Examples include identity-based encryption, group signatures and
non-interactive zero-knowledge proofs.
+
+**Identity-based encryption** doesn’t require certificates and certificate
authorities. A trusted third party generates all the private keys, but all the
public keys can be derived knowing the identity of the public key owner, for
example, an email address. That means that no certificate is needed to bind a
public key to its owner. Typically, it is up to the application to verify the
owner possesses access to the unique identity attribute during the enrollment
process in which a client [...]
+
+**Post-quantum cryptography** Post-quantum cryptography are cryptosystems
which can be run on a classical computer, but are secure even if an adversary
possesses a quantum computer. For data that must be private, but has the
potential to be long lived and publicly available, using post-quantum secure
algorithms like AES 256-bit for encryption and SIKE for encapsulation of
encryption keys is essential.
+
+**Zero-knowledge proof** is a method by which one party (the prover) can prove
to another party (the verifier) that a given statement is true, without
conveying any information apart from the fact that the statement is indeed true.
+
+For an in-depth dive into the cryptographic protocols in use within the
Milagro framework, see the next section [Milagro
Protocols](milagro-protocols.html).
+
+---
+
+:::note See an error in this documentation?
+Submit a pull request on the development branch of [Milagro Website
Repo](https://github.com/apache/incubator-milagro).
+:::
+
+<!--
+Supported admonition types are: caution, note, important, tip, warning.
+-->
\ No newline at end of file
diff --git a/docs/milagro-design.md b/docs/milagro-design.md
new file mode 100644
index 0000000..ce7a24d
--- /dev/null
+++ b/docs/milagro-design.md
@@ -0,0 +1,157 @@
+---
+id: milagro-design
+title: Milagro Design
+sidebar_label: Milagro Design
+---
+## Protocols and Technology
+
+### Identity Based Encryption
+
+M-Pin and Chow Choo are in the class of Identity Based Encryption protocols,
which use pairings in their construction. The M-Pin Protocol is intended to
replace the well-known Username/Password authentication mechanism which is
widely considered to be effectively broken.
+
+The main problem is the existence of a password file on the server, which is
commonly stolen and hacked, revealing most user passwords.
+
+The idea behind Milagro's Zero-Knowledge Proof Multi-Factor Authentication
(ZKP-MFA) Server is that each registered client is issued with a secret
cryptographic key derived from their identity. They then prove to the Milagro
ZKP-MFA Server that they are in possession of this key using a zero-knowledge
proof protocol, which can be extended to include authenticated key agreement.
+
+This protocol design eliminates the need for any information related to
clients, or their keys, to be kept on the authentication server. Should an
attacker penetrate the server, it is impossible to deduct any information about
end users because it doesn't exist, at least within the authentication system.
+
+Common to both Chow-Choo and M-Pin is that the keys are issued in shares, not
as whole keys, by entities called Decentralized Trust Authorities. Only the
clients who receive all of the shares from the D-TA's, will ever know their
completed whole keys.
+
+Industry commentators have long advocated a multi-factor solution. The novel
feature of M-Pin and Chow-Choo is that the cryptographic secrets issued to
clients or peers may be safely split up into any number of independent factors.
+
+Each of these factors has the same form; they are points on an elliptic curve.
To recreate the original secret, they are simply added together again -- it's
as simple as that.
+
+One factor might be derived from a key unlocked from the biometric login (ex:
FaceID) which is available as a PIN input on a successful biometric
authentication. This 'biometric based' PIN is, on Apple hardware, stored in the
secure element of the device (something you are). Another factor might be the
remainder token securely stored in the authenticator app on a smartphone
(something you have). Yet a final piece can be a PIN or passphrase (something
you know), which is secure as the M-P [...]
+
+### Decentralized Identity
+
+Milagro applications use these identity based protocols in combination with
classical cryptosystems where the endpoint generates a public/private key pair
and the private key never leaves the application or device.
+
+An entity running a Milagro application attaches the public keys it has
generated upon initialization to a self sovereign identity document (ID
Document), that only reveals a unique account code as identifier. This ID
document is signed by the Milagro and distributed over a decentralized identity
system built upon IPFS[^first], so each ID Document lives on an immutable,
operation-based conflict-free replicated data structure (CRDT), which is
accessible to any other Milagro application.
+
+[^first]: [IPFS](https://github.com/ipfs/ipfs)
+
+_For further detail, please see the format specification for ID Documents._
+
+### Encrypted Envelope
+
+ID Documents enable messages, called Encrypted Envelopes, containing secrets
to be sent between endpoints running Milagro software. This can include
clients, servers and peers and Milagro ZKP-MFA Servers, ZKP-MFA clients and
Decentralized Trust Authorities. The ID Documents of recipients are available
to any endpoint, so their public keys can be used to secure secrets in transit.
In the case of digital asset custody, these messages need to be part of a
permanent record, available in a de [...]
+
+Messages and immutable records are encrypted with AES-GCM at a 256-bit level
with parameters anticipating quantum cryptography. It is necessary to know the
recipient's public key, obtained via the ID Document, in order to encapsulate
the encryption key for each recipient of the message or entity who has access
to the Immutable Record.
+
+SIKE keys pairs are generated locally by endpoints running Milagro software,
are not received in shares from D-TAs. SIKE public keys are used by the sender
of a message to encapsulate the AES 256-bit key used to create the Encrypted
Envelope. An encapsulation takes place once for every recipient and is affixed
to the Encrypted Envelope.
+
+BLS signatures handle two jobs. Like SIKE key pairs, BLS signature key pairs
are generated locally by endpoints running Milagro software, are not received
in shares from D-TAs. The signatures these keys generate enable the
non-repudiation of Encrypted Envelopes between endpoints and stored long term
as immutable records. This is a classic use case of digital signatures, like
PGP signatures over email.
+
+_For further detail, please see the format specification for Encrypted
Envelopes._
+
+The other use of BLS signatures is more complex. As described previously, BLS
signatures have unique properties. Milagro leverages its own Encrypted Envelope
format to enable the BLS ability of splitting signing keys by with a secure
mechanism to securely distribute the split BLS signing keys. When delivered
securely to the right entities, these part shares of BLS signing keys
themselves become signature keys. The thresholds of these signatures can be
aggregated securely to produce an ag [...]
+
+Another capability is for a public key to be aggregated from multiple public
keys in advance of aggregating signatures created by the corresponding private
keys. These private keys are generated locally, and never leave the device, vs
the method described previously. Signatures made from these keys can themselves
be aggregated into a complete signature, verified by the aggregated public key.
+
+These capabilities are well suited to safeguarding secrets with an example in
the following section.
+
+## Decentralized Trust Authorities: D-TA
+
+The Milagro framework protocols rely on Decentralized Trust Authorities for
two jobs: Issuing shares of secrets, or safeguarding shares of secrets.
+
+D-TAs can issue shares, or fractions, of Type-3 Pairing private keys to
Milagro Applications, such as the Milagro ZKP-MFA Servers or clients or to
other D-TAs, which can be any software or hardware applications that have
embedded some Milagro code in order derive the functional capabilities.
+
+These clients or peers become the only entities that know the completed whole
keys assembled from shares issued by different Decentralized Trust Authorities.
+
+Type-3 pairings were selected as they are the most efficient pairing and will
work with non-supersingular pairing-friendly curves.
+
+These operate as \\( G_1 \\) x \\( G_2 \rightarrow G_T \\), where \\( G_2 \\)
is a particular group of points, again of the order \\( q \\), but on a twisted
elliptic curve defined over an extension which is a divisor of \\( k \\).
+
+These curves can be constructed to be a near perfect fit at any required level
of security. The pairing protocols within the Milagro framework all work on a
Type-3 pairing.
+
+One of the novel aspects of pairing-based cryptography is that deployed
secrets are commonly represented as points on an elliptic curve, which are the
result of multiplying a known point by a master secret \\( s \\).
+
+So for example a secret might be of the form \\( sP \\), where \\( P \\) is
known.
+
+There are a number of interesting things we can do with secrets that have this
form, that are not possible with the secrets that arise when using other
cryptographic technologies.
+
+For example they can be split into two, into \\( s_1P \\) and \\( s_2P \\)
where \\( s=s_1+s_2 \\) and \\( sP = s_1P +s_2P \\).
+
+In fact they can be just as easily split into multiple parts, just like
chopping up a cucumber.
+
+We can also add extra components to create a secret of the form \\( s(P_1+P_2)
= sP_1+sP_2 \\).
+
+It is the flexibility that arises from this form of the secret that allows us
to introduce the idea of chopping off a tiny sliver of the secret to support a
PIN number.
+
+It also facilitates the concept of *Time Permits* as discussed in a later
section.
+
+Lastly, it enables Decentralized Trust.
+
+### Issuing Secrets
+
+A Trusted Authority will be in possession of a master secret \\( s \\), a
random element of \\( F_q \\).
+
+A client secret is of the form \\( s.H(ID) \\), where ID is the client
identity and \\( H(.) \\) a hash function which maps to a point on \\( G_1 \\).
+
+From prior art, we assume that \\( H \\) is modeled as a random oracle where
\\( H(ID) = r_{ID}.P \\)
+
+where \\( r_{ID} \in F_q \\) is random and \\( P \\) is a fixed generator of
\\( G_1 \\).
+
+A Milagro ZKP-MFA Server will be issued with \\( sQ \\), where \\( Q \\) is a
fixed generator of \\( G_2 \\).
+
+Note that this will be the only multiple of \\( s \\) in \\( G_2 \\) ever
provided by the TA. Servers will always be associated with their own unique
master secrets.
+
+Note that the TA functionality can be trivially decentralized and distributed
using a secret sharing scheme, to remove from the overall system a single point
of compromise or coercion.
+
+In the simplest possible case there may be two Decentralized Trusted
Authorities (D-TAs), each of which independently maintains their own share of
the master key.
+
+So \\( s=s_1+s_2 \\), and each D-TA issues a part-client key to the client \\(
s_1 H(ID) \\) and \\( s_2 H(ID) \\), which the client, after receiving the
shares, adds together to form their full key.
+
+Now even if one D-TA is compromised, the client key is still safe.
+
+In the age of self sovereign identity, any entity can be a Decentralized Trust
Authority as long as its Beneficiary trusts it to securely issue shares of
secrets, or hold them for safekeeping.
+
+### Safekeeping Secrets
+
+A D-TA may act as a Fiduciary over secrets where it can participate in a
process to enable a Beneficiary to recover the secret. Using aggregated BLS
signatures in a simple example, an entity running Milagro software may engage
multiple D-TAs to act as Fiduciaries over its seed value used to generate and
back up a cryptocurrency HD Wallet.
+
+As described in[^first] the first step is for each D-TA to generate a key pair
by choosing \\( s k \stackrel{s}{\leftarrow} \mathbb{Z}_{q} \\) to compute:
+
+$$ p k \leftarrow g_{2}^{s k}$$
+
+which outputs the \\( (p k, s k) \\).
+
+The Beneficiary would select which D-TA service providers (acting in concert)
it would use to help it generate a secret. Assume a Beneficiary is also a
participant in this protocol, it also runs a D-TA and acts as the designated
combiner in the protocol.
+
+[^first]: [Compact Multi-Signatures for Smaller
Blockchains](https://eprint.iacr.org/2018/483)
+
+In advance of creating the HD Wallet seed, a Beneficiary would elicit the
services of Decentralized Trust Authorities to act as Fiduciaries in a
decentralized secret recovery protocol. The Beneficiary's next step calculates
the aggregate public key by running protocol \\( \text { KAg }\\)({\\( p k_{1},
\ldots, p k_{n} \\)}) using the D-TA's known public keys as input (who have
agreed to act as Fiduciaries to this process) and also its own public key.
+
+The Beneficiary then requests a signature \\( \sigma \\) on a message \\( m
\\) from each of the D-TAs acting as Fiduciaries, including itself. For each
D-TA, singing is a single round protocol.
+
+To finalize setup, each D-TA transmits its signature \\( \sigma \\) to the
Beneficiary (acting as designated combiner). The Beneficiary generates its own
signature and combines it with the received D-TA signatures for the final
aggregated signature of \\( \sigma \leftarrow \prod_{j=1}^{n} s_{j} \\).
+
+The final signature is verified against the aggregated public key if the
verifier function outputs 1. Assuming so, the setup completes by hashing the
aggregated signature where \\( H(\tilde{\sigma}) \\) is the seed of the HD
Wallet.
+
+Assuming the Beneficiary has backed up their BLS signature key, recovering the
HD Wallet seed from multiple Fiduciaries becomes as simple as re-running the
setup protocol again. It is easy to envision Fiduciary services running D-TAs,
responding and authenticating requests for recovering secrets.
+
+## Summary
+
+### Pairing and PQ Cryptography
+Milagro leverages a combination of pairing and post-quantum algorithms to
distribute cryptographic operations and split cryptographic parameters,
providing a level of security and functionality that is a step forward in when
compared to the certificate backed cryptosystems in service today. With pairing
cryptography, security systems such as multi-factor authentication using zero
knowledge protocols, certificate-less authenticated key agreement with perfect
forward secrecy and decentrali [...]
+
+### Decentralized Cryptosystem
+Bitcoin's blockchain provides an alternative distributed approach to managing
a currency without the need for a central bank. With bitcoin, the ledger is
distributed, not centralized. Milagro's cryptosystem is decentralized to create
the same advantages as a distributed ledger. While architecturally different to
the blockchain, Milagro's cryptosystem and the applications built on it are
compatible with and can add significant value to cryptocurrencies and other
decentralized networks.
+
+Milagro envisions a new class of cryptographic service providers called
Decentralized Trust Authorities, or D-TAs for short. The purpose of a D-TA is
to independently issue shares, or fractions, of cryptographic keys to Milagro
clients and servers and application endpoints which have embedded Milagro
cryptographic libraries. D-TA's also operate as 'Fiduciaries', to enable their
'Beneficiaries' to recover secrets in a decentralized manner, without keeping a
share of the secret itself. D-T [...]
+
+### No Single Point of Compromise
+Milagro entities receive issued shares cryptographic keys or signatures and
combine them to create the whole completed key or signature, thus becoming the
only audience who possess knowledge of the entire key or signature. If D-TAs
are under separate organizational controls, current root key compromises and
key escrow threats inherent in PKI systems are an order of magnitude harder to
achieve in a Milagro cryptosystem. An attacker would need to subvert all
independent parties.
+
+In other words, all D-TAs used to generate shares, or fractions, of keys for
Milagro clients and servers must be compromised to create the equivalent of a
PKI root key compromise. All D-TAs under the threshold needed to recreate a
signature would need to be compromised (including the Beneficiary) in order to
generate a final signature.
+
+---
+
+:::note See an error in this documentation?
+Submit a pull request on the development branch of [Milagro Website
Repo](https://github.com/apache/incubator-milagro).
+:::
+
+<!--
+Supported admonition types are: caution, note, important, tip, warning.
+-->
\ No newline at end of file
diff --git a/docs/milagro-intro.md b/docs/milagro-intro.md
new file mode 100644
index 0000000..c9fba87
--- /dev/null
+++ b/docs/milagro-intro.md
@@ -0,0 +1,95 @@
+---
+id: milagro-intro
+title: Milagro Introduction
+sidebar_label: Milagro Introduction
+---
+
+Apache Milagro is core security infrastructure and crypto libraries
purpose-built for decentralized networks and distributed systems, while also
providing value to cloud-connected app-centric software and IoT devices that
require Internet scale.
+
+Milagro's purpose is to provide a secure and positive open source alternative
to centralized and proprietary monolithic trust providers such as commercial
certificate authorities and the certificate backed cryptosystems that rely on
them.
+
+## Pairing Cryptography
+
+Over the last decade, pairings on elliptic curves have been a very active area
of research in cryptography, particularly within decentralized networks and
distributed systems.
+
+A pairing is a kind of the bilinear map defined over an elliptic curve.
Examples include Weil pairing, Tate pairing, optimal Ate pairing and so on.
+
+Pairings map pairs of points on an elliptic curve into the multiplicative
group of a finite field. Their unique properties have enabled many new
cryptographic protocols that had not previously been feasible.
+
+[Pairing-Based Cryptography
(PBC)](https://en.wikipedia.org/wiki/Pairing-based_cryptography) is emerging as
a solution to complex problems that proved intractable to the standard
mathematics of Public-Key Cryptography such as Identity-Based Encryption,
whereby the identity of a client can be used as their public key.
+
+In certain use cases, this removes the need for a PKI infrastructure
eliminates the root key 'single point of compromise' weakness, as the main
reason to issue certificates is used to bind a public / private key pair to an
identity.
+
+Removing the certificate management burden enables the identity management and
key lifecycle to take place within the decentralized cryptosystem itself.
+
+As a result, Milagro's decentralized cryptosystem design goals seek to deliver
products that are easier to scale and manage that traditional PKI, and are a
seamless fit for today's decentralized networks and distributed systems.
+
+## Pairings Go Mainstream
+
+Pairings are key building blocks in Apache Milagro's crypto libraries and
products. As examples, BLS signatures feature prominently in Milagro
Decentralized Trust Authorities (D-TA), while the M-Pin protocol used in the
Milagro ZKP-MFA clients and servers.
+
+[BLS signatures](https://en.wikipedia.org/wiki/Boneh-Lynn-Shacham) are widely
recognized within the cryptocurrency space for their signature aggregation
abilities. BLS signatures are now going through an IETF submission
review[^first] standardization process.
+
+[^first]: [IETF BLS Signature Internet
Draft](https://datatracker.ietf.org/doc/draft-boneh-bls-signature/)
+
+The [M-Pin protocol](https://eprint.iacr.org/2002/164)[^second], which is a
multi-factor authentication protocol built upon zero-knowledge proofs, is
widely deployed across cloud infrastructures and in public facing deployments
by the UK Government[^third].
+
+[^second]: [IETF M-Pin Informational
Draft](https://tools.ietf.org/html/draft-scott-mpin-00)
+
+[^third]: [UK Government selects M-Pin protocol based authentication
provider](https://www.computerweekly.com/news/4500260479/Experian-chooses-UK-authentication-startup-for-GovUK-Verify)
+
+Zcash implements their own zero-knowledge proof algorithm named zk-SNARKs
(Zero-Knowledge Succinct Non-Interactive Argument of Knowledge)[^fourth].
zk-SNARKs is used for protecting privacy of transactions of Zcash. Pairings are
a key ingredient for constructing zk-SNARKS.
+
+[^fourth]: [Lindemann, R., "What are zk-SNARKs?", July
2018](https://z.cash/technology/zksnarks.html)
+
+Cloudflare introduced Geo Key Manager[^fifth] to restrict distribution of
customers' private keys to the subset of their data centers. To achieve this
functionality, attribute-based encryption is used and pairings again are a key
building block.
+
+[^fifth]: [Geo Key Manager: How It
Works](https://blog.cloudflare.com/geo-key-manager-how-it-works)
+
+The Trusted Computing Group (TCG) specifies ECDAA (Elliptic Curve Direct
Anonymous Attestation) in the specification of Trusted Platform Module[^sixth].
ECDAA is a protocol for proving the attestation held by a Trusted Platform
Module (TPM) to a verifier without revealing the attestation held by that TPM.
Pairing cryptography is used for constructing ECDAA. FIDO Alliance[^seventh]
and W3C[^eighth] have also published ECDAA algorithms similar to TCG.
+
+[^sixth]: [TPM 2.0 Library Specification", September
2016](https://trustedcomputinggroup.org/resource/tpm-library-specification/)
+
+[^seventh]: [FIDO ECDAA Algorithm - FIDO Alliance Review Draft
02](https://fidoalliance.org/specs/fido-v2.0-rd-20180702/fido-ecdaa-algorithm-v2.0-rd-20180702.html)
+
+[^eighth]: [Web Authentication: An API for accessing Public Key Credentials
Level 1 - W3C Candidate Recommendation](https://www.w3.org/TR/webauthn)
+
+In 2015, NIST [(***the 'post-NSA'
NIST***)](http://www.theregister.co.uk/2014/05/26/congress_divorces_nist_from_nsa/)
goes so far as to recommend standardization of pairing based cryptography in
their publication, [Report on Pairing-Based
Cryptography](http://nvlpubs.nist.gov/nistpubs/jres/120/jres.120.002.pdf).
+
+> "Based on the study, the report suggests an approach for including
pairing-based cryptography schemes in the NIST cryptographic toolkit. As we
have seen, pairing-based cryptography has much to offer. Pairing-based schemes,
such as IBE, provide special properties which cannot be provided through
traditional PKI in a straightforward way. Therefore, pairing-based
cryptographic schemes would make a nice addition to NIST’s cryptographic
toolkit. In particular, we have focused attention on I [...]
+>
+> --- NIST, Report on Pairing-Based Cryptography
+
+## The Move to Post-Quantum
+
+The security of almost all public-key cryptosystems in use today rely on
computational assumptions such as the Integer Factorization (IF) and Discrete
Logarithm (DL) problems as the foundation of their security. These are problems
that today's classical computers cannot solve. In 1994, Shor[^ninth] showed
that both IF and DL problems are easy to solve on a quantum computer, based on
the laws of quantum physics. As a consequence, almost all currently deployed
public-key cryptosystems will [...]
+
+[^ninth]: [Algorithms for quantum computation: discrete logarithms and
factoring](https://pdfs.semanticscholar.org/6902/cb196ec032852ff31cc178ca822a5f67b2f2.pdf)
+
+According to NIST in its Report on Post-Quantum Cryptography[^tenth], "It will
take significant effort to ensure a smooth and secure migration from the
current widely used cryptosystems to their quantum computing resistant
counterparts. Therefore, regardless of whether we can estimate the exact time
of the arrival of the quantum computing era, we must begin now to prepare our
information security systems to be able to resist quantum computing."
+
+[^tenth]: [Report on post-quantum
cryptography](https://nvlpubs.nist.gov/nistpubs/ir/2016/NIST.IR.8105.pdf)
+
+Most experts have a range of quantum computing being strong enough to crack
today's cryptosystems being on the horizon anywhere from five to twenty years.
It should also be stated that quantum computation only speeds up a brute-force
keysearch by a factor of a square root, so any symmetric algorithm can be made
secure against a quantum computer by doubling the key length, i.e., take AES
from 128 bits to 256.
+
+Milagro has begun implementing post-quantum algorithms into its code base,
beginning with the Supersingular Isogeny Key Encapsulation[^eleventh] protocol.
Why?
+
+[^eleventh]: [SIKE](https://sike.org/)
+
+Obviously, data that is transient and that does not retain a long term value
doesn't require a level of protection against a post-quantum adversary. It
becomes an issue when data is retained for the long term. If data is harvested
and stored, and has retained value even after decades, then it should be
protected to a post-quantum degree. In short, you are protecting the data for
the day _WHEN_ a working quantum computer comes online.
+
+---
+
+**It is hoped that Apache Milagro will become a safe, IPR free island of
innovation for cryptographers interested in pairing protocols that deliver much
needed core security infrastructure for the advancement of decentralized
networks and distributed systems.**
+
+**We hope you join us and become part of this journey.**
+
+---
+
+:::note See an error in this documentation?
+Submit a pull request on the development branch of [Milagro Website
Repo](https://github.com/apache/incubator-milagro).
+:::
+
+<!--
+Supported admonition types are: caution, note, important, tip, warning.
+-->
\ No newline at end of file
diff --git a/docs/milagro-protocols.md b/docs/milagro-protocols.md
new file mode 100644
index 0000000..a5289b6
--- /dev/null
+++ b/docs/milagro-protocols.md
@@ -0,0 +1,870 @@
+---
+id: milagro-protocols
+title: Milagro Protocols
+sidebar_label: Milagro Protocols
+---
+The Apache Milagro crypto libraries contain an (almost) overwhelming choice of
algorithms and cryptographic primitives for robust and rapid application
development. This section focuses specifically on a few protocols that are used
extensively as key building blocks within the Milagro Zero-Knowledge Proof
Multi-Factor Authentication (ZKP-MFA) server and clients, and Milagro
Decentralized Trust Authority (D-TA) applications. Both applications implement
these protocols using the Milagro cr [...]
+
+## M-Pin Protocol - Introduction
+
+The genesis of the M-Pin Protocol was first put forward in a research paper by
[Dr. Michael
Scott](https://scholar.google.com/citations?user=GsM-aeEAAAAJ&hl=en) in
2002[^first].
+
+The M-Pin Protocol has been iterated on several times over the years since, to
develop three distinct modes, which will be explored in the following sections.
+
+[^first]: [M-Pin protocol](https://eprint.iacr.org/2002/164)
+
+ As noted in [Milagro Crypto](milagro-crypto.html), the M-Pin Protocol is of
these classifications and exploits the features of:
+* Elliptic Curve Cryptography
+* Pairing Based Cryptography
+* Identity Based Encryption
+* Zero Knowledge Proof
+
+Because of the characteristics that M-Pin inherits from the four techniques
above, the M-Pin Protocol and its variants are able to deliver:
+* Multi-factor authentication (MFA) using Zero Knowledge Proof
+* Authenticated Key Agreement
+* Distribution, or splitting, of Trust Authorities
+* [Subliminal Channel
Communication](https://en.wikipedia.org/wiki/Subliminal_channel)[^second]
+
+[^second]: [The Carnac protocol -- or how to read the contents of a sealed
envelope](https://eprint.iacr.org/2015/576)
+
+The three modes of operation of the M-Pin Protocol are as follows:
+* **M-Pin 1-pass**: Client to server authentication via digital signature,
this mode implements a *non-interactive* zero knowledge proof and is resistant
to [MITM (man in the
middle)](https://en.wikipedia.org/wiki/Man-in-the-middle_attack) attacks.
+* **M-Pin 2-pass**: Client to server authentication via a *interactive* zero
knowledge proof, resistant to
[MITM](https://en.wikipedia.org/wiki/Man-in-the-middle_attack) and [KCI (Key
Compromise Impersonation)](https://kcitls.org) attacks.
+* **M-Pin FULL**: Mutual client to server authentication via a *interactive*
zero knowledge proof, resistant to MITM and KCI attacks and able to drive an
Authenticated [Key
Agreement](https://en.wikipedia.org/wiki/Key-agreement_protocol) between client
and server, resulting in 128 bit shared secret key.
+
+Note that the M-Pin Full Authenticated Key Agreement possesses the quality of
[perfect forward secrecy (PFS)](https://en.wikipedia.org/wiki/Forward_secrecy),
meaning, even if the client and server long term keys are compromised, the past
session keys (used to encrypt TLS traffic, for example) are not compromised.
+
+## Chow-Choo Protocol - Introduction
+
+The Chow-Choo Protocol was developed by Sherman S.M. Chow and Kim-Kwang
Raymond Choo and published in 2007 via a research paper titled Strongly-Secure
Identity-based Key Agreement[^third]. The Chow-Choo Protocol can be
technically described as an identity-based key agreement protocol.
+
+[^third]: [Strongly-Secure Identity-based Key Agreement and Anonymous
Extension](https://eprint.iacr.org/2007/018.pdf)
+
+The Chow-Choo Protocol is of these classifications and exploits the features
of:
+* Elliptic Curve Cryptography
+* Pairing Based Cryptography
+* Identity Based Encryption
+
+Because of the characteristics that Chow-Choo inherits from the three
techniques above, the Chow-Choo Protocol can deliver:
+* Authenticated Key Agreement
+* Distribution, or splitting, of Trust Authorities
+
+Note that the Chow-Choo Protocol is not a Zero Knowledge Proof protocol.
+
+## BLS Signatures - Introduction
+
+The BLS signature (Boneh-Lynn-Schacham) scheme[^fourth] uses a bilinear
pairing for verification, and signatures are elements of an elliptic curve
group. Working in an elliptic curve group provides some defense against index
calculus attacks (with the caveat that such attacks are still possible in the
target group \\( G_{T} \\) of the pairing), allowing shorter signatures than
other systems for similar levels of security.
+
+[^fourth]: [Short Signatures from the Weil
Pairing](https://www.iacr.org/archive/asiacrypt2001/22480516.pdf)
+
+BLS signatures have become the subject of much work as they are seen as being
a possible way forward to solve privacy issues within cryptocurrencies through
a process of signature aggregation. Apache Milagro uses signature aggregation
and key splitting, and further aggregation of signatures from those split keys,
as a key component of the Milagro Custody Node digital asset safekeeping
protocol.
+
+## Supersingular Isogeny Key Encapsulation - Introduction
+
+Supersingular isogeny Diffie–Hellman key exchange (SIDH) and the key
encapsulation protocol, SIKE[^fifth] (derived from SIDH), are post-quantum
cryptographic algorithms used to establish a secret key between two parties
over an otherwise insecure communications channel. SIKE boasts one of the
smallest key sizes of all post-quantum key encapsulations; with compression,
SIKE uses 2688-bit public keys at a 128-bit quantum security level.
+
+[^fifth]: [Supersingular isogeny key encapsulation - NIST
Submission](https://sike.org/)
+
+SIKE also distinguishes itself from similar systems such as NTRU and Ring-LWE
by supporting perfect forward secrecy, a property that prevents compromised
long-term keys from compromising the confidentiality of old communication
sessions. These properties make SIKE a natural candidate to replace
Diffie–Hellman (DHE and elliptic curve Diffie–Hellman (ECDHE), which are widely
used in Internet communication.
+
+Since it is the only post-quantum cryptography protocol which is constructed
on elliptic curves, hybrid cryptography protocols can be derived from SIKE and
classical elliptic curve cryptography (ECC) to make the transition towards
post-quantum cryptography more convenient and practical.
+
+Milagro Custody Node implements SIKE for key encapsulation within Milagro's
encrypted envelope format.
+
+---
+
+Protocols | Use Cases
+-------|-------
+M-Pin 1-Pass | Digital signature authentication in battery or bandwidth
constrained environments such as IoT devices, embedded applications and mobile
apps. <br>This should be considered the default implementation for client to
server authentication suitable for almost all use cases.
+M-Pin 1-Pass + <br>M-Pin 2-Pass | Digital signature and client to server
authentication in smartphones apps, desktop browsers and software applications.
+M-Pin 2-Pass | Client to server authentication in smartphone apps, desktop
browsers and software applications.
+M-Pin FULL | Mutual client and server authentication with authenticated key
agreement for use in smartphone apps, hardware and software applications.
<br>Authenticated Key Agreement with PFS can be used as the basis for TLS
sessions between clients and servers.
+Chow-Choo | Mutual peer to peer authentication with authenticated key
agreement for use in smartphone apps, hardware and software applications.
<br>Authenticated Key Agreement with PFS can be used as the basis for TLS
sessions between clients and servers and peer to peer.
+BLS Signing + <br>Key Splitting + <br>Signature Aggregation | A simple
approach for splitting keys and aggregating many BLS signatures (from the
shares of keys acting as signing keys) on a common message. Public keys are not
needed for verifying the multi-signature. <br>An important property of the
construction is that the scheme is secure against a rogue public-key attack
without requiring users to prove knowledge of their secret keys.
+SIKE (Key Encapsulation) | SIKE is a family of post-quantum key encapsulation
mechanisms based on the Supersingular Isogeny Diffie-Hellman (SIDH) key
exchange protocol. <br>The algorithms use arithmetic operations on elliptic
curves defined over finite fields and compute maps, so-called isogenies,
between such curves. <br>SIKE can also delivery perfect forward secrecy.
+
+
+---
+
+## Protocols In Depth
+
+### M-Pin 1-Pass
+
+As opposed to Chow-Choo, which can be used in a client to server as well as a
peer to peer setting, M-Pin is strictly a client-server protocol.
+
+To embellish the security of the client-server protocol, it is important that
client and server secrets should be kept distinct.
+
+A simple way to do this is to exploit the structure of a Type-3 pairing and
put client secrets in \\( G_1 \\) and the server secret in \\( G_2 \\) as
previously noted in the preceding section.
+
+For a Type-3 pairing there is assumed to be no computable isomorphism between
these groups, even though both are of the same order.
+
+In the original implementation, the client was supplied with a challenge by
the server as part of the second step within the protocol, after the first step
whereby the client announced her identity to the server.
+
+In a later proposal, it was realised that an M-Pin 1-Pass Protocol could be
obtained if the client itself derived the challenge as \\( y \\) as \\(
y=H(U|T) \\) where \\( T \\) is a time-stamp transmitted by the Client along
her claimed identity, \\( U \\) and \\( V \\).
+
+The protocol could then be reduced in an obvious way to a secure 1-pass
protocol. However, this assumes that the Server checks the accuracy of the
time-stamp before completing the protocol.
+
+This all works thanks to the pairing function \\( e(.,.) \\) and its
remarkable bilinearity property \\( e(aP,Q) = e(P,aQ) = e(P,Q)^{a} \\).
+
+---
+
+|Alice - identity \\( ID_a \\)|Server|
+|:----------------------:|:----------------------:|
+|Generates random \\( x<q \\) | |
+| \\( A=H(ID_a) \\)||
+| \\( U=x{A} \\)||
+| \\( ID_a \\), \\( U~~ \\) ||
+| \\( y=H(U \\) | \\( T) \\) ||
+| \\( V=-(x+y){((s-\alpha)A+\alpha A)} \rightarrow \\)||
+| |\\( A=H(ID_a) \\)|
+| |\\( g=e(V,Q).e(U+yA,sQ) \\)|
+| |if \\( g \ne 1 \\), reject the connection|
+<figure>
+ <caption><strong>Figure 1.</strong> M-Pin 1-Pass</caption>
+</figure>
+---
+
+### M-Pin 2-Pass
+
+As you can see below in Fig 2., M-Pin in the two pass operation operates in a
challenge (from the Server) to client, who responds to challenge. This
implementation obviates the any risk of Key Compromise Impersonation attack
vector, at the cost of of a full roundtrip.
+
+---
+|Alice - identity \\( ID_a \\)|Server|
+|:----------------------:|:----------------------:|
+|Generates random \\( x<q \\)|Generates random \\( y<q \\)|
+|\\( A=H(ID_a) \\)||
+|\\( U=x{A} \\)||
+|\\( ID_a$, $U~~ \rightarrow \\)||
+| |\\( \leftarrow y \\)|
+|\\( V=-(x+y){((s-\alpha)A+\alpha A)} \rightarrow \\)||
+| |\\( A=H(ID_a) \\) |
+| |\\( g=e(V,Q).e(U+yA,sQ) \\)|
+| |if \\( g \ne 1 \\), reject the connection|
+
+<figure>
+ <caption><strong>Figure 2.</strong> M-Pin 2-Pass</caption>
+</figure>
+---
+
+### M-Pin FULL
+
+This more elaborate protocol not only replaces Username/Password, but replaces
the functionality of digital certificates being utilised to drive key agreement
for TLS or VPN protocols as well.
+
+Our starting point is the M-Pin protocol as described above.
+
+The idea is to run it first (to authenticate the client to the server), and
then proceed to authenticate the server to the client via an authenticated key
exchange, which also establishes the agreed key of 128 bits.
+
+The first thing to note is that both the client and the server can already
calculate a mutual authenticated encryption key!
+
+This protocol requires another general hash function \\( H_g(.) \\) which
serializes, and hashes its input to a 256-bit value. Both sides can then
extract a key from this value \\( K \\).
+
+It is left as a simple exercise for the reader to confirm that both client and
server end up with the same key.
+
+Note that since the first part of the protocol is just the original M-Pin
protocol, all of its features and extensions still apply.
+
+---
+
+|Alice - identity \\( ID_a \\)|Server|
+|:----------------------:|:----------------------:|
+|Generates random \\( x<q \\)|Generates random \\( y<q \\)|
+|\\( A=H(ID_a) \\)||
+|\\( U=x{A} \\)||
+|\\( ID_a$, $U~~ \rightarrow \\)||
+| |\\( \leftarrow y \\)|
+|\\( V=-(x+y){((s-\alpha)A+\alpha A)} \rightarrow \\)||
+| |\\( A=H(ID_a) \\) |
+| |\\( g=e(V,Q).e(U+yA,sQ) \\)|
+| |if \\( g \ne 1 \\), reject the connection|
+| \\( R=r{A} \rightarrow \\) | \\( \leftarrow W=w{A} \\) |
+| \\( h=H(A,U,y,V,R,W) \\) | \\( h=H(A,U,y,V,R,W) \\) |
+| \\( K=H_g((g_1.{g_2}^\alpha)^{r+h} \ \\) | \\( x{W}) \\) | \\(
K=H_g(e(R+hA,sQ) \ \\) | \\( w{U}) \\) |
+<figure>
+ <caption><strong>Figure 3.</strong> M-Pin FULL</caption>
+</figure>
+
+---
+
+Note that the transmission of \\( R \\) from the client to the server can be
done at the same time as \\( V \\) is transmitted, and the transmission of \\(
W \\) from the server to the client can be done at the same time as \\( y \\)
is transmitted, to avoid introducing any extra flows into the protocol.
+
+### Chow-Choo Protocol
+
+As initially proposed, the Chow-Choo Protocol was based on a type-1 pairing.
Note that in the Milagro framework, the Chow-Choo Protocol is made to work in a
Type-3 setting.
+
+Pairings are usually written as functions of the form \\( g=e(A,B) \\), where
\\( A \in G_1 \\), \\( g \in G_T \\), and for a Type-1 pairing \\( B \in G_1
\\) and for Type-3 \\( B \in G_2 \\).
+
+Consider now an application of this protocol to an imagined Internet of Things
(IoT) setting.
+
+Each 'Thing' is issued with a serial number and its own Chow-Choo key (which
can double as an M-Pin Key) based on that serial number as an identity.
+
+These keys may be embedded at the time of manufacture, by the manufacturer
acting as a naturally trusted authority.
+
+When a Thing needs to communicate with another Thing, an action which requires
knowing only the identity of the other, both parties can activate the Chow-Choo
Protocol to calculate the same key to encrypt their communication.
+
+For both sending and receiving, Alice is issued with \\( sA_1 \\) and \\( sA_2
\\), where \\( A_1=H_1 \\) and \\( A_2=H_2 \\) both in the \\( ID = Alice \\).
+
+Similarly Bob is issued with \\( sB_1 \\) and \\( sB_2 \\). Now if Alice
initiates and Bob responds, Alice calculates the key as \\( e(sA_1,B_2) \\) and
Bob can calculate the same key as \\( e(A_1,sB_2) \\), where by convention the
initiator uses their *sender* key and the responder uses their *receiver* key.
+
+One thing we can exploit -- in any communication context there is an initiator
and a responder, or a *sender* and *receiver*, if you will.
+
+In the above example, Alice and Bob both were issued *sender* and *receiver*
keys respectively, as this describes where they can appear in the pairing.
+
+An obvious advantage is to issue each Thing with two keys, one in \\( G_1 \\)
and the other in \\( G_2 \\), **if** the Thing is approved to send and receive.
+
+However, the capability exists to cryptographically bound Things to only
receiving information, or only sending information, based upon whether or not a
Thing has been issued a sender and / or a receiver key.
+
+This capability is exploited in the Milagro framework to enable peer to peer
authenticated key agreement.
+
+---
+
+<!--- This is the Chow Choo protocol in a Mathml table / frame because
redering in Math LaTex equations exposes a bug in MathJax. It's just one
equation that has this bug! --->
+<figure>
+ <html>
+ <math xmlns="http://www.w3.org/1998/Math/MathML"; display='block'>
+ <mtable frame="solid" rowlines="solid"
rowalign="center" mathbackground="white">
+ <mstyle mathsize='.85em'>
+ <mtr>
+ <mtd>
+ <mspace width="0.1em" />
+ </mtd>
+ <mtd columnalign="left">
+ <mtable class="m-matrix">
+ <mtr>
+ <mtd>
+ <mtext>SENDER</mtext>
+ </mtd>
+ <mtd>
+ <mtext>RECEIVER</mtext>
+ </mtd>
+ </mtr>
+ <mtr>
+ <mtd>
+ <mi>x</mi>
+ <mo>∈</mo>
+ <msubsup>
+
<mi>ℤ</mi>
+ <mi>q</mi>
+ <mo>*</mo>
+ </msubsup>
+ </mtd>
+ <mtd>
+ </mtd>
+ </mtr>
+ <mtr>
+ <mtd>
+ <mi>A</mi>
+ <mi>G</mi>
+ <mn>1</mn>
+ <mo>:</mo>
+ <mo>=</mo>
+ <msub>
+ <mi>H</mi>
+ <mn>1</mn>
+ </msub>
+ <mrow>
+ <mo
form="prefix">(</mo>
+ <mi>I</mi>
+
<mo>ⅆ</mo>
+ <mi>A</mi>
+ <mo
form="postfix">)</mo>
+ </mrow>
+ </mtd>
+ <mtd>
+ </mtd>
+ </mtr>
+ <mtr>
+ <mtd>
+ <mi>P</mi>
+ <mi>a</mi>
+ <msub>
+ <mi>G</mi>
+ <mn>1</mn>
+ </msub>
+ <mo>:</mo>
+ <mo>=</mo>
+ <mi>x</mi>
+ <mo>⋅</mo>
+ <mi>A</mi>
+ <msub>
+ <mi>G</mi>
+ <mn>1</mn>
+ </msub>
+ </mtd>
+ <mtd>
+ </mtd>
+ </mtr>
+ <mtr>
+ <mtd>
+ <mi>I</mi>
+ <mo>ⅆ</mo>
+ <mi>A</mi>
+ <mo>,</mo>
+ <mi>P</mi>
+ <mi>a</mi>
+ <msub>
+ <mi>G</mi>
+ <mn>1</mn>
+ </msub>
+ <mo>⟶</mo>
+ </mtd>
+ <mtd>
+ </mtd>
+ </mtr>
+ <mtr>
+ <mtd>
+ </mtd>
+ <mtd>
+ <mi>y</mi>
+ <mo>,</mo>
+ <mi>w</mi>
+ <mo>∈</mo>
+ <msubsup>
+
<mi>ℤ</mi>
+ <mi>q</mi>
+ <mo>*</mo>
+ </msubsup>
+ </mtd>
+ </mtr>
+ <mtr>
+ <mtd>
+ </mtd>
+ <mtd>
+ <mi>A</mi>
+ <msub>
+ <mi>G</mi>
+ <mn>1</mn>
+ </msub>
+ <mo>:</mo>
+ <mo>=</mo>
+ <msub>
+ <mi>H</mi>
+ <mn>1</mn>
+ </msub>
+ <mrow>
+ <mo
form="prefix">(</mo>
+ <mi>I</mi>
+
<mo>ⅆ</mo>
+ <mi>A</mi>
+ <mo
form="postfix">)</mo>
+ </mrow>
+ </mtd>
+ </mtr>
+ <mtr>
+ <mtd>
+ </mtd>
+ <mtd>
+ <mi>B</mi>
+ <msub>
+ <mi>G</mi>
+ <mn>2</mn>
+ </msub>
+ <mo>:</mo>
+ <mo>=</mo>
+ <msub>
+ <mi>H</mi>
+ <mn>2</mn>
+ </msub>
+ <mrow>
+ <mo
form="prefix">(</mo>
+ <mi>I</mi>
+
<mo>ⅆ</mo>
+ <mi>B</mi>
+ <mo
form="postfix">)</mo>
+ </mrow>
+ </mtd>
+ </mtr>
+ <mtr>
+ <mtd>
+ </mtd>
+ <mtd>
+ <mi>P</mi>
+ <mi>b</mi>
+ <msub>
+ <mi>G</mi>
+ <mn>2</mn>
+ </msub>
+ <mo>:</mo>
+ <mo>=</mo>
+ <mi>y</mi>
+ <mo>⋅</mo>
+ <mi>B</mi>
+ <msub>
+ <mi>G</mi>
+ <mn>2</mn>
+ </msub>
+ </mtd>
+ </mtr>
+ <mtr>
+ <mtd>
+ </mtd>
+ <mtd>
+ <mi>P</mi>
+ <mi>g</mi>
+ <msub>
+ <mi>G</mi>
+ <mn>1</mn>
+ </msub>
+ <mo>:</mo>
+ <mo>=</mo>
+ <mi>w</mi>
+ <mo>⋅</mo>
+ <mi>A</mi>
+ <msub>
+ <mi>G</mi>
+ <mn>1</mn>
+ </msub>
+ </mtd>
+ </mtr>
+ <mtr>
+ <mtd>
+ </mtd>
+ <mtd>
+ <mtext>pia</mtext>
+ <mo>:</mo>
+ <mo>=</mo>
+ <msub>
+ <mi>H</mi>
+ <mi>q</mi>
+ </msub>
+ <mrow>
+ <mo
form="prefix">(</mo>
+ <mi>P</mi>
+ <mi>a</mi>
+ <msub>
+
<mi>G</mi>
+
<mn>1</mn>
+ </msub>
+
<mo>‖</mo>
+ <mi>P</mi>
+ <mi>b</mi>
+ <msub>
+
<mi>G</mi>
+
<mn>2</mn>
+ </msub>
+
<mo>‖</mo>
+ <mi>P</mi>
+ <mi>g</mi>
+ <msub>
+
<mi>G</mi>
+
<mn>1</mn>
+ </msub>
+
<mo>‖</mo>
+ <mi>I</mi>
+
<mo>ⅆ</mo>
+ <mi>B</mi>
+ <mo
form="postfix">)</mo>
+ </mrow>
+ </mtd>
+ </mtr>
+ <mtr>
+ <mtd>
+ </mtd>
+ <mtd>
+ <mtext>pib</mtext>
+ <mo>:</mo>
+ <mo>=</mo>
+ <msub>
+ <mi>H</mi>
+ <mi>q</mi>
+ </msub>
+ <mrow>
+ <mo
form="prefix">(</mo>
+ <mi>P</mi>
+ <mi>b</mi>
+ <msub>
+
<mi>G</mi>
+
<mn>2</mn>
+ </msub>
+
<mo>‖</mo>
+ <mi>P</mi>
+ <mi>a</mi>
+ <msub>
+
<mi>G</mi>
+
<mn>1</mn>
+ </msub>
+
<mo>‖</mo>
+ <mi>P</mi>
+ <mi>g</mi>
+ <msub>
+
<mi>G</mi>
+
<mn>1</mn>
+ </msub>
+
<mo>‖</mo>
+ <mi>I</mi>
+
<mo>ⅆ</mo>
+ <mi>A</mi>
+ <mo
form="postfix">)</mo>
+ </mrow>
+ </mtd>
+ </mtr>
+ <mtr>
+ <mtd>
+ </mtd>
+ <mtd>
+ <mi>k</mi>
+ <mo>:</mo>
+ <mo>=</mo>
+ <mi>e</mi>
+ <mrow>
+ <mo
form="prefix">(</mo>
+
<mtext>pia</mtext>
+
<mo>⋅</mo>
+ <mi>A</mi>
+ <msub>
+
<mi>G</mi>
+
<mn>1</mn>
+ </msub>
+ <mo>+</mo>
+ <mi>P</mi>
+ <mi>a</mi>
+ <msub>
+
<mi>G</mi>
+
<mn>1</mn>
+ </msub>
+ <mo>,</mo>
+ <mo
form="prefix">(</mo>
+ <mi>y</mi>
+ <mo>+</mo>
+
<mtext>pib</mtext>
+ <mo
form="postfix">)</mo>
+
<mo>⋯</mo>
+
<mo>⋅</mo>
+ <mi>B</mi>
+ <msub>
+
<mi>G</mi>
+
<mn>2</mn>
+ </msub>
+ <mo
form="postfix">)</mo>
+ </mrow>
+ </mtd>
+ </mtr>
+ <mtr>
+ <mtd>
+ </mtd>
+ <mtd>
+ <mi>K</mi>
+ <mo>:</mo>
+ <mo>=</mo>
+ <mi>H</mi>
+ <mrow>
+ <mo
form="prefix">(</mo>
+ <mi>k</mi>
+ <mo>,</mo>
+ <mi>w</mi>
+
<mo>⋅</mo>
+ <mi>P</mi>
+ <mi>a</mi>
+ <msub>
+
<mi>G</mi>
+
<mn>1</mn>
+ </msub>
+ <mo
form="postfix">)</mo>
+ </mrow>
+ </mtd>
+ </mtr>
+ <mtr>
+ <mtd>
+ </mtd>
+ <mtd>
+ <mo>⟵</mo>
+ <mi>I</mi>
+ <mo>ⅆ</mo>
+ <mi>B</mi>
+ <mo>,</mo>
+ <mi>P</mi>
+ <mi>g</mi>
+ <msub>
+ <mi>G</mi>
+ <mn>1</mn>
+ </msub>
+ <mo>,</mo>
+ <mi>P</mi>
+ <mi>b</mi>
+ <msub>
+ <mi>G</mi>
+ <mn>2</mn>
+ </msub>
+ </mtd>
+ </mtr>
+ <mtr>
+ <mtd>
+ <mi>B</mi>
+ <msub>
+ <mi>G</mi>
+ <mn>2</mn>
+ </msub>
+ <mo>:</mo>
+ <mo>=</mo>
+ <msub>
+ <mi>H</mi>
+ <mn>2</mn>
+ </msub>
+ <mrow>
+ <mo
form="prefix">(</mo>
+ <mi>I</mi>
+
<mo>ⅆ</mo>
+ <mi>B</mi>
+ <mo
form="postfix">)</mo>
+ </mrow>
+ </mtd>
+ <mtd>
+ </mtd>
+ </mtr>
+ <mtr>
+ <mtd>
+ <mtext>pia</mtext>
+ <mo>:</mo>
+ <mo>=</mo>
+ <msub>
+ <mi>H</mi>
+ <mi>q</mi>
+ </msub>
+ <mrow>
+ <mo
form="prefix">(</mo>
+ <mi>P</mi>
+ <mi>a</mi>
+ <msub>
+
<mi>G</mi>
+
<mn>1</mn>
+ </msub>
+
<mo>‖</mo>
+ <mi>P</mi>
+ <mi>b</mi>
+ <msub>
+
<mi>G</mi>
+
<mn>2</mn>
+ </msub>
+
<mo>‖</mo>
+ <mi>P</mi>
+ <mi>g</mi>
+ <msub>
+
<mi>G</mi>
+
<mn>1</mn>
+ </msub>
+
<mo>‖</mo>
+ <mi>I</mi>
+
<mo>ⅆ</mo>
+ <mi>B</mi>
+ <mo
form="postfix">)</mo>
+ </mrow>
+ </mtd>
+ <mtd>
+ </mtd>
+ </mtr>
+ <mtr>
+ <mtd>
+ <mtext>pib</mtext>
+ <mo>:</mo>
+ <mo>=</mo>
+ <msub>
+ <mi>H</mi>
+ <mi>q</mi>
+ </msub>
+ <mrow>
+ <mo
form="prefix">(</mo>
+ <mi>P</mi>
+ <mi>b</mi>
+ <msub>
+
<mi>G</mi>
+
<mn>2</mn>
+ </msub>
+
<mo>‖</mo>
+ <mi>P</mi>
+ <mi>a</mi>
+ <msub>
+
<mi>G</mi>
+
<mn>1</mn>
+ </msub>
+
<mo>‖</mo>
+ <mi>P</mi>
+ <mi>g</mi>
+ <msub>
+
<mi>G</mi>
+
<mn>1</mn>
+ </msub>
+
<mo>‖</mo>
+ <mi>I</mi>
+
<mo>ⅆ</mo>
+ <mi>A</mi>
+ <mo
form="postfix">)</mo>
+ </mrow>
+ </mtd>
+ <mtd>
+ </mtd>
+ </mtr>
+ <mtr>
+ <mtd>
+ <mi>k</mi>
+ <mo>:</mo>
+ <mo>=</mo>
+ <mi>e</mi>
+ <mrow>
+ <mo
form="prefix">(</mo>
+ <mo
form="prefix">(</mo>
+ <mi>x</mi>
+ <mo>+</mo>
+ <mi>p</mi>
+ <mi>i</mi>
+ <mi>a</mi>
+ <mo
form="postfix">)</mo>
+
<mo>⋯</mo>
+
<mo>⋅</mo>
+ <mi>A</mi>
+ <msub>
+
<mi>G</mi>
+
<mn>1</mn>
+ </msub>
+ <mo>,</mo>
+
<mtext>pib</mtext>
+
<mo>⋅</mo>
+ <mi>B</mi>
+ <msub>
+
<mi>G</mi>
+
<mn>2</mn>
+ </msub>
+ <mo>+</mo>
+ <mi>P</mi>
+ <mi>b</mi>
+ <msub>
+
<mi>G</mi>
+
<mn>2</mn>
+ </msub>
+ <mo
form="postfix">)</mo>
+ </mrow>
+ </mtd>
+ <mtd>
+ </mtd>
+ </mtr>
+ <mtr>
+ <mtd>
+ <mi>K</mi>
+ <mo>:</mo>
+ <mo>=</mo>
+ <mi>H</mi>
+ <mrow>
+ <mo
form="prefix">(</mo>
+ <mi>k</mi>
+ <mo>,</mo>
+ <mi>x</mi>
+
<mo>⋅</mo>
+ <mi>P</mi>
+ <mi>g</mi>
+ <msub>
+
<mi>G</mi>
+
<mn>1</mn>
+ </msub>
+ <mo
form="postfix">)</mo>
+ </mrow>
+ </mtd>
+ <mtd>
+ </mtd>
+ </mtr>
+ </mtable>
+ </mtd>
+ </mtr>
+ </mtable>
+ </math>
+ </html>
+</figure>
+<figure>
+ <caption><strong>Figure 4.</strong> Chow-Choo Protocol</caption>
+</figure>
+
+---
+
+**Notes on Chow-Choo Protocol:**
+
+* \\( G_1 \\): a \\( r \\)-order cyclic subgroup of \\( E(F_p) \\).
+* \\( G_2 \\): a subgroup of \\( E(F_{p^k}) \\), where \\( k \\) is the
embedding degree of the Curve.
+* \\( H1 \\): Maps string value to a point on the curve in \\( G_1 \\).
+* \\( H2 \\): Maps string value to a point on the curve in \\( G_2 \\).
+* \\( Hq \\): Hashes inputs to an integer modulo the curve order \\( q
\\).When run in the simple SIDH
+* H(): Hash function.
+* \\( || \\): denotes the concatenation of messages.
+
+---
+
+### Secret Revocation
+
+We introduce Time Permits to handle the revocation issue. Normally in
Identity-Based Encryption the problem of client revocation is solved by
date-stamping identities so that the private key issued for an identity becomes
useless once the time period expires. Now a new private key must be issued, and
we will simply not issue one to a revoked client.
+
+Milagro achieves a much more immediate revocation capability through the use
of Time Permits. The D-TA that is controlled by the application owner is
envisioned to be the controlling D-TA to issue Time Permits at the point where
a client needs to authenticate to a server, or create an authenticated key
agreement between client and server or peer to peer.
+
+The idea is that the server includes an explicitly described time slot in its
construction of Alice's hashed identity. Unless Alice has a corresponding "Time
permit" for the same time slot, she cannot complete the protocol.
+
+In the protocol above we instead calculate \\( H(ID_a) + H_T(T_i|ID_a) \\) on
both sides of the protocol where \\( T_i \\) is a textual description of the
\\( i \\)-th time slot and \\( H_T(.) \\) is a hash function distinct from \\(
H(.) \\).
+
+For the protocol to work correctly Alice must be issued by the Trusted
Authority with a permit \\( s.H_T(T_i|ID_a) \\) which gets added to her
combined PIN-plus-token secret \\( s.H(ID_a) \\).
+
+Observe that the permit is of no use to any other party, and hence can be
issued publicly, uploaded to a public cloud data store (AWS S3), or delivered
via the server directly.
+
+A proof of security for this idea in the context of Boneh and Franklin IBE can
be found in Tseng[^ninth] et al.
+
+[^ninth]: [A brief review of revocable ID-based public key
cryptosystem](https://reader.elsevier.com/reader/sd/pii/S2213020915000592?token=5C2E08C17803B9549FB79F3A91A1ED2382360D3E840087C8C065BD06EFCABB55C4A5A300566388A2920786DCC63E631E)
+
+___
+
+### BLS Subgroup Multi-Signatures
+
+Dan Boneh, Ben Lynn and Hovav Schacham introduced their paper entitled "Short
Signatures from the Weil Pairing" in 2001[^fourth]. The paper described a short
signature scheme based on the computational Diffie-Hellman assumption on
certain elliptic and hyper-elliptic curves.
+
+In a simple instantiation, given a secret key \\( sk \\), a public key \\( p
k=g^{S k} \\), a message \\( m \\), a hashing-into-the-curve function \\( H
\\), and a bilinear pairing \\( e \\):
+
+* Key Generation: \\( sk \\) is a random integer over the field, \\( p k=g^{S
k} \\)
+* Signature: \\( S=H(m)^{s k} \\)
+* Verify: \\( e(H(m), p k)=e(S, g) \\)
+
+Biliniarity is on display as the signature
+
+$$ \begin{array}{c}{e(H(m), p k)=e\left(H(m), g^{s k}\right)=e(H(m), g)^{s
k}=} \\ {=e\left(H(m)^{s k}, g\right)=e(S, g)}\end{array} $$
+
+but is also unique and deterministic, something missing from ECDSA.
+
+In June of 2018 Dan Boneh, Manu Drijvers and Gregory Neven released research
that constructs the first practical, short accountable-subgroup multi-signature
(ASM) scheme based on BLS signatures[^sixth].
+
+[^sixth]: [Compact Multi-Signatures for Smaller
Blockchains](https://eprint.iacr.org/2018/483)
+
+An ASM scheme enables any subset \\( S \\) of a set of \\( n \\) parties to
sign a message \\( m \\) so that a valid signature discloses which subset
generated the signature (hence the subset \\( S \\) is accountable for signing
\\( m \\)).
+
+In addition to the ASM scheme, Milagro exploits a unique property of BLS
signatures: Signing Keys can be split using Shamir's Secret Sharing[^seventh]
in which the 'shares' of the keys, when distributed to signers, themselves
become signing keys. By using a 'key splitter' and 'signature aggregator' role
who also performs the Shamir Secret Sharing (SSS) dealer function, several
benefits emerge.
+
+Thresholds can be set on the distribution of key shares just as in a normal
SSS routine. So once the shares of the original signing key are distributed,
the original signing key can be securely deleted, and is never re-created
again. Instead, signatures derived from the shares of the original signing key
are created. Again, the properties of BLS enable these shares of signature keys
to be themselves used a signature keys. The object of the exercise is for the
signature aggregator, who is [...]
+
+In other words, if the aggregator takes m-of-n of these signature shares, and
perform the same polynomial interpolation as one would usually do with the
secret shares, you’ll recover a complete signature which is identical to what
would have been created if the original complete private key would have been
used.
+
+[^seventh]: [How to Share a
Secret](https://cs.jhu.edu/~sdoshi/crypto/papers/shamirturing.pdf)
+
+In this context, signing is a single round protocol and is non-interactive.
+
+---
+
+### Supersingular Isogeny Key Encapsulation (SIKE)
+
+A key encapsulation mechanism (KEM) is a set of three algorithms.
+
+* key generation (KeyGen)
+* encapsulation (Encaps)
+* decapsulation (Decaps)
+
+and a defined key space, where
+
+* KeyGen(): returns a public and a secret key \\( (pk, sk) \\).
+* Encaps\\( (pk) \\): takes pk as input and outputs ciphertext \\( c \\) and a
key \\( K \\) from the key space.
+* Decaps\\( (sk, c) \\): takes \\( sk \\) and \\( c \\) as input, and returns
a key \\( K \\) or ERROR. \\( K \\) is called the session key.
+
+
+SIKE uses Hofheinz transformation on SIDH to achieve CCA security. Let \\(
p=2^{e_{A}} 3^{e_{3}}-1 \\), and let \\( E \\) be a supersingular elliptic
curve defined over a field of characteristic \\( p \\). \\( E \\) can also be
defined over \\( \mathbb{F}_{p^{2}} \\) up to its isomorphism. An isogeny \\(
\phi : E \rightarrow E^{\prime} \\) is a non-constant map from \\( E \\) to \\(
E^{\prime} \\) which translates the identity into the identity.
+
+An isogeny map is defined by its degree and kernel. The degree of an isogeny
is its degree as morphism. An isogeny with degree \\( \ell \\) map is called
\\( \ell \\)-isogeny. Let \\( G \\) be a subgroup of points on \\( E \\) which
contains \\( \ell \\) + 1 cyclic subgroups of order \\( \ell \\). This subgroup
is the torsion group \\( E[\ell] \\) and each element of this group is
corresponding to an isogeny of degree \\( \ell \\); accordingly, an isogeny
also can be identified by \\( G [...]
+
+This section provides a brief presentation of the SIKE protocol. We refer
readers to [^eighth] and [^fifth] for more detailed explanation of the
supersignular isogeny problem and the base key-exchange protocol which the SIKE
is constructed upon.
+
+[^eighth]: [Towards quantum-resistant cryptosystems from supersingular
elliptic curve isogenies](https://eprint.iacr.org/2011/506.pdf)
+---
+
+:::note See an error in this documentation?
+Submit a pull request on the development branch of [Milagro Website
Repo](https://github.com/apache/incubator-milagro).
+:::
+
+<!--
+Supported admonition types are: caution, note, important, tip, warning.
+-->
\ No newline at end of file
diff --git a/docs/zkp-mfa-api.md b/docs/zkp-mfa-api.md
new file mode 100644
index 0000000..e7eec69
--- /dev/null
+++ b/docs/zkp-mfa-api.md
@@ -0,0 +1,14 @@
+---
+id: zkp-mfa-api
+title: Zero Knowledge Proof MFA API
+sidebar_label: ZKP-MFA API
+---
+
+:::tip WE NEED HELP DOCUMENTING!
+Interested in becoming a contributor? Milagro is looking for you.
+[CONTRIBUTOR'S GUIDE](/docs/contributor-guide.html).
+:::
+
+<!--
+Supported admonition types are: caution, note, important, tip, warning.
+-->
\ No newline at end of file
diff --git a/docs/zkp-mfa-overview.md b/docs/zkp-mfa-overview.md
new file mode 100644
index 0000000..9e28074
--- /dev/null
+++ b/docs/zkp-mfa-overview.md
@@ -0,0 +1,14 @@
+---
+id: zkp-mfa-overview
+title: Zero Knowledge Proof MFA Overview
+sidebar_label: ZKP-MFA Overview
+---
+
+:::tip WE NEED HELP DOCUMENTING!
+Interested in becoming a contributor? Milagro is looking for you.
+[CONTRIBUTOR'S GUIDE](/docs/contributor-guide.html).
+:::
+
+<!--
+Supported admonition types are: caution, note, important, tip, warning.
+-->
\ No newline at end of file
