mirror of https://github.com/openssl/openssl.git
Add design doc for rfc4514 DN output format
Reviewed-by: Saša Nedvědický <sashan@openssl.org> Reviewed-by: Tomas Mraz <tomas@openssl.org> Reviewed-by: Todd Short <todd.short@me.com> (Merged from https://github.com/openssl/openssl/pull/28104)
This commit is contained in:
Viktor Dukhovni
Todd Short
parent
fb295aa65c
commit
da9a6c6ebd
|
|
@ -0,0 +1,258 @@
|
|||
RFC4514: String Representation of Distinguished Names
|
||||
=====================================================
|
||||
|
||||
Introduction
|
||||
------------
|
||||
|
||||
[RFC4514], obsoletes [RFC2253], which defines the standard string format for
|
||||
representing *Distinguished Names* (**DN**s) and *Relative Distinguished Names*
|
||||
(**RDN**s) within LDAP, but is used more broadly, e.g., as the string
|
||||
representations of issuer and subject names in X.509 certificates.
|
||||
|
||||
Distinguished Names (DNs)
|
||||
-------------------------
|
||||
|
||||
A *Distinguished Name* (**DN**) is a sequence of *Relative Distinguished Names*
|
||||
(**RDNs**).
|
||||
|
||||
### String representation of DNs
|
||||
|
||||
The string representation of a DN consists of strings representing each of its
|
||||
`RDNs` separated by commas (`,`). The [RFC4514] specification lists the RDNs
|
||||
**in reverse order** (as a result, the most specific elements, such as
|
||||
`CommonName`, are output first, and the most general, such as the
|
||||
`CountryName`, last). The expected physical order of `RDNs` within a `DN` is
|
||||
to list the most general names first.
|
||||
|
||||
Empty DNs are represented by an **empty** string.
|
||||
|
||||
**Example:** `cn=John Doe,ou=People,dc=example,dc=com`
|
||||
|
||||
### Attributes and Values
|
||||
|
||||
Each RDN is composed of one or more attribute-value pairs. An attribute-value
|
||||
pair is represented as `type=value`. The type names are not case-sensitive.
|
||||
|
||||
**Example:** `cn=John Doe`. Here `cn` (CommonName) is the attribute type and
|
||||
`John Doe` is the attribute value.
|
||||
|
||||
Relative Distinguished Names (RDNs)
|
||||
-----------------------------------
|
||||
|
||||
A Relative Distinguished Name (RDN) identifies an entry uniquely within its
|
||||
immediate superior entry. An RDN can consist of a single attribute-value pair
|
||||
or a set of multiple attribute-value pairs.
|
||||
|
||||
### Multiple Attribute-Value Pairs in an RDN
|
||||
|
||||
The string representation of multiple attribute-value pairs within a single RDN
|
||||
separates these by plus signs (`+`). In most cases each RDN consists of just a
|
||||
single attribute-value pair. The order of these pairs within an RDN is not
|
||||
significant (the ASN.1 abstract syntax designates them as a **SET** rather than
|
||||
as a **SEQUENCE**).
|
||||
|
||||
**Example:** `cn=John Doe+uid=jdoe`
|
||||
|
||||
String Representation Rules
|
||||
---------------------------
|
||||
|
||||
RFC4514 specifies detailed rules for the string representation of DNs and RDNs
|
||||
to handle special characters and ensure unambiguous parsing.
|
||||
|
||||
### Escaping Special Characters
|
||||
|
||||
Certain characters have special meaning in DN strings and must be escaped if
|
||||
they appear in an attribute value. The special characters are:
|
||||
|
||||
* Comma (`,`)
|
||||
* Plus (`+`)
|
||||
* Double Quote (`"`)
|
||||
* Backslash (`\`)
|
||||
* Less than (`<`)
|
||||
* Greater than (`>`)
|
||||
* Semicolon (`;`)
|
||||
* Leading hash (`#`)
|
||||
* Leading or trailing space
|
||||
* Optionally escaped: equals (`=`), non-leading hash(`#`)
|
||||
|
||||
These characters are escaped by preceding them with a backslash (`\`). Other
|
||||
characters **may** be escaped by encoding **each octet** of their UTF-8
|
||||
encoding as two hexadecimal digits preceded by a backslash.
|
||||
|
||||
**Example:** `cn=Doe\, John` (escaping a comma in the value)
|
||||
|
||||
### Hexadecimal Escaping
|
||||
|
||||
Any character **may** be represented separately encoding each byte of its UTF-8
|
||||
encoding with its hexadecimal value preceded by a backslash (`\`). This is
|
||||
particularly applicable for non-ASCII characters.
|
||||
|
||||
**Example:** `cn=John\20Doe` (representing a space using its hexadecimal code)
|
||||
**Example:** `cn=Doe\2c John` (escaping a comma in the value)
|
||||
**Example**: `cn=Виктор \d0\94\d1\83\d1\85\d0\be\d0\b2\d0\bd\d1\8b\d0\b9`
|
||||
(escaping each UTF-8 byte of the last name).
|
||||
|
||||
### Leading and Trailing Spaces, or a leading hash mark
|
||||
|
||||
Leading or trailing spaces and any leading hash mark in an attribute value must
|
||||
be escaped. Spaces in the middle of a value do not need to be escaped.
|
||||
|
||||
**Example:** `cn=\ John Doe\ ` (escaping leading and trailing spaces)
|
||||
|
||||
### Character Sets
|
||||
|
||||
The string must first be converted to UTF-8, prior to any escaping. In
|
||||
particular some strings in X.509 certificates may be encoded in 16-bit Unicode
|
||||
(BMP) form, as a first step, these need to be converted to UTF-8.
|
||||
|
||||
Tests should include some examples of non-ASCII, non-UTF8 strings that require
|
||||
conversion to UTF-8 as part of encoding, the output should not produce the
|
||||
`\U<xxxx>` or `\W<xxxxxxxx>` forms seen in `do_esc_char()`.
|
||||
|
||||
Attribute Type Names
|
||||
--------------------
|
||||
|
||||
The core attribute type names "c", "l", "o", "ou", etc., are specified directly in
|
||||
[RFC4519] Sections 2 and 4. These names are not case sensitive. We may wish
|
||||
to expand the set of recognised type names to include some that are new in
|
||||
[RFC4519] or in the IANA [LDAP descriptor registry].
|
||||
|
||||
Only the entries of type "A" (Attribute Type) are potentially relevant. All
|
||||
the *mainstream* attribute types are already listed in
|
||||
`crypto/objects/objects.txt` and should be already supported:
|
||||
|
||||
| Atribute Name | OID | Reference |
|
||||
|---|---|---|
|
||||
| uid | 0.9.2342.19200300.100.1.1 | [RFC4519] |
|
||||
| userId | 0.9.2342.19200300.100.1.1 | [RFC4519] |
|
||||
| mail | 0.9.2342.19200300.100.1.3 | [RFC4524] |
|
||||
| RFC822Mailbox | 0.9.2342.19200300.100.1.3 | [RFC4524] |
|
||||
| DC | 0.9.2342.19200300.100.1.25 | [RFC4519] |
|
||||
| domainComponent | 0.9.2342.19200300.100.1.25 | [RFC4519] |
|
||||
| email | 1.2.840.113549.1.9.1 | [RFC3280] |
|
||||
| emailAddress | 1.2.840.113549.1.9.1 | [RFC3280] |
|
||||
| cn | 2.5.4.3 | [RFC4519] |
|
||||
| commonName | 2.5.4.3 | [RFC4519] |
|
||||
| sn | 2.5.4.4 | [RFC4519] |
|
||||
| surname | 2.5.4.4 | [RFC4519] |
|
||||
| serialNumber | 2.5.4.5 | [RFC4519] |
|
||||
| c | 2.5.4.6 | [RFC4519] |
|
||||
| countryName | 2.5.4.6 | [RFC4519] |
|
||||
| L | 2.5.4.7 | [RFC4519] |
|
||||
| localityName | 2.5.4.7 | [RFC4519] |
|
||||
| st | 2.5.4.8 | [RFC4519] |
|
||||
| stateOrProvinceName | 2.5.4.8 | [RFC2256] |
|
||||
| street | 2.5.4.9 | [RFC4519] |
|
||||
| streetAddress | 2.5.4.9 | [RFC2256] |
|
||||
| o | 2.5.4.10 | [RFC4519] |
|
||||
| organizationName | 2.5.4.10 | [RFC4519] |
|
||||
| ou | 2.5.4.11 | [RFC4519] |
|
||||
| organizationalUnitName | 2.5.4.11 | [RFC4519] |
|
||||
| title | 2.5.4.12 | [RFC4519] |
|
||||
| description | 2.5.4.13 | [RFC4519] |
|
||||
| businessCategory | 2.5.4.15 | [RFC4519] |
|
||||
| postalAddress | 2.5.4.16 | [RFC4519] |
|
||||
| postalCode | 2.5.4.17 | [RFC4519] |
|
||||
| postOfficeBox | 2.5.4.18 | [RFC4519] |
|
||||
| physicalDeliveryOfficeName | 2.5.4.19 | [RFC4519] |
|
||||
| telephoneNumber | 2.5.4.20 | [RFC4519] |
|
||||
| name | 2.5.4.41 | [RFC4519] |
|
||||
| givenName | 2.5.4.42 | [RFC4519] |
|
||||
| initials | 2.5.4.43 | [RFC4519] |
|
||||
| generationQualifier | 2.5.4.44 | [RFC4519] |
|
||||
| pseudonym | 2.5.4.65 | [RFC3280] |
|
||||
|
||||
When an attribute type OID is not one of the known values it is represented by
|
||||
its dotted-decimal form, and the attribute value must then be encoded with a
|
||||
leading `#` character followed by the hexadecimal encoding of the DER encoded
|
||||
value, see section 2.4 of [RFC4514]. This form may also be used when the value
|
||||
has no suitable string representation.
|
||||
|
||||
I have not checked whether we implement case-insensitive string comparison for
|
||||
any of the attributes for which this is expected in LDAP. In certificates I do
|
||||
not expect to find case-variants of RDNs that need to be considered equivalent
|
||||
when comparing subject and issuer DNs.
|
||||
|
||||
Parsing of Names
|
||||
----------------
|
||||
|
||||
The parsing of X.509 directory names (e.g. the `-subj` option of the x509
|
||||
command) is performed by the `parse_name()` function in `apps/lib/apps.c`.
|
||||
This currently assumes that the output format is that of the legacy
|
||||
`X509_NAME_oneline()` function. That format always starts with a `/`
|
||||
character. A single slash by itself represents an **empty** RDN sequence.
|
||||
|
||||
The `parse_name()` function is used in the `ca, cmp, req, storeutl,` and
|
||||
`x509` commands.
|
||||
|
||||
If or when we switch to output the [RFC4514] format, we need to also accept
|
||||
it on input, therefore, `parse_name()` needs to be updated to treat strings
|
||||
starting with a `/` as legacy online forms, and other strings as the RFC4514
|
||||
format.
|
||||
|
||||
Parsing of [RFC4514] syntax is covered in Section 3. Currently, our parser
|
||||
does not support RDNs with ad hoc dott-decimal OIDs, only known named attribute
|
||||
types are supported. We should consider allowing explicit dotted decimal OIDs
|
||||
and using `X509_NAME_add_entry_by_OBJ()` to add these.
|
||||
|
||||
Names in the configuration file
|
||||
-------------------------------
|
||||
|
||||
In configuration files, we represent directory names as a "section" with one
|
||||
"attr = value" line per RDN component. Relevant documentation is in
|
||||
`x509v3_config(3)` and `openssl-req(1`). For example:
|
||||
|
||||
subjectAltName = dirName:dir_sect
|
||||
[dir_sect]
|
||||
C = UK
|
||||
O = My Organization
|
||||
OU = My Unit
|
||||
CN = My Name
|
||||
|
||||
So in the configuration file, we only have to handle the syntax of the
|
||||
individual value elements, the DN as a whole is not parsed. The `string_mask`
|
||||
affects the encoding of the various strings, and defaults to `utf8only` (other
|
||||
values are not recommended).
|
||||
|
||||
Only the `ca` and `req` commands process the string mask, though user
|
||||
applications can do the same by calling `ASN1_STRING_set_default_mask_asc()`,
|
||||
which is an undocumented and non-thread-safe function. The comments above the
|
||||
code say:
|
||||
|
||||
/*-
|
||||
* This function sets the default to various "flavours" of configuration.
|
||||
* based on an ASCII string. Currently this is:
|
||||
* MASK:XXXX : a numerical mask value.
|
||||
* default : use Printable, IA5, T61, BMP, and UTF8 string types
|
||||
* nombstr : any string type except variable-sized BMPStrings or UTF8Strings
|
||||
* pkix : PKIX recommendation in RFC 5280
|
||||
* utf8only : this is the default, use UTF8Strings
|
||||
*/
|
||||
|
||||
Bottom-line is that for most users the DN components in the configuration file
|
||||
are already UTF8-friendly, the only thing to check is whether we support the
|
||||
desired set of attribute type names, both in the configuration file and while
|
||||
parsing a string representation of a complete DN.
|
||||
|
||||
<!-- Links -->
|
||||
|
||||
[RFC2253]:
|
||||
<https://www.rfc-editor.org/rfc/rfc2253.html>
|
||||
|
||||
[RFC2256]:
|
||||
<https://www.rfc-editor.org/rfc/rfc2256.html>
|
||||
|
||||
[RFC3280]:
|
||||
<https://www.rfc-editor.org/rfc/rfc3280.html>
|
||||
|
||||
[RFC4514]:
|
||||
<https://www.rfc-editor.org/rfc/rfc4514.html>
|
||||
|
||||
[RFC4519]:
|
||||
<https://www.rfc-editor.org/rfc/rfc4519.html>
|
||||
|
||||
[RFC4524]:
|
||||
<https://www.rfc-editor.org/rfc/rfc4524.html>
|
||||
|
||||
[LDAP descriptor registry]:
|
||||
<https://www.iana.org/assignments/ldap-parameters/ldap-parameters.xhtml#ldap-parameters-3>
|
||||
Loading…
Reference in New Issue