You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The Digital Bill of Materials (DBoM) Consortium Linux Foundation project seeks to improve supply chain efficiency by enabling more effective attestation sharing among supply chain partners. Find us at `dbom.io <http://dbom.io/>`_ .
6
6
To know more go to :doc:`what-dbom` or if you want to get started and set up a DBoM Node go to :doc:`getting-started`.
Copy file name to clipboardExpand all lines: source/tutorials.rst
+106-6Lines changed: 106 additions & 6 deletions
Original file line number
Diff line number
Diff line change
@@ -52,11 +52,111 @@ The agent is configured to automatically reload the agent config if any
52
52
changes occur on the configmap or in the file-system
53
53
54
54
55
-
=================================================
56
-
Connecting Multiple Nodes to a MongoDB Repository
57
-
=================================================
55
+
=========================
56
+
Connecting Multiple Nodes
57
+
=========================
58
+
59
+
60
+
MongoDB (Database Agent)
61
+
------------------------
62
+
63
+
This can be done by configuring the same mongoDB URI for the database-agent deployment for each node, either by using docker environment variables or the appropriate keys in the Kubernetes configmap
Ensure that both nodes have the agent configuration correctly set with the same names for the repositories. Access control to channels is facilitated by MongoDB Collection Level Role Based Access Control. Find how that can be setup by referring to the `official MongoDB documentation <https://docs.mongodb.com/manual/core/collection-level-access-control/>`__
71
+
72
+
IOTA (IOTA MAM Agent)
73
+
---------------------
74
+
75
+
To know more about setting up multiple channels for the IOTA MAM Agent, go to the `official repository <https://github.com/DBOMproject/iota-agent#multi-node-channel-support>`__
76
+
77
+
.. _gw-extension-apis:
78
+
79
+
================================
80
+
Using The Gateway Extension APIs
81
+
================================
82
+
83
+
In addition to the core create, update, attach, detach and audit APIs, the gateway has extension APIs that provide utility functions. These tutorials guide you through using them
84
+
85
+
86
+
Transfer API
87
+
------------
88
+
89
+
The Transfer API allows you to copy over an asset from one attestation channel to another. This could be useful when you're moving an asset downstream in the supply chain, where entities only have visibility into a limited set of the channels
90
+
91
+
.. image:: _static/img/transfer-asset-example.png
92
+
:alt:Example transfer scenario
93
+
94
+
Pictured above is an example scenario where the "Supplier-Manufacturer" channel's policy restricts it to be read by just the supplier and the manufacturer.
95
+
96
+
If the manufacturer wanted to share this asset downstream with the distributor, they can transfer it to the "Manufacturer-Distributor" channel, whose policies allow the distributor to read it
97
+
98
+
When a transfer occurs, the metadata required to find the transfer destination and source are embedded into the asset payload. This allows you to track the asset's audit trail throughout it's lifetime
99
+
100
+
Using the REST API
101
+
^^^^^^^^^^^^^^^^^^
102
+
103
+
Import the `Postman files for the Gateway <https://github.com/DBOMproject/api-specs/tree/master/gateway/postman>`__ to experiment with the REST API.
104
+
105
+
Open up the postman collection and navigate to the "Transfer an Asset" request. Enter your parameters for repo ID, channel ID and asset ID (source) into the http parameters tab
106
+
107
+
When you navigate to the "body" tab, you will see the following payload
108
+
109
+
.. code-block:: json
110
+
111
+
{
112
+
"transferDescription": "...",
113
+
"repoID": "...",
114
+
"channelID": "...",
115
+
"assetID": "..."
116
+
}
117
+
118
+
The ``repoID``, ``channelID`` and ``assetID`` referred to in the body must be replaced with the destination repo, channel and asset id that you want the asset to assume after the transfer operation. You can also provide a ``transferDescription`` to provide context for the transfer operation
119
+
120
+
Once transferred, the source and destination assets will be amended with a ``custodyTransferEvents`` JSON array, which reflects all the transfer events that have occured on the asset. As this is part of the asset payload, it is immutably reflected in the asset audit trail.
121
+
122
+
.. note::
123
+
124
+
By default, the source asset is also marked 'read-only' by the gateway.
125
+
126
+
If you retrieve the destination or source asset that you transferred right now, you'll find the following key added to the asset payload:
127
+
128
+
.. code-block:: json
129
+
130
+
"custodyTransferEvents ": [
131
+
{
132
+
"timestamp": "2021-03-22T11:22:14.589Z",
133
+
"transferDescription": "moved",
134
+
"sourceRepoID": "DB1",
135
+
"sourceChannelID": "C1",
136
+
"sourceAssetID": "ABC02",
137
+
"destinationRepoID": "DB1",
138
+
"destinationChannelID": "C2",
139
+
"destinationAssetID": "ABC02"
140
+
}
141
+
],
142
+
143
+
This event tells the requestor that this asset was moved from DB1,C1 to DB1,C2 at the shown timestamp with the description "moved". The presence of this event on the asset can be used in your applications to recursively retrieve the state of the asset across multiple channels in order to trace and establish provenance of the asset.
144
+
145
+
146
+
Transfer Policies
147
+
^^^^^^^^^^^^^^^^^^
148
+
.. note::
149
+
150
+
This subsection describes functionality that has not yet been implemented in the OSS DBoM Gateway
151
+
152
+
There are cases where you would want to mark assets on a channel as being transferrable only if it meets the criteria set by channel-wide or asset-specific policies.
153
+
154
+
This is where transfer policies come in. They allow you to set channel wide or asset specific policies for transfer including
155
+
156
+
- the ability to disable transfers altogether
157
+
- controlled transfers that are limited to specific repositories and channels
158
+
159
+
Channels will have a default transfer policy, which will apply to all assets that don't have an explicit channel policy specified, however if the asset references a specific policy as part of the asset metadata, that policy will override the default policy set at the channel level
0 commit comments