susp_aaip_2_0.txt 19.7 KB
Newer Older
1 2 3 4


                 Arbitrary Attribute Interchange Protocol

5
                                Version 2.0
6

7
                                Mar 18 2009
8 9 10 11 12 13 14 15 16 17 18 19 20 21 22

                Interchange of Persistent File Attributes

          by Thomas Schmitt    - mailto:scdbackup@gmx.net
          Libburnia project    - mailto:libburn-hackers@pykix.org


AAIP is intended as companion of the Rock Ridge Interchange Protocol RRIP
which under the general design of System Use Sharing Protocol SUSP extends
ISO 9660 aka ECMA-119 filesystem semantics to match POSIX needs.

Goal is to have for each file an arbitrary number of attributes which consist
of two components (Name and Value) of arbitrary length and to have a compact
representation of ACLs.

23 24
This document describes a SUSP entry with Signature Word "AL" which collides
neither with SUSP 1.12 nor with RRIP 1.12. The AL entry has been designed
25 26
to be as similar to the RRIP entry SL as possible.
The presence of AAIP shall be announced by a particular ER entry.
27

28
Since the size of a SUSP entry is limited to 255, multiple entries may be
29 30 31
needed to describe one component. The CE mechanism of SUSP shall be used to
address enough storage if needed.

32
AL entries and the ER entry of AAIP shall only be present if the ER entry
33 34 35 36 37 38
of RRIP is present.

-------------------------------------------------------------------------------

System Entries Provided by this Specification

39
* AL
40

41
Description of the "AL" System Use Entry
42

43
The entry has exactly the same layout as RRIP entry SL. One has to expect
44 45 46
more data bytes than with SL, though, and any of the 256 possible byte values. 
The reader shall be prepared to detect and handle oversized data.

47
One or more AL entries form the Attribute List of a file object with
48
an even number of components. Each two consecutive components form a pair of
49
Name and Value.
50 51 52

The empty name indicates that the value is a compact representation of ACLs.
Names must not contain byte value 0x00. Names which begin by bytes 0x01 to 0x1f
53
represent names in particular namespaces. See below: Namespaces.
54
The meaning of any other names or name parts is not specified by this document.
55

56
All AL entries except the last one shall have the CONTINUE flag set. An AL
57
entry with CONTINUE set to 0 indicates the end of the Attribute List.
58

59
The format of the AL System Use Field is as follows:
60

61
  [1] "BP 1 to BP 2 - Signature Word" shall be (41)(4C) ("AL").
62 63

  [2] "BP 3 - Length" shall specify as an 8-bit number the length in bytes of
64
      the AL entry recorded according to ISO 9660:7.1.1.
65 66 67 68 69

  [3] "BP 4 - System Use Entry Version" shall be 1 as in ISO 9660:7.1.1.

  [4] "BP 5 - Flags" shall contain bit field flags numbered 0 to 7 starting
      with the least significant bit as follows:
70
        0   CONTINUE  This AL entry continues in the next AL entry.
71 72 73 74 75
      All other bits shall be set to 0.

  [5] "BP 6 to Length - Component Area" shall contain Component Records
      as described below.

76
  | 'A' | 'L' | LENGTH | 1 | FLAGS | COMPONENT AREA |
77 78
  

79
Within AL entries each component (Name or Value) shall be recorded as one
80
or more component records. If a component does not fit into the remaining
81
space of an AL entry then it shall be continued in following AL entries.
82 83 84 85 86 87 88 89

All Component Records of a component except the last one shall have the
CONTINUE flag set. A Component Record with CONTINUE set to 0 indicates the end
of the component. An eventually following Component Record starts the next
component.

-------------------------------------------------------------------------------

90
The Component Record format is identical to the one of the SL entry.
91
The complete form of the following summary can be found in RRIP 1.12 "4.1.3.1".
Thomas Schmitt's avatar
Thomas Schmitt committed
92 93
In case of discrepancies, RRIP 1.12 is the decisive specification. Please
inform the author of this document if you find such a discrepancy.
94 95 96

Component Records shall be recorded contiguously within each Component Area,
starting in the first byte of the Component Area. The last Component Record
97 98
in the Component Area of an AL System Use Entry may be continued in the
Component Area of the next recorded AL System Use Entry in the same
99 100 101 102 103 104 105
System Use Area.

Each Component Record shall have the following format:

  [A] "BP 1 - Component Flags" shall contain bit field flags numbered 0 to 7,
      starting with the least significant bit, as follows:
        0   CONTINUE  This Component Record continues in the next
106
                      AL Component Record.
107 108 109 110 111 112 113 114 115 116 117 118 119 120
        all others are RESERVED and shall be 0.

  [B] "BP 2 - Component Length (LEN_CP)" shall specify as an 8-bit number the
      number of component bytes in the Component Record. This length shall not
      include the first two bytes of the Component Record.
      This field shall be recorded according to ISO 9660 Format section 7.1.1.

  [C] "BP 3 to 2 + LEN_CP - Component Content" shall contain the component
      bytes in the Component Record.

  | COMPONENT FLAGS | LEN_CP | COMPONENT BYTES |


Example: Two pairs of "name"="long...content" and "one"="more" encoded as
121
         two AL entries
122 123 124

  Field 1 contains the Component Record of Name and one Component Record of
  Value :
125
  { 'A', 'L', 255,   1,   1,
126
      0,   4, 'n', 'a', 'm', 'e',
127
      1, 255, 'l', 'o', 'n', 'g', ... 238 more bytes, 13 go to next AL ... }
128 129
  Field 2 contains the rest of "long...content" and the complete second pair.
  It marks the end of the Attribute List :
130
  { 'A', 'L',  38,   1,   0,
131
              ... 13 remaining bytes of the Component Record in first entry ...
132 133 134 135 136 137
      0,   7, 'c', 'o', 'n', 't', 'e', 'n', 't',
      0,   3, 'o', 'n', 'e',
      0,   4, 'm', 'o', 'r', 'e' }

-------------------------------------------------------------------------------

138
Namespaces
139 140 141 142 143 144

AAIP provides a short notation for namespaces which uses a single non-printable
byte at the start of the name.
Reserved start bytes of names are
    0x01 to 0x1F

145 146
The names of extended file attributes are traditionally organized in
namespaces, which get expressed as first part of an attribute name up to a
147 148 149
period "." character. It is also tradition that names are printable text,
single words and especially contain no 0-bytes.

150 151
AAIP does not enforce the use of any namespace but it urges that names in the
following registered namespaces are used according to traditions.
152

153
The namespaces "system." and "user." are available with many file system
154 155 156
types. "system." is file system dependent and often restricted in the
choice of names. "user." is portable and allows to choose about any name.

157
Namespace "isofs." is defined for internal use of AAIP enhanced ISO 9660
158 159
file systems. Names in this namespace should be registered at
libburnia-project.org.
160

161
Further namespaces may be registered at libburnia-project.org.
162 163 164 165 166 167

The reserved start bytes of names have the following meaning
    0x01   escape reserved character at start of name
    0x02   namespace "system."
    0x03   namespace "user."
    0x04   namespace "isofs."
168 169 170
    0x05   namespace "trusted."
    0x06   namespace "security."
    0x07 to 0x1F shall not be used yet.
171 172

Examples:
173 174 175 176
   Name "user.abc" with and without short notation. Both is allowed.
      0,   4, 0x03,  'a',  'b',  'c'
      0    8,  'u',  's',  'e',  'r',  '.',  'a',  'b',  'c'

177
   Name "\003abc" (if really desired)
178
      0,   5, 0x01, 0x03,  'a',  'b',  'c'
179 180 181

-------------------------------------------------------------------------------

182 183 184 185 186 187 188 189 190 191 192 193 194 195
Specification of binary ACL representation as special Arbitrary Attribute

The Name component of a binary ACL shall be of length 0.

The Value shall be an arbitrary number of ACL Entries:

  [a] "BP 1 - Entry Flags" shall contain bit field flags numbered 0 to 7,
      starting with the least significant bit, as follows:
        0   EXEC      indicates that this entry grants execute permission
        1   WRITE                                      write permission
        2   READ                                       read permission
        3   QUALIFIER indicates that one or more Qualifier Records follow
        4 - 7  TYPE
               shall contain the tag type of the ACL entry as four bit code:
196 197 198 199 200 201 202 203 204 205 206 207
                 0  TRANSLATE      Entry for a global map of name to numeric id
                                   Qualifier is a record of number and text
                 1  ACL_USER_OBJ   Permissions of owning user (as of PX entry)
                 3  ACL_GROUP_OBJ  Permissions of owning group (as of PX entry)
                 5  ACL_MASK       Restricts 10, 3, and 12 via logical AND
                 6  ACL_OTHER      Permissions of non-listed, non-owning users
                 8  SWITCH_MARK    Switch from "access" ACL to "default" ACL
                10  ACL_USER_N     Permissions of arbitrary user. Qualifier is
                                   the numeric user id (max. 4 bytes).
                12  ACL_GROUP_N    Permissions of arbitrary group. Qualifier is
                                   the numeric group id (max. 4 bytes).
                15  FUTURE_VERSION  Will indicate that this document
208 209 210 211 212
                                    does not apply to the entry.
                The other values are reserved. Readers shall ignore them if
                they are not aware of updates of this document which would
                assign a meaning to them.

213 214 215 216
The entries must match the permission bits of the PX entry. This shall obey the
rule that ACL_USER_OBJ must match S_IRWXU, ACL_OTHER must match S_IRWXO,
ACL_MASK - if present - must match S_IRWXG, else ACL_GROUP_OBJ must match
S_IRWXG. If there is ACL_USER_N or ACL_GROUP_N there must also be ACL_MASK.
217

218 219
A numeric qualifier is a binary number of variable length up to 4 bytes. The
Most Significant Byte comes first. The number shall be the "POSIX File User ID"
220
or "POSIX File Group ID" as also used in RRIP PX entries. The ids of owning
221
user and owning group shall be taken from the PX entry of the file object.
222 223 224 225 226 227 228 229

Optional TRANSLATE entries may associate user or group names with numeric
ids to allow the reading system to remap the numeric ids. See below.
The writer is not obliged to write them and the reader is not obliged to
interpret them.

The ACL entries belong to the "access" ACL of a file object. An optional
SWITCH_MARK entry may direct further entries to the "default" ACL which
230 231
is defined for directory objects. The EXEC bit of SWITCH_MARK shall be 1.
The bits for WRITE, READ, QUALIFIER shall be 0.
232

233
An eventually needed qualifier is stored in one or more Qualifier Records.
234 235 236 237

  [b] "BP 2 - Qualifier Record Head" shall be present only if QUALIFIER is set
      to 1. It shall give the number of Qualifier Bytes and eventually
      indicate that the qualifier continues in a Qualifier Record which comes
238
      immediately after this record.
239 240 241 242 243 244 245 246 247 248 249 250 251
          0 to 127   Q_LENGTH, the qualifier is complete by this record
        128 to 255   Q_LENGTH+128, the qualifier is continued by next record
      So a Qualifier Record can contain at most 127 Qualifier Bytes.
      This field shall be recorded according to ISO 9660 Format section 7.1.1.

  [c] "BP 3 to BP 2 + Q_LENGTH - Qualifier Bytes" shall be present only if
      QUALIFIER is set to 1 and hold the announced number of bytes of the
      user or group name.

  | ENTRY FLAGS [ | QUALIFIER HEAD | QUALIFIER BYTES | ]

 
Example: From man 5 acl:  u::rw-,u:lisa:rw-,g::r--,g:toolies:rw-,m::r--,o::r--
252
         "lisa" has user number 123, "toolies" has group number 65534
253
  { 'A', 'L',  20,   1,   0,
254
      0,   0,
255 256 257 258 259 260 261 262 263
      0,  11, 0x16,
              0xAE,   1, 123,
              0x34,
              0xCE,   2, 255, 254,
              0x54,
              0x64 }

Example: "Access" ACL and "default" ACL (0x81 is the switch mark)
         u::rwx,g::r-x,o::r-x,  du::rwx,dg::r-x,dm::rwx,do::r-x,du:lisa:rwx
264
  { 'A', 'L',  20,  1,   0,
265 266 267 268 269
      0,   0,
      0,  11, 0x17, 0x35, 0x65,
              0x81,
              0x17, 0x35, 0x57, 0x65,
              0xA7,    1, 123 }
270 271 272

-------------------------------------------------------------------------------

273
Association of Names and Numeric Identifiers
274 275 276 277 278
         
The entry flag value 0x08 TRANSLATE is not a ACL entry of the hosting object
but rather a global hint about the relation of roles, names and numeric ids.
If it is recorded at all, then it shall be recorded with the first Directory
Entry of the volume's root directory. According to the description of SUSP
279
entry ER, this has to be "dot" or (00). Other than with ER, a TRANSLATE entry
280 281 282 283
may not appear in the root of directory sub trees.

An interested reader shall examine the Arbitrary Attributes of this Directory
Entry in order to collect a translation table.
284
The advised translation is: PX or AL Id number -> name -> local id number.
285 286 287 288 289 290 291 292 293 294 295 296 297 298

The Qualifier Bytes of a TRANSLATE entry shall have the following format:

  [i] "BP 0 - Role" shall tell whether it is about a user name (role 0) or
      a group name (role 1). Other values are not allowed.

 [ii] "BP 1 to BP 8 - Numeric Id" shall hold the 32 bit POSIX Id number of the
      entry. This field shall be recorded according to ISO 9660:7.3.3.

[iii] "BP 9 to End Of Qualifier - Name" shall hold the name bytes of this
      entry.

  | ROLE | NUMERIC ID | NAME |

299 300 301
Example: User id number 123 gets associated with user name "lisa"

               0x08,  13,  0,  123,0,0,0,   0,0,0,123,  'l', 'i', 's', 'a',
302 303


304 305 306 307 308 309
Example: A very long qualifier naming "His_Excellency_..._the_Boss" as user #1.
         This needs two qualifier records.
               0x08, 255,   0,   1,0,0,0,   0,0,0,1,
                          'H', 'i', 's', '_', 'E', 'x', 'c', 'e', 'l', 'e',
                                     ... 108 more bytes ...
                       8, 't', 'h', 'e', '_', 'B', 'o', 's', 's', 
310 311 312 313 314 315

-------------------------------------------------------------------------------

Specification of the ER System Use Entry Values for AAIP:

This ER system entry shall only be present if the ER entry of RRIP is present.
316
To be compliant with SUSP-1.12, this ER entry must be present if AL entries
317
are present, and ES entries have to mark RRIP and AAIP entries.
318 319 320
If for some reason compliance with SUSP-1.10 is intended, then this ER entry
and the ES entries must not be present, although SUSP-1.10 would allow ER.
(See below: Compatibility considerations.)
321 322 323

The Extension Version number for this version of AAIP shall be 1.

324
The Extension Identifier field shall be "AAIP_0200" with Identifier Length 9.
325 326

The mandatory content form of the Extension Descriptor is 
327
"AL PROVIDES VIA AAIP 2.0 SUPPORT FOR ARBITRARY FILE ATTRIBUTES IN ISO 9660 IMAGES"
328 329 330 331 332 333
The Description Length is 81.

The recommended content of the Extension Source is
"PLEASE CONTACT THE LIBBURNIA PROJECT VIA LIBBURNIA-PROJECT.ORG".
The corresponding Source Length is 62.

334 335 336 337 338
-------------------------------------------------------------------------------

                        Compatibility Considerations

This extension is supposed not to disturb any reader system which complies
339
to SUSP-1.10:
340 341 342 343 344 345 346 347 348 349 350 351 352 353 354
"6.2 Requirements for a Receiving System
 [...]
 Any System Use Field which the receiving system does not recognize
 is to be ignored and skipped."

SUSP-1.12 extends this prescription by:
"Any System Use Entry, with the exception of the set of System Use Entries
 defined in this document, following an "ES" System Use Entry that indicates
 an extension specification which the receiving system does not recognize
 shall be ignored and skipped."

According to SUSP-1.12 the ER entry is mandatory for a conformant extension.
It also prescribes that in the case that ER entries of RRIP and AAIP are 
present, then ES entries shall be used to separate RRIP entries from AAIP
entries.
Thomas Schmitt's avatar
Thomas Schmitt committed
355 356
SUSP-1.12 frowns on extensions which are not announced by ER. Nevertheless
is does not totally outrule them.
357

358 359 360
SUSP-1.10 does not specify ES entries at all and allows to have extension
entries without announcing them by an ER entry. So if a second ER entry is
not bearable, then the SUSP-1.10 downgrade of AAIP allows to omit the
361
AAIP ER and the ES entries. But if there is the AAIP ER then there must be ES
362
at the appropriate places. Else the format would explicitly violate SUSP-1.12.
363 364 365 366

-------------------------------------------------------------------------------
Model Relations:

367 368
  Attribute List ------------- [1:0..1] ------------- ACL
  [1:0..n]                                            [1:0..n] 
369 370
  Arbitrary Attribute ( [1:0..1] ACL )                Entry
  [1:2..2n]                                           [1:0..1]
371
  Component  ( [1..m:1..n] AL Field )                 Qualifier
372 373 374
  [1:1..n]                                            <<  one of >>
  Component Record                                  /              \
  [1..m:1..n]                              Translation Entry ,  Numeric Id
375
  AL Field                                         |                 |
376 377
                                                 [1:1..n]          [1:1]
                                                     \              /
378 379 380 381 382
                                                      Qualifier Record

-------------------------------------------------------------------------------
Revoked drafts:

383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400
The following outdated versions may be interpreted at read time but they
shall not be written any more.

                                    AAIP-1.0

Previous versions up to AAIP 1.0 used field signature "AA" rather than "AL".
This nearly collides with "Apple ISO 9660 Extensions". The Apple "AA" field of
version 1 has a length of 7, whereas the shortest first AAIP field "AA" had
length 9.

Beginning with AAIP 2.0, the field name has been changed to "AL".
If a reader interprets old AAIP "AA" fields, then it must take precautions to
distinguish them from Apple "AA" fields. But it is well compliant with AAIP 2.0
to just ignore any kind of "AA" fields.

AAIP 1.0 had ER signature "AAIP_0100".

                                    AAIP-0.2
401

402
AAIP 0.2 with ER signature "AAIP_0002" allowed to announce and use a different
403
signature than "AA". This was revoked because ES entries serve the purpose
404
to distinguish AAIP entries from eventual "AA" entries of any other extension.
405 406
Regrettably no reader (kernel) was found which neatly interprets ES. Many do
not even recognize the RRIP-1.12 ER signatures "IEEE_P1282", "IEEE_1282".
407 408 409 410 411 412

AAIP 0.2 defined two ACL types which did not make it into AAIP 1.0
                 2  ACL_USER       of arbitrary user, with name as qualifier
                 4  ACL_GROUP      of arbitrary group, with name as qualifier
Their job was transferred to ACL_USER_N and ACL_GROUP_N which have numeric
qualifiers.
413

414 415 416 417 418
                                    AAIP-0.0

There was a draft AAIP 0.0 with ER signature "AAIP_2008A". It did not resemble
the existing entry SL and was never implemented.

419 420 421
-------------------------------------------------------------------------------
References:

422 423 424 425 426 427 428 429
ECMA-119 aka ISO 9660
  http://www.ecma-international.org/publications/files/ECMA-ST/Ecma-119.pdf

SUSP 1.12 (entries CE , PD , SP , ST , ER , ES)
  ftp://ftp.ymi.com/pub/rockridge/susp112.ps

RRIP 1.12 (entries PX , PN , SL , NM , CL , PL , RE , TF , SF , obsolete: RR)
  ftp://ftp.ymi.com/pub/rockridge/rrip112.ps
430

431 432
Apple ISO 9660 Extensions (entries AA and BA)
  http://developer.apple.com/technotes/fl/fl_36.html
433

434 435 436 437 438 439 440 441
Amiga AS entry
  http://www.estamos.de/makecd/Rock_Ridge_Amiga_Specific

zisofs entry ZF (prepared by zisofs-tools, written by mkisofs)
  http://freshmeat.net/projects/zisofs-tools/

Program mkisofs emits entry XA
  ftp://ftp.berlios.de/pub/cdrecord/alpha
442

443
-------------------------------------------------------------------------------
444

445
This text is under
446
Copyright (c) 2009 - 2013 Thomas Schmitt <scdbackup@gmx.net>
447 448 449 450 451 452 453 454 455
It shall only be modified in sync with libisofs and other software which
makes use of AAIP. Please mail change requests to mailing list
<libburn-hackers@pykix.org> or to the copyright holder in private.
Only if you cannot reach the copyright holder for at least one month it is
permissible to modify this text under the same license as the affected
copy of libisofs.
If you do so, you commit yourself to taking reasonable effort to stay in 
sync with the other interested users of this text.