doc/architecture/manifest-format.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: architecture
   4 title: Manifest format
   5 ...
   6 {% comment %}
   7 Copyright (C) The Arvados Authors. All rights reserved.
   8
   9 SPDX-License-Identifier: CC-BY-SA-3.0
  10 {% endcomment %}
  11
  12 Each collection record has a @manifest_text@ field, which describes how to reassemble keep blocks into files. Each block identifier in the manifest has an added signature which is used to confirm permission to read the block.  To read a block from a keepstore server, the client must provide the block identifier, the signature, and the same API token used to retrieve the collection record.
  13
  14 !(full-width){{site.baseurl}}/images/Keep_manifests.svg!
  15
  16 h2. Manifest v1
  17
  18 A manifest is utf-8 encoded text, consisting of zero or more newline-terminated streams.
  19
  20 <pre>
  21 manifest       ::= stream*
  22 stream         ::= stream-name (" " locator)+ (" " file-segment)+ "\n"
  23 stream-name    ::= "." ("/" path-component)*
  24 path-component ::= <printable ASCII - (whitespace, "/")>+
  25 file-segment   ::= position ":" size ":" filename
  26 position       ::= [0-9]+
  27 size           ::= [0-9]+
  28 filename       ::= path-component ("/" path-component)*
  29 </pre>
  30
  31 Notes:
  32
  33 * The first token is the stream name, consisting of one or more path components, delimited by @"/"@.
  34 ** The first path component is always @"."@.
  35 ** No path component is empty.
  36 ** No path component following the first one can be "." or "..".
  37 ** The stream name never begins or ends with @"/"@.
  38 * The next N tokens are "keep locators":#locator
  39 ** These describe the "data stream".  By logically concatenating the blocks in the order that they appear, we can refer to "positions" in the data stream.
  40 * File tokens come after the sequence of keep locators.
  41 ** A file token has three parts, delimited by @":"@: position, size, filename.
  42 ** Position and size are given in decimal
  43 ** The position is the position in the data stream
  44 ** The size is the count of bytes following the position in the data stream.  A file size may cross multiple blocks in the data stream.
  45 ** Filename may contain @"/"@ characters, but must not start or end with @"/"@, and must not contain @"//"@.
  46 ** Filename components (delimited by @"/"@) must not be @"."@ or @".."@.
  47 ** There may be multiple file tokens.
  48
  49 It is legal to have multiple file tokens in the manifest (possible across different streams) with the same combined path name @stream name + "/" + filename@.  This must be interpreted as a concatenation of file content, in the order that the file tokens appear in the manifest.
  50
  51 Spaces are represented by the escape sequence @\040@.  Spaces in stream names and filenames must be translated when reading and writing manifests.  A manifest may not contain TAB characters, nor other ASCII whitespace characters or control codes other than the spaces or newlines used as delimiters specified above.  A manifest always ends with a newline -- except the empty (zero-length) string, which is a valid manifest.
  52
  53 h3. Normalized manifest v1
  54
  55 A normalized manifest is a manifest that meets the following additional restrictions:
  56
  57 * Streams are in alphanumeric order.
  58 * Each stream name is unique within the manifest.
  59 * Files within a stream are listed in alphanumeric order.
  60 * Blocks within a stream are ordered based on order of file tokens of the stream.  A given block is listed at most once in a stream.
  61 * Filename must not contain @"/"@ (the stream name represents the path prefix)
  62
  63 h3. Example manifests
  64
  65 A manifest with four files in two directories:
  66
  67 <pre>
  68 . 930625b054ce894ac40596c3f5a0d947+33 0:0:a 0:0:b 0:33:output.txt
  69 ./c d41d8cd98f00b204e9800998ecf8427e+0 0:0:d
  70 </pre>
  71
  72 The same manifest with permission signatures on each block:
  73
  74 <pre>
  75 . 930625b054ce894ac40596c3f5a0d947+33+A1f27a35dd9af37191d63ad8eb8985624451e7b79@5835c8bc 0:0:a 0:0:b 0:33:output.txt
  76 ./c d41d8cd98f00b204e9800998ecf8427e+0+A27117dcd30c013a6e85d6d74c9a50179a1446efa@5835c8bc 0:0:d
  77 </pre>
  78
  79 A manifest containing a file consisting of multiple blocks and a space in the file name:
  80
  81 <pre>
  82 . c449ed86671e4a34a8b8b9430850beba+67108864 09fcfea01c3a141b89dd0dcfa1b7768e+22534144 0:89643008:Docker\040image.tar
  83 </pre>
  84 h2(#locator). Keep locator format
  85
  86 BNF notation for a valid Keep locator string (with hints).  For example: *d41d8cd98f00b204e9800998ecf8427e+0+Z+Ada39a3ee5e6b4b0d3255bfef95601890afd80709@53bed294*
  87
  88 <pre>
  89 locator          ::= sized-digest hint*
  90 sized-digest     ::= digest size-hint
  91 digest           ::= <32 lowercase hexadecimal digits>
  92 size-hint        ::= "+" [0-9]+
  93 hint             ::= "+" hint-type hint-content
  94 hint-type        ::= [A-Z]+
  95 hint-content     ::= [A-Za-z0-9@_-]*
  96 sign-hint        ::= "+A" <40 lowercase hexadecimal digits> "@" sign-timestamp
  97 remote-sign-hint ::= "+R" [A-Za-z0-9]{5} "-" <40 lowercase hexadecimal digits> "@" sign-timestamp
  98 sign-timestamp   ::= <8 lowercase hexadecimal digits>
  99 </pre>
 100
 101 h3. Regular expression to validate locator
 102
 103 <pre>
 104 /^([0-9a-f]{32})\+([0-9]+)(\+[A-Z][-A-Za-z0-9@_]*)*$/
 105 </pre>
 106
 107 h3. Valid locators
 108
 109 table(table table-bordered table-condensed).
 110 |@d41d8cd98f00b204e9800998ecf8427e+0@|
 111 |@d41d8cd98f00b204e9800998ecf8427e+0+Z@|
 112 |<code>d41d8cd98f00b204e9800998ecf8427e+0+Z+Ada39a3ee5e6b4b0d3255bfef95601890afd80709@53bed294</code>|
 113 |<code>930625b054ce894ac40596c3f5a0d947+33+Rzzzzz-1f27a35dd9af37191d63ad8eb8985624451e7b79@5835c8bc</code>|
 114
 115 h3. Invalid locators
 116
 117 table(table table-bordered table-condensed).
 118 ||Why|
 119 |@d41d8cd98f00b204e9800998ecf8427e@|No size hint|
 120 |@d41d8cd98f00b204e9800998ecf8427e+Z+0@|Other hint before size hint|
 121 |@d41d8cd98f00b204e9800998ecf8427e+0+0@|Multiple size hints|
 122 |@d41d8cd98f00b204e9800998ecf8427e+0+z@|Hint does not start with uppercase letter|
 123 |@d41d8cd98f00b204e9800998ecf8427e+0+Zfoo*bar@|Hint contains invalid character @*@|
 124
 125 h3. Token signatures
 126
 127 A token signature (sign-hint) provides proof-of-access for a data block.  It is computed by taking a SHA1 HMAC of the blob signing token (a shared secret between the API server and keep servers), block digest, current API token, expiration timestamp, and blob signature TTL.
 128
 129 When communicating with the @keepstore@ to fetch a block, or the API server to create or update a collection, the service computes the expected token signature for each block and compares it to the token signature that was presented by the client.  Keep clients receive valid block signatures when uploading a block to a keep store (getting back a signed token as proof of knowledge) or, from the API server, getting the manifest text of a collection on which the user has read permission.
 130
 131 Security of a token signature is derived from the following characteristics:
 132
 133 # Valid signatures can only be generated by entities that know the shared secret (the "blob signing token")
 134 # A signature can only be used by an entity that also know the API token that was used to generate it.
 135 # It expires after a set date (the expiration time, based on the "blob signature time-to-live (TTL)")
 136
 137 h3(#federationsignatures). Federation and signatures
 138
 139 When a collection record is returned through a federation request, the keep blocks listed in the manifest may not be available on the local cluster, and the keep block signatures returned by the remote cluster are not valid for the local cluster.  To solve this, @arvados-controller@ rewrites the signatures in the manifest to "remote cluster" signatures.
 140
 141 A local signature comes after the block identifier and block size, and starts with @+A@:
 142
 143 <code>930625b054ce894ac40596c3f5a0d947+33+A1f27a35dd9af37191d63ad8eb8985624451e7b79@5835c8bc</code>
 144
 145 A remote cluster signature starts with @+R@, then the cluster id of the cluster it originated from (@zzzzz@ in this example), a dash, and then the original signature:
 146
 147 <code>930625b054ce894ac40596c3f5a0d947+33+Rzzzzz-1f27a35dd9af37191d63ad8eb8985624451e7b79@5835c8bc</code>
 148
 149 When the client provides a remote-signed block locator to keepstore, the keepstore proxies the request to the remote cluster.
 150
 151 # keepstore determines the cluster id to contact from the first part of the @+R@ signature
 152 # creates a salted token using the API token and cluster id
 153 # contacts the "accessible" endpoint on the remote cluster to determine the remote cluster's keepstore or keepproxy hosts
 154 # converts the remote signature @+R@ back to a local signature @+A@
 155 # contacts the remote keepstore or keepproxy host and requests the block using the local signature
 156 # returns the block contents back to the client
 157
 158 h3(#example). Example
 159
 160 This example uses @c1bad4b39ca5a924e481008009d94e32+210@, which is the content hash of a @collection@ that was added to Keep in "how to upload data":{{ site.baseurl }}/user/tutorials/tutorial-keep.html.  Get the collection manifest using @arv-get@:
 161
 162 <notextile>
 163 <pre><code>~$ <span class="userinput">arv-get c1bad4b39ca5a924e481008009d94e32+210</span>
 164 . 204e43b8a1185621ca55a94839582e6f+67108864+Aasignatureforthisblockaaaaaaaaaaaaaaaaaa@5f612ee6 b9677abbac956bd3e86b1deb28dfac03+67108864+Aasignatureforthisblockbbbbbbbbbbbbbbbbbb@5f612ee6 fc15aff2a762b13f521baf042140acec+67108864+Aasignatureforthisblockcccccccccccccccccc@5f612ee6 323d2a3ce20370c4ca1d3462a344f8fd+25885655+Aasignatureforthisblockdddddddddddddddddd@5f612ee6 0:227212247:var-GS000016015-ASM.tsv.bz2
 165 </code></pre>
 166 </notextile>
 167
 168 This collection includes a single file @var-GS000016015-ASM.tsv.bz2@ which is 227212247 bytes long. It is stored using four sequential data blocks with hashes @204e43b8a1185621ca55a94839582e6f+67108864@, @b9677abbac956bd3e86b1deb28dfac03+67108864@, @fc15aff2a762b13f521baf042140acec+67108864@, and @323d2a3ce20370c4ca1d3462a344f8fd+25885655@. Each of the block hashes is followed by the rest of their "locator":#locator.
 169
 170 Use @arv-get@ to download the first data block:
 171
 172 notextile. <pre><code>~$ <span class="userinput">arv-get 204e43b8a1185621ca55a94839582e6f+67108864+Aasignatureforthisblockaaaaaaaaaaaaaaaaaa@5f612ee6 &gt; block1</span></code></pre>
 173
 174 Inspect the size and compute the MD5 hash of @block1@:
 175
 176 <notextile>
 177 <pre><code>~$ <span class="userinput">ls -l block1</span>
 178 -rw-r--r-- 1 you group 67108864 Dec  9 20:14 block1
 179 ~$ <span class="userinput">md5sum block1</span>
 180 204e43b8a1185621ca55a94839582e6f  block1
 181 </code></pre>
 182 </notextile>
 183
 184 As expected, the md5sum of the contents of the block matches the @digest@ part of the "locator":#locator, and the size of the contents matches the @size-hint@.