INTERNET-DRAFT V. Ryan Expires 12 November, 1998 S. Seligman R. Lee Sun Microsystems, Inc. 12 May, 1998 Schema for Representing Java(tm) Objects in an LDAP Directory Status of this Memo This document is an Internet-Draft. 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." To view the entire list of current Internet-Drafts, please check the "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow Directories on ftp.is.co.za (Africa), ftp.nordu.net (Northern Europe), ftp.nis.garr.it (Southern Europe), munnari.oz.au (Pacific Rim), ftp.ietf.org (US East Coast), or ftp.isi.edu (US West Coast). Abstract This document defines the schema used to represent Java(tm) objects in an LDAP directory [LDAPv3]. It defines schema elements to enable Java objects to be represented in either of two ways: as serialized byte streams [Serial] and as JNDI references [JNDI]. 1. Introduction This document assumes that the reader has a general understanding of the Java programming language [Java]. For brevity we use the term "Java object" in place of "object in the Java programming language" throughout this text. Traditionally, LDAP directories have been used to store data. Users and programmers think of the directory as a hierarchy of directory entries, each containing a set of attributes. You look up an entry from the directory and extract the attribute(s) of interest. For example, you can look up a person's telephone number from the directory. Alternatively, you can search the directory for entries Ryan, et. al. [Page 1] INTERNET-DRAFT Schema for Java Objects May 1998 with a particular set of attributes. For example, you can search for all persons in the directory with the surname "Smith." For applications written in the Java programming language, a kind of data that is typically shared are Java objects themselves. For such applications, it makes sense to be able to use the directory as a repository for Java objects. Java applications can use the directory as the means by which Java applications find and store Java objects. The directory provides a centrally administered and possibly replicated service for Java applications distributed on the network to use. For example, an application server may use the directory for "registering" objects representing the services that it manages, so that a client can later search the directory to locate the services that it needs. The motivation for this document is to definite a common way for applications to store and retrieve Java objects from the directory. Using this common schema, any Java application that needs to read or store Java objects in the directory can do so in an interoperable way. 2 Representation of Java Objects This document defines two ways to represent a Java object in the directory: the first uses object serialization; the second uses a JNDI reference. 2.1 Serialized Objects To "serialize" an object means to convert its state into a byte stream in such a way that the byte stream can be reverted back into a copy of the object. A Java object is "serializable" if its class or any of its superclasses implement the Serializable interface or its subinterface Externalizable. "Deserialization" is the process of converting the serialized form of an object back into a copy of the object. The Java platform specifies a default way by which serialized objects are serialized. A (Java) class can also override this default serialization and defines its own way of serializing objects of that class. See [Serial] for details. When an object is serialized, information that identifies its class is recorded in the serialized stream. However, the class's definition ("class file") itself is not recorded. It is the responsibility of the system that is deserializing the object to determine the Ryan, et. al. [Page 2] INTERNET-DRAFT Schema for Java Objects May 1998 mechanism to use for locating and loading the associated class files. For example, the Java application might include in its classpath a JAR file containing the class files of the serialized object(s). 2.1.1 Representation in the Directory A serialized object is stored in the directory using the attributes javaClassName and javaSerializedObject, described in Section 3. A directory entry holding a serialized object is represented by the object class javaObject. It is an auxiliary object class meaning it needs to be mixed in with a structural object class. The object class javaContainer represents a directory entry dedicated to storing a Java object. It is a structural object class. In cases where javaObject is mixed in with another structural object class then javaContainer is not required. Both of these object classes are described in Section 4. 2.2 JNDI References Java Naming and Directory Interface(tm) (JNDI) [JNDI] is a directory access API specified in the Java programming language. It provides an object-oriented view of the directory, allowing Java objects to be added to and retrieved from the directory without requiring the client to manage data representation issues. JNDI defines the notion of a "reference" for use when an object cannot be stored in the directory directly, or when it is inappropriate or undesirable to do so. An object with an associated reference is stored in the directory indirectly, by storing its reference instead. 2.2.1 Contents of a Reference A JNDI reference is a Java object of class javax.naming.Reference. It consists of an ordered list of addresses, and class information about the object being referenced. An address is a Java object of class javax.naming.RefAddr. Each address contains information on how to construct the object. A common use for JNDI references is to represent connections to a network service such as a database, directory, or file system. Each address may then identify a "communications endpoint" for that service, containing information on how to contact the service. Multiple addresses may arise for various reasons, such as replication or the object offering interfaces over more than one communication Ryan, et. al. [Page 3] INTERNET-DRAFT Schema for Java Objects May 1998 mechanism. A reference also contains information to assist in creating an instance of the object to which the reference refers. It contains the Java class name of that object, and the class name and location of the object factory to be used to create the object. The procedures for creating an object given its reference, and the reverse, are described in [JNDI]. 2.2.2 Representation in the Directory An object reference is stored in the directory using the attributes javaClassName, javaReferenceAddress, javaFactory, and javaFactoryLocation, described in Section 3. These attributes store information corresponding to the contents of a reference described above. A directory entry holding a JNDI reference is represented by the object class javaNamingReference. It is an auxiliary object class meaning it needs to be mixed in with a structural object class. The object class javaContainer represents a directory entry dedicated to storing a Java object. It is a structural object class. In cases where javaNamingReference is mixed in with another structural object class then javaContainer is not required. Both of these object classes are described in Section 4. 2.3 Serialized Objects Vs. References There are some differences between storing a JNDI reference and the serialized form of an object in the directory. A reference provides a way of recording address information about an object which itself is not directly bound in the directory. For a serialized object, (a copy of) the object is itself is bound in the directory. In other words, you can think of a reference as a compact representation of the information required to access the object, while a serialized object is the representation of the object itself. A JNDI reference typically consists of a small number of human- readable strings. Standard text-based tools for directory administration may therefore be used to add, read, or modify reference entries -- if so desired -- quite easily. Serialized objects are not intended to be read or manipulated directly by humans. Ryan, et. al. [Page 4] INTERNET-DRAFT Schema for Java Objects May 1998 Another difference is that a reference may contain information about where to locate the class files for the target object. A separate out-of-band mechanism is needed to locate and load the associated classes for a serialized object, as described above. 3 Attribute Type Definitions The following attribute types are defined in this document: javaClassName javaSerializedObject javaReferenceAddress javaFactory javaFactoryLocation 3.1 javaClassName This attribute stores the Java object's fully qualified class or interface name (e.g. "java.lang.String"). This attribute's syntax is 'Directory String'. ( 1.3.6.1.4.1.42.2.27.4.1.1 NAME 'javaClassName' DESC 'Fully qualified Java class or interface name' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) 3.2 javaSerializedObject This attribute stores the serialized form of a Java object. The serialized form is described in [Serial]. This attribute's syntax is 'Binary'. ( 1.3.6.1.4.1.42.2.27.4.1.2 NAME 'javaSerializedObject' DESC 'Serialized form of a Java object' SYNTAX 1.3.6.1.4.1.1466.115.121.1.5 SINGLE-VALUE ) 3.3 javaReferenceAddress This attribute represents the sequence of addresses of a JNDI reference. Each of its values represents one address, a Java object of type javax.naming.RefAddr. Its value is a concatenation of the Ryan, et. al. [Page 5] INTERNET-DRAFT Schema for Java Objects May 1998 address type and address contents, preceded by a sequence number (the order of addresses in a JNDI reference is significant). For example: #0#TypeA#ValA #1#TypeB#ValB #2#TypeC##rO0ABXNyABpq... In more detail, the value is encoded as follows: The delimiter is the first character of the value. For readability the character '#' is recommended when it is not otherwise used anywhere in the value, but any character may be used subject to restrictions given below. The first delimiter is followed by the sequence number. The sequence number of an address is its position in the JNDI reference, with the first address being numbered 0. It is represented by its shortest string form, in decimal notation. The sequence number is followed by a delimiter, then by the address type, and then by another delimiter. If the address is of Java class javax.naming.StringRefAddr, then this delimiter is followed by the value of the address contents (which is a string). Otherwise, this delimiter is followed immediately by another delimiter, and then by the Base64 encoding of the serialized form of the entire address. The delimiter may be any character other than a digit or a character contained in the address type. In addition, if the address contents is a string, the delimiter may not be the first character of that string. This attribute's syntax is 'Directory String'. It can contain multiple values. ( 1.3.6.1.4.1.42.2.27.4.1.3 NAME 'javaReferenceAddress' DESC 'Addresses associated with a JNDI Reference' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) 3.4 javaFactory This attribute stores the fully qualified class name of the object factory (e.g. "com.wiz.jndi.WizObjectFactory") that can be used to create an instance of the object identified by the javaClassName attribute. This attribute's syntax is 'Directory String'. Ryan, et. al. [Page 6] INTERNET-DRAFT Schema for Java Objects May 1998 ( 1.3.6.1.4.1.42.2.27.4.1.4 NAME 'javaFactory' DESC 'Fully qualified Java class name of a JNDI object factory' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) 3.5 javaFactoryLocation This attribute stores the location for loading the object factory identified by the javaFactory attribute. For example, this can be a URL specifying a JAR file from which to load the object factory class. This attribute's syntax is 'Directory String'. ( 1.3.6.1.4.1.42.2.27.4.1.5 NAME 'javaFactoryLocation' DESC 'Location of a JNDI object factory' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) 4 Object Class Definitions The following object classes are defined in this document: javaContainer javaObject javaNamingReference 4.1 javaContainer This structural object class represents a container for a Java object. ( 1.3.6.1.4.1.42.2.27.4.2.1 NAME 'javaContainer' DESC 'Container for a Java object' SUP top STRUCTURAL MUST cn ) 4.2 javaObject This auxiliary object class represents a serialized Java object. Ryan, et. al. [Page 7] INTERNET-DRAFT Schema for Java Objects May 1998 It must be mixed in with a structural object class. ( 1.3.6.1.4.1.42.2.27.4.2.2 NAME 'javaObject' DESC 'Serialized Java object' SUP top AUXILIARY MAY ( javaClassName $ javaSerializedObject ) ) 4.3 javaNamingReference This auxiliary object class represents a JNDI reference. It must be mixed in with a structural object class. ( 1.3.6.1.4.1.42.2.27.4.2.3 NAME 'javaNamingReference' DESC 'JNDI reference' SUP top AUXILIARY MAY ( javaClassName $ javaReferenceAddress $ javaFactory $ javaFactoryLocation ) ) 5. Security Considerations Serializing an object and storing it into the directory enables (a copy of) the object to be examined and used outside the environment in which it was originally created. The directory entry containing the serialized object could be read and modified within the constraints imposed by the access control mechanisms of the directory. If an object contains sensitive information or information that could be misused outside of the context in which it was created, the object should not be stored in the directory. For more details on security-related issues relating to serialized objects in general, see [Serial]. Ryan, et. al. [Page 8] INTERNET-DRAFT Schema for Java Objects May 1998 6. References [Java] Ken Arnold and James Gosling, "The Java(tm) Programming Language", Second Edition, ISBN 0-201-31006-6. [JNDI] The Java(tm) Naming and Directory Interface (tm) Specifica- tion, JavaSoft Division, Sun Microsystems, Inc., Feb 1998. http://java.sun.com/products/jndi/. [LDAPv3] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol (v3)" RFC2251, December 1997. [Serial] Object Serialization Specification, JavaSoft Division, Sun Microsystems, Inc., February 1997. http://java.sun.com/products/jdk/1.1/docs/guide/serialization/spec.doc.html 7. Authors' Addresses Vincent Ryan Sun Microsystems, Inc. Mail Stop EDUB03 901 San Antonio Road Palo Alto, CA 94303 USA +353 1 819 9151 vincent.ryan@ireland.sun.com Scott Seligman Sun Microsystems, Inc. Mail Stop UCUP02-209 901 San Antonio Road Palo Alto, CA 94303 USA +1 408 863 3222 scott.seligman@eng.sun.com Rosanna Lee Sun Microsystems, Inc. Mail Stop UCUP02-206 901 San Antonio Road Palo Alto, CA 94303 USA +1 408 863 3221 rosanna.lee@eng.sun.com Ryan, et. al. [Page 9]