legacy/libisoburn/trunk/doc/susp_aaip_0_2.txt

                 Arbitrary Attribute Interchange Protocol

                             Draft version 0.2
                                Dec 19 2008

                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.

This document describes a SUSP field with adjustable name (Signature Word).
The name is defined in an ER field of which the content form is described here.
Recommended is to use the name "AA" which collides neither with SUSP 1.12 nor
with RRIP 1.12.
The field has been designed to be as similar to the RRIP field SL as possible.

Since the size of a SUSP field is limited to 255, multiple fields may be
needed to describe one component. The CE mechanism of SUSP shall be used to
address enough storage if needed.

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

System Entries Provided by this Specification

* AA (or another name which does not disturb other co-existing SUSP protocols)

Description of the "AA" System Use Entry

This SUSP field and the ER entry of AAIP shall only be present if the ER entry
of RRIP is present.

The field has exactly the same layout as RRIP field SL. One has to expect
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.

One or more AA fields form the Attribute List of a file object with
an even number of components. Each two consequtive components form a pair of
Name and Value. The empty name is reserved for a compact representation of
ALCs. The meaning of any other name is not specified by this document.

All AA fields except the last one shall have the CONTINUE flag set. An AA
field with CONTINUE set to 0 indicates the end of the Attribute List.

The format of the "AA" System Use Field is as follows:

  [1] "BP 1 to BP 2 - Signature Word" shall be (41)(41) ("AA") resp. the word
      that is defined in the ER field. See below.

  [2] "BP 3 - Length" shall specify as an 8-bit number the length in bytes of
      the "AA" entry recorded according to ISO 9660:7.1.1.

  [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:
        0   CONTINUE  This AA field continues in the next AA field.
      All other bits shall be set to 0.

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

  | 'A' | 'A' | LENGTH | 1 | FLAGS | COMPONENT AREA |
  

Within "AA" fields each component (Name or Value) shall be recorded as one
or more component records. If a component does not fit into the remaining
space of an AA field then it shall be continued in following AA fields.

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.

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

The Component Record format is identical to the one of the SL field.
The complete form of the following summary can be found in RRIP 1.12 "4.1.3.1".
In case of discrepancies, RRIP 1.12 is the decisive specification.

Component Records shall be recorded contiguously within each Component Area,
starting in the first byte of the Component Area. The last Component Record
in the Component Area of an "AA" System Use Entry may be continued in the
Component Area of the next recorded "AA" System Use Entry in the same
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
                      AA Component Record.
      The following bits are defined but may not be set if the Component
      Record shall carry payload. (Their use case is unclear yet.)
        1   CURRENT   This Component Record refers to the current
                      directory.
        2   PARENT    This Component Record refers to the parent of
                      the current directory.
        3   ROOT      This Component Record refers to root directory.

        all others are RESERVED and shall be 0.

      No more than one of "AA" Component Flag Bits 0-3 shall be set to ONE.

  [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.
      If any of the bit positions 1-3 is set, the value of this field shall be
      set to ZERO and no Component Content shall be recorded.
      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
         two AA fields

  Field 1 contains the Component Record of Name and one Component Record of
  Value :
  { 'A', 'A', 255,   1,   1,
      0,   4, 'n', 'a', 'm', 'e',
      1, 255, 'l', 'o', 'n', 'g', ... 238 more bytes, 13 go to next AA ... }
  Field 2 contains the rest of "long...content" and the complete second pair.
  It marks the end of the Attribute List :
  { 'A', 'A',  38,   1,   0,
              ... 13 remaining bytes of the Component Record in first field ...
      0,   7, 'c', 'o', 'n', 't', 'e', 'n', 't',
      0,   3, 'o', 'n', 'e',
      0,   4, 'm', 'o', 'r', 'e' }

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

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:
                 0  TRANSLATE      entry for a global map of name to numeric id
                 1  ACL_USER_OBJ   permissions of owning user (as of PX field)
                 2  ACL_USER       of arbitrary user, with name as qualifier
                 3  ACL_GROUP_OBJ  permissions of owning group (as of PX field)
                 4  ACL_GROUP      of arbitrary group, with name as qualifier
                 5  ACL_MASK       restricts 2, 3, and 4 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     like 2, with numeric user id as qualifier
                12  ACL_GROUP_N    like 4, with numeric group id as qualifier
                15  FUTURE_VERSION  will indicate that this document
                                    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.

If any of ACL_USER_OBJ, ACL_GROUP_OBJ, ACL_OTHER are missing then the settings
from the PX field shall get into effect. If they exist then they shall override
the PX field.

A numeric qualifier is a binary number of variable length. The Most Significant
Byte comes first. The number shall be the "POSIX File User ID" resp.
"POSIX File Group ID" as also used in RRIP PX fields. The ids of owning user
and owning group shall be taken from the PX field of the file object.

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
is defined for directory objects. The switching is controlled by the EXEC bit.
        0  "access" ACL
        1  "default" ACL
The bits for WRITE, READ, QUALIFIER shall be 0 with SWITCH_MARK.

The eventually needed qualifier is stored in one or more Qualifier Records.

  [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
      imediately after this record.
          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--
  { 'A', 'A',  28,   1,   0,
      0,   0,
      0,  19,  0x16,
               0x2E,   4, 'l', 'i', 's', 'a',
               0x34,
               0x4E,   7, 't', 'o', 'o', 'l', 'i', 'e', 's',
               0x54,
               0x64 }

Example: An entry with very long qualifier  u:His_Excellency_..._the_Boss:r--
               0x2C, 255, 'H', 'i', 's', '_', 'E', 'x', 'c', 'e', 'l', 'e',
                          ... 117 more bytes ...,
                       8, 't', 'h', 'e', '_', 'B', 'o', 's', 's', 

Example: User number 71 in numerical form gets rwx
               0xAF,   1,  71,
         Group number 65534 gets r-x
               0xCD,   2, 255, 254,


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

About Names and Numeric Identifiers
         
It makes an important difference whether qualifiers are represented as names
or as id numbers. By storing names (and usually wasting space) it is possible
to control permissions in a way that is portable between uncoordinated
computers as long as the human readable user/group names are present on both
sides. POSIX File ID numbers make most sense in backups which shall be read
by the same system which wrote it.
Rock Ridge can only record POSIX File Ids but not user or group names.

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
field ER, this has to be "dot" or (00). Other than with ER, a TRANSLATE entry
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.
The advised translation is: PX or AA Id number -> name -> local id number.

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 |

Example: User id number 1001 gets associated with user name "lisa"

               0x08,   13,   0,   233,3,0,0,   0,0,3,233, 'l', 'i', 's', 'a',


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

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.

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

The Extension Identifier field shall be "AAIP_0002" with Identifier Length 9.

The mandatory content form of the Extension Descriptor is 
"AA PROVIDES VIA AAIP 0.2 SUPPORT FOR ARBITRARY FILE ATTRIBUTES IN ISO 9660 IMAGES"
with possibly two letters other than "AA" at the start of the string.
The Description Length is 81.

The reader of AAIP shall take the actual name of the AA field from BP 19 and
BP 20 of the ER field.

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


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

Model Relations:

  Attribute List ------------- [1:0..1] ------------- ACL 
  [1:0..n]                                            [1:0..n]
  Arbitrary Attribute ( [1:0..1] ACL )                Entry
  [1:2..2n]                                           [1:0..1]
  Component  ( [1..m:1..n] AA Field )                 Qualifier
  [1:1..n]                                            <<  one of >> 
  Component Record                                  /       \       \
  [1..m:1..n]                          Translation Entry , Name , Numeric Id
  AA Field                                        |          |        |
                                               [1:1..n]   [1:1..n]   [1:1]
                                                    \        |       /
                                                      Qualifier Record

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

There was a draft AAIP 0.0 with ER signature "AAIP_2008A". It did not resemble
the existing field SL and therefore shall not be used by writers of ISO images.

-------------------------------------------------------------------------------
References:

ECMA-119  http://www.ecma-international.org/publications/files/ECMA-ST/Ecma-119.pdf

SUSP 1.12 ftp://ftp.ymi.com/pub/rockridge/susp112.ps

RRIP 1.12 ftp://ftp.ymi.com/pub/rockridge/rrip112.ps
(especially field SL)