├── HACKING └── index.rst ├── LICENSE ├── README.rst ├── copyright ├── drafts ├── client.rst ├── deaddrop.rst ├── decoy_traffic.rst ├── diagrams │ ├── client_aqms.png │ ├── katzenpost_active_correlation1.png │ ├── katzenpost_active_correlation2.png │ ├── katzenpost_active_correlation3.png │ ├── katzenpost_active_correlation4.png │ ├── katzenpost_active_correlation5.png │ ├── katzenpost_active_correlation6.png │ ├── katzenpost_alice_loop1.png │ ├── katzenpost_alice_loop2.png │ ├── katzenpost_loopix1.png │ ├── katzenpost_loopix2.png │ ├── katzenpost_net1.png │ ├── katzenpost_net2.png │ ├── katzenpost_net3.png │ ├── katzenpost_net4.png │ ├── mixnet_layer_cake.svg │ └── stop_and_wait_ARQ.svg ├── dspool.rst ├── key_agility.rst ├── keyserver.rst ├── mixdesign.txt ├── noname_messaging.txt ├── panda.txt ├── priority_tasks.rst └── zcash_send.rst ├── faq.rst ├── glossary.rst ├── handbook ├── index.rst ├── mailproxy.rst ├── mix_server.rst ├── nonvoting_pki.rst ├── tor.rst └── voting_pki.rst ├── mixnet_academy └── syllabus.rst ├── papers └── catshadow_threat_model │ ├── IEEEtran.cls │ ├── Makefile │ ├── bibliography.bib │ ├── catshadow.pdf │ └── catshadow.tex ├── setup.rst ├── software_bill_of_materials └── index.rst ├── specs.rst └── specs ├── certificate.rst ├── diagrams └── replay1.png ├── end_to_end.rst ├── kaetzchen.rst ├── lioness.rst ├── mailproxy_user_interface.rst ├── mixnet.rst ├── pki.rst ├── sphinx.rst ├── sphinx_replay_detection.rst └── wire-protocol.rst /HACKING/index.rst: -------------------------------------------------------------------------------- 1 | 2 | ================== 3 | HACKING Katzenpost 4 | ================== 5 | 6 | 7 | Getting started in Katzenpost development 8 | ========================================= 9 | 10 | This guide assumes you are familiar with golang, 11 | git and Unix like operating system environment. 12 | 13 | 14 | Overview of our git repositories 15 | -------------------------------- 16 | 17 | We do some additional ticket tracking in: 18 | 19 | * mixnet_uprising - Repository for tracking open tasks for the 20 | Katzenpost mixnet framework. 21 | 22 | 23 | Our specs, drafts and other documents are in: 24 | 25 | * docs - The documentation is here with the exception of the 26 | website. This includes the design specifications as well as the 27 | document you are currently reading. 28 | 29 | 30 | The mix server and directory authority libraries both make use 31 | of our core library: 32 | 33 | * core - Core library 34 | 35 | * server - Mix server 36 | 37 | * authority - Mix PKI, nonvoting and voting Directory Authority servers and clients 38 | 39 | * tools - Tools are programs that we use for testing and debugging. 40 | 41 | Our core library's wire protocol depends on our fork 42 | of the golang noise library: 43 | 44 | * noise - The Katzenpost fork of flynn's golang Noise crypto library 45 | implementation which has the ablity to use the New Hope Simple 46 | post quantum hybrid key exchange for forward secrecy. 47 | 48 | 49 | Clients also use the core library: 50 | 51 | * minclient - Minimal client library which is the basis for all 52 | other mix clients. 53 | 54 | * mailproxy - High-level client library with optional reliability and 55 | optional SMTP and POP3 listeners. 56 | 57 | * client - Experimental client library implementing proper Loopix decoy 58 | traffic et cetera. 59 | 60 | 61 | Our website: 62 | 63 | * website - The Katzenpost website 64 | 65 | 66 | The rest of these repositories do not currently have a maintainer 67 | associated with them and it is likely they have bitrot: 68 | 69 | * bindings - Language bindings for Java and Python. STATUS: NOT finished. 70 | 71 | * nixops - NixOS automated configuration for Katzenpost server components. 72 | 73 | * nixpkg - NixOS packages for Katzenpost components. 74 | 75 | * pykatzenpost - Python client library for Katzenpost. 76 | 77 | * katzsim - Client simulator for load testing mix servers. 78 | 79 | * katzenpost-android-mail - A Katzenpost client, based on K-9 Mail. 80 | 81 | * pykatzen-auth - Optional Katzenpost server authentication module in python. 82 | 83 | 84 | development workflow 85 | -------------------- 86 | 87 | 0. Acquire a recent version of golang (go1.11 or later) so that 88 | you can use the go-modules features for dependency version pinning! 89 | Read about go-modules here: 90 | 91 | * https://github.com/golang/go/wiki/Modules 92 | 93 | 1. Setup proper golang environment variables such 94 | as GOPATH, GOROOT and GO111MODULE, for example: 95 | :: 96 | 97 | export GO111MODULE=on 98 | export GOPATH=/home/user/gopath 99 | export GOROOT=/home/user/code/go 100 | 101 | 2. Checkout the latest master branch of the component you 102 | are interested in building: 103 | :: 104 | 105 | cd $GOPATH/src/github.com/katzenpost/ 106 | git clone https://github.com/katzenpost/server.git 107 | cd server 108 | git checkout master 109 | 110 | 3. Edit the source code and make it do cool stuff. 111 | 112 | 4. Track a new dependency with go-modules: 113 | :: 114 | 115 | cd $GOPATH/src/github.com/katzenpost/server/ 116 | go get github.com/foo/bar@v1.2.3 117 | 118 | Or perhaps you'd like to build with the master branch of such a dependency: 119 | :: 120 | 121 | cd $GOPATH/src/github.com/katzenpost/server/ 122 | go get github.com/foo/bar@master 123 | 124 | 5. Build the binary. 125 | :: 126 | 127 | cd $GOPATH/src/github.com/katzenpost/server/cmd/server 128 | go build 129 | 130 | 131 | client and server internals 132 | --------------------------- 133 | 134 | The Katzenpost server repository has several coding themes which you 135 | should become familiar with before making a contribution. The server 136 | must not have any unbounded resource consumption such as spawning new 137 | go routines for example. 138 | 139 | 140 | the Worker type 141 | ``````````````` 142 | 143 | Katzenpost is NOT crash-only software! Everything has a proper 144 | shutdown code path unlike many golang examples on the 145 | Internet. Struct types which act as worker goroutines MUST be a 146 | composite struct type with the Worker type which is defined in our 147 | "core" repository here: 148 | 149 | * https://github.com/katzenpost/core/blob/master/worker/worker.go 150 | 151 | Correctly implementing a composite Worker type means that your 152 | code uses the Worker's Go method to spawn new goroutines and will 153 | halt it's runtime loop upon receiving from the channel returned 154 | by the Worker's HaltCh method. There are plenty of examples of this 155 | in our code. 156 | 157 | 158 | the Channels library 159 | ```````````````````` 160 | 161 | The Katzenpost mix server and mailproxy both use the EApache Channels library: 162 | 163 | * https://gopkg.in/eapache/channels.v1 164 | 165 | Channels API docs: 166 | 167 | * https://godoc.org/gopkg.in/eapache/channels.v1 168 | 169 | Channels code: 170 | 171 | * https://github.com/eapache/channels/tree/v1.1.0 172 | 173 | The extended functionality of these channels is well suited to 174 | building various kinds of computational pipelines. In particular 175 | throughout the code base you will see "infinite buffered channels" 176 | used as a queue connecting the schedulers of pipeline stages. 177 | More discussion on this pipeline model is below in the next section. 178 | 179 | 180 | the SEDA model 181 | `````````````` 182 | 183 | The Katzenpost server is essentially a software based router and as 184 | such it utilizes three active queue management algorithms 185 | (AQMs). These queues are called the ingress queue, the mix strategy 186 | queue and the egress queue. We utilize a computational model called 187 | SEDA or Staged Even Driven Architecture where these three queues are 188 | pipelined together. 189 | 190 | At each stage of the pipeline there is a thread pool of workers which 191 | perform the computation for that stage. Between each of these stages 192 | is an AQM which can drop work tasks and can have dynamic load shedding 193 | properties so that performance degrades gracefully with respect to 194 | increased work load. 195 | 196 | If you'd like to learn more about the SEDA computation model we 197 | recommend reading: 198 | 199 | * "SEDA: An Architecture for Well-Conditioned, Scalable Internet Services", 200 | http://www.sosp.org/2001/papers/welsh.pdf 201 | 202 | 203 | the mix strategy 204 | ```````````````` 205 | 206 | Currently Katzenpost only supports the Poisson mix strategy and 207 | therefore the mix strategy AQM is implemented using a priority 208 | queue. To learn more about the Poisson mix strategy you should read: 209 | 210 | * "The Loopix Anonymity System", 211 | https://arxiv.org/pdf/1703.00536.pdf 212 | 213 | * "Stop-and-Go-MIXes Providing Probabilistic Anonymity in an Open System", 214 | https://www.freehaven.net/anonbib/cache/stop-and-go.pdf 215 | 216 | 217 | Mix Pipeline Diagram 218 | -------------------- 219 | 220 | :: 221 | 222 | .-----------. .------------. .---------. 223 | | Listeners | ---> | incoming | ---> | crypto | 224 | `-----------' | connection | | workers | 225 | ▲ | workers | `---------' 226 | | `------------' | 227 | | | 228 | | V 229 | | .------------. .----------. 230 | | connector | | mix | 231 | network link <--- | packet | <--- | strategy | 232 | | dispatcher | | AQM | 233 | `------------' `----------' 234 | 235 | 236 | Provider Pipeline Diagram 237 | ------------------------- 238 | 239 | :: 240 | 241 | .-----------. .------------. .---------. .----------. .-------------. 242 | | Listeners | ---> | incoming | ---> | crypto | ---> | provider | ---> | user spools | 243 | `-----------' | connection | | workers | | packet | `-------------' 244 | ▲ | workers | `---------' | workers | .-----------------. 245 | | `------------' | `----------' .--------> | external plugin | 246 | | | | | | | workers | 247 | | V | '_ | `-----------------' 248 | | .------------. .----------. V '-------| .-----------------. 249 | | connector | | mix | .-----------. | | external plugin | 250 | network link <--- | packet | <--- | strategy | | kaetzchen | |--------> | workers | ....-----. 251 | | dispatcher | | AQM | | workers | | `-----------------' `\ 252 | `------------' `----------' `-----------' | .-----------------. | 253 | _ | | | external plugin | | 254 | _ |\ | '--------> | workers | | 255 | |\ \ _' `-----------------' | 256 | \ '-----------------------------' | 257 | \ | 258 | \ _' 259 | '------------------------------------------------------------------------------------------' 260 | 261 | 262 | Exercising Katzenpost with your own private mixnet 263 | -------------------------------------------------- 264 | 265 | For many circumstances it is easier and more appropriate to perform your 266 | integration testing on a mixnet deployed to a single machine, a remote 267 | server which could be a VM instance. In that case I would compile my katzenpost 268 | binaries locally and upload them to my remote server and then run a bash script 269 | to restart the services. 270 | 271 | You will most likely want to turn on debug logging for all the mixnet services. 272 | Checking these debug log can help you determine if the behavior is correct. 273 | Certainly you could do all of this and add extra debug log statements to help 274 | track down a problem that would otherwise be very difficult to detect. 275 | 276 | 277 | Making a code contribution 278 | -------------------------- 279 | 280 | 0. Meet the Katzenpost developers 281 | 282 | Chat with the Katzenpost developers on irc: #katzenpost on the OFTC 283 | network or reach out to us on our mailing list: 284 | https://lists.mixnetworks.org/listinfo/katzenpost 285 | 286 | It is a good idea to discuss your code change with us before 287 | investing your time in writing the code. 288 | 289 | These days the IRC channel is not so active. Try contacting us over the mailing list. 290 | 291 | 1. Write a specification document 292 | 293 | If your code change is complex or requires us to change any of our 294 | protocols, you will need to first propose a draft specification 295 | document. You can do this by forking our docs repository, creating 296 | a new git branch with your specification document and then 297 | submitting a pull-request. 298 | 299 | 2. Document the work task 300 | 301 | Open a ticket to document your feature addition or code change using 302 | the repository's issue tracker. 303 | 304 | 3. Testing your code 305 | 306 | Your code should have unit tests. However you may wish to gain 307 | extra confidence in your code addition by using our kimchi tool. 308 | 309 | 4. Request code review 310 | 311 | Finally you can submit a pull-request for your code changes or 312 | additions. We will review your code. There may be several rounds 313 | of code reviews until the code is of sufficient quality to be 314 | merged. 315 | -------------------------------------------------------------------------------- /README.rst: -------------------------------------------------------------------------------- 1 | migrated to monorepo https://github.com/katzenpost/katzenpost/issues/1 2 | -------------------------------------------------------------------------------- /copyright: -------------------------------------------------------------------------------- 1 | 2 | Files: specs/LIONESS.txt specs/wire-protocol.txt 3 | Copyright: 4 | Copyright (C) 2017 Yawning Angel 5 | License: Creative Commons Attribution-ShareAlike 4.0 International License 6 | 7 | Files: specs/end_to_end.txt, specs/mixnet.txt, specs/sphinx.txt, specs/pki.txt 8 | Copyright: 9 | Copyright (C) 2017 Yawning Angel, George Danezis, Claudia Diaz, Ania Piotrowska, David Stainton 10 | License: Creative Commons Attribution-ShareAlike 4.0 International License 11 | -------------------------------------------------------------------------------- /drafts/deaddrop.rst: -------------------------------------------------------------------------------- 1 | Katzenpost Dead Drop Extension 2 | ****************************** 3 | 4 | | David Stainton 5 | 6 | Version 0 7 | 8 | .. rubric:: Abstract 9 | 10 | This document describes the message dead drop service. The dead drop 11 | service can be used to compose messaging systems with stronger 12 | location hiding properties, and increased resistance to longterm 13 | statistical disclosure attacks also known as intersection attacks. 14 | 15 | .. contents:: :local: 16 | 17 | 18 | 1. Introduction 19 | =============== 20 | 21 | The dead drop service is implemented as a Provider side 22 | autoresponder service [KAETZCHEN]_, it provides clients with the 23 | ability to retrieve messages from remote Providers. This 24 | unidirectional dead drop scheme should leak less information than a 25 | bidirectional dead drop. This document does not describe the full 26 | design of a message system. Instead we merely specify a mixnet dead 27 | drop service which can be one of many design elements used to 28 | compose a messaging system. 29 | 30 | 1.1 Conventions Used in This Document 31 | ------------------------------------- 32 | 33 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 34 | "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 35 | document are to be interpreted as described in [RFC2119]_. 36 | 37 | 1.2 Terminology 38 | --------------- 39 | 40 | ``Provider`` - A service, operated by a third party, that Clients 41 | communicate directly with to communicate with the Mixnet. It is 42 | responsible for Client authentication, forwarding outgoing 43 | messages to the Mixnet, and storing incoming messages for the 44 | Client. The Provider MUST have the ability to perform 45 | cryptographic operations on the relayed messages. 46 | 47 | ``SURB`` - Single Use Reply Block is a cryptographic delivery 48 | token which was first introduced by the Mixminion design 49 | [MIXMINION]_ and revised by the Sphinx cryptographic packet format. 50 | [SPHINX]_ [SPHINXSPEC]_ 51 | 52 | 2. Overview 53 | =========== 54 | 55 | A client possessing the dead drop address sends a message to a dead 56 | drop just like a normal Katzenpost message [KATZMIXE2E]_. However 57 | the receiver of the message uses the dead drop Kaetzchen service to 58 | retrieve messages by sending one or more SURBs to the dead drop. 59 | 60 | Consider this diagram where Alice sends a message to Bob's spool on 61 | his remote Provider: 62 | 63 | .. image:: diagrams/katzenpost_net1.png 64 | :alt: diagram 5 65 | :align: center 66 | 67 | 68 | At a latter time, Bob sends a SURB to his remote Provider to retrieve 69 | a message from his spool: 70 | 71 | .. image:: diagrams/katzenpost_net2.png 72 | :alt: diagram 6 73 | :align: center 74 | 75 | 76 | The messages return trip from remote Provider to Bob's local Provider 77 | can look like this: 78 | 79 | .. image:: diagrams/katzenpost_net3.png 80 | :alt: diagram 7 81 | :align: center 82 | 83 | 84 | Finally, Bob retrieves the message from his local Provider: 85 | 86 | .. image:: diagrams/katzenpost_net4.png 87 | :alt: diagram 8 88 | :align: center 89 | 90 | 3. Protocol Messages 91 | ==================== 92 | 93 | The DeadDropRequest is sent to the dead drop service with a SURB 94 | that is used to send the DeadDropResponse back to the client. 95 | 96 | 3.1 DeadDropRequest message 97 | --------------------------- 98 | 99 | Dead drop requests are authenticated by the Provider's user 100 | authentication database similar to how Katzenpost Providers 101 | authenticate client wire protocol connections, as detailed in [KATZMIXWIRE]_ 102 | and [KATZMIXE2E]_. In this case, we are coupling the User and AuthToken 103 | fields in the DeadDropRequest to provide the needed authentication 104 | information. 105 | 106 | :: 107 | 108 | { 109 | "Version": 0, 110 | "User": "Alice", 111 | "AuthToken": "yczzyO30cLKtoh/BDAOfyIDjb6nwe6l/ebuVDDhN+Q8boxB7SHG8IS4NFp62LEZg", 112 | "Ack": 0 113 | } 114 | 115 | 116 | * The User field is a string which the Provider associates with a 117 | X25519 public key AND a message spool. 118 | 119 | * The AuthToken field is a base64 encoded ciphertext blob produced by 120 | encrypting a zero length payload with 121 | `Noise_K_25519_ChaChaPoly_Blake2b` using the user's link key, 122 | which the Katzenpost system uses for link layer authentication 123 | [KATZMIXWIRE]_. 124 | 125 | The encrypted and authenticated blob has the following structure: 126 | 127 | :: 128 | 129 | // XXX Correct? 130 | 131 | struct { 132 | /* Noise protocol fields. */ 133 | opaque noise_e[32]; /* The Noise handshake `e`. */ 134 | opaque noise_mac[16]; /* The Noise ciphertext MAC. */ 135 | } BlockCiphertext; 136 | 137 | 138 | * The Ack field defaults to zero unless the user has had a previous 139 | interaction where a DeadDropResponse was received. In that case the 140 | previously received Sequence numbers are placed into this Ack field 141 | which causes the deaddrop service to purge the associated messages. 142 | 143 | 3.2. DeadDropResponse message 144 | ----------------------------- 145 | 146 | :: 147 | 148 | { 149 | "Version": 0, 150 | "StatusCode": 0, 151 | "QueueHint": 0, 152 | "Sequence": 0, 153 | "Payload": "" 154 | } 155 | 156 | * The StatusCode field is used to report errors to the client if any. 157 | Valid status codes are: 158 | 159 | :: 160 | 161 | enum { 162 | status_ok(0), /* No error condition. It SHOULD be 163 | accompanied with a valid message payload. */ 164 | status_syntax_error(1), /* The request was malformed. */ 165 | status_no_identity(2), /* No such identity was found. */ 166 | status_auth_error(3), /* Authentication failure. */ 167 | } StatusCodes; 168 | 169 | 170 | * QueueHint is used to inform the client how many more messages are 171 | queued. 172 | 173 | * Sequence is used by the server to decide when to permanently 174 | delete a message. When the next request message is received 175 | containing this sequence number then the associated message is 176 | purged. 177 | 178 | * Payload is used to encapsulate one or more messages. 179 | 180 | 4. Dead Drop Descriptor 181 | ======================= 182 | 183 | Dead drop descriptors can be exchanged between clients to establish 184 | communication channels. 185 | 186 | :: 187 | 188 | { 189 | "Version": 0, 190 | "TimeoutUnixEpoch": 12345, 191 | "DeadDropAddress": "fe37a524ce6410a59718@provider-0.example.org" 192 | } 193 | 194 | * The TimeoutUnixEpoch field is used to specify the timeout in Unix 195 | epoch format. 196 | 197 | * The DeadDropAddress field is used to specify the dead drop slot 198 | on the remote Provider. 199 | 200 | 5. Anonymity Considerations 201 | =========================== 202 | 203 | * Collusion of Providers might make it possible to link an account 204 | on two different Providers. That is, given user's dead drop, an attacker 205 | can discover if the two Providers collude. However, this linkage 206 | may require a longterm statistical disclosure attack. In that case, 207 | these longterm attacks might not converge on success if deaddrops 208 | are rotated frequently enough. 209 | 210 | * Sending a deaddrop request with many bundled SURBs 211 | increases exposure to compulsion attack by the remote Provider. 212 | 213 | * Sending a deaddrop request with many bundled SURBs exposes the 214 | client to a potential active confirmation attack where the remote 215 | Provider uses all of the SURBs to send messages concurrently. The 216 | adversary then tries to determine if there is an observed 217 | confirmation on the network exposing the destination of these 218 | SURB reply messages. In the [LOOPIX]_ Provider model the attacker 219 | might try to determine if any of the Providers receive slightly 220 | more messages. If the adversary has compromised one or more 221 | Providers, then the goal would be to determine if one message 222 | spool receives more messages than the rest. 223 | 224 | * Client retransmissions can be predictable behavior which allows 225 | for active confirmation attacks which can discover the client's 226 | Provider. Consider for instance Alice and Bob where Alice is a 227 | powerful adversary that wishes to discover Bob's Provider. Alice 228 | compromises the server which hosts Bob's dead drop service. 229 | Alice knows when Bob sends a Message Retrieval command. In 230 | response to these Message Retrieval commands Alice then blocks 231 | one or more Providers and sends the response to the client using 232 | the supplied SURB. If another Message Retrieval command is 233 | received, it is likely that this retransmission confirms that the 234 | SURB Response was not received by the client because of blocking 235 | messages to one or more Providers. Alice uses these active 236 | confirmation attacks in a binary search to quickly discover Bob's 237 | Provider. 238 | 239 | 6. Security Considerations 240 | ========================== 241 | 242 | * End to end message integrity and confidentiality from client to 243 | Provider is ensured by the Sphinx cryptographic packet format. 244 | 245 | * The dead drop service authenticates message retrieval requests 246 | using a cryptographic token produced using the one-way Noise 247 | pattern *K*, in the construction `Noise_K_25519_ChaChaPoly_Blake2b`. 248 | 249 | 7. Future Work 250 | ============== 251 | 252 | It should be possible to increase the communication channel 253 | efficiency by sending DeadDropRequest messages supplied with 254 | multiple SURBs. However, this must be carefully balanced with the 255 | resulting exposure to statistical disclosure and compulsion 256 | attacks. 257 | 258 | Appendix A. References 259 | ====================== 260 | 261 | Appendix A.1 Normative References 262 | --------------------------------- 263 | 264 | .. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 265 | Requirement Levels", BCP 14, RFC 2119, 266 | DOI 10.17487/RFC2119, March 1997, 267 | . 268 | 269 | .. [KAETZCHEN] Angel, Y., Kaneko, K., Stainton, D., 270 | "Katzenpost Provider-side Autoresponder", January 2018, 271 | . 272 | 273 | .. [NOISE] Perrin, T., "The Noise Protocol Framework", May 2017, 274 | . 275 | 276 | .. [KATZMIXE2E] Angel, Y., Danezis, G., Diaz, C., Piotrowska, A., Stainton, D., 277 | "Katzenpost Mix Network End-to-end Protocol Specification", July 2017, 278 | . 279 | 280 | Appendix A.2 Informative References 281 | ----------------------------------- 282 | 283 | .. [KATZMIXWIRE] Angel, Y. "Katzenpost Mix Network Wire Protocol Specification", June 2017, 284 | . 285 | 286 | .. [LOOPIX] Piotrowska, A., Hayes, J., Elahi, T., Meiser, S., Danezis, G., 287 | “The Loopix Anonymity System”, 288 | USENIX, August, 2017 289 | . 290 | 291 | .. [SPHINX] Danezis, G., Goldberg, I., "Sphinx: A Compact and 292 | Provably Secure Mix Format", DOI 10.1109/SP.2009.15, 293 | May 2009, . 294 | 295 | .. [SPHINXSPEC] Angel, Y., Danezis, G., Diaz, C., Piotrowska, A., Stainton, D., 296 | "Sphinx Mix Network Cryptographic Packet Format Specification" 297 | July 2017, . 298 | 299 | .. [MIXMINION] Danezis, G., Dingledine, R., Mathewsom, N., 300 | "Mixminion: Design of a Type III Anonymous Remailer Protocol" 301 | . 129 | 130 | .. [RFC7049] C. Bormannm, P. Hoffman, "Concise Binary Object Representation (CBOR)", 131 | Internet Engineering Task Force (IETF), October 2013, 132 | . 133 | 134 | Appendix A.2 Informative References 135 | ----------------------------------- 136 | 137 | .. [KATZMIXPKI] Angel, Y., Piotrowska, A., Stainton, D., 138 | "Katzenpost Mix Network Public Key Infrastructure Specification", December 2017, 139 | . 140 | -------------------------------------------------------------------------------- /drafts/keyserver.rst: -------------------------------------------------------------------------------- 1 | Katzenpost Key Discovery Extension 2 | ****************************** 3 | 4 | | Yawning Angel 5 | | Claudia Diaz 6 | | Kali Kaneko 7 | | kwadronaut 8 | | Ruben Pollan 9 | | mo 10 | | David Stainton 11 | 12 | Version 0 13 | 14 | .. rubric:: Abstract 15 | 16 | This document describes a mechanism for user identity key discovery 17 | that is to be used with the Katzenpost end to end protocol as 18 | described in [KATZMIXE2E]_ for end to end client encryption of 19 | messages. 20 | 21 | .. contents:: :local: 22 | 23 | 1. Introduction 24 | =============== 25 | 26 | This key discovery service is implemented as a Provider-side 27 | autoresponder [KAETZCHEN]_. Clients send a request message and wait 28 | to receive a response message. Keys exchanged with this service 29 | are not end to end authenticated. Authentication of keys must be 30 | done out of band. 31 | 32 | 1.1 Conventions Used in This Document 33 | ------------------------------------- 34 | 35 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 36 | "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 37 | document are to be interpreted as described in [RFC2119]_. 38 | 39 | 1.2 Terminology 40 | --------------- 41 | 42 | * ``Provider`` - A service operated by a third party that Clients 43 | communicate directly with to communicate with the Mixnet. It is 44 | responsible for Client authentication, forwarding outgoing 45 | messages to the Mixnet, and storing incoming messages for the 46 | Client. The Provider MUST have the ability to perform 47 | cryptographic operations on the relayed messages. 48 | 49 | * ``Kaetzchen`` - A Provider-side autoresponder service as defined in 50 | [KAETZCHEN]_. 51 | 52 | 2. Overview 53 | =========== 54 | 55 | A Client, Alice, may discover Bob's key by sending a 56 | KeyserverRequest to Bob's Provider and waiting for a KeyserverResponse 57 | containing Bob's key. 58 | 59 | :: 60 | 61 | .--------. .----------. .-------. .-------. 62 | | Alice | ---> | Provider | ---> | Mix | ---> | Mix | ----. 63 | `--------' `----------' `-------' `-------' `\ 64 | | 65 | .-----. .----------. / 66 | | Bob | ------> | Provider | <--------------------------------------' 67 | `-----' <------ `----------' 68 | 69 | 3. Protocol Messages 70 | ==================== 71 | 72 | The KeyserverRequest is sent to the key discovery service with a 73 | SURB that is used to send the KeyserverResponse back to the client. 74 | 75 | 3.1 KeyserverRequest Message 76 | ---------------------------- 77 | 78 | :: 79 | 80 | { 81 | "Version": 0, 82 | "User": "Alice" 83 | } 84 | 85 | Notes: 86 | 87 | * The User field specifies which identity key to retrieve. 88 | 89 | 3.2 KeyserverResponse Message 90 | ----------------------------- 91 | 92 | :: 93 | 94 | { 95 | "Version": 0, 96 | "StatusCode": 0, 97 | "User": "Alice", 98 | "PublicKey": "33BB41546AF0CC576AFA631D28B6A6CDFE4DF36CAF9038B942E3A32AC433667D" 99 | } 100 | 101 | Notes: 102 | 103 | * The StatusCode field is used to report errors to the client if any. Valid status codes are: 104 | 105 | :: 106 | 107 | enum { 108 | status_ok(0), /* No error condition. */ 109 | status_syntax_error(1), /* The request was malformed. */ 110 | status_no_identity(2), /* The specified identity was not found. */ 111 | } StatusCodes; 112 | 113 | * The User field is used to specify the identity. 114 | * The PublicKey field contains the hex encoded X25519 public 115 | identity key for the given User. 116 | 117 | 4. Client-side Behavior 118 | ======================= 119 | 120 | Clients maintain a local database of contact keys which 121 | can be in one of three states: 122 | 123 | * RECEIVED-ONLY 124 | * UNVERIFIED 125 | * VERIFIED 126 | 127 | On receiving a message from an unknown identity key included with 128 | the signed message, the key MUST be marked as RECEIVED-ONLY. 129 | 130 | In the case of a sender for whom the user only has a key flagged as 131 | RECEIVED-ONLY, and before the moment of establishing communication 132 | with such sender, the users' client SHOULD trigger a key lookup 133 | against the Kaetzchen agent specified by the sender's provider, if 134 | any. 135 | 136 | Otherwise, an identity key verified by means of an out-of-band 137 | mechanism, or in its absence a key marked as RECEIVED-ONLY will be 138 | used for end to end encryption with this identity. If such a key 139 | lookup results in a mismatch then the Client user interface MUST 140 | present a warning to the user. 141 | 142 | A given identity received via the key discovery defined in this 143 | specification MUST be marked as unverified until the Client marks 144 | it as verified by means of an out-of-band mechanism. Defining the 145 | means of verification is out of scope of this document. 146 | 147 | Clients SHOULD periodically send requests to its own key, and the 148 | UI MUST display some kind of warning in case of a mismatch or 149 | failure. Clients MAY also send warnings to already verified 150 | recipients about this failure in the lookup. 151 | 152 | 5. Anonymity Considerations 153 | =========================== 154 | 155 | // XXX David: this section doesn't make sense and needs cleanup. 156 | 157 | This mechanism allows for a malicious provider to learn about the 158 | online activity of a given user by creating dummy identities that 159 | produce a key lookup that the malicious provider can observe. 160 | 161 | Countermeasure would include applying a random delay on the send 162 | queue for the first hop ("offline send helper"), and leaving the 163 | account in an "unusable" state. This effectively limits the 164 | information leakage after the first hop. This countermeasure is 165 | also helpful to paliate the time window in which ... DISCUSS 166 | 167 | In order to avoid user enumeration attacks, every request to the 168 | Kaetzchen MUST include the lookup of one and only one key. 169 | 170 | [ The sender provider SHOULD/MAY also implement traffic rate 171 | limitations to the amount of request per unit of time that a given 172 | client can emit. This is a generic defense against spam that is 173 | also effective against user enumeration XXXTODO: CROSS-REF to some 174 | other proper spec ] 175 | 176 | (How can a provider tell if a given message is a key lookup? The 177 | side servicing a request can, but they don't know who's sending the 178 | request. The side that's sending the request can't tell :P) kali: 179 | meskio's proposal considers that this probably doesn't belong here, 180 | but the rationale is to defend against aspam 181 | 182 | It's a good idea, but it falls more under, "providers should limit 183 | how much traffic any given client can dump into the mixnet at 184 | once". yep. what do you think is the right spec to drop this 185 | consideration in? 186 | 187 | Not sure. There's a comment in the server code that says "Add rate 188 | limiting here.", past that I didn't give this much thought. ( 189 | 190 | // TODO: If clients should be rate-limited in how fast they can 191 | send // packets, this is probably the natural place to do so. 192 | ) 193 | 194 | Right now everything assumes clients are moderately well behaved. 195 | 196 | 6. Security Considerations 197 | ========================== 198 | 199 | * We rely on visual confirmation of the user ID on both ends, so 200 | homoglyphs in user IDs MUST be prohibited. 201 | 202 | 7. Future Work 203 | ============== 204 | 205 | * Key rotation implies key refreshes. How is this to be made in a 206 | way that doesn't leak info? 207 | 208 | Appendix A. References 209 | ====================== 210 | 211 | Appendix A.1 Normative References 212 | --------------------------------- 213 | 214 | .. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 215 | Requirement Levels", BCP 14, RFC 2119, 216 | DOI 10.17487/RFC2119, March 1997, 217 | . 218 | 219 | .. [KAETZCHEN] Angel, Y., Kaneko, K., Stainton, D., 220 | "Katzenpost Provider-side Autoresponder", January 2018, 221 | . 222 | 223 | Appendix A.2 Informative References 224 | ----------------------------------- 225 | 226 | .. [KATZMIXE2E] Angel, Y., Danezis, G., Diaz, C., Piotrowska, A., Stainton, D., 227 | "Katzenpost Mix Network End-to-end Protocol Specification", July 2017, 228 | . 229 | -------------------------------------------------------------------------------- /drafts/noname_messaging.txt: -------------------------------------------------------------------------------- 1 | Noname Message Protocol Specification 2 | David Stainton 3 | 4 | Version 0 5 | 6 | Abstract 7 | 8 | This document describes the Noname message protocol which is 9 | specifically designed to provide strong location hiding properties, 10 | tunable resistance to longterm statistical disclosure attacks and 11 | resistance to some active attacks. This mix network protocol 12 | essentially provides to clients reliable bidirectional communication 13 | channels. It can be used to construct messaging applications. 14 | 15 | 1. Introduction 16 | 17 | This specification is inspired by Pond and Petmail [POND] [PETMAIL] 18 | and also uses many designs from the mix network literature, 19 | especially the [LOOPIX], Katzenpost [KATZMIXNET] and [MIXMINION] 20 | systems. Compared to Katzenpost the system I describe here has a 21 | server side that is almost exactly the same except for the addition 22 | of several Provider-side mixnet services. [KAETZCHEN] 23 | 24 | This protocol uses [PANDA] to exchange channel setup information 25 | between clients, this information includes public keys for 26 | encryption AND descriptors of unidirectional dead drops 27 | [KATZDEADDROP]. We use the exchange of unidirectional channels to 28 | form bidirectional channels. We exchange multiple dead drop 29 | descriptors for reliability purposes. The highest protocol 30 | presentation specified here is that of a reliable or optionally 31 | unreliable client to client bidirection communication channel. 32 | 33 | This document is meant to be read with the accompanying 34 | specification documents: 35 | 36 | * [KATZMIXNET] - Katzenpost Mix Network Specification 37 | 38 | * [KATZDECOY] - Katzenpost Mix Network Decoy Traffic Specification 39 | 40 | * [KATZMIXPKI] - Katzenpost Mix Network Public Key 41 | Infrastructure Specification 42 | 43 | * [KATZMIXWIRE] - Katzenpost Mix Network Wire Protocol Specification 44 | 45 | * [KAETZCHEN] - Katzenpost Provider-side Autoresponder Extension 46 | 47 | * [KATZDEADDROP] - Katzenpost Dead Drop Extension 48 | 49 | 1.1 Conventions Used in This Document 50 | 51 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 52 | "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 53 | document are to be interpreted as described in [RFC2119]. 54 | 55 | 1.2 Terminology 56 | 57 | * ARQ - Automatic Repeat reQuest, a protocol scheme which 58 | uses ACKnowledgement messages AND retransmissions to achieve 59 | end to end reliability. 60 | 61 | * PANDA - Phrase Automated Nym Discovery Authentication; a 62 | variation of a Password Authenticated Key Exchange where clients 63 | have identical behavior and perform their message exchanges 64 | asynchronously with a simple server which enforces two message 65 | slots per "meeting place". See [PANDA] and [PANDASPEC] for details. 66 | 67 | * SURB - Single Use Reply Block is a cryptographic delivery 68 | token which was first introduced by the Mixminion design 69 | [MIXMINION] and revised by the Sphinx cryptographic packet format. 70 | See [SPHINX] and [SPHINXSPEC] for details. 71 | 72 | 1.3 Differences From The Katzenpost Messaging System 73 | 74 | * Herein I describe a protocol not a messaging system. We therefore 75 | do not concern ourselves with the end to end encryption but provide 76 | a cryptographic transport. Confidentiality and message integrity are 77 | protected using the link layer [KATZMIXWIRE] and sphinx encryption 78 | layers. [SPHINX] [SPHINXSPEC] 79 | 80 | * There is no universal naming scheme or inherent SPAM problem, rather 81 | clients are responsible for exchanging the channel initialization 82 | information. 83 | 84 | 2. System Overview 85 | 86 | Mixminion introduced the Single Use Reply Block, also known as a 87 | SURB which is a single-use cryptographic delivery token for latent 88 | message delivery. SURBs have a relatively short lifetime because 89 | they are essentially a mixnet packet header which is encrypted with 90 | the routing keys of several mixes and therefore expires when any of 91 | the mixes rotate their key. 92 | 93 | In the Katzenpost system this key rotation epoch is every 3 94 | hours. [KATZMIXPKI] It is NOT desirable to have long lived mix 95 | routing keys because this increases the time allowance of 96 | compulsion attacks. We conclude that SURBs are NOT suitable for 97 | establishing a bidirectional communication channel for clients that 98 | frequently go offline for time durations greater than the mix key 99 | rotation epoch. 100 | 101 | Instead a Katzenpost autoresponder [KAETZCHEN] based dead drop 102 | [KATZDEADDROP] service can be used. Unlike SURBs dead drop 103 | descriptors do not have any inherent expiration. However, for the 104 | purpose of reducing exposure to longterm statistical disclosure 105 | attacks, these descriptors shall specify an expiration. The 106 | expiration specifies how far into the future the receiver promises 107 | to check for messages in the dead drop queue. Client communication 108 | partners MUST periodically exchange new dead drop descriptors 109 | before the old dead drop descriptors expire. 110 | 111 | 3. Threat Model 112 | 113 | 3.1 Security Goals 114 | 115 | This specification document describes a messaging system with 116 | the following security goals: 117 | 118 | * strong location hiding properties: The system MUST NOT give 119 | Bob enough information to easily find Alice's location AND if 120 | a compulsion attack is used it MUST require compromising more 121 | than one mixnet node. 122 | 123 | * sender and receiver anonymity with respect to third party 124 | observers: Bob and Alice send each other messages while being 125 | certain of who will receive the messages AND while not hiding 126 | their identity to the receiver. However, third party observers 127 | will NOT be able to determine that they are even communicating 128 | with each other. 129 | 130 | * receiver unobservability: Receivers receive decoy traffic and 131 | legit traffic thereby creating uncertainty for passive network 132 | observers. 133 | 134 | * sender unobservability: Senders send decoy and legit traffic 135 | thereby creating uncertainly for passive network observers. 136 | 137 | We shall now proceed with Brian Warner's mode of analysis and 138 | quote several security goals from the [PETMAIL] document : 139 | 140 | """ 141 | * S0: Two different senders cannot tell if they're talking to the 142 | same recipient or not. 143 | 144 | * M0: The mailbox server cannot tell which message came from which 145 | sender, not even that two messages came from the same sender, nor 146 | can it determine how many senders might be configured for each 147 | recipient. 148 | 149 | * R0: The recipient can use the transport information to accurately 150 | identify the sender. 151 | 152 | * Rev0: R can revoke one sender without involving the remaining ones. 153 | """ 154 | 155 | Our security goals in short form are expressed as: 156 | 157 | S0 M0 R0 Rev0 158 | 159 | 4. Protocol Description 160 | 161 | Each client performs the [PANDA] protocol exchange using 162 | their shared passphrase. This allows clients to establish 163 | a Single Double Ratchet connection using Katzenpost dead drops. 164 | 165 | Our four point protocol plan is as follows: 166 | 167 | 1. register a remote mailbox as the dead drop for the new contact 168 | 169 | 2. create signal double ratchet keys and compose a dead drop descriptor 170 | 171 | 3. perform the PANDA exchange 172 | 173 | 4. send and receive messages 174 | 175 | 176 | X. Future Work 177 | 178 | * a more formal security analysis 179 | 180 | * Post Quantum double ratchet instead of Signal Double Ratchet 181 | 182 | * can we use Sphinc-256 signatures for anything? ;-p 183 | 184 | Y. Anonymity Considerations 185 | Z. Security Considerations 186 | 187 | Appendix A. References 188 | 189 | Appendix A.1 Normative References 190 | 191 | [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 192 | Requirement Levels", BCP 14, RFC 2119, 193 | DOI 10.17487/RFC2119, March 1997, 194 | . 195 | 196 | [LOOPIX] Piotrowska, A., Hayes, J., Elahi, T., Meiser, S., Danezis, G., 197 | “The Loopix Anonymity System”, 198 | USENIX, August 2017, 199 | . 200 | 201 | [POND] Langley, A., "Pond", November 2012, 202 | . 203 | 204 | [KATZMIXNET] Angel, Y., Danezis, G., Diaz, C., Piotrowska, A., Stainton, D., 205 | "Katzenpost Mix Network Specification", June 2017, 206 | . 207 | 208 | [KATZDECOY] Angel, Y., Danezis, G., Diaz, C., Piotrowska, A., Stainton, D., 209 | "Katzenpost Mix Network Decoy Traffic Specification", 210 | . 211 | 212 | [KATZMIXPKI] Angel, Y., Piotrowska, A., Stainton, D., 213 | "Katzenpost Mix Network Public Key Infrastructure Specification", December 2017, 214 | . 215 | 216 | [KATZMIXWIRE] Angel, Y., "Katzenpost Mix Network Wire Protocol Specification", June 2017. 217 | . 218 | 219 | [SPHINXSPEC] Angel, Y., Danezis, G., Diaz, C., Piotrowska, A., Stainton, D., 220 | "Sphinx Mix Network Cryptographic Packet Format Specification" 221 | July 2017, . 222 | 223 | [LIONESS] Angel, Y., 2017, "The LIONESS Wide-Block-Cipher", 224 | . 225 | 226 | [RFC7748] Langley, A., Hamburg, M., and S. Turner, "Elliptic Curves 227 | for Security", RFC 7748, January 2016. 228 | 229 | [KAETZCHEN] Angel, Y., Kaneko, K., Stainton, D., 230 | "Katzenpost Provider-side Autoresponder", January 2018, 231 | . 232 | 233 | [KATZDEADDROP] Stainton, D., "Katzenpost Dead Drop Extension", February 2018, 234 | . 235 | 236 | [KATZPANDA] Stainton, D., "Katzenpost PANDA Autoresponder Extension", 237 | March 2018, . 238 | 239 | Appendix A.2 Informative References 240 | 241 | [SHAKE] "SHA-3 STANDARD: PERMUTATION-BASED HASH AND EXTENDABLE OUTPUT FUNCTIONS", 242 | . 243 | 244 | [RFC7539] Nir, Y. and A. Langley, "ChaCha20 and Poly1305 for IETF 245 | Protocols", RFC 7539, DOI 10.17487/RFC7539, May 2015, 246 | . 247 | 248 | [RFC7693] Saarinen, M-J., Ed., and J-P. Aumasson, "The BLAKE2 249 | Cryptographic Hash and Message Authentication Code 250 | (MAC)", RFC 7693, DOI 10.17487/RFC7693, November 2015, 251 | . 252 | 253 | [SIGNAL] Perrin, T., Marlinspike, M., "The Double Ratchet Algorithm", November 2016, 254 | . 255 | 256 | [NOISE] Perrin, T., "The Noise Protocol Framework", May 2017, 257 | . 258 | 259 | [PETMAIL] Warner, B., "Petmail mailbox-server delivery protocol", 260 | Proceedings of Brian Warner's blog, July 2015, 261 | . 262 | 263 | [MIXMINION] Danezis, G., Dingledine, R., Mathewsom, N., 264 | "Mixminion: Design of a Type III Anonymous Remailer Protocol" 265 | . 270 | 271 | [PANDA] Appelbaum, J., "Going Dark: Phrase Automated Nym Discovery Authentication", 272 | . 273 | 274 | [PANDASPEC] ? 275 | 276 | [FORWARDMIX] Danezis, G., "Forward Secure Mixes", 277 | In the Proceedings of 7th Nordic Workshop on Secure IT Systems, 278 | November 2002, . 279 | 280 | [COMPULS05] Danezis, G., Clulow, J., "Compulsion Resistant Anonymous Communications", 281 | Proceedings of Information Hiding Workshop, June 2005, 282 | . 283 | 284 | [FINGERPRINTING] Danezis, G., Clayton, R., 285 | "Route Finger printing in Anonymous Communications", 286 | . 287 | 288 | [BRIDGING] Danezis, G., Syverson, P., 289 | "Bridging and Fingerprinting: Epistemic Attacks on Route Selection", 290 | In the Proceedings of PETS 2008, Leuven, Belgium, July 2008, 291 | . 292 | 293 | [LOCALVIEW] Gogolewski, M., Klonowski, M., Kutylowsky, M., 294 | "Local View Attack on Anonymous Communication", 295 | . 296 | 297 | [HEARTBEAT03] Danezis, G., Sassaman, L., "Heartbeat Traffic to Counter (n-1) Attacks", 298 | Proceedings of the Workshop on Privacy in the Electronic Society, October 2003, 299 | . 300 | 301 | [MIRANDA] Leibowitz, H., Piotrowska, A., Danezis, G., Herzberg, A., 2017, 302 | "No right to ramain silent: Isolating Malicious Mixes" 303 | . 304 | 305 | [MIXRELIABLE] Dingledine, R., Freedman, M., Hopwood, D., Molnar, D., 2001 306 | "A Reputation System to Increase MIX-Net Reliability", 307 | In Information Hiding, 4th International Workshop, 308 | . 309 | 310 | [YEE02] Yee, Ka-Ping., "User Interaction Design for Secure Systems", 311 | Computer Science Department, University of California, Berkeley, 312 | May 2002, . 313 | -------------------------------------------------------------------------------- /drafts/panda.txt: -------------------------------------------------------------------------------- 1 | Katzenpost PANDA Autoresponder Extension 2 | David Stainton 3 | 4 | version 0 5 | 6 | Abstract 7 | 8 | This document describes the behavior of a PANDA (see [PANDA] and 9 | [PANDASPEC]) server implemented as a Provider side autoresponder 10 | service [KAETZCHEN]. This Panda Kaetzchen service can be used as an 11 | alternative to [KATZKEYSERVER]. 12 | 13 | 1. Introduction 14 | 15 | PANDA, Phrase Automated Nym Discovery Authentication is a variation 16 | of [EKE2] a PAKE, Password Authenticated Key Exchange, with some 17 | design variations that allows clients to perform the key exchanges 18 | asynchronously. The Panda protocol has three principals, two 19 | clients and one server. The clients have identical behavior and do 20 | all the crypto while the server is very simple and merely 21 | facilitates the exchanges of cryptographic binary blobs. 22 | 23 | 1.1. Terminology 24 | 25 | * PAKE: Password Authenticated Key Exchange 26 | 27 | * PANDA: Phrase Automated Nym Discovery Authentication: see [PANDA] 28 | and [PANDASPEC]. 29 | 30 | * kaetzchen/autoresponder service: A service which runs on a 31 | Provider and uses a request-response style protocol scheme to 32 | implement arbitrary services for mix network clients. See 33 | [KAETZCHEN] for details. 34 | 35 | * Provider: A service operated by a third party that Clients 36 | communicate directly with to communicate with the Mixnet. It is 37 | responsible for Client authentication, forwarding outgoing 38 | messages to the Mixnet, and storing incoming messages for the 39 | Client. The Provider MUST have the ability to perform 40 | cryptographic operations on the relayed packets. 41 | 42 | * Posting: A structure referenced by a unique identifier (a Tag), 43 | containing two message slots for storing binary blobs on the 44 | Panda server's storage subsystem. 45 | 46 | * Tag: A 32 byte value used to reference a Posting. 47 | 48 | 1.2 Conventions Used in This Document 49 | 50 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 51 | "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 52 | document are to be interpreted as described in [RFC2119]. 53 | 54 | 2. System Overview 55 | 56 | The server side of the Panda protocol assumes that two Panda 57 | clients have previously selected a Panda server to use. Panda 58 | servers act like a bulletin board system, however a particular 59 | Posting is only visible to clients that present the associated 32 60 | byte Tag identifier. 61 | 62 | The two Panda clients use the Panda server to make two binary blob 63 | exchanges. Panda clients uses their binary blobs to facilitate an 64 | authenticated key exchange. The full Panda protocol details are 65 | described in [PANDASPEC]. 66 | 67 | The Panda server stores a simple data structure called a Posting 68 | which has two message slots and is referenced by a tag. If Alice 69 | manages to contact the Panda server before Bob then Alice's message 70 | will be inserted into Slot 1. Alice's client will then periodically 71 | check the Posting for Bob's message in Slot 2. When Bob finally 72 | contacts the Panda server he inserts his message into Slot 2 and 73 | receives Alice's message from Slot 1. 74 | 75 | .--------. .----------. .-------. .-------. 76 | | Bob | ---> | Provider | ---> | Mix | ---> | Mix | -------. 77 | `--------' <--- `----------'_ `-------' `-------' \ 78 | |\ .-------. .------- | 79 | '--- | Mix | <--- | Mix | <---. | 80 | '-------' `-------' \ | 81 | | V 82 | 83 | .-- Panda Server --. 84 | | .---------. | 85 | | | Posting | | 86 | | | | | 87 | | | Slot 1 | | 88 | | | Slot 2 | | 89 | | | | | 90 | | `---------' | 91 | `------------------' 92 | | Ʌ 93 | .-------. .------- / | 94 | .---- | Mix | <--- | Mix | <----' | 95 | |/_ '-------' `------- | 96 | .--------. .----------. .-------. .-------. / 97 | | Bob | ---> | Provider | ---> | Mix | ---> | Mix | --------' 98 | `--------' <--- `----------' `-------' `-------' 99 | 100 | 3. Panda Server Parameters 101 | 102 | The Panda Server is parameterized by the implementation 103 | based on the application and security requirements. 104 | 105 | * POSTING_TAG_LENGTH - It is recommended that the Tag length be 32 bytes. 106 | 107 | * MAX_SLOT_LENGTH - As specified in [KAETZCHE], the request and response messages 108 | are limited in size by the max payload size of the Sphinx packets. 109 | 110 | * EXPIRATION_DURATION - The duration a Posting can remain on the Panda server 111 | without being expunged by garbage collection. 112 | 113 | 3.1 Public Panda Parameters 114 | 115 | Panda server implementations SHOULD publish their EXPIRATON_DURATION in 116 | their parameters section of their entry in the PKI document as detailed 117 | in [KAETZCHEN]. 118 | 119 | 4. Protocol Messages 120 | 121 | The PandaRequest is sent to the Panda service with a SURB 122 | that is used to send the PandaResponse back to the client. 123 | 124 | 4.1 PandaRequest message 125 | 126 | { 127 | "Version": 0, 128 | "Tag": "8151d5513e0e4c44e4fee37f07a524ce646141dd10a59718ef223c06dea41b8c", 129 | "Message": "QPXc2+lEruQXNe3PNpDfM+Uh1cajoSkpS+jioWUdys2WzzBu2wBEzx6qs7TXe+5VrdyMn9dkVrFywwJr" 130 | } 131 | 132 | Notes: 133 | 134 | * The Tag field is hex string encoding a 32 bytes value. 135 | 136 | * The Message is a variable length base64 encoded binary blob. 137 | 138 | 4.2 PandaResponse message 139 | 140 | { 141 | "Version": 0, 142 | "StatusCode": "0", 143 | "Message": "gtjbknqV+fc9FzKlmDB8wVKZhbqWq6+nDV4S/rD/PzRjV5MMeR+cE0swfsBkxlqGlQHb5wSefNee0Wxg" 144 | } 145 | 146 | Notes: 147 | 148 | * The StatusCode field is used to report errors to the client if 149 | any. Valid status codes are: 150 | 151 | enum { 152 | status_received1(0), /* Message1 was received. */ 153 | status_received2(1), /* Message2 was received. */ 154 | status_syntax_error(2), /* The request was malformed. */ 155 | status_tag_collision_error(3), /* The request tag collision error. */ 156 | status_tag_request_recorded_error(4), /* The request message was already recorded. */ 157 | status_storage_error(5), /* Storage subsystem failure. */ 158 | } StatusCodes; 159 | 160 | * The Message field is variable length and base64 encoded, it 161 | contains the retrieved message from a previously queued Posting. 162 | This field MAY be empty such as in the case where the Panda 163 | server does not find the specified tag in it's storage subsystem. 164 | 165 | 5. Panda Server Storage 166 | 167 | The Panda servers stores Postings of the following format: 168 | 169 | struct { 170 | uint64_t unix_time; 171 | opaque slot1[]; 172 | opaque slot2[]; 173 | } Posting; 174 | 175 | Notes: 176 | 177 | * The unix_time field specifies the time when the Posting was 178 | persisted to disk. 179 | 180 | * slot1 and slot2 are the two message slots. 181 | 182 | 5.1 Garbage Collection 183 | 184 | The Panda server MUST periodically garbage collect expired Postings. 185 | 186 | 6. Anonymity Considerations 187 | 188 | * Mix network based transports are a good choice for implementing 189 | the Panda protocol because they are message oriented and hide the 190 | identity/location of clients from the Panda server. 191 | 192 | 7. Security Considerations 193 | 194 | * After the two binary blob exchanges are performed, the Panda 195 | server does NOT expunge the two Postings because the Kaetzchen 196 | protocol is lossy. Therefore the Panda server must not assume the 197 | client will receive the PandaResponse message. The queued 198 | ciphertext on the Panda server represents vulnerability to a 199 | compulsion attack. That is, an adversary might break the 200 | confidentiality guarantee using a key compromise. 201 | 202 | * Panda is not a post quantum cryptographic protocol and therefore 203 | a sufficiently motivated adversary may be able to violate the 204 | decisional Diffie-Hellman assumption using a quantum computer 205 | after capturing queued ciphertext blobs. 206 | 207 | 8. Future Work 208 | 209 | * Future versions may decide to use a stricter eviction policy 210 | in exchange for reduced ciphertext availability. 211 | 212 | * It might be possible to design a decentralised variation of 213 | the Panda protocol to remove the dependency on a single server 214 | for ciphertext availability. 215 | 216 | Appendix A. References 217 | 218 | Appendix A.1 Normative References 219 | 220 | [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 221 | Requirement Levels", BCP 14, RFC 2119, 222 | DOI 10.17487/RFC2119, March 1997, 223 | . 224 | 225 | [KAETZCHEN] Angel, Y., Kaneko, K., Stainton, D., 226 | "Katzenpost Provider-side Autoresponder", January 2018, 227 | . 228 | 229 | Appendix A.2 Informative References 230 | 231 | [PANDA] Appelbaum, J., "Going Dark: Phrase Automated Nym Discovery Authentication", 232 | . 233 | 234 | [PANDASPEC] ? 235 | 236 | [SPAKE2] Abdalla, M., Pointcheval, D., 237 | "Simple Password-Based Encrypted Key Exchange Protocols", 238 | Topics in cryptology–CT-RSA 2005, 239 | . 240 | 241 | [EKE2] Bellare, M., Pointcheval, D., Rogaway, P., 242 | "Authenticated Key Exchange Secure Against Dictionary Attacks", 243 | EUROCRYPT, April 2000, . 244 | 245 | [KATZKEYSERVER] Angel, Y., Diaz, C., Pollan, R., kwadronaut, mo, Kaneko, K., Stainton, D., 246 | "Katzenpost Key Discovery Extension", February 2018, 247 | . 248 | -------------------------------------------------------------------------------- /drafts/priority_tasks.rst: -------------------------------------------------------------------------------- 1 | 2 | Priority Development tasks (which do not include design work) 3 | ============================================================= 4 | 5 | Unit tests 6 | ---------- 7 | 8 | The mix server and Directory Authority server should have unit tests 9 | that can be used with a continuous integration system such as Travis. 10 | This should hopefully shed light on some Directory Authority server 11 | bugs and help us fix them as well as prevent regressions. 12 | 13 | Priority Design tasks 14 | ===================== 15 | 16 | Upgrade Link Layer Protocol 17 | --------------------------- 18 | 19 | Upgrade mixnet link layer to use the Kyber PQ KEM instead of New Hope Simple 20 | because Dr. Peter Schwabe says it's a good idea. It also greatly simplifies 21 | rustification. Before this development task begins the specification document 22 | should reflect the necessary changes: 23 | 24 | * https://github.com/katzenpost/docs/blob/master/specs/wire-protocol.rst 25 | 26 | 27 | Key Agility 28 | ----------- 29 | 30 | Currently Katzenpost mix servers and Directory Authority servers do not have key agility. 31 | That is to say, there is no way for these servers to change their static identity keys. 32 | The two primary reasons for key agility are recovery from a known key compromise 33 | and as a prerequisite for usage with a hardware security module. 34 | 35 | Early unfinished key agility draft specification document: 36 | * https://github.com/katzenpost/docs/blob/master/drafts/key_agility.rst 37 | 38 | 39 | Client Library 40 | -------------- 41 | 42 | Early unfinished draft specification document: 43 | * https://github.com/katzenpost/docs/blob/master/drafts/client.rst 44 | 45 | After this draft specification document is completed additional composable 46 | libraries should be designed which have more sophisticated encryption as 47 | provided by the Signal Double Ratchet or OTRv4. 48 | 49 | 50 | Rustification 51 | ============= 52 | 53 | The goal should be binary compatibility with the golang implementation 54 | of Katzenpost such that the existing golang components can 55 | interoperate with the new Rust components. Perhaps the biggest advantage 56 | of using Rust would be for writing mixnet clients as opposed to mix servers. 57 | A Rust mixnet client could easily present a FFI that could be used by 58 | user interfaces written in Java for Android and Swift for iOS. 59 | 60 | I wrote several relavant rust crates: 61 | 62 | * https://crates.io/crates/aez 63 | * https://crates.io/crates/ecdh_wrapper 64 | * https://crates.io/crates/mix_link 65 | * https://crates.io/crates/rust-lioness 66 | * https://crates.io/crates/epoch 67 | * https://crates.io/crates/sphinx_replay_cache 68 | * https://crates.io/crates/sphinxcrypto 69 | 70 | 71 | Sphinx binary compatibility 72 | --------------------------- 73 | 74 | * https://crates.io/crates/sphinxcrypto 75 | 76 | The rust Sphinx uses the exact same cryptographic primitives 77 | as the golang implementation. Therefore it should be fairly 78 | easy to make them binary compatible. They should share test vectors. 79 | 80 | 81 | Mix link layer binary compatibility 82 | ----------------------------------- 83 | 84 | * https://crates.io/crates/mix_link 85 | 86 | Currently this mix link layer crate uses ``Noise_XX_25519_ChaChaPoly_BLAKE2b`` 87 | however if the Katzenpost link layer were to upgrade to 88 | Kyber then the task of making this crate binary compatibility 89 | would be greatly simplified. 90 | 91 | Here's an implementation of Kyber: 92 | 93 | * https://crates.io/crates/kyber 94 | 95 | This ``mix_link`` crate uses the snow Noise protocol library implementation: 96 | 97 | * https://crates.io/crates/snow 98 | 99 | However we SHOULD patch snow with Kyber PQ KEM hybrid forward secrecy. 100 | Here's the snow github ticket for this task: 101 | 102 | * https://github.com/mcginty/snow/issues/39 103 | 104 | 105 | Mix server 106 | ---------- 107 | 108 | Current work in progress rust mix server: 109 | 110 | * https://github.com/david415/mix_server 111 | 112 | Development progress has halted due to not being able to interoperate 113 | with the existing Katzenpost Directory Authority system. 114 | -------------------------------------------------------------------------------- /drafts/zcash_send.rst: -------------------------------------------------------------------------------- 1 | Katzenpost Zcash Submission Protocol Specification 2 | ************************************************** 3 | 4 | | David Stainton 5 | 6 | Version 0 7 | 8 | 9 | .. rubric:: Abstract 10 | 11 | This document describes an unreliable unidirectional protocol and the 12 | Zcash transaction submission mixnet service [KAETZCHEN]_ which allows 13 | clients of the mix network to anonymously write transactions to the 14 | Zcash blockchain. 15 | 16 | .. contents:: :local: 17 | 18 | 19 | 1. Introduction 20 | =============== 21 | 22 | The primary use case for this protocol is to facilitate the development 23 | of superior Zcash wallets with the highest degree of traffic analysis 24 | resistance. 25 | 26 | 27 | 1.1 Terminology 28 | ---------------- 29 | 30 | ``Provider`` - A service operated by a third party that Clients 31 | communicate directly with to communicate with the Mixnet. It is 32 | responsible for Client authentication, forwarding outgoing 33 | messages to the Mixnet, and storing incoming messages for the 34 | Client. The Provider MUST have the ability to perform 35 | cryptographic operations on the relayed packets. 36 | 37 | ``Kaetzchen`` - A Provider-side autoresponder service as defined in 38 | [KAETZCHEN]_. 39 | 40 | 41 | 1.2 Conventions Used in This Document 42 | ------------------------------------- 43 | 44 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 45 | "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 46 | document are to be interpreted as described in [RFC2119]_. 47 | 48 | 49 | 2. System Overview 50 | ================== 51 | 52 | The Zcash sending wallet MUST be in possession of the cryptographic and 53 | connection information which gives us the capability to send and 54 | receive messages on the mix network. The Katzenpost architecture 55 | [KATZMIXNET]_ describes the PKI as providing a complete network view 56 | to clients. [KATZMIXPKI]_ This network consensus document is used by 57 | clients to learn about the mixes and services on the network. [KAETZCHEN]_ 58 | 59 | Providers are mixes in the network that provide additional services. 60 | In the Loopix and Katzenpost architecture Providers form the perimeter 61 | of the network and therefore route all incoming connections from 62 | clients if they pass the access control check using cryptographic 63 | authentication. [KATZMIXWIRE]_ [KATZMIXE2E]_ Providers are also the 64 | destination of each route and queue messages until a client retrieves it. 65 | 66 | In contrast, this crypto currency submission protocol does not 67 | have any need to queue messages. Authenticating clients at the network 68 | perimeter is a policy decision and is therefore out of scope here. 69 | 70 | The Zcash sender composes a transaction and passes it's serialized 71 | blob form into the protocol library. A Sphinx packet is created and is 72 | sent over the mixnet link layer [KATZMIXWIRE]_ to the entry point, the 73 | client's Provider. This Sphinx packet is routed through the network 74 | and the Provider is the first to remove a layer of Sphinx encryption. 75 | Once the packet arrives at it's destination Provider, the Zcash 76 | transaction submission service receives the transaction submission 77 | request. 78 | 79 | :: 80 | 81 | .--------. .----------. .-------. .-------. .----------. 82 | | Sender | ---> | Provider | ---> | Mix | ---> | Mix | ---> | Provider | 83 | `--------' `----------' `-------' `-------' '----------' 84 | 85 | On the "server side", the Provider receives the Sphinx packet and 86 | decrypts it's payload and then passes the plaintext to the "Zcash 87 | Submission Provider-side Service" module which parses the JSON blob 88 | and submits the transaction blob to the Zcash blockchain using the 89 | zcashd client RPC. No receipt or acknowledgement is produced. Handling 90 | any kind of failure is out of scope. 91 | 92 | 93 | 2.1 Protocol Goals 94 | ------------------ 95 | 96 | Our goals include: 97 | 98 | * Sender Unobservability: 99 | 100 | Prevention of any network observer from learning when a client sends a 101 | legitimate message (in this context a Zcash transaction). Clients 102 | therefore periodically send decoy traffic AND legitimate traffic as 103 | described in [LOOPIX]_ however for this application we DO NOT NEED 104 | loop traffic of any kind, nor do we need decoy loops since this 105 | protocol is unidirectional AND unreliable. 106 | 107 | * Client To Transaction Unlinkability: 108 | 109 | We desire to make it very difficult for active and passive network 110 | adversaries to link a specific transaction to a specific client. 111 | 112 | 113 | 3. The Provider-side Zcash Transaction Submission Service 114 | ========================================================= 115 | 116 | Kaetzchen [KAETZCHEN]_ services are a request-response protocol 117 | API where responses are optional. In this protocol no response is sent. 118 | The client puts their transaction blob inside of a ZcashRequest 119 | and sends it to this service. 120 | 121 | 122 | 3.1 ZcashRequest Message Format 123 | ------------------------------- 124 | :: 125 | 126 | type zcashRequest struct { 127 | Version int 128 | Tx string 129 | } 130 | 131 | The ``Tx`` field must be populated with the transaction blob in hex 132 | string format. 133 | 134 | 135 | 3.2 Submission Service Behavior 136 | ------------------------------- 137 | 138 | The submission service uses a HTTP JSON RPC to submit transactions to 139 | the blockchain using the ``sendrawtransaction`` RPC command which 140 | works for Bitcoin as well as Zcash. [ZCASHPAYMENTAPI]_ 141 | [ZCASHINTEGRATION]_ [BTCRPC]_ 142 | 143 | Here's an example JSON blob:: 144 | {"jsonrpc":"1.0","method":"sendrawtransaction","params":["030000807082c40301ee9aa1a0f1212131580f546903997eff6f2e3d3a8262b40c676dc2ba1aa7094b010000006b483045022100f3e5a20c7246545352c90971bb7e5d335d424b3ead78c1aefa95a630b0da577202203609bbadcddc7a89951636212643e57be2dbff4f718ef2b0ad9a41a9001c4b860121038d17c14225360038a5b6dfd063bfbe53a6e014c33f1f2bc6b49babe896595f7dfeffffff0200a3e111000000001976a914681a2881e0369225b353ff737d562ae5b60f6aca88acdd1b6403000000001976a91471257ac18b24ac66774f772782856fcedda5599288ac1f4d03003e4d030000",true],"id":6439} 145 | 146 | Further details about this RPC command are here: https://bitcoin.org/en/developer-reference#sendrawtransaction 147 | 148 | 149 | 4. Client Behavior and Programming Interface 150 | ============================================ 151 | 152 | 153 | 4.1 Starting and Stopping the Client 154 | ------------------------------------ 155 | 156 | Requirements: 157 | 158 | * PKI connection information 159 | * PKI key material for signature verification 160 | * optional Provider access credential 161 | 162 | Using the above information the client ensures that it always 163 | has a fresh PKI consensus document. The client periodically 164 | sends decoy drop messages to randomly selected Providers as 165 | described in the Loopix paper [LOOPIX]_. 166 | 167 | The optional Provider access credential is currently being 168 | used by the Katzenpost system, an X25519 public key and a username 169 | are stored on the Provider's user database. This in part is used 170 | to restrict access to the user's mailbox stored on the Provider 171 | however in our case we either wish to restrict access to the entire 172 | mixnet or we want an open use mix network. This policy decision 173 | affects which information a client will need. 174 | 175 | 176 | 4.2 Send Raw Transaction 177 | ------------------------ 178 | 179 | 1. The client checks a fresh PKI consensus document for advertized Zcash 180 | submission services. The client chooses one at random to use. 181 | 182 | 2. Sends the raw transaction as a hex string. 183 | 184 | 185 | 5. Performance and Scaling Considerations 186 | ========================================= 187 | 188 | As mentioned in [KATZMIXNET]_ the mix network should utilize the 189 | stratified topology to spread the Sphinx packet traffic load. The 190 | mixes present at each strata are added or removed according to the 191 | PKI. Therefore the PKI is used to close the feedback loop for 192 | dynamically adjusting the load on the network. 193 | 194 | The Zcash transaction submissions can also similarly be loadbalanced. 195 | One or more Zcash submission services can be operated on the mix 196 | network. They will all be advertized in the PKI consensus document as 197 | mentioned in [KAETZCHEN]_. 198 | 199 | 200 | 6. Anonymity Considerations 201 | =========================== 202 | 203 | * Using an entry Provider for many uses and for long periods of time 204 | may be an unnecessary information leakage towards the operator of 205 | that Provider. Instead it may be preferable to have an "open mixnet" 206 | where clients can connect to any entry Provider to inject their 207 | Sphinx packets into the network. 208 | 209 | 210 | 7. Security Considerations 211 | ========================== 212 | 213 | * Unlike the Katzenpost client to client protocol as described in 214 | [KATZMIXE2E]_, this protocol uses a Provider-side service 215 | [KAETZCHEN]_ and therefore the Sphinx encryption is sufficient to 216 | protect the confidentiality and integrity of the payload. 217 | 218 | 219 | 8. Future Work and Research 220 | =========================== 221 | 222 | * Compose a reliable Zcash submission protocol library where the 223 | client checks the blockchain to see if the transaction was 224 | successfully transmitted; using this information instead of 225 | ACKnowledgment messages an Automatic Repeat reQuest protocol scheme 226 | can be conceived. 227 | 228 | * Compose a semi-reliable Zcash submission protocol that uses client 229 | decoy loops. The successful acquisition of a transaction blob by 230 | the Zcash submission service triggers the response with a SURB 231 | ACKnowledgement message as described in [KATZMIXE2E]_. Clients 232 | periodically send decoy traffic as client loops and these are 233 | indistinguishable from transaction submission messages from the 234 | point of view of a passive network observers and all network 235 | operators but the destination Provider. 236 | 237 | * Nothing here is specific to Zcash. There could also be a Bitcoin 238 | transaction submission service. These two transaction submission 239 | services SHOULD be on the same mix network and thereby both benefit 240 | from increasing each other's anonymity set size. 241 | 242 | 243 | Appendix A. References 244 | ====================== 245 | 246 | Appendix A.1 Normative References 247 | --------------------------------- 248 | 249 | .. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 250 | Requirement Levels", BCP 14, RFC 2119, 251 | DOI 10.17487/RFC2119, March 1997, 252 | . 253 | 254 | .. [KAETZCHEN] Angel, Y., Kaneko, K., Stainton, D., 255 | "Katzenpost Provider-side Autoresponder", January 2018, 256 | . 257 | 258 | .. [KATZMIXWIRE] Angel, Y., "Katzenpost Mix Network Wire Protocol Specification", June 2017. 259 | . 260 | 261 | .. [KATZMIXNET] Angel, Y., Danezis, G., Diaz, C., Piotrowska, A., Stainton, D., 262 | "Katzenpost Mix Network Specification", June 2017, 263 | . 264 | .. [KATZMIXPKI] Angel, Y., Diaz, C., Piotrowska, A., Stainton, D., 265 | "Katzenpost Mix Network PKI Specification", November 2017, 266 | 267 | 268 | .. [ZCASHPAYMENTAPI] . 269 | 270 | .. [ZCASHINTEGRATION] . 271 | 272 | .. [BTCRPC] . 273 | 274 | Appendix A.2 Informative References 275 | ----------------------------------- 276 | 277 | .. [KATZMIXE2E] Angel, Y., Danezis, G., Diaz, C., Piotrowska, A., Stainton, D., 278 | "Katzenpost Mix Network End-to-end Protocol Specification", July 2017, 279 | . 280 | 281 | .. [LOOPIX] Piotrowska, A., Hayes, J., Elahi, T., Meiser, S., Danezis, G., 282 | “The Loopix Anonymity System”, 283 | USENIX, August, 2017 284 | . 285 | -------------------------------------------------------------------------------- /faq.rst: -------------------------------------------------------------------------------- 1 | Frequently Asked Questions 2 | ========================== 3 | 4 | .. contents:: :local: 5 | 6 | What is a mix network? 7 | ---------------------- 8 | 9 | A mix network is an unreliable packet switching network which 10 | resists traffic analysis. Mix networks can be designed to provide 11 | various anonymity properties such as: 12 | 13 | * sender anonymity 14 | * receiver anonymity 15 | * sender and receiver anonymity with respect to third party observers 16 | 17 | 18 | Can Katzenpost act as a drop-in TCP replacement? 19 | ------------------------------------------------ 20 | 21 | No and furthermore you should not want a stream oriented interface 22 | for interacting with a message oriented protocol. If your application 23 | is message oriented then integration as a Katzenpost client is possible. 24 | Client protocol libraries are currently being developed! 25 | 26 | Although decryption mixnets are inherently unreliable and offer unordered 27 | delivery, reliability and ordered delivery can be achieved by the protocol 28 | library and NOT by the mix network itself. That is to say, the mixnet client 29 | library should abstract away all the details of retransmissions and book keeping 30 | related to ordered delivery. 31 | 32 | 33 | What kinds of applications can use Katzenpost? 34 | ---------------------------------------------- 35 | 36 | Katzenpost can be used by various kinds of message oriented applications. 37 | Generally these fall into two categories: 38 | 39 | 1. peer to peer: 40 | Alice can chat with Bob over the mixnet. In this case there's a 41 | protocol library that let's them send and receive messages with a 42 | Katzenpost specific addressing sytem. In this case the mixnet acts 43 | as a transport for Alice and Bob's interactions. 44 | 45 | 2. client to server: 46 | Alice can interact with a service that listens on the mixnet for 47 | mixnet messages. This means there is a client and a server 48 | component and they use the mixnet as a transport for their 49 | interaction. 50 | 51 | What's are some examples of "client to server" mixnet applications? 52 | 53 | * Clients send URLs to a "retrieval service" on the mixnet. This service 54 | retrieves the URLs and sends the content back to the client. 55 | 56 | * Privacy preserving crypto currency wallet sends crypto currency transactions 57 | to the mixnet service. This service then submits the transaction to the blockchain. 58 | 59 | 60 | What are some examples of "peer to peer" mixnet applications? 61 | 62 | * Encrypted chat applications can use the mixnet as the transport. 63 | 64 | * File exchange: Alice can send Bob a file using the mixnet as the transport. 65 | 66 | 67 | What is Loopix? 68 | --------------- 69 | 70 | Loopix is described in the paper "The Loopix Anonymity System" 71 | published at USENIX 2017, https://arxiv.org/pdf/1703.00536.pdf 72 | 73 | Briefly, Loopix uses a collection of the best mix network designs 74 | to create a messaging system that has the property of sender and 75 | receiver anonymity with respect to third party observers. This 76 | particular meaning of "anonymity" is remarkably different than what 77 | Tor provides. Loopix does not have strong location hiding 78 | properties nor does it provide sender anonymity or receiver 79 | anonymity. That having been said it should be possible to create 80 | such systems based on the Loopix design. 81 | 82 | The Loopix design is informed by over 15 years of mixnet literature 83 | and strives to reduce many kinds of metadata leakages that 84 | historically have made mix networks vulnerable to long term 85 | statistical disclosure attacks. Loopix has a defense against 86 | blending/n-1 attacks. Loopix explores the tradeoff between decoy 87 | traffic and latency, thus revitalizing mix networks with much lower 88 | latency for message transportation. 89 | 90 | Loopix uses the Sphinx cryptographic packet format, the Poisson mix 91 | strategy, three kinds of decoy traffic and the stratified mix 92 | topology. It's Provider architecture forces long term statistical 93 | disclosure attacks to take place on the receiver's Provider, thus 94 | forcing such adversaries to actively compromise Providers instead of 95 | passively observing the mix network which is in contrast to historical 96 | mix network designs. 97 | 98 | What is Katzenpost? 99 | ------------------- 100 | 101 | Katzenpost has the goal of implementing the Loopix designs with the 102 | additional property of message transport reliability. Reliability 103 | is achieved using a Stop and Wait ARQ which is half duplex and uses 104 | SURBs to create the reply channel for the ACKnowledgement messages. 105 | 106 | Why is this a big deal? To our knowledge, no other mix network design 107 | has attempted to achieve reliability. We believe that the lack of 108 | reliability has been one of the major obstacles to the adoption 109 | of mix networks. "Would you want to use a messaging system which 110 | might not even transport your messages to their destination?" 111 | 112 | How are mix networks different from Tor? 113 | ---------------------------------------- 114 | 115 | Tor is stream oriented. Mixnets are message oriented. Tor is low 116 | latency, easy to use, has a great primary application (Tor 117 | Browser), and functions as an extremely useful general purpose 118 | anonymity system. This is in contrast to mix networks which do not 119 | function well as general purpose anonymity systems. Instead mix 120 | networks are better suited to customization for specific 121 | applications, for example a mix network for instant messaging and a 122 | mix network for e-mail will have different traffic patterns and 123 | therefore require different decoy traffic patterns to achieve the 124 | desired traffic analysis resistant properties. 125 | 126 | There are also many adversarial model differences between Tor and 127 | mix networks. For example, Tor can be easily deanonymized by 128 | statistical correlation attacks by a sufficiently global adversary 129 | whereas mixnets are not immediately vulnerable to these kinds of 130 | attacks if they correctly use mix strategies and decoy traffic. 131 | 132 | Both Tor and mix networks can scale well with respect to 133 | increasing user traffic, however Tor requires route 134 | unpredictability to achieve it's anonymity properties. Mix networks 135 | on the other hand do not require route unpredictability and 136 | therefore can achieve very strong anonymity properties with far fewer 137 | network nodes than Tor. 138 | 139 | How do mix networks compare to Pond? 140 | ------------------------------------ 141 | 142 | Pond doesn't actually mix anything whereas mix networks 143 | specifically contain component mixes, each containing a mix queue 144 | which "mixes" messages together via some specific mix strategy 145 | before sending them to the next hop in the route. Pond uses a 146 | group signature scheme to prevent the server from learning to whom 147 | a message is being sent to. Pond uses Tor onion services as it's 148 | transport while also using decoy traffic to prevent a passive 149 | network observer from determining when a user sends a message. Mix 150 | network designs can also use decoy traffic, however in the Loopix 151 | design there are three different kinds of decoy traffic that serve 152 | different purposes. Mix networks also scale much better with 153 | respect to increasing users and traffic whereas pond servers 154 | quickly become performance bottlenecks. This is in contrast to mix 155 | networks where additional mixes can be added to the network in 156 | order to efficiently process increases in user traffic. 157 | 158 | How does Vuvuzela differ from Loopix/Katzenpost? 159 | ------------------------------------------------ 160 | 161 | Vuvuzela uses the cascade mix topology which does not scale 162 | well with respect to an increase in user traffic. Loopix uses 163 | the stratified topology which scales very well. In Vuvuzela, messages cannot 164 | be received when a user is offline. In Loopix messages received 165 | while a user is offline are queued by their Provider. Vuvuzela operates 166 | in rounds whereas Loopix does not. Vuvuzela does not provide reliable 167 | message transportation whereas Katzenpost does. 168 | 169 | How does AnonPOP differ from Loopix/Katzenpost? 170 | ----------------------------------------------- 171 | 172 | AnonPOP operates in rounds and provides offline storage of messages. 173 | Loopix uses a continuous time mix strategy so that it avoids 174 | user synchronization issues. AnonPOP does not provide reliable 175 | message transportation whereas Katzenpost does. 176 | -------------------------------------------------------------------------------- /glossary.rst: -------------------------------------------------------------------------------- 1 | Glossary 2 | ======== 3 | 4 | .. glossary:: 5 | 6 | Traffic Analysis Resistance 7 | Traffic analysis resistance means hiding traffic metadata from 8 | passive network observers. Such metadata includes: 9 | 10 | * message sender 11 | * message receiver 12 | * size of the message 13 | * time of message transmission 14 | 15 | Mix 16 | A mix is the primary component used to compose a mix network. 17 | Mixes receive incoming messages, mix them via some specific 18 | mix strategy which incurs a delay and then output the messages 19 | after removing one layer of encryption. Bitwise unlinkability 20 | between input and output messages is achieved using the mix 21 | network cryptographic packet format. Mixes can also output 22 | their own decoy traffic which adds further entropy to the 23 | network as detailed in the Loopix paper. 24 | 25 | Mixnet 26 | Mixnet is short for mix network which is a network of 27 | :term:`mix`\ es. Fundamentally a mix network is a lossy 28 | packet switching network whose primary purpose is to achieve 29 | traffic analysis resistant properties such as location hiding, 30 | sender anonymity etc. See our FAQ for more information. 31 | 32 | Node 33 | A :term:`Mix` or :term:`Provider` instance. 34 | 35 | User 36 | An agent controlling a :term:`Client` of the :term:`Katzenpost` system. 37 | 38 | Client 39 | Software run by the :term:`User` on its local device to participate 40 | in the :term:`Mixnet`. 41 | 42 | Provider 43 | In the context of Loopix/Katzenpost, a Provider is a node in 44 | the mix network which is responsible for authenticating 45 | :term:`Client`\s, forwarding messages to the rest of the mix 46 | network on behalf of :term:`Client`\s and queueing messages 47 | that can later be retrieved by :term:`Client`\s. 48 | 49 | PKI 50 | Stands for Public Key Infrastructure. In the context of :term:`Panoramix` 51 | is also known as the :term:`Mix Directory Authority service`. 52 | In :term:`Katzenpost`, :term:`Network Authority` or in short 53 | :term:`Authority` is the server responsible to provide the 54 | :term:`Mix Directory Authority service`. 55 | 56 | It is explained in more detail in :ref:`pki` 57 | 58 | .. note:: 59 | Define PKI 60 | 61 | Sphinx 62 | The Sphinx cryptographic packet format is now the defacto 63 | standard for mix networks. The Mixminion mix network 64 | used SURBs to achieve sender anonymity. Mixminion inspired the 65 | design of the Sphinx packet format. 66 | 67 | Katzenpost 68 | A mixnet design based on the :term:`Loopix` research with 69 | added message transport reliability using an :term:`ARQ` 70 | protocol scheme. 71 | 72 | Panoramix 73 | A project funded by the European Union's Horizon 2020 research and 74 | innovation programme to research :term:`mixnet`\s for voting, statistics, 75 | and messaging, running from 2015 to 2019. See `panoramix-project.eu `_. 76 | 77 | Loopix 78 | The Loopix mixnet design is described in the paper `"The Loopix Anonymity 79 | System" published at USENIX 2017 `_. 80 | Loopix uses a collection of the best mix network designs to create a 81 | messaging system that has the property of sender and receiver anonymity 82 | with respect to third party observers. Loopix uses the :term:`Sphinx` 83 | cryptographic packet format, various kinds of :term:`decoy traffic` and 84 | a :term:`stratified mix topology`. 85 | 86 | ARQ 87 | ARQ means Automatic Repeat reQuest which is a protocol scheme 88 | that achieves reliability by means for ACKnowledgement 89 | protocol control messages and retransmissions. This concept 90 | comes from the packet switching network literature and is not 91 | generally associated with mix networks. There is no other way 92 | to achieve network reliability other than an ARQ scheme 93 | although there are many hybrid ARQ schemes for radio 94 | communication that use forward error correction for the 95 | purpose of performing retransmissions less frequently. 96 | 97 | Stop and Wait ARQ 98 | Stop and Wait ARQ is the simplest of all the ARQ protocol 99 | schemes. In the context of mix networks it also leaks the 100 | least amount of information. When comparing it to TCP, Stop 101 | and Wait ARQ has a congestion window of size one. This means 102 | that after a message is transmitted, a second message cannot 103 | be sent until the ACK for the first message is received. If 104 | the ACK message is not received within a particular time 105 | duration then the message is retransmitted. 106 | 107 | SURB 108 | 109 | SURB means Single Use Reply Block. SURBs are essentially a 110 | cryptographic delivery token with a short lifetime. In the 111 | :term:`Sphinx` packet format SURBs have two categories of components, 112 | those used by the creator and those used by the sender. When 113 | Alice creates a SURB, she retains a decryption token and a 114 | SURB ID. Alice gives Bob a Sphinx header and a payload 115 | encryption token. Bob can use the payload encryption token to 116 | encrypt his message. Bob then attaches the :term:`Sphinx` header to 117 | his ciphertext payload, thus forming a :term:`Sphinx` packet which he 118 | sends through the network. Bob cannot know the destination or 119 | route of this :term:`Sphinx` packet. Alice will receive the ciphertext 120 | payload and the SURB ID. She uses the SURB ID to identify 121 | which SURB decryption token to use for the ciphertext payload 122 | decryption. 123 | 124 | SURBs have a short lifetime because mixes MUST rotate Sphinx 125 | routing keys frequently as the primary method of achieving 126 | forward secrecy. The other reason routing keys must be rotated 127 | is because each mix retains a replay cache which stores a 128 | unique tag for each Sphinx packet that traverses it. This 129 | replay cache can only be flushed after a key rotation. 130 | 131 | Mixminion 132 | A mix network software project whose design has been inspirational to 133 | the Katzenpost design. For more information see . 134 | -------------------------------------------------------------------------------- /handbook/index.rst: -------------------------------------------------------------------------------- 1 | 2 | Katzenpost Handbook 3 | ******************* 4 | 5 | | David Stainton 6 | 7 | Version 0 8 | 9 | .. rubric:: Abstract 10 | 11 | Thank you for interest in Katzenpost! This document describes how to 12 | use and configure the Katzenpost Mix Network software system. The 13 | target audience for this document is systems administrators. This 14 | document assumes you are familiar with using unix systems, git 15 | revision control system and building golang binaries. 16 | 17 | .. contents:: :local: 18 | 19 | 20 | Introduction 21 | ============ 22 | 23 | Katzenpost can be used as a message oriented transport for a variety 24 | of applications and is in no way limited to the e-mail use case 25 | demonstrated by the ``mailproxy`` client/library. Other possible 26 | applications of Katzenpost include but are not limited to: instant 27 | messenger applications, crypto currency transaction transport, 28 | bulletin board systems, file sharing and so forth. 29 | 30 | The Katzenpost system has four component categories: 31 | 32 | * public key infrastructure 33 | * mixes 34 | * Providers 35 | * clients 36 | 37 | Providers has a superset of mixes that fulfill two roles: 38 | 1. The initial hop in the route and therefore as an ingress hop 39 | this node authenticates clients and does per client rate limiting. 40 | 2. The terminal hop in the route and therefore can either store and 41 | forward or proxy to a ``Kaetzchen`` aka a mixnet service. 42 | 43 | 44 | This handbook will describe how to use and deploy each of these. 45 | The build instructions in this handbook assume that you have a proper 46 | golang environment with at least golang 1.10 or later AND the git 47 | revision control system commandline installed. 48 | 49 | 50 | Building the latest stable version of Katzenpost 51 | ------------------------------------------------ 52 | 53 | NOTE: Find out what our latest stable version tag 54 | by looking at the "releases.rst" file in the top-level 55 | of this repository. 56 | 57 | 58 | 0. Make sure you have a recent version of Go that supports go modules. 59 | 60 | 1. Follow the build instructions for each Katzenpost component you want to build. 61 | 62 | 63 | There are two server infrastructure components: 64 | 65 | * https://github.com/katzenpost/server 66 | 67 | * https://github.com/katzenpost/authority 68 | 69 | 70 | There are several clients. Our latest work-in-progress: 71 | 72 | * https://github.com/katzenpost/catchat 73 | 74 | The old client from the Panoramix EU 2020 grant deliverable: 75 | 76 | * https://github.com/katzenpost/mailproxy 77 | 78 | 79 | Additionally HashCloak makes crypto currency clients that work with Katzenpost: 80 | 81 | * https://github.com/hashcloak 82 | 83 | The Katzenpost Configuration File Format 84 | ---------------------------------------- 85 | 86 | Each Katzenpost component has a configuration file in the TOML format. 87 | This handbook will give you all the details you need to know to configure 88 | each of these configuration files. To learn more about the TOML format 89 | see: https://github.com/toml-lang/toml#toml 90 | 91 | NOTE: ``#`` may be used at the beginning of a line to denote a comment 92 | instead of an effective configuration line. 93 | 94 | 95 | Notes on Building a Test Mix Network 96 | ------------------------------------ 97 | 98 | See our docker repo: 99 | 100 | https://github.com/katzenpost/docker 101 | -------------------------------------------------------------------------------- /handbook/mailproxy.rst: -------------------------------------------------------------------------------- 1 | Mailproxy Client Daemon 2 | ======================= 3 | 4 | Overview 5 | -------- 6 | 7 | Mailproxy is one of many possible clients for using a Katzenpost mix 8 | network. It supports POP3 and SMTP for message retreival and message 9 | transmission respectively and is intended to run on a user's localhost 10 | to allow standard mail clients to send and receive mail over the 11 | mixnet. 12 | 13 | Mailproxy is a daemon which runs in the background and periodically 14 | transmits and receives messages. Once it receives a message it will be 15 | queued locally and encrypted onto disk for later retreival via POP3. 16 | 17 | Upon receiving the HUP signal, mailproxy will rescan it's recipients 18 | directory to check for new recipients. Other signals trigger a clean shutdown. 19 | 20 | Configuration 21 | ------------- 22 | 23 | The Proxy Section 24 | ````````````````` 25 | 26 | The Proxy section contains mandatory proxy configuration, for example:: 27 | 28 | [Proxy] 29 | POP3Address = "127.0.0.1:2524" 30 | SMTPAddress = "127.0.0.1:2525" 31 | DataDir = "/home/user/.local/share/katzenpost 32 | 33 | * `POP3Address` is the IP address/port combination that the mail proxy 34 | will bind to for POP3 access. If omitted `127.0.0.1:2524` will be 35 | used. 36 | 37 | * `SMTPAddress` is the IP address/port combination that the mail proxy 38 | will bind to for SMTP access. If omitted `127.0.0.1:2525` will be 39 | used. 40 | 41 | * `DataDir` is the absolute path to mailproxy's state files. 42 | 43 | * `NoLaunchListeners` is set to true to disable the SMTP and POP3 listeners. 44 | 45 | 46 | The Logging Section 47 | ``````````````````` 48 | 49 | The Logging section controls the logging, for example:: 50 | 51 | [Logging] 52 | Disable = false 53 | File = "/home/user/.local/share/katzenpost/katzenpost.log" 54 | Level = "DEBUG" 55 | 56 | * `Disable` disables logging entirely if set to `true`. 57 | 58 | * `File` specifies the log file, if omitted stdout will be used. 59 | 60 | * `Level` specifies the log level out of `ERROR`, `WARNING`, `NOTICE`, 61 | `INFO` and `DEBUG`. 62 | 63 | **Warning: The `DEBUG` log level is unsafe for production use.** 64 | 65 | 66 | The NonvotingAuthority Section 67 | `````````````````````````````` 68 | 69 | The NonvotingAuthority section specifies one or more nonvoting 70 | directory authorities, for example:: 71 | 72 | [NonvotingAuthority] 73 | [NonvotingAuthority.TestAuthority] 74 | Address = "192.0.2.2:2323" 75 | PublicKey = "kAiVchOBwHVtKJVFJLsdCQ9UyN2SlfhLHYqT8ePBetg=" 76 | 77 | This configuration section supports multiple entries. In the above 78 | example, the entry is labelled as `TestAuthority` and is referred 79 | to later in the `Account` section of the mailproxy configuration. 80 | 81 | * `Address` is the IP address/port combination of the directory 82 | authority. 83 | 84 | * `PublicKey` is the directory authority's public key in Base64 or 85 | Base16 format. 86 | 87 | 88 | The Account Section 89 | ``````````````````` 90 | 91 | The Account section specifies account configuration(s), for example:: 92 | 93 | [[Account]] 94 | User = "alice" 95 | Provider = "example.com" 96 | ProviderKeyPin = "0AV1syaCdBbm3CLmgXLj6HdlMNiTeeIxoDc8Lgk41e0=" 97 | Authority = "TestAuthority" 98 | InsecureKeyDiscovery = true 99 | 100 | * ``User`` is the account user name. 101 | 102 | * ``Provider`` is the provider identifier used by this account. 103 | 104 | * ``ProviderKeyPin`` is the optional pinned provider signing key in 105 | Base64 or Base16 format. 106 | 107 | * ``Authority`` is the authority configuration used by this account. 108 | 109 | * ``InsecureKeyDiscovery`` is set to true in order to allow unverified 110 | user identity key lookups to be used for end-to-end encryption of messages. 111 | 112 | 113 | The Management section 114 | `````````````````````` 115 | 116 | The Management section specifies the management interface configuration, 117 | for example:: 118 | 119 | [Management] 120 | Enable = true 121 | Path = "/home/user/.local/share/katzenpost/management_sock" 122 | 123 | * ``Enable`` enables the management interface. 124 | 125 | * ``Path`` specifies the path to the management interface socket. If 126 | left empty it will use `management_sock` under the DataDir. 127 | 128 | 129 | Using the management interface 130 | ----------------------------- 131 | 132 | Several mailproxy management commands are supported: 133 | 134 | * ``GET_RECIPIENT`` - Returns the given user's public identity key. 135 | The syntax of the command is as follows:: 136 | 137 | GET_RECIPIENT username 138 | 139 | * ``SET_RECIPIENT`` - Sets the given user's public identity key specified in hex or base64. 140 | The syntax of the command is as follows:: 141 | 142 | SET_RECIPIENT username X25519_public_key_in_hex_or_base64 143 | 144 | * ``REMOVE_RECIPIENT`` - Removes a given recipient. 145 | The syntax of the command is as follows:: 146 | 147 | REMOVE_RECIPIENT username 148 | 149 | * ``LIST_RECIPIENTS`` - Lists all the recipients. 150 | This command expects no arguments. 151 | -------------------------------------------------------------------------------- /handbook/nonvoting_pki.rst: -------------------------------------------------------------------------------- 1 | Katzenpost Mix Network Public Key Infrastructure 2 | ================================================ 3 | 4 | Overview 5 | -------- 6 | 7 | This is essentially a single point of failure. If this PKI system becomes 8 | compromised by an adversary it's game over for anonymity and security 9 | guarantees. Consider using the voting authority instead. 10 | 11 | The Katzenpost voting Directory Authority system is a replacement for 12 | the non-voting Directory Authority. However it's votiing protocol is 13 | NOT byzantine fault tolerant. Therefore a Directory Authority server 14 | which is participating in the voting protocol can easily perform a 15 | denial of service attack for each voting round. This would cause the 16 | mix network to become totally unusable. 17 | 18 | All Katzenpost PKI systems have two essential components: 19 | 20 | * a client library 21 | * server infrastructure 22 | 23 | Furthermore this client library has two types of users, namely mixes 24 | and clients. That is, mixes must use the library to upload/download 25 | their mix descriptors and clients use the library to download a 26 | network consensus document so that they can route messages through the 27 | mix network. 28 | 29 | 30 | Install 31 | ------- 32 | 33 | See the authority readme: 34 | 35 | * https://github.com/katzenpost/authority 36 | 37 | 38 | Configuration 39 | ------------- 40 | 41 | A sample configuration file can be found in our docker repository, here: 42 | 43 | * https://github.com/katzenpost/docker 44 | 45 | 46 | CLI usage of The Non-voting Directory Authority 47 | ----------------------------------------------- 48 | 49 | The non-voting authority has the following commandline usage:: 50 | 51 | ./nonvoting --help 52 | Usage of ./nonvoting: 53 | -f string 54 | Path to the authority config file. (default "katzenpost-authority.toml") 55 | -g Generate the keys and exit immediately. 56 | 57 | 58 | The ``-g`` option is used to generate the public and private keys for 59 | the Directory Authority. Clients of the PKI will use this public key 60 | to verify retrieved network consensus documents. However before 61 | invoking the authority with this commandline option you MUST provide a 62 | valid configuration file. This file will specify a data directory 63 | where these keys will be written. Normal invocation will omit this 64 | ``-g`` option because the keypair should already be present. 65 | 66 | A minimal configuration suitable for using with this ``-g`` option for 67 | generating the key pair looks like this:: 68 | 69 | [Authority] 70 | Addresses = [ "192.0.2.1:12345" ] 71 | DataDir = "/var/run/katzauth" 72 | 73 | Example invocation commandline:: 74 | 75 | ./nonvoting -g -f my_authority_config.toml 76 | 77 | However the invocation may fail if the permissions on the data directory 78 | are not restricted to the owning user:: 79 | 80 | ./nonvoting -g -f my_authority_config.toml 81 | Failed to spawn authority instance: authority: DataDir '/var/run/katzauth' has invalid permissions 'drwxr-xr-x' 82 | 83 | Fix permissions like so:: 84 | 85 | chmod 700 /var/run/katzauth 86 | 87 | A successful run will print output that looks like this:: 88 | 89 | 14:47:43.141 NOTI authority: Katzenpost is still pre-alpha. DO NOT DEPEND ON IT FOR STRONG SECURITY OR ANONYMITY. 90 | 14:47:43.142 NOTI authority: Authority identity public key is: 375F00F6EA20ACFB3F4CDCA7FDB50AE427BF02035B6A2F5789281DAA7290B2BB 91 | 92 | Note that if you choose to configure logging to a file one disk, you 93 | can implement log rotation by moving the log file and then sending the 94 | ``HUP`` to the authority server process. This will cause the daemon to 95 | rewrite the log file in the location specified by the config file. 96 | 97 | 98 | Configuring The Non-voting Directory Authority 99 | ---------------------------------------------- 100 | 101 | Authority section 102 | ````````````````` 103 | 104 | The Authority section contains information which is mandatory, 105 | for example:: 106 | 107 | [Authority] 108 | Addresses = [ "192.0.2.1:29483", "[2001:DB8::1]:29483" ] 109 | DataDir = "/var/lib/katzenpost-authority" 110 | 111 | * ``Addresses`` contains one or more IP addresses which 112 | correspond to local network interfaces to listen for connections on. 113 | These can be specified as IPv4 or IPv6 addresses. 114 | 115 | * ``DataDir`` specifies the absolute path to the server's 116 | state files including the keypair use to sign network consensus 117 | documents. 118 | 119 | 120 | Logging section 121 | ``````````````` 122 | 123 | The logging section controls the logging, for example:: 124 | 125 | [Logging] 126 | Disable = false 127 | File = "/var/log/katzenpost.log" 128 | Level = "DEBUG" 129 | 130 | * ``Disable`` is used to disable logging if set to ``true``. 131 | 132 | * ``File`` specifies the file to log to. If omitted then stdout is used. 133 | 134 | * ``Debug`` may be set to one of the following: 135 | 136 | * ERROR 137 | * WARNING 138 | * NOTICE 139 | * INFO 140 | * DEBUG 141 | 142 | 143 | Parameters section 144 | `````````````````` 145 | 146 | The Parameters section holds the network parameters, for example:: 147 | 148 | [Parameters] 149 | SendRatePerMinute = 30 150 | Mu = 0.00025 151 | MuMaxDelay = 9000 152 | LambdaP = 15.0 153 | SendShift = 3 154 | LambdaPMaxDelay = 3000 155 | LambdaL = 0.00025 156 | LambdaLMaxDelay = 9000 157 | LambdaD = 0.00025 158 | LambdaDMaxDelay = 9000 159 | LambdaM = 0.00025 160 | LambdaMMaxDelay = 9000 161 | 162 | * ``SendRatePerMinute`` is the rate limiter maximum allowed rate of 163 | packets per client. 164 | 165 | * ``Mu`` is the inverse of the mean of the exponential 166 | distribution that the Sphinx packet per-hop mixing delay will be 167 | sampled from. 168 | 169 | * ``MuMaxDelay`` is the maximum Sphinx packet per-hop mixing 170 | delay in milliseconds. 171 | 172 | * ``LambdaP`` LambdaP is the inverse of the mean of the exponential distribution 173 | that **clients** will sample to determine the time interval between sending 174 | messages from it's FIFO egress queue or drop decoy messages if the queue 175 | is empty. 176 | 177 | * ``LambdaPMaxDelay`` is the maximum send interval for LambdaP in milliseconds 178 | 179 | * ``LambdaL`` LambdaL is the inverse of the mean of the exponential distribution 180 | that **clients** will sample to determine the time interval between sending 181 | decoy loop messages. 182 | 183 | * ``LambdaLMaxDelay`` sets the maximum send interval for LambdaL in milliseconds. 184 | 185 | * ``LambdaD`` is the inverse of the mean of the exponential distribution 186 | that **clients** will sample to determine the time interval between sending 187 | decoy drop messages. 188 | 189 | * ``LambdaDMaxDelay`` is the maximum send interval in milliseconds. 190 | 191 | * ``LambdaM`` is the inverse of the mean of the exponential distribution that 192 | **mixes** will sample to determine send timing of mix loop decoy traffic. 193 | 194 | * ``LambdaMMaxDelay`` sets the maximum delay for LambdaM 195 | 196 | 197 | Mixes section 198 | ````````````` 199 | 200 | The Mixes array defines the list of white-listed non-provider nodes, 201 | for example:: 202 | 203 | [[Mixes]] 204 | IdentityKey = "kAiVchOBwHVtKJVFJLsdCQ9UyN2SlfhLHYqT8ePBetg=" 205 | 206 | [[Mixes]] 207 | IdentityKey = "900895721381C0756D28954524BB1D090F54C8DD9295F84B1D8A93F1E3C17AD8" 208 | 209 | 210 | * ``IdentityKey`` is the node's EdDSA signing key, in either Base16 OR Base64 format. 211 | 212 | 213 | Provider section 214 | ```````````````` 215 | 216 | The Providers array defines the list of white-listed Provider nodes, 217 | for example:: 218 | 219 | [[Providers]] 220 | Identifier = "provider1" 221 | IdentityKey = "0AV1syaCdBbm3CLmgXLj6HdlMNiTeeIxoDc8Lgk41e0=" 222 | 223 | [[Providers]] 224 | Identifier = "provider2" 225 | IdentityKey = "375F00F6EA20ACFB3F4CDCA7FDB50AE427BF02035B6A2F5789281DAA7290B2BB" 226 | 227 | 228 | * ``Identifier`` is the human readable provider identifier, such as a 229 | FQDN. 230 | 231 | * ``IdentityKey`` is the provider's EdDSA signing key, in either 232 | Base16 OR Base64 format. 233 | 234 | -------------------------------------------------------------------------------- /handbook/tor.rst: -------------------------------------------------------------------------------- 1 | 2 | Torification of Katzenpost 3 | ************************** 4 | 5 | .. rubric:: Abstract 6 | 7 | Tor and mixnets provide orthogonal anonymity properties and therefore 8 | it can be advantageous for clients to connect to their mixnet Provider 9 | and Directory Authority service(s) over Tor onion services. This document 10 | describes how to configure these services and a mailproxy client to use Tor 11 | onion services. 12 | 13 | .. contents:: :local: 14 | 15 | 16 | Introduction 17 | ============ 18 | 19 | This document assumes you have already installed Tor. 20 | You can either install Tor as part of the Tor Browser Bundle 21 | or you can install it standalone. Obviously only clients may 22 | be interested in using Tor Browser Bundle. 23 | 24 | 1. Install Tor Browser Bundle: https://www.torproject.org/download/download-easy.html.en 25 | 26 | 2. Install a standlone Tor in Debian/Ubuntu: https://www.torproject.org/docs/debian.html.en 27 | 28 | 29 | Mailproxy 30 | --------- 31 | 32 | Here is a complete mailproxy configuration that uses only Tor onion services 33 | for it's communication with the mix network: 34 | 35 | :: 36 | [Proxy] 37 | POP3Address = "127.0.0.1:2524" 38 | SMTPAddress = "127.0.0.1:2525" 39 | DataDir = "/home/user/.mailproxy" 40 | 41 | [Logging] 42 | Disable = false 43 | Level = "NOTICE" 44 | 45 | [NonvotingAuthority] 46 | [NonvotingAuthority.PlaygroundAuthority] 47 | Address = "lxqkz5d5e3pehagu.onion:61832" 48 | PublicKey = "o4w1Nyj/nKNwho5SWfAIfh7SMU8FRx52nMHGgYsMHqQ=" 49 | 50 | [[Account]] 51 | User = "alice" 52 | Provider = "playground" 53 | ProviderKeyPin = "imigzI26tTRXyYLXujLEPI9QrNYOEgC4DElsFdP9acQ=" 54 | Authority = "PlaygroundAuthority" 55 | 56 | [Management] 57 | Enable = false 58 | 59 | [UpstreamProxy] 60 | PreferedTransports = [ "onion" ] 61 | Type = "tor+socks5" 62 | Network = "tcp" 63 | Address = "127.0.0.1:9050" 64 | -------------------------------------------------------------------------------- /handbook/voting_pki.rst: -------------------------------------------------------------------------------- 1 | Katzenpost Voting Directory Authority 2 | ===================================== 3 | 4 | Overview 5 | -------- 6 | 7 | Most of the mixnet papers are written with the assumption that 8 | the mixnet's PKI exists and performs their functions perfectly. 9 | Our mixnet PKI is a so called Directory Authority design which is 10 | inspired by the Tor's and Mixminion's Directory Authority. 11 | 12 | 13 | For more details about the design of the Katzenpost voting PKI 14 | you should see our specification document: 15 | 16 | * https://github.com/katzenpost/docs/blob/master/specs/pki.rst 17 | 18 | 19 | As with Katzenpost clients and mixes, this authority server uses our 20 | post quantum cryptographic noise based wire protocol as described 21 | in the specification document: 22 | 23 | * https://github.com/katzenpost/docs/blob/master/specs/wire-protocol.rst 24 | 25 | Each authority's configuration has the public link layer key 26 | of each of it's peers for authenticating the wire protocol connection. 27 | 28 | Peers are also configured with each other's public signing key so that they 29 | may verify each other's signatures on votes. The voting system is used to 30 | create a document describing the collective view of the network. Mixnet clients 31 | download the consensus document so that they may utilize the network to route 32 | their Sphinx packets. 33 | 34 | Install 35 | ------- 36 | 37 | See the authority readme: 38 | 39 | * https://github.com/katzenpost/authority 40 | 41 | 42 | CLI usage of The Voting Directory Authority 43 | ------------------------------------------- 44 | 45 | The voting authority has the following commandline usage:: 46 | 47 | ./voting -h 48 | Usage of ./voting: 49 | -f string 50 | Path to the authority config file. (default "katzenpost-authority.toml") 51 | -g Generate the keys and exit immediately. 52 | 53 | The ``-g`` option is used to generate the public and private signing and link keys. 54 | 55 | 56 | Configuring The Voting Directory Authority 57 | ---------------------------------------------- 58 | 59 | A sample configuration file can be found in our docker repository, here: 60 | 61 | * https://github.com/katzenpost/docker 62 | 63 | 64 | Authority section 65 | ````````````````` 66 | 67 | The Authority section contains information which is mandatory, 68 | for example:: 69 | 70 | [Authority] 71 | Addresses = [ "192.0.2.1:29483", "[2001:DB8::1]:29483" ] 72 | DataDir = "/var/lib/katzenpost-authority" 73 | 74 | * ``Addresses`` contains one or more IP addresses which 75 | correspond to local network interfaces to listen for connections on. 76 | These can be specified as IPv4 or IPv6 addresses. 77 | 78 | * ``DataDir`` specifies the absolute path to the server's 79 | state files including the keypair use to sign network consensus 80 | documents. 81 | 82 | 83 | Logging section 84 | ``````````````` 85 | 86 | The logging section controls the logging, for example:: 87 | 88 | [Logging] 89 | Disable = false 90 | File = "/var/log/katzenpost.log" 91 | Level = "DEBUG" 92 | 93 | * ``Disable`` is used to disable logging if set to ``true``. 94 | 95 | * ``File`` specifies the file to log to. If omitted then stdout is used. 96 | 97 | * ``Debug`` may be set to one of the following: 98 | 99 | * ERROR 100 | * WARNING 101 | * NOTICE 102 | * INFO 103 | * DEBUG 104 | 105 | Parameters section 106 | `````````````````` 107 | 108 | The Parameters section holds the network parameters, for example:: 109 | 110 | [Parameters] 111 | SendRatePerMinute = 30 112 | Mu = 0.00025 113 | MuMaxDelay = 9000 114 | LambdaP = 15.0 115 | SendShift = 3 116 | LambdaPMaxDelay = 3000 117 | LambdaL = 0.00025 118 | LambdaLMaxDelay = 9000 119 | LambdaD = 0.00025 120 | LambdaDMaxDelay = 9000 121 | LambdaM = 0.00025 122 | LambdaMMaxDelay = 9000 123 | 124 | * ``SendRatePerMinute`` is the rate limiter maximum allowed rate of 125 | packets per client. 126 | 127 | * ``Mu`` is the inverse of the mean of the exponential 128 | distribution that the Sphinx packet per-hop mixing delay will be 129 | sampled from. 130 | 131 | * ``MuMaxDelay`` is the maximum Sphinx packet per-hop mixing 132 | delay in milliseconds. 133 | 134 | * ``LambdaP`` LambdaP is the inverse of the mean of the exponential distribution 135 | that **clients** will sample to determine the time interval between sending 136 | messages from it's FIFO egress queue or drop decoy messages if the queue 137 | is empty. 138 | 139 | * ``LambdaPMaxDelay`` is the maximum send interval for LambdaP in milliseconds 140 | 141 | * ``LambdaL`` LambdaL is the inverse of the mean of the exponential distribution 142 | that **clients** will sample to determine the time interval between sending 143 | decoy loop messages. 144 | 145 | * ``LambdaLMaxDelay`` sets the maximum send interval for LambdaL in milliseconds. 146 | 147 | * ``LambdaD`` is the inverse of the mean of the exponential distribution 148 | that **clients** will sample to determine the time interval between sending 149 | decoy drop messages. 150 | 151 | * ``LambdaDMaxDelay`` is the maximum send interval in milliseconds. 152 | 153 | * ``LambdaM`` is the inverse of the mean of the exponential distribution that 154 | **mixes** will sample to determine send timing of mix loop decoy traffic. 155 | 156 | * ``LambdaMMaxDelay`` sets the maximum delay for LambdaM 157 | 158 | 159 | Debug Section 160 | ````````````` 161 | 162 | * ``IdentityKey`` is this authority's EdDSA signing key, in either Base16 OR Base64 format. 163 | 164 | * ``LinkKey`` is this authority's ECDH link layer key, in either Base16 OR Base64 format. 165 | 166 | * ``Layers`` is the number of non-provider layers in the network topology. 167 | 168 | * ``MinNoderPerLayer`` is the minimum number of nodes per layer required to form a valid Document. 169 | 170 | * ``GenerateOnly`` if set to true causes the server to halt and clean up the data dir 171 | right after long term key generation. 172 | 173 | 174 | Mixes Section 175 | ````````````` 176 | 177 | The Mixes configuration section looks like this 178 | :: 179 | 180 | [[Mixes]] 181 | IdentityKey = "kAiVchOBwHVtKJVFJLsdCQ9UyN2SlfhLHYqT8ePBetg=" 182 | 183 | [[Mixes]] 184 | IdentityKey = "900895721381C0756D28954524BB1D090F54C8DD9295F84B1D8A93F1E3C17AD8" 185 | 186 | * ``IdentityKey`` is the node's EdDSA signing key, in either Base16 OR Base64 format. 187 | 188 | 189 | Providers Section 190 | ````````````````` 191 | 192 | Configure like so: 193 | :: 194 | 195 | [[Providers]] 196 | Identifier = "example.com" 197 | IdentityKey = "0AV1syaCdBbm3CLmgXLj6HdlMNiTeeIxoDc8Lgk41e0=" 198 | 199 | * ``Identifier`` is the human readable provider identifier, such as a FQDN. 200 | 201 | * ``IdentityKey`` is the provider's EdDSA signing key, in either Base16 OR Base64 format. 202 | -------------------------------------------------------------------------------- /mixnet_academy/syllabus.rst: -------------------------------------------------------------------------------- 1 | Learn Mix Networks for Great Good 2 | ********************************* 3 | 4 | (maybe the second title should be: Prevent Murder using Mathematics) 5 | 6 | 7 | Course Syllabus And Reading List 8 | ================================ 9 | 10 | There are no good introductory papers on mix networks. Instead, the 11 | approach is to read all the really important academic papers on mix 12 | networks. These papers are roughly organized into several categories 13 | such as: 14 | 15 | .. contents:: :local: 16 | 17 | Missing from this list are ``verified shuffles``. These are 18 | specialized mix strategies which at times are very useful for specific 19 | use cases such as ``voting``. 20 | 21 | In a few of these mixnet sections I have included youtube videos I've 22 | made to help explain some of the fundamental mixnet concepts. As you 23 | read these mixnet papers keep in mind that decryption mixnets have the 24 | following attack categories: 25 | 26 | * tagging attacks 27 | * n-1 attacks 28 | * compulsion attacks 29 | * statistical disclosure attacks 30 | * epistemic attacks 31 | 32 | After all this mix network literature we turn to the 33 | ``Classical Packet Switching Network Literature`` below in the next major section 34 | of reading. Many of these important papers happen to not be academic 35 | papers but rather come from industry/IETF and are RFCs. Why read these? 36 | Aren't mixnet papers enough? Yes if you want to only publish papers on mix 37 | networks then reading about only mix networks may be enough. 38 | 39 | However if you want to design real world mix network systems then 40 | understanding the mathematical limitations of the packet switching 41 | networking design space is extremely important! You must read about 42 | the early Internet design mistakes to understand what not to do in 43 | your mix network designs. In your mix network designs you must take 44 | care to avoid such fatal conditions such as **Congestion Collapse**. 45 | 46 | Have questions? Sit on them for a week and voraciously read papers. 47 | If you still have questions then do feel free to ask me. We have a mailing 48 | list and IRC channel for such things: 49 | 50 | * https://katzenpost.mixnetworks.org/contribute.html#communication 51 | 52 | 53 | Mix Network Fundamentals 54 | ------------------------ 55 | 56 | Watch lecture "A Brief Introduction to mix networks." 57 | 58 | * https://www.youtube.com/watch?v=1VMUb47QhfE 59 | 60 | Read Introduction blog post: "Introduction to Mix Networks and Anonymous Communication Networks" 61 | 62 | * https://leastauthority.com/blog/mixnet-intro/ 63 | 64 | "Untraceable electronic mail, return addresses, and digital pseudonyms" 65 | 66 | * https://www.freehaven.net/anonbib/cache/chaum-mix.pdf 67 | 68 | "Anonymity Trilemma: Strong Anonymity, Low Bandwidth Overhead, Low Latency --- Choose Two" 69 | 70 | * https://eprint.iacr.org/2017/954.pdf 71 | 72 | Mix Strategies 73 | -------------- 74 | 75 | "From a Trickle to a Flood: Active Attacks on Several Mix Types" 76 | 77 | * https://www.freehaven.net/anonbib/cache/trickle02.pdf 78 | 79 | "Why I'm not an Entropist" 80 | 81 | * https://www.freehaven.net/anonbib/cache/entropist.pdf 82 | 83 | "Sleeping dogs lie on a bed of onions but wake when mixed" 84 | 85 | * https://bib.mixnetworks.org/pdf/pets2011.pdf 86 | 87 | "Stop-and-Go MIXes: Providing Probabilistic Anonymity in an Open System" 88 | 89 | * https://www.freehaven.net/anonbib/cache/stop-and-go.pdf 90 | 91 | "Heartbeat Traffic to Counter (n-1) Attacks" 92 | 93 | * https://www.freehaven.net/anonbib/cache/danezis:wpes2003.pdf 94 | 95 | "Generalising Mixes" 96 | 97 | * https://www.freehaven.net/anonbib/cache/diaz:pet2003.ps.gz 98 | 99 | Mix Network Topology 100 | -------------------- 101 | 102 | Watch lecture "Mix Network Topology" 103 | 104 | * https://www.youtube.com/watch?v=bxk4H_X_OsM 105 | 106 | "Impact of Network Topology on Anonymity and Overhead in Low-Latency Anonymity Networks" 107 | 108 | * https://www.esat.kuleuven.be/cosic/publications/article-1230.pdf 109 | 110 | "The disadvantages of free MIX routes and how to overcome them" 111 | 112 | * https://www.freehaven.net/anonbib/cache/disad-free-routes.pdf 113 | 114 | 115 | Compulsion Attacks And Packet Format 116 | ------------------------------------ 117 | 118 | "Sphinx: A Compact and Provably Secure Mix Format" 119 | 120 | * https://www.freehaven.net/anonbib/cache/DBLP:conf/sp/DanezisG09.pdf 121 | 122 | "Compulsion Resistant Anonymous Communications" 123 | 124 | * https://www.freehaven.net/anonbib/cache/ih05-danezisclulow.pdf 125 | 126 | "Forward Secure Mixes" 127 | 128 | * https://www.freehaven.net/anonbib/cache/Dan:SFMix03.pdf 129 | 130 | Note that Jeff Burdges has designed but not completely specified a 131 | new forward secure mix design that uses Post Quantum cryptographic 132 | ratchets. You can learn more about this here: 133 | 134 | * https://github.com/burdges/lake 135 | 136 | 137 | Statistical Disclosure Attacks and Decoy Traffic 138 | ------------------------------------------------ 139 | 140 | Watch lecture "Introduction to Statistical Disclosure Attacks and Defenses for Mix Networks" 141 | 142 | * https://www.youtube.com/watch?v=pHLbe1JKrAQ&t=229s 143 | 144 | "Statistical Disclosure or Intersection Attacks on Anonymity Systems" 145 | 146 | * https://www.freehaven.net/anonbib/cache/DanSer04.ps 147 | 148 | "Taxonomy of Mixes and Dummy Traffic" 149 | 150 | * https://www.freehaven.net/anonbib/cache/taxonomy-dummy.pdf 151 | 152 | "Limits of Anonymity in Open Environments" 153 | 154 | * https://www.freehaven.net/anonbib/cache/limits-open.pdf 155 | 156 | "Reasoning about the Anonymity Provided by Pool Mixes that Generate Dummy Traffic" 157 | 158 | * https://www.freehaven.net/anonbib/cache/pool-dummy04.pdf 159 | 160 | 161 | Epistemic Attacks 162 | ----------------- 163 | 164 | "Route Finger printing in Anonymous Communications" 165 | 166 | * https://www.cl.cam.ac.uk/~rnc1/anonroute.pdf 167 | 168 | "Bridging and Fingerprinting: Epistemic Attacks on Route Selection" 169 | 170 | * https://www.freehaven.net/anonbib/cache/danezis-pet2008.pdf 171 | 172 | "Local View Attack on Anonymous Communication" 173 | 174 | * https://www.freehaven.net/anonbib/cache/esorics05-Klonowski.pdf 175 | 176 | 177 | Modern Mix Network Designs 178 | -------------------------- 179 | 180 | "The Loopix Anonymity System" 181 | 182 | * https://arxiv.org/pdf/1703.00536.pdf 183 | 184 | "No right to remain silent: Isolating Malicious Mixes" 185 | 186 | * https://eprint.iacr.org/2017/1000.pdf 187 | 188 | "A Reputation System to Increase MIX-Net Reliability" 189 | 190 | * https://www.freehaven.net/anonbib/cache/mix-acc.pdf 191 | 192 | "Two Cents for Strong Anonymity: The Anonymous Post-office Protocol" 193 | 194 | * https://eprint.iacr.org/2016/489.pdf 195 | 196 | "Vuvuzela: Scalable Private Messaging Resistant to Traffic Analysis" 197 | 198 | * https://www.freehaven.net/anonbib/cache/vuvuzela:sosp15.pdf 199 | 200 | 201 | Classical Packet Switching Network Literature 202 | ============================================= 203 | 204 | .. contents:: :local: 205 | 206 | 207 | Congestion Control 208 | ------------------ 209 | 210 | "RFC 896: Congestion Control in IP/TCP Internetworks" 211 | 212 | * https://tools.ietf.org/html/rfc896 213 | 214 | "Congestion Avoidance and Control" 215 | 216 | * http://ee.lbl.gov/papers/congavoid.pdf 217 | 218 | "Promoting the Use of End-to-End Congestion Control in the Internet" 219 | 220 | * https://www.icir.org/floyd/papers/collapse.may99.pdf 221 | 222 | "RFC5681: TCP Congestion Control" 223 | 224 | * https://tools.ietf.org/html/rfc5681 225 | 226 | 227 | Automatic Repeat Request Protocol Considerations 228 | ------------------------------------------------ 229 | 230 | NOTE: many more papers by Milica Stojanovic about underwater acoustic network 231 | protocols can be found here: 232 | 233 | * http://millitsa.coe.neu.edu/?q=publications 234 | 235 | "Optimization of a Data Link Protocol for an Underwater Acoustic Channel" 236 | 237 | * http://web.mit.edu/millitsa/www/resources/pdfs/arq.pdf 238 | 239 | 240 | Router Scheduling (for general purpose computers) 241 | ------------------------------------------------- 242 | 243 | "SEDA: An Architecture for Well-Conditioned, Scalable Internet Services" 244 | 245 | * http://www.sosp.org/2001/papers/welsh.pdf 246 | 247 | 248 | Active Queue Management 249 | ----------------------- 250 | 251 | "Controlling Queue Delay: A modern AQM is just one piece of the solution to bufferbloat" 252 | 253 | * https://dl.acm.org/ft_gateway.cfm?id=2209336&ftid=1217981&dwn=1 254 | 255 | "Random Early Detection Gateways for Congestion Avoidance" 256 | 257 | * http://www.icir.org/floyd/papers/early.pdf 258 | 259 | "Controlled Delay Active Queue Management" 260 | 261 | * https://tools.ietf.org/html/draft-ietf-aqm-codel-07 262 | 263 | "Stochastic Fair Blue: A Queue Management Algorithm for Enforcing Fairness" 264 | 265 | * http://www.thefengs.com/wuchang/blue/41_2.PDF 266 | 267 | "RSFB: Resilient Stochastic Fair Blue algorithm" 268 | 269 | * https://sites.google.com/site/cwzhangres/home/files/RSFBaResilientStochasticFairBluealgorithmagainstspoofingDDoSattacks.pdf 270 | 271 | 272 | Attacks on Congestion Control 273 | ----------------------------- 274 | 275 | "the TCP Daytona paper" 276 | 277 | * http://cseweb.ucsd.edu/~savage/papers/CCR99.pdf 278 | 279 | "Low-Rate TCP-Targeted Denial of Service Attacks (The Shrew vs. the Mice and Elephants)" 280 | 281 | * http://www.cs.cornell.edu/People/egs/cornellonly/syslunch/spring04/p75-kuzmanovic.pdf 282 | 283 | "Flow level detection and filtering of low-rate DDoS" 284 | 285 | * http://discovery.ucl.ac.uk/1399235/2/1399235.pdf 286 | 287 | "The Sniper Attack: Anonymously Deanonymizing and Disabling the Tor Network" 288 | 289 | * https://www.freehaven.net/anonbib/cache/sniper14.pdf 290 | 291 | 292 | Congestion Control with Explicit Signaling 293 | ------------------------------------------ 294 | 295 | NOTE: for more reading on this subject refer to Dr. Sally Floyd's ECN reading list: 296 | 297 | * http://www.icir.org/floyd/ecn.html 298 | 299 | "TCP and Explicit Congestion Notification" 300 | 301 | * http://www.icir.org/floyd/papers/tcp_ecn.4.pdf 302 | 303 | "The Benefits of Using Explicit Congestion Notification (ECN)" 304 | 305 | * https://tools.ietf.org/html/rfc8087 306 | 307 | "Performance Evaluation of Explicit Congestion Notification (ECN) in IP Networks" 308 | 309 | * https://tools.ietf.org/html/rfc2884 310 | -------------------------------------------------------------------------------- /papers/catshadow_threat_model/Makefile: -------------------------------------------------------------------------------- 1 | 2 | default: 3 | latex catshadow.tex 4 | bibtex catshadow.aux 5 | latex catshadow.tex 6 | pdflatex catshadow.tex 7 | -------------------------------------------------------------------------------- /papers/catshadow_threat_model/bibliography.bib: -------------------------------------------------------------------------------- 1 | 2 | @article{notions-pets2019, 3 | title = {On Privacy Notions in Anonymous Communication}, 4 | author = {Christiane Kuhn and Martin Beck and Stefan Schiffner and Eduard Jorswieck and 5 | Thorsten Strufe}, 6 | journal = {Proceedings on Privacy Enhancing Technologies}, 7 | volume = {2019}, 8 | number = {2}, 9 | year = {2019}, 10 | month = {April}, 11 | www_tags = {selected}, 12 | www_pdf_url = {https://petsymposium.org/2019/files/papers/issue2/popets-2019-0022.pdf}, 13 | www_section = {Traffic analysis}, 14 | } 15 | 16 | @article{piotrowska2017loopix, 17 | Author = {Piotrowska, Ania and Hayes, Jamie and Elahi, Tariq and Meiser, Sebastian and Danezis, George}, 18 | Journal = {arXiv preprint arXiv:1703.00536}, 19 | Title = {The Loopix Anonymity System}, 20 | Url = {https://arxiv.org/pdf/1703.00536}, 21 | Year = {2017}, 22 | Bdsk-Url-1 = {https://arxiv.org/pdf/1703.00536}} 23 | 24 | @inproceedings{DanezisG09, 25 | author = {George Danezis and Ian Goldberg}, 26 | title = {Sphinx: A Compact and Provably Secure Mix Format}, 27 | booktitle = {Proceedings of the 30th IEEE Symposium on Security and Privacy (S\&P 2009)}, 28 | year = {2009}, 29 | pages = {269--282}, 30 | ee = {http://dx.doi.org/10.1109/SP.2009.15}, 31 | www_tags = {selected}, 32 | www_pdf_url = {http://research.microsoft.com/en-us/um/people/gdane/papers/sphinx-eprint.pdf}, 33 | www_section = comm 34 | } 35 | 36 | @inproceedings{stop-and-go, 37 | Author = {Dogan Kesdogan and Jan Egner and Roland B\"uschkes}, 38 | Booktitle = {Proceedings of Information Hiding Workshop (IH 1998)}, 39 | Publisher = {Springer-Verlag, LNCS 1525}, 40 | Title = {Stop-and-Go {MIX}es: Providing Probabilistic Anonymity in an Open System}, 41 | Www_Pdf_Url = {http://www.uow.edu.au/~ldn01/infohide98.pdf}, 42 | Www_Tags = {selected}, 43 | Year = {1998}} 44 | 45 | @inproceedings{topology-pet2010, 46 | title = {Impact of Network Topology on Anonymity and Overhead in Low-Latency Anonymity Networks}, 47 | author = {Claudia Diaz and Steven J. Murdoch and Carmela Troncoso}, 48 | booktitle = {Proceedings of the 10th Privacy Enhancing Technologies Symposium (PETS 2010)}, 49 | year = {2010}, 50 | month = {July}, 51 | location = {Berlin, Germany}, 52 | www_tags = {selected}, 53 | www_pdf_url = {http://www.cosic.esat.kuleuven.be/publications/article-1230.pdf}, 54 | www_section = traffic 55 | } 56 | 57 | 58 | @online{KatzMixnet, 59 | title = {Katzenpost Mix Network Specification}, 60 | author = {Yawning Angel and George Danezis and Claudia Diaz and Ania Piotrowska and David Stainton}, 61 | url = {https://github.com/Katzenpost/docs/blob/master/specs/mixnet.rst}, 62 | year = {2017} 63 | } 64 | 65 | @online{KatzEndToEnd, 66 | title = {Katzenpost Mix Network Specification}, 67 | author = {Yawning Angel and George Danezis and Claudia Diaz and Ania Piotrowska and David Stainton}, 68 | url = {https://github.com/Katzenpost/docs/blob/master/specs/mixnet.rst}, 69 | year = {2017} 70 | } 71 | 72 | 73 | @online{KatzMixWire, 74 | title = {Katzenpost Mix Network Wire Protocol Specification}, 75 | author = {Yawning Angel}, 76 | url = {https://github.com/katzenpost/docs/blob/master/specs/wire-protocol.rst}, 77 | year = {2017} 78 | } 79 | 80 | @online{KatzMixPKI, 81 | title = {Katzenpost Mix Network Public Key Infrastructure Specification}, 82 | author = {Yawning Angel and Ania Piotrowska and David Stainton}, 83 | url= {https://github.com/katzenpost/docs/blob/master/specs/pki.rst}, 84 | year = {2017} 85 | } 86 | 87 | @online{SphinxSpec, 88 | title = {Sphinx Mix Network Cryptographic Packet Format Specification}, 89 | author = {Yawning Angel and George Danezis and Claudia Diaz and Ania Piotrowska and David Stainton}, 90 | url = {https://github.com/katzenpost/docs/blob/master/specs/sphinx.rst}, 91 | year = {2017} 92 | } 93 | 94 | @inproceedings{danezis:wpes2003, 95 | Author = {George Danezis and Len Sassaman}, 96 | Booktitle = {{Proceedings of the Workshop on Privacy in the Electronic Society (WPES 2003)}}, 97 | Location = {Washington, DC, USA}, 98 | Month = {October}, 99 | Title = {Heartbeat Traffic to Counter (n-1) Attacks}, 100 | Www_Pdf_Url = {http://www.cl.cam.ac.uk/users/gd216/p125_danezis.pdf}, 101 | Www_Remarks = {Mix nodes should send out "heartbeat" messages (dummies that start and end at that node). By measuring how many return in a given time, they can detect whether the adversary is dropping or delaying traffic coming into them (possibly so he can launch an active blending attack).}, 102 | Www_Tags = {selected}, 103 | Year = {2003}} 104 | 105 | @inproceedings{trickle02, 106 | Author = {Andrei Serjantov and Roger Dingledine and Paul Syverson}, 107 | Booktitle = {Proceedings of Information Hiding Workshop (IH 2002)}, 108 | Editor = {Fabien Petitcolas}, 109 | Month = {October}, 110 | Publisher = {Springer-Verlag, LNCS 2578}, 111 | Title = {From a Trickle to a Flood: Active Attacks on Several Mix Types}, 112 | Www_Important = {1}, 113 | Www_Pdf_Url = {http://freehaven.net/doc/batching-taxonomy/taxonomy.pdf}, 114 | Www_Ps_Url = {http://freehaven.net/doc/batching-taxonomy/taxonomy.ps}, 115 | Www_Tags = {selected}, 116 | Year = {2002}} 117 | 118 | @inproceedings{danezis-pet2008, 119 | title = {Bridging and Fingerprinting: Epistemic Attacks on Route Selection}, 120 | author = {George Danezis and Paul Syverson}, 121 | booktitle = {Proceedings of the Eighth International Symposium on Privacy Enhancing 122 | Technologies (PETS 2008)}, 123 | year = {2008}, 124 | month = {July}, 125 | location = {Leuven, Belgium}, 126 | pages = {133--150}, 127 | editor = {Nikita Borisov and Ian Goldberg}, 128 | publisher = {Springer}, 129 | www_important = {1}, 130 | www_tags = {selected}, 131 | bookurl = {http://petsymposium.org/2008/}, 132 | www_pdf_url = {http://research.microsoft.com/~gdane/papers/bridge.pdf}, 133 | www_section = {Traffic analysis}, 134 | } 135 | 136 | @inproceedings{esorics05-Klonowski, 137 | title = {Local View Attack on Anonymous Communication}, 138 | author = {Marcin Gogolewski and Marek Klonowski and Miroslaw Kutylowski}, 139 | booktitle = {Proceedings of ESORICS 2005}, 140 | year = {2005}, 141 | month = {September}, 142 | www_tags = {selected}, 143 | www_ps_url = {http://www.im.pwr.wroc.pl/~klonowsk/LocalViewAttack.ps}, 144 | www_section = {Traffic analysis}, 145 | } 146 | 147 | @inproceedings{DanezisC06, 148 | author = {George Danezis and 149 | Richard Clayton}, 150 | title = {Route Fingerprinting in Anonymous Communications}, 151 | booktitle = {Sixth {IEEE} International Conference on Peer-to-Peer Computing {(P2P} 152 | 2006), 2-4 October 2006, Cambridge, United Kingdom}, 153 | pages = {69--72}, 154 | year = {2006}, 155 | url = {https://doi.org/10.1109/P2P.2006.33}, 156 | doi = {10.1109/P2P.2006.33}, 157 | timestamp = {Wed, 16 Oct 2019 14:14:52 +0200}, 158 | biburl = {https://dblp.org/rec/bib/conf/p2p/DanezisC06}, 159 | bibsource = {dblp computer science bibliography, https://dblp.org} 160 | } 161 | 162 | @inproceedings{ih05-danezisclulow, 163 | Author = {George Danezis and Jolyon Clulow}, 164 | Booktitle = {Proceedings of Information Hiding Workshop (IH 2005)}, 165 | Month = {June}, 166 | Pages = {11--25}, 167 | Title = {Compulsion Resistant Anonymous Communications}, 168 | Www_Pdf_Url = {http://www.cl.cam.ac.uk/users/gd216/compel.pdf}, 169 | Www_Tags = {selected}, 170 | Year = {2005}} 171 | 172 | @inproceedings{Dan:SFMix03, 173 | Author = {George Danezis}, 174 | Booktitle = {Proceedings of 7th Nordic Workshop on Secure {IT} Systems}, 175 | Day = {7}, 176 | Editor = {Fisher-Hubner, Jonsson}, 177 | Location = {Karlstad, Sweden}, 178 | Month = {November}, 179 | Pages = {195--207}, 180 | Title = {Forward Secure Mixes}, 181 | Www_Pdf_Url = {http://www.cl.cam.ac.uk/~gd216/fsmix.pdf}, 182 | Www_Tags = {selected}, 183 | Year = {2002}} 184 | 185 | @misc{cryptoeprint:2016:489, 186 | Author = {Nethanel Gelernter and Amir Herzberg and Hemi Leibowitz}, 187 | Howpublished = {Cryptology ePrint Archive, Report 2016/489}, 188 | Title = {Two Cents for Strong Anonymity: The Anonymous Post-office Protocol}, 189 | Url = {https://eprint.iacr.org/2016/489.pdf}, 190 | Year = {2016}, 191 | Bdsk-Url-1 = {https://eprint.iacr.org/2016/489.pdf}} 192 | 193 | @misc{cryptoeprint:2017:1000, 194 | title = {No right to remain silent: Isolating Malicious Mixes}, 195 | author = {Hemi Leibowitz and Ania Piotrowska and George Danezis and Amir Herzberg}, 196 | year = {2017}, 197 | month = {October}, 198 | howpublished = {Cryptology ePrint Archive, Report 2017/1000}, 199 | www_tags = {selected}, 200 | www_section = {Anonymous communication}, 201 | www_pdf_url = {http://eprint.iacr.org/2017/1000.pdf}, 202 | www_html_url = {http://eprint.iacr.org/2017/1000}, 203 | } 204 | 205 | @inproceedings{minion-design, 206 | title = {{Mixminion: Design of a Type III Anonymous Remailer Protocol}}, 207 | author = {George Danezis and Roger Dingledine and Nick Mathewson}, 208 | booktitle = {Proceedings of the 2003 IEEE Symposium on Security and Privacy}, 209 | year = {2003}, 210 | month = {May}, 211 | pages = {2--15}, 212 | www_important = {1}, 213 | www_tags = {selected}, 214 | www_section = {Anonymous communication}, 215 | www_pdf_url = {http://mixminion.net/minion-design.pdf}, 216 | } 217 | 218 | @online{PANDA, 219 | title = {Going Dark: Phrase Automated Nym Discovery Authentication}, 220 | author = {Jacob Appelbaum and another cypherpunk}, 221 | url = {https://github.com/agl/pond/blob/master/papers/panda/panda.tex}, 222 | year = {2014} 223 | } 224 | -------------------------------------------------------------------------------- /papers/catshadow_threat_model/catshadow.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/katzenpost/docs/020afcc17a349622e4e26f72ffffc4e736553051/papers/catshadow_threat_model/catshadow.pdf -------------------------------------------------------------------------------- /setup.rst: -------------------------------------------------------------------------------- 1 | How to Set Up Your Own Katzenpost Mixnet 2 | **************************************** 3 | 4 | .. warning:: 5 | 6 | Katzenpost is still pre-alpha. DO NOT DEPEND ON IT FOR STRONG SECURITY OR ANONYMITY. 7 | 8 | 9 | .. caution:: 10 | 11 | Mix networks are meant to be decentralized and therefore should 12 | be operated by multiple entities. You can of course be the only 13 | operator of a mix network for testing purposes. 14 | 15 | 16 | Build Software 17 | ============== 18 | 19 | Take a look at our docker repo. This will explain how to configure and run a katzenpost mixnet. 20 | 21 | * https://github.com/katzenpost/docker 22 | 23 | A Katzenpost mix network has two binary programs, a :term:`PKI` and a 24 | :term:`Mix`/:term:`Provider`. 25 | 26 | Katzenpost server side requires a recent golang. 27 | See golang install instructions: 28 | https://golang.org/doc/install 29 | 30 | 31 | Follow the build instructions for each Katzenpost component repo. 32 | 33 | * https://github.com/katzenpost/server 34 | 35 | * https://github.com/katzenpost/authority 36 | 37 | The produced binaries are statically linked, so you can build the 38 | authority and the server code on one machine, and then distribute 39 | them to any Linux based machines to run. 40 | 41 | 42 | Synchronize Clock 43 | ================= 44 | 45 | Each network component, the PKI and mixes/providers, 46 | MUST have the correct time. We recommend 47 | `chrony `_ for the purpose of time synchronization. 48 | 49 | .. code:: console 50 | 51 | apt install chrony 52 | 53 | 54 | Add Users to the Provider 55 | ========================= 56 | 57 | This step might not need to be performed if you are using a client 58 | that auto-registers users with their Katzenpost Provider; such as catchat. 59 | 60 | Add :term:`User`\s to the :term:`Provider` using the management interface: 61 | 62 | .. code:: console 63 | 64 | socat unix://management_sock STDOUT 65 | ADD_USER alice X25519_public_key_in_hex_or_base64 66 | 67 | In case you want to use the automatic key discovery for mailproxy, the user identity key (identity.public.pem) also needs to be set: 68 | 69 | .. code:: console 70 | 71 | SET_USER_IDENTITY alice X25519_public_key_in_hex_or_base64 72 | -------------------------------------------------------------------------------- /software_bill_of_materials/index.rst: -------------------------------------------------------------------------------- 1 | Katzenpost Software Bill of Materials 2 | ************************************* 3 | 4 | .. rubric:: Abstract 5 | 6 | This document describes the Katzenpost software dependencies and their 7 | licenses for the core katzenpost server side components AND the 8 | catshadow anonymous messaging system with QT user interface. This 9 | document is meant to be useful for determining software license 10 | compliance and to assist in audits. 11 | 12 | 13 | Dependencies and Licenses 14 | ========================= 15 | 16 | We use go-modules ( https://github.com/golang/go/wiki/Modules ) in 17 | each golang git repository to pin dependencies. Therefore these 18 | dependencies can easily be derived from the `go.mod` file at the 19 | root of each git repo. Auditors wishing to quickly learn the transitive 20 | dependencies can do so by looking at these files. 21 | 22 | 23 | Core 24 | ---- 25 | 26 | github.com/katzenpost/core with license AGPL-3.0 27 | 28 | The Katzenpost Core library depends on: 29 | 30 | * git.schwanenlied.me/yawning/aez.git with license CC0 1.0 Universal 31 | * git.schwanenlied.me/yawning/bsaes.git with license https://git.schwanenlied.me/yawning/bsaes/src/master/LICENSE.txt 32 | * github.com/agl/ed25519 with license BSD-3-Clause 33 | * github.com/stretchr/testify with license MIT 34 | * github.com/ugorji/go/codec with license MIT 35 | * golang.org/x/crypto with license https://github.com/golang/crypto/blob/master/LICENSE 36 | * gopkg.in/op/go-logging.v1 with license BSD-3-Clause 37 | 38 | Forks of external dependencies: 39 | 40 | * github.com/katzenpost/chacha20 with license AGPL-3.0 41 | * github.com/katzenpost/noise with license https://github.com/katzenpost/noise/blob/master/LICENSE 42 | 43 | 44 | Noise 45 | ----- 46 | 47 | https://github.com/katzenpost/noise with license https://github.com/katzenpost/noise/blob/master/LICENSE 48 | 49 | Noise Protocol Framework: Katzenpost fork of the flynn noise library ( https://github.com/flynn/noise ) 50 | 51 | Noise depends on: 52 | 53 | * github.com/flynn/noise with license https://github.com/flynn/noise/blob/master/LICENSE 54 | * golang.org/x/crypto with license https://github.com/golang/crypto/blob/master/LICENSE 55 | * gopkg.in/check.v1 with license https://github.com/go-check/check/blob/v1/LICENSE 56 | 57 | Forks of external dependencies: 58 | 59 | * github.com/katzenpost/newhope 60 | 61 | 62 | Newhope 63 | ------- 64 | 65 | github.com/katzenpost/newhope with license CC0 1.0 Universal 66 | 67 | fork of https://git.schwanenlied.me/yawning/newhope 68 | 69 | depends on: 70 | * github.com/katzenpost/chacha20 with license AGPL-3.0 71 | * golang.org/x/crypto with license https://github.com/golang/crypto/blob/master/LICENSE 72 | 73 | 74 | Chacha20 75 | -------- 76 | 77 | https://github.com/katzenpost/chacha20 with license AGPL-3.0 78 | fork of https://git.schwanenlied.me/yawning/chacha20 79 | 80 | depends on: 81 | 82 | * github.com/stretchr/testify with license MIT 83 | * golang.org/x/sys with license https://github.com/golang/sys/blob/master/LICENSE 84 | 85 | 86 | Authority 87 | --------- 88 | 89 | github.com/katzenpost/authority with license AGPL-3.0 90 | 91 | The Katzenpost Authority depends on: 92 | 93 | * github.com/katzenpost/core with license AGPL-3.0 94 | * github.com/BurntSushi/toml with license MIT 95 | * github.com/coreos/bbolt with license MIT 96 | * github.com/stretchr/testify with license MIT 97 | * github.com/ugorji/go/codec with license MIT 98 | * golang.org/x/crypto with license https://github.com/golang/crypto/blob/master/LICENSE 99 | * golang.org/x/net with license https://github.com/golang/net/blob/master/LICENSE 100 | * gopkg.in/op/go-logging.v1 with license BSD-3-Clause 101 | 102 | Forks of external dependencies: 103 | 104 | * github.com/katzenpost/chacha20 with license AGPL-3.0 105 | 106 | 107 | Server 108 | ------ 109 | 110 | github.com/katzenpost/server with license AGPL-3.0 111 | 112 | Server depends on: 113 | 114 | * github.com/katzenpost/core with license AGPL-3.0 115 | * github.com/katzenpost/authority with license AGPL-3.0 116 | * git.schwanenlied.me/yawning/aez.git with license CC0 1.0 Universal 117 | * git.schwanenlied.me/yawning/avl.git with license CC0 1.0 Universal 118 | * git.schwanenlied.me/yawning/bloom.git with license CC0 1.0 Universal 119 | * github.com/BurntSushi/toml with license MIT 120 | * github.com/coreos/bbolt with license MIT 121 | * github.com/jackc/pgx with license MIT 122 | * github.com/stretchr/testify with license: MIT 123 | * github.com/ugorji/go/codec with license MIT 124 | * golang.org/x/net with license https://github.com/golang/net/blob/master/LICENSE 125 | * golang.org/x/text with license https://github.com/golang/text/blob/master/LICENSE 126 | * gopkg.in/eapache/channels.v1 with license MIT 127 | * gopkg.in/op/go-logging.v1 with license BSD-3-Clause 128 | 129 | 130 | Minclient 131 | --------- 132 | 133 | github.com/katzenpost/minclient with license AGPL-3.0 134 | 135 | Minclient depends on: 136 | 137 | * github.com/katzenpost/core with license AGPL-3.0 138 | * github.com/stretchr/testify with license MIT 139 | * gopkg.in/op/go-logging.v1 with license BSD-3-Clause 140 | 141 | Forks of external dependencies: 142 | 143 | * github.com/katzenpost/noise with license https://github.com/katzenpost/noise/blob/master/LICENSE 144 | 145 | 146 | Client 147 | ------ 148 | 149 | github.com/katzenpost/client with license AGPL-3.0 150 | 151 | Client depends on: 152 | 153 | * github.com/katzenpost/authority with license AGPL-3.0 154 | * github.com/katzenpost/core with license AGPL-3.0 155 | * github.com/katzenpost/kimchi with license AGPL-3.0 156 | * github.com/katzenpost/minclient with license AGPL-3.0 157 | * github.com/katzenpost/registration_client with license AGPL-3.0 158 | * github.com/BurntSushi/toml with license MIT 159 | * github.com/stretchr/testify with license MIT 160 | * golang.org/x/net with license https://github.com/golang/net/blob/master/LICENSE 161 | * golang.org/x/text with license https://github.com/golang/text/blob/master/LICENSE 162 | * gopkg.in/eapache/channels.v1 with license MIT 163 | * gopkg.in/op/go-logging.v1 with license BSD-3-Clause 164 | 165 | 166 | Catshadow 167 | --------- 168 | 169 | github.com/katzenpost/catshadow with license AGPL-3.0 170 | 171 | Client depends on: 172 | 173 | * github.com/katzenpost/core with license AGPL-3.0 174 | * github.com/katzenpost/client with license AGPL-3.0 175 | * github.com/katzenpost/kimchi with license AGPL-3.0 176 | * github.com/katzenpost/memspool with license AGPL-3.0 177 | * github.com/katzenpost/panda with license AGPL-3.0 178 | * github.com/katzenpost/doubleratchet with license https://github.com/katzenpost/doubleratchet/blob/master/LICENSE 179 | * github.com/BurntSushi/toml with license MIT 180 | * github.com/stretchr/testify with license MIT 181 | * github.com/ugorji/go/codec with license MIT 182 | * golang.org/x/crypto with license https://github.com/golang/crypto/blob/master/LICENSE 183 | * gopkg.in/eapache/channels.v1 with license MIT 184 | * gopkg.in/op/go-logging.v1 with license BSD-3-Clause 185 | 186 | Forks of external dependencies: 187 | 188 | * https://github.com/katzenpost/panda/tree/master/crypto with license https://github.com/katzenpost/panda/blob/master/crypto/LICENSE 189 | 190 | 191 | 192 | Catchat 193 | ------- 194 | 195 | https://github.com/katzenpost/catchat with license AGPL-3.0 196 | 197 | depends on: 198 | 199 | * QT, the C++ library with license LGPL-3.0 https://doc.qt.io/qt-5/opensourcelicense.html 200 | * github.com/therecipe/qt/core with license LGPL-3.0 201 | * github.com/katzenpost/catshadow with license AGPL-3.0 202 | * github.com/katzenpost/client with license AGPL-3.0 203 | * github.com/dustin/go-humanize with license MIT 204 | * github.com/BurntSushi/toml with license MIT 205 | * github.com/muesli/go-app-paths with license MIT 206 | * golang.org/x/crypto with license https://github.com/golang/crypto/blob/master/LICENSE 207 | 208 | 209 | Double Ratchet 210 | -------------- 211 | 212 | github.com/katzenpost/doubleratchet with license https://github.com/katzenpost/doubleratchet/blob/master/LICENSE 213 | 214 | fork of double ratchet from agl's pond ( https://github.com/agl/pond ) 215 | 216 | depends on: 217 | 218 | * github.com/agl/ed25519 with license BSD-3-Clause 219 | * golang.org/x/crypto with license https://github.com/golang/crypto/blob/master/LICENSE 220 | * github.com/ugorji/go/codec with license MIT 221 | 222 | 223 | Memspool 224 | -------- 225 | 226 | https://github.com/katzenpost/memspool with license AGPL-3.0 227 | 228 | depends on: 229 | 230 | * github.com/katzenpost/client with license AGPL-3.0 231 | * github.com/katzenpost/core with license AGPL-3.0 232 | * github.com/katzenpost/kimchi with license AGPL-3.0 233 | * github.com/katzenpost/server with license AGPL-3.0 234 | * github.com/coreos/bbolt with license MIT 235 | * github.com/stretchr/testify with license MIT 236 | * github.com/ugorji/go/codec with license MIT 237 | * gopkg.in/op/go-logging.v1 with license BSD-3-Clause 238 | 239 | 240 | 241 | Registration Client 242 | ------------------- 243 | 244 | https://github.com/katzenpost/registration_client with license AGPL-3.0 245 | 246 | This component will hopefully go away soon but we include it for completeness. 247 | 248 | depends on: 249 | 250 | * github.com/katzenpost/core with license AGPL-3.0 251 | * github.com/katzenpost/server with license AGPL-3.0 252 | * golang.org/x/net with license https://github.com/golang/net/blob/master/LICENSE 253 | -------------------------------------------------------------------------------- /specs.rst: -------------------------------------------------------------------------------- 1 | Specifications 2 | ************** 3 | 4 | .. note:: 5 | 6 | The canonical versions of the specifications live in RFC plaintext format at . Pull requests to fix formatting welcome! 7 | 8 | .. toctree:: 9 | :glob: 10 | :maxdepth: 2 11 | 12 | specs/* 13 | -------------------------------------------------------------------------------- /specs/certificate.rst: -------------------------------------------------------------------------------- 1 | Certificate Format Specification 2 | ******************************** 3 | | 4 | | David Stainton 5 | | 6 | | Version 0 7 | | 8 | .. rubric:: Abstract 9 | 10 | This document proposes a certificate format that Katzenpost 11 | mix server, directory authority server and clients will use. 12 | 13 | .. contents:: :local: 14 | 15 | 16 | 1. Introduction 17 | =============== 18 | 19 | Mixes and Directory Authority servers need to have key agility in the 20 | sense of operational abilities such as key rotation and key revocation. 21 | That is, we wish for mixes and authorities to periodically utilize a 22 | long-term signing key for generating certificates for new short-term 23 | signing keys. 24 | 25 | Yet another use-case for these certificate is to replace the use of 26 | JOSE [RFC7515]_ in the voting Directory Authority system [KATZMIXPKI]_ 27 | for the multi-signature documents exchanged for voting and consensus. 28 | 29 | 30 | 1.1 Conventions Used in This Document 31 | ------------------------------------- 32 | 33 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 34 | "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 35 | document are to be interpreted as described in [RFC2119]_. 36 | 37 | 38 | 1.2 Terminology 39 | --------------- 40 | 41 | 42 | 2. Document Format 43 | ================== 44 | 45 | The CBOR [RFC7049]_ serialization format is used to serialize certificates: 46 | :: 47 | 48 | // Signature is a cryptographic signature 49 | // which has an associated signer ID. 50 | type Signature struct { 51 | // Identity is the identity of the signer. 52 | Identity []byte 53 | // Signature is the actual signature value. 54 | Signature []byte 55 | } 56 | 57 | // certificate structure for serializing certificates. 58 | type certificate struct { 59 | // Version is the certificate format version. 60 | Version uint32 61 | 62 | // Expiration is seconds since Unix epoch. 63 | Expiration int64 64 | 65 | // KeyType indicates the type of key 66 | // that is certified by this certificate. 67 | KeyType string 68 | 69 | // Certified is the data that is certified by 70 | // this certificate. 71 | Certified []byte 72 | 73 | // Signatures are the signature of the certificate. 74 | Signatures []Signature 75 | } 76 | 77 | 78 | That is, one or more signatures sign the certificate. However the 79 | ``Certified`` field is not the only information that is signed. The 80 | ``Certified`` field along with the other non-signature fields are all 81 | concatenated together and signed. Before serialization the signatures 82 | are sorted by their identity so that the output is binary deterministic. 83 | 84 | 85 | 2.1 Certificate Types 86 | --------------------- 87 | 88 | The certificate ``type`` field indicates the type of certificate. 89 | So far we have only two types: 90 | 91 | * identity key certificate 92 | * directory authority certificate 93 | 94 | Both mixes and directory authority servers have a secret, long-term 95 | identity key. This key is ideally stored encrypted and offline, it's 96 | used to sign key certificate documents. Key certificates contain a 97 | medium-term signing key that is used to sign other documents. In the 98 | case of an "authority signing key", it is used to sign vote and 99 | consensus documents whereas the "mix singing key" is used to sign mix 100 | descriptors which are uploaded to the directory authority servers. 101 | 102 | 103 | 2.2. Certificate Key Types 104 | -------------------------- 105 | 106 | It's more practical to continue using Ed25519 [ED25519]_ keys but it's 107 | also possible that in the future we could upgrade to a stateless hash 108 | based post quantum cryptographic signature scheme such as SPHINCS-256 109 | or SPHINCS+. [SPHINCS256]_ 110 | 111 | 112 | 3. Golang API 113 | ============= 114 | 115 | * https://godoc.org/github.com/katzenpost/core/crypto/cert 116 | 117 | Our golang implementation is agnostic to the specific cryptographic 118 | signature scheme which is used. Cert can handle single and multiple 119 | signatures per document and has a variety of helper functions that 120 | ease use for multi signature use cases. 121 | 122 | 123 | 4. Acknowledgments 124 | ================== 125 | 126 | This specification was inspired by Tor Project's certificate format 127 | specification document: 128 | 129 | * https://gitweb.torproject.org/torspec.git/tree/cert-spec.txt 130 | 131 | 132 | Appendix A. References 133 | ====================== 134 | 135 | Appendix A.1 Normative References 136 | --------------------------------- 137 | 138 | .. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 139 | Requirement Levels", BCP 14, RFC 2119, 140 | DOI 10.17487/RFC2119, March 1997, 141 | . 142 | 143 | .. [KATZMIXPKI] Angel, Y., Piotrowska, A., Stainton, D., 144 | "Katzenpost Mix Network Public Key Infrastructure Specification", December 2017, 145 | . 146 | 147 | .. [RFC7049] C. Bormannm, P. Hoffman, "Concise Binary Object Representation (CBOR)", 148 | Internet Engineering Task Force (IETF), October 2013, 149 | . 150 | 151 | .. [RFC7693] Saarinen, M-J., Ed., and J-P. Aumasson, "The BLAKE2 152 | Cryptographic Hash and Message Authentication Code 153 | (MAC)", RFC 7693, DOI 10.17487/RFC7693, November 2015, 154 | . 155 | 156 | .. [ED25519] . 157 | 158 | 159 | Appendix A.2 Informative References 160 | ----------------------------------- 161 | 162 | .. [RFC7515] Jones, M., Bradley, J., Sakimura, N., 163 | "JSON Web Signature (JWS)", May 2015, 164 | . 165 | 166 | .. [SPHINCS256] Bernstein, D., Hopwood, D., Hulsing, A., Lange, T., 167 | Niederhagen, R., Papachristodoulou, L., Schwabe, P., Wilcox 168 | O'Hearn, Z., "SPHINCS: practical stateless hash-based signatures", 169 | . 170 | 171 | Appendix B. Citing This Document 172 | ================================ 173 | 174 | Appendix B.1 Bibtex Entry 175 | ------------------------- 176 | 177 | Note that the following bibtex entry is in the IEEEtran bibtex style 178 | as described in a document called "How to Use the IEEEtran BIBTEX Style". 179 | 180 | :: 181 | 182 | @online{KatzenCert, 183 | title = {Certificate Format Specification}, 184 | author = {David Stainton}, 185 | url = {https://github.com/katzenpost/docs/blob/master/specs/certificate.rst}, 186 | year = {2018} 187 | } 188 | -------------------------------------------------------------------------------- /specs/diagrams/replay1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/katzenpost/docs/020afcc17a349622e4e26f72ffffc4e736553051/specs/diagrams/replay1.png -------------------------------------------------------------------------------- /specs/kaetzchen.rst: -------------------------------------------------------------------------------- 1 | Katzenpost Provider-side Autoresponder Extension 2 | ************************************************ 3 | 4 | | Yawning Angel 5 | | Kali Kaneko 6 | | David Stainton 7 | 8 | Version 0 9 | 10 | .. rubric:: Abstract 11 | 12 | This document describes extensions to the core Katzenpost protocol 13 | to support Provider-side autoresponders. 14 | 15 | 16 | .. contents:: :local: 17 | 18 | 1. Introduction 19 | =============== 20 | 21 | This interface is meant to provide support for various autoresponder 22 | agents ("Kaetzchen") that run on Katzenpost provider instances, thus 23 | bypassing the need to run a discrete client instance to provide 24 | functionality. The use-cases for such agents include, but are not 25 | limited to, user identity key lookup, a discard address, and a 26 | loop-back responder for the purpose of cover traffic. 27 | 28 | 1.1 Conventions Used in This Document 29 | ------------------------------------- 30 | 31 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 32 | "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 33 | document are to be interpreted as described in [RFC2119]. 34 | 35 | 1.2. Terminology 36 | ---------------- 37 | 38 | ``SURB`` - "single use reply block"; SURBs are used to achieve 39 | recipient anonymity, that is to say, SURBs function as a 40 | cryptographic delivery token that you can give to another 41 | client entity so that they can send you a message without 42 | them knowing your identity or location on the network. See 43 | [SPHINXSPEC] and [SPHINX]. 44 | 45 | ``BlockSphinxPlaintext`` - The payload structure which is 46 | encapsulated by the Sphinx body. It is described in [KATZMIXE2E], 47 | section "4. Client and Provider processing of received packets". 48 | 49 | 2. Extension Overview 50 | ===================== 51 | 52 | Each Kaetzchen agent will register as a potential recipient on its 53 | Provider. When the Provider receives a forward packet destined for 54 | a Kaetzchen instance, it will hand off the fully unwrapped packet 55 | along with its corresponding SURB to the agent, which will then 56 | act on the packet and optionally reply utilizing the SURB. 57 | 58 | 3. Agent Requirements 59 | ===================== 60 | 61 | * Each agent operation MUST be idempotent. 62 | 63 | * Each agent operation request and response MUST fit within one 64 | Sphinx packet. 65 | 66 | * Each agent SHOULD register a recipient address that is prefixed 67 | with `+` (Or another standardized delimiter, agreed to by all 68 | participating providers in a given mixnet.). 69 | 70 | * Each agent SHOULD register a recipient address that consists 71 | of a [RFC5322] dot-atom value, and MUST register recipient 72 | addresses that are at most 64 octets in length. 73 | 74 | * The first byte of the agent's response payload MUST be 0x01 to 75 | allow clients to easily differentiate between SURB-ACKs and 76 | agent responses. 77 | 78 | 3.1 Mix Message Formats 79 | ----------------------- 80 | 81 | Messages from clients to Kaetzchen use the following payload 82 | format in the forward Sphinx packet:: 83 | 84 | struct { 85 | uint8_t flags; 86 | uint8_t reserved; /* Set to 0x00. */ 87 | select (flags) { 88 | case 0: 89 | opaque padding[sizeof(SphinxSURB)]; 90 | case 1: 91 | SphinxSURB surb; 92 | } 93 | opaque plaintext[]; 94 | } KaetzchenMessage; 95 | 96 | 97 | The plaintext component of a ``KaetzchenMessage`` MUST be padded by 98 | appending '0x00' bytes to make the final total size of a 99 | ``KaetzchenMessage`` equal to that of a ``BlockSphinxPlaintext``. 100 | 101 | Messages (replies) from the Kaetzchen to client use the following 102 | payload format in the SURB generated packet:: 103 | 104 | struct { 105 | uint8_t payload_type; /* Set to 0x01 */ 106 | uint8_t reserved; /* Set to 0x00 */ 107 | opaque plaintext[]; 108 | } KaetzchenReply; 109 | 110 | The plaintext component of a ``KaetzchenReply`` MUST be padded by 111 | appending '0x00' bytes to make the final total size of a 112 | ``KaetzchenReply`` equal to that of a ``BlockSphinxPlaintext``. 113 | 114 | 4. PKI Extensions 115 | ================= 116 | 117 | Each provider SHOULD publish the list of publicly accessible 118 | Kaetzchen agent endpoints in its MixDescriptor, along with 119 | any other information required to utilize the agent. 120 | 121 | Provider should make this information available in the form of a map 122 | in which the keys are the label used to identify a given service, and the 123 | value is a map with arbitrary keys. 124 | 125 | Valid service names refer to the services defined in extensions to this 126 | specification. Every service MUST be implemented by one and only one 127 | Kaetzchen agent. 128 | 129 | For each service, the provider MUST advertise a field for the endpoint at 130 | which the Kaetzchen agent can be reached, as a key value pair where the 131 | key is `endpoint`, and the value is the provider side endpoint identifier. 132 | 133 | :: 134 | 135 | { "kaetzchen": 136 | { "keyserver" : { 137 | "endpoint": "+keyserver", 138 | "version" : 1 } }, 139 | { "discard" : { 140 | "endpoint": "+discard", } }, 141 | { "loop" : { 142 | "endpoint": "+loopback", 143 | "restrictedToUsers": true } }, 144 | } 145 | 146 | 147 | 5. Anonymity Considerations 148 | =========================== 149 | 150 | In the event that the mix keys for the entire return path are 151 | compromised, it is possible for adversaries to unwrap the SURB 152 | and determine the final recipient of the reply. 153 | 154 | Depending on what sort of operations a given agent implements, 155 | there may be additional anonymity impact that requires separate 156 | consideration. 157 | 158 | Clients MUST NOT have predictable retranmission otherwise this 159 | makes active confirmations attacks possible which could be used 160 | to discover the ingress Provider of the client. 161 | 162 | 6. Security Considerations 163 | ========================== 164 | 165 | It is possible to use this mechanism to flood a victim with unwanted 166 | traffic by constructing a request with a SURB destined for the target. 167 | 168 | Depending on the operations implemented by each agent, the added 169 | functionality may end up being a vector for Denial of Service attacks 170 | in the form of CPU or network overload. 171 | 172 | Unless the agent implements additional encryption, message integrity 173 | and privacy is limited to that which is provided by the base Sphinx 174 | packet format and parameterization. 175 | 176 | 7. Acknowledgments 177 | ================== 178 | 179 | The inspiration for this extension comes primarily from a design 180 | by Vincent Breitmoser. 181 | 182 | Appendix A. References 183 | ====================== 184 | 185 | Appendix A.1 Normative References 186 | --------------------------------- 187 | 188 | .. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 189 | Requirement Levels", BCP 14, RFC 2119, 190 | DOI 10.17487/RFC2119, March 1997, 191 | . 192 | 193 | .. [SPHINXSPEC] Angel, Y., Danezis, G., Diaz, C., Piotrowska, A., Stainton, D., 194 | "Sphinx Mix Network Cryptographic Packet Format Specification" 195 | July 2017, . 196 | 197 | .. [KATZMIXE2E] Angel, Y., Danezis, G., Diaz, C., Piotrowska, A., Stainton, D., 198 | "Katzenpost Mix Network End-to-end Protocol Specification", July 2017, 199 | . 200 | 201 | .. [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, 202 | DOI 10.17487/RFC5322, October 2008, 203 | . 204 | 205 | Appendix A.2 Informative References 206 | ----------------------------------- 207 | 208 | .. [SPHINX] Danezis, G., Goldberg, I., "Sphinx: A Compact and 209 | Provably Secure Mix Format", DOI 10.1109/SP.2009.15, 210 | May 2009, . 211 | 212 | .. [KATZMIXPKI] Angel, Y., Piotrowska, A., Stainton, D., 213 | "Katzenpost Mix Network Public Key Infrastructure Specification", December 2017, 214 | . 215 | 216 | Appendix B. Citing This Document 217 | ================================ 218 | 219 | Appendix B.1 Bibtex Entry 220 | ------------------------- 221 | 222 | Note that the following bibtex entry is in the IEEEtran bibtex style 223 | as described in a document called "How to Use the IEEEtran BIBTEX Style". 224 | 225 | :: 226 | 227 | @online{Kaetzchen, 228 | title = {Katzenpost Provider-side Autoresponder Extension}, 229 | author = {Yawning Angel and Kali Kaneko and David Stainton}, 230 | url = {https://github.com/Katzenpost/docs/blob/master/specs/kaetzchen.rst}, 231 | year = {2018} 232 | } 233 | -------------------------------------------------------------------------------- /specs/lioness.rst: -------------------------------------------------------------------------------- 1 | The LIONESS Wide-Block-Cipher Specification 2 | ******************************************* 3 | | 4 | | Yawning Angel 5 | | 6 | .. rubric:: Abstract 7 | 8 | This document defines the LIONESS Wide-Block-Cipher construct, and 9 | provides a concrete parameterization based around the BLAKE2b hash 10 | algorithm and ChaCha20 stream cipher. 11 | 12 | This document does not introduce any new crypto, but is meant to 13 | serve as a stable reference and implementation guide. 14 | 15 | .. contents:: :local: 16 | 17 | 1. Introduction 18 | =============== 19 | 20 | LIONESS is a provably secure wide-block-cipher proposed by Anderson 21 | and Biham in [AB96]_. Internally it is a four round unbalanced 22 | Feistel cipher comprised of a keyed hash function and a stream 23 | cipher. It supports processing large abitrary sized blocks, with 24 | a minimum block size imposed by the choice of primitives, and has 25 | the property such that each bit of the ciphertext is dependent on 26 | every single bit of the plaintext and vice versa. 27 | 28 | 1.1 Conventions Used in This Document 29 | ------------------------------------- 30 | 31 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 32 | "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 33 | document are to be interpreted as described in [RFC2119]_. 34 | 35 | ``x | y`` is the concatenation of x and y. 36 | 37 | ``x ^ y`` is the bitwise XOR of x and y. 38 | 39 | A "``byte``" is an 8-bit octet. 40 | 41 | ``x[a:b]`` is the sub-vector of x where a/b denote the start/end 42 | byte indexes (inclusive-exclusive). a/b may be omitted to signify 43 | the start/end of the vector x respectively. 44 | 45 | 2. The LIONESS Wide-Block-Cipher Construct 46 | ========================================== 47 | 48 | LIONESS is parameteriezed with a keyed hash function (MAC) and 49 | a stream cipher as follows. 50 | 51 | ``H(k, m)`` is a keyed hash function (MAC) with the key ``k``, for a 52 | message ``m`` of arbitrary size. Let ``HashLength`` denote the size 53 | of the output and the key in bytes. 54 | 55 | ``H()`` MUST be collision resistant or preimage resistant, and 56 | implementations SHOULD pick algorithms that provide both 57 | properties. 58 | 59 | ``S(k)`` is a pseudo random function (stream cipher) which given the 60 | ``HashLength`` sized input ``k`` will generate an output of arbitrary 61 | size. 62 | 63 | ``S()`` MUST be key recovery resistant. 64 | 65 | 2.1 LIONESS Encryption 66 | ---------------------- 67 | 68 | .. code:: 69 | 70 | LIONESS-Encrypt(k1, k2, k3, k4, plaintext) -> ciphertext 71 | 72 | Inputs: 73 | 74 | ``k1,k2,k3,k4`` Round keys, each HashLength bytes in size. 75 | 76 | ``plaintext`` The plaintext to encrypt, greater than ``HashLength`` bytes in size. 77 | 78 | Output: 79 | 80 | ``ciphertext`` The resulting ciphertext. 81 | 82 | The output of LIONESS-Encrypt is calculated as follows:: 83 | 84 | L = plaintext[0:HashLength] 85 | R = plaintext[HashLength:] 86 | R = R ^ S(L ^ k1) 87 | L = L ^ H(k2, R) 88 | R = R ^ S(L ^ k3) 89 | L = L ^ H(k4, R) 90 | ciphertext = L | R 91 | 92 | 2.2 LIONESS Decryption 93 | ---------------------- 94 | 95 | .. code:: 96 | 97 | LIONESS-Decrypt(k1, k2, k3, k4, ciphertext) -> plaintext 98 | 99 | Inputs: 100 | 101 | ``k1,k2,k3,k4`` Round keys, each ``HashLength`` bytes in size. 102 | 103 | ``ciphertext`` The ciphertext to decrypt, greater than ``HashLength`` 104 | bytes in size. 105 | 106 | Output: 107 | 108 | ``plaintext`` The resulting plaintext. 109 | 110 | The output of LIONESS-Decrypt is calculated as follows:: 111 | 112 | L = ciphertext[0:HashLength] 113 | R = ciphertext[HashLength:] 114 | L = L ^ H(k4, R) 115 | R = R ^ S(L ^ k3) 116 | L = L ^ H(k2, R) 117 | R = R ^ S(L ^ k1) 118 | plaintext = L | R 119 | 120 | 3. LIONESS-BLAKE2b-ChaCha20 121 | =========================== 122 | 123 | LIONESS-BLAKE2b-ChaCha20 is a concrete parameterization of LIONESS 124 | based around the BLAKE2b [RFC7693]_ hash algorithm and ChaCha20 125 | [RFC7539]_ stream cipher. It provides a security level of at least 126 | 256 bits, and supports a per-call initialization vector. 127 | 128 | Plaintext and Ciphertext MUST NOT exceed 32 + ((1 << 32) * 64) bytes. 129 | 130 | For sections 3.1 and 3.2: 131 | 132 | Let ``BLAKE2b(k, m)`` return the BLAKE2b digest calculated with 133 | key ``k``, and message ``m``, truncated to 32 bytes. 134 | 135 | Let ``ChaCha20(k, n, m)`` return the ChaCha20 encrypted ciphertext 136 | with key ``k``, nonce ``n``, and message ``m``, with the counter initialized 137 | to ``0``. 138 | 139 | 3.1 LIONESS-BLAKE2b-ChaCha20 Encryption 140 | --------------------------------------- 141 | 142 | .. code:: 143 | 144 | LIONESS-BLAKE2b-ChaCha20-Encrypt(key, iv, plaintext) -> ciphertext 145 | 146 | Inputs: 147 | 148 | ``key`` The key, 128 bytes in size. 149 | 150 | ``iv`` The initialization vector, 48 bytes in size. 151 | 152 | ``plaintext`` The plaintext to encrypt, greater than 32 bytes in size. 153 | 154 | Output: 155 | 156 | ``ciphertext`` The resulting ciphertext. 157 | 158 | The output of LIONESS-BLAKE2b-ChaCha20-Encrypt is calculated as 159 | follows:: 160 | 161 | k1 = key[0:32] 162 | k2 = key[32:64] 163 | k3 = key[64:96] 164 | k4 = key[96:128] 165 | iv1 = iv[0:12] 166 | iv2 = iv[12:24] 167 | iv3 = iv[24:36] 168 | iv4 = iv[36:48] 169 | 170 | L = ciphertext[0:32] 171 | R = ciphertext[32:] 172 | R = ChaCha20(L ^ k1, iv1, R) 173 | L = L ^ BLAKE2b(k2 | iv2, R) 174 | R = ChaCha20(L ^ k3, iv3, R) 175 | L = L ^ BLAKE2b(k4 | iv4, R) 176 | ciphertext = L | R 177 | 178 | 3.2 LIONESS-BLAKE2b-ChaCha20 Decryption 179 | --------------------------------------- 180 | 181 | .. code:: 182 | 183 | LIONESS-BLAKE2b-ChaCha20-Decrypt(key, iv, ciphertext) -> plaintext 184 | 185 | Inputs: 186 | 187 | ``key`` The key, 128 bytes in size. 188 | 189 | ``iv`` The initialization vector, 48 bytes in size. 190 | 191 | ``ciphertext`` The ciphertext to decrypt, greater than 32 bytes in size. 192 | 193 | Output: 194 | 195 | ``plaintext`` The resulting plaintext. 196 | 197 | The output of LIONESS-BLAKE2b-ChaCha20-Decrypt is calculated as 198 | follows:: 199 | 200 | k1 = key[0:32] 201 | k2 = key[32:64] 202 | k3 = key[64:96] 203 | k4 = key[96:128] 204 | iv1 = iv[0:12] 205 | iv2 = iv[12:24] 206 | iv3 = iv[24:36] 207 | iv4 = iv[36:48] 208 | 209 | L = ciphertext[0:32] 210 | R = ciphertext[32:] 211 | L = L ^ BLAKE2b(k4 | iv4, R) 212 | R = ChaCha20(L ^ k3, iv3, R) 213 | L = L ^ BLAKE2b(k2 | iv2, R) 214 | R = ChaCha20(L ^ k1, iv1, R) 215 | plaintext = L | R 216 | 217 | 4. Implementation Considerations 218 | ================================ 219 | 220 | When choosing the underlying stream cipher or MAC, implementors 221 | may wish to consider the initialization overhead such as 222 | key scheduling, as the performance impact can be non-negligible 223 | depending on algorithm choice. 224 | 225 | 5. Security Considerations 226 | ========================== 227 | 228 | When parameterizing the LIONESS construct care MUST be taken 229 | to pick cryptographic primitives that meet the requirements 230 | specified in Section 2.1. Depending on the primitive chosen 231 | for ``S()``, there may be a maximum block size imposed by the 232 | maximum amount of data that ``S()`` may encrypt with a given key. 233 | 234 | Care MUST be taken to avoid leaking sensitive information via 235 | side-channels, however this is primarily influenced by the 236 | algorithms and implementations selected for ``H()`` and ``S()`` than the 237 | LIONESS construct itself. 238 | 239 | No claims are made regarding the security of LIONESS when the 240 | same key material is used to encrypt multiple blocks, beyond 241 | those made in [MPRA11]_. Conservative users may wish to avoid this 242 | behavior, use LIONESS as the building block for standard block 243 | cipher constructs that take initialization vectors, or incorporate 244 | initialization vectors in the ``H()`` and ``S()`` calls. 245 | 246 | Appendix A. References 247 | ====================== 248 | 249 | Appendix A.1 Normative References 250 | --------------------------------- 251 | 252 | .. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 253 | Requirement Levels", BCP 14, RFC 2119, 254 | DOI 10.17487/RFC2119, March 1997, 255 | . 256 | 257 | .. [RFC7539] Nir, Y. and A. Langley, "ChaCha20 and Poly1305 for IETF 258 | Protocols", RFC 7539, DOI 10.17487/RFC7539, May 2015, 259 | . 260 | 261 | .. [RFC7693] Saarinen, M-J., Ed., and J-P. Aumasson, "The BLAKE2 262 | Cryptographic Hash and Message Authentication Code 263 | (MAC)", RFC 7693, DOI 10.17487/RFC7693, November 2015, 264 | . 265 | 266 | Appendix A.2 Informative References 267 | ----------------------------------- 268 | 269 | .. [AB96] Anderson, R., Biham, E., "Two Practical and Provably 270 | Secure Block Ciphers: BEAR and LION", 1996. 271 | 272 | .. [MPRA11] Maines, L., Piva, M., Rimoldi, A., Sala, M., "On the 273 | provable security of BEAR and LION schemes", 274 | arXiv:1105.0259, May 2011, 275 | . 276 | 277 | Appendix B. LIONESS-ChaCha20-BLAKE2b Test Vector 278 | ================================================ 279 | 280 | Appendix C. Citing This Document 281 | ================================ 282 | 283 | Appendix C.1 Bibtex Entry 284 | ------------------------- 285 | 286 | Note that the following bibtex entry is in the IEEEtran bibtex style 287 | as described in a document called "How to Use the IEEEtran BIBTEX Style". 288 | 289 | :: 290 | 291 | @online{LionessSpec, 292 | title = {The LIONESS Wide-Block-Cipher Specification}, 293 | author = {Yawning Angel}, 294 | url = {https://github.com/Katzenpost/docs/blob/master/specs/lioness.rst}, 295 | year = {2017} 296 | } 297 | -------------------------------------------------------------------------------- /specs/mailproxy_user_interface.rst: -------------------------------------------------------------------------------- 1 | Katzenpost Decryption Mix Network User Interface Design 2 | ******************************************************* 3 | 4 | | Yawning Angel 5 | | Claudia Diaz 6 | | Kali Kaneko 7 | | David Stainton 8 | 9 | Version 0 10 | 11 | .. rubric:: Abstract 12 | 13 | This document describes the user interface design of the Katzenpost 14 | mix network. 15 | 16 | .. contents:: :local: 17 | 18 | 1. Introduction 19 | =============== 20 | 21 | This user interface is meant to mimic the e-mail experience in 22 | several ways, by allowing existing e-mail programs to interact with 23 | a mixnet SMTP submission proxy and a POP3 receive proxy. We will 24 | also suggest specific e-mail client modifications that will present 25 | some special mixnet specific indicators to the user. 26 | 27 | 1.1 Terminology 28 | ---------------- 29 | 30 | * ``MTA`` - mail transfer agent, refers to a mail server 31 | 32 | * ``SMTP`` - simple mail transfer protocol, this is the protocol 33 | used by e-mail clients for sending mail [RFC5321]_ [RFC6409]_ 34 | 35 | * ``POP3`` - post office protocol version 3, a commonly used protocol 36 | for retrieving mail from a remote server [RFC1939]_ [RFC2449]_ 37 | 38 | 2. System Overview 39 | ================== 40 | 41 | Our messaging system user interface design has the goal of 42 | satisfying one of the two primary obstacles for user adoption, 43 | namely interoperability. [ADOPT17]_ What we mean here by 44 | interoperability is that any e-mail client is able to function 45 | correctly with our SMTP submission proxy and POP3 retrieval proxy 46 | components which run locally with the e-mail client. 47 | 48 | We shall also maintain strict adherence to various secure user 49 | interface design principles such as the "Principle of the Path of 50 | Least Resistance" which in this context could mean that no extra 51 | action on the part of the user is required to encrypt a message 52 | because encryption is used by default all the time. [YEE02]_ 53 | 54 | The mix network client is essentially split up into two components 55 | the SMTP proxy and the POP3 proxy. The POP3 proxy only needs to 56 | communicate with the mixnet PKI to retrieve the user's mail queue 57 | connection information whereas the SMTP proxy makes more use of the 58 | PKI in order to perform mix network path selection, mix key 59 | retrieval for Sphinx packet composition. 60 | 61 | 3. Behavior of the SMTP submission proxy 62 | ======================================== 63 | 64 | Submission proxy three point plan: 65 | 66 | * The SMTP proxy will refuse to queue a message if the recipient's 67 | key is not available and issue the SMTP error message: 68 | 69 | ``455 Server unable to accommodate parameters`` 70 | 71 | * The SMTP proxy will refuse to queue the message if the mixnet is 72 | not available with the following error message: 73 | 74 | ``450 Requested mail action not taken: mailbox unavailable.`` 75 | 76 | * Mail delivery failures will be indicated by the reception of 77 | bounce messages. 78 | 79 | * The SMTP proxy should announce the availability of the mixnet, so 80 | that the end-user can receive early feedback about the possibility or 81 | routing a message via the mixnet, while composing the message. This 82 | availability can be announced in the capabilities header. 83 | 84 | 85 | 4. Behavior of the POP3 retrieval proxy 86 | ======================================= 87 | 88 | ... TBD ... 89 | 90 | 5. Behavior of the e-mail client / K9mail 91 | ========================================= 92 | 93 | This section specifies features and user interfaces changes to the 94 | K9mail e-mail client software. In principle these changes could be 95 | done to any existing e-mail client however it should also be 96 | possible to use an e-mail client without these user interface 97 | enhancements. 98 | 99 | The e-mail client should feature the ability for the user to send 100 | messages as multiple identities and their corresponding 101 | key-pairs. The sender identity is signaled to a recipient via a 102 | header that is added by the recipient's mixnet client like thus: 103 | 104 | ``X-Katzenpost-Sender: `` 105 | 106 | Clients MUST NOT generate outbound mail with the 107 | `X-Katzenpost-Sender` header set, and MUST examine 108 | inbound mail for the presence of such a header, and treat all mails 109 | received that have the header as potentially mallicious. 110 | 111 | 6. Recommendations for UX in the client implementations 112 | ======================================================= 113 | 114 | When integrating with an existing email application, and being an 115 | experimental feature, the user will be able to opt-in to mixing 116 | outgoing email. 117 | 118 | There should be an easy visual indication that one recipient is 119 | able to receive email through the mixnet, based on the domain part 120 | of the user identifier belonging to the mixable set announced by 121 | each provider participating of the mixnet infrastructure, which the 122 | katzenpost client can retrieve from the PKI. 123 | 124 | In the composing view, the "mixing" icon should be enabled by 125 | default if the following conditions are met: 126 | 127 | - the user opted-in for the katzenpost capability. the recipient's 128 | - domain belongs to the mixable set. the mixnet status is healthy. 129 | 130 | Even when the switch to route an outgoing email is enabled 131 | automatically, the user should be able to disable mixnet routing on 132 | a per-message basis. 133 | 134 | In order to assist the user making the best choices in terms of 135 | tradeoffs when sending an email, the MUA should be able to display 136 | some light statistics about the status of the service in a 137 | non-obstrusive way (ie, mouseover). These statistics would include: 138 | 139 | - the amount of delay to expect when delivering through the mixnet. 140 | - the percentage of successful deliveries. 141 | 142 | In the mailbox and message views, the "mixing" icon should be 143 | enabled and green if the mixnet-specific header is present in the 144 | message. Optionally, this header can be signed by the key of the 145 | mixnet delivery agent, either by signing the header individually or 146 | by including that header in a memoryhole-signed payload. If a 147 | signature is present, the MUA should verify it and display a 148 | verification mark accordingly. 149 | 150 | In the case of the non-mixed email, the "mixing" icon should be 151 | enabled and grayed out if the user opted-in for the mixing 152 | capabilities, or just disabled otherwise. 153 | 154 | In the cases in which the MUA is already displaying the status of 155 | e2e encryption (like in PGP-enabled MUAs), when deciding the status 156 | of such visual indication the semantics of e2e encryption in 157 | katzenpost should also be considered and merged with the other 158 | status, instead of indicating katzenpost e2e encryption and pgp 159 | encryption as two separate parts. 160 | 161 | Appendix A. References 162 | ====================== 163 | 164 | Appendix A.1 Normative References 165 | --------------------------------- 166 | 167 | Appendix A.1 Informative References 168 | ----------------------------------- 169 | 170 | .. [RFC5321] J., Klensin, Network Working Group, Standards Track, 171 | October 2008, "Simple Mail Transfer Protocol", 172 | . 173 | 174 | .. [RFC6409] J., Klensin, R., Gellens, Internet Engineering Task Force, Standards Track, 175 | November 2011, "Message Submission for Mail", 176 | . 177 | 178 | .. [RFC1939] J., Myers, M., Rose, 179 | May 1996, "Post Office Protocol - Version 3", 180 | . 181 | 182 | .. [RFC2449] R., Gellens, C., Newman, L., Lundblade, Network Working Group, Standards Track, 183 | November 1998, "POP3 Extension Mechanism", 184 | . 185 | 186 | .. [ADOPT17] Bonneau, J., Sasse, M., Abu-Salma, R., Smith, M., Naiakshina, A., Danilova, A. 187 | "Obstacles to the Adoption of Secure Communication Tools", 188 | Proceedings of the 38th IEEE Symposium on Security and Privacy, 189 | Oakland, San Jose, CA, USA, 2017 190 | . 191 | 192 | .. [YEE02] Yee, Ka-Ping., "User Interaction Design for Secure Systems", 193 | Computer Science Department, University of California, Berkeley, 194 | May 2002, . 195 | -------------------------------------------------------------------------------- /specs/sphinx_replay_detection.rst: -------------------------------------------------------------------------------- 1 | Sphinx Packet Replay Detection Specification 2 | ******************************************** 3 | 4 | | David Stainton 5 | | 6 | | Version 0 7 | | 8 | .. rubric:: Abstract 9 | 10 | This document defines the replay detection for any protocol that uses 11 | Sphinx cryptographic packet format. This document is meant to serve as an 12 | implementation guide and document the existing replay protect for deployed 13 | mix networks. 14 | 15 | .. contents:: :local: 16 | 17 | 1. Introduction 18 | =============== 19 | 20 | The Sphinx cryptographic packet format is a compact and provably 21 | secure design introduced by George Danezis and Ian Goldberg [SPHINX09]_. 22 | Although it supports replay detection, the exact mechanism of replay 23 | detection is neither described in [SPHINX09]_ nor is it described 24 | in our [SPHINXSPEC]_. Therefore we shall describe in detail how to 25 | efficiently detect Sphinx packet replay attacks. 26 | 27 | 1.1 Terminology 28 | --------------- 29 | 30 | * ``Epoch`` - A fixed time interval defined in section 31 | "4.2 Sphinx Mix and Provider Key Rotation" of [KATZMIXNET]_. 32 | 33 | * ``Packet`` - A fixed-length sequence of bytes transmitted through 34 | the network, containing the encrypted message and metadata for 35 | routing. 36 | 37 | * ``Header`` - The packet header consisting of several components, which 38 | convey the information necessary to verify packet integrity and 39 | correctly process the packet. 40 | 41 | * ``Payload`` - The fixed-length portion of a packet containing an 42 | encrypted message or part of a message, to be delivered. 43 | 44 | * ``Group`` - A finite set of elements and a binary operation that 45 | satisfy the properties of closure, associativity, invertability, 46 | and the presence of an identity element. 47 | 48 | * ``Group element`` - An individual element of the group. 49 | 50 | * ``Group generator`` - A group element capable of generating any other 51 | element of the group, via repeated applications of the generator 52 | and the group operation. 53 | 54 | * ``SEDA`` - Staged Event Driven Architecture. [SEDA]_ 55 | 1. A highly parallelizable computation model. 56 | 2. A computational pipeline composed of multiple stages connected by 57 | queues utilizing active queue management algorithms that can 58 | evict items from the queue based on dwell time or other criteria 59 | where each stage is a thread pool. 60 | 3. The only correct way to efficiently implement a software based 61 | router on general purpose computing hardware. 62 | 63 | 1.2 Conventions Used in This Document 64 | ------------------------------------- 65 | 66 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 67 | "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 68 | document are to be interpreted as described in [RFC2119]_. 69 | 70 | 2. Sphinx Cryptographic Primitives 71 | ================================== 72 | 73 | This specification borrows the following cryptographic primitives 74 | constants from our [SPHINXSPEC]_: 75 | 76 | * ``H(M)`` - A cryptographic hash function which takes an byte array M 77 | to produce a digest consisting of a ``HASH_LENGTH`` byte 78 | array. ``H(M)`` MUST be pre-image and collision resistant. 79 | 80 | * ``EXP(X, Y)`` - An exponentiation function which takes the 81 | ``GROUP_ELEMENT_LENGTH`` byte array group elements ``X`` and ``Y``, 82 | and returns ``X ^^ Y`` as a ``GROUP_ELEMENT_LENGTH`` byte array. 83 | 84 | Let ``G`` denote the generator of the group, and ``EXP_KEYGEN()`` 85 | return a ``GROUP_ELEMENT_LENGTH`` byte array group element 86 | usable as private key. 87 | 88 | The group defined by ``G`` and ``EXP(X, Y)`` MUST satisfy the Decision 89 | Diffie-Hellman problem. 90 | 91 | 2.1 Sphinx Parameter Constants 92 | ------------------------------ 93 | 94 | * ``HASH_LENGTH`` - 32 bytes. Katzenpost currently uses SHA-512/256. [RFC6234]_ 95 | * ``GROUP_ELEMENT_LENGTH`` - 32 bytes. Katzenpost currently uses X25519. [RFC7748]_ 96 | 97 | 3. System Overview 98 | ================== 99 | 100 | Mixes as currently deployed, have two modes of operation: 101 | 102 | 1. Sphinx routing keys and replay caches are persisted to disk 103 | 2. Sphinx routing keys and replay caches are persisted to memory 104 | 105 | These two modes of operation fundamentally represent a tradeoff 106 | between mix server availability and notional compulsion attack 107 | resistance. Ultimately it will be the mix operator's decision to make 108 | since they affect the security and availability of their mix 109 | servers. In particular since mix networks are vulnerable to the 110 | various types of compulsion attacks (see [SPHINXSPEC]_ section 9.4 111 | Compulsion Threat Considerations) and therefore there is some 112 | advantage to NOT persisting the Sphinx routing keys to disk. The mix 113 | operator can simply poweroff the mix server before seizure rather than 114 | physically destroying the disk in order to prevent capture of the 115 | Sphinx routing keys. An argument can be made for the use of full disk 116 | encryption, however this may not be practical for servers hosted in 117 | remote locations. 118 | 119 | On the other hand, persisting Sphinx routing keys and replay caches to 120 | disk is useful because it allows mix operators to shutdown their mix 121 | server for maintenance purposes without loosing these Sphinx routing 122 | keys and replay caches. This means that as soon as the maintenance 123 | operation is completed the mix server is able to rejoin the 124 | network. Our current PKI system [KATZMIXPKI]_ does NOT provide a 125 | mechanism to notify Directory Authorities of such an outage or 126 | maintenance period. Therefore if there is loss of Sphinx routing keys 127 | this results in a mix outage until the next epoch. 128 | 129 | The two modes of operation both completely prevent replay attacks 130 | after a system restart. In the case of the disk persistence, replay 131 | attacks are prevented because all packets traversing the mix have 132 | their replay tags persisted to disk cache. This cache is therefore 133 | once again used to prevent replays after a system restart. In the case 134 | of memory persistence replays are prevented upon restart because the 135 | Sphinx routing keys are destroyed and therefore the mix will not 136 | participant in the network until at least the next epoch 137 | rotation. However availability of the mix may require two epoch 138 | rotations because in accordance with [KATZMIXPKI]_ mixes publish 139 | future epoch keys so that Sphinx packets flowing through the network 140 | can seamlessly straddle the epoch boundaries. 141 | 142 | 4. Sphinx Packet Replay Cache 143 | ============================= 144 | 145 | 4.1 Sphinx Replay Tag Composition 146 | --------------------------------- 147 | 148 | The following excerpt from our [SPHINXSPEC]_ shows how the replay tag 149 | is calculated. 150 | 151 | .. code:: 152 | 153 | hdr = sphinx_packet.header 154 | shared_secret = EXP( hdr.group_element, private_routing_key ) 155 | replay_tag = H( shared_secret ) 156 | 157 | However this tag is not utilized in replay detection until the rest of 158 | the Sphinx packet is fully processed and it's header MAC verified as 159 | described in [SPHINXSPEC]_. 160 | 161 | 4.2 Sphinx Replay Tag Caching 162 | ----------------------------- 163 | 164 | It would be sufficient to use a key value store or hashmap to detect 165 | the presence of a duplicate replay tag however we additionaly employ a 166 | bloom filter to increase performance. Sphinx keys must periodically be 167 | rotated and destroyed to mitigate compulsion attacks and therefore our 168 | replay caches must likewise be rotated. This kind of key erasure 169 | scheme limits the window of time that an adversary can perform a 170 | compulsion attack. See our PKI specification [KATZMIXPKI]_ for more 171 | details regarding epoch key rotation and the grace period before and 172 | after the epoch boundary. 173 | 174 | We tune our bloom filter for line-speed; that is to say the bloom 175 | filter for a given replay cache is tuned for the maximum number of 176 | Sphinx packets that can be sent on the wire during the epoch duration 177 | of the Sphinx routing key. This of course has to take into account 178 | the size of the Sphinx packets as well as the maximum line speed of 179 | the network interface. This is a conservative tuning heuristic given 180 | that there must be more than this maximum number of Sphinx packets in 181 | order for there to be duplicate packets. 182 | 183 | Our bloomfilter with hashmap replay detection cache looks like this: 184 | 185 | .. image:: diagrams/replay1.png 186 | :alt: replay cache 187 | :align: left 188 | 189 | Note that this diagram does NOT express the full complexity of the 190 | replay caching system. In particular it does not describe how entries 191 | are entered into the bloom filter and hashmap. Upon either bloom 192 | filter mismatch or hashmap mismatch both data structures must be 193 | locked and the replay tag inserted into each. 194 | 195 | For the disk persistence mode of operation the hashmap can simply be 196 | replaced with an efficient key value store. Persistent stores may use 197 | a write back cache and other techniques for efficiency. 198 | 199 | 4.3 Epoch Boundaries 200 | -------------------- 201 | 202 | Since mixes publish future epoch keys (see [KATZMIXPKI]_) so that 203 | Sphinx packets flowing through the network can seamlessly straddle the 204 | epoch boundaries, our replay detection forms a special kind of double 205 | bloom filter system. During the epoch grace period mixes perform trial 206 | decryption of Sphinx packets. The replay cache used will be the one 207 | that is associated with the Sphinx routing key which was successfully 208 | used to decrypt (unwrap transform) the Sphinx packet. This is not a 209 | double bloom filter in the normal sense of this term since each bloom 210 | filter used is distinct and associated with it's own cache, 211 | furthermore, replay tags are only ever inserted into one cache and one 212 | bloom filter. 213 | 214 | 4.4 Cost Of Checking Replays 215 | ---------------------------- 216 | 217 | The cost of checking a replay tag from a single replay cache is 218 | the sum of the following operations: 219 | 220 | 1. Sphinx packet unwrap operation 221 | 2. A bloom filter lookup 222 | 3. A hashmap or cache lookup 223 | 224 | Therefore these operations are roughly O(1) in complexity. However 225 | Sphinx packets processed near epoch boundaries will not be constant 226 | time due to trial decryption with two Sphinx routing keys as mentioned 227 | above in section "3.3 Epoch Boundaries". 228 | 229 | 5. Concurrent Processing of Sphinx Packet Replay Tags 230 | ===================================================== 231 | 232 | The best way to implement a software based router is with a 233 | [SEDA]_ computational pipeline. We therefore need a mechanism 234 | to allow multiple threads to reference our rotating Sphinx keys 235 | and associated replay caches. Here we shall describe a shadow 236 | memory system which the mix server uses such that the individual 237 | worker threads shall always have a reference to the current set of 238 | candidate mix keys and associates replay caches. 239 | 240 | 5.1 PKI Updates 241 | --------------- 242 | 243 | The mix server periodically updates it's knowledge of the network by 244 | downloading a new consensus document as described in [KATZMIXPKI]_. 245 | The individual threads in the "cryptoworker" thread pool which process 246 | Sphinx packets make use of a ``MixKey`` data structure which consists of: 247 | 248 | 1. Sphinx routing key material (public and private X25519 keys) 249 | 2. Replay Cache 250 | 3. Reference Counter 251 | 252 | Each of these "cryptoworker" thread pool has it's own hashmap 253 | associating epochs to a reference to the ``MixKey``. The mix server 254 | PKI threat maintains a single hashmap which associates the epochs with 255 | the corresponding ``MixKey``. We shall refer to this hashmap as 256 | ``MixKeys``. After a new ``MixKey`` is added to ``MixKeys``, a 257 | "reshadow" operation is performed for each "cryptoworker" thread. The 258 | "reshadow" operation performs two tasks: 259 | 260 | 1. Removes entries from each "cryptoworker" thread's hashmap that are 261 | no longer present in ``MixKeys`` and decrements the ``MixKey`` 262 | reference counter. 263 | 264 | 2. Adds entries present in ``MixKeys`` but are not present in the 265 | thread's hashmap and increments the ``MixKey`` reference counter. 266 | 267 | Once a given ``MixKey`` reference counter is decremented to zero, the 268 | ``MixKey`` and it's associated on disk data is purged. Note that we do 269 | not discuss synchronization primitives, however it should be obvious 270 | that updating the replay cache should likely make use of a mutex or 271 | similar primitive to avoid data races between "cryptoworker" threads. 272 | 273 | Appendix A. References 274 | ====================== 275 | 276 | Appendix A.1 Normative References 277 | --------------------------------- 278 | 279 | .. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 280 | Requirement Levels", BCP 14, RFC 2119, 281 | DOI 10.17487/RFC2119, March 1997, 282 | . 283 | 284 | .. [KATZMIXNET] Angel, Y., Danezis, G., Diaz, C., Piotrowska, A., Stainton, D., 285 | "Katzenpost Mix Network Specification", June 2017, 286 | . 287 | 288 | .. [KATZMIXPKI] Angel, Y., Piotrowska, A., Stainton, D., 289 | "Katzenpost Mix Network Public Key Infrastructure Specification", December 2017, 290 | . 291 | 292 | .. [SPHINXSPEC] Angel, Y., Danezis, G., Diaz, C., Piotrowska, A., Stainton, D., 293 | "Sphinx Mix Network Cryptographic Packet Format Specification" 294 | July 2017, . 295 | 296 | .. [SEDA] Welsh, M., Culler, D., Brewer, E., 297 | "SEDA: An Architecture for Well-Conditioned, Scalable Internet Services", 298 | ACM Symposium on Operating Systems Principles, 2001, 299 | . 300 | 301 | Appendix A.2 Informative References 302 | ----------------------------------- 303 | 304 | .. [SPHINX09] Danezis, G., Goldberg, I., "Sphinx: A Compact and 305 | Provably Secure Mix Format", DOI 10.1109/SP.2009.15, 306 | May 2009, . 307 | 308 | .. [COMPULS05] Danezis, G., Clulow, J., "Compulsion Resistant Anonymous Communications", 309 | Proceedings of Information Hiding Workshop, June 2005, 310 | . 311 | 312 | .. [RFC7748] Langley, A., Hamburg, M., and S. Turner, "Elliptic Curves 313 | for Security", RFC 7748, January 2016. 314 | 315 | .. [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms 316 | (SHA and SHA-based HMAC and HKDF)", RFC 6234, 317 | DOI 10.17487/RFC6234, May 2011, 318 | . 319 | 320 | Appendix B. Citing This Document 321 | ================================ 322 | 323 | Appendix B.1 Bibtex Entry 324 | ------------------------- 325 | 326 | Note that the following bibtex entry is in the IEEEtran bibtex style 327 | as described in a document called "How to Use the IEEEtran BIBTEX Style". 328 | 329 | :: 330 | 331 | @online{SphinxReplay, 332 | title = {Sphinx Packet Replay Detection Specification}, 333 | author = {David Stainton}, 334 | url = {https://github.com/katzenpost/docs/blob/master/specs/sphinx_replay_detection.rst}, 335 | year = {2019} 336 | } 337 | -------------------------------------------------------------------------------- /specs/wire-protocol.rst: -------------------------------------------------------------------------------- 1 | Katzenpost Mix Network Wire Protocol Specification 2 | ************************************************* 3 | | 4 | | Yawning Angel 5 | | 6 | | Version 0 7 | | 8 | .. rubric:: Abstract 9 | 10 | This document defines the Katzenpost Mix Network Wire Protocol for 11 | use in all network communications to, from, and within the Katzenpost 12 | Mix Network. 13 | 14 | .. contents:: :local: 15 | 16 | 1. Introduction 17 | =============== 18 | 19 | The Katzenpost Mix Network Wire Protocol (KMNWP) is the custom wire 20 | protocol for all network communications to, from, and within the 21 | Katzenpost Mix Network. This protocol provides mutual authentication, 22 | and an additional layer of cryptographic security and forward 23 | secrecy. 24 | 25 | 1.1 Conventions Used in This Document 26 | ------------------------------------- 27 | 28 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 29 | "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 30 | document are to be interpreted as described in [RFC2119]_. 31 | 32 | The "C" style Presentation Language as described in [RFC5246]_ 33 | Section 4 is used to represent data structures, except for 34 | cryptographic attributes, which are specified as opaque byte 35 | vectors. 36 | 37 | ``x | y`` denotes the concatenation of x and y. 38 | 39 | 1.2 NewHope-Simple Key Encapsulation Mechanism 40 | ---------------------------------------------- 41 | 42 | This protocol uses the NewHope-Simple Key Encapsulation Mechanism, 43 | as specified in the original NewHope [NEWHOPE]_ and NewHope-Simple 44 | [NHSIMPLE]_ papers. All references to the NewHope-Simple shared 45 | secret in this document are to be interpreted as the final ``mu`` 46 | output for each party. 47 | 48 | Note that while the NewHope and NewHope-Simple papers describe Alice 49 | as the "server" and Bob as the "client", for the purposes of this 50 | protocol, Alice is to be interpreted as the initiator, and Bob as 51 | the responder. 52 | 53 | 2. Core Protocol 54 | ================ 55 | 56 | The protocol is based on NewHope-Simple and Trevor Perrin's Noise 57 | Protocol Framework [NOISE]_ with the Hybrid Forward Secrecy extension 58 | [NOISEHFS]_ and can be viewed as a prologue, Noise handshake, followed 59 | by a stream of Noise Transport messages in a minimal framing layer, 60 | over a TCP/IP connection. 61 | 62 | ``Noise_XXhfs_25519+NewHopeSimple_ChaChaPoly_Blake2b`` is used as the 63 | Noise protocol name, and parameterization for the purposes of this 64 | specification. As a non-standard modification to the Noise protocol, 65 | the 65535 byte message length limit is increased to 1048576 bytes. 66 | 67 | As NewHope-Simple is not formally defined for the purpose of this 68 | version of the ``hfs`` handshake variant, let the following be the 69 | parameters: 70 | 71 | ``FLEN1 = 1824``, the size of the ``m_a`` output of the NewHope-Simple 72 | encodeA operation. 73 | 74 | ``FLEN2 = 2176``, the size of the ``m_b`` output of the NewHope-Simple 75 | encodeB operation. 76 | 77 | ``FFLEN = 32`` 78 | 79 | It is assumed that all parties using the KMNWP protocol have a fixed 80 | long lived X25519 keypair [RFC7748]_, the public component of which 81 | is known to the other party in advance. How such keys are distributed 82 | is beyond the scope of this document. 83 | 84 | 2.1 Handshake Phase 85 | ------------------- 86 | 87 | All sessions start in the Handshake Phase, in which an anonymous 88 | authenticated handshake is conducted. 89 | 90 | The handshake is a unmodified Noise handshake, with a fixed 91 | prologue prefacing the initiator's first Noise handshake message. 92 | This prologue is also used as the ``prologue`` input to the Noise 93 | HandshakeState ``Initialize()`` operation for both the initiator and 94 | responder. 95 | 96 | The prologue is defined to be the following structure: 97 | 98 | .. code:: 99 | 100 | struct { 101 | uint8_t protocol_version; /* 0x00 */ 102 | } Prologue; 103 | 104 | As all Noise handshake messages are fixed sizes, no additional 105 | framing is required for the handshake. 106 | 107 | Implementations MUST preserve the Noise handshake hash (`h`) for the 108 | purpose of implementing authentication (Section 2.3). 109 | 110 | Implementations MUST reject handshake attempts by terminating the 111 | session immediately upon any Noise protocol handshake failure 112 | and when, as a responder, they receive a Prologue containing 113 | an unknown protocol_version value. 114 | 115 | Implementations SHOULD impose reasonable timeouts for the handshake 116 | process, and SHOULD terminate sessions that are taking too long to 117 | handshake. 118 | 119 | 2.1.1 Handshake Authentication 120 | ------------------------------ 121 | 122 | Mutual authentication is done via exchanging fixed sized payloads 123 | as part of the ``Noise_XX`` handshake consisting of the following 124 | structure:: 125 | 126 | struct { 127 | uint8_t ad_len; 128 | opaque additional_data[ad_len]; 129 | opaque padding[255 - ad_len]; 130 | uint32_t unix_time; 131 | } AuthenticateMessage; 132 | 133 | Where: 134 | 135 | * ``ad_len`` - The length of the optional additional data. 136 | 137 | * ``additional_data`` - Optional additional data, such as a username, 138 | if any. 139 | 140 | * ``unix_time`` - 0 for the initiator, the approximate number of 141 | seconds since 1970-01-01 00:00:00 UTC for the 142 | responder. 143 | 144 | The initiator MUST send the ``AuthenticateMessage`` after it has 145 | received the peer's response (so after ``-> s, se`` in Noise parlance). 146 | 147 | The contents of the optional ``additional_data`` field is deliberately 148 | left up to the implementation, however it is RECOMMENDED that 149 | implementations pad the field to be a consistent length regardless 150 | of contents to avoid leaking information about the authenticating 151 | identity. 152 | 153 | To authenticate the remote peer given an AuthenticateMessage, 154 | the receiving peer must validate the ``s`` component of the Noise 155 | handshake (the remote peer's long term public key) with the known 156 | value, along with any of the information in the a``dditional_data`` 157 | field such as the user name, if any. 158 | 159 | Iff the validation procedure succeeds, the peer is considered 160 | authenticated. If the validation procedure fails for any reason, 161 | the session MUST be terminated immediately. 162 | 163 | Responders MAY add a slight amount (+- 10 seconds) of random 164 | noise to the unix_time value to avoid leaking precise load 165 | information via packet queueing delay. 166 | 167 | 2.2 Data Transfer Phase 168 | ----------------------- 169 | 170 | Upon successfully concluding the handshake the session enters the 171 | Data Transfer Phase, where the initiator and responder can exchange 172 | KMNWP messages. 173 | 174 | A KMNWP message is defined to be the following structure:: 175 | 176 | enum { 177 | no_op(0), 178 | disconnect(1), 179 | send_packet(2), 180 | 181 | (255), 182 | } Command; 183 | 184 | struct { 185 | Command command; 186 | uint8_t reserved; /* MUST be '0x00' */ 187 | uint32_t msg_length; /* 0 <= msg_length <= 1048554) */ 188 | opaque message[msg_length]; 189 | opaque padding[]; /* length is implicit */ 190 | } Message; 191 | 192 | Notes: 193 | 194 | * The padding field, if any MUST be padded with ``'0x00'`` bytes. 195 | 196 | All outgoing Message(s) are encrypted and authenticated into a pair 197 | of Noise Transport messages, each containing one of the following 198 | structures:: 199 | 200 | struct { 201 | uint32_t message_length; 202 | } CiphertextHeader; 203 | 204 | struct { 205 | uint32_t message[ciphertext_length-16]; 206 | } Ciphertext; 207 | 208 | Notes: 209 | 210 | * The ``ciphertext_length`` field includes the Noise protocol 211 | overhead of 16 bytes, for the Noise Transport message 212 | containing the Ciphertext. 213 | 214 | All outgoing Message(s) are preceded by a Noise Transport Message 215 | containing a ``CiphertextHeader``, indicating the size of the Noise 216 | Transport Message transporting the Message Ciphertext. After 217 | generating both Noise Transport Messages, the sender MUST call the 218 | Noise CipherState ``Rekey()`` operation. 219 | 220 | To receive incoming Ciphertext messages, first the Noise Transport 221 | Message containing the CiphertextHeader is consumed off the network, 222 | authenticated and decrypted, giving the receiver the length of the 223 | Noise Transport Message containing the actual message itself. The 224 | second Noise Transport Message is consumed off the network, 225 | authenticated and decrypted, with the resulting message being 226 | returned to the caller for processing. After receiving both Noise 227 | Transport Messages, the receiver MUST call the Noise CipherState 228 | ``Rekey()`` operation. 229 | 230 | Implementations MUST immediately terminate the session any of the 231 | ``DecryptWithAd()`` operations fails. 232 | 233 | Implementations MUST immediately terminate the session if 234 | an unknown command is received in a Message, or if the Message 235 | is otherwise malformed in any way. 236 | 237 | Implementations MAY impose a reasonable idle timeout, and 238 | terminate the session if it expires. 239 | 240 | 3. Predefined Commands 241 | ====================== 242 | 243 | 3.1 The no_op Command 244 | --------------------- 245 | 246 | The ``no_op`` command is a command that explicitly is a No Operation, 247 | to be used to implement functionality such as keep-alives and or 248 | application layer padding. 249 | 250 | Implementations MUST NOT send any message payload accompanying 251 | this command, and all received command data MUST be discarded 252 | without interpretation. 253 | 254 | 3.2 The disconnect Command 255 | -------------------------- 256 | 257 | The ``disconnect`` command is a command that is used to signal explicit 258 | session termination. Upon receiving a disconnect command, 259 | implementations MUST interpret the command as a signal from the peer 260 | that no additional commands will be sent, and destroy the 261 | cryptographic material in the receive CipherState. 262 | 263 | While most implementations will likely wish to terminate the session 264 | upon receiving this command, any additional behavior is explicitly 265 | left up to the implementation and application. 266 | 267 | Implementations MUST NOT send any message payload accompanying 268 | this command, and MUST not send any further traffic after sending 269 | a disconnect command. 270 | 271 | 3.3 The send_packet Command 272 | --------------------------- 273 | 274 | The ``send_packet`` command is the command that is used by the initiator 275 | to transmit a Sphinx Packet over the network. The command's message 276 | is the Sphinx Packet destined for the responder. 277 | 278 | Initiators MUST terminate the session immediately upon reception of 279 | a ``send_packet`` command. 280 | 281 | 4. Anonymity Considerations 282 | =========================== 283 | 284 | Adversaries being able to determine that two parties are 285 | communicating via KMNWP is beyond the threat model of this protocol. 286 | At a minimum, it is trivial to determine that a KMNWP handshake is 287 | being performed, due to the length of each handshake message, and 288 | the fixed positions of the various public keys. 289 | 290 | 5. Security Considerations 291 | ========================== 292 | 293 | It is imperative that implementations use ephemeral keys for every 294 | handshake as the security properties of the NewHope-Simple KEM are 295 | totally lost if keys are ever reused. 296 | 297 | NewHope-Simple was chosen as the KEM algorithm due to it's 298 | conservative parameterization, simplicty of implementation, and 299 | high performance in software. It is hoped that the addition of a 300 | quantum resistant algorithm will provide forward secrecy even in 301 | the event that large scale quantum computers are applied to 302 | historical intercepts. 303 | 304 | 6. Acknowledgments 305 | ================== 306 | 307 | I would like to thank Trevor Perrin for providing feedback during 308 | the design of this protocol, and answering questions regarding 309 | Noise. 310 | 311 | Appendix A. References 312 | ====================== 313 | 314 | Appendix A.1 Normative References 315 | --------------------------------- 316 | 317 | .. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 318 | Requirement Levels", BCP 14, RFC 2119, 319 | DOI 10.17487/RFC2119, March 1997, 320 | . 321 | 322 | .. [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 323 | (TLS) Protocol Version 1.2", RFC 5246, 324 | DOI 10.17487/RFC5246, August 2008, 325 | . 326 | 327 | .. [NEWHOPE] Alkim, E., Ducas, L., Poeppelmann, T., Schwabe, P., 328 | "Post-quantum key exchange - a new hope", 329 | Cryptology ePrint Archive, Report 2015/1092, 2015, 330 | . 331 | 332 | .. [NHSIMPLE] Alkim, E., Ducas, L., Poeppelmann, T., Schwabe, P., 333 | "NewHope without reconciliation", 334 | Cryptology ePrint Archive, Report 2016/1157, 2016, 335 | . 336 | 337 | .. [RFC7748] Langley, A., Hamburg, M., and S. Turner, "Elliptic Curves 338 | for Security", RFC 7748, 339 | DOI 10.17487/RFC7748, January 2016, 340 | . 341 | 342 | .. [NOISE] Perrin, T., "The Noise Protocol Framework", May 2017, 343 | . 344 | 345 | .. [NOISEHFS] Weatherley, R., "Noise Extension: Hybrid Forward Secrecy", 346 | 1draft-5, June 2017, 347 | 348 | 349 | Appendix A.2 Informative References 350 | ----------------------------------- 351 | 352 | Appendix B. Citing This Document 353 | ================================ 354 | 355 | Appendix B.1 Bibtex Entry 356 | ------------------------- 357 | 358 | Note that the following bibtex entry is in the IEEEtran bibtex style 359 | as described in a document called "How to Use the IEEEtran BIBTEX Style". 360 | 361 | :: 362 | 363 | @online{KatzMixWire, 364 | title = {Katzenpost Mix Network Wire Protocol Specification}, 365 | author = {Yawning Angel}, 366 | url = {https://github.com/katzenpost/docs/blob/master/specs/wire-protocol.rst}, 367 | year = {2017} 368 | } 369 | --------------------------------------------------------------------------------