From 0db020b9627b24fe8ef22099316d0e879e127f5f Mon Sep 17 00:00:00 2001 From: Michael Quigley Date: Fri, 23 Jun 2023 16:09:06 -0400 Subject: [PATCH] private sharing rewrite --- docs/core-features/sharing-private.md | 28 +++++++++++++-------------- 1 file changed, 13 insertions(+), 15 deletions(-) diff --git a/docs/core-features/sharing-private.md b/docs/core-features/sharing-private.md index a756e97d..0373d9d1 100644 --- a/docs/core-features/sharing-private.md +++ b/docs/core-features/sharing-private.md @@ -4,31 +4,29 @@ sidebar_position: 0 # Shares - Private `zrok` was built to share and access digital resources. A `private` share allows a resource to be -shared through a __privately__ available endpoint. Sharing a resource with `private` is __a differentiating__ -feature of `zrok`. +shared through a __privately__ available endpoint. Privately shared resources can only be accessed by another `zrok` user who has the details of your unique share. + +Sharing a resource with privately is one of the things that makes `zrok` unique. + +`zrok` also provides `public` sharing of resources with non-`zrok` users. Public resource sharing is limited to only resources that can be accessed over `HTTP` or `HTTPS`. + +Here's how private sharing works: # Peer to Peer ![zrok_public_share](../images/zrok_private_share.png) -A `private` share will require `zrok` to access the share and will also require a special shared -secret token. This access token, combined with the `zrok access` command will be how the private share is accessed. +`private` shares are accessed using the `zrok access` command, and require the accessing user to have a working (and `enable`-d) `zrok` account on the same service instance where the share was created. -Sharing something with `private` is similar to sharing something publicly. The main difference is -obvious, the shared resource is `private` and the share is __not__ open to the public. With `zrok`, you -can share resources on a private network without needing to expose the service to the internet. The share is not -through an obfuscated, difficult to guess url. Instead the sharing is accomplished using a secure, zero trust overlay -network provided by [OpenZiti](https://docs.openziti.io/docs/learn/introduction/). With this private, peer to peer -sharing model, there will never an attack surface available to the open internet. +The `private` share is identified by a _share token_, which uniquely identifies your share. The accessing user will use the share token, along with the `zrok access` command to create a local endpoint on their system, which let's them use the shared resource as if it were local to their system. + +`private` sharing does not require you to open any firewall ports or otherwise compromise the security of your local system; there is never an attack surface open to the public internet. The shared resource can be a development web server to share with friends and colleagues or perhaps, it could be a webhook from a server running in the cloud which has `zrok` running and has been instructed to `access` the private resource. What matters is that the access to the shared resource __should not__ be done in a public way, for more secure access. -Using `private` shares is easy and is accomplished using the `zrok share private` command. Run `zrok share private` -to see the usage output and to further learn how to use the command. +The peer-to-peer capabilities of `zrok` are an important property of the underlying [OpenZiti](https://docs.openziti.io/docs/learn/introduction/) network that `zrok` uses to provide connectivity between users and resources. -Unlike public shares, `private` shares do not need to be [reserved](./sharing-reserved.md) to be predictable. When sharing a -resource with `private`, the resource is shared at a known location. Resources shared with `private` do not -need to be `reserved`. \ No newline at end of file +Using `private` shares is easy and is accomplished using the `zrok share private` command. Run `zrok share private` to see the usage output and to further learn how to use the command. \ No newline at end of file