added tech section to docs, moved some of the pages from website and design to this new section.

7 files changed, 682 insertions, 0 deletions

diff --git a/docs/tech/en.html.haml b/docs/tech/en.html.haml
new file mode 100644
index 0000000..9ab0398
--- /dev/null
+++ b/docs/tech/en.html.haml
@@ -0,0 +1,6 @@
+- @title = "Technology"
+- @summary = "Musings, notes, and background information on various technology issues that relate to LEAP."
+
+%p Musings, notes, and background information on various technology issues that relate to LEAP.
+
+= child_summaries
\ No newline at end of file
diff --git a/docs/tech/hard-problems.md b/docs/tech/hard-problems.md
new file mode 100644
index 0000000..e856334
--- /dev/null
+++ b/docs/tech/hard-problems.md
@@ -0,0 +1,117 @@
+@title = 'Hard problems in secure communication'
+@nav_title = 'Hard problems'
+@summary = "How LEAP addresses the difficult problems in secure communication"
+
+## The big seven
+
+If you take a survey of interesting initiatives to create more secure communication, a pattern starts to emerge: it seems that any serious attempt to build a system for secure message communication eventually comes up against the following list of seven hard problems.
+
+1. **Authenticity problem**: Public key validation is very difficult for users to manage, but without it you cannot have confidentiality.
+2. **Meta-data problem**: Existing protocols are vulnerable to meta-data analysis, even though meta-data is often much more sensitive than content.
+3. **Asynchronous problem**: For encrypted communication, you must currently choose between forward secrecy or the ability to communicate asynchronously.
+4. **Group problem**: In practice, people work in groups, but public key cryptography doesn't.
+5. **Resource problem**: There are no open protocols to allow users to securely share a resource.
+6. **Availability problem**: People want to smoothly switch devices, and restore their data if they lose a device, but this very difficult to do securely.
+7. **Update problem**: Almost universally, software updates are done in ways that invite attacks and device compromises.
+
+These problems appear to be present regardless of which architectural approach you take (centralized authority, distributed peer-to-peer, or federated servers).
+
+It is possible to safely ignore many of these problems if you don't particularly care about usability or matching the features that users have grown accustomed to with contemporary methods of online communication. But if you do care about usability and features, then you are stuck with finding solutions to these problems.
+
+## Our solutions
+
+In our work, LEAP has tried to directly face down these seven problems. In some cases, we have come up with solid solutions. In other cases, we are moving forward with temporary stop-gap measures and investigating long term solutions. In two cases, we have no current plan for addressing the problems.
+
+### Authenticity problem
+
+The problem:
+
+> Public key validation is very difficult for users to manage, but without it you cannot have confidentiality.
+
+If proper key validation is a precondition for secure communication, but it is too difficult for most users, what hope do we have? We have developed a unique federated system called [Nicknym](/nicknym) that automatically discovers and validates public keys allowing the user to take advantage of public key cryptography without knowing anything about keys or signatures.
+
+### Meta-data problem
+
+The problem:
+
+> Existing protocols are vulnerable to meta-data analysis, even though meta-data is often much more sensitive than content.
+
+As a short term measure, we are integrating opportunistic encrypted transport (TLS) for email and chat messages when relayed among servers. There are two important aspects to this:
+
+* Relaying servers need a solid way to discover and validate the keys of one another. For this, we are initially using DNSSEC/DANE.
+* An attacker must not be able to downgrade the encrypted transport back to cleartext. For this, we are modifying software to ensure that encrypted transport cannot later be downgraded.
+
+This approach is potentially effective against external network observers, but does not protect the meta-data from the service providers themselves. Also, it does not, by itself, protect against more advanced attacks involving timing and traffic analysis.
+
+In the long term, we plan to adopt one of several different schemes for securely routing meta-data. These include:
+
+* Auto-alias-pairs: Each party auto-negotiates aliases for communicating with each other. Behind the scenes, the client then invisibly uses these aliases for subsequent communication. The advantage is that this is backward compatible with existing routing. The disadvantage is that the user's server stores a list of their aliases. As an improvement, you could add the possibility of a third party service to maintain the alias map.
+* Onion-routing-headers: A message from user A to user B is encoded so that the "to" routing information only contains the name of B's server. When B's server receives the message, it unwraps (unencrypts) a supplementary header that contains the actual user "B". Like aliases, this provides no benefit if both users are on the same server. As an improvement, the message could be routed through intermediary servers.
+* Third-party-dropbox: To exchange messages, user A and user B negotiate a unique "dropbox" URL for depositing messages, potentially using a third party. To send a message, user A would post the message to the "dropbox". To receive a message, user B would regularly polls this URL to see if there are new messages.
+* Mixmaster-with-signatures: Messages are bounced through a mixmaster-like set of anonymization relays and then finally delivered to the recipient's server. The user's client only displays the message if it is encrypted, has a valid signature, and the user has previously added the sender to a 'allow list' (perhaps automatically generated from the list of validated public keys).
+
+For a great discussion comparing mix networks and onion routing, see [Tom Ritter's blog post on the topic](https://ritter.vg/blog-mix_and_onion_networks.html).
+
+### Asynchronous problem
+
+The problem:
+
+> For encrypted communication, you must currently choose between forward secrecy or the ability to communicate asynchronously.
+
+In the example of email and chat, we have OpenPGP with email and OTR with chat: the former provides asynchronous capabilities, and the latter forward secrecy, but neither one supports both abilities.
+
+With the pace of growth in digital storage and decryption, forward secrecy is increasingly important. Otherwise, any encrypted communication you engage in today is likely to become cleartext communication in the near future.
+
+Because all email is asynchronous, encrypted email does not have forward secrecy. But this is a problem for chat too, because increasingly users demand the ability to send and receive offline chat messages, so we can no longer assume that chat is a synchronous protocol.
+
+In the short term, we are layering forward secret transport for email and chat relay on top of traditional object encryption (OpenPGP). This approach is identical to our stop-gap approach for the meta-data problem, with the one addition that relaying servers need the ability to not simply negotiate TLS transport, but to also negotiate forward secret ciphers and to prevent a cipher downgrade.
+
+This approach is potentially effective against external network observers, but does not achieve forward secrecy from the service providers themselves.
+
+In the long term, we plan to work with other groups to create new encryption protocol standards that can be both asynchronous and forward secret. The essential idea is to combine both object encryption and session encryption, and to opportunistically upgrade to session encryption when possible, potentially using session keys that are long lived or kept alive until the next synchronous session. Currently, Open Whisper System's TextSecure is the only working example of using long lived session keys for simulating asynchronous communication with forward secrecy that we are aware of.
+
+### Group problem
+
+The problem:
+
+> In practice, people work in groups, but public key cryptography doesn't.
+
+We have a lot of ideas, but we don't have any solutions yet to fix this. Essentially, the question is how to use existing public key primitives to create strong cryptographic groups, where membership and permissions are based on keys and not arbitrary server-maintained access control lists.
+
+Most of the interesting work in this area has been done by companies working on secure file backup/sync/sharing, such as Wuala and Spideroak. Unfortunately, there are not yet any good open protocols or free software packages that can handle group cryptography.
+
+### Resource problem
+
+The problem:
+
+> There are no open protocols to allow users to securely share a resource.
+
+For example, when using secure chat or secure federated social networking, you need some way to link to external media, such as an image, video or file, that has the same security guarantees as the message itself. Embedding this type of resource in the messages themselves is prohibitively inefficient.
+
+We don't have a proposal for how to address this problem. There are a lot of great initiatives working under the banner of read-write-web, but these do not take encryption into account. In many ways, solutions to the resource problem are dependent on solutions to the the group problem.
+
+As with the group problem, most of the progress in this area has been by people working on encrypted file sync (e.g. strategies like Lazy Revocation and Key Regression).
+
+### Availability problem
+
+The problem:
+
+> People want to smoothly switch devices, and restore their data if they lose a device, but this very difficult to do securely.
+
+Users today demand the ability to access their data on multiple devices and to have piece of mind that there data will not be lost forever if they lose a device. In the free software world, only Firefox has addressed this problem adequately and in a secure way (with Firefox Sync).
+
+At LEAP, we have worked to solve the availability problem with a system we call [Soledad](/soledad) (for Synchronization of Locally Encrypted Documents Among Devices). Soledad gives the client application an encrypted, synchronized, searchable document database. All data is client encrypted, both when it is stored on the local device and synced with the cloud. As far as we know, there is nothing else like it, either in the free software or commercial world.
+
+### Update problem
+
+The problem:
+
+> Almost universally, software updates are done in ways that invite attacks and device compromises.
+
+The sad state of update security is especially troublesome because update attacks can now be purchased off the shelf by repressive regimes. The problem of software update is particular bad on desktop platforms. In the case of mobile and HTML5 apps, the vulnerabilities are not as dire, but the issues are also harder to fix.
+
+To address the update problem, LEAP is adopting a unique update system called Thandy from the Tor project. Thandy is complex to manage, but is very effective at preventing known update attacks.
+
+Thandy, and the related [TUF](https://updateframework.com), are designed to address the many [security vulnerabilities in existing software update systems](https://updateframework.com/projects/project/wiki/Docs/Security). In one example, other update systems suffer from an inability of the client to confirm that they have the most up-to-date copy, thus opening a huge vulnerability where the attacker simply waits for a security upgrade, prevents the upgrade, and launches an attack exploiting the vulnerability that should have just been fixed. Thandy/TUF provides a unique mechanism for distributing and verifying updates so that no client device will install the wrong update or miss an update without knowing it.
+
+Related to the update problem is the backdoor problem: how do you know that an update does not have a backdoor added by the software developers themselves? Probably the best approach is that taken by [Gitian](https://gitian.org/), which provides a "deterministic build process to allow multiple builders to create identical binaries". We hope to adopt Gitian in the future.
diff --git a/docs/tech/infosec/en.haml b/docs/tech/infosec/en.haml
new file mode 100644
index 0000000..306fbe9
--- /dev/null
+++ b/docs/tech/infosec/en.haml
@@ -0,0 +1,104 @@
+- @title = "Architecture comparison"
+- @summary = "A comparison of the trade-offs made by different communication archectures"
+
+= render_local_template 'table-style'
+
+%h1.first You can't have it all
+
+%p Every messaging architecture makes certain design choices that privilege one property of information security over another. Although there is no intrinsically necessary trade off among different information security properties, when we examine the technical limitations of actual implementations we see clearly that existing architectures are structurally biased toward certain properties and against others.
+
+%h1 A fancy table
+
+%p This table provides a rough comparison of the choices made by common messaging architectures. See #{link 'below for details' => '#table-notes'} regarding the column and row headings.
+
+.p
+  %b Table 1. Information security of common messaging architectures
+  = render_local_template 'table', :table_type => :big
+
+%p Reasonable people may disagree: this table represents one defensible assessment of the various architecture categories. Many people would adjust one or two cells, but on the whole we believe this table is a fair and accurate comparison. Some squares get low marks because of user error. For example, peer-to-peer systems have a hard time with user friendly keys, leading to high user error and low effective authenticity.
+
+%p In table 2 we see a simplified representation that highlights the relative differences between the encrypted architectures:
+
+.p
+  %b Table 2. Relative trade-offs of encrypted messaging architectures
+  = render_local_template 'table', :table_type => :small
+
+%p Relatively better is not necessarily good. For example, federated and peer-to-peer models have better authenticity than silo models, but still in practice have many authenticity problems.
+
+%h1 The LEAP strategy
+
+%p In a nutshell, the LEAP strategy is this: take a federated architecture and improve the authenticity, unmappability, and usability. In table form, that looks like this:
+
+.p
+  %b Table 3. The LEAP strategy for improving federated architectures
+  = render_local_template 'table', :table_type => :leap
+
+%p Why this focus on authenticity, unmappability, and usability?
+
+%p First, there is a lot of room for improvement. We believe that there is actually no particular structural reason why these properties are so low in existing federated encrypted architectures.
+
+%p Second, these property are extremely important and yet are typically given low priority or are ignored completely.
+
+%ul
+  %li
+    %b Authenticity:
+    Message security rests entirely on a foundation of authenticity. Without proper validation of encryption keys, you cannot be assured of confidentiality or integrity. Unfortunately, current system of establishing message authenticity are so difficult to use that most users simply ignore this step. LEAP will address these problems with a system of #{link 'strong and automatic identity validation' => 'nicknym'}.
+  %li
+    %b Usability:
+    There are plenty of high security tools that are nearly impossible for the common user to use correctly. If the tool is too difficult, it will not be widely adopted and will likely be used incorrectly by those who do adopt it. LEAP with address these problems with the #{link 'LEAP client' => 'client'} that is tightly coupled with the server-side software and is autoconfiguring.
+  %li
+    %b Unmappability:
+    Recent advances in social network analysis and the greatly expanded of ability state and corporate actors to gather social graph information have made unmappability an urgent requirement for any architecture that seeks to address the surveillance situation we face today. LEAP will address these problems with our proposal for #{link 'graph resistant routing' => 'routing'}.
+
+%p Improvement in these areas will come at a price. Although LEAP communication tools will be backward compatible with existing federated standards, a user of the LEAP platform will not have the same degree of choice in client software and provider as does a user of a traditional federated system. Our goal is to actively help providers adopt the LEAP platform, in order to give users more options in the long run.
+
+%h1#table-notes Decoding the table
+
+%h2 Communication architectures (columns)
+
+(to be written)
+
+%h2 Aspects of information security (rows)
+
+%p Classical information security consists of a trio of properties: confidentiality, integrity, availability. To this list, others have added authenticity, control, and anonymity (among many others).
+
+%p For our purposes here, we also add usability, compatibility, and unmappability. What do all these mean? Let's use the example of a single message, and group these nine properties in three categories:
+
+%h3 Message Security
+
+%table.properties
+  %tr
+    %th Confidentiality
+    %td A message has highly confidentiality if only the intended recipients are able to read the message.
+  %tr
+    %th Integrity
+    %td A message has high integrity if the recipient is assured the message has not been altered.
+  %tr
+    %th Availability
+    %td A message has high availability if the user is able to get to the message when they so desire.
+
+%h3 Identity Security
+
+%table.properties
+  %tr
+    %th Authenticity
+    %td A message has high authenticity if the recipient is certain who sent the message and the sender is certain who received it.
+  %tr
+    %th Anonymity
+    %td A message has high anonymity if the identity of the sender cannot be established by examining the message or the pattern of message delivery.
+  %tr
+    %th Unmappability
+    %td A message has high unmappability if the social network that you communicate with cannot be easily discovered. Unmappability is often collapsed under anonymity. This is unfortunate. It is true the anonymity is one of the issue at stake with social network mapping, but it is just one of many. Because of recent advances in social network analysis and the ability to gather social graph information, we feel that unmappability deserves to be highlighted on its own.
+
+%h3 User Freedom
+
+%table.properties
+  %tr
+    %th Control
+    %td If a user is in possession of their own data and can do with it exactly what they want (and others cannot use the data in ways contrary to the wishes of the user), then we say that they have high control.
+  %tr
+    %th Usability
+    %td For a communication system to have high usability, the common user must be able to operate the system in a way that does not compromise their security.
+  %tr
+    %th Compatibility
+    %td For a system to have high compatibility, the user must not be locked into a particular provider or technology, but should have competing and compatible options available to them. In other words, a user's data should be portable and they should have a choice of clients.
diff --git a/docs/tech/infosec/table-style.haml b/docs/tech/infosec/table-style.haml
new file mode 100644
index 0000000..c9a3495
--- /dev/null
+++ b/docs/tech/infosec/table-style.haml
@@ -0,0 +1,59 @@
+%style
+  :sass
+    table.properties
+      td
+        vertical-align: top
+        padding-bottom: 0.75em
+      th
+        vertical-align: top
+        padding-right: 1em
+        text-align: right
+        font-weight: normal
+        font-style: italic
+
+    table.infosec
+      width: 100%
+      border-collapse: collapse
+      tbody
+        border-top: 1px solid black
+        border-bottom: 1px solid black
+      th span.normal
+        font-weight: normal
+      th.first, th.second, th.cell
+        width: 14.285714286%
+      th.spacer, td.spacer
+        width: 1px !important
+        padding: 0 !important
+        background: black
+        // border: 1px dotted black
+        //border: 0 !important
+      //th.second
+      //  width: 0%
+      //th.cell
+      //  width: 20%
+      td.cell
+        border-top: 1px solid black
+        border-bottom: 1px solid black
+        //border-right: 1px dotted rgba(0,0,0,.1)
+        border-left: 1px dotted rgba(0,0,0,.1)
+        text-align: center
+        padding: 4px
+        &.none
+          //background-color: #ccc
+          background: #888
+        &.low, &.lower, &.worse
+          //background-color: #FFCCCC
+          background: #aaa
+        &.medium, &.higher
+          //background-color: #FFFFCC
+          background: #ccc
+        &.high, &.better
+          //background-color: #CCFFCC
+          background: #e6e6e6
+        &.better, &.worse
+          font-weight: bold
+      tr.footer td
+        border-left: 1px dotted rgba(0,0,0,.1)
+        text-align: center
+        font-size: 0.8em
+
diff --git a/docs/tech/infosec/table.haml b/docs/tech/infosec/table.haml
new file mode 100644
index 0000000..f2de6bf
--- /dev/null
+++ b/docs/tech/infosec/table.haml
@@ -0,0 +1,233 @@
+:ruby
+
+  if table_type == :small
+    ##
+    ## SMALL TABLE
+    ##
+    columns = [:p2p, :ssilo, :sfed]
+    column_data = {
+      :ssilo  => [:silo, :encrypted],
+      :sfed   => [:federation, :encrypted],
+      :p2p    => [:peer_to_peer, :encrypted]
+    }
+    rows = [:availability, :usability, :compatibility, :authenticity, :control, :anonymity]
+    row_groups = []
+    footer = false
+    cells = {
+      :ssilo => {
+        :control         => [:lower],
+        :compatibility   => [:lower],
+        :usability       => [:higher],
+        :authenticity    => [:lower],
+        :availability    => [:higher],
+        :anonymity       => [:lower]
+      },
+      :sfed => {
+        :control         => [:higher],
+        :compatibility   => [:higher],
+        :usability       => [:lower],
+        :authenticity    => [:higher],
+        :availability    => [:lower],
+        :anonymity       => [:lower]
+      },
+      :p2p => {
+        :control         => [:higher],
+        :compatibility   => [:lower],
+        :usability       => [:lower],
+        :authenticity    => [:higher],
+        :availability    => [:lower],
+        :anonymity       => [:higher]
+      }
+    }
+  elsif table_type == :big
+    ##
+    ## BIG TABLE
+    ##
+    columns = [:silo, :fed, :ssilo, :sfed, :p2p]
+    column_data = {
+      :silo   => [:silo, :cleartext, :silo_example],
+      :fed    => [:federation, :cleartext, :fed_example],
+      :ssilo  => [:silo, :encrypted, :ssilo_example],
+      :sfed   => [:federation, :encrypted, :sfed_example],
+      :p2p    => [:peer_to_peer, :encrypted, :p2p_example],
+      :spacer  => [:spacer, :spacer, :spacer]
+    }
+    rows = [
+      :control, :compatibility, :usability,
+      :anonymity, :unmappability, :authenticity,
+      :availability, :confidentiality, :integrity
+    ]
+    row_groups = [:message_security, :identity_security, :user_freedom]
+    row_groups_data = {
+      :user_freedom      => [:control, :compatibility, :usability],
+      :identity_security => [:authenticity, :anonymity, :unmappability],
+      :message_security  => [:confidentiality, :integrity, :availability]
+    }
+    footer = true
+    cells = {
+      :silo => {
+        :control         => [:none],
+        :compatibility   => [:none],
+        :usability       => [:high],
+        :anonymity       => [:none],
+        :unmappability   => [:none],
+        :authenticity    => [:none],
+        :availability    => [:high],
+        :confidentiality => [:none],
+        :integrity       => [:none]
+      },
+      :fed => {
+        :control         => [:medium],
+        :compatibility   => [:high],
+        :usability       => [:medium],
+        :anonymity       => [:none],
+        :unmappability   => [:none],
+        :authenticity    => [:none],
+        :availability    => [:medium],
+        :confidentiality => [:none],
+        :integrity       => [:none]
+      },
+      :ssilo => {
+        :control         => [:none],
+        :compatibility   => [:none],
+        :usability       => [:high],
+        :anonymity       => [:low],
+        :unmappability   => [:none],
+        :authenticity    => [:none],
+        :availability    => [:high],
+        :confidentiality => [:high],
+        :integrity       => [:high]
+      },
+      :sfed => {
+        :control         => [:medium],
+        :compatibility   => [:medium],
+        :usability       => [:low],
+        :anonymity       => [:low],
+        :unmappability   => [:none],
+        :authenticity    => [:low],
+        :availability    => [:medium],
+        :confidentiality => [:high],
+        :integrity       => [:high]
+      },
+      :p2p => {
+        :control         => [:high],
+        :compatibility   => [:none],
+        :usability       => [:low],
+        :anonymity       => [:medium],
+        :unmappability   => [:medium],
+        :authenticity    => [:low],
+        :availability    => [:low],
+        :confidentiality => [:high],
+        :integrity       => [:high]
+      },
+      :spacer => {
+        :control         => [:spacer],
+        :compatibility   => [:spacer],
+        :usability       => [:spacer],
+        :anonymity       => [:spacer],
+        :unmappability   => [:spacer],
+        :authenticity    => [:spacer],
+        :availability    => [:spacer],
+        :confidentiality => [:spacer],
+        :integrity       => [:spacer]
+      }
+    }
+  elsif table_type == :leap
+    ##
+    ## LEAP TABLE
+    ##
+    columns = [:fed, :sfed, :leap]
+    column_data = {
+      :ssilo  => [:silo, :encrypted],
+      :sfed   => [:federation, :encrypted],
+      :p2p    => [:peer_to_peer, :encrypted],
+      :fed    => [:federation, :cleartext],
+      :leap   => [:leap, :encrypted]
+    }
+    rows = [
+      :control, :compatibility, :usability,
+      :anonymity, :unmappability, :authenticity,
+      :availability, :confidentiality, :integrity
+    ]
+    row_groups = [:message_security, :identity_security, :user_freedom]
+    row_groups_data = {
+      :user_freedom      => [:control, :compatibility, :usability],
+      :identity_security => [:authenticity, :anonymity, :unmappability],
+      :message_security  => [:confidentiality, :integrity, :availability]
+    }
+    footer = false
+    cells = {
+      :fed => {
+        :control         => [:medium],
+        :compatibility   => [:high],
+        :usability       => [:medium],
+        :anonymity       => [:none],
+        :unmappability   => [:none],
+        :authenticity    => [:none],
+        :availability    => [:medium],
+        :confidentiality => [:none],
+        :integrity       => [:none]
+      },
+      :sfed => {
+        :control         => [:medium],
+        :compatibility   => [:medium],
+        :usability       => [:low],
+        :anonymity       => [:low],
+        :unmappability   => [:none],
+        :authenticity    => [:low],
+        :availability    => [:medium],
+        :confidentiality => [:high],
+        :integrity       => [:high]
+      },
+      :leap => {
+        :control         => [:medium],
+        :compatibility   => [:worse],
+        :usability       => [:better],
+        :anonymity       => [:low],
+        :unmappability   => [:better],
+        :authenticity    => [:better],
+        :availability    => [:medium],
+        :confidentiality => [:high],
+        :integrity       => [:high]
+      }
+    }
+  end
+
+%table.infosec
+  %tr
+    %th.first
+    - if row_groups.any?
+      %th.second
+    - columns.each do |column|
+      - if column == :spacer
+        %th.spacer
+      - else
+        %th.cell
+          = I18n.t column_data[column][0], :scope => 'infosec'
+          %br<>
+          %span.normal
+            = I18n.t column_data[column][1], :scope => 'infosec'
+  - if row_groups.any?
+    - row_groups.each do |row_group|
+      %tbody
+        - rows = row_groups_data[row_group]
+        - rows.each do |row|
+          %tr
+            - if rows.first == row
+              %td{:rowspan=>3}= I18n.t(row_group, :scope => 'infosec').sub(' ', '<br/>').html_safe
+            %td= I18n.t row, :scope => 'infosec'
+            - columns.each do |column|
+              %td.cell{:class => cells[column][row]}= I18n.t cells[column][row].first, :scope => 'infosec'
+  - else
+    - rows.each do |row|
+      %tbody
+        %tr
+          %td= I18n.t row, :scope => 'infosec'
+          - columns.each do |column|
+            %td.cell{:class => cells[column][row]}= I18n.t(cells[column][row].first, :scope => 'infosec')
+  - if footer
+    %tr.footer
+      %td{:colspan=>2}= I18n.t :for_example, :scope => 'infosec'
+      - columns.each do |column|
+        %td= I18n.t column_data[column][2], :scope => 'infosec'
+
diff --git a/docs/tech/limitations.md b/docs/tech/limitations.md
new file mode 100644
index 0000000..e61d1c3
--- /dev/null
+++ b/docs/tech/limitations.md
@@ -0,0 +1,100 @@
+@title = 'Known Limitations'
+@toc = true
+@summary = 'Known limitations, issues, and security problems with the LEAP platform'
+
+Herein lie the know limitations, issues, and security problems of the LEAP platform.
+
+Provider problems
+==========================================
+
+Meta-data can be recorded by the provider
+-------------------------------------------------
+
+Currently, the service provider is able to observe the meta-data routing information of messages in transit of their own users (email and chat). This information is not stored, but a nefarious provider could observe this information in transit and record it.
+
+We have several plans to eliminate this, but these are not part of the initial release.
+
+The provider can undermine the security of the web application
+-------------------------------------------------------------------------
+
+Both the client and the web application use something called SRP (Secure Remote Password) to prevent the server from ever seeing a cleartext copy of the password. This is in contrast to normal password systems, where the password is hashed on the server, so the server could record a copy of the password when it is initially set.
+
+However, because all the javascript cryptographic libraries used by the user's web browser to perform the SRP negotiation are loaded from the provider's server, a nefarious or compromised provider could give the user's browser bad libraries that secretly sent a cleartext copy of the user's password.
+
+There are two methods that can be used to prevent this:
+
+* We could offer the option of first visiting a third party website that loads the authentication libraries before redirecting to the provider's website. Unfortunately, this user experience is a bit awkward.
+* We could allow providers the option of not allowing authentication or signup through the webapp. Instead, the client could be distributed with an HTML page with all the javascript needed to authenticate. When the user wants to authenticate, the client loads this page in a web browser, authenticates with the provider's API, and then redirects to the actual website.
+
+It is not either or, we could support both options.
+
+The details for both of these are bit more tricky than in these simple descriptions, because of the need to work around the single origin policy, but it is still entirely possible to do this securely (using either CORS or PostMessage).
+
+Still possible to brute force the password verifier
+-----------------------------------------------------------------
+
+SRP (Secure Remote Password) does not store a hash of the password in the provider's user database, but instead a password verifier. However, if an attacker gains access to the database of password verifiers (plus salts) they can perform a brute force attack similar to a normal attack on a database of password hashes. The attack in the case of SRP is more difficult, since there is more cryptographic work involved, but it is still possible.
+
+To mitigate exposure of the password verifiers, we plan to separate them out into a separate database with only a separate single-purpose authentication API daemon granted access.
+
+The provider can observe VPN traffic
+--------------------------------------------------
+
+The "Encrypted Internet" feature of LEAP currently works using OpenVPN secure tunnel to proxy all network traffic to a gateway operated by the provider. Once the traffic exits this gateway, it is cleartext (unless otherwise encrypted on the client, e.g. HTTPS) and could be observed and record by the provider, or any network observer able to monitor all traffic into and out of the gateway.
+
+This limitation is mitigated by having the LEAP client authenticate with the VPN gateway using semi-anonymous or anonymous client certificates. A nefarious or compromised provider could attempt to record the moment that a user fetches a new client certificate, and record the IP address or authentication credentials of the user at that time.
+
+In the future, we plan to remove this vulnerability in two ways:
+
+* Allow the client to fetch new client certificates using blind signatures, so that there is no way for the provider to associate user with certificate, but we can also ensure that only valid users get client certificates.
+* Use Tor as an alternate and optional transport for "Encrypted Internet". From the stand point of the user, it would work the same (using perhaps tun socks proxy and dnscrypt-proxy). This option would be slower and not support UDP traffic, but it would be much more secure. The Tor project prefers that every application that uses Tor be specifically designed for Tor so that it does not leak information in other ways. Using Tor as a default route like we do with OpenVPN would violate this, but would be more user friendly.
+
+User problems
+=================================
+
+A compromised device is a sad device
+----------------------------------------------
+
+The LEAP client tries to minimize attacks related to physical access to the device. In particular, we try to be very resistant to offline attacks, where an attacker has captured the user's device while the LEAP client does not have an open session. For example, locally stored data is kept in an encrypted database that is only unlocked when the user authenticates with the application.
+
+However, if an attacker gains access to the device, and then the device is returned to the user, they can do all kinds of nasty things, like install a keylogger that captures every keystroke.
+
+This vulnerability is true of all software, not just LEAP, but it is worth noting.
+
+Passwords are never going to be very good
+---------------------------------------------------
+
+LEAP relies on the user's password to unlock access to the user's client encrypted data storage. It does this the right way, using a solid KDF, but passwords are pretty limited and offer marginal security if an attacker gains offline access to the user's encrypted storage (for example, if they obtain the device).
+
+In the future, we hope to add support for OpenPGP smart cards in order to overcome many of the problems associated with passwords.
+
+Design problems
+============================================
+
+Enumeration of usernames
+-----------------------------
+
+The system LEAP uses to validate the public keys of users is inherently vulnerable to an attacker enumerating usernames. Because requests for public keys may be proxy'ed through other providers, there is no good method of preventing an attacker from launching many queries for public keys and eventually mapping most of the usernames.
+
+This is unfortunate, but this is also a problem with all other such systems of key discovery and validation (i.e. DANE). For now, we consider this to be an acceptable compromise.
+
+Much trust is placed in LEAP
+-------------------------------------------
+
+In order to shield the service provider from being pressured by a host government or criminal organization to add a backdoor into the client, the model with the LEAP platform is that the client is normally downloaded from the leap.se website and subsequent updates are signed by LEAP developers.
+
+This is good for the provider, but not so good for LEAP, since this system could potentially place pressure on LEAP. Because LEAP does not have a provider-customer relationship with any user, LEAP cannot target compromised applications for particular users. LEAP could, however, introduce a backdoor in the client used by all users.
+
+To prevent this, we plan to adopt [Gitian](https://gitian.org/) or something equivalent. Gitian allows for a way to standardize the entire build environment and build process in order for third parties to be able to verify that the released binary application does indeed match the correct source code.
+
+External authority problems
+=================================================
+
+Certificate authorities considered dangerous
+---------------------------------------------------
+
+The long term goal with LEAP is to entirely rid ourselves of reliance on the x.509 certificate authority system. However, there are a few places where the platform still relies on it:
+
+* When the client first validates a new provider, it will assume the provider's TLS connection is valid if presented with a server certificate signed by a commercial CA recognized by the operating system.
+* When nicknym discovers new public keys for users, it uses a TLS connection validated by a commercial CA recognized by the operating system.
+* Currently, the web application does not get deployed with any other TLS validation than the standard commercial CA method. Eventually, we plan to support [DNS-based Authentication of Named Entities (DANE)](https://datatracker.ietf.org/wg/dane/), [Trust Assertions for Certificate Keys (TACK)](http://tack.io/), or [Public Key Pinning Extension for HTTP](https://datatracker.ietf.org/doc/draft-ietf-websec-key-pinning/).
diff --git a/docs/tech/routing.md b/docs/tech/routing.md
new file mode 100644
index 0000000..948d4c3
--- /dev/null
+++ b/docs/tech/routing.md
@@ -0,0 +1,63 @@
+@title = "Graph Resistant Routing"
+@summary = "LEAP's plans for protecting routing meta-data"
+
+# A social graph is highly sensitive data
+
+As messages are sent and delivered, they contain "meta-data" describing where these messages should be routed. With existing protocols for email and chat, this meta-data is sent in the clear and can be used to build a social graph of how people interact.
+
+As the field of network analysis has advanced in recent years, the social graph has become highly sensitive and critical information. Knowledge of the social graph can give an attacker a blueprint into the inner workings of an organization or reveal surprisingly intimate personal details, such as sexual orientation or even health status.
+
+In the short term, LEAP is opportunistically encrypting the message transport whenever possible. This protects the meta-data routing information from an external observer, but does not protect against a nefarious or compromised service provider. This page is about our plans for a better way.
+
+# Possible solutions
+
+There are four strategies we might employ to add protection of routing information to email and chat:
+
+* Auto-alias-pairs: Each party auto-negotiates aliases for communicating with each other. Behind the scenes, the client then invisibly uses these aliases for subsequent communication. The advantage is that this is backward compatible with existing routing. The disadvantage is that the user's server stores a list of their aliases. As an improvement, you could add the possibility of a third party service to maintain the alias map.
+* Onion-routing-headers: A message from user A to user B is encoded so that the "to" routing information only contains the name of B's server. When B's server receives the message, it unwraps (unencrypts) a supplementary header that contains the actual user "B". Like aliases, this provides no benefit if both users are on the same server. As an improvement, the message could be routed through intermediary servers.
+* Third-party-dropbox: To exchange messages, user A and user B negotiate a unique "dropbox" URL for depositing messages, potentially using a third party. To send a message, user A would post the message to the "dropbox". To receive a message, user B would regularly polls this URL to see if there are new messages.
+* Mixmaster-with-signatures: Messages are bounced through a mixmaster-like set of anonymization relays and then finally delivered to the recipient's server. The user's client only displays the message if it is encrypted, has a valid signature, and the user has previously added the sender to a 'allow list' (perhaps automatically generated from the list of validated public keys).
+
+None of these are currently used for email or chat.
+
+# Auto alias pairs
+
+How would auto alias pairs work? Imagine users Alice and Bob. Alice wants to correspond with Bob but doesn't want either her service provider or Bob's service provider to be able to record the association. She also doesn't want a network observer to be able to map the association.
+
+When Alice first sends a message to Bob, Alice's client will initiate the following chain of events on her behalf, automatically and behind the scenes.
+
+* Alice's client requests a new alias from her service provider. If her normal address is alice@domain.org, she receives an alias hjj3fpwv84fn@domain.org that will forward messages to her account.
+* Alice's client uses automatic key discovery and validation to find Bob's public key and discover if Bob's service provider supports map resistant routing.
+* If Bob does support it, Alice's client will then send a special message, encrypted to Bob's key, that contains Alice's public address and her private alias.
+* When Bob's client encounters this special message, it records a mapping between Alice's public address (alice@domain.org) and the private alias she has created for Bob's use (hjj3fpwv84fn@domain.org).
+* Bob's client then creates an alias for Bob and sends it to Alice.
+* Alice's client receives this alias, and records the mapping between Bob's public address and his private alias.
+* Alice's client then relays the original message to Bob's alias.
+
+Subsequently, whenever Alice or Bob want to communicate, they use the normal public addresses for one another, but behind the scenes their clients will rewrite the source and recipient of the messages to use the private aliases.
+
+This scheme is backwards compatible with existing messaging protocols, such as SMTP and XMPP.
+
+## Limitations
+
+There are five major limitations to this scheme:
+
+1. **Alias unmasking attacks:** because each service provider maintains an alias map for their own users, an attacker who has gained access to this alias map can de-anonymize all the associations into and out of that particular provider, for the past and future.
+2. **Timing attacks:** a statistical analysis of the time that messages of a particular size are sent, received, and relayed by both service providers could reveal the map of associations.
+3. **Log correlation problem:** a powerful attacker could gain access to the logs of both service providers, and thereby reconstruct the associations between the two providers.
+4. **Single provider problem:** this scheme does not protect associations between people on the same service provider.
+5. **Client problem:** if the user's device is compromised, the record of their actual associations can be discovered.
+
+At this point, we feel that it is OK to live with these limitations for the time being in order to simply the logic of the user's client application and to ensure backward compatibility with existing messaging protocols.
+
+Possible future enhancements could greatly mitigate these attacks:
+
+* We could use temporarily aliases that rotate daily, perhaps based on an HMAC counter, based on a shared secret between two users.
+* The 'alias service' could be run by a third party, so that providers don't have access to the alias maps (thus migitating problems 1, 3, and 4).
+* A service provider with sufficient traffic could be in a very good position to be able to aggregate and time-shift the messages it relays in order to disrupt timing attacks.
+
+Ultimately, however, most of these attacks are a problem when faced with an extremely powerful adversary. This scheme is not designed for these situations. Instead, it is designed to prevent the casual, mass surveillance of all communication that currently takes place in repressive and democratic countries alike, by both governments and corporations. It greatly reduces the capacity for association mapping of both traffic over the wire and in stored communication. It is not designed to make a particular user anonymous when specifically targeted by a powerful adversary.
+
+# How would X work?
+
+How would onion-routing-headers, third-party-dropbox, or mixmaster-with-signatures work? To be written.