Skip to content

InDepth

Jump to bottom Edit New page
claeslundahl edited this page Sep 10, 2015 · 3 revisions

Inneh?llsf?rteckning

  • Inneh?llsf?rteckning
  • Referenser
  • Bakgrund och ?ndam?l
  • Vad ?r en elektronisk signatur?
  • Hur signerar jag utan signeringtj?nsten?
  • Funktionsbeskrivning
  • Hur signerar jag med signeringtj?nsten?
  • Vad g?r signeringstj?nsten f?r mig?
  • ?versiktlig systembeskrivning *"https://github.com/Vastra-Gotalandsregionen/oppna-program-signing-service/wiki/images/solution.png" width
  • S?kerhet
  • Ordlista
  • Sekvensdiagram
  • Projektstruktur
  • Installation
  • S?tta upp en instans av signeringstj?nsten
  • Konfiguration *"443" protocol *"150" scheme *"false" sslProtocol *"s3cr3t-passw0rd" keystoreType
  • Felhantering
  • Loggning
  • Lokal Utvecklingsmilj?
  • Signeringstj?nsten
  • Referensapplikation
  • Testcertifkat
  • S?kerhet
  • Certifikathantering
  • Kvarst?ende utvecklingspunkter
  • Anslut till signeringstj?nsten

Referenser

Bakgrund och ?ndam?l

En elektronisk signatur ska s?kerst?lla att elektroniskt ?verf?rd information inte har ?ndrats och f?r att identifiera informationens avs?ndare. Genom kryptering skyddas uppgifter i ett dokument mot obeh?rig ?tkomst.

Vad ?r en elektronisk signatur?

En elektroniskt underskriven handling best?r av tv? delar. Dels texten som skall signeras och dels sj?lva signaturen. F?r att s?kerst?lla att en text ?r identisk vid tv? olika tillf?llen ber?knas en kontrollsumma av texten. Denna kontrollsumma ?r alltid densamma s? l?nge texten inte har f?r?ndrats och d?rmed kan man garantera att texten inte har f?r?ndrats ?ver tid. Detta ?r dock inte tillr?ckligt utan man beh?ver ?ven kunna s?kerst?lla vem som har utf?rdat texten. Detta g?rs genom att kontrollsumman krypteras med undertecknarens privat nyckel. Dekryptering kan sedan endast g?ras med hj?lp av undertecknarens publika nyckel. Nu kan man med s?kerhet knyta en viss text till en best?md utst?llare.

I den digitala signatur som genereras finns tillr?ckligt med information f?r att kontrollera ?ktheten hos en elektroniskt underskriven handling. Formatet p? dessa signaturer kommer i tv? varianter, PKCS#7 eller XMLDSig beroende p? vilken typ av e-legitimation som anv?nds vid signeringstillf?llet.

Hur signerar jag utan signeringtj?nsten?

F?rsta steget f?r en applikation ?r att erbjuda signering f?r en anv?ndare. N?r anv?ndaren har bett om signering m?ste applikationen visa en signeringsklient f?r anv?ndaren som skall utf?ra sj?lva signeringen. H?r m?ste applikationen ta h?nsyn till vad f?r typ av certifikat som anv?ndaren vill signera med samt vilken browser som anv?nds. I n?sta steg m?ste applikationen ta emot signaturen och genomf?ra en kontroll av den f?r att verifiera att certifikatet som anv?ndes vid signeringen ?r giltligt. Det som verifieras ?r att certifikatet ?r utf?rdat av en giltig CA-Root, att det inte ?r revokerat samt att det inte har g?tt ut. I sista steget m?ste applikationen spara signaturen f?r framtida behov. Nedan visas en schematisk bild ?ver hur fl?det ser ut, de heldragna pilarna ?r de interaktioner som m?ste hanteras/implementeras av applikationen.

Funktionsbeskrivning

Hur signerar jag med signeringtj?nsten?

F?rsta steget f?r en applikation ?r att erbjuda signering f?r en anv?ndare. Efter detta tar signeringstj?nsten ?ver och hanterar presentationen av signeringsklineten (t.ex. NetID) med allt vad det inneb?r, signeringstj?nsten tar ?ven hand om certifikatskontrollen som bla. verifierar att certifikatet som anv?nds i signaturen inte ?r sp?rrat. Det den nyttjande applikationen beh?ver ta h?nsyn till ?r lagringen av signaturen. Nedan visas en schematisk bild ?ver hur fl?det ser ut, de heldragna pilarna ?r de interaktioner som m?ste hanteras/implementeras av applikationen.

Vad g?r signeringstj?nsten f?r mig?

Signeringstj?nsten hj?lper till med f?ljande:

  • M?jlighet att visa ett gr?nssnitt f?r val av signerings-certifikat
  • Presenatation av olika signeringsklienter beroende p? certifikat
  • Hantering av olika webbl?sare
  • Verifiering av utf?rdad signatur

?versiktlig systembeskrivning

<img src#"https://github.com/Vastra-Gotalandsregionen/oppna-program-signing-service/wiki/images/solution.png" width"800"/>

  1. Klienten beg?r att f? n?got signerat(TBS ? To Be Signed) av SS. Rekommenderat ?r att skicka en kontrollsumma av TBS. Kontrollsumman ?r f?rslagsvis ber?knad utifr?n SHA-2(t.ex. SHA-256) f?r att f? en ?kad s?kerhet. SS beh?ver ?ven ha en submitUri dit signaturen skall skickas n?r den ?r klar. Valbart(optional) ?r att skicka in en clientType.
  2. Har ingen clientType skickats med visas ett val av tillg?ngliga clientTypes f?r anv?ndaren. SS tar fram ett block av html/xhtml(PKI Client Code) baserat p? clientType och TBS som den visar f?r klienten.
  3. PKI-klienten startar upp f?r signering hos anv?ndaren.
  4. Anv?ndaren matar in l?senord f?r sin privata nyckel och TBS signeras. PKI-klienten postar signaturen PKSC#7 eller XML-Signature) till SS. Vilket format som skickas till SS beror p? clientType.
  5. Signaturen verifieras via en OSIF tj?nst.
  6. Status f?r hur valideringen gick skickas tillbaka till SS.
  7. SS skickar signaturen till submitUri f?r lagring, detta sker ?ver ftps eller https. Om https v?ljs finns ?ven en m?jlighet f?r applikationen att sj?lv presentera status f?r signeringen (se steg 7). I annat fall kommer SS att hantera presentationen av status.
  8. Om X sj?lv kan och vill presentera status f?r signeringen g?r den en 302 Moved Temporary till en url som hanterar presentationen. Om X vill ?verl?ta detta till SS r?cker det med att svara med en vanlig 200 OK response.
  9. Om SS f?r en 302 Moved Temporary fr?n X skickar ?ven SS en 302 redirect tillbaka till klienten med samma location som X satte i sin redirect. Om SS f?r en 200 OK visar den en status sida f?r klienten.
  10. 302 Moved Temporary till location satt av X.
  11. X visar ett svar f?r klienten. Kommentarer *Steg 10 och 11 kommer endast att intr?ffa om X g?r en 302 Moved Temporary i steg 8.

S?kerhet

F?r att garantera s?kerheten b?r all kommunikation ske ?ver en krypterad anslutning ? https. Det finns dock fortfarande en risk att SS blir utsatt f?r en attack och ers?tts av en "elak" SS som byter ut signatur och certifikat. F?r att f?rhindra detta ?r det starkt rekommenderat att X s?tter upp TLS mot SS. TLS syftar till att genom utbyte av certifikat mellan SS och X kan X grantera att identiteten p? SS. Allts?, med tillg?ng till SS publika nyckel kan X verifiera att det ?r SS som skickar signaturen till submitUri.

Ordlista

|| Begrepp || F?rklaring || || TBS || To Be Signed. Data som skall signeras. || || submitUri || Uri dit signaturen skall skickas efter signering. || || clientType || Typ av signering, i dagsl?get har Signeringstj?nsten st?d f?r !BankId, Nordea, Posten och SITHS. ||

Sekvensdiagram

Projektstruktur

Signeringstj?nsten best?r egentligen av tv? projekt:

  • signer-service som i sin tur best?r av tv? moduler:
    • core-bc - detta ?r sj?lva signeringstj?nsten
    • reference-application - en konsument som fungerar som ett exempel p? hur man kan utnyttja signeringstj?nsten
  • signer-service-schemas - inneh?ller schemat f?r det xml-meddelande, inneh?llandes signaturen, som skickas fr?n signeringstj?nsten till konsumenten.

Installation

Signeringstj?nsten beh?ver konfigureras en hel innan den kan startas. Detta beror p? att den anv?nder sig av TLS f?r att datan som skickas mellan den och konsumenterna. F?r att i m?jligaste m?n underl?tta s? mycket som m?jligt f?r utvecklarna av tj?nsten har en viss default-konfiguration paketerats med i projektet. F?r en produktionsinstans m?ste dock denna konfiguration anpassas. Hur man g?r detta beskrivs i avsnittet [ InDepth#Konfiguration konfiguration ] ( InDepth#Konfiguration konfiguration ) l?ngre ner i dokumentationen.

?ven konsumenterna av signeringstj?nsten kr?ver en del TLS-konfiguration vilket finns beskrivet i avsnittet Anslut till signeringstj?nsten.

S?tta upp en instans av signeringstj?nsten

Att installera och konfigurera signeringstj?nsten i en produktionsmilj? ganska trixit. Installationen best?r av tv? steg: f?rst skapar man en katalog med namnet '.ss' i hemkatalogen (h?r kommer konfigurationen att hamna) f?r den anv?ndare som k?r webbservern (t.ex. Tomcat) och sen installerar man war-filen. Mellan dessa steg m?ste dock en hel del konfiguration g?ras, se avsnittet om [ InDepth#Konfiguration konfiguration ] ( InDepth#Konfiguration konfiguration ) .

Konfiguration

F?r att f? en bakgrund till hur man skall konfigurera signeringstj?nsten ?r det l?mpligt att l?sa denna blog-post som p? ett bra s?tt beskriver hur applikationen l?ser in sin konfiguration.

Med bakgrund till ovan n?mnda blogg kommer h?r en f?rklaring till inst?llningar som kan g?ras f?r signeringstj?nsten. Till att b?rja med m?ste en fil med namnet 'config.properties' skapas och l?ggas in under '~/.ss'. Om man vill ha en mall att utg? ifr?n s? kan man anv?nda sig av default-konfigurationen som ligger i projektets web-modul ('$PROJECT_HOME/core-bc/modules/web/src/main/resources/default.properties'). I denna fil kan f?ljande parametrar s?ttas:

|| Parameter || Beskrivning || || connectionTimeout || Vid ?verf?ring av signaturen till konsumenten anv?nds en http-klient. Detta v?rde anger hur l?nge applikationen skall v?nta p? en connection till servern. || || soTimeout || Vid ?verf?ring av signaturen till konsumenten anv?nds en http-klient. Detta v?rde anger hur l?nge en socket skall v?nta p? svar n?r den l?ser och skriver paket. Detta ligger p? en l?gre niv? i n?tverksstacken ?n connectionTimeout. || || maxTotalConnections || Signeringstj?nsten anv?nder sig av en connection-pool f?r de http-connections den anv?nder. Max antal connections som denna pool hanterar styrs av denna parameter. || || keystore.type || ?verf?ring av signaturen till konsumenten rekommenderas att ske ?ver TLS med sk. Mutual Authentication anv?nds. Detta aktiveras av konsumentens mottagande server (Finns beskrivet i anslut till signeringstj?nsten). F?r att Mutual Authentication skall fungera m?ste klienten (i det h?r fallet signeringstj?nsten, se steg 7 i bilden under ?versiktlig systembeskrivning) presentera sig med ett SITHS-certifikat inneh?llande en privat nyckel. Detta certifikat lagras i en viss typ av i n?got som kallas keystore. Det ?r denna typ som anges i detta f?lt. Exempel p? olika typer ?r 'JKS, P12 och PFX'. || || keystore.location || Anger s?kv?gen p? ovan n?mnda keystore || || keystore.password || Anger l?senordet p? ovan n?mnda keystore || || truststore.type || ?verf?ring av signaturen till konsumenten rekommenderas att ske ?ver TLS. Detta inneb?r att den http-klient som signeringstj?nsten anv?nder sig av f?r detta f?rfarande m?ste lita p? mottagaren av signaturen. Signeringstj?nsten m?ste s?ledes ta del av mottagarens (konsumentens) publika certifikat och l?gga in det i sitt truststore. P? samma s?tt som keystore finns ?ven truststore i olika format och det ?r detta format som skall anges i det h?r f?ltet. Exempel p? olika typer ?r 'JKS, P12 och PFX'. || || truststore.location || Anger s?kv?gen p? ovan n?mnda keystore || || truststore.password || Anger l?senordet p? ovan n?mnda keystore || || eid.endpoint || F?r att verifiera en signatur anv?nder sig signeringstj?nsten av en annan tj?nst. Denna tj?nst kallas OSIF och hostas idag av Logica. I detta f?lt anges servicens endpoint adress. || || eid.serviceid || F?r att f? nyttja OSIF-tj?nsten kr?vs att man skickar med ett seriviceId. Detta seriviceId anges h?r. ||

Ut?ver denna konfiguration har man ?ven m?jlighet att s?tta en System Properties vid uppstart av applikationen. Denna s?tts mha -D-flaggan n?r jvm:en startas.

||?System Property?|| V?rden || Beskrivning?|| || 'ssl.hostname.verification' || 'strict' eller 'lenient' || Normalt n?r ett certifikat verifieras vid en TLS-konversation kr?vs att hostnamnet ?verensst?mmer med certifikatnamnet. Genom att s?tta denna property till 'lenient' s? kan man komma runt det kravet. Detta ?r bra framf?r allt under utveckling och test. I en produktionsmilj? ?r det rekommenderat att anv?nda 'strict' validering av hostnamnet. Utel?mnas denna konfiguration s? anv?nds 'strict' som default.||

Slutligen, SSL/TLS-konfigurationen som exponeras mot webb-l?sarna g?rs p? den server som signerinstj?nstens installerats. P? en tomcat g?rs denna konfiguation i $TOMCAT_HOME/conf/server.xml. D?r skall en ny https-connector skapas med inst?llningar f?r vilken bla. port och keystore som skall anv?ndas. Ett exempel p? hur detta kan se ut:

<Connector port#"443" protocol"HTTP/1.1" SSLEnabled="true"
  maxThreads#"150" scheme"https" secure="true"
  clientAuth#"false" sslProtocol"TLS" keystoreFile="${user.home}/.ss/keystore.jks"
  keystorePass#"s3cr3t-passw0rd" keystoreType"JKS"/>

Felhantering

Loggning

Lokal Utvecklingsmilj?

Signeringstj?nsten

Att s?tta upp en utvecklingsmilj? f?r signeringstj?nsten ?r relativt enkelt:

  1. Ladda ner k?llkoden fr?n https://oppna-program-signing-service.googlecode.com/svn/signer-service/trunk/
  2. Kopiera hela katalogen core-bc/modules/web/doc/.ss till din hemkatalog (ex. '/Users//.ss'). Mer om vad den inneh?ller finns beskrivet i avsnittet [ InDepth#Konfiguration konfiguration ] ( InDepth#Konfiguration konfiguration )
  3. Navigera dig fram till core-bc/modules/web i ett terminal-/kommandof?nster
  4. K?r maven-kommandot 'mvn install jetty:run'

Vill man ist?llet anv?nda tomcat fr?n sin IDE b?r man ut?ver normal serverkonfiguration l?gga till en System Property via D-flaggan n?r tomcat startar. Detta g?rs enklast genom att:

  1. Dubbelklicka p? din server i eclipse server-vy
  2. Klicka p? l?nken Open launch configuration
  3. V?lj fliken Arguments
  4. I f?ltet VM arguments l?gg in '-Dssl.hostname.verification=lenient'
  5. F?r att sl? p? SSL/TLS debug l?gg ?ven in '-Djavax.net.debug=ssl'

Alla dessa inst?llningar som g?rs f?r tomcat ?r redan f?rkonfigurerade i web-modulens pom.xml om man v?ljer att anv?nda jetty.

S?tter man upp allt sj?lv s? kan man f?r certifikatkonfigurationen utg? fr?n [ InDepth#Certfikathantering produktionsmilj?ns ] ( InDepth#Certfikathantering produktionsmilj?ns ) konfiguration.

Referensapplikation

Testcertifkat

F?r att kunna testa ?r det bra om man anv?nder sig av testcertifikat. Dessa hittas under f?ljande l?nkar:

S?kerhet

Certifikathantering

Signeringstj?nsten anv?nder en hel del certifikat, i f?ljande avsnitt beskrivs vilka certifikat som anv?nds och vart i applikationen de h?r hemma. ?ven n?gra mindre exempel p? hur nya certifikat kan genereras och importeras kommer att visas.

Signeringstj?nsten agerar b?de som tj?nstekonsument samt tj?nsteproducent och i samtliga fall ?r det krav eller ?tminstone rekommenderat att kommunikationen sker insynsskyddat. I samtliga fall ?r detta implementerat med hj?lp av TLS. Det ?r dessutom krav eller rekommenderat att ?ven kunna autentisera klienten, detta g?rs antingen p? protokollniv? med sk. Mutual Authentication eller p? applikationsniv? med en biljett(ticket) som m?ste bifogas f?r att f? utnyttja tj?nsten.

Nedan visas en bild ?ver vilka certifikat som anv?nds samt vilken metod som anv?nds f?r att autentisera klienten:

F?rklaring till bilden:

  • Vid inkommande kommunikation b?r signeringstj?nsten exponera ett certifikat som ?r betrott av de vanliga webbl?sarna. Klienten beh?ver skicka med en biljett vid varje anrop f?r att signeringsstj?nsten skall kunna bekr?fta beh?righeten.
  • F?r utg?ende kommunikation med Logicas eID-tj?nst kr?vs att signeringstj?nsten betror det certifikat som eID-tj?nsten exponerar. Detta certifikat l?ggs in i signeringstj?nstens Truststore. eID-tj?nsten kan ?ven kr?va att n?gon form av biljett skickas med vid anrop.
  • F?r utg?ende kommunikation med AppX ?r det rekommenderat att AppX anv?nder sig av en TLS-anslutning med Mutual Authentication. Det kr?vs d? att signeringsstj?nsten har ett eget certifikat i sin keystore samt AppX publika nyckel i sin truststore. Samma sak g?ller hos AppX, dvs. sitt eget certifikat i keystore samt signeringstj?nstens certifikat i truststore.

F?r att konfigurera certifikaten kr?vs att man anv?nder sig av ett verktyg d?r man kan skapa keystores och truststores samt importera certifikat. Ett exempel p? s?dant verktyg ?r keytool som f?ljer med Javas JDK. Keytool ?r ett kommandotolkverktyg vilket inneb?r att man beh?ver en kommandotolk till hands f?r att utnyttja det. Nedan f?ljer n?gra exempel p? anv?ndbara kommandon:

  • Lista inneh?llet i en keystore/truststore *

    keytool -v -list -keystore keystore.jks

  • Skapa en keystore/truststore *

    keytool -genkey -keyalg RSA -alias selfsigned -keystore keystore.jks -storepass password -validity 360 -keysize 2048

  • Exportera den publika nyckeln fr?n ett keystore *

    keytool -export -alias mydomain -file mydomain.crt -keystore keystore.jks

  • Importera en publik nyckel i en befintlig truststore *

    keytool -import -trustcacerts -alias mydomain -file mydomain.crt -keystore keystore.jks

Mer information om keytool och olika kommandon kan hittas h?r:

  1. Skapa ett keystore med ett "CA-trustat" certifikat. Detta keystore pekas sedan ut i tomcat:ens server.xml. Se sist i avsnittet [ InDepth#Konfiguration konfiguration ] ( InDepth#Konfiguration konfiguration ) . I VGR:s fall anv?nds deras certifikat *.vgregion.se som ?r i formatet PKCS #12.
  2. Skapa ett till keystore med ett SHITS-certifikat. Detta certifkat anv?nds f?r Mutual Authentication gentemot AppX. Detta keystore pekas ut i signeringstj?nstens config.properties under variablerna keystore.*.
  3. Exportera den publika delen av SITHS-certifikatet och dela ut till alla konsumerande applikationer. De beh?ver ha detta certifikat i deras truststore.
  4. Skapa ett truststore d?r AppX och Logicas eID-tj?nsts publika nyckel importeras. Truststoret pekas ut ut i signeringstj?nstens config.properties under variablerna truststore.*. AppX m?ste skicka ?ver sin publika nyckel till signeringstj?nsten.

Kvarst?ende utvecklingspunkter

  • Som konsument skall man kunna begr?nsa valm?jligheten av vilka certifikat som man f?r signera med. T.ex. i fallet d?r AppX ?r beh?righetsskyddad med eID, d? skall AppX kunna v?lja att endast den inloggades certifikat skall f? anv?ndas f?r signering. Detta g?rs genom att skicka in ett id f?r certifikatet till signeringstj?nsten vilken sen endast exponerar signeringsrutan om certifikatet finns hos anv?ndaren. Detta kan g?ras genom att s?tt f?ltet subject eller issuers i api:t f?r pki-klienterna.

Anslut till signeringstj?nsten

In nedanst?ende guide kommer vi att g? igenom steg f?r steg hur man ansluter till signeringstj?nsten. F?r att underl?tta processen s? kommer vi att g?ra det iterativt, f?rsta steget ?r att f? det fungera ?ver vanlig http, n?sta steg blir att aktivera SSL/TLS och i sista steget l?gger vi p? Mutual Authentication.

  1. Det f?rsta vi beh?ver s?tta upp ?r en tj?nst dit signeringstj?nsten kan leverera signaturen. Detta kan vara antingen i form av en http- eller ftp-server, h?r kommer vi att beskriva fallet http-server. Tj?nsten m?ste acceptera POST med f?ljande parametrar i dess body:
  • envelope - XML-envelope inneh?llande signaturen
  1. N?sta steg blir att erbjuda signering till anv?ndarna i form av en html-sida. Fr?n denna html sida g?rs en Http POST till https://service-host.com/sign/prepare med f?ljande parametrar i dess body:
  • tbs - Data som skall signeras
  • submitUri - Uri till den tj?nst som vi satte upp i steg 1
  • clientType - Anger vilken typ av nyckel som skall anv?ndas vid signeringen. V?lj mellan: BankId, Telia, Nordea eller SITHS. Utel?mnas detta kommer signeringstj?nsten att presentera sida d?r anv?ndaren f?r v?lja.
  1. Nu ?r det dags f?r ett f?rsta f?rs?k, g?r allt bra s? kan du forts?tta till n?sta steg.
  2. Funkar allt nu s? ?r det dags att s?kra upp ?verf?ringen av signaturen. Detta g?rs i tv? steg
  3. Aktivera https p? den tj?nst som aktiverades i steg 1. Hur man g?r detta beror p? vilken webserver man anv?nder. Vid anslutning mot utbildnings-milj?n kan man anv?nda ett egenutf?rdat certifikat.
  4. Den publika delen av certifikatet m?ste skickas till en administrat?r av signeringstj?nten f?r import i dess truststore.
  5. Slutligen s? skall vi aktivera Mutual Authentication, detta f?r att den anslutande applikationen skall veta att det ?r signeringstj?nsten som skickar signaturen och inte n?gon annan som utger sig f?r att vara det. Detta t.ex. kan ske i en man-in-the-middle-attack. Vi g?r ?ven detta i tv? steg:
  6. Aktivera Mutual Authentication p? webbservern. Detta ?r levereant?rsspecifikt, p? tomcat t.ex. s?tts attributet clientAuth p? connector-taggen i server.xml till true.
  7. Ladda ner och l?gg in signeringstj?nstens [ klient-certifikat ] ( klient-certifikat ) i ditt truststore.
Add a custom footer
Add a custom sidebar
Clone this wiki locally