non-arbitrary strings, including the descriptive help text, is
directly translatable from one language to another. Non-literal
attribute definitions, attribute identifiers, attribute type names,
attribute flags, and the boolean constants "true" and "false" are
never translated. Translation of attribute identifiers is prohibited
because, as with domain names, they can potentially be part of a
service: URL and therefore their character set is restricted. In
addition, as with variable identifiers in programming languages, they
could become embedded into program code.
All strings used in attribute values are assumed translatable unless
explicitly defined as being literal, so that best effort translation
(see below) does not modify strings which are meant to be interpreted
by a program, not a person.
An example of a translated service template is included in Section A.
There are two ways to go about translation: standardization and best
effort.
When the service type is standardized, more than one document can be
submitted for review. One service type description is approved as a
master, so that when a service type template is updated in one
language, all the translations (at least eventually) reflect the same
semantics.
If no document exists describing the standard translation of the
service type, a 'best effort' translation for strings should be done.
7. Security Considerations
Service type templates provide information that is used to interpret
information obtained by the Service Location Protocol. If these
templates are modified or false templates are distributed, services
may not correctly register themselves, or clients might not be able
to interpret service information.
The service: URLs themselves specify the service access point and
protocol for a particular service type. These service: URLs could be
distributed and indicate the location of a service other than that
normally want to used. The Service Location Protocol [10]
distributes service: URLs and has an authentication mechanism that
allows service: URLs of registered services to be signed and for the
signatures to be verified by clients.
Each Service Template will include a security considerations section
which will describe security issues with using the service scheme for
the specific Service Type.
A. Service Template Examples
The text in the template example sections is to be taken as being a
single file. They are completely fictitious (ie. the examples do
not represent real services).
The FOO example shows how to use service templates for an application
that has very few attributes. Clients request the FOO server where
their user data is located by including their user name as the value
of the user attribute.
The Net-Transducer example shows how abstract service types are
defined and how a corresponding concrete instance is defined. A
system might support any of several NetTransducer services. Here we
give only one concrete instance of the abstract type.
It is not necessary to register concrete templates for an abstract
service type if the abstract service type template is completely
clear as to what possible values can be used as a concrete type, and
what their interpretation is.
A.1. FOO
The FOO service template submission example follows:
Name of submitter: "Erik Guttman" <Erik.Guttman@sun.com>
Language of service template: en
Security Considerations:
If the USER and GROUPS attributes are included a
possibility exists that the list of identities for users or groups
can be discovered. This information would otherwise be difficult
to discover.
Template Text:
-------------------------template begins here-----------------------
template-type=FOO
template-version=0.0
template-description=
The FOO service URL provides the location of an FOO service.
template-url-syntax=
url-path= ; There is no URL path defined for a FOO URL.
users= string M L O
# The list of all users which the FOO server supports.
groups= string M L O
# The list of all groups which the FOO server supports.
--------------------------template ends here------------------------
This template could be internationalized by registering another
version, say in German:
Name of submitter: "Erik Guttman" <Erik.Guttman@sun.com>
Language of service template: de
Security Considerations:
Wenn die USER und GROUPS Eigenschaften inbegriffen sind,
besteht die Moeglichkeit, dass die Liste der Identitaeten
von Benutzern oder Gruppen endeckt werden kann. Diese
Information wurde unter anderen Umstaenden schwierig zu
entdecken sein.
Template Text:
-------------------------template begins here-----------------------
template-type=FOO
template-version=0.0
template-description=
Der FOO Service URL zeigt die Stelle von einem Foo Service an.
template-url-syntax=
url-path= ; Es gibt keinen fuer den FOO URL definierten Pfad.
users= string M L O
# Die Liste aller Users, die der FOO Server unterstuetzt.
groups= string M L O
# Die Liste aller Gruppen, die der FOO Server unterstuetzt.
--------------------------template ends here------------------------
Note that the attribute tags are not translated. If translations
are desired, the suggested convention for doing so is to define a
separate attribute called localize-<tag> for each attribute tag which
is to be localized. This will aid in displaying the attribute tags
in a human interface.
For example, in this case above, the following two attributes could
be defined:
localize-users= string
Benutzer
localize-groups= string
Gruppen
The attributes (in SLPv2 attribute list format) for a service
registration of a FOO service based on this template, in German,
could be:
(users=Hans,Fritz),(groups=Verwaltung,Finanzbuchhaltung),
(template-type=FOO),(template-version=0.0),(template-description=
Der FOO Service URL zeigt die Stelle von einem Foo Service an.),
(template-url-syntax= \OD url-path= ; Es gibt kein fuer den FOO
URL definiert Pfad. \OD),(localize-users=Benutzer),
(localize-groups=Gruppen)
Anyone obtaining these attributes could display "Benutzer=Hans,Fritz"
in a human interface using the included information. Note that the
template attributes have been included in this registration. This is
OPTIONAL, but makes it possible to discover which template was used
to register the service.
A.2. Abstract Service Type: Net-Transducer
An example submission of an abstract service type template is:
Name of submitter: "Erik Guttman" <Erik.Guttman@sun.com>
Language of service template: en
Security Considerations:
See the security considerations of the concrete service types.
Template Text:
-------------------------template begins here-----------------------
template-type=Net-Transducer
template-version=0.0
template-description=
This is an abstract service type. The purpose of the Net-
Transducer service type is to organize into a single category
all network enabled Transducers which have certain properties.
template-url-syntax=
url-path= ; Depends on the concrete service type.
; See these templates.
sample-units= string L
# The units of sample that the Transducer provides, for instance
# C (degrees Celsius), V (Volts), kg (Kilograms), etc.
sample-resolution= string L
# The resolution of the Transducer. For instance, 10^-3 means
# that the Transducer has resolution to 0.001 unit.
sample-rate= integer L
# The speed at which samples are obtained per second. For
# instance 1000 means that one sample is obtained every millisecond.
--------------------------template ends here------------------------
A.3. Concrete Service Type: Net-Transducer:Thermometer
This is another service template submission example, supplying a
concrete service type corresponding to the abstract template above.
Name of submitter: "Erik Guttman" <Erik.Guttman@sun.com>
Language of service template: en
Security Considerations:
There is no authentication of the Transducer output. Thus,
the Thermometer output could easily be spoofed.
Template Text:
-------------------------template begins here-----------------------
template-type=service:Net-Transducer:Thermometer
template-version=0.0
template-description=
The Thermometer is a Net-Transducer capable of reading temperature.
The data is read by opening a TCP connection to one of the ports
in the service URL and reading an ASCII string until an NULL
character is encountered. The client may continue reading data at
no faster than the sample-rate, or close the connection.
template-url-syntax=
url-path = "ports=" ports-list
port-list = port / port "," ports
port = 1*DIGIT
; See the Service URL <port> production rule.
; These are the ports connections can be made on.
location-description=string
# The location where the Thermometer is located.
operator=string O
# The operator to contact to have the Thermometer serviced.
--------------------------template ends here------------------------
A.4. service: URLs and SLP
A user with an FOO enabled calendar application should not be
bothered with knowing the address of their FOO server. The calendar
client program can use SLP to obtain the FOO service: URL
automatically, say 'service:foo://server1.nosuch.org', by issuing a
Service Request. In the event that this FOO server failed, the
Calendar client can issue the same service request again to find the
backup FOO server, say 'service:foo://server2.nosuch.org'. In both
cases, the service: URL conforms to the FOO service template as do
the associated attributes (user and group.)
A network thermometer based on the above template could be advertised
with the SLPv2 attribute list:
URL = service:net-transducer:thermometer://v33.test/ports=3211
Attributes = (location-description=Missile bay 32),
(operator=Joe Agent), (sample-units=C),
(sample-resolution=10^-1),(sample-rate=10),
(template-type=service:net-transducer:thermometer),
(template-version=0.0),(template-description=
The Thermometer is a Net-Transducer capable of reading temperature.
The data is read by opening a TCP connection to one of the ports
in the service URL and reading an ASCII string until an NULL
character is encountered. The client may continue reading data at
no faster than the sample-rate, or close the connection.),
(template-url-syntax= \0D "ports=" port-list \OD
port-list = port / port "," ports \OD
port = 1*DIGIT \OD
; See the Service URL <port> production rule. \OD
; These are the ports connections can be made on.\OD)
This might be very useful for a technician who wanted to find a
Thermometers in Missile bay 32, for example.
Note that the template attributes are advertised. The
template-url-syntax value requires explicit escaped CR characters so
that the ABNF syntax is correct.
B. Acknowledgments
Thanks to Michael Day and Leland Wallace for assisting with the IPX
and AppleTalk address syntax portions. Ryan Moats provided valuable
feedback throughout the writing of this document.
C. References
[1] Protocol and service names, October 1994.
ftp://ftp.isi.edu/in-notes/iana/assignments/service-names.
[2] Port numbers, July 1997.
ftp://ftp.isi.edu/in-notes/iana/assignments/port-numbers.
[3] Alvestrand, H., "Tags for the Identification of Languages",
RFC1766, March 1995.
[4] ANSI. Coded Character Set -- 7-bit American Standard code for
Information Interchange. X3.4-1986, 1986.
[5] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform
Resource Identifiers (URI): Generic Syntax", RFC2396,
August 1998.
[6] Bradner, S., "Key Words for Use in RFCs to Indicate
Requirement Levels", BCP 14, RFC2119, March 1997.
[7] Apple Computer. Inside Macintosh. Addison-Wesley, 1993.
[8] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", RFC2234, November 1997.
[9] S. Gursharan, R. Andrews, and A. Oppenheimer. Inside AppleTalk.
Addison-Wesley, 1990.
[10] Guttman, E., Perkins, C., Veizades, J. and M. Day, "Service
Location Protocol Version 2", RFC2608, June 1999.
[11] Myers, J., "Simple Authentication and Security Layer (SASL)",
RFC2222, October 1997.
[12] Narten, T. and H. Alvestrand, "Guidelines for Writing
an IANA Considerations Section in RFCs, BCP 26, RFC2434,
October 1998
[13] Newman C. and J. Myers, "ACAP -- Application Configuration
Access Protocol", RFC2244, November 1997.
[14] Inc Novell. IPX RIP and SAP Router Specification. Part Number
107-000029-001, Version 1.30, May 1996.
[15] Veizades, J., Guttman, E., Perkins, C. and S. Kaplan, "Service
Location Protocol", RFC2165, July 1997.
[16] Yergeau, F., "UTF-8, a transformation format of ISO 10646",
RFC2279, January 1998.
D. Authors' Addresses
Questions about this memo can be directed to:
Erik Guttman
Sun Microsystems
Bahnstr. 2
74915 Waibstadt
Germany
Phone: +49 7263 911484
Fax: +1 650 786 5992
EMail: erik.guttman@sun.com
Charles E. Perkins
Sun Microsystems
15 Network Circle
Menlo Park, CA 94303
USA
Phone: +1 650 786 6464
Fas: +1 650 786 6445
EMail: cperkins@sun.com
James Kempf
Sun Microsystems
15 Network Circle
Menlo Park, CA 94303
USA
Phone: +1 650 786 5890
Fax: +1 650 786 6445
EMail: james.kempf@sun.com
E. 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 RFCEditor function is currently provided by the
Internet Society.