From 7ef43db4d07683b16b57d6cf238c244d79015a25 Mon Sep 17 00:00:00 2001
From: Mrinal Wadhwa <mrinal@ockam.io>
Date: Mon, 12 Feb 2024 15:36:29 +0000
Subject: [PATCH] GITBOOK-1333: change request with no subject merged in
 GitBook

---
 how-does-ockam-work.md               | 16 ++++++++--------
 portals/databases/README.md          |  2 +-
 portals/databases/postgres/README.md |  2 +-
 portals/databases/postgres/docker.md |  8 ++++----
 4 files changed, 14 insertions(+), 14 deletions(-)

diff --git a/how-does-ockam-work.md b/how-does-ockam-work.md
index 493c999e..e418bcbe 100644
--- a/how-does-ockam-work.md
+++ b/how-does-ockam-work.md
@@ -41,7 +41,7 @@ ockam enroll
 
 The first step is to install Ockam Command and enroll. The commands below can be run in a production setup with two machines in two different networks or in a dev environment on a single machine. If you’re doing this on two machines, install and enroll on both machines.
 
-The enroll command creates a new [vault](reference/protocols/keys.md) and generates a cryptographic [<mark style="color:blue;">identity</mark>](reference/protocols/identities.md) with private keys stored in that vault. It then guides you to sign in to Ockam Orchestrator.
+The enroll command creates a new [<mark style="color:blue;">vault</mark>](reference/protocols/keys.md) and generates a cryptographic [<mark style="color:blue;">identity</mark>](reference/protocols/identities.md) with private keys stored in that vault. It then guides you to sign in to Ockam Orchestrator.
 
 If this is your first time signing in, the Orchestrator creates a new dedicated project for you. A project offers two services: a membership [<mark style="color:blue;">authority</mark>](reference/protocols/identities.md#credentials) and a [<mark style="color:blue;">relay</mark>](reference/protocols/routing.md#relay) service.
 
@@ -68,11 +68,11 @@ When this outlet receives messages from corresponding inlets, it unwraps all [<m
 
 Next, create a relay in your project at address: _postgres_.
 
-This command first creates an outgoing tcp connection from inside Bank Corp. to your project. It then creates a [secure channel](reference/protocols/secure-channels.md) to your project over this tcp connection. This succeeds because Bank Corp’s network allows outgoing tcp connections to the Internet, and your Orchestrator project’s secure channel listener allows channels with project members.
+This command first creates an outgoing tcp connection from inside Bank Corp. to your project. It then creates a [<mark style="color:blue;">secure channel</mark>](reference/protocols/secure-channels.md) to your project over this tcp connection. This succeeds because Bank Corp’s network allows outgoing tcp connections to the Internet, and your Orchestrator project’s secure channel listener allows channels with project members.
 
 Over this secure channel, the command then asks the relay service to create a [<mark style="color:blue;">relay</mark>](reference/protocols/routing.md#relay) at address: _postgres_. The relay is created because the [<mark style="color:blue;">access control</mark>](reference/protocols/access-controls.md) on the relay service allows authenticated project administrators to create relays at any address. When this relay receives messages, it routes them to the outlet node through the previously created secure channel and underlying tcp connection.
 
-The default [access control](reference/protocols/access-controls.md) on the outlet and the relay only allow messages from project members who have authenticated through a secure channel by presenting a [<mark style="color:blue;">credential</mark>](reference/protocols/identities.md#credentials) from the project membership authority that attests their [<mark style="color:blue;">identifier</mark>](reference/protocols/identities.md#identities) is a member of the project.
+The default [<mark style="color:blue;">access control</mark>](reference/protocols/access-controls.md) on the outlet and the relay only allow messages from project members who have authenticated through a secure channel by presenting a [<mark style="color:blue;">credential</mark>](reference/protocols/identities.md#credentials) from the project membership authority that attests their [<mark style="color:blue;">identifier</mark>](reference/protocols/identities.md#identities) is a member of the project.
 
 <div data-full-width="true">
 
@@ -88,11 +88,11 @@ ockam tcp-inlet create --from 15432 --to postgres
 
 In Analysis Corp.’s Azure VNet, on the machine that has the postgres client, create a tcp portal inlet.
 
-The inlet first creates a tcp listener on localhost port _15432_. It then creates an outgoing tcp connection from inside Analysis Corp. to your project. Next, it creates a [secure channel](reference/protocols/secure-channels.md) to your project over this tcp connection. Finally, it creates an end-to-end secure channel to the outlet node in Bank Corp. through the relay in your project at address: _postgres._
+The inlet first creates a tcp listener on localhost port _15432_. It then creates an outgoing tcp connection from inside Analysis Corp. to your project. Next, it creates a [<mark style="color:blue;">secure channel</mark>](reference/protocols/secure-channels.md) to your project over this tcp connection. Finally, it creates an end-to-end secure channel to the outlet node in Bank Corp. through the relay in your project at address: _postgres._
 
 Over this end-to-end secure channel the inlet creates a **portal** with the outlet.
 
-All secure channels are mutually authenticated and all messages are checked for authorization. The default [access control](reference/protocols/access-controls.md) on the inlet only allows messages from project members who have authenticated through a secure channel by presenting a [<mark style="color:blue;">credential</mark>](reference/protocols/identities.md#credentials) from the project membership authority that attests their [<mark style="color:blue;">identifier</mark>](reference/protocols/identities.md#identities) is a member of the project.
+All secure channels are mutually authenticated and all messages are checked for authorization. The default [<mark style="color:blue;">access control</mark>](reference/protocols/access-controls.md) on the inlet only allows messages from project members who have authenticated through a secure channel by presenting a [<mark style="color:blue;">credential</mark>](reference/protocols/identities.md#credentials) from the project membership authority that attests their [<mark style="color:blue;">identifier</mark>](reference/protocols/identities.md#identities) is a member of the project.
 
 <div data-full-width="true">
 
@@ -108,9 +108,9 @@ psql --host localhost --port 15432
 
 In Analysis Corp.’s Azure VNet, connect with the **virtually adjacent** postgres on _localhost:15432_.
 
-When a tcp connection is created with this inlet at _localhost:15432,_ it wraps tcp segments in [routing](reference/protocols/routing.md) messages and sends them through the portal. Messages are encrypted inside Analysis Corp. and decrypted only when they are inside Bank Corp. The outlet in Bank Corp. unwraps routing information and sends raw tcp segments to the tcp server.
+When a tcp connection is created with this inlet at _localhost:15432,_ it wraps tcp segments in [<mark style="color:blue;">routing</mark>](reference/protocols/routing.md) messages and sends them through the portal. Messages are encrypted inside Analysis Corp. and decrypted only when they are inside Bank Corp. The outlet in Bank Corp. unwraps routing information and sends raw tcp segments to the tcp server.
 
-The outlet sends response segments from the tcp server back through the portal. Response messages are encrypted inside Bank Corp. and decrypted only when they are inside Analysis Corp. The inlet unwraps all [routing](reference/protocols/routing.md) information and sends raw tcp response segments to the tcp client.
+The outlet sends response segments from the tcp server back through the portal. Response messages are encrypted inside Bank Corp. and decrypted only when they are inside Analysis Corp. The inlet unwraps all [<mark style="color:blue;">routing</mark>](reference/protocols/routing.md) information and sends raw tcp response segments to the tcp client.
 
 <div data-full-width="true">
 
@@ -126,7 +126,7 @@ We ran a few simple commands to securely connect with a micro-service in another
 
 In this example, we used a postgres server and client. However, the same commands work for any tcp server and client, such as an http server serving an api built with express or django. We have to adjust some port numbers, but other than that, the tcp server and client remain unchanged. Ockam runs as a companion next to the server and its clients.
 
-Sensitive business data in the postgres database is only accessible to Bank Corp. and  Analysis Corp. All data is [encrypted](reference/protocols/secure-channels.md) with strong forward secrecy as it moves through the Internet. The communication channel is [<mark style="color:blue;">mutually authenticated</mark>](reference/protocols/secure-channels.md) and [<mark style="color:blue;">authorized</mark>](reference/protocols/access-controls.md). Keys and credentials are automatically rotated. Access to connect with postgres can be easily revoked.
+Sensitive business data in the postgres database is only accessible to Bank Corp. and  Analysis Corp. All data is [<mark style="color:blue;">encrypted</mark>](reference/protocols/secure-channels.md) with strong forward secrecy as it moves through the Internet. The communication channel is [<mark style="color:blue;">mutually authenticated</mark>](reference/protocols/secure-channels.md) and [<mark style="color:blue;">authorized</mark>](reference/protocols/access-controls.md). Keys and credentials are automatically rotated. Access to connect with postgres can be easily revoked.
 
 Analysis Corp. does not get unfettered access to Bank Corp.’s network. It gets access only to run queries on the postgres server. Bank Corp. does not get unfettered access to Analysis Corp.’s network. It gets access only to respond to queries over a tcp connection. Bank Corp. cannot initiate connections.
 
diff --git a/portals/databases/README.md b/portals/databases/README.md
index 905ec353..0d31b447 100644
--- a/portals/databases/README.md
+++ b/portals/databases/README.md
@@ -14,7 +14,7 @@ layout:
 
 # Databases
 
-This section contains hands-on examples that use [Ockam](../../) to create **encrypted portals** to various databases running in various environments.
+This section contains hands-on examples that use [<mark style="color:blue;">Ockam</mark>](../../) to create **encrypted portals** to various databases running in various environments.
 
 In each example, we connect a nodejs app in one private network with a database in another private network. To understand how end-to-end trust is established, and how the portal works even though the two networks are isolated with no exposed ports, please read: “[<mark style="color:blue;">How does Ockam work?</mark>](../../how-does-ockam-work.md)”
 
diff --git a/portals/databases/postgres/README.md b/portals/databases/postgres/README.md
index 8e04488b..111ea4e9 100644
--- a/portals/databases/postgres/README.md
+++ b/portals/databases/postgres/README.md
@@ -14,7 +14,7 @@ layout:
 
 # PostgreSQL
 
-This section contains hands-on examples that use [Ockam](../../../) to create **encrypted portals** to postgres database running in various environments.
+This section contains hands-on examples that use [<mark style="color:blue;">Ockam</mark>](../../../) to create **encrypted portals** to postgres database running in various environments.
 
 In each example, we connect a nodejs app in one private network with a postgres database in another private network.  To understand how end-to-end trust is established, and how the portal works even though the two networks are isolated with no exposed ports, please read: “[<mark style="color:blue;">How does Ockam work?</mark>](../../../how-does-ockam-work.md)”
 
diff --git a/portals/databases/postgres/docker.md b/portals/databases/postgres/docker.md
index d69f50a7..c757b0e1 100644
--- a/portals/databases/postgres/docker.md
+++ b/portals/databases/postgres/docker.md
@@ -75,12 +75,12 @@ networks:
     driver: bridge
 ```
 
-* Analysis Corp.’s [<mark style="color:blue;">docker-compose configuration</mark>](https://github.com/build-trust/ockam/blob/develop/examples/command/portals/databases/postgres/docker/analysis\_corp/docker-compose.yml) is used when run.sh invokes docker-compose. It creates an [<mark style="color:blue;">isolated virtual network</mark>](https://github.com/build-trust/ockam/blob/develop/examples/command/portals/databases/postgres/docker/analysis\_corp/docker-compose.yml#L3-L6) for Analysis Corp. In this network, docker compose starts an [Ockam node container](https://github.com/build-trust/ockam/blob/develop/examples/command/portals/databases/postgres/docker/analysis\_corp/docker-compose.yml#L9-L20) and an [<mark style="color:blue;">app container</mark>](https://github.com/build-trust/ockam/blob/develop/examples/command/portals/databases/postgres/docker/analysis\_corp/docker-compose.yml#L22-L32).
+* Analysis Corp.’s [<mark style="color:blue;">docker-compose configuration</mark>](https://github.com/build-trust/ockam/blob/develop/examples/command/portals/databases/postgres/docker/analysis\_corp/docker-compose.yml) is used when run.sh invokes docker-compose. It creates an [<mark style="color:blue;">isolated virtual network</mark>](https://github.com/build-trust/ockam/blob/develop/examples/command/portals/databases/postgres/docker/analysis\_corp/docker-compose.yml#L3-L6) for Analysis Corp. In this network, docker compose starts an [<mark style="color:blue;">Ockam node container</mark>](https://github.com/build-trust/ockam/blob/develop/examples/command/portals/databases/postgres/docker/analysis\_corp/docker-compose.yml#L9-L20) and an [<mark style="color:blue;">app container</mark>](https://github.com/build-trust/ockam/blob/develop/examples/command/portals/databases/postgres/docker/analysis\_corp/docker-compose.yml#L22-L32).
 * The [<mark style="color:blue;">Ockam node container</mark>](https://github.com/build-trust/ockam/blob/develop/examples/command/portals/databases/postgres/docker/analysis\_corp/docker-compose.yml#L9-L20) is created using [<mark style="color:blue;">this dockerfile</mark>](https://github.com/build-trust/ockam/blob/develop/examples/command/portals/databases/postgres/docker/ockam.dockerfile) and this [<mark style="color:blue;">entrypoint script</mark>](https://github.com/build-trust/ockam/blob/develop/examples/command/portals/databases/postgres/docker/analysis\_corp/run\_ockam.sh). The enrollment ticket from run.sh is [<mark style="color:blue;">passed to the container</mark>](https://github.com/build-trust/ockam/blob/develop/examples/command/portals/databases/postgres/docker/analysis\_corp/docker-compose.yml#L18).
 * When the Ockam node container starts in the Analysis Corp network, it runs [<mark style="color:blue;">its entrypoint</mark>](https://github.com/build-trust/ockam/blob/develop/examples/command/portals/databases/postgres/docker/analysis\_corp/run\_ockam.sh)<mark style="color:blue;">.</mark> The entrypoint script creates a new identity and uses the enrollment ticket to [<mark style="color:blue;">enroll with your project</mark> ](https://github.com/build-trust/ockam/blob/develop/examples/command/portals/databases/postgres/docker/analysis\_corp/run\_ockam.sh#L6-L19)and get a project membership credential that attests to the attribute <mark style="background-color:yellow;">postgres-inlet=true.</mark> The run function [<mark style="color:blue;">assigned this attribute</mark>](https://github.com/build-trust/ockam/blob/develop/examples/command/portals/databases/postgres/docker/run.sh#L41-L48) to the enrollment ticket.
 * The entrypoint script then [<mark style="color:blue;">creates a node that uses</mark>](https://github.com/build-trust/ockam/blob/develop/examples/command/portals/databases/postgres/docker/analysis\_corp/run\_ockam.sh#L21-L30) this identity and membership credential. It then sets an [<mark style="color:blue;">access control policy</mark>](https://github.com/build-trust/ockam/blob/develop/examples/command/portals/databases/postgres/docker/analysis\_corp/run\_ockam.sh#L29C55-L29C91) that only allows project members that possesses a credential with attribute <mark style="background-color:yellow;">postgres-outlet="true"</mark> to connect to tcp portal inlets on this node.
 * Next, the entrypoint [<mark style="color:blue;">creates tcp portal</mark>](https://github.com/build-trust/ockam/blob/develop/examples/command/portals/databases/postgres/docker/analysis\_corp/run\_ockam.sh#L30) inlet that makes the [<mark style="color:blue;">remote postgres</mark>](https://github.com/build-trust/ockam/blob/develop/examples/command/portals/databases/postgres/docker/analysis\_corp/run\_ockam.sh#L30C50-L30C58) available on all localhost IPs at [<mark style="color:blue;">0.0.0.0:15432</mark>](https://github.com/build-trust/ockam/blob/develop/examples/command/portals/databases/postgres/docker/analysis\_corp/run\_ockam.sh#L30C31-L30C44). This makes postgres available at <mark style="background-color:yellow;">ockam:15432</mark> within Analysis Corp’s virtual private network.
-* Once the Ockam node container [<mark style="color:blue;">is ready</mark>](https://github.com/build-trust/ockam/blob/develop/examples/command/portals/databases/postgres/docker/analysis\_corp/docker-compose.yml#L27), docker compose starts [an app container](https://github.com/build-trust/ockam/blob/develop/examples/command/portals/databases/postgres/docker/analysis\_corp/docker-compose.yml#L22-L32). The app container is created using [<mark style="color:blue;">this dockerfile</mark>](https://github.com/build-trust/ockam/blob/develop/examples/command/portals/databases/postgres/docker/analysis\_corp/app.dockerfile) which runs this [<mark style="color:blue;">app.js</mark>](https://github.com/build-trust/ockam/blob/develop/examples/command/portals/databases/postgres/docker/analysis\_corp/app.js) file on startup.
+* Once the Ockam node container [<mark style="color:blue;">is ready</mark>](https://github.com/build-trust/ockam/blob/develop/examples/command/portals/databases/postgres/docker/analysis\_corp/docker-compose.yml#L27), docker compose starts [<mark style="color:blue;">an app container</mark>](https://github.com/build-trust/ockam/blob/develop/examples/command/portals/databases/postgres/docker/analysis\_corp/docker-compose.yml#L22-L32). The app container is created using [<mark style="color:blue;">this dockerfile</mark>](https://github.com/build-trust/ockam/blob/develop/examples/command/portals/databases/postgres/docker/analysis\_corp/app.dockerfile) which runs this [<mark style="color:blue;">app.js</mark>](https://github.com/build-trust/ockam/blob/develop/examples/command/portals/databases/postgres/docker/analysis\_corp/app.js) file on startup.
 * The app.js file is a nodejs app, it [<mark style="color:blue;">connects with postgres</mark>](https://github.com/build-trust/ockam/blob/develop/examples/command/portals/databases/postgres/docker/analysis\_corp/app.js#L3-L27) on <mark style="background-color:yellow;">ockam:15432</mark>, then [<mark style="color:blue;">creates a table</mark>](https://github.com/build-trust/ockam/blob/develop/examples/command/portals/databases/postgres/docker/analysis\_corp/app.js#L41-L42) in the database, [<mark style="color:blue;">inserts some data</mark>](https://github.com/build-trust/ockam/blob/develop/examples/command/portals/databases/postgres/docker/analysis\_corp/app.js#L44-L48) into the table, [<mark style="color:blue;">queries it</mark>](https://github.com/build-trust/ockam/blob/develop/examples/command/portals/databases/postgres/docker/analysis\_corp/app.js#L50-L51) back, and [<mark style="color:blue;">prints it</mark>](https://github.com/build-trust/ockam/blob/develop/examples/command/portals/databases/postgres/docker/analysis\_corp/app.js#L52).
 
 ## Recap
@@ -89,9 +89,9 @@ networks:
 
 We connected a nodejs app in one virtual private network with a postgres database in another virtual private network over an end-to-end encrypted portal.
 
-Sensitive business data in the postgres database is only accessible to Bank Corp. and  Analysis Corp. All data is [encrypted](../../../reference/protocols/secure-channels.md) with strong forward secrecy as it moves through the Internet. The communication channel is [<mark style="color:blue;">mutually authenticated</mark>](../../../reference/protocols/secure-channels.md) and [<mark style="color:blue;">authorized</mark>](../../../reference/protocols/access-controls.md). Keys and credentials are automatically rotated. Access to connect with postgres can be easily revoked.
+Sensitive business data in the postgres database is only accessible to Bank Corp. and Analysis Corp. All data is [<mark style="color:blue;">encrypted</mark>](../../../reference/protocols/secure-channels.md) with strong forward secrecy as it moves through the Internet. The communication channel is [<mark style="color:blue;">mutually authenticated</mark>](../../../reference/protocols/secure-channels.md) and [<mark style="color:blue;">authorized</mark>](../../../reference/protocols/access-controls.md). Keys and credentials are automatically rotated. Access to connect with postgres can be easily revoked.
 
-Analysis Corp. does not get unfettered access to Bank Corp.’s network. It gets access only to run queries on the postgres server. Bank Corp. does not get unfettered access to Analysis Corp.’s network. It gets access only to respond to queries over a tcp connection. Bank Corp. cannot initiate connections.&#x20;
+Analysis Corp. does not get unfettered access to Bank Corp.’s network. It gets access only to run queries on the postgres server. Bank Corp. does not get unfettered access to Analysis Corp.’s network. It gets access only to respond to queries over a tcp connection. Bank Corp. cannot initiate connections.
 
 All [<mark style="color:blue;">access controls</mark>](../../../reference/protocols/access-controls.md) are secure-by-default. Only project members, with valid credentials, can connect with each other. NAT’s are traversed using a relay and outgoing tcp connections. Bank Corp. or Analysis Corp. don’t expose any listening endpoints on the Internet. Their networks are completely closed and protected from any attacks from the Internet.