home *** CD-ROM | disk | FTP | other *** search
/ Internet Info 1997 December / Internet_Info_CD-ROM_Walnut_Creek_December_1997.iso / drafts / draft_ietf_a_c / draft-ietf-asid-ldapv3-lang-02.txt < prev    next >
Text File  |  1997-06-06  |  18KB  |  465 lines
  1.  
  2. Network Working Group                                            M. Wahl
  3. INTERNET-DRAFT                                       Critical Angle Inc.
  4.                                                                 T. Howes
  5.                                            Netscape Communications Corp.
  6. Expires in six months from                                   6 June 1997
  7. Intended Category: Standards Track
  8.  
  9.  
  10.                      Use of Language Codes in LDAPv3
  11.                   <draft-ietf-asid-ldapv3-lang-02.txt>
  12.  
  13. 1. Status of this Memo
  14.  
  15.    This document is an Internet-Draft.  Internet-Drafts are working 
  16.    documents of the Internet Engineering Task Force (IETF), its areas,and
  17.    its working groups.  Note that other groups may also distribute 
  18.    working documents as Internet-Drafts.
  19.  
  20.    Internet-Drafts are draft documents valid for a maximum of six months
  21.    and may be updated, replaced, or obsoleted by other documents at any
  22.    time.  It is inappropriate to use Internet-Drafts as reference 
  23.    material or to cite them other than as "work in progress."
  24.  
  25.    To learn the current status of any Internet-Draft, please check the
  26.    "1id-abstracts.txt" listing  contained in the Internet-Drafts Shadow
  27.    Directories on ds.internic.net (US East Coast), nic.nordu.net (Europe),
  28.    ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim).
  29.  
  30. 2. Abstract
  31.  
  32.    The Lightweight Directory Access Protocol [1] provides a means for 
  33.    clients to interrogate and modify information stored in a distributed
  34.    directory system.  The information in the directory is maintained as 
  35.    attributes [2] of entries.  Most of these attributes have syntaxes 
  36.    which are human-readable strings, and it is desirable to be able to 
  37.    indicate the natural language associated with attribute values.  
  38.  
  39.    This document describes how language codes [3] are carried in LDAP 
  40.    and are to be interpreted by LDAP servers.  All implementations MUST
  41.    be prepared to accept language codes in the LDAP protocols.  Servers 
  42.    may or may not be capable of storing attributes with language codes 
  43.    in the directory.
  44.  
  45. 3. Language Codes
  46.  
  47.    Section 2 of RFC 1766 [3] describes the language code format which is 
  48.    used in LDAP.  Briefly, it is a string of ASCII alphabetic characters 
  49.    and hyphens.  Examples include "fr", "en-US" and "ja-JP". 
  50.  
  51.    Language codes are case insensitive.  For example, the language code 
  52.    "en-us" is the same as "EN-US" and "en-US".  One language code is a 
  53.    prefix of another if both codes are equal up to the length of the 
  54.    first code.  For example, the language code "en" is a prefix of the 
  55.    language codes "en-us" and "EN-US".
  56.  
  57.  
  58. Wahl, Howes                                                     [Page 1]
  59.  
  60. INTERNET-DRAFT            Use of Language Codes in LDAPv3      June 1997
  61.  
  62.    Implementations MUST NOT otherwise interpret the structure of the 
  63.    code when comparing two codes, but should treat them as simply 
  64.    strings of characters. Client and server implementations MUST allow 
  65.    any arbitrary string which follows the patterns given in RFC 1766 to 
  66.    be used as a language code.
  67.  
  68. 4. Use of Language Codes in LDAP
  69.   
  70.    This section describes how LDAP implementations MUST interpret 
  71.    language codes in performing operations.  
  72.  
  73.    In general, an attribute with a language code is to be treated as a 
  74.    subtype of the attribute without a language code.  If a server does 
  75.    not support storing language codes with attribute values in the DIT, 
  76.    then it MUST always treat an attribute with a language code as an 
  77.    unrecognized attribute.
  78.  
  79.    Clients may request the use of a particular language through the 
  80.    preferredLanguage control.  This control determines how the server
  81.    interprets attributes without an explicit language parameter.  The 
  82.    details of this interaction for specific operations are given below.
  83.  
  84. 4.1. Attribute Description
  85.  
  86.    An attribute consists of a type, a list of options for that type, and 
  87.    a set of one or more values.  In LDAP, the type and the options are 
  88.    combined into the AttributeDescription, defined in section 4.1.5 of 
  89.    [1]. This is represented as an attribute type name and a 
  90.    possibly-empty list of options.  One of these options associates a 
  91.    natural language with values for that attribute. 
  92.  
  93.         language-option = "lang-" lang-code
  94.  
  95.         lang-code = printable-ascii ; a code as defined in RFC 1766
  96.  
  97.    There can be at most one language option present in an 
  98.    AttributeDescription.
  99.  
  100.    The language code has no effect on the character set encoding for 
  101.    string representations of DirectoryString syntax values; the UTF-8 
  102.    representation of UniversalString (ISO 10646) is always used.
  103.  
  104.    Examples of valid AttributeDescription:
  105.         givenName;lang-en-US
  106.         CN;lang-ja-JP-kanji
  107.         CN;lang-ja-JP-romaji
  108.  
  109.    In LDAP and in examples in this document, a directory attribute is 
  110.    represented as an AttributeDescription with a list of values.  Note 
  111.    that the data may be stored in the LDAP server in a different 
  112.    representation.
  113.  
  114.  
  115.  
  116. Wahl, Howes                                                     [Page 2]
  117.  
  118. INTERNET-DRAFT            Use of Language Codes in LDAPv3      June 1997
  119.  
  120. 4.2.  Preferred Language Control
  121.  
  122.    The preferredLanguage control is always non-critical.  Its value is
  123.    a language code as defined in RFC 1766 [3].  If this control is 
  124.    absent, the default is that there is no preferred language for the 
  125.    client.  The OID of the control is "1.3.6.1.4.1.1466.20035".
  126.  
  127.    It is recommended that clients should use the most general language 
  128.    code which is suitable for their purpose.  A language code with 
  129.    multiple subtags may result in too much directory information being 
  130.    filtered out of responses.  In most cases, it is recommended that 
  131.    only the primary language tag (such as "EN") should be provided.
  132.  
  133.    If the server supports the storing of language codes with attribute 
  134.    values in the DIT, then it MUST indicate that the OID given above is 
  135.    a supported control in the supportedControl attribute of the root DSE.
  136.    Otherwise it SHOULD NOT indicate support for this control.
  137.  
  138. 4.3. Distinguished Names and Relative Distinguished Names
  139.  
  140.    No attribute description options are permitted in Distinguished Names
  141.    or Relative Distinguished Names.  Thus language codes MUST NOT be 
  142.    used in forming DNs.
  143.  
  144. 4.4. Search Filter
  145.  
  146.    A client may provide a language code in an AttributeDescription in a 
  147.    search filter.  If present, then only attribute values in the 
  148.    directory which match the base attribute type or its subtype, the 
  149.    language code and the assertion value match this filter. 
  150.  
  151.    Thus for example a filter of an equality match of type 
  152.    "name;lang-en-US" and assertion value "Billy Ray", against the 
  153.    following directory entry
  154.  
  155.    objectclass: top                     DOES NOT MATCH (wrong type)
  156.    objectclass: person                  DOES NOT MATCH (wrong type)
  157.    name;lang-EN-US: Billy Ray           MATCHES 
  158.    name;lang-EN-US: Billy Bob           DOES NOT MATCH (wrong value)
  159.    CN;lang-EN-US;dynamic: Billy Ray     MATCHES
  160.    CN;lang-en;dynamic: Billy Ray        DOES NOT MATCH (differing lang-)
  161.    name: Billy Ray                      DOES NOT MATCH (no lang-)
  162.    SN: Ray                              DOES NOT MATCH (wrong value)
  163.  
  164.    (Note that "CN" and "SN" are subtypes of "name".)  
  165.  
  166.    If the server does not support storing language codes with attribute 
  167.    values in the DIT, then any filter which includes a language code 
  168.    will always fail to match, as it is an unrecognized attribute type 
  169.    (note however than no error will be returned because of this).
  170.  
  171.  
  172.  
  173.  
  174. Wahl, Howes                                                     [Page 3]
  175.  
  176. INTERNET-DRAFT            Use of Language Codes in LDAPv3      June 1997
  177.  
  178.    If no language code is specified in the search filter, then only the 
  179.    base attribute type and the assertion value need match the value in 
  180.    the directory.  
  181.  
  182.    Thus for example a filter of an equality match of type "name" and 
  183.    assertion value "Billy Ray", against the following directory entry
  184.  
  185.    objectclass: top                     DOES NOT MATCH (wrong type)
  186.    objectclass: person                  DOES NOT MATCH (wrong type)
  187.    name;lang-EN-US: Billy Ray           MATCHES
  188.    name;lang-EN-US: Billy Bob           DOES NOT MATCH (wrong value)
  189.    CN;lang-EN-US;dynamic: Billy Ray     MATCHES
  190.    CN;lang-en;dynamic: Billy Ray        MATCHES
  191.    name: Billy Ray                      MATCHES
  192.    SN: Ray                              DOES NOT MATCH (wrong value)
  193.  
  194.    There is no effect of the preferredLanguage control in filtering.
  195.  
  196. 4.5. Compare 
  197.  
  198.    A client may provide a language code in an AttributeDescription used 
  199.    in a compare request AttributeValueAssertion.  This is to be treated 
  200.    by servers the same as the use of language codes in a search filter 
  201.    with an equality match, as described in the previous section.  If 
  202.    there is no attribute in the entry with the same subType and language
  203.    code, the noSuchAttributeType error will be returned.
  204.  
  205.    Thus for example a compare request of type "name" and assertion value 
  206.    "Johann", against an entry with all the following directory entry
  207.  
  208.    objectclass: top
  209.    objectclass: person
  210.    givenName;lang-de-DE: Johann
  211.    CN: Johann Sibelius
  212.    SN: Sibelius
  213.  
  214.    will cause the server to return compareTrue.
  215.  
  216.    If the server does not support storing language codes with attribute 
  217.    values in the DIT, then any comparison which includes a language code 
  218.    will always fail to locate an attribute type, and noSuchAttributeType 
  219.    will be returned.
  220.  
  221.    There is no effect of the preferredLanguage control in comparing.
  222.  
  223. 4.6. Requested Attributes in Search
  224.  
  225.    Clients may provide language codes in AttributeDescription in the 
  226.    requested attribute list in a search request.
  227.  
  228.  
  229.  
  230.  
  231.  
  232. Wahl, Howes                                                     [Page 4]
  233.  
  234. INTERNET-DRAFT            Use of Language Codes in LDAPv3      June 1997
  235.  
  236.    If a language code is provided in an attribute description, then only
  237.    attribute values in a directory entry which have the same language 
  238.    code as that provided may be returned. Thus if a client requests an 
  239.    attribute "description;lang-en", the server MUST NOT return values of 
  240.    an attribute "description" or "description;lang-fr".
  241.  
  242.    Clients may provide in the attribute list multiple 
  243.    AttributeDescription which have the same base attribute type but 
  244.    different options. For example a client may provide both 
  245.    "name;lang-en" and "name;lang-fr", and this would permit an attribute 
  246.    with either language code to be returned.  Note there would be no 
  247.    need to provide both "name" and "name;lang-en" since all subtypes of 
  248.    name would match "name".
  249.  
  250.    If a server does not support storing language codes with attribute 
  251.    values in the DIT, then any attribute descriptions in the list which 
  252.    include language codes are to be ignored, just as if they were 
  253.    unknown attribute types.
  254.  
  255.    If a request is made specifying all attributes or an attribute is 
  256.    requested without providing a language code, and the 
  257.    preferredLanguage control has not been set, then all attribute values 
  258.    regardless of their language code are returned.
  259.  
  260.    For example, if the client has set no preferredLanguage control and
  261.    requests a "description" attribute, and a matching entry contains 
  262.  
  263.    objectclass: top
  264.    objectclass: organization
  265.    O: Software GmbH
  266.    description: software  
  267.    description;lang-en: software products
  268.    description;lang-de: softwareproduckte
  269.    postalAddress: Berlin 8001 Germany
  270.    postalAddress;lang-de: Berlin 8001 
  271.  
  272.    The server will return: 
  273.  
  274.    description: software
  275.    description;lang-en: software products
  276.    description;lang-de: softwareproduckte
  277.    
  278.    If the client has set the preferredLanguage control, then attributes 
  279.    are excluded from the result if either of the following is true:
  280.      - the attribute has a language code for which the preferredLanguage 
  281.        value is not a prefix, or 
  282.      - the attribute does not have a language code, but there is another 
  283.        attribute of the same type or a subtype in the entry, which has a 
  284.        language code for which the preferredLanguage value is a prefix.
  285.  
  286.  
  287.  
  288.  
  289.  
  290. Wahl, Howes                                                     [Page 5]
  291.  
  292. INTERNET-DRAFT            Use of Language Codes in LDAPv3      June 1997
  293.  
  294.    For example, if the client sets that the preferredLanguage was "en" 
  295.    and requests all attributes, then the following will be returned.  
  296.    The "description;lang-de" and "postalAddress;lang-de" are excluded, 
  297.    since the language code in these attributes does not match the 
  298.    preferredLanguage.  The "description" attribute is excluded, since it 
  299.    is a subtype of the "description;lang-en" attribute, which does match 
  300.    the language code.  
  301.  
  302.    objectclass: top
  303.    objectclass: organization
  304.    O: Software GmbH
  305.    description;lang-en: software products
  306.    postalAddress: Berlin 8001 Germany
  307.  
  308.   
  309.    If a server does not support storing language codes with attribute 
  310.    values in the DIT, then it will ignore the preferredLanguage control.
  311.  
  312. 4.7. Add Operation
  313.  
  314.    Clients may provide language codes in AttributeDescription in 
  315.    attributes of a new entry to be created, subject to the limitation 
  316.    that the client MUST provide the attribute values used in the RDN 
  317.    without any language code or any other option.
  318.  
  319.    A client may provide multiple attributes with the same attribute type 
  320.    and value, so long as each attribute has a different language code.
  321.  
  322.    Servers which support storing language codes in the DIT MUST allow any
  323.    attributes with DirectoryString to have a language code associated 
  324.    with it. Servers may allow language codes to be associated with other 
  325.    attributes.
  326.  
  327.    For example, the following is a legal request.
  328.  
  329.    objectclass: top
  330.    objectclass: person
  331.    objectclass: residentialPerson
  332.    name: John Smith
  333.    CN: John Smith
  334.    CN;lang-en: John Smith
  335.    SN: Smith
  336.    streetAddress: 1 University Street
  337.    streetAddress;lang-en: 1 University Street
  338.    streetAddress;lang-fr: 1 rue University
  339.    houseIdentifier;lang-fr: 9e etage
  340.  
  341.    If a server does not support storing language codes with attribute 
  342.    values in the DIT, then it MUST treat an AttributeDescription with a 
  343.    language code as an unrecognized attribute. If the server forbids the 
  344.    addition of unrecognized attributes then it MUST fail the add request 
  345.    with the appropriate result code.
  346.  
  347.  
  348. Wahl, Howes                                                     [Page 6]
  349.  
  350. INTERNET-DRAFT            Use of Language Codes in LDAPv3      June 1997
  351.  
  352.    There is no effect of the preferredLanguage control in storing 
  353.    attributes in the add operation.
  354.  
  355. 4.8. Modify Operation
  356.  
  357.    A client may provide a language code in an AttributeDescription as 
  358.    part of a modification element in the modify operation.  
  359.  
  360.    Attribute types and language codes MUST match exactly against values 
  361.    stored in the directory.  For example, if the modification is a 
  362.    "delete", then if the stored values to be deleted have a language 
  363.    code, the language code MUST be provided in the modify operation, and 
  364.    if the stored values to be deleted do not have a language code, then 
  365.    no language code is to be provided.
  366.  
  367.    If the server does not support storing language codes with attribute 
  368.    values in the DIT, then it MUST treat an AttributeDescription with a 
  369.    language code as an unrecognized attribute, and MUST fail the request 
  370.    with an appropriate result code.
  371.  
  372.    There is no effect of the preferredLanguage control in performing 
  373.    this operation.
  374.  
  375. 4.9. Diagnostic Messages
  376.  
  377.    If the server supports returning diagnostic messages in more than one 
  378.    language, then if the preferredLanguage control has been set, it may 
  379.    use the preferredLanguage to choose an appropriate message.  If the 
  380.    preferredLanguage is not recognized, the diagnostic messages MUST be 
  381.    returned in the default language.
  382.  
  383.    It is strongly recommended that in the default language for 
  384.    diagnostic messages, only printable ASCII characters be used, as not 
  385.    all clients will be able to display the full range of Unicode.
  386.  
  387. 5.  Security Considerations
  388.  
  389.    There are no known security considerations for this document.  See
  390.    the security considerations sections of [1] and [2] for security
  391.    considerations of LDAP in general.
  392.  
  393. 6.  Bibliography
  394.  
  395.    [1] M.Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol
  396.        (Version 3)", INTERNET DRAFT 
  397.        <draft-ietf-asid-ldapv3-protocol-05.txt>, June 1997.
  398.  
  399.    [2] M. Wahl, A. Coulbeck, T. Howes, S. Kille, "Lightweight X.500 
  400.        Directory Access Protocol Attribute Syntax Definitions", 
  401.        <draft-ietf-asid-ldapv3-attributes-05.txt>, June 1997.
  402.  
  403.    [3] H. Alvestrand, "Tags for the Identification of Languages",
  404.        RFC 1766, March 1995.
  405.  
  406. Wahl, Howes                                                     [Page 7]
  407.  
  408. INTERNET-DRAFT            Use of Language Codes in LDAPv3      June 1997
  409.  
  410.  
  411. 7.  Authors Addresses
  412.  
  413.        Mark Wahl
  414.        Critical Angle Inc.
  415.        4815 W Braker Lane #502-385
  416.        Austin, TX 78759
  417.        USA
  418.  
  419.        EMail:  M.Wahl@critical-angle.com
  420.  
  421.  
  422.        Tim Howes
  423.        Netscape Communications Corp.
  424.        501 E. Middlefield Rd
  425.        Mountain View, CA 94043
  426.        USA
  427.        
  428.        Phone:  +1 415 937-3419
  429.        EMail:   howes@netscape.com
  430.  
  431.  
  432.  
  433.  
  434.  
  435.  
  436.  
  437.  
  438.  
  439.  
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462. <draft-ietf-asid-ldapv3-lang-02.txt> Expires: November, 1997
  463.  
  464. Wahl, Howes                                                     [Page 8]
  465.