Integrasjonsguide

Sist oppdatert 22.04.2020

Innholdsfortegnelse

Meldingsformat
Datoformat
Kryptering
API-endepunkt

Meldingsformat

Beskrivelse av formatet på meldingene mellom som utveksles mellom Innsynsorkestratoren og registrene.

Type meldinger

Det er p.t. seks dialogprosesser. Disse er hentet fra Digital dialog - Implentasjonsguide standarder.docx som er skrevet av Direktoratet for eHelse. De fire siste må p.t. håndteres manuelt og trenger derfor ikke spesifiseres her.

  1. Dialog om oppføring: Innbygger kan forespørre om han er registrert eller register kan fortelle innbygger at han er registrert.
  2. Dialog innsyn helseopplysninger: Innsyn i opplysninger som er registrert om meg
  3. Dialog innsyn bruk: Innsyn i hvem som har benyttet opplysninger registrert om meg
  4. Dialog innsyn utlevering: Innsyn i hvem som har fått utlevert opplysninger om meg
  5. Dialog melde feil: Melding om feil i opplysninger registrert om meg
  6. Dialog sletting eller sperring: Anmodning om at opplysninger om meg slettes eller sperres for bruk

Meldingsskjelett

Ambisjonen er at meldingen skal være så enkel som mulig og inneholde kun det som det absolutt er behov for.

Dialog om oppføring

Request JSON-objekt

{ 
    fodselsnummer: "12345678901"
}

Response JSON-objekt

{
    oppforingsstatus: 0 | 1 | 2 
    statusTidsstempel: tidspunkt,
    dataSistEndret: tidspunkt
}

Dialog innsyn helseopplysninger

Request JSON-objekt

{ 
    fodselsnummer: "12345678901"
    rapportHovedType: "STD" | "FULL" | "TRA" | "LOK"
    lokalRapportType: rapportens lokale identifikator
}

Response JSON-objekt

{
    innsyn: standard xml-format definert av e-helse
    stottedeRapporter: liste med støttede rapporter
    vedlegg: liste med vedlegg
}

Eksempler

Dialog om oppføring

Andreas Heimdal, fødselsnummer 01128330700, sender forespørsel til Tonsilleregisteret om han er registrert der. Det er han.

Request JSON-objekt

{ 
    fodselsnummer: "01128330700"
}

Response JSON-objekt

{
    oppforingsstatus: 1 
    statusTidsstempel: "2018-10-19T12:38:48",
    dataSistEndret: "2018-01-01T00:00:00"
}

Dialog innsyn helseopplysninger

Andreas Heimdal, fødselsnummer 01128330700, sender forespørsel til Tonsilleregisteret om å generere en Standard rapport til han. Han får den generert som strukturert informasjon samt en PDF-fil som vedlegg. Han får også informasjon om at FULL rapport er tilgjengelig i tillegg til STD.

Request JSON-objekt

{ 
    fodselsnummer: "01128330700",
    rapportHovedType: "STD"
    lokalRapportType: ""
}

Response JSON-objekt

{
    innsyn: "<XML_MED_STANDARD_RAPPORT>"
    stottedeRapporter: [{
        rapportHovedType: "FULL"
    }]
    vedlegg: [{  
        mimetype: "application/pdf"
        innhold: <BASE64_KODET_PDF_FIL>  
        innholdsbeskrivelse: "Vedlegg til Standardrapport"
    }]
}

Datoformat

Dato og tid skal angis uten tidssone og på følgende format: “2018-10-19T12:38:48”

Kryptering

Kommunikasjon mellom Innsynsorkestrator og register krypteres både for å sikre at uvedkomne ikke skal kunne se dataene og for å sikre at det kommuniseres med korrekt register. Krypteringen baserer seg på en delt hemmelighet.

Delt hemmelighet

Sikring av kommunikasjonen baseres på en hemmelig nøkkel som bare registeret og orkestratoren kjenner til. Denne er forskjellig for hvert enkelt register orkestratoren kommuniserer med og vil dermed også kunne brukes til å verifisere at meldingene går til / fra korrekt register. Nøkkelen blir generert av Innsynsorkestratoren og samme nøkkel må benyttes i registeret for å kunne dekryptere informasjonen. Nøkkelen er Base64 kodet.

Eksempel på nøkkel:

8HY69972SIS8lBodnWGwIva2HVwfn/BzldoecxKhOcU=

Krypteringsalgoritme

Informsajon om krypteringsalgoritmen. Alle parametere er standard for c# implementasjonen av algoritmen.

Type: AES
BlockSize: 128
KeySize: 256
FeedbackSize: 8
Mode: CBC
Padding: PKCS7

Flyt ved kryptering

Ved kryptering benyttes nøkkelen sammen med en tilfeldig generert initialiseringsvektor (IV) for å generere cipher-teksten (det krypterte innholdet) som overføres mellom orkestrator og register. IV benyttes for å unngå at kryptering av to like tekster genererer den samme cipher-teksten. IV er et byte-array på 16 bytes som legges til foran det byte-arrayet som er den genererte cipher-teksten. Kombinasjonen av IV og cipher-teksten (det kombinerte byte-arrayet) blir deretter base64-kodet til en streng før det overføres mellom orkestrator og register.

Flyt ved dekryptering

Ved dekryptering går man motsatt vei. Den overførte strengen blir først konvertert fra base64-kodet streng til byte-array. De 16 første bytene i dette byte-arrayet gir IV, de resterende bytene gir cipher-teksten som så kan dekrypteres med nøkkelen og IV som ble sent sammen med cipher-teksten.

Test av kryptering og dekryptering

Bruk følgende eksempel for å teste kryptering og dekryptering. Ved kryptering: Merk at cipher-teksten vil bli forskjellig hver gang den genereres selv om teksten som krypteres er lik.

Eksempel

Nøkkel (delt hemmelighet)

8HY69972SIS8lBodnWGwIva2HVwfn/BzldoecxKhOcU=

Data i klartekst

Text to be encrypted

Ved å bruke nøkkelen sammen med en tilfeldig generert IV til å kryptere data i klartekst får man denne base64-kodede strengen som består av IV og cipher-teksten

VxQSM09R+xJe+uDCpPcKHrzVk0iePxZzpPJMl2eb9wp2K15w0uocJS2UHlIXWP9H

Denne base64-kodede strengen kan brukes for å teste dekryptering ved å se om man får dekryptert den tilbake til original tekst ved å benytte samme nøkkel

API-endepunkt

Orkestratoren forventer at API-endepunktene for de ulike meldingstypene er tilgjengelig på følgende URLer:

  1. Dialog om oppføring: <API base URL>/Oppforing
  2. Dialog innsyn helseopplysninger: <API base URL>/InnsynHelseopplysninger

Her er <API base URL> en variabel som orkestratoren må konfigureres med.

Orkestratoren sender forespørsler til API-endepunktene som POST.