idnits 2.17.1 draft-hanna-sstp-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-16) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. ** The document is more than 15 pages and seems to lack a Table of Contents. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 22 longer pages, the longest (page 2) being 60 lines == It seems as if not all pages are separated by form feeds - found 0 form feeds but 23 pages Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 8 instances of too long lines in the document, the longest one being 8 characters in excess of 72. == There are 4 instances of lines with non-RFC2606-compliant FQDNs in the document. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 70: '... MUST...' RFC 2119 keyword, line 74: '... SHOULD...' RFC 2119 keyword, line 80: '... MAY...' RFC 2119 keyword, line 87: '... of the MUST requirements for the pr...' RFC 2119 keyword, line 88: '...atisfies all the MUST and all the SHOU...' (30 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- Couldn't find a document date in the document -- date freshness check skipped. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Possible downref: Non-RFC (?) normative reference: ref. '2' -- Possible downref: Non-RFC (?) normative reference: ref. '3' -- Possible downref: Non-RFC (?) normative reference: ref. '4' ** Obsolete normative reference: RFC 822 (ref. '5') (Obsoleted by RFC 2822) Summary: 12 errors (**), 0 flaws (~~), 4 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 INTERNET DRAFT Steve Hanna 2 draft-hanna-sstp-00.txt ON Technology 4 Simple Scheduling Transfer Protocol 6 Status of this Memo 8 This document is an Internet-Draft. Internet-Drafts are working 9 documents of the Internet Engineering Task Force (IETF), its areas, 10 and its working groups. Note that other groups may also distribute 11 working documents as Internet-Drafts. 13 Internet-Drafts are draft documents valid for a maximum of six months 14 and may be updated, replaced, or obsoleted by other documents at any 15 time. It is inappropriate to use Internet- Drafts as reference 16 material or to cite them other than as ``work in progress.'' 18 To learn the current status of any Internet-Draft, please check the 19 ``1id-abstracts.txt'' listing contained in the Internet- Drafts 20 Shadow Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe), 21 munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or 22 ftp.isi.edu (US West Coast). 24 Abstract 26 The Simple Scheduling Transfer Protocol (SSTP) provides a mechanism 27 for the exchange of scheduling information between independent 28 scheduling systems. This will allow users to schedule meetings with 29 anyone, no matter what scheduling system they use. 31 It also allows user agents to access scheduling data that is stored 32 in scheduling systems. This opens up scheduling data for much more 33 sophisticated access, such as automated scheduling programs and 34 network computers. 36 1 Introduction 38 1.1 Purpose 40 Group schedulers and personal information managers are widely used to 41 plan meetings and manage time. Unfortunately, each system is an 42 island. Scheduling a meeting with someone who uses another system or 43 sharing your own calendar between several systems is very difficult. 44 SSTP bridges the gap between scheduling systems by defining a 45 standard protocol with which these systems can talk to each other. 47 Several other standards have recently been proposed for scheduling 49 draft-hanna-sstp-00.txt SSTP INTERNET DRAFT 51 system information interchange. SSTP's primary advantages over these 52 standards are: 54 SSTP is simple, including only four commands. 56 SSTP is scalable, including three levels of support from a minimal 57 PIM implementation to a full-blown server implementation. 59 SSTP is extensible, with built-in mechanisms that allow for safe, 60 simple, and inexpensive extensibility. 62 SSTP is based on established protocols and formats such as SMTP, 63 POP, IMAP, MIME, Simplegrams, and vCalendar. 65 1.2 Requirements 67 This specification uses the same words as RFC 1123 [1] for defining 68 the significance of each particular requirement. These words are: 70 MUST 71 This word or the adjective "required" means that the item is an 72 absolute requirement of the specification. 74 SHOULD 75 This word or the adjective "recommended" means that there may exist 76 valid reasons in particular circumstances to ignore this item, but 77 the full implications should be understood and the case carefully 78 weighed before choosing a different course. 80 MAY 81 This word or the adjective "optional" means that this item is truly 82 optional. One vendor may choose to include the item because a 83 particular marketplace requires it or because it enhances the 84 product, for example; another vendor may omit the same item. 86 An implementation is not compliant if it fails to satisfy one or more 87 of the MUST requirements for the protocols it implements. An 88 implementation that satisfies all the MUST and all the SHOULD 89 requirements for its protocols is said to be "unconditionally 90 compliant"; one that satisfies all the MUST requirements but not all 91 the SHOULD requirements for its protocols is said to be 92 "conditionally compliant." 94 1.3 Document Structure 96 draft-hanna-sstp-00.txt SSTP INTERNET DRAFT 98 This document is divided into several major sections. The Protocol 99 Overview section describes the protocol as a whole, including key 100 concepts. The Commands section describes the specific commands 101 supported by the protocol. The Scheduling Objects section describes 102 the parts of the protocol that pertain most specifically to 103 scheduling, the scheduling objects. The Levels of Support section 104 describes three levels of support for the protocol's features. The 105 Examples section includes several example SSTP sessions. The Formal 106 Syntax section includes a formal syntax for the protocol. 108 2 Protocol Overview 110 2.1 Description 112 All communications via SSTP occur in the context of an SSTP session. 113 An SSTP session begins when an SSTP client contacts an SSTP server 114 using a reliable data stream protocol such as TCP. Once a session has 115 been established, the client sends a command and the server sends a 116 reply. This is repeated until the session is terminated. 118 The server cannot issue commands during a session or "turn" the 119 session and become the client. Only one command can be pending at a 120 time. That is, the client MUST NOT send a command until it has 121 received the reply to the previous one. 123 Normally, an SSTP session ends when the client sends a QUIT command 124 and the server sends a result code and closes the connection. If an 125 SSTP session is terminated in another way (network failure, for 126 instance), it is undefined whether any pending command was completed. 128 All data sent by client and server MUST consist of lines of US ASCII 129 [2] text (character values 32 to 126 decimal only), terminated by 130 CRLF. If client and server use the AUTHENTICATE command to agree on 131 an encryption technique, the encrypted data may have any form. The 132 decrypted data will continue to have the form described here. 134 All user data is included in SSTP objects, which are transmitted 135 using the Simplegram format [4]. The ENCODING and CHARSET parameters 136 defined in this specification allow property values to include binary 137 data or text in any character set, including Unicode. 139 Each command or reply is a single line, unless it includes an object 140 or objects. In that case, the first line MUST end with an equal sign 141 ("="). The following lines are considered part of the command or 142 reply until the sequence CRLF CRLF equal sign CRLF is read. Because 143 this sequence is not a valid part of a Simplegram, it can easily be 144 distinguished from the object or objects. 146 draft-hanna-sstp-00.txt SSTP INTERNET DRAFT 148 2.2 Commands 150 Each SSTP command consists of a keyword, optionally followed by 151 arguments. As described above, each command is a single line, unless 152 it includes an object or objects. 154 There are four commands in the standard SSTP command set, although 155 more can be added and their presence indicated via the capabilities 156 query mechanism. The required commands are SUBMIT, QUERY, and QUIT. 157 The optional command is AUTHENTICATE. 159 2.3 Replies 161 SSTP replies consist of a numerical result code, optionally followed 162 by data. Successful completion of a command results in a result code 163 of "000" followed by whatever data may be appropriate to the command. 164 Failure of a command results in a non-zero result code followed by an 165 optional textual description of the error. 167 The following numerical result codes are defined. Servers MUST return 168 a result codes in every reply. Clients MAY use these codes to attempt 169 to recover from errors (for example, authenticating if code 100 is 170 returned). Other three digit numerical result codes MAY be defined in 171 extensions to this specification. If the client does not recognize a 172 result code it MUST treat it as a code 900. 174 Code Meaning 175 ---- ------- 176 000 Command completed successfully. 177 100 Access denied. Try the AUTHENTICATE command? 178 200 Command or argument not supported. Check capabilities. 179 300 Authentication failed. 180 900 Other error. 182 2.4 SSTP Objects 184 SSTP uses a very simple object format to transport data from one 185 server to another. This allows the protocol to be very simple, yet 186 easily extended to handle many different kinds of data. This format 187 is called the Simplegram format and it is described in the next 188 section. 190 Specific SSTP object types are listed in the Object Types section 191 below and described where they are used. 193 2.4.1 Simplegrams 195 Whenever a large or extensible chunk of data needs to be sent, SSTP 197 draft-hanna-sstp-00.txt SSTP INTERNET DRAFT 199 uses the Simplegram format [4] to send the data. This format is used 200 by the vCalendar and vCard specifications, and it's a convenient way 201 of communicating objects in an extensible, general-purpose fashion. 203 A capsule summary of the Simplegram format appears in the next 204 paragraph, although the original specification should be consulted 205 for details. Several different object types are used in different 206 parts of the SSTP protocol, including SSTP-Authentication objects, 207 SSTP-Query objects, and SSTP-Storage objects. These types are defined 208 in the Object Types section below. 210 A Simplegram is a series of lines of ASCII text that represent one or 211 more objects. Each object begins with a begin delimiter of the form 212 "BEGIN: object-type" and ends with an end delimiter of the form "END: 213 object-type". Between these delimiters come a sequence of property- 214 value pairs of the form "PROPERTY-NAME[params]: value". Standard 215 params include TYPE, VALUE, ENCODING, CHARSET, and LANGUAGE. Values 216 are a single line of ASCII text unless ENCODING is BASE64 or QUOTED- 217 PRINTABLE, in which case multiline values are permitted, ending at 218 the first line that begins with a non-white space character. 220 2.4.2 Object Types 222 Here is a list of object types defined in this document. For a 223 description of each type, see the section where it is used. Other 224 object types may be defined in SSTP protocol extensions. If an SSTP 225 server encounters a type is does not recognize, it MUST return a 226 result code of 200. 228 SSTP-Authentication-Password 229 SSTP-Stored-Object-Create-Request 230 SSTP-Stored-Object-Change-Request 231 SSTP-Stored-Object-Delete-Request 232 SSTP-Stored-Object-Create-Result 233 SSTP-Stored-Object-Change-Result 234 SSTP-Stored-Object-Delete-Result 235 SSTP-Query-Capability 236 SSTP-Query-Results-Capability 237 SSTP-Capability-Commands 238 SSTP-Capability-Authentication 239 SSTP-Capability-Queries 240 SSTP-Capability-Descriptors 241 SSTP-Descriptor-Event 242 SSTP-Query-Busy-Time 243 SSTP-Query-Results-Busy-Time 244 SSTP-Busy-Time 245 SSTP-Query-Calendar 246 SSTP-Query-Results-Calendar 248 draft-hanna-sstp-00.txt SSTP INTERNET DRAFT 250 2.5 Stored Objects 252 SSTP objects are purely transient. They are used only to transfer 253 information from the SSTP client to the SSTP server. However, SSTP's 254 main business is communicating information about stored objects. 255 These are objects such as events that continue to exist even when no 256 SSTP session is running. SSTP doesn't care where or how stored 257 objects are stored, but it does make certain requirements on these 258 objects so that they can be managed and referenced properly. 260 Each stored object is owned by one SSTP server (the object owner), 261 which is responsible for storing the master copy of the object, 262 accepting requests to change the object, and distributing changes to 263 other servers. 265 Each stored object also has an object id, which is a string of 266 printable ASCII characters assigned by the object owner. Together 267 with the owner's server id, this object id uniquely identifies the 268 object. 270 Since SSTP does not describe where or how stored objects are stored, 271 it cannot specify their exact format or content either. Instead, it 272 defines specific types of SSTP objects called Stored Object 273 Descriptors that provide a standard way of describing these stored 274 objects. For instance, the Event Descriptor is an SSTP object that 275 describes events, including start and end dates, attendees, etc. 277 For information about specific Stored Object Descriptors, see the 278 Scheduling Objects section below. 280 2.6 Server IDs 282 SSTP servers are identified with a server ID, which must be an 283 absolute DNS name (also known as a Fully Qualified Domain Name or 284 FQDN). Server IDs are used to identify servers and to establish 285 sessions with them. See the section on Establishing an SSTP Session 286 below for more information. 288 Because of the nature of DNS, a single server may have more than one 289 server ID. However, each server ID resolves to only a single server. 291 2.7 User IDs 293 SSTP manages meetings and events for users (or user equivalents such 294 as meeting rooms). SSTP users are identified with a user id of the 295 form user@server, where server is an SSTP server ID and user is a 296 string of printable ASCII characters (values 32 to 126 decimal), not 297 including an at sign ("@") or comma (","). 299 draft-hanna-sstp-00.txt SSTP INTERNET DRAFT 301 Several user IDs may refer to the same user or even the same user 302 account. For instance, hanna@on.com, shanna@on.com, and 303 steve@sstp.on.com might all refer to the same account. 304 hanna@homebiz.com might refer to a different account for the same 305 user. staff@homebiz.com might refer to more than one user. Any 306 aliasing or forwarding along these lines is the responsibility of the 307 SSTP server referred to in the user ID. Other SSTP servers and 308 clients should just treat each user ID as a single user. 310 2.8 Establishing an SSTP Session 312 Whenever an SSTP client wants to contact an SSTP server with a 313 certain ID, a DNS lookup on this name is performed and the TEXT 314 records for this name are examined. If one of these records begins 315 with "SSTP:", the rest of this record is taken to be a DNS name. A 316 lookup is performed on this name and the A record is used to fetch an 317 IP address. A TCP connection can now be made to the SSTP port (port 318 9243 for now) on this host. 320 If no TEXT records are found for a server ID, the A record for this 321 name is fetched and a TCP connection is made to the SSTP port on this 322 host. 324 If this process fails, the host in question cannot be contacted at 325 this time. The SSTP client can try again later. 327 As soon as a connection is established, the SSTP server must send a 328 greeting line of the form 000 SSTP-1.0 [comments] CRLF. If an SSTP 329 client receives a greeting line that does not begin with 000 SSTP- 330 1.0, it MUST close the connection because an incompatible version of 331 SSTP is being used. It is hoped that the extensibility mechanisms 332 built into the protocol will avoid any need to change the basic 333 protocol. If no greeting line is received within a certain timeout, 334 the SSTP client MAY close the connection. 336 3 Commands 338 3.1 AUTHENTICATE 340 Arguments: auth-object 342 Reply: 000 [auth-object] - Authentication proceeding or completed 343 200 - Command or argument not supported 344 300 - Authentication failed 345 900 - Other error 347 draft-hanna-sstp-00.txt SSTP INTERNET DRAFT 349 The AUTHENTICATE command conducts an authentication process with the 350 server. This process may be used to establish client and/or server 351 identity and to begin encryption of the session. Depending on the 352 policy of a given server, some or all operations may be restricted 353 depending on the identity of the client. 355 In order to support many different authentication techniques, the 356 auth-object is a Simplegram containing a single object. The type of 357 this object determines the authentication scheme used. If the 358 object's type is not supported by the server, a 200 reply is sent. 359 Otherwise, the object is passed to the appropriate authentication 360 method. The object's content may vary depending on the method. If 361 authentication fails, a 300 reply is sent. If it succeeds, a 000 362 reply is sent, perhaps with an auth-object. 364 Some authentication methods may require several AUTHENTICATE commands 365 to complete the authentication process. For instance, they may return 366 a challenge key in the auth-object of their first reply. The client 367 might then have to respond with another AUTHENTICATE command 368 including a challenge response. Eventually, the authentication 369 method would return an error reply or a success reply with an auth- 370 object that indicates that the exchange is over and the client has 371 been authenticated. The form of this exchange and the content of the 372 auth-object is particular to the authentication method being used. 374 Some authentication methods may enable encryption of the session. 375 This is up to the authentication method and may be negotiated between 376 the client and the server using the auth-objects, as defined in the 377 description of authentication methods below. Whatever encryption is 378 used, the plaintext of the session will remain the same. 380 Note that the identity established by the AUTHENTICATE command may 381 not correspond to a specific user ID. For instance, it could 382 correspond to a trusted entity which is allowed to SUBMIT objects. 384 3.1.1 SSTP-Authentication-Password 386 An object of type SSTP-Authentication-Password is used to send an 387 account name and plaintext password to an SSTP server. This is the 388 most basic form of authentication available with SSTP and does not 389 provide for encryption. SSTP servers need not support this 390 authentication technique. 392 The ACCOUNT property contains an account name. The PASSWORD property 393 contains a password. 395 draft-hanna-sstp-00.txt SSTP INTERNET DRAFT 397 3.2 QUIT 399 Arguments: none 401 Reply: 000 - No error 403 The QUIT command terminates the current SSTP session. The server will 404 send a 000 result code and terminate the session. The main point of 405 having this command is so that the server can distinguish between 406 normal and abnormal session completion. 408 3.3 SUBMIT 410 Arguments: submission 412 Reply: 000 submission-results - Submission accepted 413 100 - Access denied 414 200 - Command or argument not supported 415 900 - Other error 417 The SUBMIT command submits stored object changes to the server. These 418 changes are sent as a series of create, change, or delete request 419 objects. 421 If the command completes successfully, the server sends a 000 reply 422 and a series of submission result objects, one for each request sent 423 with the command. Successful completion of the SUBMIT command does 424 not mean that all of the changes requested were made. It only means 425 that they were received and attempted. The submission result objects 426 must be examined and matched up with the requests sent to see what 427 the outcome of each request was. This allows several requests to be 428 submitted at once and have some succeed and some fail. 430 If no changes can be performed with the identity that has been 431 established, a 100 reply will be sent. 433 If some part of the submission is not recognized or supported, a 200 434 reply will be sent. 436 If any other error occurs, a 900 will be sent. 438 3.3.1 SSTP-Stored-Object-Create-Request Objects 440 draft-hanna-sstp-00.txt SSTP INTERNET DRAFT 442 An object of type SSTP-Stored-Object-Create-Request is used to create 443 a stored object on a server. The DATA property is a Stored Object 444 Descriptor that describes the object to be created. 446 If the object is already owned by another server and is simply being 447 replicated to this server, several properties that identify the 448 object precede the DATA property. The OWNER property is a server-id. 449 The ID property is an object id. 451 The server attempts to create an object using the data supplied. It 452 returns the results in an SSTP-Stored-Object-Create-Result object. 454 3.3.2 SSTP-Stored-Object-Change-Request Objects 456 An object of type SSTP-Stored-Object-Change-Request is used to change 457 a stored object. The OWNER property is a server-id. The ID property 458 is an object id. The DATA property is a Stored Object Descriptor that 459 describes the changes being requested. 461 The server attempts to change the specified object using the data 462 supplied. It returns the results in an SSTP-Stored-Object-Change- 463 Result object. 465 3.3.3 SSTP-Stored-Object-Delete-Request Objects 467 An object of type SSTP-Stored-Object-Delete-Request is used to delete 468 a stored object. The OWNER property is a server-id. The ID property 469 is an object id. 471 The server attempts to delete the specified object. It returns the 472 results in an SSTP-Stored-Object-Delete-Result object. 474 3.3.4 SSTP-Stored-Object-Create-Result Objects 476 An object of type SSTP-Stored-Object-Create-Result is used to return 477 the results of an SSTP-Stored-Object-Create-Request object sent to 478 the server. 480 The RESULT property is a result code in the same format used for SSTP 481 commands, that is a numerical result code followed by an optional 482 textual error message. If the request completed successfully, the 483 result code is 000. If the object had no owner, OWNER and ID 484 properties describing the new object appear after the RESULT 485 property. If an error occurred, the result code is non-zero and no 486 other properties follow the RESULT property. Likely result codes 487 include 100 (Access denied), 200 (Command or argument not supported), 488 and 900 (Other error). 490 draft-hanna-sstp-00.txt SSTP INTERNET DRAFT 492 3.3.5 SSTP-Stored-Object-Change-Result Objects 494 An object of type SSTP-Stored-Object-Change-Result is used to return 495 the results of an SSTP-Stored-Object-Change-Request object sent to 496 the server. 498 The RESULT property is a result code in the same format used for SSTP 499 commands, that is a numerical result code followed by an optional 500 textual error message. If the request completed successfully, the 501 result code is 000. If the object is owned by the server accepting 502 the request, a DATA property describing the latest version of the 503 object appear after the RESULT property. 505 The DATA returned to the client may not include a complete 506 description of the object. If the changes to the object are slight 507 (especially if they only include the changes made in this request), 508 little or no data need be included in the data object. If no data is 509 needed, no DATA object need be sent. 511 If an error occurred, the result code is non-zero and no other 512 properties follow the RESULT property. Likely result codes include 513 100 (Access denied), 200 (Command or argument not supported), and 900 514 (Other error, such as no such object). 516 3.3.6 SSTP-Stored-Object-Delete-Result Objects 518 An object of type SSTP-Stored-Object-Delete-Result is used to return 519 the results of an SSTP-Stored-Object-Delete-Request object sent to 520 the server. 522 The RESULT property is a result code in the same format used for SSTP 523 commands, that is a numerical result code followed by an optional 524 textual error message. If the request completed successfully, the 525 result code is 000. If an error occurred, the result code is non- 526 zero. Likely result codes include 100 (Access denied), 200 (Command 527 or argument not supported), and 900 (Other error). 529 3.4 QUERY 531 Arguments: query 533 Reply: 000 query-results - Query completed 534 100 - Access denied 535 200 - Command or argument not supported 536 900 - Other error 538 draft-hanna-sstp-00.txt SSTP INTERNET DRAFT 540 The QUERY command submits a query object to the server, which returns 541 the results in a query-results object. 543 If this query cannot be performed with the identity that has been 544 established, a 100 reply will be sent. 546 If the query object received is not recognized or supported, a 200 547 reply will be sent. 549 If any other error occurs (internal error, no such user, etc.), a 900 550 will be sent. 552 For information about specific types of query and query results 553 objects, see the Scheduling Objects section below. 555 3.4.1 SSTP-Query-Capability Objects 557 An object of type SSTP-Query-Capability is used to find out what 558 capabilities an SSTP server supports. There is one optional property 559 for this object, the CAPABILITY-TYPE property. If this property is 560 present, it requests that the server return only objects of the 561 specified type in the SSTP-Query-Results-Capability object. 563 This query object MUST be supported by all SSTP servers. 565 3.4.2 SSTP-Query-Results-Capability Objects 567 An object of type SSTP-Query-Results-Capability is used to return the 568 results of a capabilities query. The object contains a series of 569 objects that describe various capabilities the server has. If the 570 query being answered included a CAPABILITY-TYPE property, all 571 capabilities that don't match that type are filtered out. Otherwise, 572 all capabilities supported by the server will be returned. 574 The client SHOULD read the objects, skipping those that it doesn't 575 understand and parsing those that it does. If it doesn't find a 576 capability that it was hoping for, it SHOULD assume that the server 577 doesn't have this capability. 579 The set of capabilities cannot change throughout a session, so the 580 client MAY execute a single capabilities query at the start of a 581 session. Actually, the client need not execute the query at all if 582 it's prepared to handle 200 result codes. 584 The standard set of capability objects is described in the next few 585 sections. 587 3.4.3 SSTP-Capability-Commands Objects 589 draft-hanna-sstp-00.txt SSTP INTERNET DRAFT 591 An object of type SSTP-Capability-Commands is used to describe the 592 commands an SSTP server supports. The COMMAND property is the name of 593 a single command. This property MAY appear multiple times within the 594 same object. In fact, it usually will. Any result from an 595 unrestricted capabilities query MUST include one object of this type. 596 Under no circumstances may more than one of object of this type be 597 included in a single SSTP-Query-Results-Capability object. 599 3.4.4 SSTP-Capability-Authentication Objects 601 An object of type SSTP-Authentication is used to describe the 602 authentication schemes an SSTP server supports. The AUTHENTICATION 603 property is a single object type. This property MAY appear multiple 604 times within the same object if more than one authentication scheme 605 is supported. If no authentication schemes are supported, the SSTP 606 server MUST NOT include an object of type SSTP-Authentication in any 607 SSTP-Query-Results-Capability object and MUST NOT include the 608 AUTHENTICATE command in any SSTP-Capability-Commands object. Under no 609 circumstances may more than one of object of this type be included in 610 a single SSTP-Query-Results-Capability object. 612 3.4.5 SSTP-Capability-Queries Objects 614 An object of type SSTP-Capability-Queries is used to describe the 615 query object types an SSTP server supports. The QUERY property is a 616 single object type. This property MAY appear multiple times within 617 the same object. In fact, it usually will. Since the SSTP-Query- 618 Capabilities query is required, any result from an unrestricted 619 capabilities query MUST include one object of this type and this 620 object MUST include a QUERY property with the value SSTP-Query- 621 Capabilities. Under no circumstances may more than one of object of 622 this type be included in a single SSTP-Query-Results-Capability 623 object. 625 3.4.6 SSTP-Capability-Descriptors Objects 627 An object of type SSTP-Capability-Descriptors is used to describe the 628 stored object descriptors an SSTP server supports. The DESCRIPTOR 629 property is a single object type. This property MAY appear multiple 630 times within the same object. In fact, it usually will. Any result 631 from an unrestricted capabilities query MUST include one object of 632 this type. Under no circumstances may more than one of object of this 633 type be included in a single SSTP-Query-Results-Capability object. 635 4 Scheduling Objects 637 These objects describe and apply to scheduling issues in particular. 639 draft-hanna-sstp-00.txt SSTP INTERNET DRAFT 641 4.1 Stored Object Descriptors 643 Stored object descriptors are SSTP objects that are used to describe 644 stored objects. They are used in object create and change requests 645 submitted with the SUBMIT command and may be used in future query 646 object types. 648 4.1.1 Event Descriptors 650 An SSTP-Descriptor-Event object is used to describe events. The 651 properties of this object include all of those described in the 652 vCalendar specification for vEvent objects [3], with several 653 additions. Also, none of the properties are required. This is 654 important for object change requests, since it's common to change 655 only a few properties of an object. For object create requests, the 656 DTSTART and DTEND properties are required. 658 Here is a description of the extra properties defined by this 659 specification. 661 The LOCATION property specifies a textual description of the event's 662 location. 664 The GUESTS property specifies a list of user ids, separated by 665 commas. 667 The PROPOSER property specifies the user id of the user proposing the 668 event. This may be used when displaying the event to guests. 670 Information about users may be stored in user information properties. 671 These properties are named USER-INFO-property-name-user-id, where 672 user-id is the user id in question and property-name is the property 673 name. 675 None of these properties are required. Some are only valid if the 676 user is included in the guest property. Others are not. Most SSTP 677 servers will allow a user (or their SSTP server) to change that 678 user's information properties. 680 The ACK user information property may have the values Y to indicate 681 that this guest has confirmed their attendance or N to indicate that 682 they have indicated they will not attend. 684 The COMMENTS guest information property may include textual comments 685 from the guest. 687 The FULL-NAME user information property is the full name of the user. 689 draft-hanna-sstp-00.txt SSTP INTERNET DRAFT 691 4.2 Query Objects and Query Result Objects 693 Query objects are SSTP objects that are used to define queries. They 694 are used with the QUERY command. Query result objects are SSTP 695 objects that are used to return the results of a query. 697 4.2.1 Busy Time Query Objects 699 An object of type SSTP-Query-Busy-Time is used to find out when a 700 user is busy. The USER property is the user-id of the user being 701 queried. The DTSTART property is the date and time when the query 702 period starts. The DTEND property is the date and time when the 703 query period ends. 705 4.2.2 Busy Time Query Result Objects 707 An SSTP-Query-Results-Busy-Time object is used to return the results 708 of a busy time query. The object contains a series of SSTP-Busy-Time 709 objects that represent busy times on the user's calendar, sorted in 710 order of increasing start times. 712 Each SSTP-Busy-Time object has only two properties: DTSTART and 713 DTEND. These properties are identical to those used in vEvent 714 objects. Depending on the server's configuration and implementation, 715 contiguous or overlapping busy time objects may or may not be merged. 716 Busy time includes any time that the user is not available for 717 meetings, such as days off or evenings. 719 4.2.3 Calendar Query Objects 721 An object of type SSTP-Query-Calendar is used to retrieve the 722 contents of a user's calendar. The USER property is the user-id of 723 the user being queried. The DTSTART property is the date and time 724 when the query period starts. The DTEND property is the date and 725 time when the query period ends. 727 4.2.4 Calendar Query Result Objects 729 An SSTP-Query-Results-Calendar object is used to return the results 730 of a calendar query. The object contains a series of SSTP- 731 Descriptor-Event objects that represent events on the user's 732 calendar, sorted in order of increasing start times. Recurring events 733 should only be included once, even if they appear on the user's 734 calendar several times during the query period. 736 Events which this user has not indicated they will attend should not 737 be included. 739 draft-hanna-sstp-00.txt SSTP INTERNET DRAFT 741 Depending on the server's configuration and implementation and the 742 access level of the current authorization, some information may be 743 stripped out of these objects. For instance, some events may be 744 visible to others while others are marked private. 746 4.2.5 Off Calendar Query Objects 748 An object of type SSTP-Query-Off-Calendar is used to retrieve a list 749 of events that include a certain user, but aren't on that user's 750 calendar. The USER property is the user-id of the user being 751 queried. 753 The most common use of this query is to retrieve a set of events that 754 include the user as a guest, but for which attendance has not yet 755 been confirmed. 757 4.2.6 Off Calendar Query Result Objects 759 An SSTP-Query-Results-Off-Calendar object is used to return the 760 results of an off calendar query. The object contains a series of 761 SSTP-Descriptor-Event objects that represent events, sorted in order 762 of increasing start times. 764 Depending on the server's configuration and implementation and the 765 access level of the current authorization, some information may be 766 stripped out of these objects. For instance, some events may be 767 visible to others while others are marked private. 769 4.2.7 Other Query Objects 771 Other kinds of query objects can be defined. For instance, an object 772 query could return data describing a specific object. An object 773 search query could search for objects based on their properties. 775 5 Levels of Support 777 There are several levels at which a scheduling product can support 778 SSTP. First, it can support SSTP as a means for interoperating with 779 other scheduling systems. Second, it can allow user agents to access 780 user calendars via SSTP. Third, it can support SSTP only as a client, 781 using the protocol to act as a user agent for a scheduling system. 783 All of these levels can be distinguished using the capabilities 784 query. More advanced levels of support are possible using the 785 extension mechanisms described herein. These are just several 786 profiles which may be common. 788 5.1 Required Support 790 draft-hanna-sstp-00.txt SSTP INTERNET DRAFT 792 All SSTP servers MUST support the SUBMIT, QUIT, and QUERY commands. 793 They MUST be able to parse these commands and respond properly if 794 they do not support one of the objects provided with the SUBMIT or 795 QUERY commands. They also MUST support SSTP-Query-Capability objects 796 and respond to them with at least SSTP-Capability-Commands and SSTP- 797 Capability-Queries objects. 799 SSTP servers are not required to support any other commands or 800 queries. They are also not required to support any object 801 descriptors. Of course, an SSTP server won't be much good if it 802 doesn't support changing or querying objects. 804 5.2 Interoperating with Other Scheduling Systems 806 To transfer data with other scheduling systems, a scheduling system 807 must be able to use SSTP both as a client and as a server. 809 When an event created on its system needs to be transferred to guests 810 on another system, it must contact that other system as an SSTP 811 client and attempt to create a stored object for that event on the 812 other system, marking itself as the owner and assigning the event a 813 unique ID. If this event changes, it SHOULD contact the other system 814 and change the stored object to reflect these changes. 816 If the guest on the other system responds to the event, the other 817 system will contact the events owner using SSTP. This owner must 818 respond as an SSTP server and allow the other system to change the 819 user information properties of the guest in question. 821 This means that as an SSTP server the system must support the SSTP- 822 Descriptor-Event object type, allowing other systems to change the 823 user information of guests and create events that are owned by those 824 foreign systems. If one-way interoperability is desired, only part of 825 this need be implemented. 827 Optionally, the system may support the SSTP-Query-Busy-Time object 828 either by using it to query remote systems about the availability of 829 their users or by responding to it with information about the 830 availability of its own users. 832 Implementing the AUTHENTICATE command and allowing the administrator 833 to configure a set of trusted server accounts would be wise. 835 5.3 Supporting User Agents 837 To support user agents, a scheduling system must allow them to create 838 events and assign those events unique IDs. It must also support the 839 SSTP-Query-Calendar object type, which allows user agents to view 841 draft-hanna-sstp-00.txt SSTP INTERNET DRAFT 843 their calendars or those of other users. Supporting the SSTP-Query- 844 Busy-Time object is important, too. Implementing the AUTHENTICATE 845 command is almost a must. 847 5.4 Acting as a User Agent 849 To act as a user agent, a program need only use SSTP as a client to 850 connect to an SSTP server, authenticate, and download its calendar 851 and off-calendar events. Then it can create events, change them, or 852 respond to off-calendar events. This will be especially handy with 853 Network Computers and other systems that don't have persistent 854 storage. 856 6 Security Considerations 858 The AUTHENTICATE command may be used to authenticate the connection 859 and optionally to begin an encrypted session. Scheduling systems may 860 be configured so that they require authentication or encryption 861 before they allow certain commands. If no authentication is required 862 or a poor authentication scheme is used, SSTP could be used to access 863 or modify scheduling data improperly. If encryption is not used, 864 confidential data could be read. 866 7 Examples 868 Here are several typical SSTP sessions, with comments. Comments are 869 marked by lines beginning with #. Lines sent by the SSTP client begin 870 with "C: ". Lines sent by the SSTP server begin with "S: ". 872 7.1 SSTP Client-Server Session 874 In this session, SSTP is being used to communicate within a 875 scheduling system between a client agent and an SSTP server (on.com). 876 The client agent is creating an event proposed by shanna@on.com with 877 libby@sun.com as a guest. 879 S: 000 SSTP-1.0 Welcome to on.com. 880 C: AUTHENTICATE = 881 C: BEGIN: SSTP-Authenticate-Password 882 C: ACCOUNT: shanna@on.com 883 C: PASSWORD: freak7 884 C: END: SSTP-Authenticate-Password 885 C: 886 C: = 887 S: 000 888 C: SUBMIT = 889 C: BEGIN: SSTP-Stored-Object-Create-Request 890 C: DATA: 892 draft-hanna-sstp-00.txt SSTP INTERNET DRAFT 894 C: BEGIN: SSTP-Descriptor-Event 895 C: DTSTART: 19960815T1145 896 C: DTEND: 19960815T1245 897 C: PROPOSER: shanna@on.com 898 C: DESCRIPTION: Lunch 899 C: LOCATION: Mary Chung's Restaurant 900 C: STATUS: TENTATIVE 901 C: GUESTS: shanna@on.com, libby@east.sun.com 902 C: USER-INFO-FULL-NAME-shanna@on.com: Steve Hanna 903 C: USER-INFO-ACK-shanna@on.com: Y 904 C: END: SSTP-Descriptor-Event 905 C: END: SSTP-Stored-Object-Create-Request 906 C: 907 C: = 908 S: 000 = 909 S: BEGIN: SSTP-Stored-Object-Create-Result 910 S: RESULT: 000 911 S: OWNER: on.com 912 S: ID: ABJ249 913 S: END: Stored-Object-Create-Result 914 S: 915 S: = 916 C: QUIT 917 S: 000 919 7.2 SSTP Server-Server Session with Object Creation 921 In this session, SSTP is being used to communicate the event proposed 922 in the last section from on.com (acting as an SSTP client in this 923 exchange) to the SSTP server for east.sun.com. 925 S: 000 SSTP-1.0 Welcome to east.sun.com. 926 C: SUBMIT = 927 C: BEGIN: SSTP-Stored-Object-Create-Request 928 C: OWNER: on.com 929 C: ID: ABJ249 930 C: DATA: 931 C: BEGIN: SSTP-Descriptor-Event 932 C: DTSTART: 19960815T1145 933 C: DTEND: 19960815T1245 934 C: PROPOSER: shanna@on.com 935 C: DESCRIPTION: Lunch 936 C: LOCATION: Mary Chung's Restaurant 937 C: STATUS: TENTATIVE 938 C: GUESTS: shanna@on.com, libby@east.sun.com 939 C: USER-INFO-FULL-NAME-shanna@on.com: Steve Hanna 940 C: USER-INFO-ACK-shanna@on.com: Y 942 draft-hanna-sstp-00.txt SSTP INTERNET DRAFT 944 C: END: SSTP-Descriptor-Event 945 C: END: SSTP-Stored-Object-Create-Request 946 C: 947 C: = 948 S: 000 = 949 S: BEGIN: SSTP-Stored-Object-Create-Result 950 S: RESULT: 000 951 S: END: Stored-Object-Create-Result 952 S: 953 S: = 954 C: QUIT 955 S: 000 957 7.3 SSTP Server-Server Session with Object Change 959 In this session, SSTP is being used to communicate 960 libby@east.sun.com's response to the event proposed in the last 961 section. In this communication, east.sun.com is acting as an SSTP 962 client and on.com is acting as an SSTP server. 964 Note that on.com changes the event's status from TENTATIVE to 965 CONFIRMED because all guests have indicated that they plan to attend. 966 Alternatively, this change might be communicated at a later time via 967 a separate session from on.com to east.sun.com. 969 S: 000 SSTP-1.0 Welcome to on.com. 970 C: SUBMIT = 971 C: BEGIN: SSTP-Stored-Object-Change-Request 972 C: OWNER: on.com 973 C: ID: ABJ249 974 C: DATA: 975 C: BEGIN: SSTP-Descriptor-Event 976 C: USER-INFO-ACK-libby@east.sun.com: Y 977 C: END: SSTP-Descriptor-Event 978 C: END: SSTP-Stored-Object-Change-Request 979 C: 980 C: = 981 S: 000 = 982 S: BEGIN: SSTP-Stored-Object-Change-Result 983 S: RESULT: 000 984 S: DATA: 985 C: BEGIN: SSTP-Descriptor-Event 986 C: STATUS: CONFIRMED 987 C: END: SSTP-Descriptor-Event 988 S: END: Stored-Object-Change-Result 989 S: 990 S: = 992 draft-hanna-sstp-00.txt SSTP INTERNET DRAFT 994 C: QUIT 995 S: 000 997 8 Formal Syntax 999 Here is a first draft of a formal syntax for SSTP. 1001 The following syntax specification uses the augmented Backus-Naur 1002 Form (BNF) notation as specified in [5]. 1004 args ::= *LWSP_char [message] *LWSP_char [object_args] 1006 atom ::= 1*ATOM_CHAR 1008 ATOM_CHAR ::= 1010 atom_specials ::= SPACE / CTL / "=" 1012 CHAR ::= 1015 command ::= command_name args CRLF 1017 command_name ::= "AUTHENTICATE" / "QUERY" / "QUIT" / "SUBMIT" / 1018 extended_cmd 1020 CR ::= 1022 CRLF ::= CR LF 1024 CTL ::= 1027 digit ::= "0" / "1" / "2" / "3" / "4" / "5" / "6" / "7" / "8" / "9" 1029 extended_cmd ::= atom 1031 HTAB ::= 1033 LF ::= 1035 LWSP-char ::= SPACE / HTAB 1037 message ::= 1*