From: Kurt Zeilenga Date: Mon, 22 Nov 1999 01:51:34 +0000 (+0000) Subject: Add recently added LDAP-related RFCs X-Git-Tag: UCDATA_2_4~180 X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=c2e18e1af74eea289e92a60c53065e8fef260c78;p=openldap Add recently added LDAP-related RFCs --- diff --git a/doc/rfc/rfc2649.txt b/doc/rfc/rfc2649.txt new file mode 100644 index 0000000000..fb5f38eab8 --- /dev/null +++ b/doc/rfc/rfc2649.txt @@ -0,0 +1,563 @@ + + + + + + +Network Working Group B. Greenblatt +Request for Comments: 2649 P. Richard +Category: Experimental August 1999 + + + An LDAP Control and Schema for Holding Operation Signatures + +Status of this Memo + + This memo defines an Experimental Protocol for the Internet + community. It does not specify an Internet standard of any kind. + Discussion and suggestions for improvement are requested. + Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (1999). All Rights Reserved. + +Abstract + + In many environments clients require the ability to validiate the + source and integrity of information provided by the directory. This + document describes an LDAP message control which allows for the + retrieval of digitally signed information. This document defines an + LDAP v3 based mechanism for signing directory operations in order to + create a secure journal of changes that have been made to each + directory entry. Both client and server based signatures are + supported. An object class for subsequent retrieval are "journal + entries" is also defined. This document specifies LDAP v3 controls + that enable this functionality. It also defines an LDAP v3 schema + that allows for subsequent browsing of the journal information. + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 + 1.1 Audit Trail Mechanism . . . . . . . . . . . . . . . . . . . 2 + 1.2. Handling the Delete Operation . . . . . . . . . . . . . . . 5 + 2. Signed Results Mechanism . . . . . . . . . . . . . . . . . . 6 + 3. Security Considerations and Other Notes . . . . . . . . . . 7 + 4. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 + 5. Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 9 + 6. Full Copyright Statement . . . . . . . . . . . . . . . . . . 10 + + + + + + + + + +Greenblatt & Richard Experimental [Page 1] + +RFC 2649 LDAP Control and Schema August 1999 + + +1. Introduction + + In many environments clients require the ability to validiate the + source and integrity of information provided by the directory. This + document describes an LDAP message control which allows for the + retrieval of digitally signed information. The perspective of this + document is that the origin of the information that is stored in LDAP + v3 accessible directories is the LDAP v3 client that creates the + information. The source and integrity of the information is + guaranteed by allowing for the digital signing of the operations that + make changes to entries in the directory. The source and integrity + of an individual LDAP connection can be guaranteed by making use of + an underlying session layer that provides such services, such as TLS. + Note that the integrity of an individual connection does not, in and + of itself guarantee the integrity of the data that comes across the + connection. This is due to the fact that the LDAP server is only + capable of providing information that it has stored. In distributed + and replicated environments, the fact that an entry has been + successfully retrieved from a server may not be completely + reassuring, if the entry in question was replicated from an untrusted + domain. + + By making use of public key technology, and creating digitally signed + transactions that are created by the LDAP v3 client as entries are + created and modified, a complete journal of the history of the entry + is available. Since each entry in the journal has been digitally + signed with the private key of the creator, or modifier of the entry, + the source and integrity of the directory entry can be validated by + verifying the signature of each entry in the journal. Note that not + all of the journal entries will have been signed by the same user. + +1.1. Audit Trail Mechanism + + Signed directory operations is a straightforward application of + S/MIME technology that also leverages the extensible framework that + is provided by LDAP version 3. LDAP version 3 is defined in [4], and + S/MIME is defined in [2]. The security used in S/MIME is based in + the definitions in [1]. The basic idea is that the submitter of an + LDAP operation that changes the directory information includes an + LDAP version 3 control that includes either a signature of the + operation, or a request that the LDAP server sign the operation on + the behalf of the LDAP client. The result of the operation (in + addition to the change of the directory information), is additional + information that is attached to directory objects, that includes the + audit trail of signed operations. The LDAP control is (OID = + 1.2.840.113549.6.0.0): + + + + + +Greenblatt & Richard Experimental [Page 2] + +RFC 2649 LDAP Control and Schema August 1999 + + + SignedOperation ::= CHOICE { + signbyServer NULL, + signatureIncluded OCTET STRING + } + + If the SignatureIncluded CHOICE is used, then the OCTET string is + just an S/MIME message of the multipart/signed variety, that is + composed of a single piece, that is the signature of the directory + operation. Multipart/signed MIME objects are defined in [3]. If the + SignbyServer CHOICE us used, then the LDAP server creates the + signature on behalf of the client, using its own identity and not the + identity of the client, in order to produce the audit trail entry. + In either case the successful result of processing the control is the + creation of additional information in the directory entry that is + being modified or created. The signature of the LDAP operation is + computed on the LDAPMessage prior to the inclusion of the + SignedOperation control. The procedure is as follows: + + - Build LDAPMessage without the SignedOperation control + - Compute signature on the above LDAPMessage + - Create new LDAPMessage that includes the old MessageID, + protocolOp and any control fields from the previous LDAPMessage, + plus the computed signature formatted as an S/MIME message. + + No control is defined for the server to return in the LDAPResult as + defined in [4]. The LDAP server MAY attempt to parse and verify the + signature included in the SignedOperation control, but is not + required to. The server can accept the signed operation without + verifying the signature. Signature verification can be quite a + lengthy operation, requiring complex certificate chain traversals. + This allows a more timely creation of the audit trail by the server. + Any LDAP client browsing the directory that retrieves the 'Changes' + (defined in the following paragraphs) attributes, should verify the + signature of each value according to the local signature verification + policies. Even if the LDAP server verifies the signature contained + in the singed operation, the LDAP client has no way of knowing what + policies were followed by the server in order to verify the + signature. + + If the LDAP server is unable to verify the signature and wishes to + return an error then the error code unwillingToPerform(53) should be + returned, and the entire LDAP operation fails. In this situation, an + appropriate message (e.g. "Unable to verify signature") MAY be + included in the errorMessage of the LDAPResult. The SignedOperation + Control MAY be marked CRITICAL, and if it is CRITICAL then if the + LDAP Server performs the LDAP operation, then must include the + signature in the signedAuditTrail information. + + + + +Greenblatt & Richard Experimental [Page 3] + +RFC 2649 LDAP Control and Schema August 1999 + + + The schema definition for the signedAuditTrail information is: + + ( 1.2.840.113549.6.1.0 + NAME 'signedAuditTrail' + SUP top + AUXILIARY + MUST ( + Changes + ) + ) + + The format of the Changes attribute is: + + ( 1.2.840.113549.6.2.0 + NAME 'Changes' + DESC 'a set of changes applied to an entry' + SYNTAX 'Binary' ) + + The actual format of the Changes attribute is: + + Changes ::= SEQUENCE { + sequenceNumber [0] INTEGER (0 .. maxInt), + signedOperation [1] OCTET STRING } + + The SignedOperation attribute is a multipart/signed S/MIME message. + Part 1 of the message is the directory operation, and part 2 is the + signature. Sequence number 0 (if present) always indicates the + starting point directory object as represented by the definitions in + "A MIME Content-Type for Directory Information", as defined in [5]. + Subsequent sequence numbers indicate the sequence of changes that + have been made to this directory object. Note that the sequence of + the changes can be verified due to the fact that the signed directory + object will have a timestamp as part of the signature object, and + that the sequence numbering as part of the change attribute should be + considered to be an unverified aid to the LDAP client. Sequence + numbers are meaningful only within the context of a single directory + entry, and LDAP servers are not expected to maintain these sequence + numbers across all entries in the directory. + + Some LDAP servers will only allow operations that include the + SignedOperation control. This is indicated by the inclusion of a + 'signedDirectoryOperationSupport' attribute in the rootDSE. This + attribute is defined as: + + + + + + + + +Greenblatt & Richard Experimental [Page 4] + +RFC 2649 LDAP Control and Schema August 1999 + + + 1.2.840.113549.6.2.2 + NAME 'signedDirectoryOperationSupport' + DESC 'how many of the LDAP operations must be signed' + SYNTAX 'Integer' SINGLE-VALUE ) + + The 'signedDirectoryOperationSupport' attribute above may have one of + the values, '0', '1' or '2' with the following meanings: + + - '0' Directory Operations may be signed + - '1' Directory Operations must always be signed + - '2' Directory Operations must never be signed + + Some LDAP servers will desire that the audit trail be continuous, and + not contain any gaps that would result from unsigned operations. + Such server will include a signature on each LDAP operation that + changes a directory entry, even when the LDAP client does not include + a signed-Operation control. + +1.2. Handling the Delete Operation + + The LDAP Delete operation represents an interesting case for Signed + Directory Operations. This is due to the case that subsequent to the + successful completion of the Delete Operation, the object that would + have held the latest 'Changes' attribute no longer exists. In order + to handle this situation, a new object class is defined to represent + a directory object that has been deleted. + + ( 1.2.840.113549.6.1.2 + NAME 'zombieObject' + SUP top + STRUCTURAL + MUST ( + Cn $ Changes $ OriginalObject + ) + ) + + The format of the OriginalObject attribute is: + + ( 1.2.840.113549.6.2.1 + NAME OriginalObject + DESC 'The LDAP URL of an object that has been deleted from the + directory' SYNTAX 'Binary' ) + + The OriginalObject attribute contains the URL of the object that was + deleted from the directory. It is formatted in accordance with RFC + 2255. Directory servers that comply with this specification SHOULD + create a zombieObject when performing the delete Operation that + contains a SignedOperation LDAPControl. The Cn attribute of the + + + +Greenblatt & Richard Experimental [Page 5] + +RFC 2649 LDAP Control and Schema August 1999 + + + zombieObject is synthesized by the LDAP server, and may or may not be + related to the original name of the directory entry that was deleted. + All changes attributes that were attached to the original entry are + copied over to the zombieObject. In addition the LDAP Server MUST + attach the signature of the Delete operation as the last successful + change that was made to the entry. + +2. Signed Results Mechanism + + A control is also defined that allows the LDAP v3 client to request + that the server sign the results that it returns. It is intended + that this control is primarily used in concert with the LDAPSearch + operation. This control MAY be marked as CRITICAL. If it is marked + as CRITICAL and the LDAP Server supports this operation, then all + search results MUST be returned with a signature as attached in the + SignedResult control if it is willing to sign results for this user. + If the server supports this control but does not wish to sign the + results for this user then the error code unwillingToPerform(53) + should be returned, and the LDAP search will have failed. In this + situation, an appropriate message (e.g. "Unwilling to sign results + for you!") MUST be included in the errorMessage of the LDAPResult. + If the LDAPSigType has the value FALSE then the client is requesting + that the server not sign this operation. This may be done in + situations where servers are configured to always sign their + operations. + + The LDAP control to include in the LDAP request is (OID = + 1.2.840.113549.6.0.1): + + DemandSignedResult ::= LDAPSigType + + LDAPSigType ::= BOOLEAN + + In response to a DemandSignedResult control, the LDAP v3 server will + return a SignedResult control in addition to the normal result as + defined by the operation (assuming that the server understands the + con- trol, and is willing to perform it). The SignedResult control + MUST NOT be marked CRITICAL. Some LDAP v3 servers may be configured + to sign all of their operations. In this situation the server always + returns a SignedResult control, unless instructed otherwise by the + DemandSigne-dResult Control. Since the SignedResult control is not + marked critical, the LDAP client is allowed to ignore it. The + signature field below includes the signature of the enitre LDAPResult + formatted as an S/MIME pkcs-7/signature object, as defined in [2]. + + + + + + + +Greenblatt & Richard Experimental [Page 6] + +RFC 2649 LDAP Control and Schema August 1999 + + + The procedure for creating the signature of the signedResult control + is the same as the procedure for the creation of the signedOperation + control. The LDAP control in the LDAP response is (OID = + 1.2.840.113549.6.0.2): + + SignedResult ::= CHOICE { + signature OCTET STRING } + +3. Security Considerations and Other Notes + + The base OIDs are: + + rsadsiLdap ::= {1 2 840 113549 6} + rsadsiLdapControls ::= {1 2 840 113549 6 0} + rsadsiLdapObjectClasses ::= {1 2 840 113549 6 1} + rsadsiLdapAttributes ::= {1 2 840 113549 6 2} + + + The complete ASN.1 module for this specification is: + + SIGNEDOPERATIONS DEFINITIONS ::= + BEGIN + + SignedOperation ::= CHOICE { + signbyServer NULL, + signatureIncluded OCTET STRING + } + + Changes ::= SEQUENCE { + sequenceNumber [0] INTEGER (0 .. maxInt), + signedOperation [1] OCTET STRING } + + DemandSignedResult ::= LDAPSigType + + LDAPSigType ::= BOOLEAN + + SignedResult ::= CHOICE { + signature OCTET STRING } + + + END + + + + + + + + + + +Greenblatt & Richard Experimental [Page 7] + +RFC 2649 LDAP Control and Schema August 1999 + + + If any of the controls in this specification are supported by an LDAP + v3 server then that server MUST make available its certificate (if + any) in the userCertificate attribute of its rootDSE object. The + UserCertificate attribute is defined in [6], and contains the public + key of the server that is used in the creation of the various + signatures defined in this specification. + + It is not the intention of this specification to provide a mechanism + that guarantees the origin and integrity of LDAP v3 operations. Such + a service is best provided by the use of an underlying protocol such + as TLS [8]. TLS defines additional features such as encryption and + compression. This specification does not define support for + encrypted operations. + + This memo proposes protocol elements for transmission and storage of + the digital signatures of LDAP operations. Though the LDAP server + may have verified the operation signatures prior to their storage and + subsequent retrieval, it is prudent for LDAP clients to verify the + signatures contained in the chained attribute upon their retrieval. + The issuing Certification Authorities of the signer's certificate + should also be consulted in order to determine if the signer's + private key has been compromised or the certificate has been + otherwise revoked. Security considerations are discussed throughout + this memo. + +4. References + + [1] Kaliski, B., "PKCS 7: Cryptographic Message Syntax Version 1-5", + RFC 2315, March 1998. + + [2] Dusse, S., Hoffman, P., Ramsdell, B., Lundblade, L. and L. + Repka., "S/MIME Version 2 Message Specification", RFC 2311, March + 1998. + + [3] Galvin, J., Murphy, S., Crocker, S. and N. Freed, "Security + Multiparts for MIME: Multipart/Signed and Multipart/Encrypted", + RFC 1847, October 1995. + + [4] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory Access + Protocol (v3)", RFC 2251, December 1997. + + [5] Howes, T., Smith, M. and F. Dawson, "A MIME Content-Type for + Directory Information", RFC 2425, September 1998. + + [6] Wahl, M., "A Summary of the X.500(96) User Schema for use with + LDAPv3", RFC 2256, December 1997. + + + + + +Greenblatt & Richard Experimental [Page 8] + +RFC 2649 LDAP Control and Schema August 1999 + + + [7] Howes, T. and M. Smith, "The LDAP URL Format", RFC 2255, December + 1997. + + [8] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", RFC + 2246, January 1999. + +5. Authors' Addresses + + Bruce Greenblatt + San Jose, CA 95119 + USA + + Phone: +1-408-224-5349 + EMail: bgreenblatt@directory-applications.com + + + Pat Richard + Xcert Software, Inc. + Suite 1001 - 701 W. Georgia + Vancouver, BC + CANADA V6G 1C9 + + EMail: patr@xcert.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Greenblatt & Richard Experimental [Page 9] + +RFC 2649 LDAP Control and Schema August 1999 + + +6. Full Copyright Statement + + Copyright (C) The Internet Society (1999). All Rights Reserved. + + This document and translations of it may be copied and furnished to + others, and derivative works that comment on or otherwise explain it + or assist in its implementation may be prepared, copied, published + and distributed, in whole or in part, without restriction of any + kind, provided that the above copyright notice and this paragraph are + included on all such copies and derivative works. However, this + document itself may not be modified in any way, such as by removing + the copyright notice or references to the Internet Society or other + Internet organizations, except as needed for the purpose of + developing Internet standards in which case the procedures for + copyrights defined in the Internet Standards process must be + followed, or as required to translate it into languages other than + English. + + The limited permissions granted above are perpetual and will not be + revoked by the Internet Society or its successors or assigns. + + This document and the information contained herein is provided on an + "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING + TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING + BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION + HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF + MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + + + + + + + + + + + + + +Greenblatt & Richard Experimental [Page 10] + diff --git a/doc/rfc/rfc2657.txt b/doc/rfc/rfc2657.txt new file mode 100644 index 0000000000..d23a877081 --- /dev/null +++ b/doc/rfc/rfc2657.txt @@ -0,0 +1,675 @@ + + + + + + +Network Working Group R. Hedberg +Request for Comment: 2657 Catalogix +Category: Experimental August 1999 + + + LDAPv2 Client vs. the Index Mesh + +Status of this Memo + + This memo defines an Experimental Protocol for the Internet + community. It does not specify an Internet standard of any kind. + Discussion and suggestions for improvement are requested. + Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (1999). All Rights Reserved. + +Abstract + + LDAPv2 clients as implemented according to RFC 1777 [1] have no + notion on referral. The integration between such a client and an + Index Mesh, as defined by the Common Indexing Protocol [2], heavily + depends on referrals and therefore needs to be handled in a special + way. This document defines one possible way of doing this. + +1. Background + + During the development of the Common Indexing Protocol (CIP), one of + the underlying assumptions was that the interaction between clients + and the Index Mesh Servers [1] would heavily depend on the passing of + referrals. Protocols like LDAPv2 [2] that lack this functionality + need to compensate for it by some means. The way chosen in this memo + is to add more intelligence into the client. There are two reasons + behind this decision. First, this is not a major enhancement that is + needed and secondly, that the intelligence when dealing with the + Index Mesh, with or the knowledge about referrals, eventually has to + go into the client. + +2. The clients view of the Index Mesh + + If a LDAPv2 client is going to be able to interact with the Index + Mesh, the Mesh has to appear as something that is understandable to + the client. Basically, this consists of representing the index + servers and their contained indexes in a defined directory + information tree (DIT) [3,4] structure and a set of object classes + and attribute types that have been proven to be useful in this + context. + + + +Hedberg Experimental [Page 1] + +RFC 2657 LDAPv2 vs. Index Mesh August 1999 + + +2.1 The CIP Object Classes + + Object class descriptions are written according to the BNF defined in + [5]. + +2.1.1 cIPIndex + + The cIPIndex objectClass, if present in a entry, allows it to hold + one indexvalue and information connected to this value. + + ( 1.2.752.17.3.9 + NAME 'cIPIndex' + SUP 'top' + STRUCTURAL + MUST ( extendedDSI $ idx ) + MAY ( indexOCAT ) + ) + +2.1.2 cIPDataSet + + The cIPDataSet objectClass, if present in a entry, allows it to hold + information concerning one DataSet. + + ( 1.2.752.17.3.10 + NAME 'cIPDataSet' + SUP 'top' + STRUCTURAL + MUST ( dSI $ searchBase ) + MAY ( indexOCAT $ description $ indexType $ + accessPoint $ protocolVersion $ polledBy $ + updateIntervall $ securityOption $ + supplierURI $ consumerURI $ baseURI $ + attributeNamespace $ consistencyBase + ) + ) + +2.2 The CIP attributeTypes + + The attributes idx, indexOCAT, extendedDSI, description, + cIPIndexType, baseURI, dSI are used by a client accessing the index + server. The other attributes (accesspoint, protocolVersion, + polledBy, updateIntervall, consumerURI, supplierURI and + securityOption, attributeNamespace, consistencyBase) are all for + usage in server to server interactions. + + + + + + + +Hedberg Experimental [Page 2] + +RFC 2657 LDAPv2 vs. Index Mesh August 1999 + + +2.2.1 idx + + The index value, normally used as part of the RDN. + + ( 1.2.752.17.1.20 + NAME 'idx' + EQUALITY caseIgnoreIA5Match + SYNTAX IA5String + SINGLE-VALUE + ) + +2.2.2 dSI + + DataSet Identifier, a unique identifier for one particular set of + information. This should be an OID, but stored in a stringformat. + + ( 1.2.752.17.1.21 + NAME 'dSI' + EQUALITY caseIgnoreIA5Match + SYNTAX IA5String + ) + +2.2.3 indexOCAT + + Describes the type of data that is stored in this entry, by using + objectcClasses and attributeTypes. The information is stored as a + objectClass name followed by a space and then an attributeType name. + A typical example when dealing with whitepages information would be + "person cn". + + ( 1.2.752.17.1.28 + NAME 'indexOCAT' + EQUALITY caseIgnoreIA5Match + SYNTAX IA5String + ) + +2.2.5 supplierURI + + A URI describing which protocols, hostnames and ports should be used + by an indexserver to interact with servers carrying indexinformation + representing this dataSet. + + ( 1.2.752.17.1.22 + NAME 'supplierURI' + EQUALITY caseIgnoreIA5Match + SYNTAX IA5String + ) + + + + +Hedberg Experimental [Page 3] + +RFC 2657 LDAPv2 vs. Index Mesh August 1999 + + +2.2.6 baseURI + + The attribute value for this attribute is a LDAP URI. One can + envisage other URI syntaxes, if the client knows about more access + protocols besides LDAP, and the interaction between the client and + the server can not use referrals for some reason. + + ( 1.2.752.17.1.26 + NAME 'baseURI' + EQUALITY caseExactIA5Match + SYNTAX IA5String + ) + +2.2.7 protocolVersion + + At present, the Common Indexing Protocol version should be 3. + + ( 1.2.752.17.1.27 + NAME 'protocolVersion' + EQUALITY numericStringMatch + SYNTAX numericString + ) + +2.2.8 cIPIndexType + + The type of index Object that is used to pass around index + information. + + ( 1.2.752.17.1.29 + NAME 'cIPIndexType' + EQUALITY caseIgnoreIA5Match + SYNTAX IA5String + ) + +2.2.10 polledBy + + The Distinguished Name of Index servers that polls data from this + indexserver. + + ( 1.2.752.17.1.30 + NAME 'polledBy' + EQUALITY distinguishedNameMatch + SYNTAX DN + ) + + + + + + + +Hedberg Experimental [Page 4] + +RFC 2657 LDAPv2 vs. Index Mesh August 1999 + + +2.2.11 updateIntervall + + The maximum duration in seconds between the generation of two updates + by the supplier server. + + ( 1.2.752.17.1.31 + Name 'updateIntervall' + EQUALITY numericStringMatch + SYNTAX numericString + SINGLE-VALUE + ) + +2.2.12 securityOption + + Whether and how the supplier server should sign and encrypt the + update before sending it to the consumer server. + + ( 1.2.752.17.1.32 + NAME 'securityOption' + EQUALITY caseIgnoreIA5Match + SYNTAX IA5String + SINGLE-VALUE + ) + +2.2.13 extendedDSI + + DataSet Identifier possibly followed by a space and a taglist, the + later as specified by [6]. + + ( 1.2.752.17.1.33 + NAME 'extendedDSI' + EQUALITY caseIgnoreIA5Match + SYNTAX IA5String + ) + +2.2.14 consumerURI + + A URI describing which means a server can accept indexinformation. + An example being a mailto URI for MIME email based index transport. + + ( 1.2.752.17.1.34 + NAME 'consumerURI' + EQUALITY caseExactIA5Match + SYNTAX IA5String + ) + + + + + + +Hedberg Experimental [Page 5] + +RFC 2657 LDAPv2 vs. Index Mesh August 1999 + + +2.2.15 attributeNamespace + + Any consumer supplier pair has to agree on what attribute that should + be used and also possibly the meaning of the attributenames. The + value of this attribute should, for example, be a URI pointing to a + document wherein the agreement is described. + + ( 1.2.752.17.1.35 NAME 'attributeNamespace' EQUALITY + caseExactIA5Match SYNTAX IA5String + ) + +2.2.16 consistencyBase + + This attribute is specifically used by consumer supplier pairs that + use the tagged index object [6]. + + ( 1.2.752.17.1.36 + NAME 'consistencyBase' + EQUALITY caseExactIA5Match + SYNTAX IA5String + ) + +3. The interaction between a client and the Index Mesh + + A client interaction with the Index Mesh consists of a couple of + rather well defined actions. The first being to find a suitable index + to start with, then to transverse the Index Mesh and finally to query + the servers holding the original data. Note when reading this text + that what is discussed here is the client's perception of the DIT, + how it is in fact implemented is not discussed. + +3.1 Finding a Index Mesh + + This approach depends on the fact that every index server partaking + in an Index Mesh is represented in the DIT by a entry of the type + cIPDataSet, and has a distinguished name (DN) which most significant + relative distinguished name (RDN) has the attributetype dSI. + Therefore, finding a suitable indexserver to start the search from is + a matter of searching the DIT at a suitable place for objects with + the objectClass cIPIndexObject. Every found entry can then be + evaluated by looking at the description value as well as the + indexOCAT value. The description string should be a human readable + and understandable text that describes what the index server is + indexing. An example of such a string could be, "This index covers + all employees at Swedish Universities and University Colleges that + has an email account". The indexOCAT attribute supplies information + about which kind of entries and which attributes within these entries + that the index information has emanated from. For example, if the + + + +Hedberg Experimental [Page 6] + +RFC 2657 LDAPv2 vs. Index Mesh August 1999 + + + indexOCAT attribute value is "person cn", one can deduce that this is + an index over persons and not over roles, and that it is the + attribute commonName that is indexed. + +3.2 Searching the mesh + + Each index server has its information represented in the DIT as a + very flat tree. In fact, it is only one level deep. + + + 0 Indexservers cIPDataSet + /|\ + / | \ + / | \ + 0 0 + cIPDataSet entries cIPIndex entries + one for each DataSet one for each index value + that this server has that this indexserver + gathered indexes from. has. + + A search then consists of a set of searches. The first being the + search for the index entries that contains an indexvalue that matches + what the user is looking for, and the second a search based on the + DSI information in the extendedDSI attribute values returned from the + first search. In the case of the the cIPIndexType being tagged- + index, the taglists should be compared to find which DSI it might be + useful to pose further queries to. + + When doing these types of searches, the client should be aware of the + fact that the index values disregarding their origin (attributeTypes) + always are stored in the index server as values of the idx attribute. + + The object of the second search is to get information on the + different DataSet involved, and should normally be performed as a + read. Since the DataSet information probably will remain quite stable + over time, this information lends itself very well to caching. If at + this stage there is more than one DataSet involved, the User + interface might use the description value to aid the user in choosing + which one to proceed with. The content of the searchBase value of + the DataSet tells the client whether it represents another index + server (the most significant part of the dn is a dSI attribute) or if + it is a end server. + + + + + + + + + +Hedberg Experimental [Page 7] + +RFC 2657 LDAPv2 vs. Index Mesh August 1999 + + +3.3 Querying the end server + + When finally reaching the end server/servers that probably has the + sought for information, the information in the indexOCAT attribute + can be used to produce an appropriate filter. If a search for "Rol*" + in an index having an indexOCAT attribute value of "person cn" + returns an idx entry with the idx value of "Roland", then an + appropriate filter to use might be "&(|(cn=* roland *)(cn=roland + *)(cn=* roland))(objectclass=person)". A complete example of a + search process is given in Appendix A. + +4. Security Considerations + + Since this memo deals with client behavior, it does not add anything + that either enhances or diminishes the security features that exists + in LDAPv2. + +5. Internationalization + + As with security, this memo neither enhances or diminishes the + handling of internationalization in LDAPv2. + +6. References + + [1] Yeong, W., Howes, T. and S. Kille, "Lightweight Directory Access + Protocol", RFC 1777, March 1995. + + [2] Allen, J. and M. Mealling "The Architecture of the Common + Indexing Protocol (CIP)", RFC 2651, August 1999. + + [3] The Directory: Overview of Concepts, Models and Service. CCITT + Recommendation X.500, 1988. + + [4] Information Processing Systems -- Open Systems Interconnection -- + The Directory: Overview of Concepts, Models and Service. ISO/IEC + JTC 1/SC21; International Standard 9594-1, 1988. + + [5] Wahl, M., Coulbeck, A., Howes, T. and S. Kille, "Lightweight + Directory Access Protocol (v3): Attribute Syntax Definitions", + RFC 2252, December 1997. + + [6] Hedberg, R., Greenblatt, B., Moats, R. and M. Wahl, "A Tagged + Index Object for use in the Common Indexing Protocol", RFC 2654, + August 1999. + + + + + + + +Hedberg Experimental [Page 8] + +RFC 2657 LDAPv2 vs. Index Mesh August 1999 + + +7. Author's Address + + Roland Hedberg + Catalogix + Dalsveien 53 + 0387 Oslo, Norway + + Phone: +47 23 08 29 96 + EMail: roland@catalogix.ac.se + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Hedberg Experimental [Page 9] + +RFC 2657 LDAPv2 vs. Index Mesh August 1999 + + +Appendix A - Sample Session + + Below is a sample of a session between a LDAPv2 client and an index + server mesh as specified in this memo. + + The original question of the session is to find the email address of + a person by the name, "Roland Hedberg", who is working at "Umea + University" in Sweden. + + Step 1. + + A singlelevel search with the baseaddress "c=SE" and the filter + "(objectclass=cipDataset)" was issued. + + The following results were received: + + DN: dSI=1.2.752.17.5.0,c=SE + dsi= 1.2.752.17.5.0 + description= "index over employees with emailaddresses within Swedish + higher education" + indexOCAT= "cn person" + cIPIndexType= "x-tagged-index-1" ; + searchBase= "dsi=1.2.752.17.5.0,c=SE" + protocolVersion = 3 + + DN: dSI=1.2.752.23.1.3,c=SE + dsi= 1.2.752.23.1.3 + description= "index over Swedish lawyers" + indexOCAT= "cn person" + cIPIndexType= "x-tagged-index-1" ; + searchBase= "dsi=1.2.752.23.1.3,c=SE" + protocolVersion = 3 + + Step 2. + + Since the first index seemed to cover the interesting population, a + single level search with the baseaddress "dsi=1.2.752.17.5.0,c=SE" + and the filter "(|(idx=roland)(idx=hedberg))" was issued. + + The following results were received: + + DN: idx=Roland,dSI=1.2.752.17.5.0,c=SE + idx= Roland + extendedDSI= 1.2.752.17.5.10 1,473,612,879,1024 + extendedDSI= 1.2.752.17.5.14 35,78,150,200 + extendedDSI= 1.2.752.17.5.16 187,2031,3167,5284,6034-6040 + extendedDSI= 1.2.752.17.5.17 17 + + + + +Hedberg Experimental [Page 10] + +RFC 2657 LDAPv2 vs. Index Mesh August 1999 + + + DN: idx=Hedberg,dSI=1.2.752.17.5.0,c=SE + idx= Hedberg + extendedDSI= 1.2.752.17.5.8 24,548-552,1066 + extendedDSI= 1.2.752.17.5.10 473,512,636,777,1350 + extendedDSI= 1.2.752.17.5.14 84,112,143,200 + extendedDSI= 1.2.752.17.5.15 1890-1912 + extendedDSI= 1.2.752.17.5.17 44 + + A comparison between the two sets of extendedDSIs shows that two + datasets 1.2.752.17.5.10 and 1.2.752.17.5.14 contains persons named + "Roland" and "Hedberg". Therefore, the next step would be to see what + the datasets represent. A comparison like this should normally not + be left to the user. + + Step. 3 + + Two baselevel searches, one for + "dsi=1.2.752.17.5.10,dsi=1.2.752.17.5.0,c=SE" and the other for + "dsi=1.2.752.17.5.14,dsi=1.2.752.17.5.0,c=SE" with the filter + "(objectclass=cipdataset)" were issued. + + The following results were received: + + DN: dSI=1.2.752.17.5.10,dSI=1.2.752.17.5.0,c=SE + dsi= 1.2.752.17.5.10 + description= "Employees at Umea University,Sweden" + indexOCAT= "person cn" + searchBase= "o=Umea Universitet,c=SE" + + respectively + + DN: dSI=1.2.752.17.5.14,dSI=1.2.752.17.5.0,c=SE + dsi= 1.2.752.17.5.14 + description= "Employees at Lund University,Sweden" + indexOCAT= "person cn" + searchBase= "o=Lunds Universitet,c=SE" + + Step 4 + + Based on the descriptions for the two datasets, "1.2.752.17.5.10" was + chosen as the best to proceed with. From the searchbase attribute + value, it was clear that this was a base server. The query now has + to be somewhat modified. One possibility would be to issue a query + with the baseobject "o=Umea Universitet,c=SE" and the filter + "(&(cn=Roland Hedberg)(objectclass=person))" + + + + + + +Hedberg Experimental [Page 11] + +RFC 2657 LDAPv2 vs. Index Mesh August 1999 + + +Full Copyright Statement + + Copyright (C) The Internet Society (1999). All Rights Reserved. + + This document and translations of it may be copied and furnished to + others, and derivative works that comment on or otherwise explain it + or assist in its implementation may be prepared, copied, published + and distributed, in whole or in part, without restriction of any + kind, provided that the above copyright notice and this paragraph are + included on all such copies and derivative works. However, this + document itself may not be modified in any way, such as by removing + the copyright notice or references to the Internet Society or other + Internet organizations, except as needed for the purpose of + developing Internet standards in which case the procedures for + copyrights defined in the Internet Standards process must be + followed, or as required to translate it into languages other than + English. + + The limited permissions granted above are perpetual and will not be + revoked by the Internet Society or its successors or assigns. + + This document and the information contained herein is provided on an + "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING + TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING + BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION + HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF + MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + + + + + + + + + + + + + +Hedberg Experimental [Page 12] + diff --git a/doc/rfc/rfc2696.txt b/doc/rfc/rfc2696.txt new file mode 100644 index 0000000000..4ccc4c169a --- /dev/null +++ b/doc/rfc/rfc2696.txt @@ -0,0 +1,395 @@ + + + + + + +Network Working Group C. Weider +Request for Comments: 2696 A. Herron +Category: Informational A. Anantha + Microsoft + T. Howes + Netscape + September 1999 + + + LDAP Control Extension for Simple Paged Results Manipulation + +Status of this Memo + + This memo provides information for the Internet community. It does + not specify an Internet standard of any kind. Distribution of this + memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (1999). All Rights Reserved. + +1. Abstract + + This document describes an LDAPv3 control extension for simple paging + of search results. This control extension allows a client to control + the rate at which an LDAP server returns the results of an LDAP + search operation. This control may be useful when the LDAP client has + limited resources and may not be able to process the entire result + set from a given LDAP query, or when the LDAP client is connected + over a low-bandwidth connection. Other operations on the result set + are not defined in this extension. This extension is not designed to + provide more sophisticated result set management. + + The key words "MUST", "SHOULD", and "MAY" used in this document are + to be interpreted as described in [bradner97]. + +2. The Control + + This control is included in the searchRequest and searchResultDone + messages as part of the controls field of the LDAPMessage, as defined + in Section 4.1.12 of [LDAPv3]. The structure of this control is as + follows: + + + + + + + + + +Weider, et al. Informational [Page 1] + +RFC 2696 LDAP Control Ext. for Simple Paged Results September 1999 + + +pagedResultsControl ::= SEQUENCE { + controlType 1.2.840.113556.1.4.319, + criticality BOOLEAN DEFAULT FALSE, + controlValue searchControlValue +} + +The searchControlValue is an OCTET STRING wrapping the BER-encoded +version of the following SEQUENCE: + +realSearchControlValue ::= SEQUENCE { + size INTEGER (0..maxInt), + -- requested page size from client + -- result set size estimate from server + cookie OCTET STRING +} + +3. Client-Server Interaction + + An LDAP client application that needs to control the rate at which + results are returned MAY specify on the searchRequest a + pagedResultsControl with size set to the desired page size and cookie + set to the zero-length string. The page size specified MAY be greater + than zero and less than the sizeLimit value specified in the + searchRequest. + + If the page size is greater than or equal to the sizeLimit value, the + server should ignore the control as the request can be satisfied in a + single page. If the server does not support this control, the server + MUST return an error of unsupportedCriticalExtension if the client + requested it as critical, otherwise the server SHOULD ignore the + control. The remainder of this section assumes the server does not + ignore the client's pagedResultsControl. + + Each time the server returns a set of results to the client when + processing a search request containing the pagedResultsControl, the + server includes the pagedResultsControl control in the + searchResultDone message. In the control returned to the client, the + size MAY be set to the server's estimate of the total number of + entries in the entire result set. Servers that cannot provide such an + estimate MAY set this size to zero (0). The cookie MUST be set to an + empty value if there are no more entries to return (i.e., the page of + search results returned was the last), or, if there are more entries + to return, to an octet string of the server's choosing,used to resume + the search. + + The client MUST consider the cookie to be an opaque structure and + make no assumptions about its internal organization or value. When + the client wants to retrieve more entries for the result set, it MUST + + + +Weider, et al. Informational [Page 2] + +RFC 2696 LDAP Control Ext. for Simple Paged Results September 1999 + + + send to the server a searchRequest with all values identical to the + initial request with the exception of the messageID, the cookie, and + optionally a modified pageSize. The cookie MUST be the octet string + on the last searchResultDone response returned by the server. + Returning cookies from previous searchResultDone responses besides + the last one is undefined, as the server implementation may restrict + cookies from being reused. + + The server will then return the next set of results from the whole + result set. This interaction will continue until the client has + retrieved all the results, in which case the cookie in the + searchResultDone field will be empty, or until the client abandons + the search sequence as described below. Once the paged search + sequence has been completed, the cookie is no longer valid and MUST + NOT be used. + + A sequence of paged search requests is abandoned by the client + sending a search request containing a pagedResultsControl with the + size set to zero (0) and the cookie set to the last cookie returned + by the server. A client MAY use the LDAP Abandon operation to + abandon one paged search request in progress, but this is discouraged + as it MAY invalidate the client's cookie. + + If, for any reason, the server cannot resume a paged search operation + for a client, then it SHOULD return the appropriate error in a + searchResultDone entry. If this occurs, both client and server should + assume the paged result set is closed and no longer resumable. + + A client may have any number of outstanding search requests pending, + any of which may have used the pagedResultsControl. A server + implementation which requires a limit on the number of outstanding + paged search requests from a given client MAY either return + unwillingToPerform when the client attempts to create a new paged + search request, or age out an older result set. If the server + implementation ages out an older paged search request, it SHOULD + return "unwilling to perform" if the client attempts to resume the + paged search that was aged out. + + A client may safely assume that all entries that satisfy a given + search query are returned once and only once during the set of paged + search requests/responses necessary to enumerate the entire result + set, unless the result set for that query has changed since the + searchRequest starting the request/response sequence was processed. + In that case, the client may receive a given entry multiple times + and/or may not receive all entries matching the given search + criteria. + + + + + +Weider, et al. Informational [Page 3] + +RFC 2696 LDAP Control Ext. for Simple Paged Results September 1999 + + +4. Example + + The following example illustrates the client-server interaction + between a client doing a search requesting a page size limit of 3. + The entire result set returned by the server contains 5 entries. + + Lines beginning with "C:" indicate requests sent from client to + server. Lines beginning with "S:" indicate responses sent from server + to client. Lines beginning with "--" are comments to help explain the + example. + + -- Client sends a search request asking for paged results + -- with a page size of 3. + C: SearchRequest + pagedResultsControl(3,"") + -- Server responds with three entries plus an indication + -- of 5 total entries in the search result and an opaque + -- cooking to be used by the client when retrieving subsequent + -- pages. + S: SearchResultEntry + S: SearchResultEntry + S: SearchResultEntry + S: SearchResultDone + pagedResultsControl(5, "opaque") + -- Client sends an identical search request (except for + -- message id), returning the opaque cooking, asking for + -- the next page. + C: SearchRequest + PagedResultsControl(3, "opaque") + -- Server responds with two entries plus an indication + -- that there are no more entries (null cookie). + S: SearchResultEntry + S: SearchResultEntry + S: SearchResultDone + pagedResultsControl(5,"") + +5. Relationship to X.500 + + For LDAP servers providing a front end to X.500 (93) directories, the + paged results control defined in this document may be mapped directly + onto the X.500 (93) PagedResultsRequest defined in X.511 [x500]. The + size parameter may be mapped onto pageSize. The cookie parameter may + be mapped onto queryReference. The sortKeys and reverse fields in + the X.500 PagedResultsRequest are excluded. + + + + + + + + + + + +Weider, et al. Informational [Page 4] + +RFC 2696 LDAP Control Ext. for Simple Paged Results September 1999 + + +6. Security Considerations + + Server implementors should consider the resources used when clients + send searches with the simple paged control, to ensure that a + client's misuse of this control does not lock out other legitimate + operations. + + Servers implementations may enforce an overriding sizelimit, to + prevent the retrieval of large portions of a publically-accessible + directory. + + Clients can, using this control, determine how many entries match a + particular filter, before the entries are returned to the client. + This may require special processing in servers which perform access + control checks on entries to determine whether the existence of the + entry can be disclosed to the client. + +7. References + + [LDAPv3] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory + Access Protocol (v3)", RFC 2251, December 1997. + + [Bradner97] Bradner, S., "Key Words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + + + + + + + + + + + + + + + + + + + + + + + + + + +Weider, et al. Informational [Page 5] + +RFC 2696 LDAP Control Ext. for Simple Paged Results September 1999 + + +8. Authors' Addresses + + Chris Weider + Microsoft Corp. + 1 Microsoft Way + Redmond, WA 98052 + USA + + Phone: +1 425 882-8080 + EMail: cweider@microsoft.com + + + Andy Herron + Microsoft Corp. + 1 Microsoft Way + Redmond, WA 98052 + USA + + Phone: +1 425 882-8080 + EMail: andyhe@microsoft.com + + + Anoop Anantha + Microsoft Corp. + 1 Microsoft Way + Redmond, WA 98052 + USA + + Phone: +1 425 882-8080 + EMail: anoopa@microsoft.com + + + Tim Howes + Netscape Communications Corp. + 501 E. Middlefield Road + Mountain View, CA 94043 + USA + + Phone: +1 415 937-2600 + EMail: howes@netscape.com + + + + + + + + + + + +Weider, et al. Informational [Page 6] + +RFC 2696 LDAP Control Ext. for Simple Paged Results September 1999 + + +9. Full Copyright Statement + + Copyright (C) The Internet Society (1999). All Rights Reserved. + + This document and translations of it may be copied and furnished to + others, and derivative works that comment on or otherwise explain it + or assist in its implementation may be prepared, copied, published + and distributed, in whole or in part, without restriction of any + kind, provided that the above copyright notice and this paragraph are + included on all such copies and derivative works. However, this + document itself may not be modified in any way, such as by removing + the copyright notice or references to the Internet Society or other + Internet organizations, except as needed for the purpose of + developing Internet standards in which case the procedures for + copyrights defined in the Internet Standards process must be + followed, or as required to translate it into languages other than + English. + + The limited permissions granted above are perpetual and will not be + revoked by the Internet Society or its successors or assigns. + + This document and the information contained herein is provided on an + "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING + TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING + BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION + HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF + MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + + + + + + + + + + + + + +Weider, et al. Informational [Page 7] + diff --git a/doc/rfc/rfc2713.txt b/doc/rfc/rfc2713.txt new file mode 100644 index 0000000000..ca88d30390 --- /dev/null +++ b/doc/rfc/rfc2713.txt @@ -0,0 +1,1179 @@ + + + + + + +Network Working Group V. Ryan +Request for Comments: 2713 S. Seligman +Category: Informational R. Lee + Sun Microsystems, Inc. + October 1999 + + + Schema for Representing Java(tm) Objects in an LDAP Directory + +Status of this Memo + + This memo provides information for the Internet community. It does + not specify an Internet standard of any kind. Distribution of this + memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (1999). All Rights Reserved. + +Abstract + + This document defines the schema for representing Java(tm) objects in + an LDAP directory [LDAPv3]. It defines schema elements to represent + a Java serialized object [Serial], a Java marshalled object [RMI], a + Java remote object [RMI], and a JNDI reference [JNDI]. + +1. Introduction + + This document assumes that the reader has a general knowledge 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 + 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. The directory provides a centrally + administered, and possibly replicated, service for use by Java + applications distributed across the network. + + + +Ryan, et al. Informational [Page 1] + +RFC 2713 Schema for Java Objects October 1999 + + + For example, an application server might use the directory for + "registering" objects representing the services that it manages, so + that a client can later search the directory to locate those services + as it needs. + + The motivation for this document is to define 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 schema elements to represent three types of + Java objects: a Java serialized object, a Java marshalled object, + and a JNDI reference. A Java remote object is stored as either a Java + marshalled object or a JNDI reference. + +2.1 Common Representations + + A Java object is stored in the LDAP directory by using the object + class javaObject. This is the base class from which other Java object + related classes derive: javaSerializedObject, javaMarshalledObject, + and javaNamingReference. javaObject is an abstract object class, + which means that a javaObject cannot exist by itself in the + directory; only auxiliary or structural subclasses of it can exist in + the directory. + + The object class javaContainer represents a directory entry dedicated + to storing a Java object. It is a structural object class. In cases + where a subclass of javaObject is mixed in with another structural + object class, javaContainer is not required. + + The definitions for the object classes javaObject and javaContainer + are presented in Section 4. + + The javaObject class has one mandatory attribute (javaClassName) and + four optional attributes (javaClassNames, javaCodebase, javaDoc, + description). javaClassName is a single valued attribute that is + used to store the fully qualified name of the object's Java class + (for example, "java.lang.String"). This may be the object's most + derived class's name, but does not have to be; that of a superclass + or interface in some cases might be most appropriate. This attribute + is intended for storing the name of the object's "distinguished" + class, that is, the class or interface with which the object should + be identified. + + + + + +Ryan, et al. Informational [Page 2] + +RFC 2713 Schema for Java Objects October 1999 + + + javaClassNames is a multivalued attribute that is used to store the + fully qualified names of the object's Java classes and interfaces + (for example, "java.lang.Byte"). Like all multivalued attributes, the + javaClassNames attribute's values are unordered and so no one value + is more "distinguished" than the others. This attribute is intended + for storing an object's class and interface names and those of its + ancestor classes and interfaces, although the list of values does not + have to be complete. If the javaClassNames attribute is present, it + should include the value of javaClassName. + + For example, suppose an object is stored in the directory with a + javaClassName attribute of "java.io.FilePermission", and a + javaClassNames attribute of {"java.security.Permission", + "java.io.FilePermission", "java.security.Guard", + "java.io.Serializable"}. An application searching a directory for + Java objects might use javaClassName to produce a summary of the + names and types of Java objects in that directory. Another + application might use the javaClassNames attribute to find, for + example, all java.security.Permission objects. + + javaCodebase is a multivalued attribute that is used to store the + location(s) of the object's class definition. javaDoc is used to + store a pointer (URL) to the Java documentation for the class. + description is used to store a textual description of a Java object + and is defined in [v3Schema]. The definitions of these attributes are + presented in Section 3. + +2.2 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 converted back into + a copy of the object. A Java object is "serializable" if its class + or any of its superclasses implements either the java.io.Serializable + interface or its subinterface java.io.Externalizable. + "Deserialization" is the process of converting the serialized form of + an object back into a copy of the object. When an object is + serialized, the entire tree of objects rooted at the object is also + serialized. When it is deserialized, the tree is reconstructed. For + example, suppose a serializable Book object contains (a serializable + field of) an array of Page objects. When a Book object is + serialized, so is the array of Page objects. + + The Java platform specifies a default algorithm by which serializable + objects are serialized. A Java class can also override this default + serialization with its own algorithm. [Serial] describes object + serialization in detail. + + + + + +Ryan, et al. Informational [Page 3] + +RFC 2713 Schema for Java Objects October 1999 + + + 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 + mechanism to use for locating and loading the associated class + definitions. For example, the Java application might include in its + classpath a JAR file containing the class definitions of the + serialized object, or load the class definitions using information + from the directory, as explained below. + +2.2.1 Representation in the Directory + + A serialized object is represented in the directory by the attributes + javaClassName, javaClassNames, javaCodebase, and javaSerializedData, + as defined in Section 3. The mandatory attribute, + javaSerializedData, contains the serialized form of the object. + Although the serialized form already contains the class name, the + mandatory javaClassName attribute also records the class name of the + serialized object so that applications can determined class + information without having to first deserialize the object. The + optional javaClassNames attribute is used to record additional class + information about the serialized object. The optional javaCodebase + attribute is used to record the locations of the class definitions + needed to deserialize the serialized object. + + A directory entry that contains a serialized object is represented by + the object class javaSerializedObject, which is a subclass of + javaObject. javaSerializedObject is an auxiliary object class, which + means that it needs to be mixed in with a structural object class. + javaSerializedObject's definition is given in Section 4. + +2.3 Marshalled Objects + + To "marshal" an object means to record its state and codebase(s) in + such a way that when the marshalled object is "unmarshalled," a copy + of the original object is obtained, possibly by automatically loading + the class definitions of the object. You can marshal any object that + is serializable or remote (that is, implements the java.rmi.Remote + interface). Marshalling is like serialization, except marshalling + also records codebases. Marshalling is different from serialization + in that marshalling treats remote objects specially. If an object is + a java.rmi.Remote object, marshalling records the remote object's + "stub" (see Section 2.5), instead of the remote object itself. Like + serialization, when an object is marshalled, the entire tree of + objects rooted at the object is marshalled. When it is unmarshalled, + the tree is reconstructed. + + + + + +Ryan, et al. Informational [Page 4] + +RFC 2713 Schema for Java Objects October 1999 + + + A "marshalled" object is the represented by the + java.rmi.MarshalledObject class. Here's an example of how to create + MarshalledObjects for serializable and remote objects: + + java.io.Serializable sobj = ...; + java.rmi.MarshalledObject mobj1 = + new java.rmi.MarshalledObject(sobj); + + java.rmi.Remote robj = ...; + java.rmi.MarshalledObject mobj2 = + new java.rmi.MarshalledObject(robj); + + Then, to retrieve the original objects from the MarshalledObjects, do + as follows: + + java.io.Serializable sobj = (java.io.Serializable) mobj1.get(); + java.io.Remote rstub = (java.io.Remote) mobj2.get(); + + MarshalledObject is available only on the Java 2 Platform, Standard + Edition, v1.2, and higher releases. + +2.3.1 Representation in the Directory + + A marshalled object is represented in the directory by the attributes + javaClassName, javaClassNames, and javaSerializedData, as defined in + Section 3. The mandatory attribute, javaSerializedData, contains the + serialized form of the marshalled object (that is, the serialized + form of a MarshalledObject instance). The mandatory javaClassName + attribute records the distinguished class name of the object before + it has been marshalled. The optional javaClassNames attribute is + used to record additional class information about the object before + it has been marshalled. + + A directory entry that contains a marshalled object is represented by + the object class javaMarshalledObject, which is a subclass of + javaObject. javaMarshalledObject is an auxiliary object class, which + means that it needs to be mixed in with a structural object class. + javaMarshalledObject's definition is given in Section 4. + + As evident in this description, a javaMarshalledObject differs from a + javaSerializedObject only in the interpretation of the javaClassName + and javaClassNames attributes. + + + + + + + + + +Ryan, et al. Informational [Page 5] + +RFC 2713 Schema for Java Objects October 1999 + + +2.4 JNDI References + + Java Naming and Directory Interface(tm) (JNDI) is a directory access + API specified in the Java programming language [JNDI]. 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.4.1 Contents of a Reference + + A JNDI reference is a Java object of class javax.naming.Reference. + It consists of class information about the object being referenced + and an ordered list of addresses. 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 + mechanism. + + A reference also contains information to assist in the creation of 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.4.2 Representation in the Directory + + A JNDI reference is stored in the directory by using the attributes + javaClassName, javaClassNames, javaCodebase, javaReferenceAddress, + and javaFactory, defined in Section 3. These attributes store + information corresponding to the contents of a reference described + above. javaReferenceAddress is a multivalued optional attribute for + storing reference addresses. javaFactory is the optional attribute + for storing the object factory's fully qualified class name. The + mandatory javaClassName attribute is used to store the name of the + distinguished class of the object. The optional javaClassNames + + + +Ryan, et al. Informational [Page 6] + +RFC 2713 Schema for Java Objects October 1999 + + + attribute is used to record additional class and interface names. + The optional javaCodebase attribute is used to store the locations of + the object factory's and the object's class definitions. + + A directory entry containing a JNDI reference is represented by the + object class javaNamingReference, which is a subclass of javaObject. + javaNamingReference is an auxiliary object class, which means that it + needs to be mixed in with a structural object class. + javaNamingReference's definition is given in Section 4. + +2.5 Remote Objects + + The Java Remote Method Invocation (RMI) system [RMI] is a mechanism + that enables an object on one Java virtual machine to invoke methods + on an object in another Java virtual machine. Any object whose + methods can be invoked in this way must implement the java.rmi.Remote + interface. When such an object is invoked, its arguments are + marshalled and sent from the local virtual machine to the remote one, + where the arguments are unmarshalled and used. When the method + terminates, the results are marshalled from the remote machine and + sent to the caller's virtual machine. + + To make a remote object accessible to other virtual machines, a + program typically registers it with the RMI registry. The program + supplies to the RMI registry the string name of the remote object and + the remote object itself. When a program wants to access a remote + object, it supplies the object's string name to the RMI registry on + the same machine as the remote object. The RMI registry returns to + the caller a reference (called "stub") to the remote object. When + the program receives the stub for the remote object, it can invoke + methods on the remote object (through the stub). A program can also + obtain references to remote objects as a result of remote calls to + other remote objects or from other naming services. For example, the + program can look up a reference to a remote object from an LDAP + server that supports the schema defined in this document. + + The string name accepted by the RMI registry has the syntax + "rmi://hostname:port/remoteObjectName", where "hostname" and "port" + identify the machine and port on which the RMI registry is running, + respectively, and "remoteObjectName" is the string name of the remote + object. "hostname", "port", and the prefix, "rmi:", are optional. If + "hostname" is not specified, it defaults to the local host. If + "port" is not specified, it defaults to 1099. If "remoteObjectName" + is not specified, then the object being named is the RMI registry + itself. See [RMI] for details. + + + + + + +Ryan, et al. Informational [Page 7] + +RFC 2713 Schema for Java Objects October 1999 + + + RMI can be supported using different protocols: the Java Remote + Method Protocol (JRMP) and the Internet Inter-ORB Protocol (IIOP). + The JRMP is a specialized protocol designed for RMI; the IIOP is the + standard protocol for communication between CORBA objects [CORBA]. + RMI over IIOP allows Java remote objects to communicate with CORBA + objects which might be written in a non-Java programming language + [RMI-IIOP]. + +2.5.1 Representation in the Directory + + Remote objects that use the IIOP are represented in the directory as + CORBA object references [CORBA-LDAP]. Remote objects that use the + JRMP are represented in the directory in one of two ways: as a + marshalled object, or as a JNDI reference. + + A marshalled object records the codebases of the remote object's stub + and any serializable or remote objects that it references, and + replaces remote objects with their stubs. To store a Remote object + as a marshalled object (java.rmi.MarshalledObject), you first create + a java.rmi.MarshalledObject instance for it. + + java.rmi.Remote robj = ...; + java.rmi.MarshalledObject mobj = + new java.rmi.MarshalledObject(robj); + + You can then store the MarshalledObject instance as a + javaMarshalledObject. The javaClassName attribute should contain the + fully qualified name of the distinguished class of the remote object. + The javaClassNames attribute should contain the names of the classes + and interfaces of the remote object. To read the remote object back + from the directory, first deserialize the contents of the + javaSerializedData to get a MarshalledObject (mobj), then retrieve it + from the MarshalledObject as follows: + + java.rmi.Remote robj = (java.rmi.Remote)mobj.get(); + + This returns the remote stub, which you can then use to invoke remote + methods. + + MarshalledObject is available only on the Java 2 Platform, Standard + Edition, v1.2 and higher releases. Therefore, a remote object stored + as a MarshalledObject can only be read by clients using the the Java + 2 Platform, Standard Edition, v1.2 or higher releases. + + + + + + + + +Ryan, et al. Informational [Page 8] + +RFC 2713 Schema for Java Objects October 1999 + + + To store a remote object as a JNDI reference, you first create a + javax.naming.Reference object instance for it using the remote + object's string name as it has been, or will be, recorded with the + RMI registry, with the additional restriction that the "rmi:" prefix + must be present. Here's an example: + + javax.naming.Reference ref = new javax.naming.Reference( + obj.getClass().getName(), + new javax.naming.StringRefAddr("URL", + "rmi://rserver/AppRemoteObjectX")); + + You then store the javax.naming.Reference instance as a + javaNamingReference. The advantage of using a JNDI reference is that + this can be done without a reference to the remote object. In fact, + the remote object does not have to exist at the time that this + recording in the directory is made. The remote object needs to exist + and be bound with the RMI registry when the object is looked up from + the directory. + +2.6 Serialized Objects Vs. Marshalled Objects Vs. References + + The object classes defined in this document store different aspects + of the Java objects. + + A javaSerializedObject or a serializable object stored as a + javaMarshalledObject represents the object itself, while a + javaNamingReference or a remote object stored as a + javaMarshalledObject represents a "pointer" to the object. + + When storing a serializable object in the directory, you have a + choice of storing it as a javaSerializedObject or a + javaMarshalledObject. The javaSerializedObject object class provides + the basic way in which to store serializable objects. When you create + an LDAP entry using the javaSerializableObject object class, you must + explicitly set the javaCodebase attribute if you want readers of that + entry to know where to load the class definitions of the object. When + you create an LDAP entry using the javaMarshalledObject object class, + you use the MarshalledObject class. The MarshalledObject class uses + the RMI infrastructure available on the Java platform to automate how + codebase information is gathered and recorded, thus freeing you from + having to set the javaCodebase attribute. On the other hand, the + javaCodebase attribute is human-readable and can be updated easily by + using text-based tools without having to change other parts of the + entry. This allows you, for instance, to move the class definitions + to another location and then update the javaCodebase attribute to + reflect the move without having to update the serialized object + itself. + + + + +Ryan, et al. Informational [Page 9] + +RFC 2713 Schema for Java Objects October 1999 + + + A javaNamingReference provides a way of recording address information + about an object which itself is not directly stored in the directory. + A remote object stored as a javaMarshalledObject also records address + information (the object's "stub") of an object which itself is not + directory stored in the directory. In other words, you can think of + these as compact representations of the information required to + access the object. + + A javaNamingReference 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 and + marshalled objects are not intended to be read or manipulated + directly by humans. + +3 Attribute Type Definitions + + The following attribute types are defined in this document: + + javaClassName + javaClassNames + javaCodebase + javaSerializedData + javaFactory + javaReferenceAddress + javaDoc + +3.1 javaClassName + + This attribute stores the fully qualified name of the Java object's + "distinguished" class or interface (for example, "java.lang.String"). + It is a single-valued attribute. This attribute's syntax is ' + Directory String' and its case is significant. + + ( 1.3.6.1.4.1.42.2.27.4.1.6 + NAME 'javaClassName' + DESC 'Fully qualified name of distinguished Java class or + interface' + EQUALITY caseExactMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 + SINGLE-VALUE + ) + + + + + + + + + +Ryan, et al. Informational [Page 10] + +RFC 2713 Schema for Java Objects October 1999 + + +3.2 javaCodebase + + This attribute stores the Java class definition's locations. It + specifies the locations from which to load the class definition for + the class specified by the javaClassName attribute. Each value of + the attribute contains an ordered list of URLs, separated by spaces. + For example, a value of "url1 url2 url3" means that the three + (possibly interdependent) URLs (url1, url2, and url3) form the + codebase for loading in the Java class definition. + + If the javaCodebase attribute contains more than one value, each + value is an independent codebase. That is, there is no relationship + between the URLs in one value and those in another; each value can be + viewed as an alternate source for loading the Java class definition. + See [Java] for information regarding class loading. + + This attribute's syntax is 'IA5 String' and its case is significant. + + ( 1.3.6.1.4.1.42.2.27.4.1.7 + NAME 'javaCodebase' + DESC 'URL(s) specifying the location of class definition' + EQUALITY caseExactIA5Match + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 + ) + +3.3 javaClassNames + + This attribute stores the Java object's fully qualified class or + interface names (for example, "java.lang.String"). It is a + multivalued attribute. When more than one value is present, each is + the name of a class or interface, or ancestor class or interface, of + this object. + + This attribute's syntax is 'Directory String' and its case is + significant. + + ( 1.3.6.1.4.1.42.2.27.4.1.13 + NAME 'javaClassNames' + DESC 'Fully qualified Java class or interface name' + EQUALITY caseExactMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 + ) + + + + + + + + + +Ryan, et al. Informational [Page 11] + +RFC 2713 Schema for Java Objects October 1999 + + +3.4 javaSerializedData + + This attribute stores the serialized form of a Java object. The + serialized form is described in [Serial]. + + This attribute's syntax is 'Octet String'. + + ( 1.3.6.1.4.1.42.2.27.4.1.8 + NAME 'javaSerializedData + DESC 'Serialized form of a Java object' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.40 + SINGLE-VALUE + ) + +3.5 javaFactory + + This attribute stores the fully qualified class name of the object + factory (for example, "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' and its case is + significant. + + ( 1.3.6.1.4.1.42.2.27.4.1.10 + NAME 'javaFactory' + DESC 'Fully qualified Java class name of a JNDI object factory' + EQUALITY caseExactMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 + SINGLE-VALUE + ) + +3.6 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 + 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: + + + + + + +Ryan, et al. Informational [Page 12] + +RFC 2713 Schema for Java Objects October 1999 + + + 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' and its case is + significant. It can contain multiple values. + + ( 1.3.6.1.4.1.42.2.27.4.1.11 + NAME 'javaReferenceAddress' + DESC 'Addresses associated with a JNDI Reference' + EQUALITY caseExactMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 + ) + +3.7 javaDoc + + This attribute stores a pointer to the Java documentation for the + class. It's value is a URL. For example, the following URL points to + the specification of the java.lang.String class: + http://java.sun.com/products/jdk/1.2/docs/api/java/lang/String.html + + This attribute's syntax is 'IA5 String' and its case is significant. + + ( 1.3.6.1.4.1.42.2.27.4.1.12 + NAME 'javaDoc' + DESC 'The Java documentation for the class' + EQUALITY caseExactIA5Match + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 + ) + + + + +Ryan, et al. Informational [Page 13] + +RFC 2713 Schema for Java Objects October 1999 + + +4 Object Class Definitions + + The following object classes are defined in this document: + + javaContainer + javaObject + javaSerializedObject + javaMarshalledObject + 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 abstract object class represents a Java object. A javaObject + cannot exist in the directory; only auxiliary or structural + subclasses of it can exist in the directory. + + ( 1.3.6.1.4.1.42.2.27.4.2.4 + NAME 'javaObject' + DESC 'Java object representation' + SUP top + ABSTRACT + MUST ( javaClassName ) + MAY ( javaClassNames $ + javaCodebase $ + javaDoc $ + description ) + ) + + + + + + + + + + + +Ryan, et al. Informational [Page 14] + +RFC 2713 Schema for Java Objects October 1999 + + +4.3 javaSerializedObject + + This auxiliary object class represents a Java serialized object. It + must be mixed in with a structural object class. + + ( 1.3.6.1.4.1.42.2.27.4.2.5 + NAME 'javaSerializedObject' + DESC 'Java serialized object' + SUP javaObject + AUXILIARY + MUST ( javaSerializedData ) + ) + +4.4 javaMarshalledObject + + This auxiliary object class represents a Java marshalled object. It + must be mixed in with a structural object class. + + ( 1.3.6.1.4.1.42.2.27.4.2.8 + NAME 'javaMarshalledObject' + DESC 'Java marshalled object' + SUP javaObject + AUXILIARY + MUST ( javaSerializedData ) + ) + +4.5 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.7 + NAME 'javaNamingReference' + DESC 'JNDI reference' + SUP javaObject + AUXILIARY + MAY ( javaReferenceAddress $ + javaFactory ) + ) + + + + + + + + + + + + +Ryan, et al. Informational [Page 15] + +RFC 2713 Schema for Java Objects October 1999 + + +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 issues relating to serialization in general, + see [Serial]. + +6. Acknowledgements + + We would like to thank Joseph Fialli, Peter Jones, Roger Riggs, Bob + Scheifler, and Ann Wollrath of Sun Microsystems for their comments + and suggestions. + +7. References + + [CORBA] The Object Management Group, "Common Object Request + Broker Architecture Specification 2.0," + http://www.omg.org + + [CORBA-LDAP] Ryan, V., Lee, R. and S. Seligman, "Schema for + Representing CORBA Object References in an LDAP + Directory", RFC 2714, October 1999. + + [Java] Ken Arnold and James Gosling, "The Java(tm) Programming + Language," Second Edition, ISBN 0-201-31006-6. + + [JNDI] Java Software, Sun Microsystems, Inc., "The Java(tm) + Naming and Directory Interface (tm) Specification," + February 1998. http://java.sun.com/products/jndi/ + + [LDAPv3] Wahl, M., Howes, T. and S. Kille, "Lightweight + Directory Access Protocol (v3)", RFC 2251, December + 1997. + + [RMI] Java Software, Sun Microsystems, Inc., "Remote Method + Invocation," November 1998. + http://java.sun.com/products/jdk/1.2/docs/guide/rmi + + + + + + + + +Ryan, et al. Informational [Page 16] + +RFC 2713 Schema for Java Objects October 1999 + + + [RMI-IIOP] IBM and Java Software, Sun Microsystems, Inc., "RMI over + IIOP", June 1999. + http://java.sun.com/products/rmi-iiop/ + + [Serial] Java Software, Sun Microsystems, Inc., "Object + Serialization Specification," November 1998. + http://java.sun.com/products/jdk/1.2/docs/guide/ + serialization + + [v3Schema] Wahl, M., "A Summary of the X.500(96) User Schema for + use with LDAPv3", RFC 2256, December 1997. + +8. Authors' Addresses + + Vincent Ryan + Sun Microsystems, Inc. + Mail Stop EDUB03 + 901 San Antonio Road + Palo Alto, CA 94303 + USA + + Phone: +353 1 819 9151 + EMail: vincent.ryan@ireland.sun.com + + + Scott Seligman + Sun Microsystems, Inc. + Mail Stop UCUP02-209 + 901 San Antonio Road + Palo Alto, CA 94303 + USA + + Phone: +1 408 863 3222 + EMail: scott.seligman@eng.sun.com + + + Rosanna Lee + Sun Microsystems, Inc. + Mail Stop UCUP02-206 + 901 San Antonio Road + Palo Alto, CA 94303 + USA + + Phone: +1 408 863 3221 + EMail: rosanna.lee@eng.sun.com + + + + + + +Ryan, et al. Informational [Page 17] + +RFC 2713 Schema for Java Objects October 1999 + + +Appendix - LDAP Schema + + -- Attribute types -- + + ( 1.3.6.1.4.1.42.2.27.4.1.6 + NAME 'javaClassName' + DESC 'Fully qualified name of distinguished Java class or interface' + EQUALITY caseExactMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 + SINGLE-VALUE + ) + + ( 1.3.6.1.4.1.42.2.27.4.1.7 + NAME 'javaCodebase' + DESC 'URL(s) specifying the location of class definition' + EQUALITY caseExactIA5Match + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 + ) + + ( 1.3.6.1.4.1.42.2.27.4.1.8 + NAME 'javaSerializedData' + DESC 'Serialized form of a Java object' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.40 + SINGLE-VALUE + ) + + ( 1.3.6.1.4.1.42.2.27.4.1.10 + NAME 'javaFactory' + DESC 'Fully qualified Java class name of a JNDI object factory' + EQUALITY caseExactMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 + SINGLE-VALUE + ) + + ( 1.3.6.1.4.1.42.2.27.4.1.11 + NAME 'javaReferenceAddress' + DESC 'Addresses associated with a JNDI Reference' + EQUALITY caseExactMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 + ) + + ( 1.3.6.1.4.1.42.2.27.4.1.12 + NAME 'javaDoc' + DESC 'The Java documentation for the class' + EQUALITY caseExactIA5Match + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 + ) + + + + +Ryan, et al. Informational [Page 18] + +RFC 2713 Schema for Java Objects October 1999 + + + ( 1.3.6.1.4.1.42.2.27.4.1.13 + NAME 'javaClassNames' + DESC 'Fully qualified Java class or interface name' + EQUALITY caseExactMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 + ) + + -- from RFC-2256 -- + + ( 2.5.4.13 + NAME 'description' + EQUALITY caseIgnoreMatch + SUBSTR caseIgnoreSubstringsMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{1024} + ) + + -- Object classes -- + + ( 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 ) + ) + + ( 1.3.6.1.4.1.42.2.27.4.2.4 + NAME 'javaObject' + DESC 'Java object representation' + SUP top + ABSTRACT + MUST ( javaClassName ) + MAY ( javaClassNames $ javaCodebase $ javaDoc $ description ) + ) + + ( 1.3.6.1.4.1.42.2.27.4.2.5 + NAME 'javaSerializedObject' + DESC 'Java serialized object' + SUP javaObject + AUXILIARY + MUST ( javaSerializedData ) + ) + + + + + + + + + +Ryan, et al. Informational [Page 19] + +RFC 2713 Schema for Java Objects October 1999 + + + ( 1.3.6.1.4.1.42.2.27.4.2.7 + NAME 'javaNamingReference' + DESC 'JNDI reference' + SUP javaObject + AUXILIARY + MAY ( javaReferenceAddress $ javaFactory ) + ) + + ( 1.3.6.1.4.1.42.2.27.4.2.8 + NAME 'javaMarshalledObject' + DESC 'Java marshalled object' + SUP javaObject + AUXILIARY + MUST ( javaSerializedData ) + ) + + -- Matching rule from ISO X.520 -- + + ( 2.5.13.5 + NAME 'caseExactMatch' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 + ) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Ryan, et al. Informational [Page 20] + +RFC 2713 Schema for Java Objects October 1999 + + +Full Copyright Statement + + Copyright (C) The Internet Society (1999). All Rights Reserved. + + This document and translations of it may be copied and furnished to + others, and derivative works that comment on or otherwise explain it + or assist in its implementation may be prepared, copied, published + and distributed, in whole or in part, without restriction of any + kind, provided that the above copyright notice and this paragraph are + included on all such copies and derivative works. However, this + document itself may not be modified in any way, such as by removing + the copyright notice or references to the Internet Society or other + Internet organizations, except as needed for the purpose of + developing Internet standards in which case the procedures for + copyrights defined in the Internet Standards process must be + followed, or as required to translate it into languages other than + English. + + The limited permissions granted above are perpetual and will not be + revoked by the Internet Society or its successors or assigns. + + This document and the information contained herein is provided on an + "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING + TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING + BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION + HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF + MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + + + + + + + + + + + + + +Ryan, et al. Informational [Page 21] + diff --git a/doc/rfc/rfc2714.txt b/doc/rfc/rfc2714.txt new file mode 100644 index 0000000000..172ff30c90 --- /dev/null +++ b/doc/rfc/rfc2714.txt @@ -0,0 +1,563 @@ + + + + + + +Network Working Group V. Ryan +Request for Comments: 2714 R. Lee +Category: Informational S. Seligman + Sun Microsystems, Inc. + October 1999 + + + Schema for Representing CORBA Object References in an LDAP Directory + +Status of this Memo + + This memo provides information for the Internet community. It does + not specify an Internet standard of any kind. Distribution of this + memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (1999). All Rights Reserved. + +Abstract + + CORBA [CORBA] is the Common Object Request Broker Architecture + defined by the Object Management Group. This document defines the + schema for representing CORBA object references in an LDAP directory + [LDAPv3]. + +1. Introduction + + This document assumes that the reader has a general understanding of + CORBA. + + 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 + with a particular set of attributes. For example, you can search for + all persons in the directory with the surname "Smith". + + CORBA applications require access to CORBA objects. Traditionally, + CORBA applications have used the COS Naming service for storage and + retrieval of CORBA object references. When deployed in environments + with a directory, CORBA applications should be able to use the + directory as a repository for CORBA object references. The directory + provides a centrally administered, and possibly replicated, service + for use by CORBA applications distributed across the network. + + + + +Ryan, et al. Informational [Page 1] + +RFC 2714 Schema for CORBA Object References October 1999 + + + For example, an application server may use the directory for + "registering" CORBA objects representing the services that it + manages, so that a client can later search the directory to locate + those services as it needs. + + The motivation for this document is to define a common way for + applications to store and retrieve CORBA object references from the + directory. Using this common schema, any CORBA application that + needs to read or store CORBA object references in the directory can + do so in an interoperable way. + + Note that this schema is defined for storing CORBA "object + references," not CORBA objects in general. There might be other ways + to store CORBA objects in an LDAP directory but they are not covered + by this schema. + +2. Representation of CORBA Object References + + This document defines schema elements to represent a CORBA object + reference in LDAP directory. Applications in possession of a + reference to an object can invoke calls on that object. Such a + reference is termed an "interoperable object reference," or IOR. + Access to CORBA objects by using IORs is achieved transparently to + the application, by means of the General Inter-ORB Protocol. + + A CORBA object reference is represented in the directory by the + object class corbaObjectReference. corbaObjectReference is a subclass + of the abstract corbaObject object class. corbaObjectReference is an + auxiliary object class, which means that it needs to be mixed in with + a structural object class. + + The object class corbaContainer is used in a directory entry which + represents a CORBA object or object reference. It is a structural + object class, and when representing an object reference, the + corbaObjectReference object class would also need to be present in + the entry. corbaContainer is not required when a subclass of + corbaObject (such as corbaObjectReference) is mixed in with another + structural object class. + + The definitions for the object classes corbaObject, + corbaObjectReference, and corbaContainer are presented in Section 4. + + The corbaObject class has two optional attributes: corbaRepositoryId + and description. corbaRepositoryId is a multivalued attribute that + is used to store the repository ids of the interfaces implemented by + a CORBA object. description is used to store a textual description + of a CORBA object. + + + + +Ryan, et al. Informational [Page 2] + +RFC 2714 Schema for CORBA Object References October 1999 + + + The corbaObjectReference class has one mandatory attribute: corbaIor. + corbaIor is used to store the object's stringified IOR. + + corbaIor and corbaRepositoryId are defined in Section 3; description + is defined in [v3Schema]. + +3. Attribute Type Definitions + + The following attribute types are defined in this document: + + corbaIor + corbaRepositoryId + +3.1 corbaIor + + This attribute stores the string representation of the interoperable + object reference (IOR) for a CORBA object. An IOR is an opaque handle + for the object which contains the information necessary to locate the + object, even if the object is in another ORB. + + This attribute's syntax is 'IA5 String' and its case is + insignificant. + + ( 1.3.6.1.4.1.42.2.27.4.1.14 + NAME 'corbaIor' + DESC 'Stringified interoperable object reference of a CORBA object' + EQUALITY caseIgnoreIA5Match + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 + SINGLE-VALUE + ) + +3.2 corbaRepositoryId + + Each CORBA interface has a unique "repository id" (also called "type + id") that identifies the interface. A CORBA object has one or more + repository ids, one for each interface that it implements. + + The format of a repository id can be any string, but the OMG + specifies four standard formats: + + a. IDL-style + + IDL:Prefix/ModuleName/InterfaceName:VersionNumber + + + + + + + + +Ryan, et al. Informational [Page 3] + +RFC 2714 Schema for CORBA Object References October 1999 + + + For example, the repository id for the "NamingContext" in OMG's COS + Naming module is: "IDL:omg.org/CosNaming/NamingContext:1.0". + + b. RMI-style + + RMI:ClassName:HashCode[:SUID] + + This format is used by RMI-IIOP remote objects [RMI-IIOP]. + "ClassName" is the fully qualified name of the class (for example, + "java.lang.String"). "HashCode" is the object's hash code (that is, + that obtained by invoking the "hashCode()" method). "SUID" is the + "stream unique identifier", which is a 64-bit number that uniquely + identifies the serialization version of the class; SUID is optional + in the repository id. + + c. DCE-style + + DCE:UUID + + This format is used for DCE/CORBA interoperability [CORBA-DCE]. + "UUID" represents a DCE UUID. + + d. "local" + + This format is defined by the local Object Request Broker (ORB). + + The corbaRepositoryId attribute is a multivalued attribute; each + value records a single repository id of an interface implemented by + the CORBA object. This attribute need not contain a complete list of + the interfaces implemented by the CORBA object. + + This attribute's syntax is 'Directory String' and its case is + significant. The values of this attribute are encoded using UTF-8. + Some values may require translation from their native representation + in order to be correctly encoded using UTF-8. + + ( 1.3.6.1.4.1.42.2.27.4.1.15 + NAME 'corbaRepositoryId' + DESC 'Repository ids of interfaces implemented by a CORBA object' + EQUALITY caseExactMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 + ) + + + + + + + + + +Ryan, et al. Informational [Page 4] + +RFC 2714 Schema for CORBA Object References October 1999 + + +4. Object Class Definitions + + The following object classes are defined in this document: + + corbaContainer + corbaObject + corbaObjectReference + +4.1 corbaContainer + + This structural object class represents a container for a CORBA + object. + + ( 1.3.6.1.4.1.42.2.27.4.2.10 + NAME 'corbaContainer' + DESC 'Container for a CORBA object' + SUP top + STRUCTURAL + MUST ( cn ) + ) + +4.2 corbaObject + + This abstract object class is the root class for representing a CORBA + object. + + ( 1.3.6.1.4.1.42.2.27.4.2.9 + NAME 'corbaObject' + DESC 'CORBA object representation' + SUP top + ABSTRACT + MAY ( corbaRepositoryId $ description ) + ) + +4.3 corbaObjectReference + + This auxiliary object class represents a CORBA object reference. It + must be mixed in with a structural object class. + + ( 1.3.6.1.4.1.42.2.27.4.2.11 + NAME 'corbaObjectReference' + DESC 'CORBA interoperable object reference' + SUP corbaObject + AUXILIARY + MUST ( corbaIor ) + ) + + + + + +Ryan, et al. Informational [Page 5] + +RFC 2714 Schema for CORBA Object References October 1999 + + +5. Security Considerations + + Obtaining a reference to an object and storing it in the directory + may make a handle to the object available to a wider audience. This + may have security implications. + +6. Acknowledgements + + We would like to thank Sanjeev Krishnan of Sun Microsystems, Simon + Nash of IBM, and Jeffrey Spirn of Oracle for their comments and + suggestions. + +7. References + + [CORBA] The Object Management Group, "Common Object Request + Broker Architecture Specification 2.2", + http://www.omg.org + + [CORBA-DCE] Distributed Systems Technology Center and Digital + Equipment Corporation, "DCE/CORBA Interworking + Specification", May 1998. + http://www.omg.org/library/schedule/ + DCE_CORBA_Interworking_RFP.html + + [LDAPv3] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory + Access Protocol (v3)", RFC 2251, December 1997. + + [RMI-IIOP] IBM and Java Software, Sun Microsystems, Inc., "RMI over + IIOP", June 1999. http://java.sun.com/products/rmi- + iiop/index.html + + [v3Schema] Wahl, M., "A Summary of the X.500(96) User Schema for use + with LDAPv3", RFC 2256, December 1997. + + + + + + + + + + + + + + + + + + +Ryan, et al. Informational [Page 6] + +RFC 2714 Schema for CORBA Object References October 1999 + + +8. Authors' Addresses + + Vincent Ryan + Sun Microsystems, Inc. + Mail Stop EDUB03 + 901 San Antonio Road + Palo Alto, CA 94303 + USA + + Phone: +353 1 819 9151 + EMail: vincent.ryan@ireland.sun.com + + + Rosanna Lee + Sun Microsystems, Inc. + Mail Stop UCUP02-206 + 901 San Antonio Road + Palo Alto, CA 94303 + USA + + Phone: +1 408 863 3221 + EMail: rosanna.lee@eng.sun.com + + + Scott Seligman + Sun Microsystems, Inc. + Mail Stop UCUP02-209 + 901 San Antonio Road + Palo Alto, CA 94303 + USA + + Phone: +1 408 863 3222 + EMail: scott.seligman@eng.sun.com + + + + + + + + + + + + + + + + + + +Ryan, et al. Informational [Page 7] + +RFC 2714 Schema for CORBA Object References October 1999 + + +9. Appendix - LDAP Schema + + -- Attribute types -- + + ( 1.3.6.1.4.1.42.2.27.4.1.14 + NAME 'corbaIor' + DESC 'Stringified interoperable object reference of a CORBA object' + EQUALITY caseIgnoreIA5Match + SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 + SINGLE-VALUE + ) + + ( 1.3.6.1.4.1.42.2.27.4.1.15 + NAME 'corbaRepositoryId' + DESC 'Repository ids of interfaces implemented by a CORBA object' + EQUALITY caseExactMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 + ) + + -- from RFC-2256 -- + + ( 2.5.4.13 + NAME 'description' + EQUALITY caseIgnoreMatch + SUBSTR caseIgnoreSubstringsMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{1024} + ) + + -- Object classes -- + + ( 1.3.6.1.4.1.42.2.27.4.2.9 + NAME 'corbaObject' + DESC 'CORBA object representation' + SUP top + ABSTRACT + MAY ( corbaRepositoryId $ description ) + ) + + ( 1.3.6.1.4.1.42.2.27.4.2.10 + NAME 'corbaContainer' + DESC 'Container for a CORBA object' + SUP top + STRUCTURAL + MUST ( cn ) + ) + + + + + + +Ryan, et al. Informational [Page 8] + +RFC 2714 Schema for CORBA Object References October 1999 + + + ( 1.3.6.1.4.1.42.2.27.4.2.11 + NAME 'corbaObjectReference' + DESC 'CORBA interoperable object reference' + SUP corbaObject + AUXILIARY + MUST ( corbaIor ) + ) + + -- Matching rule from ISO X.520 -- + + ( 2.5.13.5 + NAME 'caseExactMatch' + SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 + ) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Ryan, et al. Informational [Page 9] + +RFC 2714 Schema for CORBA Object References October 1999 + + +10. Full Copyright Statement + + Copyright (C) The Internet Society (1999). All Rights Reserved. + + This document and translations of it may be copied and furnished to + others, and derivative works that comment on or otherwise explain it + or assist in its implementation may be prepared, copied, published + and distributed, in whole or in part, without restriction of any + kind, provided that the above copyright notice and this paragraph are + included on all such copies and derivative works. However, this + document itself may not be modified in any way, such as by removing + the copyright notice or references to the Internet Society or other + Internet organizations, except as needed for the purpose of + developing Internet standards in which case the procedures for + copyrights defined in the Internet Standards process must be + followed, or as required to translate it into languages other than + English. + + The limited permissions granted above are perpetual and will not be + revoked by the Internet Society or its successors or assigns. + + This document and the information contained herein is provided on an + "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING + TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING + BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION + HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF + MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + + + + + + + + + + + + + +Ryan, et al. Informational [Page 10] +