sss-certmap 5 Filformat och konventioner sss-certmap SSSD:s certifikatmatchnings- och -mappningsregler Manualsidan beskriver reglerna som kan användas av SSSD och andra komponenter för att matcha X.509-certifikat och koppla dem till konton. Varje regel har fyra komponenter, en prioritet, en matchningsregel, en mappningsregel och en domänlista. Alla komponenter är frivilliga. En saknad prioritet kommer lägga till regeln med den lägsta prioriteten. Standard-matchningsregeln kommer matcha certifikat med digitalSignature-nyckelanvändning och clientAuth-utökadnyckelanvändning. Om mappningsregeln är tom kommer certifikaten sökas efter i attributet userCertificate som DER-kodade binärer. Om inga domäner anges kommer endast den lokala domänen sökas. För att tillåta utökningar eller helt annorluda regelstil kan mapping och matching rules innehålla ett prefix separerat med ett ”:” från huvuddelen av regeln. Prefixet får bara innehålla versala ASCII-bokstäver och siffror. Om prefixet utelämnas kommer standardtypen användas vilken är ”KRB5” för matchningsregler och ”LDAP” för avbildningsregler. Verktyget ”sssctl” tillhandahåller kommandot ”cert-eval-rule” för att kontrollera om ett givet certifikat stämmer med en matchningsregel och hur utdata från en avbildningsregel skulle se ut. Reglerna bearbetas i prioritetsordning där ”0” (noll) indikerar den högsta prioriteten. Ju högre talet är desto lägre är prioriteten. Ett saknat värde indikerar den lägsta prioriteten. Regelbearbetningen stoppas när en regel som matchar hittas och inga ytterligare regler kontrolleras. Internt behandlas prioriteten som teckenlösa 32-bitars heltal, att använda ett prioritetsvärde större än 4294967295 kommer orsaka ett fel. Om flera regler har samma prioritet och bara en av de relaterade matchningsreglerna gäller kommer denna regel att väljas. Om det finns flera regler med samma prioritet som matchar väljs en men vilken av den är odefinierat. För att undvika detta beteende, använd antingen olika prioriteter eller gör matchningsregeln mer specifik, t.ex. genom att använda olika <ISSUER>-mönster. Matchningsregeln används för att välja ett certifikat som översättningsregeln skall tillämpas på. Det använder ett system liknande det som används av alternativet pkinit_cert_match i MIT Kerberos. Det består av ett nyckelord omgivet av ”<” och ”>” som identifierar en specifik del av certifikatet och ett mönster som skall finnas för att regeln skall matcha. Flera nyckelord/mönster-par kan antingen sammanfogas med ”&&” (och) eller ”||” (eller). Givet likheten med MIT Kerberos är typprefixet för denna regel ”KRB5”. Men ”KRB5” kommer även vara standardvärdet för matching rules så att ”<SUBJEKT>.*,DC=MIN,DC=DOMÄN” och ”KRB5:<SUBJEKT>.*,DC=MIN,DC=DOMÄN” är likvärdiga. De tillgängliga alternativen är: <SUBJECT>reguljärt-uttryck Med denna kan en del eller hela certifikatets subject-namn matchas. För matchningen används POSIX syntax för utökade reguljära uttryck, se regex(7) för detaljer. För matchningen konverteras subject-namnet lagrat i certifikatet i DER-kodad ASN.1 till en sträng i enlighet med RFC 4514. Detta betyder att den mest specifika namnkomponenten kommer först. Observera att inte alla möjliga attributnamn täcks av RFC 4514. De inkluderade namnen är ”CN”, ”L”, ”ST”, ”O”, ”OU”, ”C”, ”STREET”, ”DC” och ”UID”. Andra attributnamn kan visas olika på olika plattformar och av olika verktyg. För att undvika förvirring är det bäst att dessa attributnamn inte används eller täcks av ett lämpligt reguljärt uttryck. Exempel: <SUBJECT>.*,DC=MIN,DC=DOMÄN Observera att tecknen ”^.[$()|*+?{\” har en särskild betydelse i reguljära uttryck och måste skyddas med hjälp av tecknet ”\” så att de kan matchas som vanliga tecken. Exempel: <SUBJECT>^CN=.* \(Admin\),DC=MIN,DC=DOMÄN$ <ISSUER>reguljärt-uttryck Med denna kan en del eller hela certifikatets issuer-namn matchas. Alla kommentarer för <SUBJECT> är tillämpliga här också. Exempel: <ISSUER>^CN=Min-CA,DC=MIN,DC=DOMÄN$ <KU>nyckelanvändning Detta alternativ kan användas för att specificera vilka nyckelanvändningsvärden certifikatet skall ha. Följande värden kan användas i en kommaseparerad lista: digitalSignature nonRepudiation keyEncipherment dataEncipherment keyAgreement keyCertSign cRLSign encipherOnly decipherOnly Ett numeriskt värde i intervallet hos ett 32-bitars teckenlöst heltal kan användas också för att täcka speciella användningsfall. Exempel: <KU>digitalSignature,keyEncipherment <EKU>utökad-nyckel-användning Detta alternativ kan användas för att specificera vilka utökade-nyckel-användningsvärden certifikatet skall ha. Följande värden kan användas i en kommaseparerad lista: serverAuth clientAuth codeSigning emailProtection timeStamping OCSPSigning KPClientAuth pkinit msScLogin Användningar av utökade nycklar som inte listas ovanför kan specificeras med sina OID:er i punktad decimal notation. Exempel: <EKU>clientAuth,1.3.6.1.5.2.3.4 <SAN>reguljärt-uttryck För att vara kompatibel med användningen av MIT Kerberos kommer detta alternativ matcha Kerberos-huvudmän i PKINIT eller AD NT-Principal SAN som <SAN:Principal> gör. Exempel: <SAN>.*@MITT\.RIKE <SAN:Principal>reguljärt-uttryck Matcha Kerberos-huvudmännen i PKINIT eller AD NT Principal SAN. Exempel: <SAN:Principal>.*@MITT\.RIKE <SAN:ntPrincipalName>reguljärt-uttryck Matcha Kerberos-huvudmän från AD NT Principal SAN. Exempel: <SAN:ntPrincipalName>.*@MITT.AD.RIKE <SAN:pkinit>reguljärt-uttryck Matcha Kerberos-huvudmän från PKINIT SAN. Exempel: <SAN:ntPrincipalName>.*@MITT\.PKINIT\.RIKE <SAN:dotted-decimal-oid>reguljärt-uttryck Ta värdet från otherName SAN-komponenten som anges av OID:n i punktad decimal notation, tolka den som en sträng och försök att matcha den mot det reguljära uttrycket. Exempel: <SAN:1.2.3.4>test <SAN:otherName>base64-sträng Gör en binär matchning med den base64-kodade klicken mot alla otherName SAN-komponenter. Med detta alternativ är det möjligt att matcha mot anpassade otherName-komponenter med speciella kodningar som inte kan hanteras som strängar. Exempel: <SAN:otherName>MTIz <SAN:rfc822Name>reguljärt-uttryck Matcha värdet på rfc822Name SAN. Exempel: <SAN:rfc822Name>.*@epost\.domän <SAN:dNSName>reguljärt-uttryck Matcha värdet på dNSName SAN. Exempel: <SAN:dNSName>.*\.min\.dns\.domän <SAN:x400Address>base64-sträng Matcha binärt värdet på x400Address SAN. Exempel: <SAN:x400Address>MTIz <SAN:directoryName>reguljärt-uttryck Matcha värdet på directoryName SAN. Samma kommentarer som gavs för <ISSUER> och <SUBJECT> gäller här också. Exempel: <SAN:directoryName>.*,DC=com <SAN:ediPartyName>base64-sträng Matcha binärt värdet på ediPartyName SAN. Exempel: <SAN:ediPartyName>MTIz <SAN:uniformResourceIdentifier>reguljärt-uttryck Matcha värdet på uniformResourceIdentifier SAN. Exempel: <SAN:uniformResourceIdentifier>URN:.* <SAN:iPAddress>reguljärt-uttryck Matcha värdet på iPAddress SAN. Exempel: <SAN:iPAddress>192\.168\..* <SAN:registeredID>reguljärt-uttryck Matcha värdet på registeredID SAN som punktad decimal sträng. Exempel: <SAN:registeredID>1\.2\.3\..* Mappningsregeln används för att koppla ett certifikat med ett eller flera konton. Ett smartkort med certifikat och den matchande privata nyckeln kan då användas för autentisering som ett av dessa konton. För närvarande stödjer SSSD egentligen bara LDAP för att slå upp användarinformation (undantaget är proxy-leverantören som inte är relevant här. På grund av detta är mappningsregeln baserad på syntaxen för LDAP-sökfilter med mallar för att lägga till certifikatinnehåll till filtret. Det antas att filtret endast kommer innehålla de specifika data som behövs för mappningen och att anroparen kommer bädda in dem i ett annat filter för att göra den egentliga sökningen. Därför skall filtersträngen börja och sluta med ”(” respektive ”)”. I allmänhet rekommenderas det att använda attribut från certifikatet och lägga till dem till speciella attribut till LDAP-användarobjektet. T.ex. kan attributet ”altSecurityIdentities” i AD eller attributet ”ipaCertMapData” i IPA användas. Detta bör hellre användas än att läsa användarspecifik data från certifikatet som t.ex. en e-postadress och söka efter den i LDAP-servern. Anledningen är att användarspecifika data i LDAP kan ändras av olika anledningar vilket skulle göra sönder mappningen. Å andra sidan skulle det vara svårt att bryta mappningen avsiktligt för en specifik användare. Standardtypen för mapping rule är ”LDAP” vilket kan läggas till som ett prefix till en regel som t.ex. ”LDAP:(userCertificate;binary={cert!bin})”. Det finns en utökning som heter ”LDAPU1” som erbjuder fler mallar för mer flexibilitet. För att tillåta äldre versioner av detta bibliotek att ignorera utökningen måste prefixet ”LDAPU1” användas när de nya mallarna i en mapping rule används annars kommer den gamla versionen av biblioteket misslyckas med ett tolkningsfel. Den nya mallarna beskrivs i avsnittet . Mallarna för att lägga till certifikatdata till sökfiltret baseras på formateringssträngar i Python-stil. De består av ett nyckelord i krullparenteser med en valfri underkomponentspecificerare separerad av en ”.” eller ett valfritt konverterings-/formateringsalternativ separerat av ett ”!”. Tillåtna värden är: {issuer_dn[!((ad|ad_x500)|ad_ldap|nss_x500|(nss|nss_ldap))]} Mallen kommer lägga till den fullständiga utgivar-DN:en konverterad till en sträng enligt RFC 4514. Om X.500-ordning (mest specifik RDN kommer sist) skall ett alternativ med prefixet ”_x500” användas. Konverteringsalternativen som börjar med ”ad_” kommer använda attribut som de används av AD, t.ex. ”S” istället för ”ST”. Konverteringsalternativen som börjar med ”nss_” kommer använda attributnamn som de används av NSS. Standard för konverteringsalternativ är ”nss”, d.v.s. attributnamn enligt NSS och LDAP/RFC 4514-ordning. Exempel: (ipacertmapdata=X509:<I>{issuer_dn!ad}<S>{subject_dn!ad}) {subject_dn[!((ad|ad_x500)|ad_ldap|nss_x500|(nss|nss_ldap))]} Mallen kommer lägga till den fullständiga subjekt-DN:en konverterad till en sträng enligt RFC 4514. Om X.500-ordning (mest specifik RDN kommer sist) skall ett alternativ med prefixet ”_x500” användas. Konverteringsalternativen som börjar med ”ad_” kommer använda attribut som de används av AD, t.ex. ”S” istället för ”ST”. Konverteringsalternativen som börjar med ”nss_” kommer använda attributnamn som de används av NSS. Standard för konverteringsalternativ är ”nss”, d.v.s. attributnamn enligt NSS och LDAP/RFC 4514-ordning. Exempel: (ipacertmapdata=X509:<I>{issuer_dn!nss_x500}<S>{subject_dn!nss_x500}) {cert[!(bin|base64)]} Denna mall kommer lägga till hela det DER-kodade certifikatet som än sträng till sökfiltret. Beroende på konverteringsalternativen konverteras antingen certifikatet till en hex-sekvens med styrtecken ”\xx” eller till base64. Hex-strängen med styrtecken är standard och kan t.ex. användas med LDAP-attributet ”userCertificate;binary”. Exempel: (userCertificate;binary={cert!bin}) {subject_principal[.short_name]} Denna mall kommer lägga till Kerberos-huvudmannen som hämtas antingen från den SAN som används av pkinit eller den som används av AD. Komponenten ”short_name” representerar första delen av huvudmannen före tecknet ”@”. Exempel: (|(userPrincipal={subject_principal})(samAccountName={subject_principal.short_name})) {subject_pkinit_principal[.short_name]} Denna mall kommer lägga till Kerberos-huvudmannen som hämtas från den SAN som används av pkinit. Komponenten ”short_name” representerar första delen av huvudmannen före tecknet ”@”. Exempel: (|(userPrincipal={subject_pkinit_principal})(uid={subject_pkinit_principal.short_name})) {subject_nt_principal[.short_name]} Denna mall kommer lägga till Kerberos-huvudmannen som hämtas från den SAN som används av AD. Komponenten ”short_name” representerar första delen av huvudmannen före tecknet ”@”. Exempel: (|(userPrincipalName={subject_nt_principal})(samAccountName={subject_nt_principal.short_name})) {subject_rfc822_name[.short_name]} Denna mall kommer lägga till strängen som lagras i komponenten rfc822Name i SAN:en, normalt en e-postadress. Komponenten ”short_name” representerar första delen av huvudmannen före tecknet ”@”. Exempel: (|(mail={subject_rfc822_name})(uid={subject_rfc822_name.short_name})) {subject_dns_name[.short_name]} Denna mall kommer lägga till strängen som lagras i komponenten dNSName i SAN:en, normalt ett fullständigt kvalificerat värdnamn. Komponenten ”short_name” representerar första delen av huvudmannen före det första ”.”-tecknet. Exempel: (|(fqdn={subject_dns_name})(host={subject_dns_name.short_name})) {subject_uri} Denna mall kommer lägga till strängen som lagras i komponenten uniformResourceIdentifier i SAN:en. Exempel: (uri={subject_uri}) {subject_ip_address} Denna mall kommer lägga till strängen som lagras i komponenten iPAddress i SAN:en. Exempel: (ip={subject_ip_address}) {subject_x400_address} Denna mall kommer lägga till värdet som lagras i komponenten x400Address i SAN:en som en hex-sekvens med styrtecken. Exempel: (attr:binary={subject_x400_address}) {subject_directory_name[!((ad|ad_x500)|ad_ldap|nss_x500|(nss|nss_ldap))]} Denna mall kommer lägga till DN-strängen för värdet som lagras i komponenten directoryName i SAN:en. Exempel: (orig_dn={subject_directory_name}) {subject_ediparty_name} Denna mall kommer lägga till värdet som lagras i komponenten ediPartyName i SAN:en som en hex-sekvens med styrtecken. Exempel: (attr:binary={subject_ediparty_name}) {subject_registered_id} Denna mall kommer lägga till OID:n som lagras i komponenten registeredID i SAN:en som en punktad decimal sträng. Exempel: (oid={subject_registered_id}) Följande mall är tillgänglig när utökningen ”LDAPU1” används: {serial_number[!(dec|hex[_ucr])]} Denna mall kommer lägga till certifikatets serienummer. Som standard kommer det skrivas som ett hexadecimalt tal med gemena bokstäver. Med formateringsalternativet ”!dec” kommer numret skrivas som en decimal sträng. Den exadecimala utdatan kan skrivas med versala bokstäver (”!hex_u”), med ett kolon som separator mellan hexadecimala byte (”!hex_c”) eller med de hexadecimala byten i omvänd ordning (”!hex_r”). Postfixbokstäverna kan kombineras så att t.ex. ”!hex_uc" kommer producera en kolonseparerad hexadecimal sträng med versaler. Exempel: LDAPU1:(serial={serial_number}) {subject_key_id[!hex[_ucr]]} Denna mall kommer lägga till certifikatets subjektnyckel-id. Som standard kommer det skrivas som ett hexadecimalt tal med gemena bokstäver. Den hexadecimala utdatan kan skrivas med versala bokstäver (”!hex_u”), med ett kolon som separator mellan hexadecimala byte (”!hex_c”) eller med de hexadecimala byten i omvänd ordning (”!hex_r”). Postfixbokstäverna kan kombineras så att t.ex. ”!hex_uc" kommer producera en kolonseparerad hexadecimal sträng med versaler. Exempel: LDAPU1:(ski={subject_key_id}) {cert[!KONTROLLSUMMA[_ucr]]} Denna mall kommer läga till certifikatets hexadecimala kontrollsumma/hash där KONTROLLSUMMA måste ersättas med namnet på en kontrollsumme-/hash-funktion som stödjs av OpenSSL, t.ex. ”sha512”. Den hexadecimala utdatan kan skrivas med versala bokstäver (”!sha512_u”), med ett kolon som separator mellan hexadecimala byte (”!sha512_c”) eller med de hexadecimala byten i omvänd ordning (”!sha512_r”). Postfixbokstäverna kan kombineras så att t.ex. ”!sha512_uc" kommer producera en kolonseparerad hexadecimal sträng med versaler. Exempel: LDAPU1:(dgst={cert!sha256}) {subject_dn_component[(.attr_name|[number]]} Denna mall kommer lägga till ett av komponentens attributvärden från subjekt-DN, som standard värdet på den mest specifika komponenten. En annan komponent kan antingen väljas via attributnamnet, t.ex. {subject_dn_component.uid} eller via position, t.ex. {subject_dn_component.[2]} där positiva tal börjar räknas från den mest specifika komponenten och negativa tal börjar räkna från den minst specifika komponenten Attributnamn och positionen kan kombineras, t.ex. {subject_dn_component.uid[2]} vilket betyder att namnet på den andra komponenten måste vara ”uid”. Exempel: LDAPU1:(uid={subject_dn_component.uid}) {issuer_dn_component[(.attr_namn|[tal]]} Denna mall kommer lägga till ett av komponentens attributvärden från utgivar-DN, som standard värdet på den mest specifika komponenten. Se ”subject_dn_component” för detaljer om attributnamn och positionsangivelser. Exempel: LDAPU1:(domain={issuer_dn_component.[-2]}.{issuer_dn_component.dc[-1]}) {sid[.rid]} Denna mall kommer lägga till SID:n om den motsvarande utökningen introducerad av Microsoft med OID 1.3.6.1.4.1.311.25.2 är tillgänglig. Med selektorn ”.rid” kommer endast den sista komponenten, d.v.s RID:n, att läggas till. Exempel: LDAPU1:(objectsid={sid}) Om domänlistan inte är tom söks användare mappade till ett givet certifikat inte bara i den lokala domänen utan i de listade domänerna också förutsatt att de är kända av SSSD. Domäner som SSSD inte känner till kommer ignoreras.