Implementation+Guidelines+for+publishing+and+discovering+LDAP+services+using+the+DNS+SRV+Record

Please use the space below to develop and edit implementation guidelines:


 * DRAFT -- Please offer corrections and additions**


 * Some how a older revision must have been posted here. userSMIMEcertificate:binary should be instead be userCertificate:binary -PB**

This implementation guide covers the use of [|Lightweight Directory Access Protocol (LDAP) v3] for publishing and discovering Digital Certificates for use with the Direct Project, and the formal specification Applicability Statement for Secure Health Transport. This method is an alternative to publishing and discovering Digital Certificates using a CERT record in the DNS protocol.

This guidance is in support of the Direct Project Certificate Pilot Recommendations Discussion. This solution supports all the Certificate guidance, and is simply an alternative method of distributing the Digital Certificate, which is the signed public key and thus not sensitive. There is a well established set of requirements in the Direct Project on Trust that must be followed.

The use of [|LDAP]for discovery of Digital Certificates is commonly found in [|off-the-shelf e-mail packages] and the guidelines here are expected to be compatible with the method used by these off-the-shelf e-mail packages. Note that with many of these off-the-shelf e-mail packages one would need to configure the address of Directories known to be needed, as it is not common to use the DNS discovery model. In organizations where Directory usage is already integrated with mail systems, which is a fairly common scenario, the question will be how to discover certificates outside the organization's current Directory using the Internet. In this case that would be a business use case for a relying party since the internal use case would already be vetted. In that case the software is likely to first require the importation of a "root certificate" for organizations which are outside one's current environment to form a basis for trust for subsequent certificates for other entities. Once one obtains that root certificate, then subsequent certificates that are signed by that root will be trusted and can be mathematically verified or rejected.

Note that the use of [|LDAP v3] here is not exclusive to specifically RFC 4510, but rather the family of IETF specifications for LDAP v3. The IETF clearly defines LDAP as an access method for X.500 directories which is "lightweight" and Internet based.

X.500 directories use LDAP as an access protocol.

In the early 1990's when computers had little processing power compared to today, and there were considerably fewer Internet connected computers, the X.500 protocol was enhanced by the addition of LDAP to allow for Internet access.

Hence the term "Lightweight Directory Access Protocol" that did not use the ISO/ITU Directory Access Protocol or DAP.

Somewhat later the University of Michigan got a grant to create a "standalone" LDAP server which could be used without a connection to the larger X.500 Directory, and this forms the code base for most LDAP servers. These have been available as open source, and in vendor supported versions, dating back to the 1990's for storing user information and digital certificates within organizations.

This does not place storage requirements on the Directory since the digital certificate is an independent security object.

However, this was the original design and the data design of the Directory is very closely aligned with Digital Certificates. This is because Digital Certificates were designed circa X.509v1 solely for the purpose of authentication to the Directory, and not for web sites, SSL etc, which came later. This was expanded for Internet use with the PKIX, which is used by the Direct Project, which does not require the use of the Directory for storage. This has to be explicitly mentioned in the RFC because it is such an obvious choice, that where it had been required before in version 1, in version 3 of certificates that have extensions, this is no longer the case, thus opening the door for other methods of adoption.

The Directory internal structure can be of any format including X.500 or any other type of database, and X.500 software is built on top of specialized databases, but contains an integrated schema that is an international standard. Certain database structures for storing certificates are patent protected.

The use of LDAP v3 only constrains the Directory to at least make LDAP v3 interface available. Other interfaces are possible including web-services or RESTful implementations such as [|DSML]. These other interfaces are not constrained by this guideline, nor are they leveraged.

Note that the use of [|RFC-2798 iNetOrgPerson] is used to enable the most broad availability of the information published. This does not restrict entries in the Directory from using other schema, it is common for multiple schema to be used for the same entries. The iNetOrgPerson schema is used as it is commonly implemented and often the default schema for individuals. The iNetOrgPerson schema includes the two attributes that we require for this guideline - The 'Mail ' attribute holds the Direct Project endpoint address (e-mail address) and the 'userSMIMECertificate ' holds the Digital Certificate to be used for the Direct Project secure communications.

The userSMIMECertificate attribute are to be stored and requested in binary form, as 'userSMIMECertificate;binary'. The attribute value is a [|PKCS#7 / RFC-2315] SignedData, where the content that is signed is ignored by consumers of userSMIMECertificate values. It is recommended that values have a `contentType' of data with an absent `content' field. Values of this attribute contain a person's entire certificate chain and an smimeCapabilities field [|RFC-2633] that at a minimum describes their SMIME algorithm capabilities. =Publishing=

The publishing of a Digital Certificate by this method includes: Publishing the endpoint Digital Certificate in an [|LDAP]Directory, and publishing the availability of the Directory using DNS.

Publishing the endpoint Digital Certificate
A Digital Certificate for use for the Direct Project is published in a 'person ' entry using the well established iNetOrgPerson schema. When an Direct Project endpoint (e-mail address) is not an individual but a department or whole organization; this guidance recommends that this be represented as a 'person ' entry as defined above.

If the same Digital Certificate is to be used for multiple Direct Project endpoints (e-mail addresses), then one of two models can be followed: 1) Multiple entries are made to the LDAP Directory with each having the unique "Mail " attribute and the same Digital Certificate in the "userSMIMECertificate " attribute. This is usually preferable as it is expandable to use of this directory for other Provider Directory needs. 2) One entry is made in the LDAP Directory with multiple "Mail " attributes for each of the e-mail addresses supported by the Digital Certificate included in that one entry "userSMIMECertificate ".

Publishing the availability of the Directory
The Directory must be addressable on the Internet, and offer 'anonymous' access to the entries defined above. The directory need only make available the "Mail ", "userSMIMECertificate ". Depending on the requirements that the Directory software places on the system other attributes may be required and thus need to be filled with accurate or pseudo information. These other attributes do not need to be published for anonymous access.

The Directory must be discoverable using DNS service location protocol. This is defined in [|RFC-2782 A DNS RR for specifying the location of services (DNS SRV)]. This is accomplished by publication of a Resource Record (RR) of type Service ("SRV ") record identifying the IP address of the Directory using the well known service identity "_ldap._tcp ". Some Directory software will automatically add this SRV record to the DNS (e.g. Microsoft Active Directory).

There can be multiple SRV records for each domain that is published in the Directory. For example if a Directory is used to host Digital Certificates for , and also <John@nwhin.example.com>; then two entries would be published in DNS "<span style="font-family: 'Courier New',Courier,monospace;">_ldap._tcp.example.com " and "<span style="font-family: 'Courier New',Courier,monospace;">_ldap._tcp.nwhin.example.com ".

=Discovery=

The discovery of Digital Certificates published in LDAP expects that the Digital Certificates are published according the the Publishing guide above.

The overall process is:
 * 1) Use DNS to discover the IP address of a LDAP directory for the domain of the endpoint Direct Project address (e-mail address)
 * 2) Use LDAP to discover the certificate for the endpoint Direct Project address (e-mail address)

The use of DNS to discover the Directory is not mandatory if the system is configured with an authorized list of Directories. It is described as a friction-less method of discovering the Directory.

Discover a Directory for that Domain of interest
A Direct Project endpoint address is defined as being composed of two parts the "Health Domain Name" (aka health-domain-name) and the "Health Endpoint Name" (aka health-endpoint-name) - In the format <span style="font-family: 'Courier New',Courier,monospace;"><health-endpoint-name@health-domain-name> ; which is the commonly understood e-mail address. In order to discover the LDAP directory that has knowledge about the endpoint address, we first must find the LDAP directories that are available to support queries on the '<span style="font-family: 'Courier New',Courier,monospace;">health-domain-name '.

Discovering the electronic address of an LDAP directory that holds information on the domain of the recipient is done using[| RFC-2782 A DNS RR for specifying the location of services (DNS SRV)] - In this specification is the explanation of how to request through the DNS system for a "Resource Record" for a service (i.e. LDAP) at a domain. The LDAP service is identified using the constant "<span style="font-family: 'Courier New',Courier,monospace;">_ldap._tcp ", which one simply appends the '<span style="font-family: 'Courier New',Courier,monospace;">health-domain-name'. For example <John@example.com> becomes a DNS resource record search for "<span style="font-family: 'Courier New',Courier,monospace;">_ldap._tcp.example.com ".

Quote from the introduction to [|RFC-2782] code If a SRV-cognizant LDAP client wants to discover a LDAP server that supports TCP protocol and provides LDAP service for the domain example.com., it does a lookup of

_ldap._tcp.example.com

as described in [ARM]. The example zone file near the end of this memo contains answering RRs for an SRV query.

Note: LDAP is chosen as an example for illustrative purposes only, and the LDAP examples used in this document should not be considered a definitive statement on the recommended way for LDAP to use SRV records. As described in the earlier applicability section, consult the appropriate LDAP documents for the recommended procedures.

code This DNS query will result in a list Resource Records of LDAP servers. The next step should be attempted with each of these in the order defined by the Priority and Weight as defined in [|RFC 2782] until a suitable certificate is discovered. Generally this is to use the entries with low Priority numbers first, using the Weight only when more than one entry has the same Priority number. for example a query might return: code _ldap._tcp   SRV 0 1 9 old-slow-box.example.com. SRV 0 3 9 new-fast-box.example.com. code

Discover the Digital Certificate
We now use LDAP queries to discover the available Digital Certificates for the endpoint address. This is done using [|RFC-4510 - Lightweight Directory Access Protocol (v3)], and the schema for individuals -- [|RFC-2798 iNetOrgPerson]. Specifically the e-mail address is searched for in the "Mail" attribute, and the Digital Certificate is returned in the "userSMIMECertificate" attribute.

The general steps are: 1) Bind to the Directory using LDAP v3 anonymous authentication 2) Discover the Base DN 3) Query across the Base DN for entries where "Mail" contains the endpoint address 4) For each entry returned, examine the Digital Certificate in the 'userSMIMECertificate' attribute for acceptability

LDAP anonymous bind
Anonymous authentication shall be used to access the LDAP Directory. Anonymous authentication is described in the [|LDAP v3 specification in section 4.2 Bind Operation].

Discover the Base DN
<span style="font-family: 'Times New Roman',serif; font-size: 12pt;">Branches in LDAP are defined by a “Base DN”. The list of Base DNs that are provided by a LDAP directory can be found by doing a LDAP Query with a NULL (i.e. “”) Base DN, and ObjectClass=”DN”.

<span style="font-family: 'Times New Roman',serif; font-size: 12pt;">Query for the Mail entry
The LDAP query will search using all the "Base DN" found for the "Mail" attribute equal to the endpoint address desired. The Scope should be set to "subtree" to allow for multiple branches to the tree defined by the returned Base DN. The "attributes" should include "userSMIMECertificate" to assure that this attribute is returned if it is available. The "attributes" may include other attributes of interest, but their specification and use is outside the scope of this guideline.

**Determine Acceptability**
Many Digital Certificates may be discovered through this method, one must determine the 'best' fit. This is done through inspecting the content of each Digital Certificate. The method of inspection and choice is defined in the Direct Project formal specification as defined in the section on Trust Verification which includes determining the proper use. This is not further constrained by the method of discovery.