From c02a7b7edfd36de25e031e33095f912419ea3e9a Mon Sep 17 00:00:00 2001 From: HifiExperiments Date: Fri, 12 Apr 2024 21:42:10 -0700 Subject: [PATCH] wip asset security docs page - discuss! --- source/create/avatars/create-avatars.rst | 2 +- source/create/avatars/find-avatars.rst | 4 +- source/host/add-content/create-content.rst | 24 +++--- .../permission-settings.rst | 32 ++++---- source/security.rst | 1 + source/security/asset-security.rst | 77 +++++++++++++++++++ 6 files changed, 107 insertions(+), 33 deletions(-) create mode 100644 source/security/asset-security.rst diff --git a/source/create/avatars/create-avatars.rst b/source/create/avatars/create-avatars.rst index ff4460b2..3403d90c 100755 --- a/source/create/avatars/create-avatars.rst +++ b/source/create/avatars/create-avatars.rst @@ -14,7 +14,7 @@ There are three ways to get your own avatar. You can either: .. note:: If you get an avatar from an external source such as TurboSquid, CGTrader, MakeHuman, or VRoid Studio, it is likely that the skeleton does not match our :doc:`avatar standards `. To use these avatars with Overte, use the `Overte Avatar Exporter for Unity `_ to correctly map the skeleton and package your avatar. -If you want to create an avatar from scratch, this page covers the steps needed to create, rig, and package your avatar. +If you want to create an avatar from scratch, this page covers the steps needed to create, rig, and package your avatar. Learn more about the `security of your assets <../../security/asset-security.html>`_. .. contents:: On This Page :depth: 2 diff --git a/source/create/avatars/find-avatars.rst b/source/create/avatars/find-avatars.rst index 983ac92d..8f1f5495 100755 --- a/source/create/avatars/find-avatars.rst +++ b/source/create/avatars/find-avatars.rst @@ -6,7 +6,7 @@ Find and Use an Existing Avatar ############################### -You can download avatars for use from external sources such as TurboSquid or CGTrader. Once you get the avatar, you will need to process it in Unity using the Overte Avatar Exporter. This tool imports most avatars into Unity, maps their skeleton using Unity's humanoid tool, and exports them as FST and FBX files to import in-world. +You can download avatars for use from external sources such as TurboSquid or CGTrader. Once you get the avatar, you will need to process it in Unity using the Overte Avatar Exporter. This tool imports most avatars into Unity, maps their skeleton using Unity's humanoid tool, and exports them as FST and FBX files to import in-world. Learn more about the `security of your assets <../../security/asset-security.html>`_. .. contents:: On This Page :depth: 3 @@ -50,7 +50,7 @@ Install the Avatar Exporter You need to install the extension for every Unity project that you have. Keep in mind, however, that you can import and export multiple avatars in a single Unity project. -1. Download the `avatar exporter `_ from Overte. +1. Download the `avatar exporter `_ from Overte. 2. In Unity, open the 'Project' window at the bottom. .. image:: _images/project-window.png diff --git a/source/host/add-content/create-content.rst b/source/host/add-content/create-content.rst index c496401e..dba66366 100755 --- a/source/host/add-content/create-content.rst +++ b/source/host/add-content/create-content.rst @@ -6,16 +6,16 @@ Build and Add Your Own Content ############################## -Maybe you've wandered around the metaverse, and you're inspired by the creativity of others. Or maybe none of the other domains really fit the atmosphere of what you have in mind. Whatever the reason, you're ready to branch out and build content of your own. If you don't know where to begin, this is a great place to start. +Maybe you've wandered around the metaverse, and you're inspired by the creativity of others. Or maybe none of the other domains really fit the atmosphere of what you have in mind. Whatever the reason, you're ready to branch out and build content of your own. If you don't know where to begin, this is a great place to start. Learn more about the `security of your assets <../../security/asset-security.html>`_. .. contents:: On This Page :depth: 2 -------------------------- -Tools for Creating Content +Tools for Creating Content -------------------------- -A content set is simply a collection of many different entities, models and scripts working together to form an interactive environment. Visit our :doc:`Create <../../create>` section to learn more about the available tools and examples of how to make your environment more alive: +A content set is simply a collection of many different entities, models and scripts working together to form an interactive environment. Visit our :doc:`Create <../../create>` section to learn more about the available tools and examples of how to make your environment more alive: * :doc:`Create Tools <../../create/tools>` * :doc:`All About Entities <../../create/entities>` @@ -27,7 +27,7 @@ A content set is simply a collection of many different entities, models and scri Techniques for Creating Content Sets ------------------------------------ -Creating a content set can be complicated because you're designing an entire environment, rather than one single item. Its like building an entire city, which is comprised of many buildings, trees and roads. Some artists want to share their progress, each step along the way. Others want to wait to show off their creation until the final build is complete. +Creating a content set can be complicated because you're designing an entire environment, rather than one single item. Its like building an entire city, which is comprised of many buildings, trees and roads. Some artists want to share their progress, each step along the way. Others want to wait to show off their creation until the final build is complete. We let you choose how you want to build and deploy your content. The process for updating the content set on your domain will differ based on the approach you use to build your content. Choose the method that fits you best to learn more: @@ -35,7 +35,7 @@ We let you choose how you want to build and deploy your content. The process for | Method | Description | +========================+======================================================================================================+ | `Make Live Updates`_ | As you make a change to your content, it will show up immediately in your domain in the metaverse. | -| | This means that any visitors in your domain will see the changes as they happen. | +| | This means that any visitors in your domain will see the changes as they happen. | +------------------------+------------------------------------------------------------------------------------------------------+ | `Under Construction`_ | During the time that you're constructing your content set, your domain is offline to outside | | | visitors. Users will be unable to visit your domain while it is under construction. | @@ -50,7 +50,7 @@ We let you choose how you want to build and deploy your content. The process for Make Live Updates ^^^^^^^^^^^^^^^^^ -Live updates are made anytime you or any other user in your domain makes changes to the content. In order to make changes, a user must have the 'Rez' permission turned on. +Live updates are made anytime you or any other user in your domain makes changes to the content. In order to make changes, a user must have the 'Rez' permission turned on. Before going this route, decide on who (if anyone) you would like to change your content set, and :doc:`verify that their rez permissions are set correctly <../configure-settings/permission-settings>`. If you're going to be the one making changes, then ensure that you have rez rights. To update your content, all you need to is visit your domain and start making changes using the :doc:`Create Tools <../../create/tools>`. @@ -63,18 +63,18 @@ Your server makes regular archives of the content in your domain. Visit your Dom Under Construction ^^^^^^^^^^^^^^^^^^ -While you make changes to your content set, you can take down your domain temporarily and prevent users from visiting while it is under construction. +While you make changes to your content set, you can take down your domain temporarily and prevent users from visiting while it is under construction. To do this, simply the remove the 'Connect' permission for all users other than yourself (and any other co-creators working alongside you). When you are done, all you need to do is re-enable the 'Connect' permission. 1. Open your domain settings. * For cloud hosted domains: Open a browser and enter the URL http://:40100/settings. Log in when prompted. - * For local servers on Windows: Click on the Overte icon in the system tray, then click 'Settings'. + * For local servers on Windows: Click on the Overte icon in the system tray, then click 'Settings'. * For local servers on Mac: Right-click the Overte icon on the top menu bar, then click 'Settings'. 2. On the top menu bar, select **Settings > Security**. -3. Scroll to 'Standard Permissions'. -4. For each Permissions group, uncheck the 'Connect' permission for all users and groups (except yourself and anyone else working on the content). +3. Scroll to 'Standard Permissions'. +4. For each Permissions group, uncheck the 'Connect' permission for all users and groups (except yourself and anyone else working on the content). 5. Click 'Save' and close the Domain Settings page. Once you have set the permissions, visit your domain and begin building your content set using the :doc:`Create Tools <../../create/tools>`. We recommend locking all of your content so that it cannot be modified by visitors to your domain. @@ -88,7 +88,7 @@ When you're done, follow the above steps to re-enable the Connect permission for Create and Deploy ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The final technique for building a content set follows a basic development workflow: +The final technique for building a content set follows a basic development workflow: * Build content in an offline environment * (Optional) Build and test it @@ -97,7 +97,7 @@ The final technique for building a content set follows a basic development workf We recommend using this method if you want to avoid interruption to your domain while you build your content, deploy your content set to multiple domains, or test your content before you deploy. -1. Install Overte's open source Client + Sandbox software on a computer that is _not_ running as a local server. +1. Install Overte's open source Client + Sandbox software on a computer that is _not_ running as a local server. 2. Open a Sandbox not connected to a local server. 3. Build your content set in the Sandbox. 4. `Export your content to JSON `_. diff --git a/source/host/configure-settings/permission-settings.rst b/source/host/configure-settings/permission-settings.rst index 5a1e58e8..8299c319 100755 --- a/source/host/configure-settings/permission-settings.rst +++ b/source/host/configure-settings/permission-settings.rst @@ -11,16 +11,16 @@ You can protect your domain by setting user permission for the visitors in your Set User Permissions -------------------- -Permissions can be assigned to standard user groups, custom user groups, specific users, users from a specific IP, and users from specific computers. +Permissions can be assigned to standard user groups, custom user groups, specific users, users from a specific IP, and users from specific computers. -The permissions for a user will be the sum of all groups that the user is in. For example, let's say that all logged in users can connect and only localhost users can rez entities. If a user is both logged in and on localhost, then they will be able to both connect and rez entities. Additionally, when you assign user permissions to a specific user, it will supersede any group-level permissions that otherwise might apply to that user. +The permissions for a user will be the sum of all groups that the user is in. For example, let's say that all logged in users can connect and only localhost users can rez entities. If a user is both logged in and on localhost, then they will be able to both connect and rez entities. Additionally, when you assign user permissions to a specific user, it will supersede any group-level permissions that otherwise might apply to that user. -To assign user permissions: +To assign user permissions: 1. Open your domain settings. * For cloud hosted domains: Open a browser and enter the URL http://:40100/settings. Log in when prompted. - * For local servers on Windows: Click on the Overte icon in the system tray, then click 'Settings'. + * For local servers on Windows: Click on the Overte icon in the system tray, then click 'Settings'. * For local servers on Mac: Right-click the Overte icon on the top menu bar, then click 'Settings'. * For any OS: Open a browser and enter the URL http://localhost:40100/settings. 2. Scroll to 'Domain-Wide User Permissions'. @@ -28,10 +28,10 @@ To assign user permissions: 4. To assign all other permissions, you need to add a custom group, specific user, etc individually to the correct permissions table: * **Add Group**: Enter the name of the custom group or list, then click the ``+`` icon. Save your domain settings to load ranks. Check the box of all permissions you'd like to grant or deny (depending on the permissions table you are adding the group to). - - .. image:: ../_images/group-permissions.png + + .. image:: ../_images/group-permissions.png * **Add Specific User**: Click the ``+`` icon, then enter a specific user name. Check the box of all permissions you'd like to grant. - + .. image:: ../_images/user-permissions.png * **Add IP Address, MAC Address, or Machine Fingerprint**: Click the ``+`` icon, then enter the information (based on the permissions table you are adding permission to). Check the box of all permissions you'd like to grant. 5. Click 'Save' to save your domain settings. @@ -40,7 +40,7 @@ To assign user permissions: Standard User Groups ----------------------------- -Your domain comes with four basic security groups that are already set up, based on the people that you will interact with in the metaverse. They are: +Your domain comes with four basic security groups that are already set up, based on the people that you will interact with in the metaverse. They are: +-----------+--------------------------------------------------------------------------------------------+ | User Type | Description | @@ -65,7 +65,7 @@ Your domain comes with four basic security groups that are already set up, based The 'Connect' permission for these standard user groups determine the privacy level of your domain: -* **Public**: A public domain allows 'anonymous' and/or 'logged-in' users to connect to it. These domains may be shown in the Explore app and in other places around the metaverse. +* **Public**: A public domain allows 'anonymous' and/or 'logged-in' users to connect to it. These domains may be shown in the Explore app and in other places around the metaverse. * **Private**: A private domain does not allow 'anonymous' and/or 'logged-in' users to connect to it. Domain owners are responsible for promoting their domains to other users and maintaining connect permissions for users to enter their domain. ---------------- @@ -90,15 +90,6 @@ The actions that you can secure for each type of user are as follows: | | Maximum Lifetime of Temporary Entities**). These users will also have full | | | access to the **Create** app. | +-------------------------+------------------------------------------------------------------------------+ -| Rez Certified | This was used to set whether a user can permanently create (or rez) new | -| | entities that were purchased from the Marketplace. Right now it does | -| | nothing. | -+-------------------------+------------------------------------------------------------------------------+ -| Rez Temporary Certified | This was used to set whether a user can create (or rez) new entities from | -| | the Marketplace for a finite lifetime (the lifetime is set in **Domain | -| | Settings > Entities > Advanced Settings > Maximum Lifetime of Temporary | -| | Entities**). Right now it does nothing. | -+-------------------------+------------------------------------------------------------------------------+ | Write Assets | Sets whether a user can add assets (models, audio, or other files) or make | | | changes to the domain's asset server (your domain's file storage space). | +-------------------------+------------------------------------------------------------------------------+ @@ -117,3 +108,8 @@ The actions that you can secure for each type of user are as follows: | | `_ type | | | definition. | +-------------------------+------------------------------------------------------------------------------+ +| Can View Asset URLs | Sets whether a user can view asset URLS in **Create** and scripts. If a user | +| | doesn't have this permission, the URLs will be reported as empty strings. | +| | Note: this is only a client-side protection. Learn more about | +| | `asset security <../../security/asset-security.html>`_. | ++-------------------------+------------------------------------------------------------------------------+ diff --git a/source/security.rst b/source/security.rst index 5a8cbcdc..a61238d0 100755 --- a/source/security.rst +++ b/source/security.rst @@ -9,3 +9,4 @@ Security information about the project and its components: Interface, server, an :titlesonly: Crash Reporting + Asset Security diff --git a/source/security/asset-security.rst b/source/security/asset-security.rst new file mode 100644 index 00000000..b30be7dc --- /dev/null +++ b/source/security/asset-security.rst @@ -0,0 +1,77 @@ +############################### +Asset Security +############################### + +Like a web browser, Overte allows you to bring together assets like models and images from external sources and share them with others. This allows you to create diverse domains and assume unique avatars using simple URLs. When you connect to a domain, your client will download and display entities and avatars using those links, just as a web browser loads an image. + +However, it is not always desirable to allow others to trivially copy your content or avatars by URL. We encourage collaborative building and sharing of assets pursuant to their licenses, but we understand that content creators may want to keep their assets private and that avatars are often personal representations that are not meant to be copied. + +Since Overte is open source, it is difficult to solve this problem completely. Bad actors will always be able to modify their clients or rip assets directly from the GPU. We can only aim to make it more difficult for them. We have outlined some of the tools we offer below and are always open to more suggestions and especially PRs. + +.. contents:: On This Page + :depth: 2 + +---------------------- +Entities +---------------------- + +Multiple types of Entities refer to external assets such as models, images, shaders, sounds, etc. These URLs are most commonly accessed via the **Create** app. You can prevent a visitor to your domain from using Create by revoking their **Rez** and **Rez Temporary** `permissions <../host/configure-settings/permission-settings.html>`_. + +However, even if a user doesn't have Rez permission and can't access Create, the URLs can still be accessed via scripts. You can prevent scripts from accessing these URLs by revoking a user's **Can View Asset URLs** permission. + +These protections are **client-side only**. This means that a malicious person with a modified client could circumvent them. There are two other options you can use to alleviate this concern: + +* For models and images, bake your assets using the `Oven <../host/add-content/bake-content.html>`_. As a side effect of compressing and optimizing them, the Oven makes it harder (**but not impossible**) to open these files in other programs. +* Use the **Asset Server**. If you upload content to the asset server, it will provide you an `atp` link which only works within your domain. + +---------------------------------- +Avatars +---------------------------------- + +Non-built-in scripts are prevented from directly reading your avatar's URL. You can grant permission to read your avatar URL on a per-script basis, so untrusted scripts cannot grab it. + +Clients do not have access to other people's avatar URLs via scripts at all (unless they have modified their client). + +---------------------------------- +Proposed Alternatives +---------------------------------- + +Asset security is extremely important and we recognize that the above might not be sufficient for everyone. Below are some alternatives that have been suggested and their pros and cons. + +We strive to provide as many options as possible and contributions to increase security are very welcome. However, note that even with many of the below suggestions, at some point, any model, image, or resource will end up on a client and a sufficiently motivated person will be able to access it. + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Have the Domain Server Obfuscate URLs +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Instead of sending URLs, the Domain Server could itself download the assets and send data directly to clients. + +For avatars, while this would prevent trivial copying of URLs, it opens domain operators up to legal repurcussions for serving copyrighted or illegal content. + +For entities, this is effectively what the Asset Server already does, if you choose to use it. It is important to carefully control who has Rez permission in your domain to avoid the above legal ramifications. + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Peer-to-Peer Avatar Sharing +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Users could share their avatars via a peer-to-peer network, either via the Domain Server or directly with other clients. + +Like the above, this opens others up to legal ramifications for sharing copyrighted or illegal content. Additionally, peer-to-peer traffic can lead to legal ramifications for people in many countries and institutions (e.g. schools) even if the content itself is not illegal. + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Server-side Avatar Verification +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The Avatar Mixer, before sending your Avatar URL to others, could verify that you actually own it. + +This was a feature of High Fidelity's marketplace, where the Avatar Mixer could check the certification of your avatar and only send it to others if you actually owned it. We no longer support High Fidelity's centralized marketplace or certificates, so this was removed. It was also trivial to download the FST, strip out the certification, and re-upload it. More complex checks, like fingerprinting based on actual vertices, are computationally expensive and still possible to work around. + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Avatar Viewing Permissions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In an FST, you could optionally specify permissions for who is allowed to view your avatar, and a fallback URL for those who aren't allowed. + +This would allow you to show your true avatar only to trusted friends. The Avatar Mixer would check the permissions for each connection before sending the URLs. + +Although there are technical questions about how this would work with differently-rigged or differently-sized avatars for the fallback, and it can be jarring to have others not be able to see your true avatar, this would be a nice option to have for those who want it.