diff options
Diffstat (limited to 'src/man/sss-certmap.5.xml')
| -rw-r--r-- | src/man/sss-certmap.5.xml | 600 |
1 files changed, 600 insertions, 0 deletions
diff --git a/src/man/sss-certmap.5.xml b/src/man/sss-certmap.5.xml new file mode 100644 index 000000000..bbe68509f --- /dev/null +++ b/src/man/sss-certmap.5.xml @@ -0,0 +1,600 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE reference PUBLIC "-//OASIS//DTD DocBook V4.4//EN" +"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"> +<reference> +<title>SSSD Manual pages</title> +<refentry> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="include/upstream.xml" /> + + <refmeta> + <refentrytitle>sss-certmap</refentrytitle> + <manvolnum>5</manvolnum> + <refmiscinfo class="manual">File Formats and Conventions</refmiscinfo> + </refmeta> + + <refnamediv id='name'> + <refname>sss-certmap</refname> + <refpurpose>SSSD Certificate Matching and Mapping Rules</refpurpose> + </refnamediv> + + <refsect1 id='description'> + <title>DESCRIPTION</title> + <para> + The manual page describes the rules which can be used by SSSD and + other components to match X.509 certificates and map them to + accounts. + </para> + <para> + Each rule has four components, a <quote>priority</quote>, a + <quote>matching rule</quote>, a <quote>mapping rule</quote> and a + <quote>domain list</quote>. All components are optional. A missing + <quote>priority</quote> will add the rule with the lowest priority. + The default <quote>matching rule</quote> will match certificates with + the digitalSignature key usage and clientAuth extended key usage. If + the <quote>mapping rule</quote> is empty the certificates will be + searched in the userCertificate attribute as DER encoded binary. If + no domains are given only the local domain will be searched. + </para> + </refsect1> + + <refsect1 id='components'> + <title>RULE COMPONENTS</title> + <refsect2 id='priority'> + <title>PRIORITY</title> + <para> + The rules are process by priority while the number '0' (zero) + indicates the highest priority. The higher the number the lower is + the priority. A missing value indicates the lowest priority. + </para> + <para> + Internally the priority is treated as unsigned 32bit integer, using + a priority value larger than 4294967295 will cause an error. + </para> + </refsect2> + <refsect2 id='match'> + <title>MATCHING RULE</title> + <para> + The matching rule is used to select a certificate to which the + mapping rule should be applied. It uses a system similar to the one + used by <quote>pkinit_cert_match</quote> option of MIT Kerberos. It + consists of a keyword enclosed by '<' and '>' which identified + a certain part of the certificate and a pattern which should be + found for the rule to match. Multiple keyword pattern pairs can be + either joined with '&&' (and) or '||' (or). + </para> + <para> + The available options are: + <variablelist> + <varlistentry> + <term><SUBJECT>regular-expression</term> + <listitem> + <para> + With this a part or the whole subject name of the + certificate can be matched. For the matching POSIX + Extended Regular Expression syntax is used, see regex(7) + for details. + </para> + <para> + For the matching the subject name stored in the + certificate in DER encoded ASN.1 is converted into a + string according to RFC 4514. This means the most + specific name component comes first. Please note that + not all possible attribute names are covered by RFC + 4514. The names included are 'CN', 'L', 'ST', 'O', + 'OU', 'C', 'STREET', 'DC' and 'UID'. Other attribute + names might be shown differently on different platform + and by different tools. To avoid confusion those + attribute names are best not used or covered by a + suitable regular-expression. + </para> + <para> + Example: <SUBJECT>.*,DC=MY,DC=DOMAIN + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><ISSUER>regular-expression</term> + <listitem> + <para> + With this a part or the whole issuer name of the + certificate can be matched. All comments for + <SUBJECT> apply her as well. + </para> + <para> + Example: <ISSUER>^CN=My-CA,DC=MY,DC=DOMAIN$ + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><KU>key-usage</term> + <listitem> + <para> + This option can be used to specify which key usage + values the certificate should have. The following value + can be used in a comma separate list: + <itemizedlist> + <listitem><para>digitalSignature</para></listitem> + <listitem><para>nonRepudiation</para></listitem> + <listitem><para>keyEncipherment</para></listitem> + <listitem><para>dataEncipherment</para></listitem> + <listitem><para>keyAgreement</para></listitem> + <listitem><para>keyCertSign</para></listitem> + <listitem><para>cRLSign</para></listitem> + <listitem><para>encipherOnly</para></listitem> + <listitem><para>decipherOnly</para></listitem> + </itemizedlist> + </para> + <para> + A numerical value in the range of a 32bit unsigned + integer can be used as well to cover special use cases. + </para> + <para> + Example: <KU>digitalSignature,keyEncipherment + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><EKU>extended-key-usage</term> + <listitem> + <para> + This option can be used to specify which extended key + usage the certificate should have. The following value + can be used in a comma separated list: + <itemizedlist> + <listitem><para>serverAuth</para></listitem> + <listitem><para>clientAuth</para></listitem> + <listitem><para>codeSigning</para></listitem> + <listitem><para>emailProtection</para></listitem> + <listitem><para>timeStamping</para></listitem> + <listitem><para>OCSPSigning</para></listitem> + <listitem><para>KPClientAuth</para></listitem> + <listitem><para>pkinit</para></listitem> + <listitem><para>msScLogin</para></listitem> + </itemizedlist> + </para> + <para> + Extended key usages which are not listed above can be + specified with their OID in dotted-decimal notation. + </para> + <para> + Example: <EKU>clientAuth,1.3.6.1.5.2.3.4 + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><SAN>regular-expression</term> + <listitem> + <para> + To be compatible with the usage of MIT Kerberos this + option will match the Kerberos principals in the PKINIT + or AD NT Principal SAN as <SAN:Principal> does. + </para> + <para> + Example: <SAN>.*@MY\.REALM + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><SAN:Principal>regular-expression</term> + <listitem> + <para> + Match the Kerberos principals in the PKINIT or AD NT + Principal SAN. + </para> + <para> + Example: <SAN:Principal>.*@MY\.REALM + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><SAN:ntPrincipalName>regular-expression</term> + <listitem> + <para> + Match the Kerberos principals from the AD NT Principal + SAN. + </para> + <para> + Example: <SAN:ntPrincipalName>.*@MY.AD.REALM + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><SAN:pkinit>regular-expression</term> + <listitem> + <para> + Match the Kerberos principals from the PKINIT SAN. + </para> + <para> + Example: <SAN:ntPrincipalName>.*@MY\.PKINIT\.REALM + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><SAN:dotted-decimal-oid>regular-expression</term> + <listitem> + <para> + Take the value of the otherName SAN component given by + the OID in dotted-decimal notation, interpret it as + string and try to match it against the regular + expression. + </para> + <para> + Example: <SAN:1.2.3.4>test + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><SAN:otherName>base64-string</term> + <listitem> + <para> + Do a binary match with the base64 encoded blob against + all otherName SAN components. With this option it is + possible to match against custom otherName components + with special encodings which could not be treated as + strings. + </para> + <para> + Example: <SAN:otherName>MTIz + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><SAN:rfc822Name>regular-expression</term> + <listitem> + <para> + Match the value of the rfc822Name SAN. + </para> + <para> + Example: <SAN:rfc822Name>.*@email\.domain + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><SAN:dNSName>regular-expression</term> + <listitem> + <para> + Match the value of the dNSName SAN. + </para> + <para> + Example: <SAN:dNSName>.*\.my\.dns\.domain + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><SAN:x400Address>base64-string</term> + <listitem> + <para> + Binary match the value of the x400Address SAN. + </para> + <para> + Example: <SAN:x400Address>MTIz + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><SAN:directoryName>regular-expression</term> + <listitem> + <para> + Match the value of the directoryName SAN. The same + comments as given for <ISSUER> and <SUBJECT> + apply here as well. + </para> + <para> + Example: <SAN:directoryName>.*,DC=com + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><SAN:ediPartyName>base64-string</term> + <listitem> + <para> + Binary match the value of the ediPartyName SAN. + </para> + <para> + Example: <SAN:ediPartyName>MTIz + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><SAN:uniformResourceIdentifier>regular-expression</term> + <listitem> + <para> + Match the value of the uniformResourceIdentifier SAN. + </para> + <para> + Example: <SAN:uniformResourceIdentifier>URN:.* + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><SAN:iPAddress>regular-expression</term> + <listitem> + <para> + Match the value of the iPAddress SAN. + </para> + <para> + Example: <SAN:iPAddress>192\.168\..* + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><SAN:registeredID>regular-expression</term> + <listitem> + <para> + Match the value of the registeredID SAN as + dotted-decimal string. + </para> + <para> + Example: <SAN:registeredID>1\.2\.3\..* + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect2> + <refsect2 id='map'> + <title>MAPPING RULE</title> + <para> + The mapping rule is used to associate a certificate with one or more + accounts. A Smartcard with the certificate and the matching private + key can then be used to authenticate as one of those accounts. + </para> + <para> + Currently SSSD basically only supports LDAP to lookup user + information (the exception is the proxy provider which is not of + relevance here). Because of this the mapping rule is based on LDAP + search filter syntax with templates to add certificate content to + the filter. It is expected that the filter will only contain the + specific data needed for the mapping an that the caller will embed + it in another filter to do the actual search. Because of this the + filter string should start and stop with '(' and ')' respectively. + </para> + <para> + In general it is recommended to use attributes from the certificate + and add them to special attributes to the LDAP user object. E.g. the + 'altSecurityIdentities' attribute in AD or the 'ipaCertMapData' + attribute for IPA can be used. + </para> + <para> + This should be preferred to read user specific data from the + certificate like e.g. an email address and search for it in the LDAP + server. The reason is that the user specific data in LDAP might + change for various reasons would would break the mapping. On the + other hand it would be hard to break the mapping on purpose for a + specific user. + </para> + <para> + The templates to add certificate data to the search filter are based + on Python-style formatting strings. They consists of a keyword in + curly braces with an optional sub-component specifier separated by a + '.' or an optional conversion/formatting option separated by a '!'. + Allowed values are: + <variablelist> + <varlistentry> + <term>{issuer_dn[!((ad|ad_x500)|ad_ldap|nss_x500|(nss|nss_ldap))]}</term> + <listitem> + <para> + This template will add the full issuer DN converted to a + string according to RFC 4514. If X.500 ordering (most + specific RDN comes last) an option with the '_x500' + prefix should be used. + </para> + <para> + The conversion options starting with 'ad_' will use + attribute names as used by AD, e.g. 'S' instead of 'ST'. + </para> + <para> + The conversion options starting with 'nss_' will use + attribute names as used by NSS. + </para> + <para> + The default conversion option is 'nss', i.e. attribute + names according to NSS and LDAP/RFC 4514 ordering. + </para> + <para> + Example: (ipacertmapdata=X509:<I>{issuer_dn!ad}<S>{subject_dn!ad}) + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>{subject_dn[!((ad|ad_x500)|ad_ldap|nss_x500|(nss|nss_ldap))]}</term> + <listitem> + <para> + This template will add the full subject DN converted to + string according to RFC 4514. If X.500 ordering (most + specific RDN comes last) an option with the '_x500' + prefix should be used. + </para> + <para> + The conversion options starting with 'ad_' will use + attribute names as used by AD, e.g. 'S' instead of 'ST'. + </para> + <para> + The conversion options starting with 'nss_' will use + attribute names as used by NSS. + </para> + <para> + The default conversion option is 'nss', i.e. attribute + names according to NSS and LDAP/RFC 4514 ordering. + </para> + <para> + Example: (ipacertmapdata=X509:<I>{issuer_dn!nss_x500}<S>{subject_dn!nss_x500}) + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>{cert[!(bin|base64)]}</term> + <listitem> + <para> + This template will add the whole DER encoded certificate + as a string to the search filter. Depending on the + conversion option the binary certificate is either + converted to an escaped hex sequence '\xx' or base64. + The escaped hex sequence is the default and can e.g. be + used with the LDAP attribute 'userCertificate;binary'. + </para> + <para> + Example: (userCertificate;binary={cert!bin}) + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>{subject_principal[.short_name]}</term> + <listitem> + <para> + This template will add the Kerberos principal which is + taken either from the SAN used by pkinit or the one used + by AD. The 'short_name' component represent the first + part of the principal before the '@' sign. + </para> + <para> + Example: (|(userPrincipal={subject_principal})(samAccountName={subject_principal.short_name})) + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>{subject_pkinit_principal[.short_name]}</term> + <listitem> + <para> + This template will add the Kerberos principal which is + given by then SAN used by pkinit. The 'short_name' + component represent the first part of the principal + before the '@' sign. + </para> + <para> + Example: (|(userPrincipal={subject_pkinit_principal})(uid={subject_pkinit_principal.short_name})) + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>{subject_nt_principal[.short_name]}</term> + <listitem> + <para> + This template will add the Kerberos principal which is + given by then SAN used by AD. The 'short_name' component + represent the first part of the principal before the '@' + sign. + </para> + <para> + Example: (|(userPrincipal={subject_principal})(samAccountName={subject_principal.short_name})) + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>{subject_rfc822_name[.short_name]}</term> + <listitem> + <para> + This template will add the string which is stored in the + rfc822Name component of the SAN, typically an email + address. The 'short_name' component represent the first + part of the address before the '@' sign. + </para> + <para> + Example: (|(mail={subject_rfc822_name})(uid={subject_rfc822_name.short_name})) + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>{subject_dns_name[.short_name]}</term> + <listitem> + <para> + This template will add the string which is stored in the + dNSName component of the SAN, typically a fully-qualified host name. + The 'short_name' component represent the first + part of the name before the first '.' sign. + </para> + <para> + Example: (|(fqdn={subject_dns_name})(host={subject_dns_name.short_name})) + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>{subject_uri}</term> + <listitem> + <para> + This template will add the string which is stored in the + uniformResourceIdentifier component of the SAN. + </para> + <para> + Example: (uri={subject_uri}) + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>{subject_ip_address}</term> + <listitem> + <para> + This template will add the string which is stored in the + iPAddress component of the SAN. + </para> + <para> + Example: (ip={subject_ip_address}) + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>{subject_x400_address}</term> + <listitem> + <para> + This template will add the value which is stored in the + x400Address component of the SAN as escaped hex + sequence. + </para> + <para> + Example: (attr:binary={subject_x400_address}) + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>{subject_directory_name[!((ad|ad_x500)|ad_ldap|nss_x500|(nss|nss_ldap))]}</term> + <listitem> + <para> + This template will add the DN string of the value which + is stored in the directoryName component of the SAN. + </para> + <para> + Example: (orig_dn={subject_directory_name}) + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>{subject_ediparty_name}</term> + <listitem> + <para> + This template will add the value which is stored in the + ediPartyName component of the SAN as escaped hex + sequence. + </para> + <para> + Example: (attr:binary={subject_ediparty_name}) + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>{subject_registered_id}</term> + <listitem> + <para> + This template will add the OID which is stored in the + registeredID component of the SAN as as dotted-decimal + string. + </para> + <para> + Example: (oid={subject_registered_id}) + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect2> + <refsect2 id='domains'> + <title>DOMAIN LIST</title> + <para> + If the domain list is not empty users mapped to a given certificate + are not only searched in the local domain but in the listed domains + as well as long as they are know by SSSD. Domains not know to SSSD + will be ignored. + </para> + </refsect2> + </refsect1> +</refentry> +</reference> |