Service Location Working Group Pete St. Pierre INTERNET DRAFT Sun Microsystems 4 November 1997 Conversion of LDAP Schemas to and from SLP Templates draft-ietf-svrloc-template-conversion-01.txt Status of This Memo This document is a submission by the Service Location Working Group of the Internet Engineering Task Force (IETF). Comments should be submitted to the srvloc@corp.home.net mailing list. Distribution of this memo is unlimited. This document is an Internet-Draft. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as ``work in progress.'' To learn the current status of any Internet-Draft, please check the ``1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow Directories on ftp.is.co.za (Africa), nic.nordu.net (North Europe), ftp.nis.garr.it (South Europe), munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or ftp.isi.edu (US West Coast). Abstract LDAP and SLP are both useful mechanisms for locating service related information on a network. While they do perform similar functions, the way in which the information they provide is formated is very different. This document describes a set of rules and mappings for translating between the ASN.1 based LDAP schema and an SLP Template as described in the ''Service Template and service: Scheme'' draft.[1] St.Pierre Expires 4 May 1998 [Page i] Internet Draft Schemas and Templates 4 November 1997 Contents Status of This Memo i Abstract i 1. Motivation 2 2. ASN.1 and BER Encodings 2 3. Mapping from Templates to Schemas 3 3.1. Data Type Mappings . . . . . . . . . . . . . . . . . . . 3 3.2. Integer . . . . . . . . . . . . . . . . . . . . . . . . . 3 3.3. String . . . . . . . . . . . . . . . . . . . . . . . . . 4 3.4. Boolean . . . . . . . . . . . . . . . . . . . . . . . . . 4 3.5. Opaque . . . . . . . . . . . . . . . . . . . . . . . . . 4 3.6. Enumerations . . . . . . . . . . . . . . . . . . . . . . 4 3.7. Multi-valued Attributes . . . . . . . . . . . . . . . . . 5 3.8. Optional Attributes . . . . . . . . . . . . . . . . . . . 5 3.9. Literal Attributes . . . . . . . . . . . . . . . . . . . 5 3.10. Explicit Matching . . . . . . . . . . . . . . . . . . . . 5 3.11. Template for Translation . . . . . . . . . . . . . . . . 6 3.12. Translated Schema . . . . . . . . . . . . . . . . . . . . 7 4. Mapping from Schemas to Templates 9 4.1. Data Type Mappings . . . . . . . . . . . . . . . . . . . 9 4.2. Integer . . . . . . . . . . . . . . . . . . . . . . . . . 9 4.3. Strings . . . . . . . . . . . . . . . . . . . . . . . . . 10 4.4. Boolean . . . . . . . . . . . . . . . . . . . . . . . . . 10 4.5. Octet String . . . . . . . . . . . . . . . . . . . . . . 10 4.6. Enumeration . . . . . . . . . . . . . . . . . . . . . . . 10 4.7. Rules for Other ASN.1 Primitive Types . . . . . . . . . . 10 4.8. Set Of . . . . . . . . . . . . . . . . . . . . . . . . . 11 4.9. Real . . . . . . . . . . . . . . . . . . . . . . . . . . 11 4.10. bitstring . . . . . . . . . . . . . . . . . . . . . . . . 11 4.11. Object Identifier . . . . . . . . . . . . . . . . . . . . 12 4.12. Sequence Of . . . . . . . . . . . . . . . . . . . . . . . 12 4.13. Schema to be Translated . . . . . . . . . . . . . . . . . 13 4.14. SLP Translation . . . . . . . . . . . . . . . . . . . . . 15 5. Notes on Matching Operators 15 A. References 16 St.Pierre Expires 4 May 1998 [Page 1] Internet Draft Schemas and Templates 4 November 1997 1. Motivation SLP templates are intended to create a simple encoding of the syntactic and semantic conventions for individual service types, their attributes, and conventions. This can easily be generated, transmitted, read by humans and parsed by programs, as it is a string based syntax with required comments. On the other hand, directory schemas serve to formalize directory entry formulation for use with X.500 and LDAP. These directories serve to store information about many types of entities. Network services are one such entity. The ability to register services across both SLP and schema based directory services is a much needed capability. In order to facilitate this, mappings must be created between the SLP template grammar and the directory schemas The simple notation and syntactic/semantic attribute capabilities of SLP will map well into directory schemas. This means that service templates will easily be converted into directory schemas. The reverse is not true. Only a certain restricted set of types, matching rules and encoding conventions will be directly mappable into service type templates. There are rules to cover the cases where mapping cannot be done directly. It is believed that the cases which are not supported are the exception rather than the rule. This document will outline the correct mappings for the four basic data types supported by SLP to the ASN.1/BER encoding used by the LDAP directory schema. Likewise, rules and guidelines will be propsed to facilitate consistent mapping of ASN.1 based schemas to be translated in the SLP template grammar. 2. ASN.1 and BER Encodings ASN.1 defined schemas are assumed to be encoded using the Basic Encoding Rules(BER) defined in CCITT Recommendation X.209. The X.209 specification contains details of the on-the-wire encoding of ASN.1 values. BER supports 4 types of encodings: Universal, Application, Context Specific and Private. All SLP types will map to Universal BER encoded values. Within the scope of Universal types, there are both primitive encodings and constructed encodings. A primitive encoding is a data value encoding in which the contents octets directly represent the value. Constructed encodings are data values encoding in which the contents octets are the complete encoding of one or more other data values. [2] St.Pierre Expires 4 May 1998 [Page 2] Internet Draft Schemas and Templates 4 November 1997 This document will deal primarily with mapping ASN.1 primitive encodings to SLP data types. Discussions of bit ordering assume bit 8 is the most significant bit. 3. Mapping from Templates to Schemas 3.1. Data Type Mappings SLP supports four data types. Each of these data types can be mapped to a specific ASN.1 type. In this way, translation of data types can be described easily. All SLP data types are encoded as strings in the protocol. Complexity is added when the SLP data type is expressed as an enumeration. This section describes the translation of each data type to its corresponding ASN.1 type. A discussion of proper enumeration handling follows these mappings. SLP Type ASN.1 Type --------------------------- Integer Integer String String Boolean Boolean Opaque Octet String 3.2. Integer Both SLP templates and ASN.1 support Integers, so there is a one to one mapping between an SLP Integer attribute and an ASN.1 Integer attribute. On the wire encoding of these two is very different, though. In SLP, all integers are encoded as strings. An integer value of 17869 would be represented by a 5 byte string containing the values of the characters '1', '7', '8', '6', and '9' in the character set specified in the request or repsonse packet. The ASN.1 Integer type is encoded in BER according to the rules in section 8 of the X.209 specification. The encoding of an ASN.1 integer value is primitive. The contents octets shall consist of one or more octets. The rules ensure that an integer value is always encoded in the smallest possible number of octets. St.Pierre Expires 4 May 1998 [Page 3] Internet Draft Schemas and Templates 4 November 1997 Also, the contents octets shall be a two's complement binary number equal to the integer value, and consisting of bits 8 to 1 of the first octet, followed by bits 8 to 1 of the second octet, followed by bits 8 to 1 of each octet in turn up to and including the last octet of the contents octets. 3.3. String SLP strings are encoded as described in section 20.5 of the SLP protocol specification [3]. All value strings are considered case insensitive for matching operations. These strings are mapped to the ASN.1 DisplayString syntax. 3.4. Boolean Boolean attributes may have one of two possible values. In SLP, these values are represented as strings, TRUE and FALSE. In SLP's string encoding of a boolean value, case does not matter. ASN.1 supports a Universal, primitive type of boolean. X.209 specifies that the Contents field of a FALSE boolean value be encoded as a single octet with a value of zero. A boolean whose value is TRUE shall be encoded as a single octet whose value shall be any non-zero value, at the sender's option. 3.5. Opaque SLP values that are encoded as Opaque are really a series of octets. While SLP uses the construct of :, this maps very nicely to the tag/length1/value BER encoding of the ASN.1 Octet String. The field of the SLP encoding will not match the len field of the BER encoding, as radix-64 encoding results in a 4 to 3 expansion of the original data. Likewise, data presented in radix-64 notation must be converted back to the original byte stream to be encoded in the Contents field of the BER encoding. 3.6. Enumerations The SLP template grammar provides for the definition of enumerations. Enumerations are defined by listing all possible values for the attribute following any help text provided for that attribute. While the template syntax allows for creation of enumerations, the SLP protocol does not strictly enforce enumerations. These enumerations St.Pierre Expires 4 May 1998 [Page 4] Internet Draft Schemas and Templates 4 November 1997 are still treated as text strings within the protocol, and values outside the scope of the enumeration defined may be present. The template enumeration is intended as a guideline to client side applications as to what values may be expected. An ASN.1 enumeration commonly maps a text string to a numerical value. In the BER encoding, the numerical value is passed as an integer across the wire. The receiving side must then translate the the value to the associated string as defined in the ASN.1 description. Because of this difference, SLP values that are encoded as ASN.1 enumerations must be sure the enumeration covers all possible values. 3.7. Multi-valued Attributes Multi-valued attributes are defined in an SLP template using the 'M' flag. This flag indicates that an attribute may have more than one value. All values for a given attribute must be of the same encoding type. The ASN.1 syntax for SET OF is commonly used to define multi-valued ASN.1 objects that must be of the same type. 3.8. Optional Attributes SLP uses the 'O' flag to indicate an attribute may or may not be present. These optional attributes are defined using the "May" clause in an ASN.1 definition. All other attributes must be defined as a "Must" 3.9. Literal Attributes ASN.1 does not have a mechanism to indicate that the values of an attribute may not be translated from one language to another. 3.10. Explicit Matching The SLP template syntax uses a flag of 'X' to indicate that an attribute must match exactly with a query made by a client. There is, however, no mechanism to prevent clients from using the sub-string operator with explicit matching attributes. Common practice would be to map this to the ASN.1 matching syntax of "MATCHES EXACTLY". St.Pierre Expires 4 May 1998 [Page 5] Internet Draft Schemas and Templates 4 November 1997 3.11. Template for Translation The template included below is derived from the printer service scheme described in [4]. type = printer version = 0.0 language = en description = The printer service template describes the attributes supported by network printing devices. Devices may be either directly connected to a network, or connected to a printer spooler that understands the a network queuing protocol such as IPP, lpr or the Salutation Architecture. url-syntax = The URL syntax is specific to the printing protocol being employed description = STRING # This attribute is a free form string that can contain any # site-specific descriptive information about this printer. security-mechanisms-supported = STRING L M none # This attribute indicates the security mechanisms supported tls, ssl, http-basic, http-digest, none operator = STRING L M # A person, or persons responsible for maintaining a # printer on a day-to-day basis, including such tasks # as filling empty media trays, emptying full output # trays, replacing toner cartridges, clearing simple # paper jams, etc. location-address = STRING O # Physical/Postal address for this device. Useful for # nailing down a group of printers in a very large corporate # network. For example: 960 Main Street, San Jose, CA 95130 priority-queue = BOOLEAN O FALSE # TRUE indicates this printer or print queue is a priority # queuing device. number-up = INTEGER O 1 St.Pierre Expires 4 May 1998 [Page 6] Internet Draft Schemas and Templates 4 November 1997 # This job attribute specifies the number of source # page-images to impose upon a single side of an instance # of a selected medium. 1, 2, 4 paper-output = STRING M L O standard # This attribute describes the mode in which pages output # are arranged. standard, noncollated sort, collated sort, stack, unknown 3.12. Translated Schema This translated schema uses the template attributes primarily as comments in the beginning of the schema definition. Since all Objects must support a cannonical name (cn), we use the URL as the value for an object cn. This maps well, as a cn identifies a particular object and a URL identifies a partular resource. -- The printer service template describes the attributes -- supported by network printing devices. Devices may be either -- directly connected to a network, or connected to a printer -- spooler that understands the a network queuing protocol such as -- IPP, lpr or the Salutation Architecture. printer OBJECT-CLASS SUBCLASS OF top MUST CONTAIN { cn, description, security-mechanisms-supported } MAY CONTAIN { operator, location-address, priority-queue, number-up, paper-output } cn OBJECT-TYPE SYNTAX DisplayString DESCRIPTION "The URL of the printer being described" description OBJECT-TYPE SYNTAX DisplayString DESCRIPTION St.Pierre Expires 4 May 1998 [Page 7] Internet Draft Schemas and Templates 4 November 1997 "This attribute is a free form string that can contain Any site-specific descriptive information about this printer." security-mechanisms-supported OBJECT-TYPE SYNTAX INTEGER { tls(1) ssl(2) http-basic(3) http-digest(4) none(5) } DESCRIPTION "This attribute indicates the security mechanisms supported" operator OBJECT-TYPE SYNTAX SET OF DisplayString DESCRIPTION "A person, or persons responsible for maintaining a printer on a day-to-day basis, including such tasks as filling empty media trays, emptying full output trays, replacing toner cartridges, clearing simple paper jams, etc." location-address OBJECT-TYPE SYNTAX DisplayString DESCRIPTION "Physical/Postal address for this device. Useful for nailing down a group of printers in a very large corporate network. For example: 960 Main Street, San Jose, CA 95130" priority-queue OBJECT-TYPE SYNTAX BOOLEAN DESCRIPTION "TRUE indicates this printer or print queue is a priority queuing device." number-up OBJECT-TYPE SYNTAX INTEGER DESCRIPTION "This job attribute specifies the number of source page-images to impose upon a single side of an instance of a selected medium." paper-output OBJECT-TYPE SYNTAX INTEGER { standard(1) St.Pierre Expires 4 May 1998 [Page 8] Internet Draft Schemas and Templates 4 November 1997 noncollated sort(2) collated sort(3) stack(4) unknown(5) } DESCRIPTION "This attribute describes the mode in which pages output are arranged." 4. Mapping from Schemas to Templates ASN.1 employs a much richer set of data types than provided by SLP. The table below show the mapping of selected ASN.1 data type to their nearest SLP equivalent. Because of the complexity and flexibility of ASN.1, a complete list cannot be provided. As sample of some ASN.1 encodings and their mappings to SLP: ASN.1 type xxxx SLP type --------------------------------------- Integer Integer Strings String Boolean Boolean Octet String Opaque Enumeration String Set Of 'M' flag Real String Bit String String Object IdentifierString Sequence Of Multiple Attributes 4.1. Data Type Mappings ASN.1 supports a much larger range of values. As such, a subset will be selected to map SLP values. ASN.1 uses BER encoding as described in CCITT Recommendation X.209 [2]. BER encodings are based on tuples containing a Type, Length and Contents. 4.2. Integer Both SLP templates and ASN.1 support Integers, so there is a one to one mapping between an SLP Integer attribute and an ASN.1 Integer attribute. Details on the encoding of integers is summarized in the St.Pierre Expires 4 May 1998 [Page 9] Internet Draft Schemas and Templates 4 November 1997 SLP template to ASN.1 section above, as well as being explained in detail in RFC2165[3] and the X.209[2] specification. 4.3. Strings Strings are supported between both SLP and ASN.1. SLP encoding of the strings must conform to the rules for handling special characters, as outlined in RFC 2165 [3]. 4.4. Boolean Boolean values are supported by both SLP and ASN.1, though on the wire encodings will vary. X.209[2] specifies zero and non-zero encoding for booleans, where SLP encodes booleans using the strings TRUE and FALSE. 4.5. Octet String An ASN.1 octet string should be mapped to an Opaque in an SLP template. An octet string is a sequence of bytes, where an Opaque is a sequence of bytes that has been encoded using radix64. 4.6. Enumeration SLP templates support the concept of enumerations through the listing of values in the attribute definition. This is similar to the ASN.1 definition of enumerations, though encodings vary. In SLP enumerated values are passed between client and server as strings. BER encodes the ASN.1 enumeration by passing the number of the elements position in the enumeration. This requires both sides to have knowledge of the specific enumeration prior to decoding an enumerations value. color-supported = STRING M none # This attribute specifies whether the Printer supports # color and, if so, what type. none, highlight, three color, four color, monochromatic 4.7. Rules for Other ASN.1 Primitive Types It is reasonable to think that all ASN.1 data types can be accurately represented using the very basic data types defined in ASN.1. As such, data types that do not map directly to SLP data types should be St.Pierre Expires 4 May 1998 [Page 10] Internet Draft Schemas and Templates 4 November 1997 defined as either a String, or as Opaque. ASN.1 types that may only contain valid characters for Strings, as defined in X.209[2] should be encoded as strings. If a value may contain illegal string values, the SLP Opaque type should be used. In either case, the first line of the help text should indicate the original ASN.1 data type. 4.8. Set Of Sets can be accommodated in an SLP template by specifying the attribute is multivalued. The flag 'M' is used to indicate an attribute Can have multiple values. All values must be of the same type. As such, a multivalued attribute of type string could have values of "one, 2, three", but the value 2 would be returned as a string, not an integer. Likewise, a multivalued integer could not have a value of "1, 2, three", as all values would need to be converted to strings, which are illegal for an attribute of type integer. 4.9. Real There is no direct mapping between floating point numbers and any SLP data types. As such, attributes should be defined as type String. Comments can be added to the attribute help text indicating the value was originally an ASN.1 real. For example weight = STRING # ASN.1: Real # The objects weight in pounds. 4.10. bitstring While the wire encoding of strings and bitstrings is quite different, it is not unreasonable to represent a bitstring as a series of ones and zeros. As such, the ASN.1 bitstring is mapped to the SLP String type, where all characters in the string are either ones or zeros. mask = STRING # ASN.1: Bitstring # The mask used to convert this number. St.Pierre Expires 4 May 1998 [Page 11] Internet Draft Schemas and Templates 4 November 1997 4.11. Object Identifier Object identifiers are commonly used in the ASN.1 world to identify object and attributes. Object ID's are a numerical representation of an elements place in the naming heirarchy. Each element at the level of a heirarchy has a unique number assigned within that level of the heirarch. A sample object ID would be the naming tree for SNMP MIBs. iso(1) org(3) dod(6) internet(1) mgmt(2) mib(1) would be written as the string 1.3.6.1.2.1 Because this representation reduces down to a string of dot separated numbers, this maps easily to the SLP String type. The help text for this element should indicate it is an ASN.1 OID identifier = STRING # ASN.1: OID # The object identifier for this SNMP agent. 4.12. Sequence Of The ASN.1 construct 'Sequence Of' is probably the least intuitive to map to an SLP template. SLP attributes can only contain values of like type. By definition, this is an ASN.1 SET OF. ASN.1 sequences are made of multiple values of different types. For example, an attribute named 'Engine' may be defined as: engine OBJECT-TYPE SYNTAX SEQUENCE OF { name DisplayString, status INTEGER { unknown(1) running(2) shutdown(3) } } DESCRIPTION "Engine description." In order to map this to an SLP template, we can create multiple attributes and rely on the ordering for association. The above might translate as: St.Pierre Expires 4 May 1998 [Page 12] Internet Draft Schemas and Templates 4 November 1997 engine-name = STRING M # The name of one of this crafts engines. engine-status = STRING M unknown # The name of one of this crafts engines. unknown, running, shutdown To do this, we are relying on an assumption stated in the service: Scheme Draft [1] that all values of a multivalued attribute retain their order. When new values are added, they are added to the end of the list of values. As such, if we had: engine-name = right, left engine-status = running, shutdown We would assume that the engine named right is running and the engine named left is shutdown. 4.13. Schema to be Translated In general, ASN.1 provides a much more robust set of data types than provided for by SLP. For this reason, it is more complex to convert LDAP schemas to templates for SLP. The following schema represents an example of a schema for an exported filesystem. The section presents it as in ASN.1, while the following section shows the SLP template translation. -- abstraction of a fstab entry (a "mount") -- these lookups would likely be performed by an -- an automounter type application mount OBJECT-CLASS SUBCLASS OF top MUST CONTAIN { -- the mount host cn, -- the mount point mountDirectory. -- the mount type mountType } St.Pierre Expires 4 May 1998 [Page 13] Internet Draft Schemas and Templates 4 November 1997 MAY CONTAIN { -- mount options mountOption, -- dump frequency mountDumpFrequency, -- passno mountPassNo } cn OBJECT-TYPE SYNTAX DisplayString DESCRIPTION "The mount host" mountDirectory SYNTAX DisplayString DESCRIPTION "The filesystem to mount" mountType OBJECT-TYPE SYNTAX INTEGER { ufs(1) hsfs(2) nfs(3) rfs(4) } DESCRIPTION "The type of the filesystem being mounted" mountOption OBJECT-TYPE SYNTAX SET OF DisplayString DESCRIPTION "mount options for this filesystem" mountDumpFrequency OBJECT-TYPE SYNTAX INTEGER (0..9) DESCRIPTION "How often to dump this filesystem" mountPassNo OBJECT-TYPE SYNTAX Integer DESCRIPTION "Boot time mount pass number" St.Pierre Expires 4 May 1998 [Page 14] Internet Draft Schemas and Templates 4 November 1997 4.14. SLP Translation type = mount version = 1.0 language = en description = "This would describe a remote filesystem access protocol" url-syntax = filesystem = 1*[ DIGIT / ALPHA ] urlpath = "/" filesystem cn = STRING L # The mount host mountDirectory = STRING L # The filesystem to mount mountType = STRING L ufs # The type of the filesystem being mounted ufs, hsfs, nfs, rfs mountOption = STRING M O L # mount options for this filesystem mountDumpFrequency = INTEGER O 0 # How often to dump this filesystem 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 mountPassNo = INTEGER O # Boot time mount pass number 5. Notes on Matching Operators While the SLP template grammar does not describe the matching properties of attributes, ASN.1 does. If chosing to add matching properties to an SLP template when converting it to an ASN.1 based schema, the following rules should be kept in mind. LDAP and SLP support the same matching operations, though using slightly different matching semantics. In addition to greaterOrEqual and lessOrEqual, SLP provides for a simple less or greater match. St.Pierre Expires 4 May 1998 [Page 15] Internet Draft Schemas and Templates 4 November 1997 LDAP Search Operators SLP Search Operators and (&) & or (|) | not (!) != equalityMatch (=) == substrings greaterOrEqual (>=) >= lessOrEqual (<=) <= present (=*) ASN.1 provides for three flavors of substring value matching. These are initial, any, and final. In specifying the match capability of an attribute, ASN.1 allows specification that a value may match the leading part, any part, or the final part of a string value. Using the SLP search sematics, this is accomplished through the substring (*) operator. Searching for initial, any or final is handled through specific placement of the operator. The following example, taken from RFC2165 illustrates this: inital: "bob*" matches "bob", "bobcat", and "bob and sue" final: "*bob" matches "bob", "bigbob", and "sue and bob" any: "*bob*" matches "bob", "bobcat", "bigbob", and "a bob I know" A. References [1]E. Guttman, C. Perkins, J. Kempf "Service Templates and service: Schemes", Work in Progress, November, 1997 draft-ietf-svrloc-service-scheme-04.txt [2]CCITT Recommendation X.209, "Specification of Basic Encoding Rules for Abstract Syntax Notation One (ASN.1), 1988 [3]J. Veizades, E. Guttman, C. Perkins, and S. Kaplan. "Service Location Protocol", RFC 2165. June 1997. [4]P. St. Pierre, "Definition of printer: URLs for use with Service Location", Work in Progress, October, 1997 draft-ietf-srvloc-printer-scheme-01.txt Authors' Addresses Questions about this memo can be directed to: St.Pierre Expires 4 May 1998 [Page 16] Internet Draft Schemas and Templates 4 November 1997 Pete St. Pierre Sun Microsystems 901 San Antonio Avenue Palo Alto, CA 94303 USA Phone: +1 415 786-5790 email: Pete.StPierre@Eng.Sun.COM St.Pierre Expires 4 May 1998 [Page 17]