Skip to content

Commit

Permalink
docs(GITBOOK#184): Jen's Jan 31 changes - added 5 page descriptions
Browse files Browse the repository at this point in the history
  • Loading branch information
@jenmonroe @gitbook-bot
jenmonroe authored and gitbook-bot committed Feb 1, 2025
1 parent 800781a commit cc043c0
Show file tree
Hide file tree
Showing 5 changed files with 110 additions and 103 deletions.
3 changes: 3 additions & 0 deletions docs/installation/macos/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
---
icon: apple
description: >-
How to install NoPorts on macOS. Guides for desktop app, CLI, and device
installation.
---

# MacOS Installation Guides
Expand Down
1 change: 1 addition & 0 deletions docs/installation/quick-start-for-macos-and-windows.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
---
icon: forward
description: How to quickly install and use NoPorts on both macOS and Windows devices.
layout:
title:
visible: true
Expand Down
1 change: 1 addition & 0 deletions docs/installation/windows/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
---
icon: windows
description: This guide walks you through installing NoPorts on Windows machines.
---

# Windows Installation Guide
Expand Down
205 changes: 102 additions & 103 deletions docs/reference/underthehood.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
---
icon: engine
description: >-
This guide provides information on the technical aspects of NoPorts, including
its architecture, protocols, and security mechanisms.
---

# Under The Hood
Expand Down Expand Up @@ -51,15 +54,11 @@ This high-level flow is visualized in the diagrams below.
### Overview diagram

<div data-full-width="true">

<img src="../.gitbook/assets/atPlanes.png" alt="">

</div>
<div data-full-width="true"><img src="../.gitbook/assets/atPlanes.png" alt=""></div>

### Policy Plane

At any point the `sshnpd` or the `srvd` software rather than using a local configuration to manage access rights, can forward those questions to another atSign. That atSign can in turn pass those queries to a policy engine and reflect the answer back to the asking atSign. In the example above @relay and/or @server could ask if @client is allowed to access the service. This allows decisions to be made at the Policy plane level and provides operational segregation of duties.&#x20;
At any point the `sshnpd` or the `srvd` software rather than using a local configuration to manage access rights, can forward those questions to another atSign. That atSign can in turn pass those queries to a policy engine and reflect the answer back to the asking atSign. In the example above @relay and/or @server could ask if @client is allowed to access the service. This allows decisions to be made at the Policy plane level and provides operational segregation of duties.

### Control plane

Expand All @@ -68,99 +67,99 @@ In the following sequence diagram, atServer address lookup flows, authentication
Since the full details are provided in those other links, the `client_1 -> atServer_1 -> atServer_2 -> client_2` message flows are abbreviated to `@atSign_1 -> @atSign_2` in the sequence diagram. Thus, for example, `sshnp (@client)` encapsulates both the sshnp program and the sshnp atServer

```mermaid
sequenceDiagram
participant c as client
participant cs as client atServer
participant rs as relay atServer
participant r as relay
participant ds as daemon atServer
participant d as daemon
note over c,d: Phase - Background services startup
par
r ->> rs: connect
r ->> rs: pkam authenticate
r ->> rs: monitor for notifications
and
d ->> ds: connect
d ->> ds: pkam authenticate
d ->> ds: monitor for notifications
end
note over c,d: Phase - Ping daemon
c ->> cs: connect & pkam authenticate
c ->> cs: monitor for notifications
alt
c ->> d: ping the daemon
activate d
else actual data flow
c -->> cs:
cs -->> ds:
ds -->> d:
end
note over c,d: Phase - Request relay session
alt
c ->> r: request two public ports from relay: {session id, nonce from client}
else actual data flow
c -->> cs:
cs -->> rs:
rs -->> r:
end
r ->> r: Request ephemeral ports from OS
alt
r ->> c: ports response from relay: {session id, host1:port1, host2:port2, nonce from relay}
else actual data flow
r -->> rs:
rs -->> cs:
cs -->> c:
end
note over c,d: Phase - Receive ping response from daemon: {list of available features}
alt
d ->> c: ping response (device info / features) from daemon
deactivate d
else actual data flow
d -->> ds:
ds -->> cs:
cs -->> c:
end
c ->> c: Validate request against daemon ping info
note over c,d: Phase - Request daemon session
c ->> c: generate new aes encryption key & iv nonce
alt
c ->> d: send session request to the daemon: {host2:port2 from relay, aes stream encryption key, aes iv nonce, requested service to access (host:port), nonce from relay, nonce from client}
else actual data flow
c -->> cs:
cs -->> ds:
ds -->> d:
end
d ->> d: Verify perimissions for client's request (based on session request info - i.e. is client allowed to connect?)
d -x r: [TCP - A] Reverse TCP the requested service to open relay host2:port2
d -x r: [TCP - A] Send auth string (signed json payload of: session id, nonce from relay, nonce from client)
r ->> r: [TCP - A] Verify auth string
alt
d ->> c: session (success) response from daemon
else actual data flow
d -->> ds:
ds -->> cs:
cs -->> c:
end
note over c,d: Phase - Client TCP connect
c ->> c: Bind a local socket to expose the service on
c -x r: [TCP - B] TCP connect to the other open relay port
c -x r: [TCP - B] Send auth string (signed json payload of: session id, nonce from relay, nonce from client)
r ->> r: [TCP - B] Verify auth string
note over c,d: Phase - internal traffic relays (lasts entire duration of the session)
par
r -->> r: relay all traffic from [TCP - A] to [TCP - B] and vice-versa
and
c -->> c: relay all traffic from [TCP - A] to local socket and vice-versa
end
note over c,d: Phase - using the connection
sequenceDiagram
participant c as client
participant cs as client atServer
participant rs as relay atServer
participant r as relay
participant ds as daemon atServer
participant d as daemon
note over c,d: Phase - Background services startup
par
r ->> rs: connect
r ->> rs: pkam authenticate
r ->> rs: monitor for notifications
and
d ->> ds: connect
d ->> ds: pkam authenticate
d ->> ds: monitor for notifications
end
note over c,d: Phase - Ping daemon
c ->> cs: connect & pkam authenticate
c ->> cs: monitor for notifications
alt
c ->> d: ping the daemon
activate d
else actual data flow
c -->> cs:
cs -->> ds:
ds -->> d:
end
note over c,d: Phase - Request relay session
alt
c ->> r: request two public ports from relay: {session id, nonce from client}
else actual data flow
c -->> cs:
cs -->> rs:
rs -->> r:
end
r ->> r: Request ephemeral ports from OS
alt
r ->> c: ports response from relay: {session id, host1:port1, host2:port2, nonce from relay}
else actual data flow
r -->> rs:
rs -->> cs:
cs -->> c:
end
note over c,d: Phase - Receive ping response from daemon: {list of available features}
alt
d ->> c: ping response (device info / features) from daemon
deactivate d
else actual data flow
d -->> ds:
ds -->> cs:
cs -->> c:
end
c ->> c: Validate request against daemon ping info
note over c,d: Phase - Request daemon session
c ->> c: generate new aes encryption key & iv nonce
alt
c ->> d: send session request to the daemon: {host2:port2 from relay, aes stream encryption key, aes iv nonce, requested service to access (host:port), nonce from relay, nonce from client}
else actual data flow
c -->> cs:
cs -->> ds:
ds -->> d:
end
d ->> d: Verify perimissions for client's request (based on session request info - i.e. is client allowed to connect?)
d -x r: [TCP - A] Reverse TCP the requested service to open relay host2:port2
d -x r: [TCP - A] Send auth string (signed json payload of: session id, nonce from relay, nonce from client)
r ->> r: [TCP - A] Verify auth string
alt
d ->> c: session (success) response from daemon
else actual data flow
d -->> ds:
ds -->> cs:
cs -->> c:
end
note over c,d: Phase - Client TCP connect
c ->> c: Bind a local socket to expose the service on
c -x r: [TCP - B] TCP connect to the other open relay port
c -x r: [TCP - B] Send auth string (signed json payload of: session id, nonce from relay, nonce from client)
r ->> r: [TCP - B] Verify auth string
note over c,d: Phase - internal traffic relays (lasts entire duration of the session)
par
r -->> r: relay all traffic from [TCP - A] to [TCP - B] and vice-versa
and
c -->> c: relay all traffic from [TCP - A] to local socket and vice-versa
end
note over c,d: Phase - using the connection
c ->> c: You connect to the local socket as if it were the remote service!
```

Expand All @@ -171,7 +170,7 @@ Once the interactions above have completed
* the sshnpd nor the sshnp programs are no longer involved
* there is a new sshrv process running on the device host which pipes i/o between requested server:port and $rv\_host:$rv\_port\_1
* there is a client process running on the client host which provides the local port forwarding tunnel
* User may now type "ssh -p $local\_port username@localhost" or use a client application like and RDP client with traffic flowing
* User may now type "ssh -p $local\_port username@localhost" or use a client application like and RDP client with traffic flowing
* client ssh program <===>
* $client\_localhost:$local\_port <===> bridged by client-side ssh tunnel to
* $rv\_host:$rv\_port\_2 <===> bridged by sshrvd to
Expand All @@ -187,6 +186,6 @@ In the sections above, we referred to "authentication", "sending notifications"

Here are some links to detailed diagrams covering

* [how atClients authenticate to their atServers](https://github.com/atsign-foundation/at\_protocol/blob/trunk/decisions/2023-01-pkam-per-app-and-device.md#appendix---current-flows)
* [how encrypted data is exchanged](https://github.com/atsign-foundation/at\_protocol/blob/trunk/usage-examples/how-to-exchange-encrypted-data.md) (including how keys are exchanged)
* [how notifications work](https://github.com/atsign-foundation/at\_protocol/blob/trunk/usage-examples/how-notifications-work.md)
* [how atClients authenticate to their atServers](https://github.com/atsign-foundation/at_protocol/blob/trunk/decisions/2023-01-pkam-per-app-and-device.md#appendix---current-flows)
* [how encrypted data is exchanged](https://github.com/atsign-foundation/at_protocol/blob/trunk/usage-examples/how-to-exchange-encrypted-data.md) (including how keys are exchanged)
* [how notifications work](https://github.com/atsign-foundation/at_protocol/blob/trunk/usage-examples/how-notifications-work.md)
3 changes: 3 additions & 0 deletions docs/usage/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
---
icon: person-from-portal
description: >-
Learn how to use NoPorts. This guide covers some of the things you can run via
NoPorts, as well as how to set up the NoPorts Tunnel (npt).
---

# Usage
Expand Down

0 comments on commit cc043c0

Please sign in to comment.