PR#9: Updates to Matching and Mapping Certificates desing page - SSSD/docs

SSSD / docs

#9 Updates to Matching and Mapping Certificates desing page

Merged 7 years ago by sbose. Opened 7 years ago by sbose.

SSSD/ sbose/docs edit into master

Updates

Sumit Bose • 7 years ago

4032299

design_pages/matching_and_mapping_certificates.rst

file modified

+275 -262

		`@@ -79,12 +79,14 @@`
		`the issuer but will match all issuers. On the other hand there might be`
		`issuers where the certificates needs special attention and more than the`
		`minimal requirement are needed. To make sure that for this issuer there`
		`- is no fallback to the catch-all rules an extra issuer attribute would make`
		`- sure that for the given issuer only those rules will be applied and there`
		`- is no fallback to other rules.`
		`+ is no fallback to the catch-all rules the rules will be processed by priority`
		`+ and if a rule with a given priority will match no rules with lower priority`
		`+ will be consulted. To be consistent with other priorities used in IPA a low`
		`+ numerical value corresponds to a high priority while a higher numerical value`
		`+ will lead to a lower priority. A missing value stands for the lowest priority.`

		`As a result there are four items which build certificate authentication rule,`
		`- the mapping and matching rule, a domain list and the issuer. All items are`
		`+ the mapping and matching rule, a domain list and the priority. All items are`
		`optional. If there is no rule at all the current behavior is used as default.`

		`An upcoming use-case might require and extension of the current mapping and`
		`@@ -99,10 +101,7 @@`
		`search filters for its own usages to server matching users on remote LDAP`
		`servers or in the local cache. Additionally it will provide an interface to`
		`check if a given user object will match according to the rules which can`
		`- be use by the PKINIT matching plugin. To most suitable representation for`
		- the user object (``LDAPMessage``, ``krb5_db_entry`` or something else) must still
		- be determined. To initialize the library a list of ``LDAPMessage`` objects can
		`- be passed to an initialization function which will return an opaque context.`
		`+ be use by the PKINIT matching plugin.`

		`Matching`
		`^^^^^^^^`
		`@@ -120,20 +119,20 @@`

		And can be grouped together with a prefixed ``&&`` (and) or ``\|\|`` (or)
		operator (``&&`` is the default). If multiple rules are given they are
		`- iterated with the order in the config file as long as a rule matches`
		`+ iterated with the order in the configuration file as long as a rule matches`
		`exactly one certificate.`

		- `Question: MIT Kerberos use case-sensitive matching and POSIX Extended Regular Expression syntax, shall we do the same?`
		+ While ``<SUBJECT>`` and ``<ISSUER>`` are (IMO) already quite flexible I can
		`+ see some potential extensions for the other components.`

		- While ``<SUBJECT>`` and ``<ISSUER>`` are (IMO) already quite flexible I can see some potential extensions for the other components.
		`-`
		- ``<EKU>`` and ``<KU>`` in MIT Kerberos only accept certain string
		`- values related to some allowed values in those field as defined in`
		+ ``<EKU>`` and ``<KU>`` in MIT Kerberos only accept certain string values
		`+ related to some allowed values in those field as defined in`
		`<https://www.ietf.org/rfc/rfc3280.txt>`_. The selection is basically
		`determined by what is supported on server side of the pkinit plugin of MIT`
		`Kerberos. Since we plan to extend pkinit and support local authentication`
		- without pkinit as well I would suggest to allow ``OID`` strings for those
		- components as well (the comparison is done on the ``OID`` level nonetheless).
		+ without pkinit as well I would suggest to allow ``OID`` strings or an integer
		+ value in the ``<KU>`` case as well (the comparison is done on the ``OID``
		`+ level nonetheless).`

		The ``<SAN>`` component in MIT Kerberos only checks the
		``otherName`` SAN component for the ``id-pkinit-san OID``
		`@@ -141,102 +140,13 @@`
		or the ``szOID_NT_PRINCIPAL_NAME`` ``OID`` as mentioned in
		`<https://support.microsoft.com/en-us/kb/287547>`_. While this is sufficient
		`for the default pkinit user case of MIT Kerberos I would suggest to extend`
		- this component by allowing to specific an ``OID`` with ``<SAN:O.I.D>``
		`+ this component by allowing to specific the other SAN component, e.g.`
		+ ``<SAN:rfc822Name>``.

		The prefix tag for this type of matching rules would be ``KRB5:`` and I
		`would suggest to take this a default, i.e. if the prefix tag is missing`
		``KRB5:`` will be assumed.

		`- Matching - alternative RFC4523 syntax`
		`- ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^`
		- Based on the X.509 ``CertificateAssertion`` syntax `RFC 4523 <https://www.ietf.org/rfc/rfc4523.txt>`_
		`- introduces Generic String Encoding`
		- Rules (``GSER``)-based (`RFC3641 <https://www.ietf.org/rfc/rfc3641.txt>`_)
		- and `RFC 3642 <https://www.ietf.org/rfc/rfc3642.txt>`_ syntax to write
		- ``CertificateAssertions`` which can be used to match certificates as well.
		`-`
		`- A matching rule for an issuer would look like::`
		`-`
		`- { issuer "cn=CA,dc=example,dc=com" }`
		`-`
		- There is an identifier for ``keyUsage`` as well::
		`-`
		`- { issuer "cn=CA,dc=example,dc=com" , keyUsage { digitalSignature , keyEncipherment }`
		`-`
		- But it looks like there is none specific for the ``extendedKeyUsage`` which
		`- is important to separate certificate e.g. for email signing and for login`
		- purposes. I think even ``nameConstraints`` cannot be use here because according
		- to X.509 "``nameConstraints`` matches if the subject names ..." which only
		`- include the subject and the subject alternative names (please let me know`
		`- if there is a standardized way to add assertions for extensions like the`
		- ``extendedKeyUsage``).
		`-`
		- Besides ``extendedKeyUsage`` there are other components in the certificate
		`- where we want to add matching rules in the future which are currently`
		- not handled by ``RFC4523``. E.g. 'Authority Information Access' (see
		- `RFC5280 section 4.2.2.1 <https://tools.ietf.org/rfc/rfc5280.txt>`_]
		- where information about ``CRLs`` or ``OCSP`` responders are stored. With
		- this we would be able to only select certificates which have an ``OCSP``
		- responder defined or where we known that the ``CRL`` is updated regularly.
		`-`
		`- Although it would be possible to add new assertion for our usage seamlessly`
		`- I think it would not be a good idea to do this without making sure that`
		- they will be added to any new versions of ``RFC4523``. I currently have no idea
		`- how easy or hard this would be and how this would limit our flexibility`
		`- to react on request from users and customers.`
		`-`
		`- To restrict the matching not only to a single certificate but to a group`
		`- of certificates based on the subject (owner) name constraints as defined`
		- in `RFC3280 section 4.2.1.11 <https://tools.ietf.org/html/rfc3280.html#section-4.2.1.11>`_
		`- can be used. The constraints are applied to the subject name and subject`
		`- alternative names attributes in the certificate and consist of a list of`
		- allowed names (``permittedSubtrees``) and rejected names (``excludedSubtrees``). For
		`- directory names (the subject name and the related SAN attribute) an area in`
		`- the directory tree can be specified where the names should match. E.g. to`
		`- match all subject names from the 'research' department but not from`
		`- sub-departments of 'research'::`
		`-`
		`- { permittedSubtrees { ( base "CN=research,DC=example,DC=com" , minimum 1, maximum 1 ) } }`
		`-`
		`- can be used. To allow everything but the 'no_access' subtree::`
		`-`
		`- { excludedSubtrees { ( base "CN=no_access,DC=example,DC=com" ) } }`
		`-`
		`- an be used, 'minimum' and 'maximum' are not needed here because the default`
		`- for 'minimum' is '0' and a missing 'maximum' specifies the whole subtree.`
		`-`
		`- Compared the regular-expressions this syntax makes it easy to reject`
		`- specific types of names. But it also requires that a full base is specified`
		- and only a simple ``key_string``. This is of course more safe but it has
		`- to be noted that the matching rules are only applied on valid and verified`
		`- certificates. Since CA certificates can contain name constraints as well and`
		- `with p11-kit it is even possible to staple those extensions <http://nmav.gnutls.org/2016/06/restricting-scope-of-ca-certificates.html>`_
		`- it would be possible to reject certificates system-wide already during`
		`- the verification.`
		`-`
		- Based on this I would suggest to reserve the prefix tag ``RFC4523:``
		`- for this type of matching rule but postpone the implementation.`
		`-`
		`- Issuer specific matching`
		`- ^^^^^^^^^^^^^^^^^^^^^^^^`
		`- Although the MIT Kerberos rules allow to select the issuer of a certificate`
		`- there are use cases where a more specific selection is needed. E.g. if`
		`- there are some default matching rules for all issuers and some other issuer`
		`- specific rules where the default rules should not apply. To make this`
		- possible with the above scheme the default rules must have an ``<ISSUER>``
		`- clause which matches all but the issuer with the specific rules. Writing`
		`- regular-expressions to not match a specific string or a list of strings`
		`- is at least error-prone if not impossible.`
		`-`
		`- To make it easier to define issuer specific rules and default rules at the`
		`- same time and optional issuer string can be added to the rule to indicate`
		`- that for the given issuer only those rules should be considered. Given the`
		`- use-case I think it is acceptable to require that the full issuer must be`
		`- specified here in LDAP order (see below) and case-sensitive matching is used.`
		`-`
		`- How the issuer string is linked to the matching rules depends on the storage`
		- (LDAP or ``sssd.conf``, see below for details).
		`-`
		`Mapping`
		`^^^^^^^`
		`Since different certificates, e.g. issued by different CAs, might have`
		`@@ -244,14 +154,10 @@`
		`than 1 mapping rule. A single mapping rule without a matching rule might`
		`be used as default/catch-all rule in this case.`

		`- If multiple rules matches the derived LDAP filter components can be grouped`
		- with the or-operator ``\|``.
		`-`
		`With trusted AD forests the mapped users might come from trusted domains as`
		`well. To avoid searching in every single domain a list of expected domains`
		`can be added to each mapping rule. If the list is empty the local domain`
		`- is assumed by default. An option might be added to switch the behavior to`
		`- search all domains if the list is empty.`
		`+ is assumed by default.`

		`Similar to Active Directory we will require a dedicated LDAP attribute in`
		`the user entry (anchor) to map the certificate to the user entry. Mapping`
		`@@ -274,7 +180,7 @@`
		`user entry as well. OTP tokens are managed in separate objects but contain`
		`the DN of the user as a unique reference. In all cases the removal of a`
		`single attribute will disable/remove a specific authentication method for`
		`- a user.`
		`+ a specific user.`

		`Finally, since mapping is about searching a user entry in the LDAP tree`
		`the dedicated attribute can be indexed to speed up the searches and help`
		`@@ -320,36 +226,13 @@`
		`on your own. As can be seen AD can translate the deprecated`
		OID `1.2.840.113549.1.9.1
		<http://www.oid-info.com/get/1.2.840.113549.1.9.1>`_ and uses ``E`` as
		- NSS. But the OID `0.9.2342.19200300.100.1.1 <http://www.oid-info.com/get/0.9.2342.19200300.100.1.1>`_ which is explicitly mentioned in RFC4514 is
		+ NSS. But the OID `0.9.2342.19200300.100.1.1 <http://www.oid-info.com/get/0.9.2342.19200300.100.1.1>`_
		`+ which is explicitly mentioned in RFC4514 is`
		`not translated as UID but the plain OID syntax is used (my guess it that`
		`Microsoft tries to be compatible with "older" versions because the UID`
		`was added in RFC2253 from 1997 but was not present in the RFC1779 from`
		`1995 and RFC1485 from 1993).`

		- This leads us to mapping rules like ``<ALT-SEC-ID-I-S:ldapAttributeName>``
		`- which would try in a best effort to produce the exact attribute value`
		`- AD is using. This should work reliable with standard RDN types (see`
		- above). I think an optional ``ldapAttributeName`` is useful here so that
		`- the same mapping rule can be used with different LDAP servers (e.g. IPA)`
		`- where user-specific mapping attributes are used with the same content but`
		`- a different attribute name.`
		`-`
		`- According to the blob post describing altSecurityIdentities some other additional mapping rules might be useful too. This will give us`
		`-`
		- * ``<ALT-SEC-ID-I-S:ldapAttributeName>``
		- * ``<ALT-SEC-ID-S:ldapAttributeName>``
		- * ``<ALT-SEC-ID-SKI:ldapAttributeName>``
		- * ``<ALT-SEC-ID-I-SR:ldapAttributeName>``
		- * ``<ALT-SEC-ID-SHA1-PUBKEY:ldapAttributeName>``
		- * ``<ALT-SEC-ID-RFC822:ldapAttributeName>``
		- * ``<ALT-SEC-ID-TP-PUBKEY:ldapAttribute>`` (?)
		`-`
		- (The last is mentioned in `MS-DVRE section 2.3.3. <https://msdn.microsoft.com/en-us/library/dn408946.aspx>`_
		`- but seems to be specific for joining devices in Azure)`
		`-`
		`- So far I didn't found a AD tool which creates to other mappings, if you`
		`- know one, please let me know.`
		`-`
		Besides ``altSecurityIdentities`` AD uses the SAN with the
		``szOID_NT_PRINCIPAL_NAME`` OID to map users. It has to be noted that AD
		does not only look at the ``userPrincipalName`` LDAP attribute to map the
		`@@ -357,18 +240,13 @@`
		``samAccountName@AD.REALM`` as well. Interestingly a ``Kerberos:user@AD.REALM``
		entry in ``altSecurityIdentities`` did not work in my tests and AD denied
		`login. So what AD does currently matches how SSSD tried to resolve a`
		`- fully-qualified name against AD. I would suggest a mapping rule like`
		- ``<NT_PRINCIPAL_NAME:ldapAttributeName>``
		`- to allow the search the user with the SAN value. When the`
		`- backend is talking to AD and the principal cannot be found the`
		- fallback search with the ``samAccountName`` LDAP is used. Since
		`+ fully-qualified name against AD.`
		`MS-PKCS Appendix A <https://msdn.microsoft.com/en-us/library/cc238488.aspx>`_
		`explicitly says that id-pkinit-san is ignored it does not have to be`
		`included for this mapping rule.`

		`Using the Certificate as an anchor`
		`^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^`
		`-`
		`For IPA and other generic LDAP servers an LDAP attribute like`
		e.g. ``userCertificate`` is a good anchor as well and is currently already
		`used to allow local authentication with a Smartcard. Since it is the`
		`@@ -382,8 +260,260 @@`
		`available, or mapping rules from above should be used if pkinit is required`
		`with AD.`

		`+ Some notes about DNs`
		`+ ^^^^^^^^^^^^^^^^^^^^`
		`+ The X.500 family of standards define names as "SEQUENCE OF`
		`+ RelativeDistinguishedName" where the sequence is "starting with the root and`
		`+ ending with the object being named" (see X.501 section 9.2 for details). On`
		`+ the other hand RFC4514 section 2.1 says "Otherwise, the output consists of`
		+ the string encoding of each ``RelativeDistinguishedName`` in the ``RDNSequence``
		`+ (according to Section 2.2), starting with the last element of the sequence`
		`+ and moving backwards toward the first." This means that the ASN.1 encoded`
		`+ issuer and subject DN from the X.509 certificate can be either displayed`
		`+ as string in the`
		`+`
		+ * X.500 order: ``DC=com,DC=example,CN=users,CN=Certuser``
		`+`
		`+ or in the`
		`+`
		+ * LDAP order: ``CN=Certuser,CN=Users,DC=example,DC=com``
		`+`
		`+ As a consequence different tools will use a different order when printing`
		`+ the issuer and subject DN. While NSS's certutil will use the LDAP order,`
		`+ 'openssl x509' and gnutls's certtool will use the X.500 order (the latter`
		+ might change due to `<https://gitlab.com/gnutls/gnutls/issues/111>`_).
		`+`
		`+ This makes it important to specific the order which is used by SSSD`
		`+ for mapping and matching. I would prefer the LDAP order here. E.g. by`
		`+ default the AD CA uses the DN of the users entry in AD as subject in`
		+ the issues certificate. So a matching rule like ``<SUBJECT:dn>`` could
		`+ tell SSSD to directly search the user based on its DN (which BTW is the`
		`+ original intention of the subject field in the certificate, only that the`
		`+ DN should be looked up in a more general DAP as defined by X.500 and not`
		`+ in the lightweight version called LDAP)`
		`+`
		`+ Another issue is the limited set of attribute names/types required by`
		`+ the RFCs (see section 4.1.2.4 of RFC 3280 and section 3 of RFC 4514). If`
		+ e.g. the deprecated OID `1.2.840.113549.1.9.1 <http://www.oid-info.com/get/1.2.840.113549.1.9.1>`_
		`+ is used all tools are able to identify it as an`
		+ email address but OpenSSL displays it as ``emailAddress=user@example.com``,
		+ certtool as ``EMAIL=user@example.com`` and certutil as ``E=user@example.com``. So
		`+ matching rules should try to avoid attribute names or only the ones from`
		+ `RFC 4514 <https://www.ietf.org/rfc/rfc4514.txt>`_:
		`+`
		+ * ``CN commonName (2.5.4.3)``
		+ * ``L localityName (2.5.4.7)``
		+ * ``ST stateOrProvinceName (2.5.4.8)``
		+ * ``O organizationName (2.5.4.10)``
		+ * ``OU organizationalUnitName (2.5.4.11)``
		+ * ``C countryName (2.5.4.6)``
		+ * ``STREET streetAddress (2.5.4.9)``
		+ * ``DC domainComponent (0.9.2342.19200300.100.1.25)``
		+ * ``UID userId (0.9.2342.19200300.100.1.1)``
		`+`
		`+`
		`+ Mapping with LDAP search filter syntax`
		`+ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^`
		`+ Given the different requirements discussed above and since the goal of the`
		`+ mapping rules is to create a LDAP search filter a filter template would be a`
		`+ direct and flexible way to define mapping rules::`
		`+`
		`+ (&(someAttr={certContent})(someOtherAttr={otherCertContent}))`
		`+`
		`+ The syntax might be a bit verbose`
		`+ but LDAP search filters are well documented and administrators`
		`+ should already have a basic understanding.`
		`+`
		`+ For the templates in curly braces Python-style formatting strings are used.`
		`+ Depending on the type of certificate data a sub-component can be specified`
		`+ with a '.' or a conversion option can be given with a '!', e.g.:`
		`+`
		`+ * {subject_nt_principal.short_name}, get the name part before the '@' sign`
		`+ * {issuer_dn!ad_x500}, get the issuer name string in x500 ordering and`
		`+ translate the attributes names as AD would do`
		`+`
		+ A detailed list of templates can be found in the `sss-certmap man page
		+ <https://www.mankier.com/5/sss-certmap>`_.
		`+`
		`+ Examples`
		`+ ^^^^^^^^`
		`+ The following example are for the FreeIPA use case and use the ''ipa`
		`+ certmaprule-\*'' utilities which are described on the related`
		+ `IPA design page <http://www.freeipa.org/page/V4/Certificate_Identity_Mapping>`_.
		`+`
		`+ All certificates from issuer CN=CA,dc=ISSUER,DC=COM with the extended key`
		`+ usage 'ClientAuthentication' shall be mapped to a user by looking up with the`
		`+ whole certificate, i.e. the certificate must be stored in the user entry::`
		`+`
		`+ ipa certmaprule-add testrule \`
		`+ --matchrule='<ISSUER>^CN=CA,dc=ISSUER,DC=COM$<EKU>clientAuth' \`
		`+ --maprule='(userCertificate;binary={cert!bin})'`
		`+ --priority=42`
		`+`
		`+ All certificates from issuer CN=CA,dc=ISSUER,DC=COM with the extended key`
		`+ usage 'ClientAuthentication' shall be mapped to an AD user by looking up the`
		`+ 'altSecurityIdentities' attribute in the AD domain ad.dom.com::`
		`+`
		`+ ipa certmaprule-add testrule \`
		`+ --matchrule='<ISSUER>^CN=CA,dc=ISSUER,DC=COM$<EKU>clientAuth' \`
		`+ --maprule='(altSecurityIdentities=X509:<I>{issuer_dn!ad_x500}<S>{subject_dn!ad_x500})' \`
		`+ --domain=ad.dom.com \`
		`+ --priority=42`
		`+`
		`+ All certificates from issuer CN=CA,dc=ISSUER,DC=COM with the extended key`
		`+ usage 'ClientAuthentication' shall be mapped to an IPA user by looking up the`
		`+ 'ipaCertMapData' attribute in the local IPA domain::`
		`+`
		`+ ipa certmaprule-add testrule \`
		`+ --matchrule='<ISSUER>^CN=CA,dc=ISSUER,DC=COM$<EKU>clientAuth' \`
		`+ --maprule='(ipaCertMapData=X509:<I>{issuer_dn}<S>{subject_dn})' \`
		`+ --priority=42`
		`+`
		`+ All certificates from issuer CN=AD-CA,dc=ISSUER,DC=COM with the extended key`
		`+ usage 'ClientAuthentication' which have an AD NT principal from the AD.DOM`
		`+ realm in the SANs shall be mapped to an AD user by looking up the`
		`+ by principal or name in the domain ad.dom::`
		`+`
		`+ ipa certmaprule-add testrule \`
		`+ --matchrule='<ISSUER>^CN=AD-CA,dc=ISSUER,DC=COM$<EKU>clientAuth<SAN:ntPrincipalName>*@AD.DOM' \`
		`+ --maprule='(\|(userPrincipal={subject_nt_principal})(samAccountName={subject_nt_principal.short_name}))' \`
		`+ --domain=ad.dom \`
		`+ --priority=42`
		`+`
		`+ Configuration changes`
		`+ ---------------------`
		`+ No changes are needed on the client. New rules are picked up after some time or`
		`+ after a restart of SSSD.`
		`+`
		`+ How To Test`
		`+ -----------`
		+ The easiest way to test the mapping rules is the new ``ListByCertificate``
		`+ DBus method offered by SSSD's Infopipe::`
		`+`
		`+ dbus-send --system --print-reply --dest=org.freedesktop.sssd.infopipe \`
		`+ /org/freedesktop/sssd/infopipe/Users \`
		`+ org.freedesktop.sssd.infopipe.Users.ListByCertificate \`
		`+ string:"$(cat cert.pem)" uint32:10`
		`+ method return time=1491995602.233163 sender=:1.616 -> destination=:1.757 serial=5 reply_serial=2`
		`+ array [`
		`+ object path "/org/freedesktop/sssd/infopipe/Users/ad_2edevel/1367242755"`
		`+ object path "/org/freedesktop/sssd/infopipe/Users/ad_2edevel/1367242776"`
		`+ ]`
		`+`
		`+`
		`+ How To Debug`
		`+ ------------`
		`+ Debug messages of the certificate mapping library are available in the SSSD`
		`+ domain log file and in the krb5kdc.log if the library is used with IPA's`
		`+ Kerberos certauth plugin.`
		`+`
		`+ Authors`
		`+ -------`
		`+ * Sumit Bose <sbose@redhat.com>`
		`+`
		`+`
		`+ Additional information for reference`
		`+ ------------------------------------`
		`+`
		`+ Matching - alternative RFC4523 syntax`
		`+ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^`
		`+ *(The follow section was used to discuss an alternative to the KRB5 matching`
		`+ rules. It was agreed that KRB5 rules will be used for a start.)*`
		+ Based on the X.509 ``CertificateAssertion`` syntax `RFC 4523 <https://www.ietf.org/rfc/rfc4523.txt>`_
		`+ introduces Generic String Encoding`
		+ Rules (``GSER``)-based (`RFC3641 <https://www.ietf.org/rfc/rfc3641.txt>`_)
		+ and `RFC 3642 <https://www.ietf.org/rfc/rfc3642.txt>`_ syntax to write
		+ ``CertificateAssertions`` which can be used to match certificates as well.
		`+`
		`+ A matching rule for an issuer would look like::`
		`+`
		`+ { issuer "cn=CA,dc=example,dc=com" }`
		`+`
		+ There is an identifier for ``keyUsage`` as well::
		`+`
		`+ { issuer "cn=CA,dc=example,dc=com" , keyUsage { digitalSignature , keyEncipherment }`
		`+`
		+ But it looks like there is none specific for the ``extendedKeyUsage`` which
		`+ is important to separate certificate e.g. for email signing and for login`
		+ purposes. I think even ``nameConstraints`` cannot be use here because according
		+ to X.509 "``nameConstraints`` matches if the subject names ..." which only
		`+ include the subject and the subject alternative names (please let me know`
		`+ if there is a standardized way to add assertions for extensions like the`
		+ ``extendedKeyUsage``).
		`+`
		+ Besides ``extendedKeyUsage`` there are other components in the certificate
		`+ where we want to add matching rules in the future which are currently`
		+ not handled by ``RFC4523``. E.g. 'Authority Information Access' (see
		+ `RFC5280 section 4.2.2.1 <https://tools.ietf.org/rfc/rfc5280.txt>`_]
		+ where information about ``CRLs`` or ``OCSP`` responders are stored. With
		+ this we would be able to only select certificates which have an ``OCSP``
		+ responder defined or where we known that the ``CRL`` is updated regularly.
		`+`
		`+ Although it would be possible to add new assertion for our usage seamlessly`
		`+ I think it would not be a good idea to do this without making sure that`
		+ they will be added to any new versions of ``RFC4523``. I currently have no idea
		`+ how easy or hard this would be and how this would limit our flexibility`
		`+ to react on request from users and customers.`
		`+`
		`+ To restrict the matching not only to a single certificate but to a group`
		`+ of certificates based on the subject (owner) name constraints as defined`
		+ in `RFC3280 section 4.2.1.11 <https://tools.ietf.org/html/rfc3280.html#section-4.2.1.11>`_
		`+ can be used. The constraints are applied to the subject name and subject`
		`+ alternative names attributes in the certificate and consist of a list of`
		+ allowed names (``permittedSubtrees``) and rejected names (``excludedSubtrees``). For
		`+ directory names (the subject name and the related SAN attribute) an area in`
		`+ the directory tree can be specified where the names should match. E.g. to`
		`+ match all subject names from the 'research' department but not from`
		`+ sub-departments of 'research'::`
		`+`
		`+ { permittedSubtrees { ( base "CN=research,DC=example,DC=com" , minimum 1, maximum 1 ) } }`
		`+`
		`+ can be used. To allow everything but the 'no_access' subtree::`
		`+`
		`+ { excludedSubtrees { ( base "CN=no_access,DC=example,DC=com" ) } }`
		`+`
		`+ an be used, 'minimum' and 'maximum' are not needed here because the default`
		`+ for 'minimum' is '0' and a missing 'maximum' specifies the whole subtree.`
		`+`
		`+ Compared the regular-expressions this syntax makes it easy to reject`
		`+ specific types of names. But it also requires that a full base is specified`
		+ and only a simple ``key_string``. This is of course more safe but it has
		`+ to be noted that the matching rules are only applied on valid and verified`
		`+ certificates. Since CA certificates can contain name constraints as well and`
		+ `with p11-kit it is even possible to staple those extensions <http://nmav.gnutls.org/2016/06/restricting-scope-of-ca-certificates.html>`_
		`+ it would be possible to reject certificates system-wide already during`
		`+ the verification.`
		`+`
		+ Based on this I would suggest to reserve the prefix tag ``RFC4523:``
		`+ for this type of matching rule but postpone the implementation.`
		`+`
		`+ Issuer specific matching`
		`+ ^^^^^^^^^^^^^^^^^^^^^^^^`
		`+ *(The following section was used to discuss an alternative to priorities but`
		`+ it was decided that priorities are more flexible)*`
		`+ Although the MIT Kerberos rules allow to select the issuer of a certificate`
		`+ there are use cases where a more specific selection is needed. E.g. if`
		`+ there are some default matching rules for all issuers and some other issuer`
		`+ specific rules where the default rules should not apply. To make this`
		+ possible with the above scheme the default rules must have an ``<ISSUER>``
		`+ clause which matches all but the issuer with the specific rules. Writing`
		`+ regular-expressions to not match a specific string or a list of strings`
		`+ is at least error-prone if not impossible.`
		`+`
		`+ To make it easier to define issuer specific rules and default rules at the`
		`+ same time and optional issuer string can be added to the rule to indicate`
		`+ that for the given issuer only those rules should be considered. Given the`
		`+ use-case I think it is acceptable to require that the full issuer must be`
		`+ specified here in LDAP order (see below) and case-sensitive matching is used.`
		`+`
		`+ How the issuer string is linked to the matching rules depends on the storage`
		+ (LDAP or ``sssd.conf``, see below for details).
		`+`
		`Future consideration`
		`^^^^^^^^^^^^^^^^^^^^`
		`+ *(The following section was used to discuss an alternative syntax for mapping`
		`+ rules. It was decided that LDAP search filter syntax is more flexible and`
		`+ better suited for a start)*`
		A mapping rule can use a similar syntax like the matching rule where the LDAP attribute can be added with a ``:``, e.g:

		* ``<ISSUER:O.I.D.:ldapAttributeName:*>``
		`@@ -442,91 +572,9 @@`

		`Maybe even search-and-replace are not sufficient for all cases and something like embedded lua scripts are needed. But since certificate mapping is about access control and authorization it should be always considered if adding a new attribute to the users LDAP entry which makes mapping easy and straight-forward wouldn't be the better solution.`

		`- Some notes about DNs`
		`- ^^^^^^^^^^^^^^^^^^^^`
		`- The X.500 family of standards define names as "SEQUENCE OF`
		`- RelativeDistinguishedName" where the sequence is "starting with the root and`
		`- ending with the object being named" (see X.501 section 9.2 for details). On`
		`- the other hand RFC4514 section 2.1 says "Otherwise, the output consists of`
		- the string encoding of each ``RelativeDistinguishedName`` in the ``RDNSequence``
		`- (according to Section 2.2), starting with the last element of the sequence`
		`- and moving backwards toward the first." This means that the ASN.1 encoded`
		`- issuer and subject DN from the X.509 certificate can be either displayed`
		`- as string in the`
		`-`
		- * X.500 order: ``DC=com,DC=example,CN=users,CN=Certuser``
		`-`
		`- or in the`
		`-`
		- * LDAP order: ``CN=Certuser,CN=Users,DC=example,DC=com``
		`-`
		`- As a consequence different tools will use a different order when printing`
		`- the issuer and subject DN. While NSS's certutil will use the LDAP order,`
		`- 'openssl x509' and gnutls's certtool will use the X.500 order (the latter`
		- might change due to `<https://gitlab.com/gnutls/gnutls/issues/111>`_).
		`-`
		`- This makes it important to specific the order which is used by SSSD`
		`- for mapping and matching. I would prefer the LDAP order here. E.g. by`
		`- default the AD CA uses the DN of the users entry in AD as subject in`
		- the issues certificate. So a matching rule like ``<SUBJECT:dn>`` could
		`- tell SSSD to directly search the user based on its DN (which BTW is the`
		`- original intention of the subject field in the certificate, only that the`
		`- DN should be looked up in a more general DAP as defined by X.500 and not`
		`- in the lightweight version called LDAP)`
		`-`
		`- Another issue is the limited set of attribute names/types required by`
		`- the RFCs (see section 4.1.2.4 of RFC 3280 and section 3 of RFC 4514). If`
		- e.g. the deprecated OID `1.2.840.113549.1.9.1 <http://www.oid-info.com/get/1.2.840.113549.1.9.1>`_
		`- is used all tools are able to identify it as an`
		- email address but OpenSSL displays it as ``emailAddress=user@example.com``,
		- certtool as ``EMAIL=user@example.com`` and certutil as ``E=user@example.com``. So
		`- matching rules should try to avoid attribute names or only the ones from`
		- `RFC 4514 <https://www.ietf.org/rfc/rfc4514.txt>`_:
		`-`
		- * ``CN commonName (2.5.4.3)``
		- * ``L localityName (2.5.4.7)``
		- * ``ST stateOrProvinceName (2.5.4.8)``
		- * ``O organizationName (2.5.4.10)``
		- * ``OU organizationalUnitName (2.5.4.11)``
		- * ``C countryName (2.5.4.6)``
		- * ``STREET streetAddress (2.5.4.9)``
		- * ``DC domainComponent (0.9.2342.19200300.100.1.25)``
		- * ``UID userId (0.9.2342.19200300.100.1.1)``
		`-`
		`- About restricting or enforcing the mapping an matching any further`
		`- ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^`
		`- The goal of the matching rules in MIT Kerberos is to select a single`
		`- certificate from a Smartcard which will then be used for PKINIT. Since`
		`- we already plan to enhance SSSD to support multiple certificates on a`
		`- Smartcard and if needed prompt the user which one to use for login we`
		`- should not enforce that the matching rules should return only a single`
		`- certificate or nothing.`
		`-`
		`- Similar we plan to enhance SSSD to use the same certificate to log in with`
		`- different user identities, e.g. as a user with standard privileges or as`
		`- a user with administrator privileges. So it can make sense that multiple`
		`- mapping rules apply to the same certificate and the related LDAP search`
		`- filter components are or-ed together.`
		`-`
		`- In many cases the login program will first ask for a user name which will`
		`- help to restrict the number of suitable certificates even further and the`
		`- mapping rules are only needed to check if the certificate belongs to the`
		`- user trying to log in.`
		`-`
		`- But GDM has a feature where GDM will detect when a Smartcard is inserted`
		`- and call PAM without a user name. In this case SSSD has to determine the`
		`- user name based on the certificates found on the Smartcard. If in this`
		`- case multiple valid certificates are on the card and the mapping rules will`
		`- return multiple users for each certificate GDM has to display a quite long`
		`- selection of certificate-user pairs the user has to choose from.`
		`-`
		`- So it should be underlined in the documentation that the matching and mapping`
		`- rules should be detailed and specific so that for the given environment`
		`- they help to avoid cases where the user is prompted to select a certificate`
		`- (or user name in the GDM case) when trying to log in.`
		`-`
		`Storing matching and mapping configuration`
		`^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^`
		`+ (Implementation is WIP )`
		`On the IPA server a new objectClass can be created to store an`
		`matching-mapping-domain rule triple together with a specific issuer. All`
		`attributes are optional because a missing mapping rule would mean that the`
		`@@ -598,38 +646,3 @@`
		``(altSecurityIdentities=<I>cn=issuer,dc=my-company,dc=com<S>cn=user,dc=my-company,dc=com)``
		`to find the matching user in the domain 'my-company.com'`

		`-`
		`- Mapping - alternative direct use of LDAP search filters`
		`- ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^`
		`- Since the goal of the mapping rules is to create a LDAP search filter a filter template can be used to define a mapping rules a well::`
		`-`
		`- (&(someAttr={issuer})(someOtherAttr={subject:O.I.D}))`
		`-`
		`- This offers much more flexibility in the rules. The syntax is a bit more`
		`- complex but LDAP search filters are well documented and administrators`
		`- should already have a basic understanding. Nevertheless a validation is`
		`- needed when a new rule is entered to make sure the template can be use to`
		`- generate a valid LDAP search filter.`
		`-`
		`- Configuration changes`
		`- ---------------------`
		`- Does your feature involve changes to configuration, like new options or`
		`- options changing values? Summarize them here. There's no need to go into`
		`- too many details, that's what man pages are for.`
		`-`
		`- How To Test`
		`- -----------`
		`- This section should explain to a person with admin-level of SSSD`
		`- understanding how this change affects run time behaviour of SSSD and how`
		`- can an SSSD user test this change. If the feature is internal-only, please`
		`- list what areas of SSSD are affected so that testers know where to focus.`
		`-`
		`- How To Debug`
		`- ------------`
		`- Explain how to debug this feature if something goes wrong. This section`
		`- might include examples of additional commands the user might run (such as`
		`- keytab or certificate sanity checks) or explain what message to look for.`
		`-`
		`- Authors`
		`- -------`
		`- * Sumit Bose <sbose@redhat.com>`