Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
SSS-CERTMAP(5)		 File Formats and Conventions		SSS-CERTMAP(5)

NAME
       sss-certmap - SSSD Certificate Matching and Mapping Rules

DESCRIPTION
       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.

       Each rule has four components, a	"priority", a "matching	rule", a
       "mapping	rule" and a "domain list". All components are optional.	A
       missing "priority" will add the rule with the lowest priority. The
       default "matching rule" will match certificates with the
       digitalSignature	key usage and clientAuth extended key usage. If	the
       "mapping	rule" 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.

RULE COMPONENTS
   PRIORITY
       The rules are processed 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.	The rules
       processing is stopped when a matched rule is found and no further rules
       are checked.

       Internally the priority is treated as unsigned 32bit integer, using a
       priority	value larger than 4294967295 will cause	an error.

   MATCHING RULE
       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
       "pkinit_cert_match" 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).

       The available options are:

       <SUBJECT>regular-expression
	   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.

	   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.

	   Example: <SUBJECT>.*,DC=MY,DC=DOMAIN

       <ISSUER>regular-expression
	   With	this a part or the whole issuer	name of	the certificate	can be
	   matched. All	comments for <SUBJECT> apply her as well.

	   Example: <ISSUER>^CN=My-CA,DC=MY,DC=DOMAIN$

       <KU>key-usage
	   This	option can be used to specify which key	usage values the
	   certificate should have. The	following values can be	used in	a
	   comma separated list:

	   o   digitalSignature

	   o   nonRepudiation

	   o   keyEncipherment

	   o   dataEncipherment

	   o   keyAgreement

	   o   keyCertSign

	   o   cRLSign

	   o   encipherOnly

	   o   decipherOnly

	   A numerical value in	the range of a 32bit unsigned integer can be
	   used	as well	to cover special use cases.

	   Example: <KU>digitalSignature,keyEncipherment

       <EKU>extended-key-usage
	   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:

	   o   serverAuth

	   o   clientAuth

	   o   codeSigning

	   o   emailProtection

	   o   timeStamping

	   o   OCSPSigning

	   o   KPClientAuth

	   o   pkinit

	   o   msScLogin

	   Extended key	usages which are not listed above can be specified
	   with	their OID in dotted-decimal notation.

	   Example: <EKU>clientAuth,1.3.6.1.5.2.3.4

       <SAN>regular-expression
	   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.

	   Example: <SAN>.*@MY\.REALM

       <SAN:Principal>regular-expression
	   Match the Kerberos principals in the	PKINIT or AD NT	Principal SAN.

	   Example: <SAN:Principal>.*@MY\.REALM

       <SAN:ntPrincipalName>regular-expression
	   Match the Kerberos principals from the AD NT	Principal SAN.

	   Example: <SAN:ntPrincipalName>.*@MY.AD.REALM

       <SAN:pkinit>regular-expression
	   Match the Kerberos principals from the PKINIT SAN.

	   Example: <SAN:ntPrincipalName>.*@MY\.PKINIT\.REALM

       <SAN:dotted-decimal-oid>regular-expression
	   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.

	   Example: <SAN:1.2.3.4>test

       <SAN:otherName>base64-string
	   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.

	   Example: <SAN:otherName>MTIz

       <SAN:rfc822Name>regular-expression
	   Match the value of the rfc822Name SAN.

	   Example: <SAN:rfc822Name>.*@email\.domain

       <SAN:dNSName>regular-expression
	   Match the value of the dNSName SAN.

	   Example: <SAN:dNSName>.*\.my\.dns\.domain

       <SAN:x400Address>base64-string
	   Binary match	the value of the x400Address SAN.

	   Example: <SAN:x400Address>MTIz

       <SAN:directoryName>regular-expression
	   Match the value of the directoryName	SAN. The same comments as
	   given for <ISSUER> and <SUBJECT> apply here as well.

	   Example: <SAN:directoryName>.*,DC=com

       <SAN:ediPartyName>base64-string
	   Binary match	the value of the ediPartyName SAN.

	   Example: <SAN:ediPartyName>MTIz

       <SAN:uniformResourceIdentifier>regular-expression
	   Match the value of the uniformResourceIdentifier SAN.

	   Example: <SAN:uniformResourceIdentifier>URN:.*

       <SAN:iPAddress>regular-expression
	   Match the value of the iPAddress SAN.

	   Example: <SAN:iPAddress>192\.168\..*

       <SAN:registeredID>regular-expression
	   Match the value of the registeredID SAN as dotted-decimal string.

	   Example: <SAN:registeredID>1\.2\.3\..*

   MAPPING RULE
       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.

       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 and 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.

       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.

       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 break the mapping. On the other hand it would
       be hard to break	the mapping on purpose for a specific user.

       The templates to	add certificate	data to	the search filter are based on
       Python-style formatting strings.	They consist 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:

       {issuer_dn[!((ad|ad_x500)|ad_ldap|nss_x500|(nss|nss_ldap))]}
	   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.

	   The conversion options starting with	'ad_' will use attribute names
	   as used by AD, e.g. 'S' instead of 'ST'.

	   The conversion options starting with	'nss_' will use	attribute
	   names as used by NSS.

	   The default conversion option is 'nss', i.e.	attribute names
	   according to	NSS and	LDAP/RFC 4514 ordering.

	   Example: (ipacertmapdata=X509:<I>{issuer_dn!ad}<S>{subject_dn!ad})

       {subject_dn[!((ad|ad_x500)|ad_ldap|nss_x500|(nss|nss_ldap))]}
	   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.

	   The conversion options starting with	'ad_' will use attribute names
	   as used by AD, e.g. 'S' instead of 'ST'.

	   The conversion options starting with	'nss_' will use	attribute
	   names as used by NSS.

	   The default conversion option is 'nss', i.e.	attribute names
	   according to	NSS and	LDAP/RFC 4514 ordering.

	   Example:
	   (ipacertmapdata=X509:<I>{issuer_dn!nss_x500}<S>{subject_dn!nss_x500})

       {cert[!(bin|base64)]}
	   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'.

	   Example: (userCertificate;binary={cert!bin})

       {subject_principal[.short_name]}
	   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 represents	the first part of the principal	before the '@'
	   sign.

	   Example:
	   (|(userPrincipal={subject_principal})(samAccountName={subject_principal.short_name}))

       {subject_pkinit_principal[.short_name]}
	   This	template will add the Kerberos principal which is given	by the
	   SAN used by pkinit. The 'short_name'	component represents the first
	   part	of the principal before	the '@'	sign.

	   Example:
	   (|(userPrincipal={subject_pkinit_principal})(uid={subject_pkinit_principal.short_name}))

       {subject_nt_principal[.short_name]}
	   This	template will add the Kerberos principal which is given	by the
	   SAN used by AD. The 'short_name' component represent	the first part
	   of the principal before the '@' sign.

	   Example:
	   (|(userPrincipal={subject_principal})(samAccountName={subject_principal.short_name}))

       {subject_rfc822_name[.short_name]}
	   This	template will add the string which is stored in	the rfc822Name
	   component of	the SAN, typically an email address. The 'short_name'
	   component represents	the first part of the address before the '@'
	   sign.

	   Example:
	   (|(mail={subject_rfc822_name})(uid={subject_rfc822_name.short_name}))

       {subject_dns_name[.short_name]}
	   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 represents the first part of the name	before
	   the first '.' sign.

	   Example:
	   (|(fqdn={subject_dns_name})(host={subject_dns_name.short_name}))

       {subject_uri}
	   This	template will add the string which is stored in	the
	   uniformResourceIdentifier component of the SAN.

	   Example: (uri={subject_uri})

       {subject_ip_address}
	   This	template will add the string which is stored in	the iPAddress
	   component of	the SAN.

	   Example: (ip={subject_ip_address})

       {subject_x400_address}
	   This	template will add the value which is stored in the x400Address
	   component of	the SAN	as escaped hex sequence.

	   Example: (attr:binary={subject_x400_address})

       {subject_directory_name[!((ad|ad_x500)|ad_ldap|nss_x500|(nss|nss_ldap))]}
	   This	template will add the DN string	of the value which is stored
	   in the directoryName	component of the SAN.

	   Example: (orig_dn={subject_directory_name})

       {subject_ediparty_name}
	   This	template will add the value which is stored in the
	   ediPartyName	component of the SAN as	escaped	hex sequence.

	   Example: (attr:binary={subject_ediparty_name})

       {subject_registered_id}
	   This	template will add the OID which	is stored in the registeredID
	   component of	the SAN	as a dotted-decimal string.

	   Example: (oid={subject_registered_id})

   DOMAIN LIST
       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.

AUTHORS
       The SSSD	upstream - https://pagure.io/SSSD/sssd/

SSSD				  03/01/2021			SSS-CERTMAP(5)

NAME | DESCRIPTION | RULE COMPONENTS | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=sss-certmap&sektion=5&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help