Systembeskrivelse for eksterne aktører - Grunnboken Test

Systembeskrivelse for eksterne aktører
Med milepæl 3 gir Kartverket neste innblikk i den kommende løsningen for elektronisk tinglysing.
Milepæl 3 gir eksterne aktører mulighet til å få innsikt i grensesnitt og anvendt teknologi for
interaksjon med det nye grunnboksystemet.
Løsningen for elektronisk tinglysing bygger videre på de konsepter og teknologier som er anvendt for
Ny grunnbok, og tilbyr et nytt Web Service basert api for elektronisk innsending av dokumenter til
tinglysing. Grensesnittet tilbyr tjenester for validering av dokumenter før innsending, tjenester for
innsending til tinglysing samt tjenester for uthenting av tinglysingsresultat. I tillegg tilbys den
funksjonalitet som ble introdusert med Ny grunnbok.
Konsepter
Melding
Den minste enhet som kan sendes til tinglysing er en melding inneholdende ett eller flere
dokumenter, hvert bestående av en eller flere rettsstiftelser. Alle dokumenter i en melding
behandles som en transaksjonell enhet, slik at alle dokumenter blir enten avvist, nektet eller tinglyst.
Alle dokumenter i en melding får samme prioritet, men behandles i en gitt rekkefølge som må
eksplisitt angis av innsender i et følgebrev ved innsending.
Dokument
Den enheten som tinglyses kalles et dokument, og består av en eller flere rettsstiftelser som tinglyses
i den rekkefølge de er oppført i dokumentet.
Før et dokument kan legges i en melding og sendes til tinglysing må det pakkes i en digital struktur og
signeres digitalt av de personer som måtte være nødvendig for å få dokumentet tinglyst. Alle
signaturene for et dokument gjelder hele dokumentets innhold, det vil si at alle signatarene må
signere på eksakt det samme innholdet. Det er ikke mulig å signere på enkeltelementer i
dokumentet.
Når et dokument har blitt signert av alle parter må innsender sørge for å kombinere signaturene
samt forsegle strukturen. Da er dokumentet klart til å legges i en melding sammen med eventuelle
andre signerte dokumenter.
Dokumenter som skal inngå i en melding kan opprettes og signeres uavhengig av hverandre.
Signeringsteknologien sikrer integriteten til innholdet, det vil ikke være mulig å endre på innholdet av
et signert dokument. Signeringsløsningen vil sjekke om noen av sertifikatene som ble brukt til å
signere med har blitt tilbakekalt eller har utløpt, slik at kun gyldige sertifikater vil bli akseptert.
Beskrivelse av hvordan man kan sette sammen en signert melding basert på det resultatet man får
når man signerer noe med BankId er beskrevet i seksjonen Innsending av signerte dokumenter.
Følgebrev
Før innsending må innsender lage et følgebrev som ved hjelp av interne dokumentreferanser i
meldingen lister opp alle dokumenter som meldingen inneholder. Følgebrevet angir dermed entydig
hvilke dokumenter som inngår i meldingen uten at dokumentene selv må være en del av følgebrevet.
Følgebrevet legges i en digital struktur som signeres av innsender.
Det signerte følgebrevet og de signerte dokumentene legges i en åpen meldingsstruktur som sendes
til tinglysing. Rekkefølgen på dokumentene i meldingen må være den samme som angitt i
følgebrevet.
Vedlegg
Støtte for vedlegg til dokumenter er ikke planlagt for første versjon av systemet. Det innebærer at
dokumenter som krever vedlegg vil bli avvist ved elektronisk innsending og vil måtte sendes inn på
papir. Et eksempel kan være dokumenter der noen av de berørte parter er mindreårige.
Innsendingsgrensesnitt
Milepæl 3 inneholder en prototype på signeringsløsning, basert på SEID-SDO med bruk av BankID
XML og XSL for visning av dokumenter til signering for sluttbruker.
Innsendingsapi for tinglysing støtter validering og tinglysing av signerte og usignerte meldinger som
inneholder instruksjoner om dokumenter som skal tinglyses. Grensesnittet er tilpasset
signeringsløsningen på en slik måte at datastrukturen som representerer dokumentene, og som
sendes inn i tjenestene, er den samme som brukes som grunnlag for visning med XSL med BankID
eller med andre eId-leverandører som støtter BIDXML.
Som kontaktpunkt for BankID henvises til https://www.bankid.no/For-partnere/
Se også egen seksjon Innsending av signerte dokumenter for en beskrivelse av dette.
Tjenester
For milepæl 3 er det implementert fire funksjoner for innsending. Disse kan brukes uavhengig av
grunnbokens øvrige tjenester, og de er uavhengig av hverandre.
Signerte data vil kunne brukes i tjenestene for å validere og å sende melding til tinglysing i
produksjon og i test. For signerte meldinger i test kommuniserer grunnboksystemet med BankID i
test, og aksepterer meldinger signert av sertifikater utstedt fra BankID test CA.
Følgende tjenester tilbys:
validerMelding
Tjenesten kan kalles for å validere en signert eller en usignert melding, både i test og i produksjon.
Valideringstjenesten gir ingen garanti for at dokumenter som validerer uten feil vil kunne tinglyses.
Formålet med tjenesten er å forsøke å finne opplagte mangler i dokumenter før de sendes til
signering, eller gjøre oppmerksom på eventuelle forhold på valideringstidspunktet som kan hindre
tinglysing.
Tjenesten vil for signerte meldinger slå opp data samt validere mot eId-leverandørers testsystemer.
sendTilTinglysing
En usignert (i test) elle signert melding sendes til behandling i tinglysing. Man sender med en intern
referanse, forsendelsesreferanse som bruker som referanse i avleverende fagsystem. Hvis meldingen
blir lagret i Kartverkets systemer så vil den intern bli tilordnet en innsendingId. Det er denne
innsendingId man bruker når man skal hente informasjon om meldingen. Signerte meldinger kan
sendes til tinglysing både i test og i produksjon, mens usignerte meldinger kan sendes til tinglysing
kun i test. I forkant kan det være nyttig å ha testet at meldingen validerer. Det vil kunne være de
samme feilene som propageres fra sendTilTinglysing som fra validerMelding, gitt at valideringen
feiler på valideringer på tidspunktet den blir validert ved mottak.
Tjenesten vil i produksjon slå opp data samt validere mot eId-leverandørers produksjonssystemer.
Dette har en kostnad, men det er ikke avklart hvem denne kostnaden vil belastes. Tjenesten
returnerer en forsendelsesstatus som inneholder informasjon om mottatt melding, eventuelle
avvisninger samt en unik innsendingId.
hentStatus
Etter at en melding er mottatt av systemet kan man hente oppdatert behandlingsstatus for den
innsendte meldingen.
Sekvensdiagram
Det tilbys eksempelklienter for Java og .NET som viser eksempler på hvordan innsendingsapiet kan
brukes for validering og tinglysing av dokumenter.
Forsendelse
Dokumenter som ønskes tinglyst som en enhet samles som en signert eller en usignert melding i en
forsendelse. Meldingen inneholder ett eller flere dokumenter, samt et følgebrev som refererer til de
individuelle dokumentene, og dermed også bekrefter hvor mange dokumenter forsendelsen
inneholder og hvilken rekkefølge disse har. Følgebrevet inneholder også innsenders
identifikasjonsnummer, og det valideres at innsender er en eksisterende person eller organisasjon.
Innsender må signere på følgebrevet med sitt brukerstedssertifikat.
Innsendingsgrensesnittet er utformet med henblikk på at dokumenter skal kunne opprettes og
signeres uavhengig av grunnboksystemet, dersom innsender har tilstrekkelig informasjon. Blant
annet må innsender ha informasjon om koder som skal anvendes i dokumentene som skal tinglyses.
Informasjon om koder er statisk og vil kunne hentes på forhånd. Innsendte koder som ikke kan
oversettes til koder systemet kjenner igjen vil forårsake systemfeil.
Forsendelsesstatus
Tjenestene for validering og tinglysing returnerer en forsendelsesstatus. For meldinger som er sendt
til tinglysing og som er mottatt av systemet, kan oppdatert forsendelsesstatus hentes gjennom
tjenesten hentStatus. Denne statusen hentes med den innsendingId man fikk tilordnet gjennom at
meldingen ble sendt til tinglysingen med sendTilTinglysing.
Hvis dokumentene i meldingen er avvist vil forsendelsesstatus og statusfeltene saksstatus og
behandlingsutfall inneholde den overordnede tilstanden, men avvisningsinformasjon vil inneholde
kontrollresultat med begrunnelse for avvisningen i form av strukturert informasjon med koder, men
også med lesbare tekster.
Dersom dokumentene i meldingen har blitt registrert i grunnboken inneholder forsendelsesstatus
blant annet informasjon om registreringstidspunkt (prioritet), samt tildelte dokumentnummer og
rettsstiftelsesnummer. Disse er angitt med en kobling til innsenders oppgitte referanser for hhv.
dokumentene og rettsstiftelsene. Når dokumentene i meldingen er tinglyst gjøres det også
tilgjengelig et sett av signerte grunnboksutskrifter for de registerenheter som er berørte av denne
tinglysingen.
Feilhåndtering
For forventede feil som systemet håndterer, f.eks. valideringsfeil, returneres begrunnelsene i form av
informasjon i behandlingsstatus, som beskrevet over.
Ved uventede feil, eller dersom meldingen ikke er lesbar, vil slike feil propageres som en SOAPFault
med en SystemException som underliggende årsak. I slike tilfeller må avleverende system forsøke å
rette feilen i sitt fagsystem før meldingen sendes på nytt, eller vente til eventuelle feil er rettet i
mottakende system. Et eksempel på en slik feil kan være innsendt XML som ikke er i henhold til
skjema.
Kontekstinformasjon
I forbindelse med signering av dokumenter er det krav til å vise tilleggsinformasjon (kontekstinformasjon) for sluttbruker, slik som navn på personer, for at sluttbruker skal få bedre forståelse av
hva det signeres på. Ved innsending må alltid fullstendig identifikator for hvert dataelement sendes
inn, selv om denne ikke nødvendigvis er vist for sluttbruker. Også kontekstinformasjon vist for
sluttbruker må sendes inn, selv om systemet i utgangspunktet ikke har behov for denne.
Det stilles krav til validering av innsendt kontekstinformasjon. Eksempelvis er det krav om at navn og
identifikasjonsnummer på personer skal valideres mot data fra folkeregisteret, mens kodeverdi og
navn på koder skal valideres mot systemets egne data. Systemet avviser en melding dersom
validering av kontekstinformasjon feiler.
Prosessflyt
Systemet implementerer en asynkron prosessflyt, slik at tinglysingskallet kun sikrer at systemet har
mottatt meldingen. Videre behandling av meldingen skjer asynkront. Innsendingsapiet har tjenesten
hentStatus som innsender kan kalle for å følge med på meldingens behandlingsstatus. Når tjenesten
for å tinglyse en melding har returnert uten feil, garanteres det at meldingen er mottatt av systemet
og at et påfølgende kall som henter behandlingsstatus vil returnere en ikke-tom respons.
Funksjonalitet og begrensninger
I Milepæl 3 er alle 8 typer rettsstiftelser som skal kunne sendes inn av eksterne aktører i første
versjon av systemet tilgjengelig for elektronisk innsending:
 Eierskifte matrikkelenhet
 Overdragelse av festerett
 Eierskifte borettslagsandel
 Pant
 Annen heftelse
 Sletting
 Tvangsforretning
 Anmerkning på person
Dokumentasjon av rettstypene finnes i UML-modellen for innsending. Implementasjonen av hver
rettstype er ikke komplett, det vil si at det kan være valideringsregler og annen forretningslogikk som
vil komme på plass senere. Det samme gjelder valideringslogikk rundt selve forsendelsen. Enkelte
typer rettsstiftelser skal kun kunne sendes inn av en spesifikk aktør, slik som Statens
Innkrevingssentral, kontroll av dette er ikke implementert i milepæl 3.
Innsendingsgrensesnittet krever at XML-delen tilhørende BIDXML kan valideres mot XSD for
namespacet for innsendingsskjemaet. Dette må oppgis på standardisert vis med
namespacehenvisning i XML-dokumentet. Det kreves også at XSL-delen tilhørende BIDXML kan
valideres mot godkjente versjoner av XSL transformasjonen. Innpakket XSL må således være binært
identisk med en versjon som er publisert av Kartverket.
Innsending av signerte dokumenter
For å forenkle testingen av hvordan man må bygge opp rettsstiftelser, så støtter innsendings-api i
test validering samt mottak og behandling av usignerte meldinger.
En forsendelse med usignert melding vil representere grunnlaget for en signert melding. I de
tilfellene så vil det som representerer henholdsvis <dokument> i en usignert melding mappes inn
som en <SDODokument> i signert melding. Det samme gjelder for følgebrev. Denne beskrivelsen vil
vise hvordan man med utgangspunkt i en forsendelse med usignert dokument kan etablere en
forsendelse med ett eller flere signerte dokumenter samt et signert følgebrev.
Mapping fra signert til usignert melding
Dette eksempelet viser mapping av en forsendelse med pant, inkludert følgebrev til en variant som
inneholder signerte dokumenter i form av SEID-SDO og signerte objekter basert på BIDXML. Merk at
pantedokumentet er forkortet noe for å redusere mengden tekst i eksempelet, men alle de andre
relevante feltene er fylt ut. I Eksempelet er det oppgitt noen kommentarer i xml-strukturen markert
som <-- Ref 1 --> for eksempel. Dette er gjort for å forenkle referansen til dette xmlelementet etterfølgende. Prosessen fra å konvertere en usignert melding til en signert melding vil
bestå av følgende trinn:
1. Hvert <dokument> under <dokumenter> i <usignertMelding> konverteres til et
SDODokument som inneholder <dokument> uendret som en del av det signerte grunnlaget i
<SignersDocument> i sdo på BIDXML-format.
2. Signaturene i forsendelsen under <ikkeDigitaleSignaturer> fjernes. Disse
signaturene representerer de parter som må signere dokumentene fra 1.
3. For hvert dokument som refereres i følgebrevet, så henter man en referert Digest fra den
assosierte signatur i SDO fra elementet <HashedData>. Dette hash/algoritmeparet angis
som <digest > og <digestAlgoritme> under elementet <referanse>, der man har
<gjelderDokumentreferanse> liggende fra det usignerte dokumentet.
Eksempler på denne konverteringen vises i etterfølgende avsnitt.
Usignert pant med følgebrev
<?xml version="1.0" encoding="ISO-8859-1"?>
<forsendelse xmlns="http://kartverket.no/grunnbok/wsapi/v2/domain/innsending">
<forsendelsesreferanse>1</forsendelsesreferanse>
<usignertMelding>
<dokumenter>
<dokument>
<!-- Ref 1 -->
<dokumentreferanse>1</dokumentreferanse>
<rettsstiftelser>
<pant>
<rettsstiftelsesreferanse>pant.test</rettsstiftelsesreferanse>
<rettsstiftelsestype>
<kodeverdi>OB_PDO</kodeverdi>
<navn>PANTEDOKUMENT</navn>
</rettsstiftelsestype>
<rettighetshavere>
....
</pant>
</rettsstiftelser>
</dokument>
</dokumenter>
<foelgebrev>
<-- Ref 2 -->
<innsendersIdentifikasjonsnummer>911044110</innsendersIdentifikasjonsnummer>
<dokumentrekkefoelge>
<referanse>
<gjelderDokumentreferanse>1</gjelderDokumentreferanse>
</referanse>
</dokumentrekkefoelge>
</foelgebrev>
</usignertMelding>
<ikkeDigitaleSignaturer>
<signatur>
<gjelderDokumentreferanse>1</gjelderDokumentreferanse>
<personidentifikasjonsnummer>11111111111</personidentifikasjonsnummer>
</signatur>
</ikkeDigitaleSignaturer>
</forsendelse>
Signert forsendelse med signert dokument for pant og signert følgebrev
Det signerte dokumentet opprettes ved at hvert enkelt element <dokument> etableres som en SDO
signert av rettighetshavere. I tillegg til dette opprettes følgebrevet som en SDO signert med
brukerstedsertifikatet til den formidlende part. Det trenger ikke å være noen relasjon mellom denne
virksomheten i virksomhetssertifikatet og det som er oppgitt som innsender i følgebrevet.
Forsendelsen med de signerte dokumentene vil etter at de signerte elementene i form av
SDODokument har blitt samlet inn fra signeringsprosessen se slik ut:
<?xml version='1.0' encoding='ISO-8859-1'?>
<forsendelse xmlns="http://kartverket.no/grunnbok/wsapi/v2/domain/innsending">
<forsendelsesreferanse>17</forsendelsesreferanse>
<signertMelding>
<dokumenter>
<SDODokument>
<signertDokument>
<!-- Fra Ref 1, Base 64 encodet sdo med <dokument> som rotnode i BIDXML -->
PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iaXNvL....
</SDODokument>
</dokumenter>
<foelgebrev>
<SDODokument>
<!-- Fra Ref 2, Base 64 encodet sdo med <foelgebrev> som rotnode i BIDXML -->
PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iaXNvL....
</SDODokument>
</foelgebrev>
</signertMelding>
<ikkeDigitaleSignaturer/>
</forsendelse>
Merk her at hvert enkelt <SDODokument>, enten det er et følgebrev eller et dokument vil være et
komplett SDO dokument som deretter har blitt base 64 encodet. <SignersDokument> i denne
SDO-strukturen vil være en BIDXML struktur, der XML-delen er en identisk kopi av det som er hentet
fra Ref 1 i det usignerte eksempelet.
Det er ikke mulig å oppgi signaturer i signerte dokumenter, dette skal hentes fra VA-tjenestene i form
av oppslag fra BankId som en del av valideringen av dokumentet. Signaturelementet
<ikkeDigitaleSignaturer> er derfor tomt. SEID SDO dokumentet vil før base 64 encodingen
for både <dokument> og <foelgebrev> likne på dette:
<?xml version="1.0" encoding="utf-8"?>
<SDOList xmlns="http://www.npt.no/seid/xmlskjema/SDO_v1.0"
xmlns:XAdES="http://uri.etsi.org/01903/v1.2.2#"
xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<SDO>
<SEIDSDOVersion>1.0</SEIDSDOVersion>
<SDODataPart>
<SignatureElement>
<CMSSignatureElement>
<SDOProfile>SEID-SDO-Basic-V</SDOProfile>
<SignaturePolicyIdentifier>
<SignaturePolicyId>
<SigPolicyId>
<XAdES:Identifier>urn:oid:2.16.578.1.16.4.1</XAdES:Identifier>
</SigPolicyId>
</SignaturePolicyId>
</SignaturePolicyIdentifier>
<SignersDocumentFormat>
<MimeType>text/BIDXML</MimeType>
</SignersDocumentFormat>
<HashedData>
<ds:DigestMethod Algorithm="SHA-256"/>
<ds:DigestValue>miF0ND68NTmdhdFosjMqI8qbqyxRx3WUPF2rNQcfpPc=</ds:DigestValue>
</HashedData>
<CMSSignature>
MIAGCSqGSIb3DQ
</CMSSignature>
<UserCertificateAndRevocationData>
<RevocationValues>
<XAdES:OCSPValues>
<XAdES:EncapsulatedOCSPValue>
MIIHGTCCAS6hX...
</XAdES:EncapsulatedOCSPValue>
</XAdES:OCSPValues>
</RevocationValues>
</UserCertificateAndRevocationData>
</CMSSignatureElement>
</SignatureElement>
</SDODataPart>
<SDOSeal>
<SDOSignature>
<CMSSignatureElement>
<SDOProfile>SEID-SDO-Basic-V</SDOProfile>
<SignaturePolicyIdentifier>
<SignaturePolicyId>
<SigPolicyId>
<XAdES:Identifier>urn:oid:2.16.578.1.16.4.1</XAdES:Identifier>
</SigPolicyId>
</SignaturePolicyId>
</SignaturePolicyIdentifier>
<SignersDocumentFormat>
<MimeType>text/plain</MimeType>
</SignersDocumentFormat>
<HashedData>
<ds:DigestMethod Algorithm="SHA-256"/>
<ds:DigestValue>CfV9X7Jn6TOCfnP/zbbvaZXtkcDJwZ9lY2sys+cFydI=</ds:DigestValue>
</HashedData>
<CMSSignature>
MIAGCSqGSIb3DQEHAq...
</CMSSignature>
<UserCertificateAndRevocationData>
<RevocationValues>
<XAdES:OCSPValues>
<XAdES:EncapsulatedOCSPValue>
MIIG8TCCAQahXj...
</XAdES:EncapsulatedOCSPValue>
</XAdES:OCSPValues>
</RevocationValues>
</UserCertificateAndRevocationData>
</CMSSignatureElement>
</SDOSignature>
</SDOSeal>
<Metadata>
<ValuePair>
<Name>MerchantDesc</Name>
<Value>Merchant description?</Value>
</ValuePair>
</Metadata>
<SignedObject>
<SignersDocument>
PEJhbmtJRFhNTD48QklEWE1MPjw/eG1sIHZlc...
</SignersDocument>
</SignedObject>
</SDO>
</SDOList>
For <dokument> elementet med Ref 1 som vist i eksempelet for den usignerte meldingen så vil
det som er oppgitt som <SignersDocument> i SDO være BIDXML. Grensesnittet som
benyttes mot BankId vil sørge for at dette er formattert korrekt. Man skal ikke lage BIDXML
strukturen selv. Det eneste man skal sende inn til denne signeringen er det som er payloaden for
<dokument> samt en identisk binær kopi av det som har blitt levert ut av gyldig xsl for innsending
som er hentet fra en av kartverkets releaseversjoner. Det er denne visningen som benyttes av BankId
når man skal presentere dokumentet i signeringsdialogen.
Denne strukturen i <SignersDocument> vil etter base64 decoding likne på dette:
<BankIDXML><BIDXML><?xml version="1.0" encoding="ISO-8859-1"?>
<dokument>
<!-- Ref 1 -->
<dokumentreferanse>1</dokumentreferanse>
<rettsstiftelser>
<pant>
<rettsstiftelsesreferanse>pant.test</rettsstiftelsesreferanse>
<rettsstiftelsestype>
<kodeverdi>OB_PDO</kodeverdi>
<navn>PANTEDOKUMENT</navn>
</rettsstiftelsestype>
<rettighetshavere>
....
</pant>
</rettsstiftelser>
</dokument>
</BIDXML><BIDXSL><?xml version="1.0" encoding="ISO-8859-1"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:inn="http://kartverket.no/grunnbok/wsapi/v2/domain/innsending"
version="1.0"
exclude-result-prefixes="xsi inn">
<xsl:output method="html" encoding="ISO-8859-1" doctypesystem="http://www.w3.org/TR/html4/loose.dtd"
....
</xsl:stylesheet>
</BIDXSL></BankIDXML>
For følgebrevet så er det et spesielt hensyn som må tas. For at det ikke skal være mulig å bytte ut et
signert dokument med et annet, så krever vi at det blir oppgitt en <digest> samt tilhørende
<digestAlgoritme> i følgebrevet som refererer til dokumentet. Det betyr at det usignerte
følgebrevet i <foelgebrev> elementet i det usignerte eksempelet må kompletteres for å bli
gyldig. I det oppgitte eksempelet som vi har referert, så vil XML-biten i BIDXML for det signerte
følgebrevet måtte utvides slik:
<?xml version="1.0" encoding="ISO-8859-1"?>
<foelgebrev xmlns="http://kartverket.no/grunnbok/wsapi/v2/domain/innsending">
<!-- Ref 2 -->
<innsendersIdentifikasjonsnummer>911044110</innsendersIdentifikasjonsnummer>
<dokumentrekkefoelge>
<referanse>
<gjelderDokumentreferanse>1</gjelderDokumentreferanse>
<digest>miF0ND68NTmdhdFosjMqI8qbqyxRx3WUPF2rNQcfpPc=</digest>
<digestAlgoritme>SHA256</digestAlgoritme>
</referanse>
</dokumentrekkefoelge>
</foelgebrev>
Det er dette grunnlaget, inkludert digest-referanser som skal signeres med brukerstedssertifikat. Når
følgebrevet valideres så vil vi validere dette opp mot den beregnede Digest for det signerte
dokumentet. Man trenger ikke å beregne denne, denne hentes fra <HashedData> oppgitt i SDO
for de signerte dokumentene. Man kan lage en enkel parser for dette selv, eller eventuelt bruke
BankId sin implementasjon som inneholder klasser og metoder for å konvertere bytes med XML-data
til en SDO-struktur i Java eller C#. Gyldigheten av disse refererte verdier vil valideres når dokumentet
valideres, og så slipper man å lage programkode for å beregne Digest over det som er BIDXML
strukturen som man normalt ikke vil se eller behandle selv.
Hvis det er flere dokumenter i en melding, så gjentas denne prosessen for hvert av de dokumentene
som man skal signere. En SDO kan kun inneholde et <dokument> eller et <foelgebrev> som
rotnode inne i BIDXML. Forutsetningen er at man signerer på et dokument i sin helhet. Disse kan
signeres av rettighetshavere i forskjellige løsninger, slik som i en nettbank eller en signeringsportal.
Når det er flere rettighetshavere som skal signere, så vil man normalt samle inn flere SDO fra BankId
for disse signeringene for så å kombinere dette inn i en SDO med flere signaturer. Dette er mulig når
det signerte innholdet er likt, men det er flere rettighetshavere som skal signere.
For følgebrevet som skal signeres med brukerstedssertifikat så er det ikke noen spesielle krav til xsltransformasjonen som pakkes inn sammen med følgebrevet ut over de krav som eventuelt kommer
fra BankId. Kartverket leverer ikke fra seg noen xsl for følgebrevet og har derfor heller ikke noen
validering av dette innholdet.
Bruk av BANKID grensesnitt for å signere SDO
BankId tilbyr klientgrensesnitt og eksempelklienter i Java og C# for å implementere signeringsdialog
som brukersted, både for sluttbruker gjennom signering i nettleser, men også for serversidesignering
som brukersted.
For scenariet som dekker signering i nettleser så er det utenfor scopet til dette dokumentet å vise det
i sin helhet. Vi anbefaler at brukerstedet gjør seg kjent med den dokumentasjonen som finnes på
http://bankid.no på innlogget område. Her kan man laste ned eksempelkode og annen programvare
samt dokumentasjon som viser hvordan dette fungerer. Vi kan ikke gi en uttømmende forklaring på
hvordan dette fungerer her, men vi vil og noen henvisninger til de relevante grensesnittene som kan
brukes for å generere SDO som etterfølgende kan pakkes som et eller flere <SDODokument> i en
<SignertMelding>.
Signering av xml og xsl med banklagret sertifikat
Dette er den signeringsdialogen som skal brukes når det er en rettighetshaver med et personnummer
som skal signere. Det kan også brukes når man skal signere som organisasjon med banklagret
ansattsertifikat der sertifikatet peker ut en organisasjon. Se beskrivelsen i Sertifikattyper for å se
hvilke typer som kan brukes når.
Kodeeksemplene nedenfor benytter er skrevet i Java og benytter at klientbibliokteket for
bankidservere-java er tilgjengelig. Eksemplene viser ikke hele kildekodefilen, men utvalgte og antatt
relevante fragmenter. Eksempelet antar også at man har satt opp en BankId-klienten slik at denne
kan vises korrekt, eksempelvis slik:
Dette vil variere fra brukersted til brukersted. Kartverket stiller ingen krav til utforming her.
Initialisering av innhold til signeringsdialog for BIDXML
BIDSessionData sessionData = new BIDSessionData(session.getTransactionReference());
String signType = session.getSignType();
sessionData.setDataDescription(session.getDataDescription());
if ("xml".equals(signType)) {
sessionData.setDataToBeSignedXMLFormat(getXsl());
sessionData.setDataToBeSigned(getXml());
} else {
throw new ServletException(
"This BankID signature type is not supported: " + signType);
}
session.setBidSessionData(sessionData);
String resp2Client = bankIDFacade.initTransaction(bidInfo
.getOperation(), bidInfo.getEncKey(), bidInfo.getEncData(),
bidInfo.getEncAuth(), bidInfo.getSid(), sessionData);
session.setBidSessionData(sessionData);
return resp2Client;
Dette vil sette opp nødvendig grunnlag for signeringen. Dette er serverkode som henter ut xml og xsl
gjennom lokale kall og setter dette på sessionData. no.bbs.server.vos.BIDSessionData
er en BankId-spesifikk klasse.
Opprette SDO fra BIDXML
//Hente sertifikatinfo
CertificateInfo certInfo = bankIDFacade.getCertificateInfo(bankIDFacade
.getPKCS7Info(sessionData.getClientSignature())
.getSignerCertificate());
//Lage SDO
SEID_SDO sdo = bankIDFacade.createSDO(sessionData.getClientSignatureBytes(),
sessionData.getMerchantSignatureBytes(),
sessionData.getSignedDataBytes(),
sessionData.getDataToBeSignedMimeType(),
sessionData.getMerchantOCSPBytes(), sessionData.getClientOCSPBytes(),
sessionData.getDataDescription());
//Sette SDO-xml på sesjonsobjekt
sdo.addSignedDataRaw(sessionData.getSignedDataBytes());
session.setSdoFile(new String(sdo.toXML()));
Tilrettelegge SDO signert av flere rettighetshavere
Dette er scenariet som skal brukes når man har flere rettighetshavere som skal signere på det samme
dokumentet. Eksempel kan være pant i fast eiendom med tre andeler der alle rettighetshavere for
den personlige andelen må signere. Eksempelet antar at det allerede har blitt etablert tre SDO
strukturer allerede som har blitt signert av BankId. Dette orkestreres i avleverende fagsystem.
byte[] signedData = null;
final File[] signedSdos = new File[]{new File("sdo-1.xml"), new File("sdo2.xml")};
List<PKCS7WithOCSPResponse> cmsData = new LinkedList<>();
for (File signedSdo : signedSdos) {
try (InputStream sdoData = new FileInputStream(signedSdo)) {
final byte[] bytes = ByteStreams.toByteArray(sdoData);
SEID_SDO sdo = new SEID_SDO(bytes);
final SEID_SDOElement seid_sdoElement = sdo.getSEID_SDOElement(0);
//Alle sdo-ene er i dette tilfellet signert over det samme grunnlagret,
det er kravet.
signedData = seid_sdoElement.getSignedObject().getSignedDataRaw();
for (SEID_SignatureElement signatureElement :
seid_sdoElement.getSeidSDODataPart().getSignatureElements()) {
final PKCS7WithOCSPResponse pkcs7WithOCSPResponse = new
PKCS7WithOCSPResponse();
cmsData.add(pkcs7WithOCSPResponse);
pkcs7WithOCSPResponse.setB64PKCS7(signatureElement.getCmsSignatureElement().getCmsSignature(
).getB64CMSSignature());
pkcs7WithOCSPResponse.setB64OCSPResponse(signatureElement.getCmsSignatureElement().getCertAn
dRevokeData().getB64EncapsulatedOCSPValue());
}
}
}
final SEID_SDO dynamicSDO = bidFacade.createDynamicSDO(cmsData.toArray(new
PKCS7WithOCSPResponse[cmsData.size()]), signedData, "text/BIDXML", "test av dynamisk sdo");
dynamicSDO.addSignedDataRaw(signedData);
final byte[] sdoXMLBytes = dynamicSDO.toXML();
Den resulterende SDO vil inneholde samtlige signaturer, også signaturer for de pågjeldende
brukersteder. Brukerstedssertifikatene er ikke relevante for denne signeringen og valideringen og
kan derfor filtreres ut. Resultatet av dette kan formidles som en SDO i SDODokument i en egnet
forsendelse. Dokumentene vil alltid inneholde mer enn en signatur. Det er påkrevet at slike
dokumenter er forseglet med et <SDOSeal>, det vil bli sjekket som en del av valideringslogikken for
disse SDO objekter.
Forsegle SDO
SEID_SDO dynamicSDO = bidFacade.createDynamicSDO(cmsData.toArray(new
PKCS7WithOCSPResponse[cmsData.size()]), signedData, "text/BIDXML", "test av dynamisk sdo");
final CertificateStatus ownCertificateStatus =
bidFacade.getOwnCertificateStatus();
dynamicSDO.addSignedDataRaw(signedData);
dynamicSDO = bidFacade.createSDOSeal(dynamicSDO,
ownCertificateStatus.getB64OCSPResponse());
Forseglingen av SDO må foretas etter at alle signaturene har blitt lagt inn.
Signering av følgebrev med brukerstedssertifikat
Dette utføres som en ren serversignering uten brukerdialog i nettleser elle mobilenhet.
final byte[] contentToBeSigned = ByteStreams.toByteArray(inputStreamBIDXMLFoelgebrev);
signatureAndData = bidFacade.sign(contentToBeSigned);
final no.bbs.server.vos.CertificateStatus ownCertificateStatus =
bidFacade.getOwnCertificateStatus();
PKCS7WithOCSPResponse merchantData = new PKCS7WithOCSPResponse();
merchantData.setB64PKCS7(signatureAndData.getB64SignatureBytes());
merchantData.setB64OCSPResponse(ownCertificateStatus.getB64OCSPResponse());
SEID_SDO serverSignedSDO = bidFacade.createDynamicSDO(new
PKCS7WithOCSPResponse[]{merchantData}, contentToBeSigned, mimeType.getType(), "Signert
Grunnboksutskrift");
serverSignedSDO.addSignedDataRaw(contentToBeSigned);
serverSignedSDO = bidFacade.createSDOSeal(serverSignedSDO,
merchantData.getB64OCSPResponse());
final byte[] sdoXMLBytes = serverSignedSDO.toXML();
Dette vil gi en SDO som er signert med et brukerstedssertifikat. Det base64 encodede resulatet av
dette kan benyttes som SDOElement i følgebrev. Virksomhet som signerer må være eksistere i
enhetsregisteret uavhengig av sertifikatsstatus og eventuell gyldighetsperiode på det pågjeldende
sertifikatet.
Det er et krav om at det er brukerstedssertifkat som anvendes når følgebrevet signeres.
folke – eller enhetsregisteret.
Forbehold
Milepæl 3 representerer et system under utvikling der de ulike deler av systemet vil være gjenstand
for forandringer. Løsningen kan ha mangelfull implementasjon samt inneholde feil.