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")
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(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 == 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 ernull
så er køen tom. Du henter bare kvitteringer fra kø gitt avMpcId
ogPrioritet
på 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.
Finne installert sertifikat
For å finne databehandlersertifikat i kode så må du finne thumbprint. Dette gjøres lettest gjennom Microsoft Management Console (mmc.exe).
SikkerDigitalPostKlient
har støtte for å ta in thumbprint direkte for Databehandler
og PostMottaker
.
Ø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.