feat(1.2): add preliminary requirements analysis & design (#2)

Co-authored-by: Diogo Correia <[email protected]>
Co-authored-by: Marco Campione <[email protected]>
Co-authored-by: Mathias Magnusson <[email protected]>
Co-authored-by: Tom Sorger <[email protected]>

docs/1-2-prelim-req-an.typ

@@ -0,0 +1,270 @@
+#import "common/template.typ": cover_page, header, footer, setup_page
+
+#cover_page(
+  title: "Preliminary Requirements Analysis & Design Report", date: "February 2024",
+)
+
+#pagebreak()
+
+#show: setup_page
+
+#set page(
+  "a4", header: header(title: "Prelim. Req. Analysis & Design"), footer: footer,
+)
+#counter(page).update(1)
+#set par(leading: 0.61em)
+
+= Introduction
+
+After a thorough analysis of the requirements set forth by ACME Scandinavia, our
+team has constructed a detailed list of requirements that were then used as a
+basis for our system design proposal, as outlined within this document.
+@fig-net-top in @annex-net-top is also provided as a visual reference to the
+present proposal.
+
+= Security Requirements
+
+#set enum(full: true, numbering: (..nums) => {
+  let nums = nums.pos()
+  let level = nums.len()
+
+  let result = numbering("R1.1.", ..nums)
+  if level <= 1 {
+    strong(result)
+  } else {
+    result
+  }
+})
+
++ *Employee Authentication*
+  + Corporate laptops store certificates that attest their long-term identity;
+  + Using these certificates, employees are issued short-lived pseudonym
+    certificates that services use to authenticate clients and verify authorization
+    against embedded roles/permissions; and
+  + Employees use their company mobile phone for 2FA using Time-based One Time
+    Passwords (TOTPs).
+
++ *Secure Connectivity*
+  + Roaming employees can use a VPN (through OpenVPN with their pseudonymous
+    certificates) to connect to company resources;
+  + Network infrastructure can distinguish and enforce different permissions for
+    devices at the Stockholm Headquarters, at the London branch, and roaming
+    elsewhere (connected through VPN);
+  + Only traffic originating from the Stockholm or London offices can perform
+    critical operations;
+  + Network traffic and requests are logged to a centralized location; and
+  + Secure employee-to-employee authentication is possible using pseudonymous
+    certificates.
+
++ *Confidentiality and Anonymity*
+  + Communications between different branches and within the company are hidden from
+    third parties (e.g., attackers sniffing network traffic) through pseudonymous
+    authentication and E2E encryption;
+  + The main web server containing critical data can only be accessed by specific,
+    trusted users connecting from within a physical branch;
+  + Servers containing less critical data are available for employees both
+    physically within a branch and roaming (e.g., from home or while traveling); and
+  + Curious observers cannot identify employee communication parties or obtain any
+    of the exchanged information.
+
++ *Secure Wireless Access*
+  + Visiting employees can connect to the network and access resources within their
+    home branch; and
+  + Authentication and authorization take place using (pseudonymous) client
+    certificates over TLS through the wireless networks if the employee is at a
+    branch.
+
++ *Secure File Exchange*
+  + ACME employees (and only ACME employees) can securely exchange files between
+    their corporate mobile phones; and
+  + The network infrastructure guarantees the Confidentiality, Integrity, and
+    Authenticity of exchanged files.
+
++ *Other Security*
+  + The network is continuously monitored by an Intrusion Detection System (IDS) to
+    detect attempted attacks;
+  + Denial of Service attacks are detected by the IDS, which (through an Intrusion
+    Prevention System component) dynamically updates firewall rules to block it;
+  + All devices and servers use a private DNS resolver which enforces security
+    requirements (e.g., validate DNSSEC assertions); and
+  + Compromised credentials are easy to revoke, with pseudonymous certificates being
+    short-lived and the identity management system providing an OCSP endpoint for
+    highly critical consumers to use according to their specific requirements if a
+    standard CRL mechanism is not suitable.
+
+#pagebreak()
+
+= System Design
+
+== User Identity and Credential Management
+
+At the core of our proposed system is a robust identity and credential
+management scheme that strives to ensure strict compliance with the security
+requirements set forth by ACME Scandinavia. In concrete terms, we propose having
+a centralized user management platform (such as a _FreeIPA_ instance) that can
+act as the single source of truth for all other components with regard to user
+information/metadata/permissions, and make its information available to other
+services by exposing specific APIs designed for different purposes and use
+cases, such as LDAP and Kerberos. In addition, we believe that _Authentik_ would
+make it more convenient for higher-level web-based services to authenticate
+users, as it integrates with _FreeIPA_ and provides other mechanisms such as
+OAuth2.
+
+Finally, we propose using a tool such as _step-ca_ to manage all the Public Key
+Infrastructure (PKI), acting as a Certificate Authority for hosts, services, and
+users. In particular, this service would be responsible for issuing long-term
+identity certificates to user devices as well as (multiple) shorter-term
+pseudonymous certificates to be used when interacting with other services. It
+would also be responsible for an eventual integration with ACME's _x-PKI_ and
+handling revocation when instructed to by _FreeIPA_.
+
+== Network Topology
+
+As outlined in @fig-net-top of @annex-net-top, we believe the network should be
+segmented into logical components, but without unnecessarily adding to the
+system's complexity. We propose a total of eight VLANs divided as described
+below, with each one using IP addresses from a pool corresponding to a specific
+subnet of `10.0.0.0/8`, the overall range to be used by the network
+infrastructure (reserved for private use by IANA).
+
+- VLAN 10 (`10.10.0.0/16`): Servers, Stockholm Headquarters
+- VLAN 11 (`10.11.0.0/16`): Employee Corporate Devices, Stockholm Headquarters
+  (wired + wireless)
+- VLAN 12 (`10.12.0.0/16`): Employee Corporate Devices through VPN, Stockholm
+  Headquarters VPN Server#footnote[In theory VLANs 12 and 22 could be merged into a single "VPN clients" VLAN even
+    with separate geographical-based servers (one provided at each location to
+    mitigate latency issues), but separate address spaces simplify routing and
+    management.]<footnote-vpn-vlan>
+- VLAN 13 (`10.13.0.0/16`): Guest Devices, Stockholm Headquarters (wired +
+  wireless)
+- VLAN 20 (`10.20.0.0/16`): Servers, London Branch
+- VLAN 21 (`10.21.0.0/16`): Employee Corporate Devices, London Branch (wired +
+  wireless)
+- VLAN 22 (`10.22.0.0/16`): Employee Corporate Devices through VPN, Stockholm
+  Headquarters VPN Server @footnote-vpn-vlan
+- VLAN 23 (`10.23.0.0/16`): Guest Devices, London Branch (wired + wireless)
+
+These VLANs allow us to compartmentalize devices and introduce logical borders
+between different zones, with the benefit of being able to define with which
+other VLANs each VLAN may communicate, in accordance with ACME's requirements.
+In order to manage this effectively, we propose having a dedicated router at
+each ACME location (Stockholm and London) hosted in NUC machines (though for
+initial prototyping one might be replaceable by a VM). Placing this logic in a
+separate context from the Wireless Access Points contributes to the system's
+scalability, as more APs can be introduced with little effort: they only need to
+be configured to broadcast two SSIDs, each of them assigned to a different VLAN: "ACME-Corp"
+(for employees; WPA2-Enterprise#footnote[WPA3 is not supported by Asus RT-AC68U Access Points.]<footnote-wpa3> authenticating
+through an instance of _FreeRADIUS_; VLAN 11 or 21) and "ACME-Guest" (for
+non-corporate devices; WPA2-PSK @footnote-wpa3; VLAN 13 or 23). Finally,
+Ethernet ports for wired connections are assigned as if on the guest network,
+unless otherwise requested and configured on a case-by-case basis.
+
+Each of these two routers also connects to the overall Internet and provides the
+only gateway between the latter and the devices in the internal network, making
+it a prime location to have an Intrusion Detection and Prevention System
+instance (such as _Snort_) and a firewall, possibly in the form of _iptables_ rules.
+In particular, one of these rules would block all incoming and outgoing DNS
+traffic for all other hosts, requiring them to use a private DNS resolver
+(perhaps also hosted on the same router) that can enforce stronger security
+guarantees. This DNS server at each office is both authoritative and recursive,
+being designated as the nameserver for the `acme.local` domain within that local
+network but also acting as an all-purpose resolver with DNS over TLS (DoT)
+support and performing DNSSEC checks for external query (responses), which must
+succeed for the resolution to be successful (if DNSSEC is supported).
+
+Other firewall rules would further restrict acceptable traffic, for example by
+disallowing all incoming connections (unless established), except for servers
+with exposed services, including the VPN server (such as _OpenVPN_) also running
+on each router (distributed geographically for user convenience), to which
+employees may easily connect to using an _OpenVPN_ client by providing one of
+their pseudonymous certificates. In terms of the internal network, devices
+should not be permitted to communicate with others (both on different VLANs and
+on the same one), with the notable exception of server, employee, and VPN VLANs
+(10-12, 20-22) being allowed to communicate with server VLANs (10, 20)#footnote[Although critical infrastructure such as the main web server in Stockholm can
+  reject connections from the VPN source addresses.]. Between London and
+Stockholm, the two offices communicate over the regular Internet, but through a
+dedicated encrypted tunnel using software such as _Wireguard_, so that employees
+in London can access servers in Stockholm and vice-versa.
+
+== Software Stack
+
+There are a number of tools that fit within our vision for ACME Scandinavia's
+new infrastructure, due to the various characteristics described in this section
+that make them suitable to fulfill different roles in the context of the network
+topology and the requirements it should comply with. First of all, for all of
+our servers, we propose using #link(
+  "https://github.com/astro/microvm.nix",
+)[NixOS Virtual Machines (_micro VMs_)], as this allows their ease of management
+and ensures we always have declarative configurations that lead to reproducible
+builds, safeguarding security through isolation and transparency (easier to
+notice if something looks strange).
+
+In terms of identity management, we propose using #link("https://www.freeipa.org/")[_FreeIPA_] as
+aforementioned, as it is highly extensible, allows for easy policy management,
+provides LDAP and Kerberos endpoints (among others) that other services can
+easily consume, and supports two-factor authentication. It also has good
+integration with #link("https://goauthentik.io/")[_Authentik_], which further
+complements our authentication and authorization setup by providing additional
+schemes such as OAuth2 which are very convenient for higher-level flows (e.g.,
+for web applications). Additionally, we propose #link("https://github.com/smallstep/certificates")[_step-ca_] as
+a Certificate Authority to manage ACME's Public Key Infrastructure, as it is a
+modern "easy to use and hard to misuse" solution with impressive feature
+support. In particular, it can dynamically generate certificates from OIDC
+tokens (e.g., from _Authentik_) or from other certificates (e.g., pseudonyms
+from long-term identities). It can also handle revocations smoothly and publish
+CRLs for other services to process, and it supports the Automatic Certificate
+Management Environment protocol, which we will use for issuing TLS certificates
+for internal services. However, for public-facing services, TLS certificates
+will be issued exclusively by #link("https://letsencrypt.org/")[_Let's Encrypt_],
+as enforced through a CAA DNS record. Moreover, the final piece in our
+authentication puzzle is #link("https://github.com/FreeRADIUS/freeradius-server")[_FreeRADIUS_] which
+is, as the name implies, a RADIUS server that can allow us to use more complex
+authentication mechanisms with WPA2-Enterprise, namely TLS authentication based
+on a client-provided certificate.
+
+For VPNs we suggest two distinct solutions: for general employee use, #link("https://github.com/OpenVPN/openvpn")[_OpenVPN_] is
+more user-friendly and supports important features such as authentication with
+client certificates and dynamically assigned IP addresses. However, for secure
+communications between the London branch and the Stockholm headquarters, flowing
+traffic through a #link("https://www.wireguard.com/")[_Wireguard_] tunnel is
+faster and better for static clients that do not change often (i.e., the
+routers, in this case). Its considerably smaller codebase also makes it more
+auditable and provides a smaller attack surface.
+
+Another important component of this networked system is a DNS server in each
+office location, for which we propose using #link("https://github.com/isc-projects/bind9")[_BIND 9_],
+since it has widespread usage (essentially being the de facto standard
+implementation), it is authoritative and recursive, and it supports features
+relevant to us such as DNSSEC validation and DoT. In addition, possibly within
+the same machine, we propose hosting an instance of #link("https://www.snort.org/")[_Snort_],
+an Intrusion Prevention System that can detect malicious-seeming patterns and
+dynamically respond to them --- possibly by automatically updating #link("https://git.netfilter.org/iptables/")[_iptables_],
+which serves as our firewall. Adding #link("https://github.com/fail2ban/fail2ban")[_fail2ban_] to
+the mix also helps prevent computational exhaustion by banning addresses that
+cause multiple authentication errors, and it can integrate with _Snort_ too.
+Furthermore, for file storage and sharing, we propose using #link("https://github.com/nextcloud/server")[_NextCloud_] or
+another similar solution that supports end-to-end encryption and SSO - as well
+as #link("https://github.com/restic/restic")[_Restic_] for optimized encrypted
+file backups. Finally, we suggest using #link("https://www.zabbix.com/")[_Zabbix_] for
+collecting metrics and logs from multiple sources and detecting problems in
+real-time (e.g., with alerts), since it provides an integrated monitoring
+solution that fits well with our needs.
+
+= Conclusion
+
+In summary, our team has analyzed ACME Scandinavia's provided use case
+descriptions and consolidated them into a list of concrete requirements that
+must be fulfilled. We then elaborated a system design proposal that strives to
+comply with these requirements as effectively and efficiently as possible, given
+the relevant constraints. This report summarizes our work and concisely outlines
+a potential plan for action for ACME's consideration.
+
+#pagebreak()
+#set heading(numbering: "A.", supplement: "Annex")
+#counter(heading).update(0)
+
+= Networked System Topology <annex-net-top>
+
+#figure(image("1-2-x-net-top.svg", width: 100%, fit: "contain"), caption: [
+  Proposal for a high-level topology of the networked system.
+]) <fig-net-top>

docs/common/template.typ

@@ -1,7 +1,8 @@
+#let kthblue = rgb("#2258a5")
+
 #let cover_page(title: none, date: none) = {
   set page("a4", margin: 1in)
   set text(12pt)
-  let kthblue = rgb("#2258a5")
   show link: it => underline(stroke: 1pt + kthblue, text(fill: kthblue, it))
   show heading: set block(above: 1.4em, below: 1em)
 
@@ -72,5 +73,7 @@
   set par(justify: true)
   set heading(numbering: "1.1.")
 
+  show link: it => underline(stroke: 1pt + kthblue, text(fill: kthblue, it))
+
   content
 }