Subject: (#3) VCAR Proposal

From: Bernard Desruisseaux <[email-masked]>
Date: Wed, 13 Feb 2002 12:06:11 -0500

Here's the third version of my proposal on VCAR.

Highlight of changes:

- Added missing "To:" and "Subject:" fields in each
  section.

- Changed the upn-filter rule part to make use of the
  rule part dot-atom-text defined in RFC 2822.

- Changed examples in UPN-FILTER to reflect the fact
  that VAGENDA can have more than one OWNER.  Changed
  description of examples to use "null" and "non-null"
  instead of "unamed and "named" to be consistent with
  section 2.4.4 "CAP Session Identity" of the draft.

- Changed examples to use new CAP-QL operator "IN"
  and new functions CAL-OWNERS() and CURRENT-CALID().

- Remove double quote (") in values of the NAME
  property.

- Changed references to value type 'capselect' to 'CAL-QUERY'
  and references to rule part 'capselect' to 'cal-query'.

- Changed description of the VCAR with "NAME:No CAR At All"
  to read "should be specified with great care" instead of
  "should not be specified".

- Changed CARIDs to be unique.

- Renamed section for the CARID property.

- Changed purpose of GRANT and DENY to talk of UPN.

- Added new DECREED property.

- Specified that the draft only suggest defintions for
  the VCAR components with the predefined CARID.

Open issues:

- I've used "iana-prop" in the ABNF of VCAR and VRIGHT but
  it's not defined anywhere.  Is "x-prop" sufficient or
  shall we defined "iana-prop" ourselves?

- Should we add "iana-comp / x-comp" in the ABNF of
  VCAR and VRIGHT?

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

x.x.1 Property Value Data Types

x.x.1.1 UPN Filter

   To: [email-masked]

   Subject: Registration of text/calendar MIME value type UPN-FILTER

   Value Name: UPN-FILTER

   Purpose: This value type is used to identify values that contain
   a user principal name filter.

   Formal Definition: The value type is defined by the following
   notation:

     upn-filter    = "OWNER" /
                     "NONOWNER" /
                     "*" /
                     [ "*" / dot-atom-text ] "@" ( "*" / dot-atom-text )

                    ; dot-atom-text is defined in RFC 2822

   Description: The value is used to match user principal names (UPNs).

   Example: The following are examples of this value type:

    OWNER       Matches the UPNs equal to any instance
                of the OWNER property of the VAGENDA in
                which the encapsulating VCAR is stored.

    NONOWNER    Matches all UPNs different from all
                instances of the OWNER property of the
                VAGENDA in which the encapsulating VCAR
                is stored.

    *           Matches all UPNs.

    @           Matches the UPN of anonymous CUs
                belonging to the null realm

    @*          Matches the UPN of anonymous CUs
                belonging to any non-null realm

    @realm      Matches the UPN of anonymous CUs
                belonging to the specified realm

    *@*         Matches the UPN of non-anonymous CUs
                belonging to any non-null realm

    *@realm     Matches the UPN of non-anonymous CUs
                belonging to the specified realm

    user@realm  Matches the UPN of the specified CU
                belonging to the specified realm

    user@*      Matches the UPN of the specified CU
                belonging to any non-null realm

x.x.2 Calendar Components

x.x.2.1 Calendar Access Right Component

   To: [email-masked]

   Subject: Registration of text/calendar MIME component VCAR

   Component Name: "VCAR"

   Purpose: Provide a grouping of calendar access rights.

   Format Definition: A "VCAR" calendar component is defined by the
   following notation:

     carc    =  "BEGIN" ":" "VCAR" CRLF
                carprop 1*rightc
                "END" ":" "VCAR" CRLF

     carprop = 1*(

             ; 'carid' is REQUIRED,
             ; but MUST NOT occur more than once

             carid /

             ; the following are OPTIONAL,
             ; and MAY occur more than once

             name / x-prop / iana-prop
             )

   Description: A "VCAR" calendar component is a grouping of component
   properties, and "VRIGHT" calendar components, that represents access
   rights granted or denied to calendar users.

   The "CARID" property specifies the local identifier for the "VCAR"
   calendar component.  The "NAME" property specifies a localizable
   display name.

   Example: In the following example, the UPN "[email-masked]" is given
   read access to the "DTSTART" and "DTEND" VEVENT properties.  No other
   access is specified:

     BEGIN:VCAR
     CARID:xyzzy-001
     NAME:View Start and End Times
     BEGIN:VRIGHT
     GRANT:[email-masked]
     PERMISSION:READ
     SCOPE:SELECT DTSTART,DTEND FROM VEVENT
     END:VRIGHT
     END:VCAR

   In this example, all UPNs are given read access to "DTSTART" and
   "DTEND" properties of VEVENT components. "All CUs and UGs" are
   specified by the UPN value "*".  Note that this enumerated UPN
   value is not in quotes:

     BEGIN:VCAR
     CARID:xyzzy-002
     NAME:View Start and End Times 2
     BEGIN:VRIGHT
     GRANT:*
     PERMISSION:READ
     SCOPE:SELECT DTSTART,DTEND FROM VEVENT
     END:VRIGHT
     END:VCAR

   In this example, rights are specified for all UPNs to read VEVENT
   components classified as PUBLIC:

     BEGIN:VCAR
     CARID:xyzzy-003
     NAME:View PUBLIC Start and End Times
     BEGIN:VRIGHT
     GRANT:*
     PERMISSION:READ
     SCOPE:SELECT DTSTART,DTEND FROM VEVENT WHERE CLASS = 'PUBLIC'
     END:VRIGHT
     END:VCAR

   In this example, rights are specified for all UPNs to read or modify
   existing VEVENT components classified as PUBLIC:

     BEGIN:VCAR
     CARID:xyzzy-004
     NAME:Read and Modify PUBLIC Calendar Entries
     BEGIN:VRIGHT
     GRANT:*
     PERMISSION:READ
     PERMISSION:MODIFY
     SCOPE:SELECT * FROM VEVENT WHERE CLASS = 'PUBLIC'
     END:VRIGHT
     END:VCAR

   In these examples, full calendar access rights are given to the
OWNER,
   and a hypothetical administrator is given access rights to specify
   calendar access rights.  If no other rights are specified, only these
   two UPNs can specify calendar access rights:

     BEGIN:VCAR
     CARID:xyzzy-005
     NAME:Only OWNER or ADMIN Settable CARs
     BEGIN:VRIGHT
     GRANT:OWNER
     PERMISSION:*
     SCOPE:SELECT * FROM VAGENDA
     END:VRIGHT
     BEGIN:VRIGHT
     GRANT:[email-masked]
     PERMISSION:*
     SCOPE:SELECT * FROM VCAR
     RESTRICTION:SELECT * FROM VCAR
     END:VRIGHT
     END:VCAR

   In this example, rights to write, read, modify or delete calendar
   access rights are denied to all UPNs.  This example would disable
   providing different access rights to the calendar store or calendar.
   This calendar access right should be specified with great care,
   as it remove the ability to change calendar access; even for the
   owner or administrator:

     BEGIN:VCAR
     CARID:xyzzy-006
     NAME:No CAR At All
     BEGIN:VRIGHT
     DENY:*
     PERMISSION:*
     SCOPE:SELECT * FROM VCAR
     END:VRIGHT
     END:VCAR

x.x.2.2 VRIGHT Calendar Component

   To: [email-masked]

   Subject: Registration of text/calendar MIME component VRIGHT

   Component Name: "VRIGHT"

   Purpose: Provide a grouping of component properties that describe an
   access right.

   Format Definition: A "VRIGHT" calendar component is defined by the
   following notation:

     rightc    =  "BEGIN" ":" "VRIGHT" CRLF
                  rightprop
                  "END" ":" "VRIGHT" CRLF

     rightprop = 2*(

               ; either 'grant' or 'deny' MUST
               ; occur at least once
               ; and MAY occur more than once

               grant / deny /

               ; 'permission' MUST occur at least once
               ; and MAY occur more than once

               permission /

               ; the following are optional,
               ; and MAY occur more than once

               scope / restriction / x-prop / iana-prop

               )

   Description: A "VRIGHT" calendar component is a grouping of calendar
   access right component properties.

   The "GRANT" property specifies the CU or UG to whom a calendar access
   right is granted.  The "DENY" property specifies the CU or UG to whom
   a calendar access right is denied.  The "PERMISSION" property
specifies
   the actual permission being set.  The "SCOPE" property identifies the
   calendar store properties, calendar properties, calendar components,
   component properties to which the access right applies.  The
   "RESTRICTION" property specifies restriction on the value that may
   take calendar store properties, calendar properties, calendar
components,
   and component properties after a WRITE or MODIFY operation.  Values
   MUST match all the instances of the RESTRICTION property to be valid.

x.x.3 Component Properties

   The following properties can appear within calendar components, as
   specified by each component property definition.

x.x.3.1 Descriptive Component Properties

   The following properties specify descriptive information about
   calendar components.

x.x.3.1.1 Name Component Property

   To: [email-masked]

   Subject: Registration of text/calendar MIME property NAME

   Property Name: NAME

   Purpose: This property provides a localizable display name for a
   calendar component.

   Value Type: TEXT

   Property Parameters: Non-standard property parameters can be
   specified on this property.

   Conformance: This property can be specified in "VAGENDA" and
   "VCAR" calendar components.

   Description: This property is used in the "VAGENDA" and in the
   "VCAR" calendar components to specify a localizable display name.

   Format Definition: The property is defined by the following notation:

     name = "NAME" nameparam ":" text CRLF

     nameparam = *(
                    ; the following is optional,
                    ; but MUST NOT occur more than once

                    ( ";" languageparam ) /

                    ; the following is optional,
                    ; and MAY occur more than once

                    ( ";" xparam )
                  )

   Example: The following is an example of this property:

     NAME:Restrict Guests From Creating ALARMs On Events

x.x.3.2 Calendar Access Right Component Properties

x.x.3.2.1 VCAR Identifier Component Property

   To: [email-masked]

   Subject: Registration of text/calendar MIME property CARID

   Property Name: CARID

   Purpose: This property specifies the identifier for an access right
   calendar component.

   Value Type: TEXT

   Property Parameters: Non-standard property parameters can be
   specified on this property.

   Conformance: This property MUST be specified once in a "VCAR"
   calendar component.

   Description: This property is used in the "VCAR" calendar component
   to specify an identifier.

   Format Definition: The property is defined by the following notation:

     carid      = "CARID" caridparam ":" text CRLF

     caridparam = *( ";" xparam )

   Example: The following is an example of this property:

     CARID:xyzzy-007

x.x.3.2.2 VCAR Decreed Component Property

   To: [email-masked]

   Subject: Registration of text/calendar MIME property DECREED

   Property Name: DECREED

   Purpose: This property specifies if an access right calendar
   component is decreed or not.

   Value Type: BOOLEAN

   Property Parameters: Non-standard property parameters can be
   specified on this property.

   Conformance: This property MAY be specified once in a "VCAR"
   calendar component.

   Description: This property is used in the "VCAR" calendar component
   to specify whether the component is decreed or not.

   Format Definition: The property is defined by the following notation:

     decreed      = "DECREED" decreedparam ":" boolean CRLF

     decreedparam = *( ";" xparam )

   Example: The following is an example of this property:

     DECREED:TRUE

x.x.3.3 Right Component Properties

x.x.3.3.1 Grant Component Property

   To: [email-masked]

   Subject: Registration of text/calendar MIME property GRANT

   Property Name: GRANT

   Purpose: This property identifies the UPN(s) being granted
	access in the VRIGHT component.

   Value Type: UPN-FILTER

   Property Parameters: Only non-standard property parameters can be
   specified on this property.

   Conformance: This property can be specified in "VRIGHT" calendar
   components.

   Description: This property is used in the "VRIGHT" calendar component
   to specify the CU or UG being granted access.

   Format Definition: The property is defined by the following notation:

     grant     = "GRANT" grantparam ":" upn-filter CRLF

     grantparam  = *( ";" xparam )

   Example: The following are examples of this property:

     GRANT:*

     GRANT:[email-masked]

x.x.3.3.2 Deny Component Property

   To: [email-masked]

   Subject: Registration of text/calendar MIME property DENY

   Property Name: DENY

   Purpose: This property identifies the UPN(s) being denied
	access in the VRIGHT component.

   Value Type: UPN-FILTER

   Property Parameters: Only non-standard property parameters can be
   specified on this property.

   Conformance: This property can be specified in "VRIGHT" calendar
   components.

   Description: This property is used in the "VRIGHT" calendar component
   to define the CU or UG being denied access.

   Format Definition: The property is defined by the following notation:

     deny       = "DENY" denyparam ":" upn-filter CRLF

     denyparam  = *( ";" xparam )

   Example: The following are examples of this property:

     DENY:*

     DENY:[email-masked]

x.x.3.3.3 Permission Component Property

   To: [email-masked]

   Subject: Registration of text/calendar MIME property PERMISSION

   Property Name: PERMISSION

   Purpose: This property defines a permission that is granted or
   denied in a VRIGHT component.

   Value Type: TEXT

   Property Parameters: Only non-standard property parameters can be
   specified on this property.

   Conformance: This property can be specified in "VRIGHT" calendar
   components.

   Description: This property is used in the "VRIGHT" calendar component
   to define a permission that is granted or denied.

   Format Definition: The property is defined by the following notation:

     perm      = "PERMISSION" permparam ":" permvalue CRLF

     permparam = *( ";" xparam )

     permvalue = ( "READ" / "WRITE" / "DELETE" / "MODIFY" / all )

     all         = "*"

   Example: The following is an example of this property:

     PERMISSION:READ

x.x.3.3.4 Scope Component Property

   To: [email-masked]

   Subject: Registration of text/calendar MIME property SCOPE

   Property Name: SCOPE

   Purpose: This property identifies the objects in the CS to which
   the access rights applies.

   Value Type: CAL-QUERY

   Property Parameters: Only non-standard property parameters can be
   specified on this property.

   Conformance: This property can be specified in "VRIGHT" calendar
   components.

   Description: This property is used in the "VRIGHT" calendar component
   to define the set of objects subject to the access right being
defined.

   Format Definition: The property is defined by the following notation:

     scope      = "SCOPE" scopeparam ":" cal-query CRLF

     scopeparam = *( ";" xparam )

   Example: The following is an example of this property:

     SCOPE:SELECT DTSTART,DTEND FROM VEVENT WHERE CLASS = 'PUBLIC'

x.x.3.3.5 Restriction Component Property

   To: [email-masked]

   Subject: Registration of text/calendar MIME property RESTRICTION

   Property Name: RESTRICTION

   Purpose: This property defines restrictions on the value that
   may take new or existent calendar components.

   Value Type: CAL-QUERY

   Property Parameters: Only non-standard property parameters can be
   specified on this property.

   Conformance: This property can be specified in "VRIGHT" calendar
   components, but only when the PERMISSION property is set to
   "WRITE", "MODIFY", or "*".

   Description: This property is used in the "VRIGHT" calendar component
   to define restrictions on the calendar components that can be written
   (i.e., by using the "create" or "move" commands) as well as on the
   values that may take existent calendar store properties, calendar
   properties, calendar components, and component properties (i.e.,
   by using the "modify" command).  Accepted values MUST match the
   specified RESTRICTION.

   Format Definition: The property is defined by the following notation:

     restrict      = "RESTRICTION" restrictparam ":" cal-query CRLF

     restrictparam = *( ";" xparam )

   Example: The following are examples of this property:

     RESTRICTION:SELECT * FROM VCALENDAR WHERE METHOD = 'REQUEST'

     RESTRICTION:SELECT * FROM VEVENT WHERE ORGANIZER = SELF()

     RESTRICTION:SELECT * FROM VEVENT WHERE
CONTAINS(CATEGORIES,'BUSINESS')

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

Predefined calendar access CARIDs that MUST be implemented are:

CARID:READBUSYTIMEINFO - grants all authenticated users the
right to read VFREEBUSY components.  Suggested definition for
this VCAR:

   BEGIN:VCAR
   CARID:READBUSYTIMEINFO
   BEGIN:VRIGHT
   GRANT:*
   PERMISSION:READ
   SCOPE:SELECT * FROM VFREEBUSY
   END:VRIGHT
   END:VCAR

CARID:REQUESTONLY - grants to users other than the owner of
the calendar the right to write new events with the property
METHOD set to REQUEST.  Suggested definition for this VCAR:

   BEGIN:VCAR
   CARID:REQUESTONLY
   BEGIN:VRIGHT
   GRANT:NONOWNER
   PERMISSION:WRITE
   RESTRICTION:SELECT * FROM VCALENDAR WHERE METHOD = 'REQUEST'
   END:VRIGHT
   END:VCAR

CARID:UPDATEPARTSTATUS - grants all authenticated users the right
to modify the instances of the ATTENDEE property set to one of
their calendar adresses in the VEVENT and VTODO components for
which the ORGANIZER property is set to the address of the VAGENDA
in which the VEVENT or VTODO is stored, given that the submitted
value of the ATTENDEE property is one of their calendar adresses.
Suggested definition for this VCAR:

   BEGIN:VCAR
   CARID:UPDATEPARTSTATUS
   BEGIN:VRIGHT
   GRANT:*
   PERMISSION:MODIFY
   SCOPE:SELECT att FROM VEVENT
    USING_PROPERTIES ATTENDEE att
    WHERE SELF() IN CAL-OWNERS(att) AND ORGANIZER = CURRENT-CALID()
   RESTRICTION:SELECT * FROM VEVENT
    WHERE SELF() IN CAL-OWNERS(ATTENDEE)
   END:VRIGHT
   BEGIN:VRIGHT
   GRANT:*
   PERMISSION:MODIFY
   SCOPE:SELECT att FROM VTODO
    USING_PROPERTIES ATTENDEE att
    WHERE SELF() IN CAL-OWNERS(att) AND ORGANIZER = CURRENT-CALID()
   RESTRICTION:SELECT * FROM VTODO
    WHERE SELF() IN CAL-OWNERS(ATTENDEE)
   END:VRIGHT
   END:VCAR

CARID:DEFAULTOWNER - grants to the owner all permissions on
all the objects in the calendar.  Suggested definition for
this VCAR:

   BEGIN:VCAR
   CARID:DEFAULTOWNER
   BEGIN:VRIGHT
   GRANT:OWNER
   PERMISSION:*
   SCOPE:SELECT * FROM VAGENDA
   END:VRIGHT
   END:VCAR

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

   [ Editor's note: Information that needs to be added to
     the restriction table of the "create" command in
     section 6.2.4.1. ]

             Component/Property     Presence Comment
             -------------------    --------
-----------------------------

             . . VCAR               0+
             . . . CARID            1
             . . . NAME             0+       Note, there MUST NOT be
                                             more than one NAME with
                                             no LANGUAGE parameter,
                                             and there MUST NOT be
                                             more than one NAME with
                                             the same LANGUAGE value.
             . . . DECREED          0        This property is outside
                                             the scope of the protocol.
             . . . X-PROPERTY       0+
             . . . [IANA-PROP]      0+       any IANA registered
                                             property
             . . . VRIGHT           1+
             . . . . PERMISSION     1+
             . . . . DENY           0+       Note, there must be at
                                             least one GRANT or DENY
                                             within the VRIGHT.
             . . . . GRANT          0+       Note, there must be at
                                             least one GRANT or DENY
                                             within the VRIGHT.
             . . . . SCOPE          0+       Note, there must be at
least
                                             one SCOPE if PERMISSION is
set
                                             to "READ", "MODIFY",
"DELETE",
                                             or "*".
             . . . . RESTRICTION    0 or 0+  Note, allowed only if
                                             PERMISSION is set to
                                             "WRITE", "MODIFY", or "*".
             . . . . X-PROPERTY     0+
             . . . . [IANA-PROP]    0+       any IANA registered
                                             property

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

Regards,
Bernard
-- 
Bernard Desruisseaux                    mailto:[email-masked]
Research & Development                  Tel.  : +1 514 733-8500 x4213
Steltor                                 Fax   : +1 514 733-8878