diff --git a/doc/susp_aaip_0_2.txt b/doc/susp_aaip_1_0.txt similarity index 74% rename from doc/susp_aaip_0_2.txt rename to doc/susp_aaip_1_0.txt index 4ebf1cd..549ef03 100644 --- a/doc/susp_aaip_0_2.txt +++ b/doc/susp_aaip_1_0.txt @@ -2,8 +2,9 @@ Arbitrary Attribute Interchange Protocol - Draft version 0.2 - Feb 10 2009 + Version 1.0 + + Feb 19 2009 Interchange of Persistent File Attributes @@ -48,9 +49,8 @@ an even number of components. Each two consequtive components form a pair of Name and Value. 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 -represent names in particular name spaces. See below: Name Spaces. +represent names in particular namespaces. See below: Namespaces. The meaning of any other names or name parts is not specified by this document. All AA entries except the last one shall have the CONTINUE flag set. An AA @@ -137,29 +137,29 @@ Example: Two pairs of "name"="long...content" and "one"="more" encoded as ------------------------------------------------------------------------------- -Name Spaces +Namespaces 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 -The names of extended file attributes are traditionally organized in name -spaces, which get expressed as first part of an attribute name up to a +The names of extended file attributes are traditionally organized in +namespaces, which get expressed as first part of an attribute name up to a period "." character. It is also tradition that names are printable text, single words and especially contain no 0-bytes. -AAIP does not enforce the use of any name space but it urges that names in the -following registered name spaces are used according to traditions. +AAIP does not enforce the use of any namespace but it urges that names in the +following registered namespaces are used according to traditions. -The name spaces "system." and "user." are available with many file system +The namespaces "system." and "user." are available with many file system types. "system." is file system dependent and often restricted in the choice of names. "user." is portable and allows to choose about any name. -Name space "isofs." is defined for internal use of AAIP enhanced ISO 9660 -file systems. Names in this name space should be registered at libburnia.org. +Namespace "isofs." is defined for internal use of AAIP enhanced ISO 9660 +file systems. Names in this namespace should be registered at libburnia.org. -Further name spaces may be registered at libburnia.org. +Further namespaces may be registered at libburnia.org. The reserved start bytes of names have the following meaning 0x01 escape reserved character at start of name @@ -169,12 +169,12 @@ The reserved start bytes of names have the following meaning 0x05 to 0x1F shall not be used yet. Examples: - Name "user.abc" - 0, 4, 0x03, 'a', 'b', 'c' + 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' + Name "\003abc" (if really desired) - 0, 5, 0x01, 0x03, 'a', 'b', 'c' - Default mapping of AAIP name component record {0, 4, 0x0f, 'a', 'b', 'c'} - "user.aaip0F_abc" + 0, 5, 0x01, 0x03, 'a', 'b', 'c' ------------------------------------------------------------------------------- @@ -192,32 +192,32 @@ The Value shall be an arbitrary number of ACL Entries: 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 entry) - 2 ACL_USER of arbitrary user, with name as qualifier - 3 ACL_GROUP_OBJ permissions of owning group (as of PX entry) - 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 + 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 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. -The entries ACL_USER_OBJ, ACL_GROUP_OBJ, ACL_OTHER must match the permission -bits of the PX entry. This shall obey the peculiar 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 must match S_IRWXG. -If there is ACL_USER_OBJ or ACL_GROUP_OBJ there must also be ACL_MASK. +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. -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 entries. The ids of owning user -and owning group shall be taken from the PX entry of the file object. +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" +resp. "POSIX File Group ID" as also used in RRIP PX entries. The ids of owning +user and owning group shall be taken from the PX entry 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. @@ -226,12 +226,10 @@ 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. +is defined for directory objects. The EXEC bit of SWITCH_MARK shall be 1. +The bits for WRITE, READ, QUALIFIER shall be 0. -The eventually needed qualifier is stored in one or more Qualifier Records. +An 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 @@ -250,38 +248,29 @@ The eventually needed qualifier is stored in one or more Qualifier Records. Example: From man 5 acl: u::rw-,u:lisa:rw-,g::r--,g:toolies:rw-,m::r--,o::r-- - { 'A', 'A', 28, 1, 0, + "lisa" has user number 123, "toolies" has group number 65534 + { 'A', 'A', 20, 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, + 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 + { 'A', 'A', 20, 1, 0, + 0, 0, + 0, 11, 0x17, 0x35, 0x65, + 0x81, + 0x17, 0x35, 0x57, 0x65, + 0xA7, 1, 123 } ------------------------------------------------------------------------------- -About Names and Numeric Identifiers +Association of 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 @@ -306,11 +295,18 @@ The Qualifier Bytes of a TRANSLATE entry shall have the following format: | ROLE | NUMERIC ID | NAME | -Example: User id number 1001 gets associated with user name "lisa" +Example: User id number 123 gets associated with user name "lisa" - 0x08, 13, 0, 233,3,0,0, 0,0,3,233, 'l', 'i', 's', 'a', + 0x08, 13, 0, 123,0,0,0, 0,0,0,123, 'l', 'i', 's', 'a', +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', + ------------------------------------------------------------------------------- Specification of the ER System Use Entry Values for AAIP: @@ -324,10 +320,10 @@ and the ES entries must not be present, although SUSP-1.10 would allow ER. 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 Extension Identifier field shall be "AAIP_0100" 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" +"AA PROVIDES VIA AAIP 1.0 SUPPORT FOR ARBITRARY FILE ATTRIBUTES IN ISO 9660 IMAGES" The Description Length is 81. The recommended content of the Extension Source is @@ -365,20 +361,19 @@ AAIP ER and the ES entries. But if there is the AAIP ER then there must be ES at the appropriate places. Else the format would explicitely violate SUSP-1.12. ------------------------------------------------------------------------------- - Model Relations: - Attribute List ------------- [1:0..1] ------------- ACL - [1:0..n] [1:0..n] + 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] - \ | / + [1:1..n] << one of >> + Component Record / \ + [1..m:1..n] Translation Entry , Numeric Id + AA Field | | + [1:1..n] [1:1] + \ / Qualifier Record ------------------------------------------------------------------------------- @@ -387,9 +382,15 @@ Revoked drafts: There was a draft AAIP 0.0 with ER signature "AAIP_2008A". It did not resemble the existing entry SL and therefore shall not be used by writers of ISO images. -AAIP 0.2 once allowed to announce and use a different signature than "AA". -This has been revoked because ES entries serve the purpose to distinguish -AAIP entries from eventual "AA" entries of any other extension. +AAIP 0.2 with ER signature "AAIP_0002" allowed to announce and use a different +signature than "AA". This has been revoked because ES entries serve the purpose +to distinguish AAIP entries from eventual "AA" entries of any other extension. + +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. ------------------------------------------------------------------------------- References: @@ -402,8 +403,3 @@ RRIP 1.12 ftp://ftp.ymi.com/pub/rockridge/rrip112.ps (especially entry SL) ------------------------------------------------------------------------------- -Pending considerations: - -- shall the tag types ACL_USER and ACL_GROUP with non-numeric qualifier be - revoked ? - diff --git a/libisofs/aaip-os-dummy.c b/libisofs/aaip-os-dummy.c index 8058b6b..089c469 100644 --- a/libisofs/aaip-os-dummy.c +++ b/libisofs/aaip-os-dummy.c @@ -5,11 +5,14 @@ Idle placeholder for: Arbitrary Attribute Interchange Protocol , system adapter for getting and - setting of ACLs and XFS-style Extended Attributes. + setting of ACLs and xattr. See aaip-os-linux.c for a real implementation of this interface. To be included by aaip_0_2.c + + Copyright (c) 2009 Thomas Schmitt, libburnia project, GPLv2 + */ #include diff --git a/libisofs/aaip-os-freebsd.c b/libisofs/aaip-os-freebsd.c index e3dc320..e4ae344 100644 --- a/libisofs/aaip-os-freebsd.c +++ b/libisofs/aaip-os-freebsd.c @@ -3,9 +3,12 @@ aaip-os-freebsd.c Arbitrary Attribute Interchange Protocol , system adapter for getting and - setting of ACLs and XFS-style Extended Attributes. + setting of ACLs and ixattr. To be included by aaip_0_2.c + + Copyright (c) 2009 Thomas Schmitt, libburnia project, GPLv2 + */ #include diff --git a/libisofs/aaip-os-linux.c b/libisofs/aaip-os-linux.c index ea1c597..493d8ee 100644 --- a/libisofs/aaip-os-linux.c +++ b/libisofs/aaip-os-linux.c @@ -3,9 +3,12 @@ aaip-os-linux.c Arbitrary Attribute Interchange Protocol , system adapter for getting and - setting of ACLs and XFS-style Extended Attributes. + setting of ACLs and xattr. To be included by aaip_0_2.c + + Copyright (c) 2009 Thomas Schmitt, libburnia project, GPLv2 + */ #include diff --git a/libisofs/aaip_0_2.c b/libisofs/aaip_0_2.c index 533c212..0874943 100644 --- a/libisofs/aaip_0_2.c +++ b/libisofs/aaip_0_2.c @@ -1,12 +1,14 @@ /* - Arbitrary Attribute Interchange Protocol , AAIP version 0.2 - Demonstration implementation of encoding and decoding EA and ACL. + Arbitrary Attribute Interchange Protocol , AAIP versions 0.2 and 1.0. + Implementation of encoding and decoding xattr and ACL. See test/aaip_0_2.h http://libburnia-project.org/wiki/AAIP + Copyright (c) 2009 Thomas Schmitt, libburnia project, GPLv2 + */ #include @@ -242,7 +244,7 @@ static ssize_t aaip_encode_acl_text(char *acl_text, mode_t st_mode, /* Convert an ACL text as of acl_to_text(3) into the value of an Arbitrary - Attribute. According to AAIP 0.2 this value is to be stored together with + Attribute. According to AAIP this value is to be stored together with an empty name. @param acl_text The ACL in long text form @param st_mode The stat(2) permission bits to be used with flag bit3 diff --git a/libisofs/aaip_0_2.h b/libisofs/aaip_0_2.h index 452ff51..5a1f57a 100644 --- a/libisofs/aaip_0_2.h +++ b/libisofs/aaip_0_2.h @@ -1,13 +1,15 @@ /* - Arbitrary Attribute Interchange Protocol , AAIP version 0.2 - Demonstration program for encoding and decoding EA and ACL. + Arbitrary Attribute Interchange Protocol , AAIP versions 0.2 and 1.0. + Implementation for encoding and decoding xattr and ACL. See http://libburnia-project.org/wiki/AAIP - or doc/susp_aaip_0_2.txt + or doc/susp_aaip_1_0.txt - test/aaip_0.2.h - Public declarations + test/aaip_0_2.h - Public declarations + + Copyright (c) 2009 Thomas Schmitt, libburnia project, GPLv2 */ @@ -39,7 +41,7 @@ size_t aaip_encode(size_t num_attrs, char **names, /* ------ ACL representation ------ */ /* Convert an ACL from long text form into the value of an Arbitrary - Attribute. According to AAIP 0.2 this value is to be stored together with + Attribute. According to AAIP this value is to be stored together with an empty name. @param acl_text The ACL in long text form @param st_mode The stat(2) permission bits to be used with flag bit3 @@ -61,7 +63,7 @@ int aaip_encode_acl(char *acl_text, mode_t st_mode, /* Convert an "access" and "default" ACL from long text form into the value - of an Arbitrary Attribute. According to AAIP 0.2 this value is to be stored + of an Arbitrary Attribute. According to AAIP this value is to be stored together with an empty name. @param a_acl_text The "access" ACL in long text form. Submit NULL if there is no such ACL to be encoded. @@ -414,7 +416,7 @@ int aaip_get_decoded_attrs(struct aaip_state **handle, size_t *num_attrs, /* ------ ACL representation ------ */ -/* Convert an AAIP 0.2 ACL attribute value into the long text form of ACL. +/* Convert an AAIP ACL attribute value into the long text form of ACL. @param data The raw data to decode @param num_data Number of data bytes provided @param consumed Returns the number of consumed data bytes