INTERNET DRAFT Yasuaki Takebe draft-takebe-cogny-protocol-00.txt (Cognitive Research Labs, Inc.) Expires: September 2004 Cogny protocol - A protocol for peer-to-peer content sharing systems Status of this Memo This document is an Internet-Draft and is subject to all provisions of Section 10 of RFC2026. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/1id-abstracts.html The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html Abstract This document describes Cogny protocol that is a SOAP-based protocol for peer-to-peer content sharing systems. Unlike general purpose peer-to-peer protocols such as JXTA protocol, Cogny protocol is specialized to support centralized peer-to-peer content sharing systems. So it is much simpler and easier to implement than JXTA protocol. Because Cogny protocol is specialized to content sharing systems, it defines application layer functions necessary to them. One of them is a content transfer protocol that keeps consistency of content. Cogny protocol defines encryption method for it. Another is efficient full-text search. Cogny protocol defines a cache method for full-text search. 1. Overview Cogny protocol is a SOAP[1][2]-based protocol for peer-to-peer content sharing systems. Unlike general purpose peer-to-peer protocols such as JXTA[3] protocol, Cogny protocol is specialized to support centralized peer- to-peer content sharing systems. So it is much simpler and easier to implement than JXTA protocol. Because Cogny protocol is specialized to content sharing systems, it Takebe [Page 1] Cogny protocol 10 February 2004 defines application layer functions necessary to them. One of them is a content transfer protocol that keeps consistency of content. Cogny protocol defines encryption method for it. Another is efficient full- text search. Cogny protocol defines a cache method for full-text search. 2. Introduction 2.1 Supposed peer-to-peer model In these systems, contents are stored at the end user clients rather than at a central server. A central server stores only information about in which client contents are stored. Clients search other clients that have contents by querying to a central server. Contents are transferred directly between clients. 2.2 Scope of Cogny protocol Cogny protocol consists of following protocols: - Protocol between a central server and a client - Protocol between a client and a client - Protocol for search and caching search results 2.3 Transport layer protocol Because Cogny protocol is defined using SOAP, there are some choices in transport layer protocol. Cogny protocol assumes HTTP on SSL as transport layer protocol because peer-to-peer content sharing systems are usually required to be secure and real-time. 2.4 SOAP representation of commands (This section needs to be revised.) Commands of Cogny protocol consist of a request and a response. They are represented by SOAP messages. Because they can be implemented by RPC on SOAP provided by Apache-SOAP version 2.3.1[4], a Java API corresponding to a command is described as an informational note. A request is represented as follows: user1 password client1 http://cogny.com/servlet/rpcrouter Takebe [Page 2] Cogny protocol 10 February 2004 Here, "ns1:login" is a name of a command. "urn:CognyServer" means that it is a request to a central server. If a request is to a client, "urn:CognyClient" is used instead. "userId", "password", "clientId" and "clientUrl" are names of parameters. A response is represented as follows: user1 Return values are stored in an array of strings. A client or a central server that returns a response must store return values in the order in the following command descriptions. 3. Protocol between a central server and a client A client can send commands in this section to a central server and receive results from a central server. 3.1 Authentication commands 3.1.1 Login command A client must receive an authentication ticket from a central server by sending a login command. A client may use a ticket obtained by a login command to send other commands. A central server should store client information sent by a login command and should associate an authentication ticket with a user id and a client id. Names of parameters sent with a login command: - userID (User ID) - password (Password) - clientID (Client ID) - clientUrl (Client URL) A user ID or a client ID may be an arbitrary string by which a central server must be able to identify a user or a client. Response of a login command: - Authentication ticket Java API: public String login(String userId, String password, String clientId, String clientUrl) Takebe [Page 3] Cogny protocol 10 February 2004 When transport layer protocol is not encrypted, authentication tickets can be stolen. Cogny protocol should be used with HTTP on SSL to solve this problem. 3.1.2 Logout command A client should send a logout comment to a central server when an authentication ticket becomes not necessary. A central server may judge a client is not connected to a peer-to- peer network by receiving a logout comment from it. Because a client may not send a logout command, a central server should judge if a client is connected or not by other methods such as timeout. Names of parameters sent with a logout command: - authTicket (Authentication ticket) Response of a PutClientInfo command: None Java API: public void logout(String authTicket) 3.1.3 GetClientInfo command A client can send a GetClientInfo command to a central server to obtain information of other clients. A central server returns URLs and public keys of clients. Parameters send with a GetClientInfo command: - authTicket (Authentication ticket) - clientID (Client ID) - infoType (Types of information of client to obtain) - URL - Public key Response of a GetClientInfo command: - URL - Public key Java API: public String[] getClientInfo(String authTicket, String clientId, String infoType[]) 3.1.4 PutClientInfo command A client can send a PutClientInfo command to a central server. A client should send PutClientInfo commands periodically so that a Takebe [Page 4] Cogny protocol 10 February 2004 central server does not consider it to be disconnected from a peer- to-peer network. Names of parameters sent with a PutClientInfo command: - authTicket (Authentication ticket) - infoType (Types of information of client to put) - URL - infoValue (Information to put) Response of a PutClientInfo command: None Java API: public void putClientInfo(String authTicket, String infoType[], String infoValue[]) 3.1.5 GetServerInfo command A client may send a GetServerInfo command to a central server to obtain information about a central server. A public key of a server is returned as a response. Note that clients must know URL of a central server. Cogny protocol does not define how to obtain URL of a central server. Names of parameters sent with a GetServerInfo command: - authTicket (Authentication ticket) - infoType (Types of information of client to obtain) - Public key Response of a GetServerInfo command: - Public key Java API: public String[] getServerInfo(String authTicket, String infoType[]) 3.2 Content publication commands In peer-to-peer content sharing systems, contents are stored at clients. A central server stores metadata of contents and id of clients that store contents. Content publication commands are used to store metadata of contents at a central server from clients 3.2.1 CreateDoc command A client may send a CreateDoc command to a central server to publish content to other clients. A CreateDoc command stores metadata of content at a central server. Takebe [Page 5] Cogny protocol 10 February 2004 Names of parameters sent with a CreateDoc command: - authTicket (Authentication ticket) - infoType (Type of metadata (need to be revised)) - infoValue (Value of metadata (need to be revised)) Metadata include a digital sign to content. Response of a CreateDoc command: - Content ID Java API: public String createDoc(String authTicket, String infoType[], String infoValue[]) 3.2.2 UpdateDoc command A client may send an UpdateDoc command to a central server to update metadata of content stored at a central server. An UpdateDoc command may be sent from a client that is different from one from which a CreateDoc command or an UpdateDoc command was previously sent for a same content. A central server must update id of client stored at it to id of client that sent an UpdateDoc command. Names of parameters sent with an UpdateDoc command: - authTicket (Authentication ticket) - docID (Content ID) - infoType (Type of metadata (need to be revised)) - infoValue (Value of metadata (need to be revised)) Response of a UpdateDoc command: None Java API: public void updateDoc(String authTicket, String docId, String infoType[], String infoValue[]) 3.2.3 DeleteDoc command A DeleteDoc command is sent to delete metadata stored at a central server correspond to content ID. Names of parameters sent with an DeleteDoc command: - authTicket (Authentication ticket) - docID (Content ID) Takebe [Page 6] Cogny protocol 10 February 2004 Response of a DeleteDoc command: None Java API: public void deleteDoc(String authTicket, String docId) 3.2.4 GetDocInfo command A GetDocInfo command is sent to obtain content information. Names of parameters sent with a GetDocInfo command: - authTicket (Authentication ticket) - docID (Content ID) - infoType (Type of information to obtain) - Version number of content Response of a GetDocInfo command: - Version number of content Java API: public String[] getDocInfo(String authTicket, String docId, String infoType[]) 3.2.5 GetDocPermission command A client can sent a GetDocPermission command to obtain permission to content. When a client provides GUI to users, this command may be used to enable or disable GUI such as an update button or a delete button. A client may cache the result of this command to reduce the load to a central server. Names of parameters sent with a GetDocPermission command: - authTicket (Authentication ticket) - docID (Content ID) - permissionType (Type of permission to obtain) - Content can be updated or not - Content can be deleted or not - User ID of content publisher Response of a GetDocPermission command: - Content can be updated or not - Content can be deleted or not - User ID of content publisher Java API: Takebe [Page 7] Cogny protocol 10 February 2004 public String[] getDocPermission(String authTicket, String docId, String permissionType[]) 3.3 Content download commands Content download commands are used to notify to a central server that a client begins to download content from other client. They are sent from a client to a central server. 3.3.1 StartDownload command A client must send a StartDownload command to a central server when it starts to download content from other client. A central server returns ID of client that stores content requested by a StartDownload command. Names of parameters sent with a StartDownload command: - authTicket (Authentication ticket) - docID (Content ID) Response of a StartDownload command: - ID of a client that stores content - Download session ID Java API: public String[] startDownload(String authTicket, String docId) 3.3.2 FinishDownload command A client must send a FinishDownload command to a central server when it finishes to download content from other client. A central server should add client id to its store to memorize that a client stores content. A central server may return a common encryption key and a digital sign to content to a client when content is encrypted by a download source client. A client can decrypt content with a common encryption key and can confirm that content is not tampered with a digital sign. Names of parameters sent with a FinishDownload command: - authTicket (Authentication ticket) - downloadId (Download session ID) Response of a FinishDownload command: - Common encryption key - Digital sign Java API: public String[] finishDownload(String authTicket, String downloadId) Takebe [Page 8] Cogny protocol 10 February 2004 3.3.3 RefleshDownloadID command A central server may discard a download session ID when a client does not send a RefleshDownloadID command for a long time. A client must send a RefleshDownloadID command to a central server to prevent a download session ID from begin discarded. Names of parameters sent with a RefleshDownloadID command: - authTicket (Authentication ticket) - downloadId (Download session ID) Response of a RefleshDownloadID command: None Java API: public void refleshDownloadId(String authTicket, String downloadId) 3.3.4 CancelDownload command A CancelDownload command can be used to notify to a central server that a client canceled to download content from other client. A central server should discard a download session ID when received a CancelDownload command. Names of parameters sent with a CancelDownload command: - authTicket (Authentication ticket) - downloadId (Download session ID) Response of a CancelDownload command: None Java API: public void cancelDownload(String authTicket, String downloadId) 3.3.5 NotifyDownloadStart command A client can send a NotifyDownloadStart command to a central server when it receives a RequestDownloadStart command. A central server may return a common encryption key to a download source client to encrypt content. A central server must confirm that a client to which it returns a common encryption key stores content corresponding to a download session ID. Names of parameters sent with a NotifyDownloadStart command: - authTicket (Authentication ticket) - downloadId (Download session ID) Takebe [Page 9] Cogny protocol 10 February 2004 Response of a NotifyDownloadStart command: - Common encryption key - Content ID Java API: public String[] notifyDownloadStart(String authTicket, String downloadId) 4. Protocol between a client and a client A client can send commands in this section to another client. These commands are for transferring content between a client and a client. 4.1 RequestDownloadStart command A client that is going to download content from another client can send a RequestDownloadStart command to that download source client. When a client receives a RequestDownloadStart command, it should send a NotifyDownloadStart command to a central server. When it receives response to a NotifyDownloadStart command, a download source client may start a download session corresponding to a download session ID passed by a RequestDownloadStart command. When a download source client does not receives response to a NotifyDownloadStart command, it may respond to a RequestDownloadStart command that a download session cannot be started. When a client receives this response, it should resend a RequestDownloadStart command to the same client after a certain period of time. When a download source client receives response to a NotifyDownloadStart command, it should respond to a RequestDownloadStart command that it can start a download session. A download client may start to download content when it receives this response. Names of parameters sent with a RequestDownloadStart command: - downloadId (Download session ID) Response of a RequestDownloadStart command: - If a download session can be started or not - "OK" or "NG" - Metadata of content - File size Java API: public String[] requestDownloadStart(String downloadId) 4.2 Download command Takebe [Page 10] Cogny protocol 10 February 2004 A client can send a download command to another client that starts a download session by sending a RequestDownloadStart command. Content may be encrypted with a common encryption key sent by a NotifyDownload command response and must be signed. A download source client may split content into blocks and transfer to a client by blocks. Names of parameters sent with a download command: - downloadId (Download session ID) - blockId (Block number) Response of a download command: - Data of content Java API: public byte[] download(String downloadId, int blockId) 5. Protocol for search and caching search results Protocol for search and caching search results defines how a client send search request to another client or a central server and how a client obtain a list of clients that cache the results of searches. 5.1 SearchDoc command A client may send a SearchDoc command to a central server to search metadata of contents stored at a central server. Names of parameters sent with a SearchDoc command: - authTicket (Authentication ticket) - keyType (Type of search keyword) - key (Value of search keyword) - infoType (Type of metadata to obtain as a search result) Response of a SearchDoc command: - List of following items: - Content ID - Metadata specified by a parameter Java API: public String[] searchDoc(String authTicket, String keyType[], String key[], String infoType[]) 5.2 GetCacheList command A client can send a GetCacheList command to a central server to obtain a list of URLs of clients that cache results of searches. A central server should choose clients that are available for a long Takebe [Page 11] Cogny protocol 10 February 2004 time. Names of parameters sent with a GetCacheList command: - authTicket (Authentication ticket) Response to a GetCacheList command: - List of URLs of clients Java API: public String[] getCacheList(String authTicket) 5.3 RequestSearchDoc command A client can send a RequestSearchDoc command to another client to obtain cached search results. A client must send a RequestSearchDoc command to a client that is a member of a list obtained by a GetCacheList command. To decide member of a list to send a RequestSearchDoc command, a client must divide range of SHA1[5] hash function into periods of equally length and assign members of a list to these periods. When a client sends a RequestSearchDoc command, it must calculate an SHA1 hash value of a keyword and send a RequestSearchDoc command to a client assigned to a period that contains a hash value. When a client receives a RequestSearchDoc command, it returns a cached result of search if it stores one. Otherwise it sends a SearchDoc command to a central server and caches a result. Names of parameters sent with a RequestSearchDoc command: - keyType (Type of search keyword) - key (Value of search keyword) - infoType (Type of metadata) Response of a RequestSearchDoc command: - List of following items: - Content ID - Metadata specified by a parameter Java API: public String[] requestSearchDoc(String keyType[], String key[], String infoType[]) References [1] Martin Gudgin, Marc Hadley, Noah Mendelsohn, Jean-Jacques Moreau, Henrik Frystyk Nielsen. W3C Proposed Recommendation "SOAP Version 1.2 Part 1: Messaging Framework". 24 June 2003 Takebe [Page 12] Cogny protocol 10 February 2004 [2] Martin Gudgin, Marc Hadley, Noah Mendelsohn, Jean-Jacques Moreau, Henrik Frystyk Nielsen. W3C Proposed Recommendation "SOAP Version 1.2 Part 2: Adjuncts". 24 June 2003 [3] JXTA v2.0 Protocols Specification. http://spec.jxta.org/nonav/v1.0/docbook/JXTAProtocols.html. [4] Apache SOAP. http://ws.apache.org/soap/. [5] D. Eastlake, 3rd, P. Jones. US Secure Hash Algorithm 1 (SHA1). RFC 3174. September 2001 Author's Address Yasuaki Takebe Cognitive Research Labs, Inc. R&D Division 303 Nagatani Ryudo Roppongi, 7-8-25 Roppongi, Minatoku 106-0032 Tokyo, Japan EMail: Yasuaki_Takebe@crl.co.jp Takebe [Page 13]