diff --git a/.gitignore b/.gitignore index 2b6b8f166..a83048564 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ build/ resources/ -public/ \ No newline at end of file +public/ +*.xpr diff --git a/assets/scss/_styles_project.scss b/assets/scss/_styles_project.scss index e5c3103d2..e98536d4b 100644 --- a/assets/scss/_styles_project.scss +++ b/assets/scss/_styles_project.scss @@ -124,3 +124,11 @@ header.article-meta { line-height: 1.6; /* Increase line height for better readability */ font-weight: 400; /* Optional: Adjust weight for optimal readability */ } + +/* Customizations */ + +.td-page-meta__view { display: none !important; } +.td-page-meta__edit { display: none !important; } +.td-page-meta__child { display: none !important; } +.td-page-meta__issue { display: none !important; } +.td-page-meta__project-issue { display: none !important; } diff --git a/content/en/docs/_index.md b/content/en/docs/_index.md index ec40525b2..3a5cb345d 100644 --- a/content/en/docs/_index.md +++ b/content/en/docs/_index.md @@ -13,7 +13,7 @@ type: "base" | | Title | Description | Link(s) | |------|----------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------| -| 📖 | **[Admin Guide](/docs/admin_guide)** | Detailed guide for deploying and managing Katzenpost servers, including setting up a local Docker-based mixnet. | [HTML](/docs/admin_guide) | +| 📖 | **[Admin Guide](/docs/admin_guide)** | Detailed guide for deploying and managing Katzenpost servers, including setting up a local Docker-based mixnet. | [HTML](/docs/admin_guide) / [PDF](/admin_guide/admin_guide.pdf) | | 🔒 | **[Threat Model](/docs/threat_model)** | An evolving document defining Katzenpost's security assumptions, attack scenarios, and mitigation strategies. | [HTML](/docs/threat_model) / [PDF](/research/Threat_Model_Doc.pdf) | | 📚 | **[Literature Review](/research/Literature_overview__website_version.pdf)** | A curated review of academic literature, explaining the theoretical foundations behind Katzenpost's design decisions. | [PDF](/research/Literature_overview__website_version.pdf) | | 🎧 | **[Audio Engineering Considerations for a Modern Mixnet](/docs/audio_eng)** | Technical analysis of audio transmission challenges and solutions for modern mixnets, with a focus on usability and scalability. | [HTML](/docs/audio_eng) / [PDF](/research/Audio_Engineering_Considerations_for_a_Modern_Mixnet.pdf) | @@ -28,15 +28,15 @@ These documents are mostly for internal use. They go into excruciating detail wh | | Title | Description | Link(s) | |----|----------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------| -| 📖 | **[Mixnet](/docs/specs/mixnet)** | Describes the overall mixnet design. | [HTML](/docs/specs/mixnet) / [PDF](/docs/specs/mixnet.pdf) | -| 📖 | **[Public Key Infrastructure](/docs/specs/pki)** | Every mixnet must have a PKI, this doc describes ours. | [HTML](/docs/specs/pki) / [PDF](/docs/specs/pki.pdf) | -| 📖 | **[Wire Protocol](/docs/specs/wire_protocol)** | A detailed design specification for our PQ Noise based wire protocol, which is used for transport encryption between all the mix nodes and dirauth nodes. | [HTML](/docs/specs/wire_protocol) / [PDF](/docs/specs/wire_protocol.pdf) | +| 📖 | **[Mixnet](/docs/specs/mixnet)** | Describes the overall mixnet design. | [HTML](/docs/specs/mixnet) / [PDF](/specs/mixnet.pdf) | +| 📖 | **[Public Key Infrastructure](/docs/specs/pki)** | Every mixnet must have a PKI, this doc describes ours. | [HTML](/docs/specs/pki) / [PDF](/specs/pki.pdf) | +| 📖 | **[Wire Protocol](/docs/specs/wire_protocol)** | A detailed design specification for our PQ Noise based wire protocol, which is used for transport encryption between all the mix nodes and dirauth nodes. | [HTML](/docs/specs/wire_protocol) / [PDF](/specs/wire_protocol.pdf) | | 📖 | **[Sphinx packet format](/docs/specs/sphinx.pdf)** | Sphinx packet format, a nested cryptographic packet format designed for mix networks. | [HTML](/docs/specs/sphinx) / [PDF](/docs/specs/sphinx.pdf) | -| 📖 | **[KEM Sphinx packet format](/docs/specs/kem_sphinx)** | The KEM Sphinx variation of Sphinx | [HTML](/docs/specs/kem_sphinx) / [PDF](/docs/specs/kemsphinx.pdf) | +| 📖 | **[KEM Sphinx packet format](/docs/specs/kem_sphinx)** | The KEM Sphinx variation of Sphinx | [HTML](/docs/specs/kem_sphinx) / [PDF](/specs/kemsphinx.pdf) | | 📖 | **[Sphinx Replay Detection](/specs/sphinx_replay_detection)** | Sphinx Replay Detection | [HTML](/docs/specs/sphinx_replay_detection) / [PDF](/docs/specs/sphinx_replay_detection.pdf) | -| 📖 | **[Certificate format](/docs/specs/certificate)** | PKI Certificate format | [HTML](/docs/specs/certificate) / [PDF](/docs/specs/certificate.pdf) | -| 📖 | **[Client2](/docs/specs/client2)** | Client2 thin client library design.. | [HTML](/docs/specs/client2) / [PDF](/docs/specs/client2.pdf) | -| 📖 | **[Mix decoy stats propagation](/docs/specs/mix_decoy_stats_propagation)** | Mix decoy stats propagation | [HTML](/docs/specs/mix_decoy_stats_propagation) / [PDF](/docs/specs/mix_decoy_stats_propagation.pdf) | +| 📖 | **[Certificate format](/docs/specs/certificate)** | PKI Certificate format | [HTML](/docs/specs/certificate) / [PDF](/specs/certificate.pdf) | +| 📖 | **[Client2](/docs/specs/client2)** | Client2 thin client library design.. | [HTML](/docs/specs/client2) / [PDF](/specs/client2.pdf) | +| 📖 | **[Mix decoy stats propagation](/docs/specs/mix_decoy_stats_propagation)** | Mix decoy stats propagation | [HTML](/docs/specs/mix_decoy_stats_propagation) / [PDF](/specs/mix_decoy_stats_propagation.pdf) | --- diff --git a/content/en/docs/admin_guide/_index.md b/content/en/docs/admin_guide/_index.md index 80a71d311..abf912a25 100644 --- a/content/en/docs/admin_guide/_index.md +++ b/content/en/docs/admin_guide/_index.md @@ -1,5 +1,5 @@ --- -title: Katzenpost administration guide +title: Administration guide weight: 6 --- @@ -9,7 +9,7 @@ Use the documentation in this section to explore how the mixnet works and to imp | | Title | Description | Link(s) | |------|----------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------| -| 📖 | **[Admin Guide](/docs/admin_guide)** | Detailed guide for deploying and managing Katzenpost servers, including setting up a local Docker-based mixnet. | [HTML](/docs/admin_guide) / [PDF](/research/) | +| 📖 | **[Admin Guide](/docs/admin_guide)** | Detailed guide for deploying and managing Katzenpost servers, including setting up a local Docker-based mixnet. | [PDF](/admin_guide/admin_guide.pdf) | diff --git a/content/en/docs/admin_guide/components.html b/content/en/docs/admin_guide/components.html index 94d951a5c..b163146b0 100644 --- a/content/en/docs/admin_guide/components.html +++ b/content/en/docs/admin_guide/components.html @@ -30,7 +30,7 @@

Figure 1. The pictured element types correspond to discrete client and server programs that Katzenpost requires to function.

-
The pictured element types correspond to discrete client and server programs that Katzenpost requires to function.
+
The pictured element types correspond to discrete client and server programs that Katzenpost requires to function.

The mix network contains an n-layer topology of mix-nodes, with three nodes per layer in this example. Sphinx packets traverse the network in one @@ -118,7 +118,7 @@ provides multiplexing and privilege separation with a consequent reduction in processing overhead. These clients also implement the Pigeonhole storage and BACAP protocols detailed in Place-holder for research paper link.

-

The following client applications are available.

Table 1. Katzenpost clients

+

The following client applications are available.

Table 1. Katzenpost clients

Name

@@ -178,7 +178,7 @@ katzenpost/docker/dirauth_mixnet/auth1/authority.toml. In a real-world mixnet, the component hosts would not be sharing a single IP address. For more information about the test mixnet, see ???.

-

Table 2. Directory authority (dirauth) configuration +

Table 2. Directory authority (dirauth) configuration sections

@@ -413,7 +413,7 @@ -
+

The Logging configuration section controls logging behavior across Katzenpost.

@@ -723,7 +723,7 @@ PKI document for validation by its peer dirauths.

-
+

The SphinxGeometry section defines parameters for the Sphinx @@ -854,7 +854,7 @@ real-world mixnet, the component hosts would not be sharing a single IP address. For more information about the test mixnet, see ???.

-

Table 3. Mix node configuration sections

+

Table 3. Mix node configuration sections

Mix node: Server section

@@ -890,7 +890,7 @@

-
+
@@ -1005,7 +1005,7 @@ -
+

The Logging configuration section controls logging behavior across Katzenpost.

@@ -1043,7 +1043,7 @@ -
+

The PKI section contains the directory authority configuration for a mix, gateway, or service node.

@@ -1161,7 +1161,7 @@ -
+

The Management section specifies @@ -1190,7 +1190,7 @@ -

+

The SphinxGeometry section defines parameters for the Sphinx @@ -1317,7 +1317,7 @@ -

+

The Debug section is the Katzenpost server debug configuration @@ -1475,7 +1475,7 @@ katzenpost/docker/dirauth_mixnet/gateway1/katzenpost.toml. In a real-world mixnet, the component hosts would not be sharing a single IP address. For more information about the test mixnet, see ???.

-

Table 4. Gateway node configuration sections

+

Table 4. Gateway node configuration sections

Gateway node: Server section

@@ -1512,7 +1512,7 @@ TCP = ["localhost:30004"] -
+
@@ -1627,7 +1627,7 @@ -
+

The Logging configuration section controls logging behavior across Katzenpost.

@@ -1688,7 +1688,7 @@ -
+

The PKI section contains the directory authority configuration for a mix, gateway, or service node.

@@ -1806,7 +1806,7 @@ -
+

The Management section specifies @@ -1835,7 +1835,7 @@ -

+

The SphinxGeometry section defines parameters for the Sphinx @@ -1962,7 +1962,7 @@ -

+

The Debug section is the Katzenpost server debug configuration @@ -2120,7 +2120,7 @@ katzenpost/docker/dirauth_mixnet/servicenode1/authority.toml. In a real-world mixnet, the component hosts would not be sharing a single IP address. For more information about the test mixnet, see ???.

-

Table 5. Mix node configuration sections

+

Table 5. Mix node configuration sections

Service node: Server section

@@ -2156,7 +2156,7 @@ [Server.AltAddresses] -
+
@@ -2271,7 +2271,7 @@ -
+

The Logging configuration section controls logging behavior across Katzenpost.

@@ -2515,7 +2515,7 @@ -
+

The PKI section contains the directory authority configuration for a mix, gateway, or service node.

@@ -2633,7 +2633,7 @@ -
+

The Management section specifies @@ -2662,7 +2662,7 @@ -

+

The SphinxGeometry section defines parameters for the Sphinx @@ -2789,7 +2789,7 @@ -

+

The Debug section is the Katzenpost server debug configuration diff --git a/content/en/docs/admin_guide/docker.html b/content/en/docs/admin_guide/docker.html index 808ce896c..686e8f3ae 100644 --- a/content/en/docs/admin_guide/docker.html +++ b/content/en/docs/admin_guide/docker.html @@ -5,7 +5,7 @@ --- - Using the Katzenpost Docker test network

Using the Katzenpost Docker test network


+ Using the Katzenpost Docker test network

Using the Katzenpost Docker test network


Katzenpost provides a ready-to-deploy Docker @@ -346,7 +346,7 @@ gray blocks represent nodes, and the arrows represent information transfer.

Figure 1. Test network topology

-
Test network topology
+
Test network topology

On the left, the Client transmits a message (shown by purple arrows) through the Gateway node, across three @@ -363,7 +363,7 @@ the following table. Note that all nodes share the same IP address (127.0.0.1, i.e., localhost), but are accessed through different ports. Each node type links to additional information in ???.

-

Table 2. Table 2: Test mixnet hosts

+

Table 2. Table 2: Test mixnet hosts

Node typeDocker IDDiagram labelIP addressTCP port

Directory authority

@@ -401,7 +401,7 @@

30012


-

The Docker file tree

+

The Docker file tree

The following tree output shows the location, relative to the katzenpost diff --git a/content/en/docs/specs/_index.md b/content/en/docs/specs/_index.md index 39120ad1f..732a7eeac 100644 --- a/content/en/docs/specs/_index.md +++ b/content/en/docs/specs/_index.md @@ -1,6 +1,8 @@ --- title: Specifications weight: 6 +draft: false +type: page --- {{% pageinfo %}} @@ -9,4 +11,4 @@ These technical specifications describe the specifics of Katzenpost protocols an | | Title | Description | Link(s) | |----|----------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------| -| đź“– | **[Katzenpost specifications](/docs/specs/)** | Developer documentation for various components and protocols used in the mixnet. | [HTML](/docs/specs/) / [PDF](/docs/specs/mixnet.pdf) | +| đź“– | **[Katzenpost specifications](/docs/specs/)** | Developer documentation for various components and protocols used in the mixnet. | [PDF](/specs/mixnet.pdf) | diff --git a/content/en/docs/specs/certificate.html b/content/en/docs/specs/certificate.html index 48bf920cc..1e40f01cc 100644 --- a/content/en/docs/specs/certificate.html +++ b/content/en/docs/specs/certificate.html @@ -2,8 +2,7 @@ title: "Katzenpost Certificate Specification" linkTitle: "Certificate" draft: false -slug: "/certificate/" -type: "pages" + ---

Abstract

diff --git a/content/en/docs/specs/kemsphinx.html b/content/en/docs/specs/kemsphinx.html index 4c9e0f35f..8236c45a2 100644 --- a/content/en/docs/specs/kemsphinx.html +++ b/content/en/docs/specs/kemsphinx.html @@ -1,51 +1,57 @@ ---- -title: "KEM Sphinx Specification" -linkTitle: "KEM Sphinx" -draft: false -slug: "/kem_sphinx/" ---- - -

Abstract

-

Here I present a modification of the Sphinx cryptographic packet -format that uses a KEM instead of a NIKE whilst preserving the -properties of bitwise unlinkability, constant packet size and route -length hiding.

-

1. Introduction

-

We’ll express our KEM Sphinx header in pseudo code. The Sphinx body -will be exactly the same as SPHINXSPEC. Our -basic KEM API has three functions:

-
    -
  • PRIV_KEY, PUB_KEY = GEN_KEYPAIR(RNG)
  • -
  • ct, ss = ENCAP(PUB_KEY) - Encapsulate generates a -shared secret, ss, for the public key and encapsulates it into a -ciphertext.
  • -
  • ss = DECAP(PRIV_KEY, ct) - Decapsulate computes the -shared key, ss, encapsulated in the ciphertext, ct, for the private -key.
  • -
-

Additional notation includes:

-
    -
  • || = concatenate two binary blobs together
  • -
  • PRF = pseudo random function, a cryptographic hash -function, e.g. Blake2b.
  • -
-

Therefore we must embed these KEM ciphertexts in the KEMSphinx -header, one KEM ciphertext per mix hop.

-

2. Post Quantum Hybrid KEM

-

Special care must be taken in order correctly compose a hybrid post -quantum KEM that is IND-CCA2 robust.

-

The hybrid post quantum KEMs found in Cloudflare’s circl library are -suitable to be used with Noise or TLS but not with KEM Sphinx because -they are not IND-CCA2 robust. Noise and TLS achieve IND-CCA2 security by -mixing in the public keys and ciphertexts into the hash object and -therefore do not require an IND-CCA2 KEM.

-

Firstly, our post quantum KEM is IND-CCA2 however we must -specifically take care to make our NIKE to KEM adapter have semantic -security. Secondly, we must make a security preserving KEM combiner.

-

2.1 NIKE to KEM adapter

-

We easily achieve our IND-CCA2 security by means of hashing together -the DH shared secret along with both of the public keys:

-
func ENCAPSULATE(their_pubkey publickey) ([]byte, []byte) {
+
+      
+   KEMSphinx

KEMSphinx

David Stainton


+ Abstract +

+ Here I present a modification of the Sphinx cryptographic packet + format that uses a KEM instead of a NIKE whilst preserving the + properties of bitwise unlinkability, constant packet size and route + length hiding. +

1. Introduction

+ We’ll express our KEM Sphinx header in pseudo code. The Sphinx + body will be exactly the same as + SPHINXSPEC Our basic KEM API + has three functions: +

  • + PRIV_KEY, PUB_KEY = GEN_KEYPAIR(RNG) +

  • + ct, ss = ENCAP(PUB_KEY) - Encapsulate + generates a shared secret, ss, for the public key and + encapsulates it into a ciphertext. +

  • + ss = DECAP(PRIV_KEY, ct) - Decapsulate + computes the shared key, ss, encapsulated in the ciphertext, + ct, for the private key. +

+ Additional notation includes: +

  • + || = concatenate two binary blobs together +

  • + PRF = pseudo random function, a + cryptographic hash function, e.g. Blake2b. +

+ Therefore we must embed these KEM ciphertexts in the KEMSphinx + header, one KEM ciphertext per mix hop. +

2. Post Quantum Hybrid KEM

+ Special care must be taken in order correctly compose a hybrid + post quantum KEM that is IND-CCA2 robust. +

+ The hybrid post quantum KEMs found in Cloudflare’s circl library + are suitable to be used with Noise or TLS but not with KEM Sphinx + because they are not IND-CCA2 robust. Noise and TLS achieve + IND-CCA2 security by mixing in the public keys and ciphertexts + into the hash object and therefore do not require an IND-CCA2 KEM. +

+ Firstly, our post quantum KEM is IND-CCA2 however we must + specifically take care to make our NIKE to KEM adapter have + semantic security. Secondly, we must make a security preserving + KEM combiner. +

2.1 NIKE to KEM adapter

+ We easily achieve our IND-CCA2 security by means of hashing + together the DH shared secret along with both of the public + keys: +

+func ENCAPSULATE(their_pubkey publickey) ([]byte, []byte) {
     my_privkey, my_pubkey = GEN_KEYPAIR(RNG)
     ss = DH(my_privkey, their_pubkey)
     ss2 = PRF(ss || their_pubkey || my_pubkey)
@@ -56,124 +62,131 @@ 

2.1 NIKE to KEM adapter

s = DH(my_privkey, their_pubkey) shared_key = PRF(ss || my_pubkey || their_pubkey) return shared_key -}
-

2.2 KEM Combiner

-

The KEM Combiners paper KEMCOMB makes the -observation that if a KEM combiner is not security preserving then the -resulting hybrid KEM will not have IND-CCA2 security if one of the -composing KEMs does not have IND-CCA2 security. Likewise the paper -points out that when using a security preserving KEM combiner, if only -one of the composing KEMs has IND-CCA2 security then the resulting -hybrid KEM will have IND-CCA2 security.

-

Our KEM combiner uses the split PRF design from the paper when -combining two KEM shared secrets together we use a hash function to also -mix in the values of both KEM ciphertexts. In this pseudo code example -we are hashing together the two shared secrets from the two underlying -KEMs, ss1 and ss2. Additionally the two ciphertexts from the underlying -KEMs, cct1 and cct2, are also hashed together:

-
func SplitPRF(ss1, ss2, cct1, cct2 []byte) []byte {
+}
+

2.2 KEM Combiner

+ The KEM Combiners paper KEMCOMB + makes the observation that if a KEM combiner is not security + preserving then the resulting hybrid KEM will not have IND-CCA2 + security if one of the composing KEMs does not have IND-CCA2 + security. Likewise the paper points out that when using a + security preserving KEM combiner, if only one of the composing + KEMs has IND-CCA2 security then the resulting hybrid KEM will + have IND-CCA2 security. +

+ Our KEM combiner uses the split PRF design from the paper when + combining two KEM shared secrets together we use a hash function + to also mix in the values of both KEM ciphertexts. In this + pseudo code example we are hashing together the two shared + secrets from the two underlying KEMs, ss1 and ss2. Additionally + the two ciphertexts from the underlying KEMs, cct1 and cct2, are + also hashed together: +

+func SplitPRF(ss1, ss2, cct1, cct2 []byte) []byte {
     cct := cct1 || cct2
     return PRF(ss1 || cct) XOR PRF(ss2 || cct)
-}
-

Which simplifies to:

-
SplitPRF := PRF(ss1 || cct2) XOR PRF(ss2 || cct1)
-

The Split PRF can be used to combine an arbitrary number of KEMs. -Here’s what it looks like with three KEMs:

-
func SplitPRF(ss1, ss2, ss3, cct1, cct2, cct3 []byte) []byte {
+}
+

+ Which simplifies to: +

+SplitPRF := PRF(ss1 || cct2) XOR PRF(ss2 || cct1)
+

+ The Split PRF can be used to combine an arbitrary number of + KEMs. Here’s what it looks like with three KEMs: +

+func SplitPRF(ss1, ss2, ss3, cct1, cct2, cct3 []byte) []byte {
     cct := cct1 || cct2 || cct3
     return PRF(ss1 || cct) XOR PRF(ss2 || cct) XOR PRF(ss3 || cct)
-}
-

3. KEMSphinx Header Design

-

NIKE Sphinx header elements:

-
    -
  1. Version number (MACed but not encrypted)
  2. -
  3. Group element
  4. -
  5. Encrypted per routing commands
  6. -
  7. MAC for this hop (authenticates header fields 1 thru 4)
  8. -
-

KEM Sphinx header elements:

-
    -
  1. Version number (MACed but not encrypted)
  2. -
  3. One KEM ciphertext for use with the next hop
  4. -
  5. Encrypted per routing commands AND KEM ciphtertexts, one for each -additional hop
  6. -
  7. MAC for this hop (authenticates header fields 1 thru 4)
  8. -
-

We can say that KEMSphinx differs from NIKE Sphinx by replacing the -header’s group element (e.g. an X25519 public key) field with the KEM -ciphertext. Subsequent KEM ciphertexts for each hop are stored inside -the Sphinx header “routing information” section.

-

First we must have a data type to express a mix hop, and we can use -lists of these hops to express a route:

-
type PathHop struct {
+}
+

3. KEMSphinx Header Design

+ NIKE Sphinx header elements: +

  1. + Version number (MACed but not encrypted) +

  2. + Group element +

  3. + Encrypted per routing commands +

  4. + MAC for this hop (authenticates header fields 1 thru 4) +

+ KEM Sphinx header elements: +

  1. + Version number (MACed but not encrypted) +

  2. + One KEM ciphertext for use with the next hop +

  3. + Encrypted per routing commands AND KEM ciphtertexts, one for + each additional hop +

  4. + MAC for this hop (authenticates header fields 1 thru 4) +

+ We can say that KEMSphinx differs from NIKE Sphinx by replacing + the header’s group element (e.g. an X25519 public key) field with + the KEM ciphertext. Subsequent KEM ciphertexts for each hop are + stored inside the Sphinx header routing information + section. +

+ First we must have a data type to express a mix hop, and we can + use lists of these hops to express a route: +

+type PathHop struct {
     public_key kem.PublicKey
     routing_commands Commands
-}
-

Here’s how we construct a KEMSphinx packet header where path is a -list of PathHop, and indicates the route through the network:

-
    -
  1. Derive the KEM ciphertexts for each hop.
  2. -
-
route_keys = []
+}
+

+ Here’s how we construct a KEMSphinx packet header where path is a + list of PathHop, and indicates the route through the network: +

  1. + Derive the KEM ciphertexts for each hop. +

+route_keys = []
 route_kems = []
 for i := 0; i < num_hops; i++ {
     kem_ct, ss := ENCAP(path[i].public_key)
     route_kems += kem_ct
     route_keys += ss
-}
-
    -
  1. Derive the routing_information keystream and encrypted padding for -each hop.
  2. -
-

Same as in SPHINXSPEC except for the fact -that each routing info slot is now increased by the size of the KEM -ciphertext.

-
    -
  1. Create the routing_information block.
  2. -
-

Here we modify the Sphinx implementation to pack the next KEM -ciphertext into each routing information block. Each of these blocks is -decrypted for each mix mix hop which will decrypt the KEM ciphertext for -the next hop in the route.

-
    -
  1. Assemble the completed Sphinx Packet Header and Sphinx Packet -Payload SPRP key vector. Same as in SPHINXSPEC -except the kem_element field is set to the first KEM -ciphertext, route_kems[0]:
  2. -
-
var sphinx_header SphinxHeader
+}
+
  1. + Derive the routing_information keystream and encrypted padding + for each hop. +

+ Same as in SPHINXSPEC except for + the fact that each routing info slot is now increased by the size + of the KEM ciphertext. +

  1. + Create the routing_information block. +

+ Here we modify the Sphinx implementation to pack the next KEM + ciphertext into each routing information block. Each of these + blocks is decrypted for each mix mix hop which will decrypt the + KEM ciphertext for the next hop in the route. +

  1. + Assemble the completed Sphinx Packet Header and Sphinx Packet + Payload SPRP key vector. Same as in + SPHINXSPEC except the + kem_element field is set to the first KEM + ciphertext, route_kems[0]: +

+var sphinx_header SphinxHeader
 sphinx_header.additional_data = version
 sphinx_header.kem_element = route_kems[0]
 sphinx_header.routing_info = routing_info
-sphinx_header.mac = mac
-

2. KEMSphinx Unwrap Operation

-

Most of the design here will be exactly the same as in SPHINXSPEC. However there are a few notable -differences:

-
    -
  1. The shared secret is derived from the KEM ciphertext instead of a -DH.
  2. -
  3. Next hop’s KEM ciphertext stored in the encrypted routing -information.
  4. -
-

3. Acknowledgments

-

I would like to thank Peter Schwabe for the original idea of simply -replacing the Sphinx NIKE with a KEM and for answering all my questions. -I’d also like to thank Bas Westerbaan for answering questions.

-

Appendix A. References

-

KEMCOMB

-
Federico Giacon, Felix Heuer, Bertram Poettering,
-"KEM Combiners",
-2018
-https://link.springer.com/chapter/10.1007/978-3-319-76578-5_7>PKC
-

SPHINX09

-
Danezis, G., Goldberg, I.,
-"Sphinx: A Compact and Provably Secure Mix Format\",
-DOI 10.1109/SP.2009.15,
-May 2009,
-https://cypherpunks.ca/~iang/pubs/Sphinx_Oakland09.pdf
-

SPHINXSPEC

-
Angel, Y., Danezis, G., Diaz, C., Piotrowska, A., Stainton, D.,
-"Sphinx Mix Network Cryptographic Packet Format Specification"
-July 2017,
-https://github.com/katzenpost/katzenpost/blob/master/docs/specs/sphinx.md
+sphinx_header.mac = mac +

2. KEMSphinx Unwrap Operation

+ Most of the design here will be exactly the same as in + SPHINXSPEC. However there are a + few notable differences: +

  1. + The shared secret is derived from the KEM ciphertext instead + of a DH. +

  2. + Next hop’s KEM ciphertext stored in the encrypted routing + information. +

3. Acknowledgments

+ I would like to thank Peter Schwabe for the original idea of + simply replacing the Sphinx NIKE with a KEM and for answering + all my questions. I’d also like to thank Bas Westerbaan for + answering questions. +

Appendix A. References

KEMCOMB. Federico Giacon, Felix Heuer, Bertram Poettering, "KEM Combiners", 2018. + https://link.springer.com/chapter/10.1007/978-3-319-76578-5_7

SPHINX09. Danezis, G., Goldberg, I., "Sphinx: A Compact and Provably Secure Mix + Format\", DOI 10.1109/SP.2009.15, May 2009. https://cypherpunks.ca/~iang/pubs/Sphinx_Oakland09.pdf

SPHINXSPEC. Angel, Y., Danezis, G., Diaz, C., Piotrowska, A., Stainton, D., "Sphinx Mix + Network Cryptographic Packet Format Specification" July 2017. https://katzenpost.network/docs/specs/sphinx/

\ No newline at end of file diff --git a/content/en/docs/specs/wire-protocol.html b/content/en/docs/specs/wire-protocol.html index 2ae1da4d0..03ba8ea6e 100644 --- a/content/en/docs/specs/wire-protocol.html +++ b/content/en/docs/specs/wire-protocol.html @@ -1,132 +1,167 @@ ---- -title: "Katzenpost Wire Protocol Specification" -linkTitle: "Wire Protocol" -draft: false -slug: "/wire_protocol/" ---- - -

Abstract

-

This document defines the Katzenpost Mix Network Wire Protocol for -use in all network communications to, from, and within the Katzenpost -Mix Network.

-

1. Introduction

-

The Katzenpost Mix Network Wire Protocol (KMNWP) is the custom wire -protocol for all network communications to, from, and within the -Katzenpost Mix Network. This protocol provides mutual authentication, -and an additional layer of cryptographic security and forward -secrecy.

-

1.1 Conventions Used in This -Document

-

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, -“SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this -document are to be interpreted as described in RFC2119.

-

The “C” style Presentation Language as described in RFC5246 Section 4 is used to represent data -structures, except for cryptographic attributes, which are specified as -opaque byte vectors.

-

x | y denotes the concatenation of x and y.

-

1.2 Key Encapsulation -Mechanism

-

This protocol uses ANY Key Encapsulation Mechanism. However it’s -recommended that most users select a hybrid post quantum KEM such as -Xwing. XWING

-

2. Core Protocol

-

The protocol is based on Kyber and Trevor Perrin’s Noise Protocol -Framework NOISE along with “Post Quantum Noise” -paper PQNOISE. Older previous versions of our -transport were based on NOISEHFS.

-

Our transport protocol begins with a prologue, Noise handshake, -followed by a stream of Noise Transport messages in a minimal framing -layer, over a TCP/IP connection.

-

Our Noise protocol is configurable via the KEM selection in the TOML -configuration files, here’s an example PQ Noise protocol string:

-
Noise_pqXX_Xwing_ChaChaPoly_BLAKE2b
-

The protocol string is a very condensed description of our protocol. -We use the pqXX two way Noise pattern which is described as follows:

-
pqXX: -> e <- ekem, s -> skem, s <- skem
-

The next part of the protocol string specifies the KEM, -Xwing which is a hybrid KEM where the share secret outputs -of both X25519 and MLKEM768 are combined.

-

Finally the ChaChaPoly_BLAKE2b parts of the protocol -string indicate which stream cipher and hash function we are using.

-

As a non-standard modification to the Noise protocol, the 65535 byte -message length limit is increased to 1300000 bytes. We send very large -messages over our Noise protocol because of our using the Sphincs+ -signature scheme which has signatures that are about 49k bytes.

-

It is assumed that all parties using the KMNWP protocol have a fixed -long or short lived Xwing keypair XWING, the public component of which is known to the -other party in advance. How such keys are distributed is beyond the -scope of this document.

-

2.1 Handshake Phase

-

All sessions start in the Handshake Phase, in which an anonymous -authenticated handshake is conducted.

-

The handshake is a unmodified Noise handshake, with a fixed prologue -prefacing the initiator's first Noise handshake message. This prologue -is also used as the prologue input to the Noise -HandshakeState Initialize() operation for both the -initiator and responder.

-

The prologue is defined to be the following structure:

-
struct {
+
+      
+   Wire Protocol

Wire Protocol

Yawning Angel

David Stainton


+ Abstract +

+ This document defines the Katzenpost Mix Network Wire Protocol for + use in all network communications to, from, and within the + Katzenpost Mix Network. +

1. Introduction

+ The Katzenpost Mix Network Wire Protocol (KMNWP) is the custom + wire protocol for all network communications to, from, and within + the Katzenpost Mix Network. This protocol provides mutual + authentication, and an additional layer of cryptographic security + and forward secrecy. +

1.1 Conventions Used in This Document

+ The key words MUST, MUST NOT, + REQUIRED, SHALL, SHALL + NOT, SHOULD, SHOULD NOT, + RECOMMENDED, MAY, and + OPTIONAL in this document are to be interpreted + as described in RFC2119. +

+ The C style Presentation Language as described in + RFC5246 Section 4 is used to + represent data structures, except for cryptographic attributes, + which are specified as opaque byte vectors. +

+ x | y denotes the concatenation of x and y. +

1.2 Key Encapsulation Mechanism

+ This protocol uses ANY Key Encapsulation Mechanism. However it’s + recommended that most users select a hybrid post quantum KEM + such as Xwing. XWING +

2. Core Protocol

+ The protocol is based on Kyber and Trevor Perrin’s Noise Protocol + Framework NOISE along with + Post Quantum Noise paper + PQNOISE. Older previous versions of + our transport were based on + NOISEHFS. +

+ Our transport protocol begins with a prologue, Noise handshake, + followed by a stream of Noise Transport messages in a minimal + framing layer, over a TCP/IP connection. +

+ Our Noise protocol is configurable via the KEM selection in the + TOML configuration files, here’s an example PQ Noise protocol + string: +

+Noise_pqXX_Xwing_ChaChaPoly_BLAKE2b
+

+ The protocol string is a very condensed description of our + protocol. We use the pqXX two way Noise pattern which is described + as follows: +

+pqXX: -> e <- ekem, s -> skem, s <- skem
+

+ The next part of the protocol string specifies the KEM, + Xwing which is a hybrid KEM where the share + secret outputs of both X25519 and MLKEM768 are combined. +

+ Finally the ChaChaPoly_BLAKE2b parts of the + protocol string indicate which stream cipher and hash function we + are using. +

+ As a non-standard modification to the Noise protocol, the 65535 + byte message length limit is increased to 1300000 bytes. We send + very large messages over our Noise protocol because of our using + the Sphincs+ signature scheme which has signatures that are about + 49k bytes. +

+ It is assumed that all parties using the KMNWP protocol have a + fixed long or short lived Xwing keypair + XWING, the public component of which + is known to the other party in advance. How such keys are + distributed is beyond the scope of this document. +

2.1 Handshake Phase

+ All sessions start in the Handshake Phase, in which an anonymous + authenticated handshake is conducted. +

+ The handshake is a unmodified Noise handshake, with a fixed + prologue prefacing the initiator's first Noise handshake + message. This prologue is also used as the + prologue input to the Noise HandshakeState + Initialize() operation for both the initiator + and responder. +

+ The prologue is defined to be the following structure: +

+struct {
     uint8_t protocol_version; /* 0x03 */
-} Prologue;
-

As all Noise handshake messages are fixed sizes, no additional -framing is required for the handshake.

-

Implementations MUST preserve the Noise handshake hash -[h] for the purpose of implementing authentication (Section -2.3).

-

Implementations MUST reject handshake attempts by terminating the -session immediately upon any Noise protocol handshake failure and when, -as a responder, they receive a Prologue containing an unknown -protocol_version value.

-

Implementations SHOULD impose reasonable timeouts for the handshake -process, and SHOULD terminate sessions that are taking too long to -handshake.

-

2.1.1 Handshake Authentication

-

Mutual authentication is done via exchanging fixed sized payloads as -part of the pqXX handshake consisting of the following -structure:

-
struct {
+} Prologue;
+

+ As all Noise handshake messages are fixed sizes, no additional + framing is required for the handshake. +

+ Implementations MUST preserve the Noise handshake hash + [h] for the purpose of implementing + authentication (Section 2.3). +

+ Implementations MUST reject handshake attempts by terminating + the session immediately upon any Noise protocol handshake + failure and when, as a responder, they receive a Prologue + containing an unknown protocol_version value. +

+ Implementations SHOULD impose reasonable timeouts for the + handshake process, and SHOULD terminate sessions that are taking + too long to handshake. +

2.1.1 Handshake Authentication

+ Mutual authentication is done via exchanging fixed sized + payloads as part of the pqXX handshake + consisting of the following structure: +

+struct {
     uint8_t ad_len;
     opaque additional_data[ad_len];
     opaque padding[255 - ad_len];
     uint32_t unix_time;
-} AuthenticateMessage;
-

Where:

-
    -
  • ad_len - The length of the optional additional -data.
  • -
  • additional_data - Optional additional data, such as a -username, if any.
  • -
  • unix_time - 0 for the initiator, the approximate number -of seconds since 1970-01-01 00:00:00 UTC for the responder.
  • -
-

The initiator MUST send the AuthenticateMessage after it -has received the peer's response (so after -> s, se in -Noise parlance).

-

The contents of the optional additional_data field is -deliberately left up to the implementation, however it is RECOMMENDED -that implementations pad the field to be a consistent length regardless -of contents to avoid leaking information about the authenticating -identity.

-

To authenticate the remote peer given an AuthenticateMessage, the -receiving peer must validate the s component of the Noise -handshake (the remote peer's long term public key) with the known value, -along with any of the information in the additional_data -field such as the user name, if any.

-

If the validation procedure succeeds, the peer is considered -authenticated. If the validation procedure fails for any reason, the -session MUST be terminated immediately.

-

Responders MAY add a slight amount (+- 10 seconds) of random noise to -the unix_time value to avoid leaking precise load information via packet -queueing delay.

-

2.2 Data Transfer Phase

-

Upon successfully concluding the handshake the session enters the -Data Transfer Phase, where the initiator and responder can exchange -KMNWP messages.

-

A KMNWP message is defined to be the following structure:

-
enum {
+} AuthenticateMessage;
+

+ Where: +

  • + ad_len - The length of the optional + additional data. +

  • + additional_data - Optional additional + data, such as a username, if any. +

  • + unix_time - 0 for the initiator, the + approximate number of seconds since 1970-01-01 00:00:00 UTC + for the responder. +

+ The initiator MUST send the + AuthenticateMessage after it has received the + peer's response (so after -> s, se in + Noise parlance). +

+ The contents of the optional additional_data + field is deliberately left up to the implementation, however it + is RECOMMENDED that implementations pad the field to be a + consistent length regardless of contents to avoid leaking + information about the authenticating identity. +

+ To authenticate the remote peer given an AuthenticateMessage, + the receiving peer must validate the s + component of the Noise handshake (the remote peer's long term + public key) with the known value, along with any of the + information in the additional_data field such + as the user name, if any. +

+ If the validation procedure succeeds, the peer is considered + authenticated. If the validation procedure fails for any reason, + the session MUST be terminated immediately. +

+ Responders MAY add a slight amount (+- 10 seconds) of random + noise to the unix_time value to avoid leaking precise load + information via packet queueing delay. +

2.2 Data Transfer Phase

+ Upon successfully concluding the handshake the session enters + the Data Transfer Phase, where the initiator and responder can + exchange KMNWP messages. +

+ A KMNWP message is defined to be the following structure: +

+enum {
     no_op(0),
     disconnect(1),
     send_packet(2),
@@ -136,157 +171,163 @@ 

2.2 Data Transfer Phase

struct { Command command; - uint8_t reserved; /* MUST be '0x00' */ + uint8_t reserved; /* MUST be '0x00' */ uint32_t msg_length; /* 0 <= msg_length <= 1048554) */ opaque message[msg_length]; opaque padding[]; /* length is implicit */ -} Message;
-

Notes:

-
    -
  • The padding field, if any MUST be padded with '0x00' -bytes.
  • -
-

All outgoing Message(s) are encrypted and authenticated into a pair -of Noise Transport messages, each containing one of the following -structures:

-
struct {
+} Message;
+

+ Notes: +

  • + The padding field, if any MUST be padded with + '0x00' bytes. +

+ All outgoing Message(s) are encrypted and authenticated into a + pair of Noise Transport messages, each containing one of the + following structures: +

+struct {
     uint32_t message_length;
 } CiphertextHeader;
 
 struct {
     uint32_t message[ciphertext_length-16];
-} Ciphertext;
-

Notes:

-
    -
  • The ciphertext_length field includes the Noise protocol -overhead of 16 bytes, for the Noise Transport message containing the -Ciphertext.
  • -
-

All outgoing Message(s) are preceded by a Noise Transport Message -containing a CiphertextHeader, indicating the size of the -Noise Transport Message transporting the Message Ciphertext. After -generating both Noise Transport Messages, the sender MUST call the Noise -CipherState Rekey() operation.

-

To receive incoming Ciphertext messages, first the Noise Transport -Message containing the CiphertextHeader is consumed off the network, -authenticated and decrypted, giving the receiver the length of the Noise -Transport Message containing the actual message itself. The second Noise -Transport Message is consumed off the network, authenticated and -decrypted, with the resulting message being returned to the caller for -processing. After receiving both Noise Transport Messages, the receiver -MUST call the Noise CipherState Rekey() operation.

-

Implementations MUST immediately terminate the session any of the -DecryptWithAd() operations fails.

-

Implementations MUST immediately terminate the session if an unknown -command is received in a Message, or if the Message is otherwise -malformed in any way.

-

Implementations MAY impose a reasonable idle timeout, and terminate -the session if it expires.

-

3. Predefined Commands

-

3.1 The no_op Command

-

The no_op command is a command that explicitly is a No -Operation, to be used to implement functionality such as keep-alives and -or application layer padding.

-

Implementations MUST NOT send any message payload accompanying this -command, and all received command data MUST be discarded without -interpretation.

-

3.2 The disconnect Command

-

The disconnect command is a command that is used to -signal explicit session termination. Upon receiving a disconnect -command, implementations MUST interpret the command as a signal from the -peer that no additional commands will be sent, and destroy the -cryptographic material in the receive CipherState.

-

While most implementations will likely wish to terminate the session -upon receiving this command, any additional behavior is explicitly left -up to the implementation and application.

-

Implementations MUST NOT send any message payload accompanying this -command, and MUST not send any further traffic after sending a -disconnect command.

-

3.3 The send_packet Command

-

The send_packet command is the command that is used by -the initiator to transmit a Sphinx Packet over the network. The -command’s message is the Sphinx Packet destined for the responder.

-

Initiators MUST terminate the session immediately upon reception of a -send_packet command.

-

4. Command Padding

-

We use traffic padding to hide from a passive network observer which -command has been sent or received.

-

Among the set of padded commands we exclude the -Consensus command because it’s contents are a very large -payload which is usually many times larger than our Sphinx packets. -Therefore we only pad these commands:

-

GetConsensus NoOp Disconnect SendPacket RetrieveMessage MessageACK -Message MessageEmpty

-

However we split them up into two directions, client to server and -server to client because they differ in size due to the difference in -size between SendPacket and Message:

-

Client to Server commands:

-

NoOp SendPacket Disconnect RetrieveMessage GetConsensus

-

Server to client commands:

-

Message MessageACK MessageEmpty

-

The GetConsensus command is a special case because we -only want to pad it when it’s sent over the mixnet. We don’t want to pad -it when sending to the dirauths. Although it would not be so terrible if -it’s padded when sent to the dirauths… it would just needlessly take up -bandwidth without providing any privacy benefits.

-

5. Anonymity Considerations

-

Adversaries being able to determine that two parties are -communicating via KMNWP is beyond the threat model of this protocol. At -a minimum, it is trivial to determine that a KMNWP handshake is being -performed, due to the length of each handshake message, and the fixed -positions of the various public keys.

-

6. Security Considerations

-

It is imperative that implementations use ephemeral keys for every -handshake as the security properties of the Kyber KEM are totally lost -if keys are ever reused.

-

Kyber was chosen as the KEM algorithm due to it’s conservative -parameterization, simplicty of implementation, and high performance in -software. It is hoped that the addition of a quantum resistant algorithm -will provide forward secrecy even in the event that large scale quantum -computers are applied to historical intercepts.

-

7. Acknowledgments

-

I would like to thank Trevor Perrin for providing feedback during the -design of this protocol, and answering questions regarding Noise.

-

Appendix A. References

-

Appendix A.1 Normative -References

-

Appendix A.2 Informative -References

-

Appendix B. Citing This -Document

-

Appendix B.1 Bibtex Entry

-

Note that the following bibtex entry is in the IEEEtran bibtex style -as described in a document called “How to Use the IEEEtran BIBTEX -Style”.

-
@online{KatzMixWire,
+} Ciphertext;
+

+ Notes: +

  • + The ciphertext_length field includes the + Noise protocol overhead of 16 bytes, for the Noise Transport + message containing the Ciphertext. +

+ All outgoing Message(s) are preceded by a Noise Transport + Message containing a CiphertextHeader, + indicating the size of the Noise Transport Message transporting + the Message Ciphertext. After generating both Noise Transport + Messages, the sender MUST call the Noise CipherState + Rekey() operation. +

+ To receive incoming Ciphertext messages, first the Noise + Transport Message containing the CiphertextHeader is consumed + off the network, authenticated and decrypted, giving the + receiver the length of the Noise Transport Message containing + the actual message itself. The second Noise Transport Message is + consumed off the network, authenticated and decrypted, with the + resulting message being returned to the caller for processing. + After receiving both Noise Transport Messages, the receiver MUST + call the Noise CipherState Rekey() operation. +

+ Implementations MUST immediately terminate the session any of + the DecryptWithAd() operations fails. +

+ Implementations MUST immediately terminate the session if an + unknown command is received in a Message, or if the Message is + otherwise malformed in any way. +

+ Implementations MAY impose a reasonable idle timeout, and + terminate the session if it expires. +

3. Predefined Commands

3.1 The no_op Command

+ The no_op command is a command that + explicitly is a No Operation, to be used to implement + functionality such as keep-alives and or application layer + padding. +

+ Implementations MUST NOT send any message payload accompanying + this command, and all received command data MUST be discarded + without interpretation. +

3.2 The disconnect Command

+ The disconnect command is a command that is + used to signal explicit session termination. Upon receiving a + disconnect command, implementations MUST interpret the command + as a signal from the peer that no additional commands will be + sent, and destroy the cryptographic material in the receive + CipherState. +

+ While most implementations will likely wish to terminate the + session upon receiving this command, any additional behavior is + explicitly left up to the implementation and application. +

+ Implementations MUST NOT send any message payload accompanying + this command, and MUST not send any further traffic after + sending a disconnect command. +

3.3 The send_packet Command

+ The send_packet command is the command that + is used by the initiator to transmit a Sphinx Packet over the + network. The command’s message is the Sphinx Packet destined for + the responder. +

+ Initiators MUST terminate the session immediately upon reception + of a send_packet command. +

4. Command Padding

+ We use traffic padding to hide from a passive network observer + which command has been sent or received. +

+ Among the set of padded commands we exclude the + Consensus command because it’s contents are a + very large payload which is usually many times larger than our + Sphinx packets. Therefore we only pad these commands: +

+ GetConsensus NoOp Disconnect SendPacket RetrieveMessage MessageACK + Message MessageEmpty +

+ However we split them up into two directions, client to server and + server to client because they differ in size due to the difference + in size between SendPacket and + Message: +

+ Client to Server commands: +

+ NoOp SendPacket Disconnect RetrieveMessage GetConsensus +

+ Server to client commands: +

+ Message MessageACK MessageEmpty +

+ The GetConsensus command is a special case + because we only want to pad it when it’s sent over the mixnet. We + don’t want to pad it when sending to the dirauths. Although it + would not be so terrible if it’s padded when sent to the dirauths… + it would just needlessly take up bandwidth without providing any + privacy benefits. +

5. Anonymity Considerations

+ Adversaries being able to determine that two parties are + communicating via KMNWP is beyond the threat model of this + protocol. At a minimum, it is trivial to determine that a KMNWP + handshake is being performed, due to the length of each handshake + message, and the fixed positions of the various public keys. +

6. Security Considerations

+ It is imperative that implementations use ephemeral keys for every + handshake as the security properties of the Kyber KEM are totally + lost if keys are ever reused. +

+ Kyber was chosen as the KEM algorithm due to it’s conservative + parameterization, simplicty of implementation, and high + performance in software. It is hoped that the addition of a + quantum resistant algorithm will provide forward secrecy even in + the event that large scale quantum computers are applied to + historical intercepts. +

7. Acknowledgments

+ I would like to thank Trevor Perrin for providing feedback during + the design of this protocol, and answering questions regarding + Noise. +

Appendix A. References

Appendix A.1 Normative References

+

Appendix A.2 Informative References

+

Appendix B. Citing This Document

Appendix B.1 Bibtex Entry

+ Note that the following bibtex entry is in the IEEEtran bibtex + style as described in a document called How to Use the + IEEEtran BIBTEX Style. +

+@online{KatzMixWire,
 title = {Katzenpost Mix Network Wire Protocol Specification},
 author = {Yawning Angel},
 url = {https://github.com/katzenpost/katzenpost/blob/master/docs/specs/wire-protocol.rst},
 year = {2017}
-}
-

XWING

-

Manuel Barbosa, Deirdre Connolly, João Diogo Duarte, Aaron Kaiser, -Peter Schwabe, Karoline Varner, Bas Westerbaan “X-Wing: The Hybrid KEM -You’ve Been Looking For”, https://eprint.iacr.org/2024/039.pdf

-

NOISE

-

Perrin, T., “The Noise Protocol Framework”, May 2017, -https://noiseprotocol.org/noise.pdf

-

NOISEHFS

-

Weatherley, R., “Noise Extension: Hybrid Forward Secrecy”, -https://github.com/noiseprotocol/noise_hfs_spec/blob/master/output/noise_hfs.pdf

-

PQNOISE

-

Yawning Angel, Benjamin Dowling, Andreas Hülsing, Peter Schwabe and -Florian Weber, “Post Quantum Noise”, 2022, -https://eprint.iacr.org/2022/539.pdf

-

RFC2119

-

Bradner, S., “Key words for use in RFCs to Indicate Requirement -Levels”, BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, -https://www.rfc-editor.org/info/rfc2119

-

RFC5246

-

Dierks, T. and E. Rescorla, “The Transport Layer Security (TLS) -Protocol Version 1.2”, RFC 5246, DOI 10.17487/RFC5246, August 2008, -https://www.rfc-editor.org/info/rfc5246

-

RFC7748

-

Langley, A., Hamburg, M., and S. Turner, “Elliptic Curves for -Security”, RFC 7748, DOI 10.17487/RFC7748, January 2016, -http://www.rfc-editor.org/info/rfc7748

+} +

XWING. Manuel Barbosa, Deirdre Connolly, João Diogo Duarte, Aaron Kaiser, Peter Schwabe, + Karoline Varner, Bas Westerbaan, X-Wing: The Hybrid KEM You’ve Been Looking + For. https://eprint.iacr.org/2024/039.pdf

NOISE. Perrin, T., The Noise Protocol Framework, May 2017. https://noiseprotocol.org/noise.pdf

NOISEHFS. Weatherley, R., Noise Extension: Hybrid Forward Secrecy. https://github.com/noiseprotocol/noise_hfs_spec/blob/master/output/noise_hfs.pdf

PQNOISE. Yawning Angel, Benjamin Dowling, Andreas Hülsing, Peter Schwabe and Florian Weber, + Post Quantum Noise, September 2023. https://eprint.iacr.org/2022/539.pdf

RFC2119. Bradner, S., Key words for use in RFCs to Indicate Requirement Levels, + BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997. https://www.rfc-editor.org/info/rfc2119

RFC5246. Dierks, T. and E. Rescorla, The Transport Layer Security (TLS) Protocol Version + 1.2, RFC 5246, DOI 10.17487/RFC5246, August 2008. https://www.rfc-editor.org/info/rfc5246 +

RFC7748.  Langley, A., Hamburg, M., and S. Turner, Elliptic Curves for Security, + RFC 7748, DOI 10.17487/RFC7748, January 2016. http://www.rfc-editor.org/info/rfc7748

\ No newline at end of file diff --git a/hugo.yaml b/hugo.yaml index 5012960fb..77014e834 100644 --- a/hugo.yaml +++ b/hugo.yaml @@ -148,7 +148,7 @@ params: # If you want this feature, but occasionally need to remove the "Feedback" section from a single page, # add "hide_feedback: true" to the page's front matter. feedback: - enable: true + enable: false # The responses that the user sees after clicking "yes" (the page was helpful) or "no" (the page was not helpful). 'yes': >- Glad to hear it! Please tell us how we can improve. @@ -177,19 +177,19 @@ params: # icon: fab fa-stack-overflow # desc: Practical questions and curated answers # Developer relevant links. These will show up on right side of footer and in the community page if you have one. - developer: - - name: GitHub - url: https://github.com/google/docsy - icon: fab fa-github - desc: Development takes place here! - - name: Slack - url: https://example.org/slack - icon: fab fa-slack - desc: Chat with other project developers - - name: Developer mailing list - url: https://example.org/mail - icon: fa fa-envelope - desc: Discuss development issues around the project +# developer: +# - name: GitHub +# url: https://github.com/google/docsy +# icon: fab fa-github +# desc: Development takes place here! +# - name: Slack +# url: https://example.org/slack +# icon: fab fa-slack +# desc: Chat with other project developers +# - name: Developer mailing list +# url: https://example.org/mail +# icon: fa fa-envelope +# desc: Discuss development issues around the project module: # Uncomment the next line to build and serve using local docsy clone declared in the named Hugo workspace: diff --git a/source/docbook/Admin_guide/source/en/book.xml b/source/docbook/Admin_guide/source/en/book.xml index c111fef73..efc0614d1 100644 --- a/source/docbook/Admin_guide/source/en/book.xml +++ b/source/docbook/Admin_guide/source/en/book.xml @@ -1,5 +1,14 @@ + + - &program_name; administrator's guide + &program_name; administration guide Introduction To Do - - - diff --git a/source/docbook/Admin_guide/source/en/components.xml b/source/docbook/Admin_guide/source/en/components.xml index 5428cccc8..eda6b1e25 100644 --- a/source/docbook/Admin_guide/source/en/components.xml +++ b/source/docbook/Admin_guide/source/en/components.xml @@ -1,6 +1,6 @@ - @@ -27,7 +27,7 @@ --> ]> -
+
Components and configuration of the &program_name; mixnet This section of the &program_name; technical documentation provides an introduction to the software components that make up &program_name; and guidance on how to configure each @@ -56,9 +56,14 @@ The pictured element types correspond to discrete client and server programs that &program_name; requires to function. + - + + + + + The mix network contains an n-layer topology of mix-nodes, with @@ -1366,4 +1371,4 @@ ldMtDsvvc9KUfE4I0+c+XQ==
-
+ diff --git a/source/docbook/Admin_guide/source/en/docker-config-appendix.xml b/source/docbook/Admin_guide/source/en/docker-config-appendix.xml index 70441c204..f0a320bc0 100644 --- a/source/docbook/Admin_guide/source/en/docker-config-appendix.xml +++ b/source/docbook/Admin_guide/source/en/docker-config-appendix.xml @@ -1,6 +1,6 @@ - @@ -28,7 +28,7 @@ --> ]> -
+
Appendix: Configuration files from the Docker test mixnet As an aid to adminstrators implementing a &program_name; mixnet, this appendix provides lightly edited examples of configuration files for each &program_name; node type. These @@ -484,4 +484,4 @@
-
+ diff --git a/source/docbook/Admin_guide/source/en/docker.xml b/source/docbook/Admin_guide/source/en/docker.xml index c6c6ea248..141ef2c1f 100644 --- a/source/docbook/Admin_guide/source/en/docker.xml +++ b/source/docbook/Admin_guide/source/en/docker.xml @@ -1,6 +1,6 @@ - @@ -28,7 +28,7 @@ --> ]> -
+
Using the &program_name; Docker test network &program_name; provides a ready-to-deploy Docker @@ -458,9 +458,14 @@
Test network topology + - + + + + +
On the left, the Client transmits a message (shown by @@ -688,4 +693,4 @@
-
+ diff --git a/source/docbook/EchoMix.xpr b/source/docbook/EchoMix.xpr deleted file mode 100644 index e12930f77..000000000 --- a/source/docbook/EchoMix.xpr +++ /dev/null @@ -1,127 +0,0 @@ - - - - - - - - - enable.project.master.files.support - true - - - scenario.associations - - - - Specificatons/source/en/book.xml - - - - 6/docbook/docbook5.framework/DocBook 5/DocBook PDF - - - - - XSL - - - - - 2 - - - - - - Specificatons/source/en/sphinx.xml - - - - 6/docbook_blogging/docbook_5_blogging_extension.framework/DocBook 5 - Blogging Extension/DocBook HTML - 6/docbook/docbook4.framework/DocBook 4/DocBook HTML - - - - - XSL - XSL - - - - - 2 - 2 - - - - - - Specificatons/source/en/certificate.xml - - - - 6/docbook/docbook4.framework/DocBook 4/DocBook PDF - - - - - XSL - - - - - 2 - - - - - - Specificatons/source/en/client2.xml - - - - 6/docbook/docbook4.framework/DocBook 4/DocBook PDF - - - - - XSL - - - - - 2 - - - - - - Admin_guide/source/en/components.xml - - - - 6/docbook/docbook4.framework/DocBook 4/DocBook HTML - - - - - XSL - - - - - 2 - - - - - - - - - - - - - \ No newline at end of file diff --git a/source/docbook/Specificatons/source/en/book.xml b/source/docbook/Specificatons/source/en/book.xml index ae0a08b7e..1fb2b1367 100644 --- a/source/docbook/Specificatons/source/en/book.xml +++ b/source/docbook/Specificatons/source/en/book.xml @@ -43,7 +43,7 @@ - + git add diff --git a/source/docbook/Specificatons/source/en/kemsphinx.xml b/source/docbook/Specificatons/source/en/kemsphinx.xml index 8ad93303b..8ef647c95 100644 --- a/source/docbook/Specificatons/source/en/kemsphinx.xml +++ b/source/docbook/Specificatons/source/en/kemsphinx.xml @@ -28,7 +28,7 @@ We’ll express our KEM Sphinx header in pseudo code. The Sphinx body will be exactly the same as - SPHINXSPEC. Our basic KEM API + Our basic KEM API has three functions: @@ -117,7 +117,7 @@ func DECAPSULATE(my_privkey, their_pubkey) []byte {
2.2 KEM Combiner - The KEM Combiners paper KEMCOMB + The KEM Combiners paper makes the observation that if a KEM combiner is not security preserving then the resulting hybrid KEM will not have IND-CCA2 security if one of the composing KEMs does not have IND-CCA2 @@ -258,7 +258,7 @@ for i := 0; i < num_hops; i++ { - Same as in SPHINXSPEC except for + Same as in except for the fact that each routing info slot is now increased by the size of the KEM ciphertext. @@ -326,34 +326,30 @@ sphinx_header.mac = mac
Appendix A. References - - KEMCOMB - - -Federico Giacon, Felix Heuer, Bertram Poettering, -"KEM Combiners", -2018 -https://link.springer.com/chapter/10.1007/978-3-319-76578-5_7>PKC - - - SPHINX09 - - -Danezis, G., Goldberg, I., -"Sphinx: A Compact and Provably Secure Mix Format\", -DOI 10.1109/SP.2009.15, -May 2009, -https://cypherpunks.ca/~iang/pubs/Sphinx_Oakland09.pdf - - - SPHINXSPEC - - -Angel, Y., Danezis, G., Diaz, C., Piotrowska, A., Stainton, D., -"Sphinx Mix Network Cryptographic Packet Format Specification" -July 2017, -https://github.com/katzenpost/katzenpost/blob/master/docs/specs/sphinx.md - + + + KEMCOMB + Federico Giacon, Felix Heuer, Bertram Poettering, "KEM Combiners", 2018. + https://link.springer.com/chapter/10.1007/978-3-319-76578-5_7 + + + + SPHINX09 + Danezis, G., Goldberg, I., "Sphinx: A Compact and Provably Secure Mix + Format\", DOI 10.1109/SP.2009.15, May 2009. https://cypherpunks.ca/~iang/pubs/Sphinx_Oakland09.pdf + + + + SPHINXSPEC + Angel, Y., Danezis, G., Diaz, C., Piotrowska, A., Stainton, D., "Sphinx Mix + Network Cryptographic Packet Format Specification" July 2017. https://katzenpost.network/docs/specs/sphinx/ + +
diff --git a/source/docbook/Specificatons/source/en/wire-protocol.xml b/source/docbook/Specificatons/source/en/wire-protocol.xml index 740107900..9cfcbded2 100644 --- a/source/docbook/Specificatons/source/en/wire-protocol.xml +++ b/source/docbook/Specificatons/source/en/wire-protocol.xml @@ -29,7 +29,7 @@ Katzenpost Mix Network.
- xml:id="wire_protocol_introduction.title">1. Introduction + 1. Introduction The Katzenpost Mix Network Wire Protocol (KMNWP) is the custom wire protocol for all network communications to, from, and within @@ -45,11 +45,11 @@ NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted - as described in RFC2119. + as described in . The C style Presentation Language as described in - RFC5246 Section 4 is used to + Section 4 is used to represent data structures, except for cryptographic attributes, which are specified as opaque byte vectors. @@ -62,7 +62,7 @@ This protocol uses ANY Key Encapsulation Mechanism. However it’s recommended that most users select a hybrid post quantum KEM - such as Xwing. XWING + such as Xwing.
@@ -70,7 +70,7 @@ 2. Core Protocol The protocol is based on Kyber and Trevor Perrin’s Noise Protocol - Framework NOISE along with + Framework along with Post Quantum Noise paper PQNOISE. Older previous versions of our transport were based on @@ -491,64 +491,62 @@ url = {https://github.com/katzenpost/katzenpost/blob/master/docs/specs/wire-prot year = {2017} } - - XWING - - - Manuel Barbosa, Deirdre Connolly, João Diogo Duarte, Aaron - Kaiser, Peter Schwabe, Karoline Varner, Bas Westerbaan - X-Wing: The Hybrid KEM You’ve Been Looking For, - https://eprint.iacr.org/2024/039.pdf - - - NOISE - - - Perrin, T., The Noise Protocol Framework, May - 2017, https://noiseprotocol.org/noise.pdf - - - NOISEHFS - - - Weatherley, R., Noise Extension: Hybrid Forward - Secrecy, - https://github.com/noiseprotocol/noise_hfs_spec/blob/master/output/noise_hfs.pdf - - - PQNOISE - - - Yawning Angel, Benjamin Dowling, Andreas Hülsing, Peter Schwabe - and Florian Weber, Post Quantum Noise, 2022, - https://eprint.iacr.org/2022/539.pdf - - - RFC2119 - - - Bradner, S., Key words for use in RFCs to Indicate - Requirement Levels, BCP 14, RFC 2119, DOI - 10.17487/RFC2119, March 1997, - https://www.rfc-editor.org/info/rfc2119 - - - RFC5246 - - - Dierks, T. and E. Rescorla, The Transport Layer Security - (TLS) Protocol Version 1.2, RFC 5246, DOI - 10.17487/RFC5246, August 2008, - https://www.rfc-editor.org/info/rfc5246 - - - RFC7748 - - - Langley, A., Hamburg, M., and S. Turner, Elliptic Curves - for Security, RFC 7748, DOI 10.17487/RFC7748, January - 2016, http://www.rfc-editor.org/info/rfc7748 - + + + XWING + Manuel Barbosa, Deirdre Connolly, João Diogo Duarte, Aaron Kaiser, Peter Schwabe, + Karoline Varner, Bas Westerbaan, X-Wing: The Hybrid KEM You’ve Been Looking + For. https://eprint.iacr.org/2024/039.pdf + + + + NOISE + Perrin, T., The Noise Protocol Framework, May 2017. https://noiseprotocol.org/noise.pdf + + + + NOISEHFS + Weatherley, R., Noise Extension: Hybrid Forward Secrecy. https://github.com/noiseprotocol/noise_hfs_spec/blob/master/output/noise_hfs.pdf + + + + PQNOISE + Yawning Angel, Benjamin Dowling, Andreas Hülsing, Peter Schwabe and Florian Weber, + Post Quantum Noise, September 2023. https://eprint.iacr.org/2022/539.pdf + + + + RFC2119 + Bradner, S., Key words for use in RFCs to Indicate Requirement Levels, + BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997. https://www.rfc-editor.org/info/rfc2119 + + + + RFC5246 + Dierks, T. and E. Rescorla, The Transport Layer Security (TLS) Protocol Version + 1.2, RFC 5246, DOI 10.17487/RFC5246, August 2008. https://www.rfc-editor.org/info/rfc5246 + + + + + RFC7748 + Langley, A., Hamburg, M., and S. Turner, Elliptic Curves for Security, + RFC 7748, DOI 10.17487/RFC7748, January 2016. http://www.rfc-editor.org/info/rfc7748 + + diff --git a/static/admin_guide/.placeholder b/static/admin_guide/.placeholder deleted file mode 100644 index e69de29bb..000000000 diff --git a/static/admin_guide/admin_guide.pdf b/static/admin_guide/admin_guide.pdf new file mode 100644 index 000000000..e80e3f151 Binary files /dev/null and b/static/admin_guide/admin_guide.pdf differ diff --git a/static/admin_guide/pix/components-production.png b/static/admin_guide/pix/components-production.png deleted file mode 100644 index d477b8efe..000000000 Binary files a/static/admin_guide/pix/components-production.png and /dev/null differ diff --git a/static/admin_guide/pix/katzenpost-docker.png b/static/admin_guide/pix/katzenpost-docker.png deleted file mode 100644 index 836e4fbcf..000000000 Binary files a/static/admin_guide/pix/katzenpost-docker.png and /dev/null differ diff --git a/static/admin_guide/pix/mixnet-traversal.png b/static/admin_guide/pix/mixnet-traversal.png deleted file mode 100644 index 718a4d847..000000000 Binary files a/static/admin_guide/pix/mixnet-traversal.png and /dev/null differ diff --git a/static/specs/certificate.pdf b/static/specs/certificate.pdf deleted file mode 100644 index 03de6c810..000000000 Binary files a/static/specs/certificate.pdf and /dev/null differ diff --git a/static/specs/client2.pdf b/static/specs/client2.pdf deleted file mode 100644 index eab8662df..000000000 Binary files a/static/specs/client2.pdf and /dev/null differ diff --git a/static/specs/kaetzchen.pdf b/static/specs/kaetzchen.pdf deleted file mode 100644 index e57317bd6..000000000 Binary files a/static/specs/kaetzchen.pdf and /dev/null differ diff --git a/static/specs/kemsphinx.pdf b/static/specs/kemsphinx.pdf index bc38c7cc0..2ff551d38 100644 Binary files a/static/specs/kemsphinx.pdf and b/static/specs/kemsphinx.pdf differ diff --git a/static/specs/mix_decoy_stats_propagation.pdf b/static/specs/mix_decoy_stats_propagation.pdf deleted file mode 100644 index c7c3a4751..000000000 Binary files a/static/specs/mix_decoy_stats_propagation.pdf and /dev/null differ diff --git a/static/specs/mixnet.pdf b/static/specs/mixnet.pdf deleted file mode 100644 index 72ad4fd5e..000000000 Binary files a/static/specs/mixnet.pdf and /dev/null differ diff --git a/static/specs/pki.pdf b/static/specs/pki.pdf deleted file mode 100644 index a774b72ee..000000000 Binary files a/static/specs/pki.pdf and /dev/null differ diff --git a/static/specs/sphinx.pdf b/static/specs/sphinx.pdf deleted file mode 100644 index 72a2b1591..000000000 Binary files a/static/specs/sphinx.pdf and /dev/null differ diff --git a/static/specs/sphinx_replay_detection.pdf b/static/specs/sphinx_replay_detection.pdf deleted file mode 100644 index e7e47fa6d..000000000 Binary files a/static/specs/sphinx_replay_detection.pdf and /dev/null differ diff --git a/static/specs/wire-protocol.pdf b/static/specs/wire-protocol.pdf new file mode 100644 index 000000000..2c3326e43 Binary files /dev/null and b/static/specs/wire-protocol.pdf differ diff --git a/static/specs/wire_protocol.pdf b/static/specs/wire_protocol.pdf deleted file mode 100644 index e068438c0..000000000 Binary files a/static/specs/wire_protocol.pdf and /dev/null differ