Commit 405ec6c7 authored by juga's avatar juga
Browse files

Add documentation about GNS

parent 7c340ee1

docs/source/_static/mixnet_gns_components.svg

0 → 100644
+62 −0
Original line number Diff line number Diff line 
<?xml version="1.0" encoding="UTF-8" standalone="no"?><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" contentScriptType="application/ecmascript" contentStyleType="text/css" height="416px" preserveAspectRatio="none" style="width:1304px;height:416px;" version="1.1" viewBox="0 0 1304 416" width="1304px" zoomAndPan="magnify"><defs><filter height="300%" id="f8trcps4qzdke" width="300%" x="-1" y="-1"><feGaussianBlur result="blurOut" stdDeviation="2.0"/><feColorMatrix in="blurOut" result="blurOut2" type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 .4 0"/><feOffset dx="4.0" dy="4.0" in="blurOut2" result="blurOut3"/><feBlend in="SourceGraphic" in2="blurOut3" mode="normal"/></filter></defs><g><!--MD5=[3daa8d6928fc49ee032578c2e238d80e]

entity Authority--><rect fill="#FEFECE" filter="url(#f8trcps4qzdke)" height="160.375" style="stroke: #A80036; stroke-width: 1.5;" width="560" x="306" y="8"/><rect fill="#FEFECE" height="10" style="stroke: #A80036; stroke-width: 1.5;" width="15" x="846" y="13"/><rect fill="#FEFECE" height="2" style="stroke: #A80036; stroke-width: 1.5;" width="4" x="844" y="15"/><rect fill="#FEFECE" height="2" style="stroke: #A80036; stroke-width: 1.5;" width="4" x="844" y="19"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="61" x="321" y="40.9951">Authority</text><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="115" x="321" y="57.292">Has the records:</text><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="115" x="321" y="73.5889">- PKEY, n1, 1111</text><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="115" x="321" y="89.8857">- PKEY, n2, 2221</text><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="0" x="325" y="106.1826"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="276" x="321" y="122.4795">Can query the records (in its root zone):</text><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="520" x="321" y="138.7764">- n1.root -&gt; TXT, n1, email=root@n1.pep.example;layer=1;openpgp=AAAA</text><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="184" x="321" y="155.0732">- n2.root -&gt; A, n2, 10.0.0.2</text><!--MD5=[f042970fa631b194e0ab6c1248938917]

entity N1--><rect fill="#FEFECE" filter="url(#f8trcps4qzdke)" height="160.375" style="stroke: #A80036; stroke-width: 1.5;" width="628" x="6" y="245"/><rect fill="#FEFECE" height="10" style="stroke: #A80036; stroke-width: 1.5;" width="15" x="614" y="250"/><rect fill="#FEFECE" height="2" style="stroke: #A80036; stroke-width: 1.5;" width="4" x="612" y="252"/><rect fill="#FEFECE" height="2" style="stroke: #A80036; stroke-width: 1.5;" width="4" x="612" y="256"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="19" x="21" y="277.9951">N1</text><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="115" x="21" y="294.292">Has the records:</text><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="157" x="21" y="310.5889">- PKEY, authority, 0000</text><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="445" x="21" y="326.8857">- TXT, n1, email=root@n1.pep.example;layer=1;openpgp=AAAA</text><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="0" x="25" y="343.1826"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="276" x="21" y="359.4795">Can query the records (in its root zone):</text><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="520" x="21" y="375.7764">- n1.root -&gt; TXT, n1, email=root@n1.pep.example;layer=1;openpgp=AAAA</text><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="588" x="21" y="392.0732">- n2.authority.root -&gt; TXT, n2, email=root@n2.pep.example;layer=1;openpgp=BBBB</text><!--MD5=[4b5ab69de11007997fdc27e7483449f4]

entity N2--><rect fill="#FEFECE" filter="url(#f8trcps4qzdke)" height="160.375" style="stroke: #A80036; stroke-width: 1.5;" width="624" x="669" y="245"/><rect fill="#FEFECE" height="10" style="stroke: #A80036; stroke-width: 1.5;" width="15" x="1273" y="250"/><rect fill="#FEFECE" height="2" style="stroke: #A80036; stroke-width: 1.5;" width="4" x="1271" y="252"/><rect fill="#FEFECE" height="2" style="stroke: #A80036; stroke-width: 1.5;" width="4" x="1271" y="256"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="19" x="684" y="277.9951">N2</text><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="115" x="684" y="294.292">Has the records:</text><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="157" x="684" y="310.5889">- PKEY, authority, 0000</text><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="449" x="684" y="326.8857">- TXT, n2, email=root@n2.pep.example;layer=1;openpgp=BBBB</text><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="0" x="688" y="343.1826"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="276" x="684" y="359.4795">Can query the records (in its root zone):</text><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="524" x="684" y="375.7764">- n2.root -&gt; TXT, n2, email=root@n2.pep.example;layer=1;openpgp=BBBB</text><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacingAndGlyphs" textLength="584" x="684" y="392.0732">- n1.authority.root -&gt; TXT, n1, email=root@n1.pep.example;layer=1;openpgp=AAAA</text><!--MD5=[a3bcdd42f3b359be92cba7c757fb6510]

link Authority to N1--><path d="M414.1244,168.1044 C401.8432,177.2491 390.2738,187.2089 380,198 C368.4189,210.1641 358.7265,224.9757 350.7446,240.1297 " fill="none" id="Authority-&gt;N1" style="stroke: #A80036; stroke-width: 1.0;"/><polygon fill="#A80036" points="348.3222,244.8411,355.9948,238.6661,350.6085,240.3944,348.8801,235.0081,348.3222,244.8411" style="stroke: #A80036; stroke-width: 1.0;"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacingAndGlyphs" textLength="46" x="381" y="211.0669">n1.root</text><!--MD5=[478e86cab0b04192df6bcbe64a4b087d]

link N1 to Authority--><path d="M409.9627,244.8452 C436.3893,221.2997 465.3567,195.4905 492.0268,171.728 " fill="none" id="N1-&gt;Authority" style="stroke: #A80036; stroke-width: 1.0;"/><polygon fill="#A80036" points="495.9445,168.2374,486.5639,171.238,492.2113,171.5636,491.8857,177.211,495.9445,168.2374" style="stroke: #A80036; stroke-width: 1.0;"/><ellipse cx="467" cy="207.0664" fill="none" rx="3" ry="3" style="stroke: #000000; stroke-width: 1.0;"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacingAndGlyphs" textLength="91" x="474" y="211.0669">.authority.root</text><!--MD5=[327723372fcc9f4d0a7402045980df41]

link Authority to N2--><path d="M719.4536,168.0721 C759.3094,191.9857 803.0675,218.2405 843.1965,242.3179 " fill="none" id="Authority-&gt;N2" style="stroke: #A80036; stroke-width: 1.0;"/><polygon fill="#A80036" points="847.5682,244.9409,841.9089,236.8804,843.2808,242.3683,837.7928,243.7402,847.5682,244.9409" style="stroke: #A80036; stroke-width: 1.0;"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacingAndGlyphs" textLength="46" x="796" y="211.0669">n2.root</text><!--MD5=[4ffae381981a331506b36106f3627a07]

link N2 to Authority--><path d="M908.5966,244.8614 C890.8551,227.9922 871.1423,211.3001 851,198 C836.1815,188.2152 820.3513,179.0225 804.0786,170.4467 " fill="none" id="N2-&gt;Authority" style="stroke: #A80036; stroke-width: 1.0;"/><polygon fill="#A80036" points="799.4776,168.0442,805.6041,175.7557,803.9098,170.3585,809.3069,168.6642,799.4776,168.0442" style="stroke: #A80036; stroke-width: 1.0;"/><ellipse cx="877" cy="207.0664" fill="none" rx="3" ry="3" style="stroke: #000000; stroke-width: 1.0;"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacingAndGlyphs" textLength="91" x="884" y="211.0669">.authority.root</text><!--MD5=[fa9ebe00ee9b7c464620861f4401fd4c]

@startuml

skinparam componentStyle rectangle



component Authority [

Authority

Has the records:

- PKEY, n1, 1111

- PKEY, n2, 2221



Can query the records (in its root zone):

- n1.root -> TXT, n1, email=root@n1.pep.example;layer=1;openpgp=AAAA

- n2.root -> A, n2, 10.0.0.2

]



component N1 [

N1

Has the records:

- PKEY, authority, 0000

- TXT, n1, email=root@n1.pep.example;layer=1;openpgp=AAAA



Can query the records (in its root zone):

- n1.root -> TXT, n1, email=root@n1.pep.example;layer=1;openpgp=AAAA

- n2.authority.root -> TXT, n2, email=root@n2.pep.example;layer=1;openpgp=BBBB

]



component N2 [

N2

Has the records:

- PKEY, authority, 0000

- TXT, n2, email=root@n2.pep.example;layer=1;openpgp=BBBB



Can query the records (in its root zone):

- n2.root -> TXT, n2, email=root@n2.pep.example;layer=1;openpgp=BBBB

- n1.authority.root -> TXT, n1, email=root@n1.pep.example;layer=1;openpgp=AAAA

]



[Authority] - -> [N1] : n1.root

[Authority] - -> [N2] : n2.root



[N1] - -> [Authority] : *.authority.root

[N2] - -> [Authority] : *.authority.root



@enduml



PlantUML version 1.2020.02(Sun Mar 01 10:22:07 GMT 2020)

(GPL source distribution)

Java Runtime: Java(TM) SE Runtime Environment

JVM: Java HotSpot(TM) 64-Bit Server VM

Java Version: 1.8.0_241-b07

Operating System: Linux

Default Encoding: UTF-8

Language: en

Country: US

--></g></svg>
 
 No newline at end of file

docs/source/design/gns.rst

0 → 100644
+115 −0
Original line number Diff line number Diff line 
.. _gns:



Mixnet nodes registration in GNS

================================



.. Note: Any key mention of key here, refers to a public key.

   Also, we talk about two different keys: the mixnet nodes OpenPGP keys and

   their GNUnet GNS associated nodes keys.



See some documentation about GNS [gnunet-gns]_



V. proposed to use GNUnet GNS to register and retrieve mixnet nodes in the

mixnet network::



    Nodes should register, with an email address and a key, what is

    already in pEp identity. The key should be in ASCII armor Clients

    obtain the nodes from GNS.



GNUnet GNS limitations

----------------------



No TLS

~~~~~~



in the Web REST interface [rest-gns]_



Because it’s not possible to send/receive encrypted queries, every node

would need to run their own GNUnet node locally and send/receive queries

to it.



No authentication

~~~~~~~~~~~~~~~~~



in the Web REST interface [rest-gns]_



Not a global system

~~~~~~~~~~~~~~~~~~~



With a global name system like DNS, all the client would have the same

view of the network. An authority would still be needed for other

reasons.



Because GNS is not global, authority(s) are needed.



Delegating GNS records

~~~~~~~~~~~~~~~~~~~~~~



The authority(s) would neeed to add (to their ``gnunet-namestore``) the keys

of the mixnet GNS nodes to be able to resolve their records, ie. the

authority(s) delegates the resolution of the node records to the nodes.



Likewise, each mixnet GNS nodes would need to add the key of the authority too,

to be able to solve other GNS nodes, ie. each mixnet GNS node delegates the

resolution of other node records to the authority.



See [delegation]_ for more details.



In the following diagram, there's an authority and two nodes, showing which

records they'd store and which records they can query.

Note that 0000, 1111, 2222 would be the GNS nodes keys, while AAAA and

BBBB would be the mixnet nodes OpenPGP keys.



.. image:: /_static/mixnet_gns_components.svg



Node registration

~~~~~~~~~~~~~~~~~



The key(s) of the authority(s) would be hard-coded, so a mixnet GNS node can

easily add the authority(s) key(s) to its zone, to delegate to the authority the resolution of other nodes.



But the authority needs to get the (new) node key too. How this can be done?



* The node could add its own key querying the Web REST API of the authority,

  but the request would not be encrypted

* nkls is investigating using GNUnet cadet of file sharing



Node discovery by the client

~~~~~~~~~~~~~~~~~~~~~~~~~~~~



A mixnet client would need to know which are the mixnet nodes in the network.

It would need to also have a local GNS node to query records to the authority.



But is it possible to ask the authority a list of all records?.



GNS records

~~~~~~~~~~~



And which would be the records that the nodes should register?



Each node should register their Email address and their OpenPGP key.

There is no need to register the OpenPGP fingerprint, since it can be obtained

from the key, and it does not add any extra security to transmit the

fingerprint in the same "channel" the key is transmited.

They probably should also register the mixnet "layer" in which they'll operate.



CG proposed to use the CERT record type [cert]_, but it would only allow to

register the key, not the Email address and the layer.



We think TXT records are more suitable to store the triple.

It'd have the form::



    email=root@n1.pep.example;layer=1;opengpg=AAAA



TXT records are limited to 255 characters, and a OpenPGP key can be way

longer than that. But it's possible to add several records with the same name,

and they key can be splitted in several.

When querying the TXT record, the key can be reconstracted concatening all the

query results.



References:



.. [cert] https://git.gnunet.org/gnunet.git/tree/src/gnsrecord/plugin_gnsrecord_dns.c#n130

.. [gnunet-gns] https://gnunet.org/en/use.html#gns_cli

.. [rest-gns] https://rest.gnunet.org/

.. [delegation] https://docs.gnunet.org/handbook/gnunet.html#Adding-Links-to-Other-Zones

docs/source/index.rst

+2 −0
Original line number Diff line number Diff line
@@ -8,10 +8,12 @@ Welcome to pEp Python Remailer's documentation! 


.. toctree::

   :maxdepth: 2

   :glob:

   :caption: Contents:



   README

   integration

   design/*

   modules