RFC 4515 - 轻量级目录访问协议 (LDAP): 搜索过滤器的字符串表示

Network Working Group M. Smith, Ed. Request for Comments: 4515 Pearl Crescent, LLC Obsoletes: 2254 T. Howes Category: Standards Track Opsware, Inc. June 2006

         Lightweight Directory Access Protocol (LDAP):
            String Representation of Search Filters

本备忘录的状态

本文档为互联网社区规定了一项互联网标准跟踪协议, 并请求讨论和改进建议. 有关本协议的标准化阶段和状态, 请参阅最新版的 "Internet Official Protocol Standards" (STD 1). 本备忘录的分发不受限制.

版权声明

Copyright (C) The Internet Society (2006).

摘要

轻量级目录访问协议 (Lightweight Directory Access Protocol, LDAP) 搜索过滤器在 LDAP 协议中使用适合网络传输的二进制表示. 本文档定义 LDAP 搜索过滤器的人类可读字符串表示, 该表示适合用于 LDAP URL (RFC 4516) 以及其他应用.

目录

1. 引言
2. LDAP 搜索过滤器定义
3. 字符串搜索过滤器定义
4. 示例
5. 安全考虑
6. 规范性引用
7. 资料性引用
8. 致谢 附录 A: 相对 RFC 2254 的变更 A.1. 技术变更 A.2. 编辑性变更

1. 引言

轻量级目录访问协议 (LDAP) [RFC4510] 定义了发送给 LDAP 服务器的搜索过滤器的网络表示. 某些应用可能需要一种通用方式, 以人类可读形式表示这些搜索过滤器; LDAP URL [RFC4516] 就是此类应用的一个例子. 本文档定义一种人类可读的字符串格式, 用于表示所有可能的 LDAP 版本 3 搜索过滤器, 包括扩展匹配过滤器.

本文档是 LDAP 技术规范 [RFC4510] 的组成部分. 该技术规范整体废止了先前定义 LDAP 技术规范的 RFC 3377.

本文档替代 RFC 2254. 相对 RFC 2254 的变更汇总于附录 A.

本文档中的关键词 "MUST"、"MUST NOT"、"REQUIRED"、"SHALL"、"SHALL NOT"、"SHOULD"、"SHOULD NOT"、"RECOMMENDED"、"MAY" 和 "OPTIONAL" 应按 BCP 14 [RFC2119] 中的说明解释.

2. LDAP 搜索过滤器定义

LDAP 搜索过滤器在 [RFC4511] 第 4.5.1 节中定义如下:

Filter ::= CHOICE {
    and                [0] SET SIZE (1..MAX) OF filter Filter,
    or                 [1] SET SIZE (1..MAX) OF filter Filter,
    not                [2] Filter,
    equalityMatch      [3] AttributeValueAssertion,
    substrings         [4] SubstringFilter,
    greaterOrEqual     [5] AttributeValueAssertion,
    lessOrEqual        [6] AttributeValueAssertion,
    present            [7] AttributeDescription,
    approxMatch        [8] AttributeValueAssertion,
    extensibleMatch    [9] MatchingRuleAssertion }

SubstringFilter ::= SEQUENCE {
    type    AttributeDescription,
    -- initial and final can occur at most once
    substrings    SEQUENCE SIZE (1..MAX) OF substring CHOICE {
     initial        [0] AssertionValue,
     any            [1] AssertionValue,
     final          [2] AssertionValue } }

AttributeValueAssertion ::= SEQUENCE {
    attributeDesc   AttributeDescription,
    assertionValue  AssertionValue }

MatchingRuleAssertion ::= SEQUENCE {
    matchingRule    [1] MatchingRuleId OPTIONAL,
    type            [2] AttributeDescription OPTIONAL,
    matchValue      [3] AssertionValue,
    dnAttributes    [4] BOOLEAN DEFAULT FALSE }

AttributeDescription ::= LDAPString
                -- Constrained to <attributedescription>
                -- [RFC4512]

AttributeValue ::= OCTET STRING

MatchingRuleId ::= LDAPString

AssertionValue ::= OCTET STRING

LDAPString ::= OCTET STRING -- UTF-8 encoded,
                            -- [Unicode] characters

[RFC4511] 所定义的 AttributeDescription 是 [RFC4512] 所讨论属性描述的字符串表示. AttributeValue 和 AssertionValue 这两个 OCTET STRING 采用 [RFC4517] 中定义的形式. Filter 使用 [X.690] 定义的基本编码规则 (Basic Encoding Rules, BER) 编码后通过网络传输, 并采用 [RFC4511] 所述的简化规则.

3. 字符串搜索过滤器定义

LDAP 搜索过滤器的字符串表示是由 UTF-8 [RFC3629] 编码的 Unicode 字符 [Unicode] 组成的字符串, 由以下语法定义. 该语法采用 [RFC4234] 定义的 ABNF 记法. 除非另有说明, 此处使用但未在此定义的产生式均定义于 [RFC4512] 第 1.4 节 (通用 ABNF 产生式). 过滤器格式采用前缀记法.

filter         = LPAREN filtercomp RPAREN
filtercomp     = and / or / not / item
and            = AMPERSAND filterlist
or             = VERTBAR filterlist
not            = EXCLAMATION filter
filterlist     = 1*filter
item           = simple / present / substring / extensible
simple         = attr filtertype assertionvalue
filtertype     = equal / approx / greaterorequal / lessorequal
equal          = EQUALS
approx         = TILDE EQUALS
greaterorequal = RANGLE EQUALS
lessorequal    = LANGLE EQUALS
extensible     = ( attr [dnattrs]
                     [matchingrule] COLON EQUALS assertionvalue )
                 / ( [dnattrs]
                      matchingrule COLON EQUALS assertionvalue )
present        = attr EQUALS ASTERISK
substring      = attr EQUALS [initial] any [final]
initial        = assertionvalue
any            = ASTERISK *(assertionvalue ASTERISK)
final          = assertionvalue
attr           = attributedescription
                 ; The attributedescription rule is defined in
                 ; Section 2.5 of [RFC4512].
dnattrs        = COLON "dn"
matchingrule   = COLON oid
assertionvalue = valueencoding
; The <valueencoding> rule is used to encode an <AssertionValue>
; from Section 4.1.6 of [RFC4511].
valueencoding  = 0*(normal / escaped)
normal         = UTF1SUBSET / UTFMB
escaped        = ESC HEX HEX
UTF1SUBSET     = %x01-27 / %x2B-5B / %x5D-7F
                    ; UTF1SUBSET excludes 0x00 (NUL), LPAREN,
                    ; RPAREN, ASTERISK, and ESC.
EXCLAMATION    = %x21 ; exclamation mark ("!")
AMPERSAND      = %x26 ; ampersand (or AND symbol) ("&")
ASTERISK       = %x2A ; asterisk ("*")
COLON          = %x3A ; colon (":")
VERTBAR        = %x7C ; vertical bar (or pipe) ("|")
TILDE          = %x7E ; tilde ("~")

请注意, 尽管上述语法中的 <substring> 和 <present> 产生式都可以生成 attr=* 结构, 但该结构仅用于表示存在性过滤器.

<valueencoding> 规则确保整个过滤器字符串是有效的 UTF-8 字符串, 并规定表示 ASCII 字符 * (ASCII 0x2a)、( (ASCII 0x28)、) (ASCII 0x29)、\ (ASCII 0x5c) 和 NUL (ASCII 0x00) 的八位组必须表示为反斜杠 \ (ASCII 0x5c), 后跟两个表示所编码八位组值的十六进制数字.

这种简单的转义机制消除了过滤器解析的歧义, 并允许任何可用 LDAP 表示的过滤器表示为以 NUL 结尾的字符串. <normal> 集合中的其他八位组也可以使用这种机制转义, 例如不可打印的 ASCII 字符.

对于包含 UTF-8 字符数据的 AssertionValue, 待转义字符的每个八位组都由一个反斜杠和两个十六进制数字替换, 它们在该字符的编码中构成单个八位组. 例如, 检查 cn 属性值中任意位置是否包含字符 * 的过滤器应表示为 (cn=*\2a*).

如 <valueencoding> 规则所示, 实现生成搜索过滤器的字符串表示时, MUST 转义所有大于 0x7F 且不属于有效 UTF-8 编码序列的八位组. 实现 SHOULD 接受并非有效 UTF-8 字符串的输入字符串. 这是必要的, 因为 RFC 2254 并未清晰定义术语 "字符串表示" (尤其没有提到 LDAP 搜索过滤器的字符串表示是由 UTF-8 编码的 Unicode 字符组成的字符串).

4. 示例

本节给出使用这种记法编写的若干搜索过滤器示例.

(cn=Babs Jensen)
(!(cn=Tim Howes))
(&(objectClass=Person)(|(sn=Jensen)(cn=Babs J*)))
(o=univ*of*mich*)
(seeAlso=)

以下示例说明扩展匹配的用法.

(cn:caseExactMatch:=Fred Flintstone)
(cn:=Betty Rubble)
(sn:dn:2.4.6.8.10:=Barney Rubble)
(o:dn:=Ace Industry)
(:1.2.3:=Wilma Flintstone)
(:DN:2.4.6.8.10:=Dino)

第一个示例说明匹配规则 caseExactMatch 的用法.

第二个示例说明不带 matchingRule 的 MatchingRuleAssertion 形式的用法.

第三个示例说明如何使用 :oid 记法指定比较时应采用 OID 2.4.6.8.10 所标识的匹配规则, 以及评估匹配时应将条目可分辨名称中的属性视为条目的一部分 (以 :dn 表示).

第四个示例表示相等匹配, 但在执行匹配时还应将 DN 组件视为条目的一部分.

第五个示例是一个应应用于支持给定匹配规则的任何属性的过滤器 (因为省略了 <attr>).

第六个也是最后一个示例同样应应用于支持给定匹配规则的任何属性. 还应考虑 DN 中支持该匹配规则的属性.

以下示例说明转义机制的用法.

(o=Parens R Us \28for all your parenthetical needs\29)
(cn=*\2A*)
(filename=C:\5cMyFile)
(bin=\00\00\00\04)
(sn=Lu\c4\8di\c4\87)
(1.3.6.1.4.1.1466.0=\04\02\48\69)

第一个示例说明如何使用转义机制表示括号字符. 第二个示例说明如何在断言值中表示 *, 从而避免将其解释为子串指示符. 第三个示例说明如何转义反斜杠字符.

第四个示例给出一个搜索四八位组值 00 00 00 04 (十六进制) 的过滤器, 说明如何使用转义机制表示包括 NUL 字符在内的任意数据.

第五个示例说明如何使用转义机制表示各种非 ASCII UTF-8 字符. 具体而言, 此示例的 <assertionvalue> 部分包含 5 个字符: 拉丁大写字母 L (U+004C)、拉丁小写字母 U (U+0075)、带倒勾的拉丁小写字母 C (U+010D)、拉丁小写字母 I (U+0069), 以及带尖音符的拉丁小写字母 C (U+0107).

第六个也是最后一个示例演示对 BER 编码值的断言.

5. 安全考虑

本文档描述 LDAP 搜索过滤器的一种字符串表示. 尽管该表示本身没有已知的安全影响, LDAP 搜索过滤器却有安全影响. LDAP 服务器会解释这些过滤器, 以选择要从中检索数据的条目. LDAP 服务器应注意保护其维护的数据, 防止未经授权的访问.

更多信息请参阅 [RFC4511] 和 [RFC4513] 的安全考虑章节.

6. 规范性引用

[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.

[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, November 2003.

[RFC4234] Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 4234, October 2005.

[RFC4510] Zeilenga, K., Ed., "Lightweight Directory Access Protocol (LDAP): Technical Specification Road Map", RFC 4510, June 2006.

[RFC4511] Sermersheim, J., Ed., "Lightweight Directory Access Protocol (LDAP): The Protocol", RFC 4511, June 2006.

[RFC4512] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP): Directory Information Models", RFC 4512, June 2006.

[RFC4513] Harrison, R., Ed., "Lightweight Directory Access Protocol (LDAP): Authentication Methods and Security Mechanisms", RFC 4513, June 2006.

[RFC4517] Legg, S., Ed., "Lightweight Directory Access Protocol (LDAP): Syntaxes and Matching Rules", RFC 4517, June 2006.

[Unicode] The Unicode Consortium, "The Unicode Standard, Version 3.2.0" is defined by "The Unicode Standard, Version 3.0" (Reading, MA, Addison-Wesley, 2000. ISBN 0-201-61633-5), as amended by the "Unicode Standard Annex #27: Unicode 3.1" (http://www.unicode.org/reports/tr27/) and by the "Unicode Standard Annex #28: Unicode 3.2."

7. 资料性引用

[RFC4516] Smith, M., Ed. and T. Howes, "Lightweight Directory Access Protocol (LDAP): Uniform Resource Locator", RFC 4516, June 2006.

[X.690] Specification of ASN.1 encoding rules: Basic, Canonical, and Distinguished Encoding Rules, ITU-T Recommendation X.690, 1994.

8. 致谢

本文档替代 Tim Howes 编写的 RFC 2254. RFC 2254 是 IETF ASID 工作组的工作成果.

本修订规范所包含的变更基于作者之间的讨论、LDAP (v3) 修订工作组 (ldapbis) 内的讨论, 以及其他 IETF 工作组内的讨论. 谨此感谢这些工作组中各位成员所作的贡献.

附录 A: 相对 RFC 2254 的变更

A.1. 技术变更

将 [ISO 10646] 引用替换为 [Unicode].

对 "字符串搜索过滤器定义" 一节的内容进行了以下技术变更:

增加说明, 指出字符串表示是由 UTF-8 编码的 Unicode 字符组成的字符串.

修订全部 ABNF, 以使用 [RFC4512] 中的通用产生式.

在 simple、extensible 和 substring (initial、any 和 final) 规则中, 以新的 assertionvalue 规则替换 value 规则. 这与 [RFC4517] 中的变更一致.

为清晰起见, 在 <extensible> 子产生式的组成部分外围添加 ( 和 ).

修订 attr、matchingrule 和 assertionvalue 的 ABNF, 使其更准确地引用 [RFC4512] 和 [RFC4511] 文档中的产生式.

在 "字符串搜索过滤器定义" 一节中, 将 greater 和 less 替换为 greaterorequal 和 lessorequal, 以避免混淆.

引入 valueencoding 及其相关的 normal 和 escaped 规则, 以减少对说明性文本的依赖. normal 产生式将过滤器字符串限制为有效的 UTF-8 序列.

鉴于 RFC 2254 未清晰定义 "字符串表示", 增加了关于预期行为的说明.

A.2. 编辑性变更

修改文档标题, 加入 LDAP: 前缀.

IESG 注释: 删除关于缺乏令人满意的强制性认证机制的注释.

在文档页眉和 "作者地址" 一节中, 增加 Mark Smith 作为文档编辑, 并更新所属机构和联系信息.

增加 "目录" 和 "知识产权" 章节.

按照最新 IETF 指南更新版权声明.

将 "摘要" 一节从引言材料中分离出来.

新增 "引言" 一节, 并将其从摘要中分离. 更新第二段, 指出本文档替代 RFC 2254 (而不是 RFC 1960). 增加对 [RFC4510] 文档的引用.

在 "LDAP 搜索过滤器定义" 一节中, 修正 LDAP 搜索过滤器的 ABNF, 使其与 [RFC4511] 中采用的定义一致.

澄清 value (现为 assertionvalue) 的定义, 以考虑它并不完全等同于 [RFC4511] 第 4.1.6 节中的 AttributeAssertion (某些字符需要特殊处理). 增加注释, 指出待转义字符的每个八位组均由一个反斜杠和两个十六进制数字替换, 它们表示单个八位组.

在 "示例" 一节中增加四个示例: (seeAlso=)、(cn:=Betty Rubble)、(:1.2.3:=Wilma Flintstone) 和 (1.3.6.1.4.1.1466.0=\04\02\48\69). 将一次 "a value" 替换为 "an assertion value". 修正对示例 (sn:dn:2.4.6.8.10:=Barney Rubble) 的说明. 在第一个扩展匹配示例中, 以 caseExactMatch 替换数字 OID, 以演示描述性形式的用法. 在最后一个扩展匹配示例中使用大写 DN, 以提醒读者 <dnattrs> 产生式不区分大小写. 改写第四个转义机制示例的说明, 避免对字节序作出假设. 在第五个转义机制示例的文本中明确说明这些非 ASCII 字符在 Unicode 中的含义.

在 "安全考虑" 一节增加对 [RFC4511] 和 [RFC4513] 的引用.

根据新的 RFC 指南, 将 "引用" 一节重命名为 "规范性引用". 在全文中将 [1] 样式改为 [RFC4511] 样式. 增加 [Unicode]、[RFC2119]、[RFC4513]、[RFC4512] 和 [RFC4510] 条目, 并更新 UTF-8 引用. 以 RFC 4234 的引用替换 RFC 822 的引用.

新增 "资料性引用" 一节, 并将 [X.690] 移至该节. 增加对 [RFC4516] 的引用.

增加 "致谢" 一节.

增加 "附录 A: 相对 RFC 2254 的变更" 一节.

在说明性文本中使用所有 ABNF 产生式名称时, 均用 < 和 > 将其括起.

将所有 LDAPv3 替换为 LDAP.

作者地址

Mark Smith, Editor
Pearl Crescent, LLC
447 Marlpool Dr.
Saline, MI 48176
USA

Phone: +1 734 944-2856
EMail: [email protected]

Tim Howes
Opsware, Inc.
599 N. Mathilda Ave.
Sunnyvale, CA 94085
USA

Phone: +1 408 744-7509
EMail: [email protected]

完整版权声明

Copyright (C) The Internet Society (2006).

本文档受 BCP 78 中所载权利、许可和限制的约束, 除其中明确规定的情形外, 作者保留其所有权利.

本文档及其中所含信息按 "原样" 提供. 投稿者、其所代表或赞助其的组织 (如有)、互联网协会以及互联网工程任务组不作任何明示或默示保证, 包括但不限于使用本文档中的信息不会侵犯任何权利的保证, 以及任何适销性或特定用途适用性的默示保证.

知识产权

对于任何声称与实施或使用本文档所述技术有关的知识产权或其他权利的有效性或范围, 以及此类权利下的许可可能或不可能获得到何种程度, IETF 不持任何立场; IETF 也不表示已作出任何独立努力来识别此类权利. 关于 RFC 文档所涉权利的处理程序, 可参见 BCP 78 和 BCP 79.

向 IETF 秘书处作出的知识产权披露副本、将提供许可的任何保证, 或实施者试图获得使用此类专有权利的一般许可或授权的结果, 均可从 IETF 在线知识产权存储库 http://www.ietf.org/ipr 获取.

IETF 邀请任何相关方提请其注意可能涵盖实施本标准所需技术的任何版权、专利或专利申请, 或其他专有权利. 请将相关信息发送至 [email protected].

致谢声明

RFC Editor 职能的经费由 IETF Administrative Support Activity (IASA) 提供.