Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: fix typos #8612

Open
wants to merge 6 commits into
base: develop
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,7 @@ ockam relay create
# connections, and where it should forward that traffic to.
ockam tcp-inlet create --from 7000

# Access the application service, that may be in a remote private network though
# Access the application service, that may be in a remote private network through
# the end-to-end encrypted secure channel, via your private and encrypted cloud relay.
curl --head 127.0.0.1:7000
```
Expand Down
8 changes: 4 additions & 4 deletions examples/app/portals/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -156,9 +156,9 @@ If you're interested in contributing to the app's Swift or Rust code, we add new

Let's take a step by step look at how a TCP service, running on your Mac, becomes securely accessible on localhost, on your friend's Mac.

1. On first launch, the Portals app, asks you to Enroll with Ockam Orchestrator. You click the Enroll button and it starts the _OAuth 2.0 Authorization Code Flow with PKCE_ with `https://account.ockam.io`. You then signup / login with your GitHub username or email address. When the OAuth flow completes, the app receives an `access_token`. It use that token to query your account information from `https://account.ockam.io`. During this process we may send you an email to verify your email address.
1. On first launch, the Portals app, asks you to Enroll with Ockam Orchestrator. You click the Enroll button and it starts the _OAuth 2.0 Authorization Code Flow with PKCE_ with `https://account.ockam.io`. You then signup / login with your GitHub username or email address. When the OAuth flow completes, the app receives an `access_token`. It uses that token to query your account information from `https://account.ockam.io`. During this process we may send you an email to verify your email address.

1. The app generates a unique [Ockam Identity](https://docs.ockam.io/reference/protocols/identities#identities), with its secret keys in an [Ockam Vault](https://docs.ockam.io/reference/protocols/keys) stored on disk. Ockam Identities are cryptographically verifiable digital identities. Each Identity maintains one or more secret keys and has a unique Identifier. It's possible to use Vaults that store secrets in Apple Keychain, Secure Enclave, Yubikey, 1Password etc. If that's interesting, [please tell us](https://discord.ockam.io) so we know which ones to prioritize in our plans. Vaults are pluggable and really simple to build. Ockam Vault in [AWS KMS](https://github.com/build-trust/ockam/tree/develop/implementations/rust/ockam/ockam_vault_aws) is a good example to learn how to build one. We'd love to [help you](https://discord.ockam.io/) contribute a [Vault](https://docs.ockam.io/reference/protocols/keys) implementation for you favorite place to store secrets.
1. The app generates a unique [Ockam Identity](https://docs.ockam.io/reference/protocols/identities#identities), with its secret keys in an [Ockam Vault](https://docs.ockam.io/reference/protocols/keys) stored on disk. Ockam Identities are cryptographically verifiable digital identities. Each Identity maintains one or more secret keys and has a unique Identifier. It's possible to use Vaults that store secrets in Apple Keychain, Secure Enclave, Yubikey, 1Password etc. If that's interesting, [please tell us](https://discord.ockam.io) so we know which ones to prioritize in our plans. Vaults are pluggable and really simple to build. Ockam Vault in [AWS KMS](https://github.com/build-trust/ockam/tree/develop/implementations/rust/ockam/ockam_vault_aws) is a good example to learn how to build one. We'd love to [help you](https://discord.ockam.io/) contribute a [Vault](https://docs.ockam.io/reference/protocols/keys) implementation for your favorite place to store secrets.

1. Next, the app establishes a mutually authenticated [Secure Channel](https://docs.ockam.io/reference/protocols/secure-channels) with Ockam Orchestrator's Controller. At compile-time, the app, was hardcoded with the Ockam [Identifier](https://docs.ockam.io/reference/protocols/identities#identities) and [Route](https://docs.ockam.io/reference/protocols/routing) to the Controller. The app sends the OAuth `access_token` to the Controller over this secure channel. The Controller uses that token to independently query your account information from `https://account.ockam.io`.

Expand All @@ -172,15 +172,15 @@ Let's take a step by step look at how a TCP service, running on your Mac, become

1. Your invited friend experiences steps 1-5 above. They generate their own Identity and get a dedicated Orchestrator Space. Their app fetches all their Invitations from the Orchestrator's Controller. Included in that list is the Invitation from you. If they accept this Invitation, their Portals app uses the included Enrollment Ticket to create a Secure Channel with your Project's Credential Authority and exchange it for a Credential that ties their Identity with their verified email address and project membership.

1. Your friend's app, its Ockam Identity, is from this point a member of your Project in Ockam Orchestrator. It knows the Route to your Outlet through your Relay in you Project Node. It also possesses a Credential to authenticate their attributes (email address and project membership) to the Project Node and to your Portals app Node. Their app creates an outgoing TCP connection with your Project Node and sets up a authenticated secure channel to get access to your Relay. It then creates an end-to-end encrypted, mutually authenticated secure channel, via your Relay to your Portals app.
1. Your friend's app, its Ockam Identity, is from this point a member of your Project in Ockam Orchestrator. It knows the Route to your Outlet through your Relay in your Project Node. It also possesses a Credential to authenticate their attributes (email address and project membership) to the Project Node and to your Portals app Node. Their app creates an outgoing TCP connection with your Project Node and sets up a authenticated secure channel to get access to your Relay. It then creates an end-to-end encrypted, mutually authenticated secure channel, via your Relay to your Portals app.

1. Finally, your friend's app starts a TCP Inlet listener on `127.0.0.1`. The Inlet [Worker](https://docs.ockam.io/reference/protocols/nodes) in _their_ app runs the portal protocol with the Outlet worker in _your_ app. This Portal is established over the end-to-end encrypted Secure Channel. The Inlet enforces an access control policy that requires that the Outlet must present an Identity that is a member of your Project and associated with the email address that sent the invitation. TCP segments received at the Inlet's TCP listener are wrapped in Ockam Routing messages and sent through the end-to-end Secure Channel which encrypts them. In your app node, at the other end of the secure channel, the messages are decrypted and routed to the Outlet. All routing information is removed and raw TCP segments are sent to your TCP service.

#### NAT traversal

In the steps above you'll notice that neither ends of the Portal expose any listening TCP servers on the Internet. Both sides make an outgoing TCP connection to the Node that offers the Relay service. This approach allows Portals to traverse NATs without any change to networks or infrastructure. Relays are highly reliable and always work if the two private networks allow outgoing connections to the Internet. This reliability, however, comes with a tradeoff - end-to-end encrypted data must travel through the relay.

[Ockam Routing](https://docs.ockam.io/reference/protocols/routing) allows us to establish end-to-end secure channels over all sorts of routing topologies. An alternative to Relays (which are simular to TURN) is to use a Rendezvous (which is similar to STUN). In this approach a Rendezvous service is used for puncturing through NATs. It has the advantage that the encrypted data no longer needs to travel through a relay. However, it also has the disadvantage of being unreliable. Puncturing through NATs doesn't always work because of the large variety of network routers and differences in how they implement network address translation. Various research papers suggest a success rate between 70 to 80 percent.
[Ockam Routing](https://docs.ockam.io/reference/protocols/routing) allows us to establish end-to-end secure channels over all sorts of routing topologies. An alternative to Relays (which are similar to TURN) is to use a Rendezvous (which is similar to STUN). In this approach a Rendezvous service is used for puncturing through NATs. It has the advantage that the encrypted data no longer needs to travel through a relay. However, it also has the disadvantage of being unreliable. Puncturing through NATs doesn't always work because of the large variety of network routers and differences in how they implement network address translation. Various research papers suggest a success rate between 70 to 80 percent.

A good compromise, we think, would be to combine the two approaches. Try to use a Rendezvous and if it doesn't work failover to using a Relay. Here are a couple of examples of using Rendezvous with Ockam Routing: [in Rust](https://github.com/build-trust/ockam/blob/develop/implementations/rust/ockam/ockam_transport_udp/examples/puncher.rs), and [in Elixir](https://github.com/build-trust/ockam/pull/6588). The Portals app doesn't support Rendezvous yet. If you're interested in that functionality [please tell us](https://discord.ockam.io) about it so we know to prioritize it in our plans.

Expand Down
2 changes: 1 addition & 1 deletion examples/rust/file_transfer/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ This Rust project shows how to create workers on different nodes to handle file

- `examples/receiver.rs` creates a node to receive files
- it opens a secure channel listener
- it creates a relay to so that files can be transferred without the node being exposed on a public network
- it creates a relay so that files can be transferred without the node being exposed on a public network

- `examples/sender.rs` creates a node to send files
- it connects to the relay
Expand Down
2 changes: 1 addition & 1 deletion examples/rust/mitm_node/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@

In my case `SecureChannel.initiator.decryptor.remote_36` Address was reachable, since this is the Secure Channel using the TCP connection we intercepted, but messages to this worker are checked cryptographically.

Also `TcpSendWorker_tx_addr_responder_62` and `TcpRecvProcessor_responder_64` were not found since it's the TCP connection used to handle `ockam worker list` command and it's termninated immediately after you see the result in the command line.
Also `TcpSendWorker_tx_addr_responder_62` and `TcpRecvProcessor_responder_64` were not found since it's the TCP connection used to handle `ockam worker list` command and it's terminated immediately after you see the result in the command line.

1. Don't forget to clean your `/etc/hosts`

Expand Down
4 changes: 2 additions & 2 deletions implementations/elixir/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -90,7 +90,7 @@ It is also possible to just execute one test by specifying to function line numb
mix test test/ockam/identity_test.exs:19
```

This is particularly useful when a test fail because you can just copy and paste the file name and line number from
This is particularly useful when a test fails because you can just copy and paste the file name and line number from
the test failure.

## Documentation
Expand All @@ -100,7 +100,7 @@ The documentation for a given package can be generated with:
mix docs
```

The generated documented can be opened in a browser with:
The generated documentation can be opened in a browser with:
```
open _build/docs/index.html
```
Expand Down
4 changes: 2 additions & 2 deletions tools/stress-test/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@ Sample output:
| In-fli | Messages in flight, sent but not yet received |
| B. sent | Total amount of bytes sent |
| B. recv | Total amount of bytes received |
| Spe. sent | Avarage outgoing speed of the last 10 seconds, in bits per second |
| Spe. recv | Avarage incoming speed of the last 10 seconds, in bits per second |
| Spe. sent | Average outgoing speed of the last 10 seconds, in bits per second |
| Spe. recv | Average incoming speed of the last 10 seconds, in bits per second |
| M. OOO | Messages out of order, it can also detect a lost packet if the following packet is received |
| Errors | Number of errors during relay or portal creation |