From f741d7377ce0c4c4f31775986d7bf64cf118f517 Mon Sep 17 00:00:00 2001 From: kn0wmad Date: Tue, 7 Dec 2021 20:59:23 -0700 Subject: [PATCH] Initial Setup init --- source/dev-docs/packaging-example.rst | 6 ++-- source/knowledgebase/concepts/embassy-os.rst | 1 + source/knowledgebase/concepts/networks.rst | 29 ++++++++++++++--- source/knowledgebase/concepts/start9.rst | 2 +- .../getting-started/initial-setup.rst | 32 +++++++------------ 5 files changed, 42 insertions(+), 28 deletions(-) diff --git a/source/dev-docs/packaging-example.rst b/source/dev-docs/packaging-example.rst index c0cc4f5..3699fba 100644 --- a/source/dev-docs/packaging-example.rst +++ b/source/dev-docs/packaging-example.rst @@ -1,8 +1,8 @@ .. _packaging-example: -*********************** -Service Packaging Guide -*********************** +************************* +Service Packaging Example +************************* A rough walkthrough of how to package a service using our example `hello-world-wrapper `_. diff --git a/source/knowledgebase/concepts/embassy-os.rst b/source/knowledgebase/concepts/embassy-os.rst index 7189f52..6150a75 100644 --- a/source/knowledgebase/concepts/embassy-os.rst +++ b/source/knowledgebase/concepts/embassy-os.rst @@ -3,3 +3,4 @@ ********* EmbassyOS ********* + diff --git a/source/knowledgebase/concepts/networks.rst b/source/knowledgebase/concepts/networks.rst index 2fb53a3..cafd2c7 100644 --- a/source/knowledgebase/concepts/networks.rst +++ b/source/knowledgebase/concepts/networks.rst @@ -13,10 +13,21 @@ A Local Area Network (LAN) is a computer network that interconnects computers wi Devices on a LAN are private and protected, such that only devices connected to the same Ethernet or WiFi network can see or communicate with them. -Your Embassy hosts itself on the LAN and is reachable by visiting its *.local* URL in the browser while also connected to the LAN. +Your Embassy hosts itself on the LAN and is reachable by visiting its ``embassy.local`` URL in the browser while also connected to the LAN. .. note:: Any device connected to a LAN can inspect all communications on that LAN. To avoid snooping, your Embassy's LAN communications are encrypted using :ref:`ssl`, which requires :ref:`additional setup `. +.. _mdns: + +MDNS +==== + +Multicast Domain Name System (MDNS) is a protocol that resolves a human-readable hostname to an IP address on a small network, such as the home or office network you might host your Embassy on. + +This is known as a "zeroconf," or zero-configuration service, meaning that you can instantly visit a human-recognizable domain name, such as ``embassy.local`` from your network. + +This domain is not broadcast outside of your local network, so it is as private and secure as your LAN. + .. _ssl: SSL @@ -24,7 +35,7 @@ SSL Visiting websites on the Tor network is slow. We wanted to provide a better option to access the Embassy at home. That’s why we created an address for the Embassy that can be accessed on your Local Area Network. -By default, this `.local` address is served like a regular website, over HTTP. Browsers make it noticeable when visiting a site over HTTP in the URL bar - it could be red, show an unlocked lock, or warn that the connection is not secure. +By default, this ``.local`` address is served like a regular website, over HTTP. Browsers make it noticeable when visiting a site over HTTP in the URL bar - it could be red, show an unlocked lock, or warn that the connection is not secure. SSL certificates are what enable websites to move from HTTP to HTTPS, which increases security and makes browsers happy. Using the Secure Sockets Layer protocol, HTTPS enabled websites use certificates to establish authenticated and encrypted links between networked computers. It’s the standard technology for keeping an internet connection secure and safeguarding any sensitive data that is being sent between two devices, preventing third parties from reading and modifying any personal information transferred. They also verify ownership of a website. @@ -32,7 +43,7 @@ Valid SSL certificates are typically issued and obtained from Certificate Author We decided to have the Embassy act as a Certificate Authority. It creates a self-signed certificate, which means that the private key used to sign the digital certificate is the Embassy’s own private key instead of a third party’s. -When you setup SSL for your Embassy and device, the certificate communicates to the client (a browser) that the server (the Embassy) demonstrated ownership of the domain (the `start9-xxxxxxxx.local` address) to the certificate authority (created on the Embassy) at the time of certificate issuance (during the setup process). The Embassy dashboard can then be accessed from a home network (LAN) using a secure HTTPS connection! +When you setup SSL for your Embassy and device, the certificate communicates to the client (a browser) that the server (the Embassy) demonstrated ownership of the domain (the ``embassy-xxxxxxxx.local`` address) to the certificate authority (created on the Embassy) at the time of certificate issuance (during the setup process). The Embassy dashboard can then be accessed from a home network (LAN) using a secure HTTPS connection! For more information on how to setup your devices to enable this feature visit :ref:`ssl-setup`. @@ -50,4 +61,14 @@ When you use Tor to communicate with services running on the Embassy, all the tr Furthermore, every service on the Embassy has a different Tor address, including the device itself. This is for privacy reasons - should one Tor address be exposed, the others will not be compromised. Tor addresses are actually ed25519 keys, which means they also provide all the benefits of cryptographically secure private/public keys. -Here's an introductory video on `Tor `__. \ No newline at end of file +Here's an introductory video on `Tor `__. + + +.. _hidden-service: + +Tor Hidden Service +================== + +A Tor Hidden Service is essentially just software or a website that is only broadcast on the Tor network. These are identified by a long, random public key, and end with the ``.onion`` suffix. For example, you can visit http://privacy34kn4ez3y3nijweec6w4g54i3g54sdv7r5mr6soma3w4begyd.onion to view the Start9 homepage on Tor. + +In order to reach a Hidden Service, you must use a browser that can handle ``.onion`` domains, such as `The Tor Browser `_ or by configuring :ref:`Firefox <>` ***REF NEEDED***. diff --git a/source/knowledgebase/concepts/start9.rst b/source/knowledgebase/concepts/start9.rst index ecc4b41..9c888dd 100644 --- a/source/knowledgebase/concepts/start9.rst +++ b/source/knowledgebase/concepts/start9.rst @@ -4,7 +4,7 @@ Start9 Labs *********** -Start9 Labs is a small, but rapidly growing team of passionate builders. We are based in Denver, Colorado, but with team members around the world. +Start9 Labs is a small, but rapidly growing team of passionate builders. We are based in Denver, Colorado, but have team members around the world. "The Origin of “Start9” ======================= diff --git a/source/user-manual/getting-started/initial-setup.rst b/source/user-manual/getting-started/initial-setup.rst index b2a9ae7..fa737b0 100644 --- a/source/user-manual/getting-started/initial-setup.rst +++ b/source/user-manual/getting-started/initial-setup.rst @@ -6,19 +6,11 @@ Initial Setup .. youtube:: DmTlwp5_zvY -Download the Setup App -====================== - -`App Store `_ - -`Google Play `_ - -`APK direct download `_ - Power On ======== -Connect your Embassy to power and Internet, normally using an ethernet port on your home Internet router. +#. Connect your Embassy to power and Internet, normally using an ethernet port on your home Internet router. +#. Plug in your external drive to one of the USB 3.0 (blue) ports on Embassy. .. note:: To avoid networking issues, it is recommended to use your primary router, not an extender or mesh router. @@ -30,26 +22,26 @@ You will hear 2 distinct sounds: Claim Your Embassy ================== -1. Ensure your phone is connected to the same WiFi network as your router. +1. Ensure the device you are using is connected to the same network as your router. .. warning:: Sometmies a router will have a "guest WiFi network," which might be different than the network your Embassy is placed on via ethernet. -2. Inside the Setup App, enter the product key located on the bottom of your Embassy +2. Visit ``embassy.local`` from a web browser. .. admonition:: Explanation :class: toggle expand - The product key is used to discover your Embassy's IP address on the Local Area Network using a hashing function and a protocol named MDNS (or Zeroconf). Once in possession of the Embassy's local IP address, the Setup App can now communicate directly with the Embassy. + The product key is used to discover your Embassy's IP address on the Local Area Network using a hashing function and a protocol named :ref:`MDNS (or Zeroconf) `. .. admonition:: Troubleshooting :class: toggle expand - #. Confirm that the Embassy is plugged into both power and Ethernet. + #. Confirm that the Embassy is plugged into both power and Ethernet, with the USB drive in a USB 3.0 (blue) slot. #. Confirm the Embassy emitted two sounds when powering on: a bep and a chime. #. Confirm you are entering the correct product key. - #. Confirm your phone is not connected to a "Guest" network - #. Confirm your phone is not using a VPN. - #. Close and reopen the Setup App and try again. + #. Confirm your device you are using is not connected to a "Guest" network + #. Confirm your device is not using a VPN. + #. Try to refresh the ``embassy.local`` page. #. Rarely, certain routers do not support mDNS. Please see the "Advanced" tab. .. admonition:: Advanced @@ -65,12 +57,12 @@ Claim Your Embassy .. admonition:: Explanation :class: toggle expand - In this step, the Setup App will provide your Embassy with three pieces of critical information: + In this step, the setup process will provide your Embassy with three pieces of critical information: * A ed25519 private key. Used by the Embassy to create a .onion public address for encrypted and anonymous communication over Tor. * A 4096 bit RSA private key. Used by the Embassy to create a SSL certificate for encrypted communication over LAN. * A master password. Used by the Embassy to authenticate you as its owner. - + All three secrets are packaged together and transmitted to the Embassy encrypted with its product key. .. warning:: There is also currently no way to change your password. Choose a strong master password. Write it down. Store it somewhere safe. DO NOT LOSE IT. If you lose this password, you may be forced to reset the device, resulting in permanent loss of data. @@ -78,4 +70,4 @@ Claim Your Embassy Setup Complete! =============== -Your Embassy is now hosted on the private web. You can view and manage your Embassy by visiting its unique Tor Address from any Tor-enabled browser. The Setup App contains our recommendations for various devices. +Your Embassy is now hosted on the private web! After setup is complete you will be presented with connection information. You can view and manage your Embassy by visiting its unique Tor Address from any Tor-enabled browser, or by accessing it's ``.local`` address from your LAN.