- Hvordan komme i gang
-Klienten er tilgjengelig som en NuGet-pakke. Denne vil oppdateres jevnlig etter hvert som ny funksjonalitet legges til.
- -For å installere NuGet-pakken, gjør følgende:
- --
-
- Velg TOOLS -> NuGet Package Manager -> Manage Nuget Packages for Solution… -
- Søk etter sikker-digital-post.
-
-
-
- Ønsker du pre-release, må du sørge for at det står Include Prerelease i drop-down menyen rett over søkeresuløtatene (der det står Stable Only). -
- - Velg sikker-digital-post-klient og trykk Install. -
Klientkonfigurasjon
-Klientkonfigurasjon brukes for å sette opp koblingsspesifikke innstillinger mot meldingsformidleren, som ProxyHost, ProxyScheme og TimeoutMillisekunder. Denne må sendes med som innparameter til SikkerDigitalPostKlient.
For å sette url mot meldingsformidler, kan du gjøre dette slik:
- -var klientkonfigurasjon = new Klientkonfigurasjon();
-
-klientkonfigurasjon.MeldingsformidlerUrl = new Uri("https://eksempelendepunkt.no")Endepunkter
- -Funksjonelt testmiljø
-https://qaoffentlig.meldingsformidler.digipost.no/api/
- -Produksjonsmiljø
-https://meldingsformidler.digipost.no/api/
- -Norsk Helsenett - Funksjonelt testmiljø
-https://qaoffentlig.meldingsformidler.nhn.digipost.no:4445/api/
- -Norsk Helsenett - Produksjonsmiljø
- - -Sende post
-Det anbefales å bruke dokumentasjon i klassene for mer detaljert beskrivelse av inputparametere.- -
PostInfo for digital post
- -Først, lag en motaker av type DigitalPostMottaker:
-Postkassetjenesteleverandørene har ulik behandling av ikke-sensitiv tittel. Se begrep.difi.no for detaljer om denne forskjellen. -- -
var personnummer = "01013300002";
-var postkasseadresse = "ola.nordmann#2233";
-var mottakersertifikat = new X509Certificate2(); //sertifikat hentet fra Oppslagstjenesten
-var orgnummerPostkasse = "123456789";
-var mottaker = new DigitalPostMottaker(
- personnummer,
- postkasseadresse,
- mottakersertifikat,
- orgnummerPostkasse
- );
-
-var ikkeSensitivTittel = "En tittel som ikke er sensitiv";
-var sikkerhetsnivå = Sikkerhetsnivå.Nivå3;
-var postInfo = new DigitalPostInfo(mottaker, ikkeSensitivTittel, sikkerhetsnivå);Husk atOrgnummerPostkasse er organisasjonsnummer til leverandør av postkassetjenesten. Organisasjonsnummeret leveres fra oppslagstjenesten sammen med postkasseadressen og sertifikatet til innbygger.
-
-PostInfo for fysisk post
- -Skal du sende fysisk post må du først lage en FysiskPostMottaker, en FysiskPostReturMottaker og sette informasjon om farge og makulering:
var navn = "Ola Nordmann";
-var adresse = new NorskAdresse("0001", "Oslo");
-var mottakersertifikat = new X509Certificate2(); // sertifikat hentet fra Oppslagstjenesten
-var orgnummerPostkasse = "123456789";
-var mottaker = new FysiskPostMottaker(navn, adresse, mottakersertifikat, orgnummerPostkasse);
-
-var returMottaker = new FysiskPostReturmottaker(
- "John Doe",
- new NorskAdresse("0566", "Oslo")
- {
- Adresselinje1 = "Returgata 22"
- });
-
-var postInfo = new FysiskPostInfo(
- mottaker,
- Posttype.A,
- Utskriftsfarge.SortHvitt,
- Posthåndtering.MakuleringMedMelding,
- returMottaker
- );Her er adressen av type NorskAdresse eller UtenlandskAdresse.
Ved sending av fysisk post må man oppgi en returadresse, uavhengig av om brevet er satt til Posthåndtering.MakuleringMedMelding. Oppretting av en FysiskPostInfo vil da se slik ut:
Oppsett før sending
- -Opprett en avsender og en databehandler:
- -var orgnummerAvsender = new Organisasjonsnummer("123456789");
-var avsender = new Avsender(orgnummerAvsender);
-
-var orgnummerDatabehandler = new Organisasjonsnummer("987654321");
-var avsendersertifikat = new X509Certificate2();
-var databehandler = new Databehandler(orgnummerDatabehandler, avsendersertifikat);Hvis man har flere avdelinger innenfor samme organisasjonsnummer, har disse fått unike avsenderidentifikatorer, og kan settes på følgende måte:
- -avsender.Avsenderidentifikator = "Avsenderidentifikator I Organisasjon";Opprette forsendelse
-Deretterer kan du opprette forsendelse. Forsendelsen inneholder de dokumentene - som skal til mottakeren:
- -var hoveddokument = new Dokument(
- tittel: "Dokumenttittel",
- dokumentsti: "/Dokumenter/Hoveddokument.pdf",
- mimeType: "application/pdf",
- språkkode: "NO",
- filnavn: "filnavn"
- );
-
-var dokumentpakke = new Dokumentpakke(hoveddokument);
-
-var vedleggssti = "/Dokumenter/Vedlegg.pdf";
-var vedlegg = new Dokument(
- tittel: "tittel",
- dokumentsti: vedleggssti,
- mimeType: "application/pdf",
- språkkode: "NO",
- filnavn: "filnavn");
-
-dokumentpakke.LeggTilVedlegg(vedlegg);
-
-Avsender avsender = null; //Som initiert tidligere
-PostInfo postInfo = null; //Som initiert tidligere
-var forsendelse = new Forsendelse(avsender, postInfo, dokumentpakke);Opprette klient og sende post
-Siste steg er å opprette en SikkerDigitalPostKlient:
var klientKonfig = new Klientkonfigurasjon(Miljø.FunksjoneltTestmiljø);
-
-Databehandler databehandler = null; //Som initiert tidligere
-Forsendelse forsendelse = null; //Som initiert tidligere
-
-var sdpKlient = new SikkerDigitalPostKlient(databehandler, klientKonfig);
-var transportkvittering = sdpKlient.Send(forsendelse);
-
-if (transportkvittering is TransportOkKvittering)
-{
- //Når alt går fint
-}
-else if(transportkvittering is TransportFeiletKvittering)
-{
- var beskrivelse = ((TransportFeiletKvittering)transportkvittering).Beskrivelse;
-}Transportkvitteringen får du tilbake umiddelbart; den trenger du ikke å polle for å få.
- -Hente kvitteringer
-For å hente kvitteringer må du sende en kvitteringsforespørsel:
- -var køId = "MpcId";
-var kvitteringsForespørsel = new Kvitteringsforespørsel(Prioritet.Prioritert, køId);
-Console.WriteLine(" > Henter kvittering på kø '{0}'...", kvitteringsForespørsel.Mpc);
-
-Kvittering kvittering = sdpKlient.HentKvittering(kvitteringsForespørsel);
-
-if (kvittering is TomKøKvittering)
-{
- Console.WriteLine(" - Kø '{0}' er tom. Stopper å hente meldinger. ", kvitteringsForespørsel.Mpc);
-}
-
-if (kvittering is TransportFeiletKvittering)
-{
- var feil = ((TransportFeiletKvittering) kvittering).Beskrivelse;
- Console.WriteLine("En feil skjedde under transport.");
-}
-
-if (kvittering is Leveringskvittering)
-{
- Console.WriteLine(" - En leveringskvittering ble hentet!");
-}
-
-if (kvittering is Åpningskvittering)
-{
- Console.WriteLine(" - Har du sett. Noen har åpnet et brev. Moro.");
-}
-
-if (kvittering is Returpostkvittering)
-{
- Console.WriteLine(" - Du har fått en returpostkvittering for fysisk post.");
-}
-
-if (kvittering is Mottakskvittering)
-{
- Console.WriteLine(" - Kvittering på sending av fysisk post mottatt.");
-}
-
-if (kvittering is Feilmelding)
-{
- var feil = (Feilmelding)kvittering;
- Console.WriteLine(" - En feilmelding ble hentet :" + feil.Detaljer, true);
-}-Husk at det ikke er mulig å hente nye kvitteringer før du har bekreftet mottak av nåværende. -- -
sdpKlient.Bekreft((Forretningskvittering)kvittering);Kvitteringer du mottar når du gjør en kvitteringsforespørsel kan være av følgende typer: Leveringskvittering,Åpningskvittering, Returpostkvittering, Mottakskvittering eller Feilmelding. Kvittering kan også være av typenTransportFeiletKvittering. Dette kan skje når selve kvitteringsforespørselen er feilformatert.
-Husk at hvis du får- -TomKøKvittering, så er køen tom. Du henter bare kvitteringer fra kø gitt avMpcIdogPrioritetpå Dokumentpakken som ble sendt. Hvis ikke dette ble satt spesifikt vilMpcId = ""ogPrioritet = Prioritet.Normal. -
Logging
-Logge slik du ønsker
- -Behovet for logging er forskjellig fra prosjekt til prosjekt. For å håndtere dette har vi lagt inn mulighet for å sette en egen loggfunksjon på Klientkonfigurasjon. KlientKonfigurasjon.Logger kan settes til en Action<TraceEventType, Guid?, String, String>, hvor TraceEventType er hvilken type loggmelding det er , Guid er Id på meldingen, nest siste parameter er metoden det ble logget i og til slutt har vi selve meldingen. Her vil meldinger
Her er et eksempel:
- -var klientkonfigurasjon = new Klientkonfigurasjon
-{
- Logger = (severity, konversasjonsId, metode, melding) =>
- {
- System.Diagnostics.Debug.WriteLine("{0} - {1} [{2}]",
- DateTime.Now,
- melding,
- konversasjonsId.GetValueOrDefault()
- );
- }
-};Det som vi logges gjennom denne funksjonen er info om sendingsprosessen og XML som ligger ved i dokumentpakken.
- -Lagre XML som sendes
- -Når det sendes brev gjennom Sikker Digital Post, så sendes legges det også ved en del ekstra informasjon. Denne informasjonen er strukturert som XML og er nødvending for at brevet skal leveres til mottaker. Ofte kan dette være svært nyttig informasjon å logge for å se hva som faktisk sendes.
- -For å aktivere logging av XML så setter du følgende på Klientkonfigurasjon:
Klientkonfigurasjon.LoggXmlTilFil = true;Hvis Klientkonfigurasjon.StandardLoggSti ikke settes, så finner du loggfilene i %AppData%/Digipost/Logg.
Lagre dokumentpakke som sendes
- -Som avsender kan det være ønskelig å lagre selve pakken med dokumenter som sendes. Denne inneholder også XML som sendes og er den faktiske pakken som krypteres og sendes. For å gjøre dette, setter du følgende på Klientkonfigurasjon:
var transportkvittering = sikkerDigitalPostKlient.Send(forsendelse, lagreDokumentpakke: true);Hvis Klientkonfigurasjon.StandardLoggSti ikke settes, så finner du dokumentpakkene i %AppData%/Digipost/Dokumentpakke.
Sende post
-For å gjøre det lettere å komme i gang med sending av Sikker digital post så følger det under noen konkrete eksempler.
- -Det anbefales å bruke dokumentasjon i klassene for mer detaljert beskrivelse av inputparametere.- -
PostInfo for digital post
- -Først, lag en motaker av type DigitalPostMottaker:
-Postkassetjenesteleverandørene har ulik behandling av ikke-sensitiv tittel. Se http://begrep.difi.no/Felles/ikkeSensitivTittel for detaljer om denne forskjellen. -- -
var personnummer = "01013300002";
-var postkasseadresse = "ola.nordmann#2233";
-var mottakersertifikat = new X509Certificate2(); //sertifikat hentet fra Oppslagstjenesten
-var orgnummerPostkasse = "123456789";
-var mottaker = new DigitalPostMottaker(
- personnummer,
- postkasseadresse,
- mottakersertifikat,
- orgnummerPostkasse
- );
-
-var ikkeSensitivTittel = "En tittel som ikke er sensitiv";
-var sikkerhetsnivå = Sikkerhetsnivå.Nivå3;
-var postInfo = new DigitalPostInfo(mottaker, ikkeSensitivTittel, sikkerhetsnivå);Husk atOrgnummerPostkasse er organisasjonsnummer til leverandør av postkassetjenesten. Organisasjonsnummeret leveres fra oppslagstjenesten sammen med postkasseadressen og sertifikatet til innbygger.
-
-PostInfo for fysisk post
- -Skal du sende fysisk post må du først lage en FysiskPostMottaker, en FysiskPostReturMottaker og sette informasjon om farge og makulering:
var navn = "Ola Nordmann";
-var adresse = new NorskAdresse("0001", "Oslo");
-var mottakersertifikat = new X509Certificate2(); // sertifikat hentet fra Oppslagstjenesten
-var orgnummerPostkasse = "123456789";
-var mottaker = new FysiskPostMottaker(navn, adresse, mottakersertifikat, orgnummerPostkasse);
-
-var returMottaker = new FysiskPostReturmottaker(
- "John Doe",
- new NorskAdresse("0566", "Oslo")
- {
- Adresselinje1 = "Returgata 22"
- });
-
-var postInfo = new FysiskPostInfo(
- mottaker,
- Posttype.A,
- Utskriftsfarge.SortHvitt,
- Posthåndtering.MakuleringMedMelding,
- returMottaker
- );Her er adressen av type NorskAdresse eller UtenlandskAdresse.
Ved sending av fysisk post må man oppgi en returadresse, uavhengig av om brevet er satt til Posthåndtering.MakuleringMedMelding. Oppretting av en FysiskPostInfo vil da se slik ut:
Oppsett før sending
- -Opprett en avsender og en databehandler:
- -var orgnummerAvsender = new Organisasjonsnummer("123456789");
-var avsender = new Avsender(orgnummerAvsender);
-
-var orgnummerDatabehandler = new Organisasjonsnummer("987654321");
-var avsendersertifikat = new X509Certificate2();
-var databehandler = new Databehandler(orgnummerDatabehandler, avsendersertifikat);Hvis man har flere avdelinger innenfor samme organisasjonsnummer, har disse fått unike avsenderidentifikatorer, og kan settes på følgende måte:
- -avsender.Avsenderidentifikator = "Avsenderidentifikator I Organisasjon";Opprette forsendelse
-Deretterer kan du opprette forsendelse. Forsendelsen inneholder de dokumentene - som skal til mottakeren:
- -var hoveddokument = new Dokument(
- tittel: "Dokumenttittel",
- dokumentsti: "/Dokumenter/Hoveddokument.pdf",
- mimeType: "application/pdf",
- språkkode: "NO",
- filnavn: "filnavn"
- );
-
-var dokumentpakke = new Dokumentpakke(hoveddokument);
-
-var vedleggssti = "/Dokumenter/Vedlegg.pdf";
-var vedlegg = new Dokument(
- tittel: "tittel",
- dokumentsti: vedleggssti,
- mimeType: "application/pdf",
- språkkode: "NO",
- filnavn: "filnavn");
-
-dokumentpakke.LeggTilVedlegg(vedlegg);
-
-Avsender avsender = null; //Som initiert tidligere
-PostInfo postInfo = null; //Som initiert tidligere
-var forsendelse = new Forsendelse(avsender, postInfo, dokumentpakke);Opprette klient og sende post
-Siste steg er å opprette en SikkerDigitalPostKlient:
var klientKonfig = new Klientkonfigurasjon();
-
-Databehandler databehandler = null; //Som initiert tidligere
-Forsendelse forsendelse = null; //Som initiert tidligere
-
-var sdpKlient = new SikkerDigitalPostKlient(databehandler, klientKonfig);
-var transportkvittering = sdpKlient.Send(forsendelse);
-
-if (transportkvittering is TransportOkKvittering)
-{
- //Når alt går fint
-}
-else if(transportkvittering is TransportFeiletKvittering)
-{
- var beskrivelse = ((TransportFeiletKvittering)transportkvittering).Beskrivelse;
-}Transportkvitteringen får du tilbake umiddelbart; den trenger du ikke å polle for å få.
- -Hente kvitteringer
-For å hente kvitteringer må du sende en kvitteringsforespørsel:
- -var køId = "MpcId";
-var kvitteringsForespørsel = new Kvitteringsforespørsel(Prioritet.Prioritert, køId);
-Console.WriteLine(" > Henter kvittering på kø '{0}'...", kvitteringsForespørsel.Mpc);
-
-Kvittering kvittering = sdpKlient.HentKvittering(kvitteringsForespørsel);
-
-if (kvittering == null)
-{
- Console.WriteLine(" - Kø '{0}' er tom. Stopper å hente meldinger. ", kvitteringsForespørsel.Mpc);
-}
-
-if (kvittering is TransportFeiletKvittering)
-{
- var feil = ((TransportFeiletKvittering) kvittering).Beskrivelse;
- Console.WriteLine("En feil skjedde under transport.");
-}
-
-if (kvittering is Leveringskvittering)
-{
- Console.WriteLine(" - En leveringskvittering ble hentet!");
-}
-
-if (kvittering is Åpningskvittering)
-{
- Console.WriteLine(" - Har du sett. Noen har åpnet et brev. Moro.");
-}
-
-if (kvittering is Returpostkvittering)
-{
- Console.WriteLine(" - Du har fått en returpostkvittering for fysisk post.");
-}
-
-if (kvittering is Mottakskvittering)
-{
- Console.WriteLine(" - Kvittering på sending av fysisk post mottatt.");
-}
-
-if (kvittering is Feilmelding)
-{
- var feil = (Feilmelding)kvittering;
- Console.WriteLine(" - En feilmelding ble hentet :" + feil.Detaljer, true);
-}-Husk at det ikke er mulig å hente nye kvitteringer før du har bekreftet mottak av nåværende. -- -
sdpKlient.Bekreft((Forretningskvittering)kvittering);Kvitteringer du mottar når du gjør en kvitteringsforespørsel kan være av følgende typer: Leveringskvittering,Åpningskvittering, Returpostkvittering, Mottakskvittering eller Feilmelding. Kvittering kan også være av typenTransportFeiletKvittering. Dette kan skje når selve kvitteringsforespørselen er feilformatert.
-Husk at hvis kvitteringen er- -nullså er køen tom. Du henter bare kvitteringer fra kø gitt avMpcIdogPrioritetpå Dokumentpakken som ble sendt. Hvis ikke dette ble satt spesifikt vilMpcId = ""ogPrioritet = Prioritet.Normal. -
Installere sertifikater
-For å sende sikker digital post trenger du å installere sertifikater. Grunnen til at vi ønsker å installere de er først og fremst sikkerhet. Alle sertifikater har en unik identifikator som kalles thumbprint. Hvis du ikke ønsker å håndtere selv i koden hvordan sertifikatene skal lastes, så kan du følge guiden under, steg for steg. Til slutt gjennomgås det hvordan du kan finne thumbprint til de installerte sertifikatene.
- -Legg inn databehandlersertifikat i certificate store
- -Databehandlersertifikat er det sertifikatet du har fått utstedt for å kunne sende post.- -
-
-
- Dobbeltklikk på sertifikatet (Sertifikatnavn.p12) -
- Velg at sertifikatet skal lagres i Current User og trykk Next -
- Filnavn skal nå være utfylt. Trykk Next -
- Skriv inn passord for privatekey og velg Mark this key as exportable …, trykk Next -
- Velg Automatically select the certificate store based on the type of certificate -
- Next og Finish -
- Får du spørsmål om å godta sertifikatet så gjør det. -
- Du skal da få en dialog som sier at importeringen var vellykket. Trykk Ok. -
Legg inn mottakersertifikat i certificate store
- -Mottakerens sertifikat vil være sertifikatet til Digipost eller E-Boks og brukes for å validere respons.- -
Hvis du skal kjøre mot Digiposts testmiljø (https://qaoffentlig.meldingsformidler.digipost.no/api/ebms), så skal du bruke Test_Digipost.cer. Høyreklikk og lagre til disk.
- --
-
- Start mmc.exe (Trykk windowstast og skriv mmc.exe) -
- Velg File -> Add/Remove Snap-in… -
- Merk Certificates og trykk Add > -
- Velg My user account og trykk Finish -
- Åpne noden Certificates - Current User -
- Høyreklikk på Trusted People og velg All Tasks -> Import… -
- Trykk Next -
- Finn mottaker-sertifikatet (Sertifikatnavn.cer) og legg det til. Trykk Next -
- Sertifikatet skal legges til i Trusted People -
- Next og Finish -
- Du skal da få en dialog som sier at importeringen var vellykket. Trykk Ok. -
Finne installert sertifikat
- -For å bruke sertifikatene i kode så må du finne thumbprint til hver av de. Dette gjøres lettest gjennom Microsoft Management Console (mmc.exe).
- -SikkerDigitalPostKlient har støtte for å ta in thumbprint direkte for Databehandler og PostMottaker. Du finner thumbprint på følgende måte:
-
-
- Start mmc.exe (Trykk windowstast og skriv mmc.exe) -
- Velg File -> Add/Remove Snap-in… -
- Merk Certificates og trykk Add > -
- Velg My user account og trykk Finish -
- Åpne mappe for sertifikat -a. Databehandlersertifikat: Åpne noden Certificates - Current User - Personal - Certificates -b. Mottakersertifikat: Åpne noden Certificates - Current User - Trusted People - Certificates -
- Dobbeltklikk på sertifikatet du installerte -
- Velg Details, scroll ned til Thumbprint og kopier -
- VIKTIG: Hvis du får problemer i kode med at sertifikat ikke finnes, så kan det hende du får med en usynling BOM(Byte Order Mark). Slett derfor denne med å sette peker før første tegn i thumbprint i en teksteditor og trykk backspace. Hvis det var en BOM der så forsvant ikke det første synlige tegnet i thumbprint. -
Ønsker du å sende inn sertifikater du har allerede har initialisert, kan du kalle konstruktøren som tar inn X509Certificate2.
Som bruker av dette biblioteket er du en Databehandler som har ansvar for sending av meldinger. For å gjøre dette trenger du et sertifikat for å kunne autentisere deg mot Meldingsformidleren. Du kan lese mer om aktørene her.
- -Ytelse
-Klientbiblioteket benytter en HttpWebRequest for å kommunisere med Meldingsformidleren. I en konsollapplikasjon er denne begrenset til maks to samtidige forbindelser om gangen, mens den i en asp.net applikasjon er begrenset til ti. Dersom du ønsker å sende flere brev samtidig kan denne verdien endres f.eks til 3. Mer enn dette anbefales ikke.
System.Net.ServicePointManager.DefaultConnectionLimit = 3;Se ServicePointManager.DefaultConnectionLimit for mer informasjon.
- -