Leverancer

Release 1.1.14

Indeholder rettelser til QA kommentarer til:

...

Indledning

Certificate Revocation Authority (CRA) er et tool til NSP platformen der er ansvarlig for at opretholde en database med informationer om de certifikater der er trukket tilbage af udstederen. Databasen skal replikeres til alle NSP miljøer således at data er tilgængelig for SecurityValve og SecurityHandler. CRA er udviklet som en J2EE web applikation og anvender Spring til konfiguration og skedulering. Konfigurationsfilerne er specifikke for JBoss8/Wildfly som skal anvendes.

Begreber

• Certificate Authority (CA)
  En udsteder af X.509 certifikater. Nets og TDC er eksempler på CA’er. En CA har et enkelt rod CA certifikat og muligvis flere intermediate CA certificater som bruges til at udstede slutbruger-certifikater.
• Certificate Revocation
  Tilbagekaldelse af et certifikat. Hvis et certifikat bliver kompromiteret kan det stadig anvendes på grund af den struktur som X.509 certifikater har. En CA vælger derfor at tilbagekalde et certifikat hvis det er nødvendigt.
• Certificate Revocation List (CRL)
  En liste af tilbagkaldne certifikater. Listen vedligeholdes og offentliggøres af en CA. Det er op til CA’en hvor mange forskellige CRL’er der indgår i infrastrukturen. Et certifikat udsted af en OCES CA, indeholder en URL til den CRL som certifikatet vil optræde på hvis det tilbagekaldes.
• Certificate Revocation Source (CRS)
  Boostrapping af CRA sker ved at angive et antal CRS’er, der til sammen indeholder alle de CRL’er der ønskes monitoreret i infrastrukturen. En CRS indeholder en eller to URL’er til CRL’er (en hvis der er tale om et OCES1 certifikat og 2 hvis det er et OCES2 certifikat) samt den certifikatkæde der knytter CRL’erne til NSP/OCES

Algoritme

For hver CRS som CRA er konfigureret med, hentes der en eller to CRL’er som gemmes i databasen. CRA verificerer først at CRS’en indeholder en valid OCES certifikatkæde og tjekker derefter om der er ændringer til CRL’erne. CRL’erne downloades, deres signatur verificeres og de tilbagekaldte serienumre gemmes i databasen. Hvis et af CA certifikaterne tilbagekaldes vil dette blive markeret i databasen således at alle certifikater, der peger på den tilhørende CRL, tilbagekaldes.

Logning

CRA logger til filen cra.log

Der benyttes en rolling file appender, hvor størrelsen af log filerne og antallet af gemte log filer konfigureres med de to environment variable: LOG_MAX_FILE_SIZE og LOG_MAX_BACKUP_INDEX.

Oprydning

Der kan foretages løbende oprydning i historikken af revokerede certifikater, som findes i en given spærreliste, og hvis de ikke længere fremgår, så fjernes de.

Oprydning kan aktiveres af driften ved at kalde oprydningsjobbet.

Der er oprettet 4 forskellige oprydninger, som kan aktiveres og vil blive udført, hvis jobbet aktiveres:

• cleanIfRootExpiredActivated
  Hvis et rodcertifikatet fra certificateRevocationSources (Se bootstap.xml) er udløbet, så findes id fra crl tabellen vha. certifikatets url (Se Endpoints), og bruges til at slette rækker fra revoked vha. crlid (Se Revokeringer).
  Hvis der er et tilhørende intermediatecertifikat, så slettes det også på samme måde, som for rodcertifikatet.
• cleanIfIntermediateExpiredActivated
  Hvis ikke rodcertifikatet er udløbet, så checkes det om intermediatecertifikat er udløbet. Hvis det er udløbet, så slettes det på samme måde, som beskrevet for rodcertifikat.
• cleanIfGhostUrlActivated
  Hvis ikke rod- eller intermediatecertifikatet er expired. Så finder vi alle aktive url'er (både for rod- og intermediatecertifikater) fra certificateRevocationSources (Se Endpoints). Oplysninger tilknyttet certifikater som findes i cachen, men som ikke er aktive, slettes fra crl og revoked tabellen.
• cleanIfGhostSerialNumberActivated
  Hvis ikke rod- eller intermediatecertifikatet er expired. Hvis listen af revoked serialnumber (Se Revokeringer) indeholder værdier, der ikke kan findes i  den aktive liste af serialnumbers, så slettes de fra databasen.

Installation

Kildekode

Kildekoden til CRA kan hentes gennem NSPs SVN:
https://svn.nspop.dk/svn/components/cra

CRA fra version 1.1.8 blevet omlagt til at kunne afvikles vha. docker-compose. Derfor er CRA blevet opdelt i følgende maven moduler:

• cra-app: Indeholder logik for opdaterings- og oprydningsjob. Desuden er der filer til at bygge cra.war filen. Det er basalt set de filer, der før var indeholdt i cra-projektet inden dockerfisering.
• cra-db: De filer der bruges til at bygge 'cradb'. Før har dette ligget udenfor CRA modulet.
• cra-crl-stub: Løsning  der udstiller en servlet, hvor man kan hente CRL-filer. Hvis ikke man inkludere cra-crl-stub i docker-compose, så hentes CRL på www.
• cra-qa: Her samles test-rapporter (jacoco) fra andre moduler og aggregeres.
• cra-parent:  Rod modulet til ovenstående moduler. Indeholder desuden compose folder, hvor docker-compose-, konfigurations- og databasefiler er placeret.

Kompilering

CRA leveres gennem NSP’s SVN systemet:

svn co https://svn.nspop.dk/svn/components/cra/release-x.y.z cra

Efter checkout skal projektet bygges med Maven således:

mvn install

Følgende filer udgør nu leverancen og anvendes i resten af installationsvejledningen:

cra/cra-app/target/cra.war
compose/configuration/cra/bootstrap.xml
compose/configuration/cra/config.xml
compose/configuration/cra/seal.xml
compose/configuration/cra/services.xml
compose/configuration/cra-ds.xml
compose/configuration/database/drop-create-db.sql
compose/configuration/log4j-cra.xml
compose/configuration/log4j-nspslalog-cra.properties
compose/configuration/nspslalog-cra.properties

Deployment

Deployment udføre vha. docker-compose.  Der findes 3 udgaver til deployement - development, test og release.

• Development: del-komponenterne cra-db, cra-crl-stub og cra-app bygges.
• Test: Servicene  hentes fra docker repository - men evt. stubbede komponenter kan stadig bygges.
• Release: Her er det kun CRA servicen og opsætningen er  er angivet.

Opsætningen  af cra- og cradb-servicen er beskrvet i efterfølgende afsnit.

Et eksempel på deployment vha. docker-compos:

docker-compose -f compose/development/docker-compose.yml up --build

Ved at angive --build, så bygges der docker images ud fra de Dockerfile-filer findes i de moduler, der skal bygges.

Konfiguration

For alle 3 deployment er CRA servicen sat op, så  følgende konfigurationsfiler kopieres til  /pack/wildfly8/standalone/configuration:

compose/configuration/cra/bootstrap.xml
compose/configuration/cra/config.xml
compose/configuration/cra/seal.xml
compose/configuration/cra/services.xml

compose/configuration/log4j-cra.xml
compose/configuration/log4j-nspslalog-cra.properties
compose/configuration/nspslalog-cra.properties

bootstrap

XML filen bootstrap.xml indeholder et eksempel på en opsætning af et antal CRS’er. Dette eksempel skal slettes og korrekte CRS’er skal konfigureres inden selve applikationen deployes.
En detaljeret gennemgang af filerne og opsætningen heri kan findes i afsnittet Opsætning.

Database

Under  deployment  vha. docker-compose, så bliver filen cra-ds.xml placeret i /pack/wildfly8/standalone/deployments.

CRA-databasen bliver bygget under deployment - eller et image af bygget biver hentet fra repo. Opskriften på byg af cradb findesi filen Dockerfile under cra-db modulet.
Det image som bygges til  cradb basere sig på 'mariadb:10.1' og indeholder 2 sql-filer:

• drop-create-db.sql: anvendes til at oprette databasen
• create-test-data.sql:  indsætter testdata i databasen.

Både cra-ds.xml og drop-create-db.sql  indeholder et simpelt brugernavn og kodeord for databasebrugeren og skal derfor rettes inden de anvendes i et produktionsmiljø. Vær også opmærksom på at værdien af connection property rewriteBatchedStatements skal passe med den tilsvarende i services.xml som beskrevet nedenfor

Applikation

Samtidigt med at alle konfigurationsfilerne er placeres korrekt og databasen er startes op kan, så bygges cra-app modulet.
I cra-app kopieres filen target/cra.war kopieres over i /pack/wildfly8/standalone/deployments/.

Konfigurationsfilen bootstrap.xml skal opdateres inden CRA deployes.

Opsætning

Inden CRA kan deployes skal konfigurationsfilerne opdateres til at afspejle den del af certifikatinfrastrukturen man ønsker af monitorer.

seal.xml

Seal føderationen skal konfigureres alt efter om der er tale om et test eller et produktionsmiljø. Attributten class på federation elementet skal have værdien dk.sosi.seal.pki.SOSITestFederation i et testmiljøcertificateRevocationAuthority og dk.sosi.seal.pki.SOSIFederation i et produktionsmiljø. Ydermere skal propertien sosi:issuer have en passende værdi alt efter miljø.

services.xml

Heri skal propertien rewriteBatchedStatements have samme værdi som den har i cra-ds.xml

Fra version 1.1.8 er der desuden indført  følgende parametre til sikre en forbindelse til databasen:

• initialWaitForDatabaseConnection: Et fixed-delay på 20000 (20 sekunder) millisekunder
• retriesWhenDatabaseConnectionFail: Et antal forsøg på at få  forbindelse
• waitBetweenDatabaseConnectionRetries: Et delay på 5000 (5 sekunder) millisekunder.

Så med disse værdier, så afventer certificateRevocationStoreDatabase 20 sekunder inden den forsøger at få forbindelse til databasen første gang. Hvis det fejler, så ventes der 5 sekunder  inden der forsøges igen.

Ved 7. fejl så smides der en exception.

    <bean id="certificateRevocationStoreDatabase" class="dk.nsi.nsp.cra.db.DBCertificateRevocationStoreImpl" init-method="init">
        <constructor-arg ref="cra.db"/>
        <property name="rewriteBatchedStatements" value="true"/>
        <property name="cleanupSerialNumbersBatchSize" value="500"/>
        <property name="initialWaitForDatabaseConnection" value="20000"/>
        <property name="retriesWhenDatabaseConnectionFail" value="6"/>
        <property name="waitBetweenDatabaseConnectionRetries" value="5000"/>
    </bean>

Opsætning af certificateRevocationAuthority til brug ifm. schedulering af opdatering.

	<bean id="certificateRevocationAuthority" class="dk.nsi.nsp.cra.CertificateRevocationAuthorityImpl">
        <constructor-arg ref="certificateRevocationStoreDatabase"/>
        <constructor-arg ref="certificateRevocationSources"/>
        <constructor-arg ref="status"/>
        <constructor-arg ref="federation"/>
        <property name="revocationBatchSize" value="20000"/>
    </bean>

Opsætning af certificateRevocationCleanUp til brug ifm. schedulering af oprydning.

    <bean id="certificateRevocationCleanUp" class="dk.nsi.nsp.cra.CertificateRevocationCleanUpImpl">
        <constructor-arg ref="certificateRevocationStoreDatabase"/>
        <constructor-arg ref="certificateRevocationSources"/>
        <constructor-arg ref="status"/>
        <!--  Activate cleanup functionality -->
        <property name="cleanActivated" value="true" />
        <property name="cleanIfRootExpiredActivated" value="true" />
        <property name="cleanIfIntermediateExpiredActivated" value="true" />
        <property name="cleanIfGhostUrlActivated" value="true" />
        <property name="cleanIfGhostSerialNumberActivated" value="true" />
    </bean>

bootstrap.xml

Heri defineres de CRS’er der skal bruges til at bootstrappe CRA. For hver CRS der defineres vil CRA læse den konfigurerede CRL samt alle CRL’er fra certifikaterne i certifikatkæden. Der er to måder at konfigurere en CRS. Enten vd at angive et slutbruger certifikat eller ved direkte at angive en url til en CRL og dens tilhørende certifikat.

Keystore CRS

   <bean id="testCertificateRevocationSource" class="dk.nsi.nsp.cra.bootstrap.KeyStoreCertificateRevocationSource">
        <constructor-arg>
            <bean id="testKeystore" class="java.io.File">
                <constructor-arg value="/pack/cra/cra-test.keystore" type="java.lang.String" />
            </bean>
        </constructor-arg>
        <constructor-arg value="!234Qwer" type="java.lang.String" />
        <constructor-arg value="SOSI:ALIAS_SYSTEM" type="java.lang.String" />
        <constructor-arg ref="certificateResolver"/>
    </bean>

Måden en KeyStoreCertificateRevocationSource konstrueres på, er ved at tage den offentlige del af et certifikat og gemme det i en Java Keystore fil. Filen, aliaset og kodeordet til filen (Ikke til den private nøgle) konfigureres derefter som de tre første constructor-arg's til en KeyStoreCertificateRevocationSource. Det sidste argument skal altid være certificateResolver

For at aktivere en CRS tilføjes den til listen certificateRevocationSources.

Java Keystore filer laves med programmet keytool der følger med Java. Der henvises til Java dokumentation for eksempler på hvordan man importerer et certifikat.

Remote CRS

    <bean id="systemtest10CertificateRevocationSource" class="dk.nsi.nsp.cra.bootstrap.RemoteCertificateRevocationSource">
        <constructor-arg value="http://m.aia.systemtest10.trust2408.com/systemtest10-ca.cer" type="java.lang.String" />
        <constructor-arg value="http://crl.systemtest10.trust2408.com/systemtest10.crl" type="java.lang.String" />
        <constructor-arg ref="certificateStore"/>
        <constructor-arg ref="certificateResolver"/>
    </bean>

Hvis man ikke har et certifikat udstedt af den CA man ønsker at tilføje kan en RemoteCertificateRevocationSource konstrueres ved at angive URL’en til CA certificatet og URL’en til den CRL der er signeret af CA’en som de to første constructor-arg's. De to sidste argumenter skal altid være certificateStore og certificateResolver

For at aktivere en CRS tilføjes den til listen certificateRevocationSources.

Overvågning

Der er følgende muligheder for at overvåge CRA.

cra-servlet.xml

Der er defineret følgende endpoints i der giver følgende muligheder:

...

<serverurl>/cra/job/revokeUpdate/start

...

<serverurl>/cra/job/revokeUpdate/status

...

<serverurl>/cra/job/cleanupRevocationLists/start

...

<serverurl>/cra/job/cleanupRevocationLists/status

...

Databasen

CRA har et relativt simpelt databaselayout bestående af to tabeller. En tabel med CRL endpoints og en tabel med revokerede certifikater.

Endpoints

Tabellen crl har følgende felter:

• id
  Teknisk identifikation af rækken - Allokeres automatisk af MySQL.
• url
  Det endpoint hvor en CRL hentes fra.
• lastmodified
  Opdateres med et nyt timestamp hver gang CRL’en downloades fra endpointet.
• nextupdate
  Det tidspunkt (timestamp) den sidst hentede version af CRL’en er gyldig til.

Revokeringer

Tabellen revoked har følgende felter:

• id
  Teknisk identifikation af rækken - Allokeres automatisk af MySQL.
• crlid
  Teknisk identifikation af den række fra tabellen crl som denne revokering kommer fra.
• serialnumber
  Serienummerer på det certifikat der er trukket tilbage.
• added
  Det tidspunkt (timestamp) rækken blev tilføjet til tabellen.
• since
  Det tidspunkt (timestamp) revokeringen trådte i kraft.

Hvis en CRL er udstedt af en CA og denne CA trækkes tilbage, så vil alle dens rækker i revoked blive slettet og en enkelt række med NULL i serialnumber vil blive oprettet. Et certifikat skal derfor betragtes som trukket tilbage hvis dets CRL enpoint findes i crl og dets serienummer findes i revoked eller der findes en række med serienummeret NULL.

CRL Stub

Når  CRA servicen skal hente crl filer, så kalder sender den et http request. Det er dog ikke altid at disse services der  udstiller CRL filerne er tilgængelige.
For at undgå afhængigheder  til andre services, så er det nu muligt at placere CRL filer i modulet cra-crl-stub.

For at CRA servicen sender sit request til stubben, så skal følgende gøres:

• Hvis vi antager at den CRL file vi skal bruge finde på denne http adresse: http://crl.XYZ.com/ABC.crl

  1. I docker-compose tilføjes crl.XYZ.com som alias

     Code Block
     language yml title docker-compose.yml
     crl-stub: networks: cra_net: aliases: - crl.XYZ.com

  2. Under compose/configuration/crl/resources oprettes en folder 'crl.XYZ.com'
  3. Filen ABC.crl downloades fra http://crl.XYZ.com/ABC.crl og placeres i folderen 'compose/configuration/crl/resources/crl.XYZ.com/'
  4. Applikationerne skal genstartes vha. "docker-compose down" og  "docker-compose up"