"Fossies" - the Fresh Open Source Software Archive

Member "libisofs-1.5.4/doc/susp_aaip_2_0.txt" (8 Jul 2020, 20156 Bytes) of package /linux/misc/libisofs-1.5.4.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "susp_aaip_2_0.txt": 1.5.2_vs_1.5.4.

    1 
    2 
    3                  Arbitrary Attribute Interchange Protocol
    4 
    5                                 Version 2.0
    6 
    7                                 Mar 18 2009
    8 
    9                 Interchange of Persistent File Attributes
   10 
   11           by Thomas Schmitt    - mailto:scdbackup@gmx.net
   12           Libburnia project    - mailto:libburn-hackers@pykix.org
   13 
   14 
   15 AAIP is intended as companion of the Rock Ridge Interchange Protocol RRIP
   16 which under the general design of System Use Sharing Protocol SUSP extends
   17 ISO 9660 aka ECMA-119 filesystem semantics to match POSIX needs.
   18 
   19 Goal is to have for each file an arbitrary number of attributes which consist
   20 of two components (Name and Value) of arbitrary length and to have a compact
   21 representation of ACLs.
   22 
   23 This document describes a SUSP entry with Signature Word "AL" which collides
   24 neither with SUSP 1.12 nor with RRIP 1.12. The AL entry has been designed
   25 to be as similar to the RRIP entry SL as possible.
   26 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 needed to describe one component. The CE mechanism of SUSP shall be used to
   30 address enough storage if needed.
   31 
   32 AL entries and the ER entry of AAIP shall only be present if the ER entry
   33 of RRIP is present.
   34 
   35 -------------------------------------------------------------------------------
   36 
   37 System Entries Provided by this Specification
   38 
   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 more data bytes than with SL, though, and any of the 256 possible byte values. 
   45 The reader shall be prepared to detect and handle oversized data.
   46 
   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 The empty name indicates that the value is a compact representation of ACLs.
   52 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   [3] "BP 4 - System Use Entry Version" shall be 1 as in ISO 9660:7.1.1.
   67 
   68   [4] "BP 5 - Flags" shall contain bit field flags numbered 0 to 7 starting
   69       with the least significant bit as follows:
   70         0   CONTINUE  This AL entry continues in the next AL entry.
   71       All other bits shall be set to 0.
   72 
   73   [5] "BP 6 to Length - Component Area" shall contain Component Records
   74       as described below.
   75 
   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 All Component Records of a component except the last one shall have the
   84 CONTINUE flag set. A Component Record with CONTINUE set to 0 indicates the end
   85 of the component. An eventually following Component Record starts the next
   86 component.
   87 
   88 -------------------------------------------------------------------------------
   89 
   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".
   92 In case of discrepancies, RRIP 1.12 is the decisive specification. Please
   93 inform the author of this document if you find such a discrepancy.
   94 
   95 Component Records shall be recorded contiguously within each Component Area,
   96 starting in the first byte of the Component Area. The last Component Record
   97 in the Component Area of an AL System Use Entry may be continued in the
   98 Component Area of the next recorded AL System Use Entry in the same
   99 System Use Area.
  100 
  101 Each Component Record shall have the following format:
  102 
  103   [A] "BP 1 - Component Flags" shall contain bit field flags numbered 0 to 7,
  104       starting with the least significant bit, as follows:
  105         0   CONTINUE  This Component Record continues in the next
  106                       AL Component Record.
  107         all others are RESERVED and shall be 0.
  108 
  109   [B] "BP 2 - Component Length (LEN_CP)" shall specify as an 8-bit number the
  110       number of component bytes in the Component Record. This length shall not
  111       include the first two bytes of the Component Record.
  112       This field shall be recorded according to ISO 9660 Format section 7.1.1.
  113 
  114   [C] "BP 3 to 2 + LEN_CP - Component Content" shall contain the component
  115       bytes in the Component Record.
  116 
  117   | COMPONENT FLAGS | LEN_CP | COMPONENT BYTES |
  118 
  119 
  120 Example: Two pairs of "name"="long...content" and "one"="more" encoded as
  121          two AL entries
  122 
  123   Field 1 contains the Component Record of Name and one Component Record of
  124   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   Field 2 contains the rest of "long...content" and the complete second pair.
  129   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       0,   7, 'c', 'o', 'n', 't', 'e', 'n', 't',
  133       0,   3, 'o', 'n', 'e',
  134       0,   4, 'm', 'o', 'r', 'e' }
  135 
  136 -------------------------------------------------------------------------------
  137 
  138 Namespaces
  139 
  140 AAIP provides a short notation for namespaces which uses a single non-printable
  141 byte at the start of the name.
  142 Reserved start bytes of names are
  143     0x01 to 0x1F
  144 
  145 The names of extended file attributes are traditionally organized in
  146 namespaces, which get expressed as first part of an attribute name up to a
  147 period "." character. It is also tradition that names are printable text,
  148 single words and especially contain no 0-bytes.
  149 
  150 AAIP does not enforce the use of any namespace but it urges that names in the
  151 following registered namespaces are used according to traditions.
  152 
  153 The namespaces "system." and "user." are available with many file system
  154 types. "system." is file system dependent and often restricted in the
  155 choice of names. "user." is portable and allows to choose about any name.
  156 
  157 Namespace "isofs." is defined for internal use of AAIP enhanced ISO 9660
  158 file systems. Names in this namespace should be registered at
  159 libburnia-project.org.
  160 
  161 Further namespaces may be registered at libburnia-project.org.
  162 
  163 The reserved start bytes of names have the following meaning
  164     0x01   escape reserved character at start of name
  165     0x02   namespace "system."
  166     0x03   namespace "user."
  167     0x04   namespace "isofs."
  168     0x05   namespace "trusted."
  169     0x06   namespace "security."
  170     0x07 to 0x1F shall not be used yet.
  171 
  172 Examples:
  173    Name "user.abc" with and without short notation. Both is allowed.
  174       0,   4, 0x03,  'a',  'b',  'c'
  175       0    8,  'u',  's',  'e',  'r',  '.',  'a',  'b',  'c'
  176 
  177    Name "\003abc" (if really desired)
  178       0,   5, 0x01, 0x03,  'a',  'b',  'c'
  179 
  180 -------------------------------------------------------------------------------
  181 
  182 Specification of binary ACL representation as special Arbitrary Attribute
  183 
  184 The Name component of a binary ACL shall be of length 0.
  185 
  186 The Value shall be an arbitrary number of ACL Entries:
  187 
  188   [a] "BP 1 - Entry Flags" shall contain bit field flags numbered 0 to 7,
  189       starting with the least significant bit, as follows:
  190         0   EXEC      indicates that this entry grants execute permission
  191         1   WRITE                                      write permission
  192         2   READ                                       read permission
  193         3   QUALIFIER indicates that one or more Qualifier Records follow
  194         4 - 7  TYPE
  195                shall contain the tag type of the ACL entry as four bit code:
  196                  0  TRANSLATE      Entry for a global map of name to numeric id
  197                                    Qualifier is a record of number and text
  198                  1  ACL_USER_OBJ   Permissions of owning user (as of PX entry)
  199                  3  ACL_GROUP_OBJ  Permissions of owning group (as of PX entry)
  200                  5  ACL_MASK       Restricts 10, 3, and 12 via logical AND
  201                  6  ACL_OTHER      Permissions of non-listed, non-owning users
  202                  8  SWITCH_MARK    Switch from "access" ACL to "default" ACL
  203                 10  ACL_USER_N     Permissions of arbitrary user. Qualifier is
  204                                    the numeric user id (max. 4 bytes).
  205                 12  ACL_GROUP_N    Permissions of arbitrary group. Qualifier is
  206                                    the numeric group id (max. 4 bytes).
  207                 15  FUTURE_VERSION  Will indicate that this document
  208                                     does not apply to the entry.
  209                 The other values are reserved. Readers shall ignore them if
  210                 they are not aware of updates of this document which would
  211                 assign a meaning to them.
  212 
  213 The entries must match the permission bits of the PX entry. This shall obey the
  214 rule that ACL_USER_OBJ must match S_IRWXU, ACL_OTHER must match S_IRWXO,
  215 ACL_MASK - if present - must match S_IRWXG, else ACL_GROUP_OBJ must match
  216 S_IRWXG. If there is ACL_USER_N or ACL_GROUP_N there must also be ACL_MASK.
  217 
  218 A numeric qualifier is a binary number of variable length up to 4 bytes. The
  219 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 Optional TRANSLATE entries may associate user or group names with numeric
  224 ids to allow the reading system to remap the numeric ids. See below.
  225 The writer is not obliged to write them and the reader is not obliged to
  226 interpret them.
  227 
  228 The ACL entries belong to the "access" ACL of a file object. An optional
  229 SWITCH_MARK entry may direct further entries to the "default" ACL which
  230 is defined for directory objects. The EXEC bit of SWITCH_MARK shall be 1.
  231 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   [b] "BP 2 - Qualifier Record Head" shall be present only if QUALIFIER is set
  236       to 1. It shall give the number of Qualifier Bytes and eventually
  237       indicate that the qualifier continues in a Qualifier Record which comes
  238       immediately after this record.
  239           0 to 127   Q_LENGTH, the qualifier is complete by this record
  240         128 to 255   Q_LENGTH+128, the qualifier is continued by next record
  241       So a Qualifier Record can contain at most 127 Qualifier Bytes.
  242       This field shall be recorded according to ISO 9660 Format section 7.1.1.
  243 
  244   [c] "BP 3 to BP 2 + Q_LENGTH - Qualifier Bytes" shall be present only if
  245       QUALIFIER is set to 1 and hold the announced number of bytes of the
  246       user or group name.
  247 
  248   | ENTRY FLAGS [ | QUALIFIER HEAD | QUALIFIER BYTES | ]
  249 
  250  
  251 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       0,  11, 0x16,
  256               0xAE,   1, 123,
  257               0x34,
  258               0xCE,   2, 255, 254,
  259               0x54,
  260               0x64 }
  261 
  262 Example: "Access" ACL and "default" ACL (0x81 is the switch mark)
  263          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       0,   0,
  266       0,  11, 0x17, 0x35, 0x65,
  267               0x81,
  268               0x17, 0x35, 0x57, 0x65,
  269               0xA7,    1, 123 }
  270 
  271 -------------------------------------------------------------------------------
  272 
  273 Association of Names and Numeric Identifiers
  274          
  275 The entry flag value 0x08 TRANSLATE is not a ACL entry of the hosting object
  276 but rather a global hint about the relation of roles, names and numeric ids.
  277 If it is recorded at all, then it shall be recorded with the first Directory
  278 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 may not appear in the root of directory sub trees.
  281 
  282 An interested reader shall examine the Arbitrary Attributes of this Directory
  283 Entry in order to collect a translation table.
  284 The advised translation is: PX or AL Id number -> name -> local id number.
  285 
  286 The Qualifier Bytes of a TRANSLATE entry shall have the following format:
  287 
  288   [i] "BP 0 - Role" shall tell whether it is about a user name (role 0) or
  289       a group name (role 1). Other values are not allowed.
  290 
  291  [ii] "BP 1 to BP 8 - Numeric Id" shall hold the 32 bit POSIX Id number of the
  292       entry. This field shall be recorded according to ISO 9660:7.3.3.
  293 
  294 [iii] "BP 9 to End Of Qualifier - Name" shall hold the name bytes of this
  295       entry.
  296 
  297   | ROLE | NUMERIC ID | NAME |
  298 
  299 Example: User id number 123 gets associated with user name "lisa"
  300 
  301                0x08,  13,  0,  123,0,0,0,   0,0,0,123,  'l', 'i', 's', 'a',
  302 
  303 
  304 Example: A very long qualifier naming "His_Excellency_..._the_Boss" as user #1.
  305          This needs two qualifier records.
  306                0x08, 255,   0,   1,0,0,0,   0,0,0,1,
  307                           'H', 'i', 's', '_', 'E', 'x', 'c', 'e', 'l', 'e',
  308                                      ... 108 more bytes ...
  309                        8, 't', 'h', 'e', '_', 'B', 'o', 's', 's', 
  310 
  311 -------------------------------------------------------------------------------
  312 
  313 Specification of the ER System Use Entry Values for AAIP:
  314 
  315 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 If for some reason compliance with SUSP-1.10 is intended, then this ER entry
  319 and the ES entries must not be present, although SUSP-1.10 would allow ER.
  320 (See below: Compatibility considerations.)
  321 
  322 The Extension Version number for this version of AAIP shall be 1.
  323 
  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 The Description Length is 81.
  329 
  330 The recommended content of the Extension Source is
  331 "PLEASE CONTACT THE LIBBURNIA PROJECT VIA LIBBURNIA-PROJECT.ORG".
  332 The corresponding Source Length is 62.
  333 
  334 -------------------------------------------------------------------------------
  335 
  336                         Compatibility Considerations
  337 
  338 This extension is supposed not to disturb any reader system which complies
  339 to SUSP-1.10:
  340 "6.2 Requirements for a Receiving System
  341  [...]
  342  Any System Use Field which the receiving system does not recognize
  343  is to be ignored and skipped."
  344 
  345 SUSP-1.12 extends this prescription by:
  346 "Any System Use Entry, with the exception of the set of System Use Entries
  347  defined in this document, following an "ES" System Use Entry that indicates
  348  an extension specification which the receiving system does not recognize
  349  shall be ignored and skipped."
  350 
  351 According to SUSP-1.12 the ER entry is mandatory for a conformant extension.
  352 It also prescribes that in the case that ER entries of RRIP and AAIP are 
  353 present, then ES entries shall be used to separate RRIP entries from AAIP
  354 entries.
  355 SUSP-1.12 frowns on extensions which are not announced by ER. Nevertheless
  356 is does not totally outrule them.
  357 
  358 SUSP-1.10 does not specify ES entries at all and allows to have extension
  359 entries without announcing them by an ER entry. So if a second ER entry is
  360 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 Model Relations:
  366 
  367   Attribute List ------------- [1:0..1] ------------- ACL
  368   [1:0..n]                                            [1:0..n] 
  369   Arbitrary Attribute ( [1:0..1] ACL )                Entry
  370   [1:2..2n]                                           [1:0..1]
  371   Component  ( [1..m:1..n] AL Field )                 Qualifier
  372   [1:1..n]                                            <<  one of >>
  373   Component Record                                  /              \
  374   [1..m:1..n]                              Translation Entry ,  Numeric Id
  375   AL Field                                         |                 |
  376                                                  [1:1..n]          [1:1]
  377                                                      \              /
  378                                                       Qualifier Record
  379 
  380 -------------------------------------------------------------------------------
  381 Revoked drafts:
  382 
  383 The following outdated versions may be interpreted at read time but they
  384 shall not be written any more.
  385 
  386                                     AAIP-1.0
  387 
  388 Previous versions up to AAIP 1.0 used field signature "AA" rather than "AL".
  389 This nearly collides with "Apple ISO 9660 Extensions". The Apple "AA" field of
  390 version 1 has a length of 7, whereas the shortest first AAIP field "AA" had
  391 length 9.
  392 
  393 Beginning with AAIP 2.0, the field name has been changed to "AL".
  394 If a reader interprets old AAIP "AA" fields, then it must take precautions to
  395 distinguish them from Apple "AA" fields. But it is well compliant with AAIP 2.0
  396 to just ignore any kind of "AA" fields.
  397 
  398 AAIP 1.0 had ER signature "AAIP_0100".
  399 
  400                                     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 Regrettably no reader (kernel) was found which neatly interprets ES. Many do
  406 not even recognize the RRIP-1.12 ER signatures "IEEE_P1282", "IEEE_1282".
  407 
  408 AAIP 0.2 defined two ACL types which did not make it into AAIP 1.0
  409                  2  ACL_USER       of arbitrary user, with name as qualifier
  410                  4  ACL_GROUP      of arbitrary group, with name as qualifier
  411 Their job was transferred to ACL_USER_N and ACL_GROUP_N which have numeric
  412 qualifiers.
  413 
  414                                     AAIP-0.0
  415 
  416 There was a draft AAIP 0.0 with ER signature "AAIP_2008A". It did not resemble
  417 the existing entry SL and was never implemented.
  418 
  419 -------------------------------------------------------------------------------
  420 References:
  421 
  422 ECMA-119 aka ISO 9660
  423   http://www.ecma-international.org/publications/files/ECMA-ST/Ecma-119.pdf
  424 
  425 SUSP 1.12 (entries CE , PD , SP , ST , ER , ES)
  426   ftp://ftp.ymi.com/pub/rockridge/susp112.ps
  427 
  428 RRIP 1.12 (entries PX , PN , SL , NM , CL , PL , RE , TF , SF , obsolete: RR)
  429   ftp://ftp.ymi.com/pub/rockridge/rrip112.ps
  430 
  431 Apple ISO 9660 Extensions (entries AA and BA)
  432   http://developer.apple.com/technotes/fl/fl_36.html
  433 
  434 Amiga AS entry
  435   http://www.estamos.de/makecd/Rock_Ridge_Amiga_Specific
  436 
  437 zisofs entry ZF (prepared by zisofs-tools, written by mkisofs)
  438   http://freshmeat.net/projects/zisofs-tools/
  439 
  440 Program mkisofs emits entry XA
  441   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 It shall only be modified in sync with libisofs and other software which
  448 makes use of AAIP. Please mail change requests to mailing list
  449 <libburn-hackers@pykix.org> or to the copyright holder in private.
  450 Only if you cannot reach the copyright holder for at least one month it is
  451 permissible to modify this text under the same license as the affected
  452 copy of libisofs.
  453 If you do so, you commit yourself to taking reasonable effort to stay in 
  454 sync with the other interested users of this text.
  455