Posten signering documentation Documentation

Posten signering documentation Documentation Release 1 Posten Norge AS Jun 03, 2019

Introduksjon 1 Hvorfor bruke Posten signering 1 2 Signeringsflyt 3 3 Signaturtype 5 4 Signerte dokumenter 7 5 Det signerte dokumentet 9 6 Format på signaturen 11 7 Pakketering av signaturer 13 8 Avsenderportalen 15 9 Send oppdrag til signering 17 10 Opprette signeringsoppdrag 19 11 Adressering av undertegner 21 12 Kontaktinformasjon 23 13 Varsler: Regler for utsending 25 14 Varseltekster for undertegnere 27 15 Endring av signeringsoppdrag 31 16 Varseltekster for avsendere 33 17 Lagring 35 18 GDPR 37 19 Sikkerhetsnivå 39 20 Kjedet signering 41 i

21 Buy enterprise certificates 43 22 Install enterprise certificate 45 23 Install client 49 24 Create client configuration 51 25 Direct flow 53 26 Portal flow 69 27 Error handling 75 28 Debugging 77 29 Dokumentpakken 81 30 API-integrasjon for signering i portalflyt 87 31 Sikkerhet 95 32 Syntax help 97 33 Ordbok 101 34 Indices and tables 103 ii

CHAPTER 1 Hvorfor bruke Posten signering Vi tror på det å gjøre livet til folk enklere. Ved å ta i bruk digital signering fra Posten, slipper du den tidkrevende og manuelle håndteringen av dokumenter som skal signeres. 1.1 Hva er Posten signering Posten signering er en tjeneste som tilbyr digital signering til offentlige og private virksomheter. Med digital signering gjennomføres selve signeringen med en elektronisk ID. Det signerte dokumentet kan ikke endres i etterkant uten at signaturen brytes, og dokumentet kan lagres i et arkiv eller lastes ned til virksomhetens arkiv. Tjenesten støtter både at enkeltpersoner og flere personer kan signere samme dokument. Vi utvikler stadig ny funksjonalitet i tjenesten, og tar gjerne imot innspill fra både virksomheter og privatpersoner. 1.2 Hvordan bruke Posten signering Som en virksomhet kan du ta i bruk Posten signering på 2 måter, avhengig av behov og ønsket signeringsflyt: 1.2.1 Avsenderportal Avsenderportalen gjør det mulig for en virksomhet å ta i bruk signeringstjenesten uten å gjøre noen tekniske integrasjoner. Dokumentene som skal signeres lastes manuelt opp i portalen. Undertegnere logger inn i portalen for å få tilgang til å lese og signere dokumentene via portalflyt. Dette er en enkel og effektiv måte å komme i gang med signeringstjenesten på, og passer bra for mindre volumer. Hvis du er en privat virksomhet, kan du registrere virksomheten direkte. Hvis du er en offentlig virksomhet, får du registrert konto i signering via Difi og samarbeidsportalen. 1.2.2 API-integrasjon API-grensesnittet krever en teknisk integrasjon mellom virksomheten og Posten signering. Ved å lage en integrasjon mot tjenesten vil undertegner forholde seg til virksomhetens nettside, og signeringstjenesten vil oppleves som en inte- 1

grert del av tjenesten. Man kan velge om undertegner skal signere i virksomhetens system eller nettside (direkteflyt), eller å la undertegneren logge inn og signere i Postens signeringsportal (portalflyt). Integrasjon mot signeringstjenestens API kan gjøres på 3 måter 1. Bruk av klientbiblioteker: Vi leverer klientbiblioteker som forenkler integrasjonsprosessen for kunder som ønsker å integrere signeringstjenesten inn i sine egne systemer. Klientbibliotekene støtter programmeringsspråkene Java og.net. 2. Integrasjon via programvareprodukt eller partner: Mange kunder benytter et fagsystem som sak- og arkivsystemer, eller andre programvareprodukter som kilde for dokumenter som skal signeres. 3. Egenutviklet integrasjon API-et er dokumentert, slik at kunder som ønsker det kan gjøre en egen integrasjon. 2 Chapter 1. Hvorfor bruke Posten signering

CHAPTER 2 Signeringsflyt Et signeringsoppdrag inneholder et dokument som skal signeres, og kan adresseres til en eller flere undertegnere som skal signere. Tjenesten tilbyr i hovedsak to ulike typer signeringsflyter. 2.1 Signering i direkteflyt Signering i direkteflyt skjer når undertegner allerede er pålogget i avsenders system. En slik flyt er ideell hvis avsender ønsker at sluttbrukerne skal oppleve signeringsprosessen som en integrert del av deres nettsted. Flyten ser typisk slik ut: 1. Undertegner er innlogget i avsenders tjeneste, og utfører en prosess der, f.eks. utfylling av et skjema er sluttresultatet 2. Avsender oppretter et signeringsoppdrag i signeringstjenesten gjennom API 3. Undertegner blir sendt til signeringstjenesten og gjennomfører signeringen 4. Undertegner blir sendt tilbake til avsenders tjeneste 5. Avsender laster ned signatur og tilbyr en kopi av det signerte dokumentet til undertegner Tip: Se gjerne denne bildeguiden i Google Presentation for signering i direkteflyt. 2.2 Signering i portalflyt 2.2.1 Adressering med fødselsnummer Hvis man adresserer med fødselsnummer så vil undertegner måtte logge inn i signeringsportalen for å kunne se signeringsoppdraget. Flyten ser typisk slik ut: 3

1. Avsender oppretter et oppdrag gjennom API eller fra web i avsenderportalen 2. Posten signering varsler undertegner på e-post (og ev. SMS om spesifiert ved opprettelse) 3. Undertegner logger inn på signeringsportalen og gjennomfører signeringssermonien 4. Undertegner laster ned signert dokument 5. Undertegner logger ut av signeringsportalen 6. Avsender laster ned det signerte dokumentet Tip: Se gjerne denne bildeguiden i Google Presentation for signering i portalflyt, adressering med fødselsnummer. 2.2.2 Adressering uten fødselsnummer En signeringsflyt hvor man får tilgang til portalen ved en lenke og et engangspassord. 1. Avsender oppretter et oppdrag gjennom API eller fra web i avsenderportalen 2. Undertegner mottar en unik lenke og engangskode til oppdrag på e-post eller SMS 3. Undertegner trykker på lenken, og fyller inn engangskode til oppdrag 4. Undertegner gjennomfører signeringsseremonien 5. Sluttside som gir mulighet til å laste ned signert dokument Når man adresserer undertegner uten fødselsnummer, er det avsenders ansvar å sjekke at det er rett eller ønsket person som har signert. Tip: Se gjerne denne bildeguiden i Google Presentation for signering i portalflyt, adressering uten fødselsnummer. 4 Chapter 2. Signeringsflyt

CHAPTER 3 Signaturtype I Norge har vi tre forskjellige måter å signere digitalt på, som beskrevet i E-signaturloven: autentisert, avansert og kvalifisert. Autentisert signatur er en sterk signatur, avansert signatur er enda sterkere, og kvalifisert signatur er den sterkeste signaturen. Vi tilbyr autentisert og avansert signatur, som er rettskraftige signaturer på lik linje med håndskrift på papir. Kvalifisert signatur eksisterer ikke per i dag, men er tenkt oppfylt på lang sikt gjennom Nasjonalt ID-kort. 3.1 Avansert signatur Ved bruk av avansert signatur så skjer signering med BankID. Det er her en sterk knytning mellom identifiseringshandling og dokument som skal signeres. En avansert signatur har en sterkere knytning mellom signaturen og dokumentet enn en Autentisert signatur fordi det er kun BankID som er involvert i den prosessen. Tip: Signering kan gjøres med BankId, Buypass eller BankID på mobil. 1 3.2 Autentisert signatur Ved bruk av autentisert signatur så autentiseres brukeren i ID-porten. IDporten vet ikke noe om at innloggingen er tilknyttet en signeringsseremoni og det er Signicats jobb å knytte autentiserinen sammen med dokumentet til en signatur. En autentisert signatur er derfor litt svakere enn en avansert signatur fordi det er flere parter involvert og at det skjer i to steg. Offentlige virksomheter bruker ofte autentisert signatur, da den er rimeligere enn avansert signatur. 1 BankID på mobil er ikke tilgjengelig for avanserte oppdrag fra offentlig virksomhet. 5

Avsender kan velge Sikkerhetsnivå på signeringen. 3.3 Valg av signaturtype Bedrift Som bedrift har du kun mulighet til å velge avansert signatur og derfor er det ikke nødvendig å sette denne eksplisitt. Offentlig virksomhet Som offentlig virksomhet har du mulighet til å velge mellom Avansert signatur eller Autentisert signatur, men Difi anbefaler offentlige virksomheter å bruke autentisert signatur ettersom det er billigere og oppfyller de kravene som blir stilt i offentlig sektor. Note: Standardverdi for signaturtype er autentisert. Fotnoter 6 Chapter 3. Signaturtype

CHAPTER 4 Signerte dokumenter Med en digital signatur kan man signere dokumenter papirløst ved å bruke autentisering av en person og koble det sammen med et dokument. For signerte PDF-dokumenter ligger signaturdata i selve filen, og mange PDF-lesere har mulighet til å vise den digitale signaturen. Etter at signering av et dokument er fullført får vi en teknisk signatur og en signert PDF. En teknisk signatur er en XML-fil som kalles XML Advanced Electronic Signature (XAdES), og er beviset på at du har signert digitalt. XAdES inneholder data som kan verifisere hvem som signerte, tidspunktet for signeringen, hvilken signeringsmetode som ble brukt, hvilken IP-adresse undertegner hadde, og om dokumentet er blitt endret etter signeringstidspunktet. En signert PDF kalles PDF Advanced Electronic Signature (PAdES). Denne består av originaldokumentet, en forside med informasjon om signeringen, og de tekniske signaturene (XAdESene) for alle undertegnerne. XAdESene er digitalt integrerte i PAdES-en og ikke synlige, men man kan åpne filene i signaturpanelet i PDF-leseren. En signert PDF med tre undertegnere, vil altså inneholde originaldokumentet, en forside med informasjon om signeringene, og tre XAdESer som er digitalt integrert i dokumentet. Alle dokumenter kan lastes ned i en periode etter at signeringsoppdraget er fullført. Levetiden er avhengig av om Langtidslagring er aktivert for avsenderen. 4.1 Hvordan identifiseres undertegnere i et ferdig signert dokument? Under opprettelse av signeringsoppdrag kan avsender velge hvordan undertegnerne skal identifiseres i de signerte dokumentene. Avsender velger å inkludere én av følgende identifikatorer i signerte dokumenter: Når avsender er en privat virksomhet: Navn + fødselsnummer Navn + fødselsdato Når avsender er en offentlig virksomhet: Navn + fødselsnummer 7

Navn Caution: Dersom du vil at undertegners fødselsnummer skal fremkomme på det signerte dokumentet er du av personvernmessige hensyn nødt til å adressere undertegner på fødselsnummer i signeringsoppdraget. Hvis du utelater fødselsnummer i de signerte dokumentene kan vi ikke påvise identiteten med 100% sikkerhet 1. Vi kan likevel i de aller fleste tilfeller oppnå tilstrekkelig beviskraft, på bakgrunn av konteksten signeringen skjer i. Sannsynligheten er for eksempel svært liten for at 2 personer med navn Kari Olsen signerer en lærekontrakt med Lærlingebedrift AS på eksakt samme tidspunkt. I tillegg vil tekniske spor, og andre eksterne forhold som kunderelasjon eller opplysninger i dokumentet også støtte opp under identiteten til den som har signert. 1 Det signerte dokumentet inneholder en anonymisert identifikator som identifiserer undertegneren med 100% sikkerhet hos leverandøren av e-id, for eksempel hos BankID. Dette krever oppslag hos leverandøren av e-id og støttes kun ved avansert signatur 8 Chapter 4. Signerte dokumenter

CHAPTER 5 Det signerte dokumentet Som vist under vil dokumentet få en forside som viser hvem som har signert og hva dokumentet inneholder. Hver side inneholder også en bunntekst som viser hvem som har signert. 5.1 I produksjonsmiljø Hvis dokumentet er signert i et produksjonsmiljø så kan man verifisere signaturen i f.eks. Adobe Acrobat Reader ved å klikke på Signaturpanel i den blå infoboksen. 9

5.2 I et testmiljø Hvis dokumentet er signert i et testmiljø så er det teknisk sett ikke en gyldig signatur siden det er sertifikater fra en test-utsteder som brukes. Dette ser du i den blå infoboksen. Det er likevel mulig å se på signaturene slik som i produksjonsmiljøet. 10 Chapter 5. Det signerte dokumentet

CHAPTER 6 Format på signaturen Med signaturformat mener vi formatet på objektet som skapes gjennom signeringsprosessen. Det elektronisk signerte dokumentet lagres normalt på et annet dokumentformat enn originaldokumentet som ble signert. Signeringstjenesten støtter følgende signaturformater som er i utbredt bruk i Norge i dag. Dette inkluderer både formatene som støttes direkte av e-id-leverandørene, i tillegg til formater som tilbys av signeringstjenesten gjennom pakketering. SEID-SDO: SEID-SDO er et påbygg av ETSI (the European Telecommunications Standards Institute) CAdES/XAdES LTV-SDO: Betegnelse for en SDO (Signed Data Object) som er utvidet med data for langtidsvalidering (LTV-data). LTV-SDO er en XAdES. PAdES: PAdES er et signaturformat som inneholder originaldokumentet, alle signaturer og all informasjon som er nødvendig for å validere signaturen. Formatet er spesifisert av ETSI, og bygger på PDF. En PAdES kan åpnes i en vilkårlig PDF-leser. Adobe Reader (og eventuelle andre avanserte PDF lesere) vil også kunne vise frem deler av valideringsinformasjonen slik at sluttbrukeren selv kan se at dokumentet er gyldig signert. 11

12 Chapter 6. Format på signaturen

CHAPTER 7 Pakketering av signaturer Signeringstjenesten gjør pakketering av signaturer gjennom et format for langtidsvalidering kalt LTV-SDO. LTV-SDO er en XAdES som brukes til å styrke og standardisere signaturene som kommer fra e-id-leverandørene. Selv om LTV-SDO er et format som er utviklet primært for langtidsvalidering, har det andre egenskaper som gjør at det er ønskelig å bruke det ved ordinær prosessering og oppbevaring av signerte dokumenter. Det gjør at signeringstjenesten og tjenesteyterne har ett format å forholde seg til, uavhengig av hvilken e-id-leverandør som er brukt til signering og om dokumentet skal langtidsvalideres eller ikke. Pakketering gjøres i to steg: 1. Pakketering av SDO til LTV-SDO. Her utvides og styrkes signaturen for å legge til rette for langtidsvalidering og å styrke bevisverdien. 2. Pakketering av LTV-SDO til PDF/PAdES. Her legges det til støtte for multisignatur, brukervennlighet og lettere manuell og maskinell prosessering hos mottaker. Denne pakketeringen gir en rekke fordeler: 1. Brukervennlighet: Pakketering til PDF/PAdES lar brukeren se det signerte dokumentet med påført signatur. Det er en viktig del av signaturseremonien at menneskelige brukere får en slik gjenpart. 2. Multisignatur - flere signatarer: Pakketering til PDF/PAdES gir mulighet for et samlet dataobjekt for flere signaturer på samme dokument. Den vil også vise frem signaturene på en brukervennlig måte, slik at man kan se flere signaturer på samme dokument. 3. Multisignatur - flere signerte dokumenter: Pakketering til PDF/PAdES gjør det mulig å samle flere signerte dokumenter som hører sammen i ett felles dataobjekt. 4. Felles format for alle e-id-leverandører: Pakketering til LTV-SDO eller til PAdES gir et konsistent signaturformat uavhengig av e-id- leverandørens format. 5. Dokumentbehandling i saks- og arkivsystemer: Pakketering til PDF/PAdES tillater viderebehandling i standard dokumentsystemer, fordi en PAdES også er en PDF. 6. Validering av signatur for sluttbruker: Pakketering til PAdES vil tillate validering av dokumentet med standard hyllevare (f.eks. Adobe Reader) dersom den signeres (forsegles) med et sertifikat som gjenkjennes av leseren. 13

7. Langtidslagring (LTV): Pakketering til LTV-SDO eller PAdES gir den beste støtten for langtidsvalidering. Langtidslagring, uavhengig av om det er i sentral arkivtjeneste eller hos kunde, krever et format som tillater preservering og oppbevaring av valideringsdata. Den underliggende SDO-en fra e-id-leverandøren ligger tilgjengelig i LTV-SDO-formatet, og kan enkelt hentes ut av ved behov. Tjenesten kan derfor både tilby kunder den berikede LTV-SDO-en og tilgang til den underliggende SDO-en fra e-id-leverandøren. Det er derfor ikke en forutsetning at kunden kan forholde seg til LTV-SDO, men snarere en anbefaling som vil gi standardisert tilgang til beriket og integritetsbeskyttet informasjon om signeringsoppdraget. Pakketering med XAdES og/eller PAdES gir full nytte av standardiseringsarbeidet for preservering som gjøres i regi av EU (XAdES Baseline som er utviklet av EU-initiativet DSS, og som vil bli de foretrukne standardene i XAdES). 14 Chapter 7. Pakketering av signaturer

CHAPTER 8 Avsenderportalen Avsenderportalen er et web-grensesnitt for avsendere hvor man kan sende ut signeringsoppdrag som skal signeres, samt administrere oppdrag og virksomhetskonto. Som avsender kan du ha tilgang til flere virksomhetskontoer. Etter innlogging velger du den virksomheten du ønsker å sende ut oppdrag fra eller administrere. [Se gjerne hjelpeguiden med skjermbilder](https://docs.google.com/presentation/d/1vqks9cunev3ssujd_z7za0ngewwwj_ fy22ihvboqbfs/edit?usp=sharing). 8.1 Din konto 8.1.1 Kontoinformasjon Her kan du laste opp logo for virksomheten din, og aktivere langtidslagring om du ønsker å bruke dette. Det er også herfra du styrer hvem som har tilgang til virksomhetskontoen. 8.1.2 Brukere Du kan legge til så mange brukere du ønsker, og velge hvilken rolle brukeren skal ha: Kontoforvalter: Som kontoforvalter har du full tilgang. Du kan du opprette og redigere brukere, laste opp virksomhetslogo, se alle signeringsoppdrag som er sendt ut fra virksomheten og opprette nye signeringsoppdrag. Dokumentbehandler: Som dokumentbehandler har du begrenset tilgang. Du kan kun opprette og se dine egne signeringsoppdrag. Du kan også velge om brukeren skal ha tilgang i ubegrenset tid, eller sette en tidsbegrensning for når brukeren ikke lenger skal ha tilgang til kontoen. 15

8.2 Oversikt i avsenderportalen I Dokumenter-fanen har du fire faner: Venter, Stoppet, Signert og Søk. Venter, stoppet og signert er knyttet til signeringsflyten på oppdrag, mens søk kan brukes for å finne tilbake til et signeringsoppdrag. Venter: Her kan du se signeringsoppdrag som du har opprettet, som venter på signering. Oppdragene blir liggende under denne fanen inntil de blir signert, eller stoppet. Merk, at hvis oppdraget har flere undertegnere, vil oppdraget ligge i Venter helt til alle har signert. Stoppet: Her finner du alle oppdrag som er stoppet. Et oppdrag kan bli stoppet av avsender og/eller av undertegner; undertegner kan avvise oppdraget, eller ikke signere innen fristen. Avsender kan kansellere oppdraget. I begge tilfeller havner oppdraget under Stoppet. Signert: Her kan du se alle signerte oppdrag. Hvis virksomheten din har aktivert langtidslagring, vil dokumentet alltid være tilgjengelig for nedlasting. Hvis ikke langtidslagring er aktivert, kan du laste ned dokumentet i 40 dager. Søk: Her kan du søke for å finne tilbake til et signeringsoppdrag. Du kan søke på fødselsnummer, e-post, mobilnummer eller referansenummer, og søke i et ønsket tidsintervall. 16 Chapter 8. Avsenderportalen

CHAPTER 9 Send oppdrag til signering 9.1 Steg 1: Dokument til signering Her laster du opp dokumentet som skal signeres. Filen må være en PDF-fil og ikke større enn 3MB. 9.1.1 Sett en signeringfrist for oppdraget Undertegner vil motta et varsel der det opplyses om signeringsfristen. Les mer om regler for utsending av varsler her. 9.1.2 Adressering av undertegner Undertegner kan adresseres på to ulike måter, med eller uten fødselsnummer. Les om adresseringen her. Med fødselsnummer: Dette gir en sikker identifisering, og undertegner må logge inn med BankID, BankID på mobil eller Buypass for å kunne signere. Med adressering på fødselsnummer må du også ta et valg på om du ønsker at hele fødselsnummeret eller bare fødselsdato skal vises i det signerte dokumentet. Les mer om innhold i det signerte dokumentet her. Uten fødselsnummer: Denne signeringsmetoden krever ingen innlogging, og du som avsender trenger ikke vite undertegners fødselsnummer. I stedet oppgir du kun e-postadressen og/eller mobilnummeret, og undertegner mottar en lenke til dokumentet og fyller inn sikkerhetskoden som er oppgitt i varselet. Undertegner kan deretter åpne og signere dokumentet med BankID, BankID på mobil eller Buypass. 9.2 Steg 2: Mottakere For at undertegnere skal få varsler om signeringsoppdrag må du her legge inn kontaktinformasjon. Et signeringsoppdrag kan ha maksimalt 10 undertegnere. Du som avsender kan være undertegner på ditt eget signeringsoppdrag. Huker du av for Jeg skal signere selv, blir e-postadressen du har registrert på din bruker automatisk fylt inn. 17

9.3 Steg 3: Informasjon til mottakere Beskrivelse av dokumentet som vises i e-postvarselet Beskrivelsen bør ikke inneholde noe sensitivt, da den vises i e- posten som sendes ut. Det er likevel bra å få med detaljer rundt hva som signeres, slik at det blir enklere for undertegner å kjenne igjen i e-posten. Forhåndsvisning av e-postvarselet: Du kan se en forhåndsvisning av e-postvarselet som blir sendt ut til undertegner. Beskrivelse av dokumentet, som du la inn over, vil synes her. Tittel på forsiden av det signerte dokumentet: Tittelen du skriver inn her vises blir med på forsiden til det signerte dokumentet. Les mer om innhold i det signerte dokumentet her. Beskjed som mottaker ser i signeringsportalen: Skriv en personlig beskjed til undertegner. Beskjeden vises før dokumentet signeres (sendes ikke i e-post eller SMS). Forhåndsvisning i signeringssportalen: Du kan se en forhåndsvisning av hvordan beskjeden, som du skrev inn over, vil se ut når undertegner logger seg inn i signeringsportalen. Internt saksnummer/referanse-id: Har du et saksnummer eller en referanse-id knyttet til dokumentet eller undertegner, kan du skrive det her. Det kan brukes for enklere å finne igjen dokumentet. Avanserte innstillinger: Under avanserte innstillinger kan du velge om du vil sende dokumentet med en gang eller senere. Ved å velge senere oppgir du dato og klokkeslett for ønsket utsendelse. 18 Chapter 9. Send oppdrag til signering

CHAPTER 10 Opprette signeringsoppdrag Ved opprettelse av signeringsoppdrag kan følgende felter angis: Felt Direkteflyt Portalflyt Ekstra informasjon Dokument Obligatorisk Obligatorisk Undertegner(e) Obligatorisk Obligatorisk se Adressering av undertegner Tittel Obligatorisk Obligatorisk Signaturtype Valgfritt Valgfritt se Signaturtype Sikkerhetsnivå Valgfritt Valgfritt se Sikkerhetsnivå Melding til mottaker(e) Valgfritt Valgfritt Undertegners identifikator Valgfritt Valgfritt se Adressering av undertegner Aktiveringstidspunkt Ikke overstyrbar 1 Valgfritt Levetid Ikke overstyrbar 2 Valgfritt E-postadresse Ikke relevant Obligatorisk se Kontaktinformasjon Mobilnummer Ikke relevant Valgfritt se Kontaktinformasjon Rekkefølge Ikke relevant Valgfritt se Kjedet signering For implementasjon for signeringsoppdrag i portalflyt, se Portal flow, og for signeringsoppdrag i direkteflyt, se Direct flow. 10.1 Begrensninger 10.1.1 Antall undertegnere Et signeringsoppdrag kan ha flere undertegnere. Tjenesten tillater maksimalt 10 undertegnere pr. oppdrag. 1 Signeringsoppdrag i direkteflyt blir alltid aktivert øyeblikkelig etter opprettelse. Standardverdi er øyeblikkelig etter opprettelse. 2 Signeringsoppdrag i direkteflyt har alltid 30 dagers levetid for å unngå at et dokument blir signert uhensiktsmessig lenge etter opprettelsen av oppdraget. Eventuell frist fra avsenders perspektiv må kommuniseres og håndteres i avsenders tjenester. 19

10.1.2 Hastighet Tjenesten tillater maksimalt 10 API-kall i sekundet per organisasjonsnummer. Hvis en avsender overskrider denne grensen vil API-et returnere HTTP 429 Too Many Requests, og avsenderen vil bli blokkert i 30 sekunder. 10.1.3 Dokumentformat Tjenesten støtter dokumenter av typen ren tekst (.txt) og PDF (.pdf). Både PDF og PDF/A aksepteres av tjenesten. Det signerte dokumentet vil være av samme type som originaldokumentet. Et originaldokument som er PDF/A gir et signert PAdES-dokument som er PDF/A, og et originaldokument som er PDF versjon 1.1 1.7 gir et signert PAdESdokument som er PDF versjon 1.7. For PDF/A vil tjenesten alltid produsere signerte PAdES-dokumenter av typen PDF/A-3b, uavhengig av PDF/A-versjon og -konformitetsnivå på originaldokumentet. For arkivering av signerte dokumenter anbefaler vi å bruke originaldokumenter av typen PDF/A. Dette er et krav hvis det signerte dokumentet skal avleveres til Riksarkivet. Note: Filen kan maksimalt være 3 MB (3 145 728 bytes) stor. PDF-versjoner som støttes er PDF 1.1-1.7. I PAdES vil dokumentet alltid presenteres i A4- og portrett-format. For best resultat anbefales det at det innsendte dokumentet også har dette formatet. Danger: Passordbeskyttede dokumenter (begrenset lese- og/eller skrive-tilgang) er ikke støttet av tjenesten og vil gi feilmelding først ved nedlasting av dokumentet. 10.1.4 Aktiveringstidspunkt Angir tidspunkt for når signeringsoppdraget skal tilgjengeliggjøres for undertegner(e). Dersom aktiveringstidspunktet er i fortiden, blir oppdraget tilgjengelig øyeblikkelig etter opprettelse. Signeringsoppdrag i direkteflyt blir alltid aktivert øyeblikkelig etter opprettelse. 10.1.5 Oppdragets levetid Angir hvor lenge etter aktivering et signeringsoppdrag er tilgjengelig for undertegner før det utløper. Kan maksimalt være 90 dager etter aktivering. Signeringsoppdrag i direkteflyt har alltid 30 dagers levetid for å unngå at et dokument blir signert uhensiktsmessig lenge etter opprettelsen av oppdraget. Eventuell frist fra avsenders perspektiv må kommuniseres og håndteres i avsenders tjenester. 20 Chapter 10. Opprette signeringsoppdrag

CHAPTER 11 Adressering av undertegner Måten undertegner adresseres og identifiseres på, er litt forskjellig avhengig av om han signerer i direkteflyt eller portalflyt, og om avsender bruker API eller avsenderportalen. Tip: Hvis du ønsker å lese en introduksjon til de forskjellige flytene en undertegner kan signere i, se Signeringsflyt. Caution: Måten du adresserer undertegner på, påvirker innholdet og utseendet på undertegners signatur. Posten signering sender ut varsel om signeringsoppdrag til undertegner på e-post og/eller SMS, hvis signering skjer i portalflyt. Ved signering i direkteflyt er det avsender som står for varsling til undertegner. Avsender som bruker API kan adressere med fødselsnummer adressere uten fødselsnummer adressere med egenvalgt identifikator (eksempelvis kundenummer) Avsender som bruker avsenderportal på web kan adressere med fødselsnummer adressere uten fødselsnummer (N.B: Kun hvis privat virksomhet) Det signerte dokumenter vil inneholde navn på undertegner og hvilken elektronisk ID som ble brukt. Man kan for øvrig velge hvilken identifikator man ønsker i signerte dokumenter. 11.1 Adressering med fødselsnummer For å adressere med fødselsnummer må du vite undertegners fødselsnummer, samt e-postadresse og/eller mobilnummer. Denne måten å adressere på gir en sikker identifisering av undertegner, siden kun én bestemt person har mulighet til å åpne og signere dokumentet. 21

Ved Signering i portalflyt med fødselsnummer må undertegner logge inn i signeringsportalen før han kan se og signere dokumentet. Dette gjør altså at kun riktig person har mulighet til å lese og signere. Se signering i portalflyt, adressering med f.nr her. Ved Signering i direkteflyt er undertegner logget inn i avsenders system, og det er da avsender som er ansvarlig for å sende undertegner til riktig lenke i signeringstjenesten. Når du som avsender velger adressering med fødselsnummer, kan du velge å inkludere fødselsnummeret i det signerte dokumentet. 11.2 Adressering uten fødselsnummer Ved adressering uten fødselsnummer blir ikke signeringsoppdraget knyttet til én spesifikk person. Derfor krever signeringstypen ingen innlogging, og du trenger ikke vite undertegners fødselsnummer. I stedet sender du kun inn e-postadressen og/eller mobilnummeret som skal motta varsel om signeringen. Se varsler for å se hvordan varselet ser ut. Ved Signering i portalflyt uten fødselsnummer får undertegner en unik lenke og en kode, og han kan se og signere dokumentet uten innlogging. Ved Signering i direkteflyt så sender du fra API. Da har du mulighet til å bruke en egenvalgt identifikator i stedet for e-postadresse og mobilnummer. Dette kan f.eks. være et kundenummer. Når du som avsender velger adressering uten fødselsnummer, vil ikke fødselsnummeret bli inkludert i det signerte dokumentet, av personvernmessige hensyn. Du vil fortsatt få med navn og eventuelt fødselsdato i det signerte dokumentet. Important: Selve signaturen er like sikker og gyldig som når du adresserer med fødselsnummer, men du som avsender er ansvarlig for at riktig person åpner og signerer dokumentet. 22 Chapter 11. Adressering av undertegner

CHAPTER 12 Kontaktinformasjon Alle undertegnere må ha minst én av e-postadresse og mobilnummer. Sending av SMS er frivillig og kan bestilles av tjenesteeieren, dette koster 40 øre per SMS. Dersom en undertegner har mobilnummer og ikke e-postadresse vil det alltid bli sendt SMS. Tjenesten støtter kun norske mobilnumre. Som bedrift må du selv vite og legge til e-postadressen og/eller mobilnummeret til undertegner. Det er ikke mulig å bruke Kontakt- og reservasjonsregisteret. For offentlige virksomheter gjør vi oppslag i Kontakt- og reservasjonsregisteret hvis ikke kontaktinformasjon overstyres. Caution: Hvis undertegnere er reservert mot digital kommunikasjon vil oppdraget bli avvist og påfølgende uthenting av status for oppdraget vil gi en feil med informasjon om hvilke undertegnere som er reservert. Undertegnere med overstyrt kontaktinformasjon blir ikke sjekket for reservasjon. Note: Det er kun tillatt å overstyre kontaktinformasjon som en offentlig virksomhet hvis undertegner ikke signerer som privatperson, det vil si signerer i kraft av en rolle for en virksomhet. 12.1 Bruk av Kontakt- og reservasjonsregisteret Ytterligere informasjon rundt bruk av Kontakt- og reservarsjonregisteret Ved utsending av senere varsler (enten utsatt aktivering på grunn av kjedet signatur eller påminnelser) blir det gjort et nytt oppslag mot registeret for å hente ut den sist oppdaterte kontaktinformasjonen. Dersom Oppslagstjenesten for Kontakt- og reservasjonsregisteret er utilgjengelig ved utsending av påminnelser vil resultatet fra oppslaget ved opprettelse av oppdraget bli brukt. 23

Reservasjon ved utsatte førstegangsvarsler: I scenariet der tjenesteeier har satt en kjedet rekkefølge på undertegnerne, og førstegangsvarsel skal sendes til en undertegner som i perioden mellom oppdraget ble opprettet og førstegangsvarsel skal sendes har reservert seg mot elektronisk kommunikasjon, så vil hele oppdraget feile. Reservasjon ved påminnelser: Hvis sluttbrukeren har reservert seg etter at oppdraget ble opprettet, men oppdraget allerede er aktivert, vil det ikke bli sendt påminnelser (e-post/sms), men oppdraget vil heller ikke feile før signeringsfristen eventuelt løper ut. Oppdrag med overstyrt kontaktinformasjon med utenlandsk mobilnummer vil bli avvist, mens utenlandske mobilnumre fra Kontakt- og reservasjonsregisteret vil bli ignorert. 24 Chapter 12. Kontaktinformasjon

CHAPTER 13 Varsler: Regler for utsending For å sørge for at undertegner mottar varsler og påminnelser i passende tidsrom, er tidspunktene for når varsler blir sendt ut avhengig av signeringsfristen for et oppdrag. Hvis avsender har lagt til både e-postadressen og mobilnummeret til undertegner, sendes det ut inntil 3 varsler om signeringen: Et førstegangsvarsel umiddelbart etter aktivering, påminnelse på e-post, og til slutt en siste påminnelse på SMS. Bakgrunnen for dette oppsettet, er at e-post da benyttes som primær varslingskanal og at SMSen skal fungere som et siste, eskalerende varsel. Signeringsfrist 1. varsel: e-post 2. varsel: e-post 3. varsel: SMS 0-24 timer Ved aktivering Ved aktivering 2-3 dager Ved aktivering 1 dag før frist 1 dag før frist 4-5 dager Ved aktivering 2 dager før frist 1 dag før frist 6-9 dager Ved aktivering 3 dager før frist 2 dager før frist 10+ dager Ved aktivering 5 dager før frist 2 dager før frist Hvis avsender har lagt til kun e-postadressen eller kun mobilnummeret til undertegner, sendes det ut inntil 2 varsler om signeringen: Et førstegangsvarsel umiddelbart etter aktivering, og én påminnelse på henholdsvis e-post eller SMS. Signeringsfrist 1. varsel: e-post/sms 2. varsel: e-post/sms 0-24 timer Ved aktivering 2-3 dager Ved aktivering 1 dag før frist 4-5 dager Ved aktivering 2 dager før frist 6-9 dager Ved aktivering 3 dager før frist 10+ dager Ved aktivering 5 dager før frist Note: SMS sendes ikke ut mellom klokken 22:00 og 08:00, med mindre oppdraget opprettes på natten og fristen er 25

så kort at det er nødvendig med umiddelbar utsending. Note: Hvis avsender utvider signeringsfristen slettes alle planlagte varsler for oppdraget. Det blir da generert nye varsler som sendes ut på relative tidspunkt knyttet til den nye fristen. Caution: Får å unngå at vi kommer i skade for å sende varsler til reelle mottakere i testmiljøer, er det lagt inn noen sikkerhetsmekanisme i difitest og difiqa: e-postvarsler inkluderer en setning som indikerer at varselet kommer fra et testmiljø: Dette er en test-e-post sendt for Difi fra Postens signeringstjeneste og SMS-varslene erstattes i sin helhet med setningen: Dette er en test-sms sendt for Difi fra Postens signeringstjeneste. 26 Chapter 13. Varsler: Regler for utsending

CHAPTER 14 Varseltekster for undertegnere Oppsettet på varslene som blir sendt ut er predefinert og ikke mulig å endre på for deg som avsender, men du kan legge til en tittel/beskrivelse av dokumentet som skal signeres. Innholdet i varselet vil variere ut fra om adresseringen til undertegner er med eller uten fødselsnummer hvilken kanal de sendes i (e-post/sms) sektor som avsender sender fra (privat eller offentlig) antall undertegnere på oppdraget Nedenfor vises de ulike variantene av varslene som sendes på e-post og SMS. 14.1 Varsel om dokument til signering, ved adressering med fødselsnummer E-post 1. varsel Emne: Dokument til signering fra [Avsender] Hei! Du har fått en forespørsel om å signere et dokument fra [Avsender]: [Tittel på dokumentet]. Dokumentet er nå signert av [antall] og må signeres innen [signeringsfrist] / Dokumentet må signeres innen [signeringsfrist]. Du kan signere med [disse elektroniske e-idene]. Logg deg inn på [signering.posten.no/logginn] for å signere dokumentet. Hilsen Posten E-post 2. varsel 27

Emne: Påminnelse: Dokument til signering fra [Avsender] Hei! Vi vil minne om at du fortsatt har et dokument til signering fra [Avsender]: [Tittel på dokumentet]. Dokumentet er nå signert av [antall] og må signeres innen [signeringsfrist] / Dokumentet må signeres innen [signeringsfrist]. Du kan signere med [disse elektroniske e-idene]. Logg deg inn på [signering.posten.no/logginn] for å signere dokumentet. Rekker du ikke å signere innen fristen? Usignerte dokumenter slettes når fristen går ut. Kontakt [Avsender] for å få dokumentet tilsendt på nytt. Hilsen Posten SMS 1. varsel Du har et dokument til signering fra [Avsender]. Logg inn og signer på [signering.posten.no/logginn] innen [signeringsfrist]. SMS 2./3. varsel Du har et usignert dokument fra [Avsender]. Logg inn og signer på [signering.posten.no/logginn] innen [signeringsfrist]. 14.2 Varsel om dokument til signering, ved adressering uten fødselsnummer E-post 1. varsel Emne: Dokument til signering fra [Avsender] Hei! Du har fått en forespørsel om å signere et dokument fra [Avsender]: [Dokumenttittel]. Dokumentet er nå signert av [antall] og må signeres innen [signeringsfrist] / Dokumentet må signeres innen [signeringsfrist]. Du kan signere med disse elektroniske ID-ene. Slik signerer du: 1) Klikk på lenken under 2) Skriv inn sikkerhetskode XXXX 3) Les og signer dokumentet [https://signering.posten.no/uniklenke] Hilsen Posten E-post 2. varsel Emne: Dokument til signering fra [Avsender] Hei! Vi vil minne om at du fortsatt har et dokument til signering fra [Avsender]: [Dokumenttittel]. [Dokumentet er nå signert av [*antall] og må signeres innen [signeringsfrist] / Dokumentet må signeres innen [signeringsfrist]. Du kan signere med [disse elektroniske ID-ene]. Slik signerer du: 1) Klikk på lenken under 2) Skriv inn sikkerhetskode [XXX] 3) Les og signer dokumentet [https://signering.posten.no/uniklenke] Rekker du ikke å signere innen fristen? Usignerte dokumenter slettes når fristen går ut. Kontakt [Avsender] for å få dokumentet tilsendt på nytt. 28 Chapter 14. Varseltekster for undertegnere

Hilsen Posten SMS 1. varsel Hei! [Avsender] ber deg signere et dokument. Bruk kode [XXXX] på [https://signering.posten.no/uniklenke] før [signeringsfrist]. SMS 2./3. varsel Hei! Husk signering for [Avsender]. Bruk kode [XXXX] på [https://signering.posten.no/uniklenke] før [signeringsfrist]. 14.3 Etter signering: Varsel om oppsalg til digital postkasse Etter at en undertegner har signert et dokument, vil hun i disse tilfeller få mulighet til å opprette en digital postkasse. Hvis avsender er privat, vil undertegner få mulighet til å opprette konto hos Digipost, og hvis avsender er offentlig vil undertegner kunne velge digital postkasse på Norge.no. Innholdet i dette varselet er ulikt avhengig av hvor mange undertegnere som skal signere dokumentet, og om avsender er privat eller offentlig. 14.3.1 Private avsendere E-post, én undertegner Emne: Motta det signerte dokumentet i Digipost Hei! Du har nettopp signert et dokument fra [Avsender] gjennom Posten signering. Hvis du oppretter en konto i Digipost innen 7 dager, sendes dokumentet du signerte automatisk dit. Da har du det lett tilgjengelig når du trenger det! Registrer deg i Digipost: https://www.digipost.no/app/registrering, Hilsen Posten E-post, flere undertegnere Emne: Motta det signerte dokumentet i Digipost Hei! Du har tidligere signert et dokument fra [Avsender] gjennom Posten signering. Nå har alle undertegnerne signert, og avsender har mottatt det ferdigsignerte dokumentet. Hvis du også ønsker å motta dokumentet med alle signaturer, må du opprette en konto i Digipost innen 7 dager. Da sendes dokumentet automatisk dit, så har du det lett tilgjengelig når du trenger det. Registrer deg i Digipost: https://www.digipost.no/app/registrering, Hilsen Posten SMS, én undertegner Hei, du har nettopp signert et dokument fra [Avsender] gjennom Posten signering. Hvis du oppretter en konto i Digipost innen 7 dager, sendes dokumentet du signerte automatisk dit: https://www.digipost.no/app/registrering SMS, flere undertegnere Hei! Du har tidligere signert et dokument fra [Avsender] gjennom Posten signering. 14.3. Etter signering: Varsel om oppsalg til digital postkasse 29

Nå har alle undertegnerne signert. Hvis du også ønsker å motta dokumentet med alle signaturer, må du opprette en konto i Digipost innen 7 dager. Da sendes dokumentet automatisk dit, så har du det lett tilgjengelig når du trenger det: https://www.digipost.no/app/registrering 14.3.2 Offentlige avsendere E-post, én undertegner Emne: Motta det signerte dokumentet i din digitale postkasse Hei! Du har nettopp signert et dokument fra [Avsender] gjennom den nasjonale fellesløsningen e-signering. Hvis du oppretter en konto i Digipost innen 7 dager, sendes dokumentet du signerte automatisk dit. Da har du det lett tilgjengelig når du trenger det! Opprett digital postkasse: https://www.norge.no/velg-digital-postkasse E-post, flere undertegnere Emne: Motta det signerte dokumentet i din digitale postkasse Hei! Du har tidligere signert et dokument fra [Avsender] gjennom den nasjonale fellesløsningen e-signering. Nå har alle undertegnerne signert, og avsender har mottatt det ferdigsignerte dokumentet. Hvis du også ønsker å motta dokumentet med alle signaturer, må du opprette en digital postkasse innen 7 dager. Da sendes dokumentet automatisk dit, så har du det tilgjengelig når du trenger det! Opprett digital postkasse: https://www.norge.no/velg-digital-postkasse SMS, én undertegner Hei, du har nettopp signert et dokument fra [Avsender] gjennom den nasjonale fellesløsningen e-signering. Hvis du oppretter en digital postkasse innen 7 dager, sendes dokumentet du signerte automatisk dit: https://www.norge.no/ velg-digital-postkasse SMS, flere undertegnere Hei, du har tidligere signert et dokument fra [Avsender] gjennom den nasjonale fellesløsningen e-signering. Nå har alle undertegnerne signert. Hvis du også ønsker å motta dokumentet med alle signaturer, må du opprette en digital postkasse innen 7 dager. Da sendes dokumentet automatisk dit, så har du det lett tilgjengelig når du trenger det: https://www.norge.no/velg-digital-postkasse 14.4 Varsel om kansellert oppdrag Hvis avsender kansellerer et signeringsoppdrag, blir det sendt ut et varsel til undertegner om dette: E-post Emne: Kansellert: Dokument til signering fra [Avsender] Hei! [Avsender] har trukket tilbake forespørselen om signering av [Dokumenttittel]. Kontakt [Avsender] om du lurer på hvorfor de kansellerte, eller om du ønsker dokumentet tilsendt på nytt. Hilsen Posten 30 Chapter 14. Varseltekster for undertegnere

CHAPTER 15 Endring av signeringsoppdrag 15.1 Handlinger som stopper et signeringsoppdrag Hvis det gjøres en terminerende handling på et signeringsoppdrag vil oppdraget avsluttes og undertegnere som fortsatt ikke har signert vil miste muligheten til dette. Avsenderen blir varslet om at signeringsoppdraget er avsluttet med en status som beskriver hvilken handling som ble gjort. De ulike handlingene som avslutter et signeringsoppdrag er: En undertegner avviser oppdraget Avsender kansellerer oppdraget Oppdragets utløpstidspunkt blir passert Eksempel Avsender oppretter et oppdrag med tre undertegnere. Undertegner 1 signerer, undertegner 2 avviser. Dersom undertegner 3 logger inn i signeringsportalen etter at undertegner 2 har avvist, vil hun ikke se signeringsoppdraget og vil ikke ha mulighet til å signere. 15.2 Kansellere signeringsoppdrag Kansellering av signeringsoppdrag er bare relevant for signeringsoppdrag i portalflyt. Et signeringsoppdrag kan på et hvilket som helst tidspunkt kanselleres av avsender, så lenge ikke oppdraget allerede er fullført. Kansellerte oppdrag blir utilgjengeliggjort for undertegnere som enda ikke har signert. 31

32 Chapter 15. Endring av signeringsoppdrag

CHAPTER 16 Varseltekster for avsendere Alle avsendere er registrert i tjenesten med e-postadresse, og varsler sendes derfor på e-post. En avsenders e- postadresse er knyttet til brukeren i tjenesten, og sendes aldri inn ifm. opprettelse av oppdrag. Note: Det er kun brukeren som har opprettet signeringsoppdraget som vil få e-poster knyttet til et oppdrag. Det sendes ut varsler til avsender i to tilfeller: 1. Når signeringsoppdrag endrer status: Varselet inneholder en oversikt over samtlige undertegneres signeringsstatus. Det blir sendt én e-post for hver undertegner som gjør noe, dvs. signerer eller avviser, eller når signeringsfristen er gått ut. 2. 24 timer før signeringsfristen for ett oppdrag går ut: Varselet sendes ut som en påminnelse til avsender om at noen fortsatt ikke har signert. Avsender kan da velge å utsette signeringsfristen, eller purre på undertegnerne ved å sende ekstra varsel. N.B: Varselet sendes kun hvis oppdragets opprinnelige signeringsfrist var mer enn 48 timer. 16.1 Varsel når signeringsoppdrag endrer status Statusendring Emne: Oppdatert signeringsstatus: Dokumentet er [delvis signert]/[ferdig signert]/[ferdig, men ufullstendig] Hei! Vi vil informere deg om at dokumentet med referanse [XXXX] har endret status til [delvis signert]/[ferdig signert]/[ferdig, men ufullstendig]. Undertegner ****: [Venter]/[Avvist]/[Signert]/[Sperret] Logg deg inn på [https://signering.posten.no/virksomhet/#/] for å (utsette fristen eller for å) se detaljer om dokumentet. Hilsen Posten Fristen går snart ut Emne: Signeringsfristen går ut om 24 timer 33

Hei! Dkoumentet med referanse [XXXX] er fortsatt ikke signert av [undertegnere]. Det er nå kun 24 timer til signeringsfristen utløper. Du kan utsette fristen for signeringen ved å logge inn og klikke på Utsett signeringsfrist. Om dokumentet ikek signeres innen fristen, stoppes prosessen, og du må eventuelt sende dokumentet på nytt for å hente inn signaturer. Logg deg inn på [https://signering.posten.no/virksomhet/#/] for å utsette fristen eller for å se detaljer om dokumentet. Hilsen Posten 34 Chapter 16. Varseltekster for avsendere

CHAPTER 17 Lagring 17.1 Langtidslagring Posten signering tilbyr en tilleggstjeneste for langtidslagring av originaldokument og signerte dokumenter. Tjenesten må aktiveres før en avsender kan ta den i bruk. For avsendere med langtidslagring aktivert, lagres alle dokumenter i minst 50 år. Dersom langtidslagring ikke er aktivert kan dokumentene bli utilgjengeliggjort etter 40 dager. Avsendere som bruker avsenderportalen kan få tilgang til langtidslagrede dokumenter via sin konto på web. For avsendere som integrerer med tjenesten via API, er dokumentene tilgjengelig via REST-grensesnittet. Signeringstjenesten langtidslagrer kun XAdES. Når man henter PAdES genereres denne der og da, basert på XAdES. 17.2 Sletting av dokumenter Avsendere kan slette arkiverte dokumenter hvis de ønsker å fjerne dem fra arkivet. Avsendere som bruker avsenderportalen kan slette dokumenter derfra. For avsendere som integrerer via API, kan dokumentene slettes via RESTgrensesnittet. 17.2.1 Begrensninger Alle undertegnere må ha signert før dokumentene kan slettes. Dokumenter som ikke blir signert av samtlige undertegnere vil slettes automatisk etter 40 dager, og kan ikke slettes manuelt av avsender. Dokumenter kan tidligst slettes 24 timer etter signeringtidspunkt, da undertegnerne skal ha mulighet til å laste ned dokumentet i et døgn. Dokumenter som skal sendes til undertegners digitale postkasse kan ikke slettes før de har blitt sendt dit. Dersom undertegner ikke har digital postkasse ventes det inntil 7 dager før dokumentene kan slettes. 35

36 Chapter 17. Lagring

CHAPTER 18 GDPR Vi sletter på generell basis data som vi ikke lenger har bruk for etter 3 år. Sletting blir gjort på ulik måte avhengig av hvilken type data det er snakk om. Under følger en oppsummering av når vi sletter hvilken type data, og hvilke krav som gjelder for sletting: 18.1 Varsler Vi sletter epost- og SMS-varsler 3 år etter siste gang de ble forsøkt sendt. 18.2 Signeringsoppdrag Vi sletter signeringsoppdrag 3 år etter at arkivbehov opphører. Det betyr at hvis en avsender oppretter et oppdrag i dag, så vil det ta 40 dager (eller 50 år hvis avsender bruker langtidsarkiv) før selve dokumentet blir slettet. 3 år etter dette sletter vi oppdraget med tilhørende data. Tilhørende data er jobb-events, kø for jobbendringer, informasjon om videresending til postkassen, varsler, undertegnere og selve oppdraget. 18.2.1 Tilgjengelighet for undertegner Oppdraget er tilgjengelig for undertegner i 24 timer etter signering. Grunnen til at det ikke er 40 dager eller 50 år er fordi vi ikke skal måtte innhente godkjente villkår fra undertegner - dette vil komplisere signeringsflyten. Ved å ha mulighet til å hente det inn i noe tid etter signering så gir vi de som ikke skjønte at de måtte laste det ned en sjanse til å prøve igjen. 18.3 Brukere Brukere kan deaktiveres fra web i avsenderportalen, av kontoforvaltere i den aktuelle virksomheten, eller av Posten og Difi gjennom administrasjonsportalen. En deaktivert bruker vil anonymiseres og slettes etter følgende regler: 37

Anonymisering: En bruker anonymiseres 3 år etter at hun ble deaktivert. Sletting: En bruker slettes 3 år etter at hun ble deaktivert hvis hun ikke har noe tilknytning til noe signeringsoppdrag. En slik tilknytning vil være at hun f.eks. har endret signeringsfristen på et oppdrag eller at hun selv har opprettet oppdraget. Merk at disse hendelsene skjer på samme tidspunkt, men at de har forskjellige krav som må oppfylles. Dette betyr at oppgavene kan kjøre uavhengig av hverandre dersom behovene skulle endre seg på sikt. 18.4 Virksomheter Deaktivering: En virksomhet kan deaktiveres med umiddelbar virkning. Etter deaktivering, beholder vi dataene i 3 måneder. Sletting: Sletting av virksomheten skjer etter at en virksomhet har vært deaktivert i 3 måneder. Da slettes alle data som er knyttet til virksomheten. 38 Chapter 18. GDPR

CHAPTER 19 Sikkerhetsnivå Som avsender har man mulighet til å angi hvilket sikkerhetsnivå signeringsoppdraget skal ha. Dette kan være 3 eller 4, og begrenser hvilke elektroniske ID-er undertegner kan bruke for å signere dokumentet. Sikkerhetsnivået begrenser også hvilke innloggingsmetoder undertegner kan bruke for å se signeringsoppdraget og dets detaljer, samt begynne selve signeringen. Tip: Om ingen signaturtype angis ved opprettelse av oppdraget, vil nivå 4 settes som standard. 19.1 Bedrift Som en bedrift har du kun mulighet til å bruke det høyeste sikkerhetsnivået, nivå 4, og du trenger derfor ikke ta stilling til dette. Tip: Tilgjengelige metoder for innlogging og signering er BankID, BankID på mobil og Buypass. 19.2 Offentlig virksomhet Som offentlig virksomhet kan du velge sikkerhetsnivå 3 eller 4. Et signeringsoppdrag som er på nivå 4 vil kun kunne vises og signeres i sin helhet med alle e-ider unntatt MinID, som er sikkerhetsnivå 3. Er bruker innlogget på nivå 3 vil få en begrenset visning av signeringsoppdraget, der kun ikke-sensitiv tittel er synlig. For å se alle detaljer om oppdraget vil brukeren bli bedt om å logge inn på nytt på til sikkerhetsnivå 4. Brukeren vil alltid bli veiledet til den innloggingsmetoden som kreves for oppdraget som skal signeres, slik at brukeropplevelsen blir så god som mulig. 39

Tip: Tilgjenglige metoder for innlogging og signering er BankID, BankID på mobil, Buypass id på smartkort, Buypass id i mobil og Commfides. 40 Chapter 19. Sikkerhetsnivå

CHAPTER 20 Kjedet signering I tillegg til å kunne tilby Signering i direkteflyt og Signering i portalflyt, så har Posten signering lagt opp til å støtte mer avanserte flyter. Avsendere som integrerer gjennom API og bruker portalflyt kan spesifisere en signeringsrekkefølge for undertegnerne. Når alle undertegnerne i en gruppe har signert, vil oppdraget bli tilgjengelig for neste gruppe. En gruppe undertegnere er alle som har samme rekkefølge (order) i APIet og kan bestå av én eller flere undertegnere som skal signere i parallell. Tip: For kjedete signeringsoppdrag gjelder aktiveringstidspunktet for første gruppe. 20.1 Eksempel Kjedet signering kan være ønskelig i flere tilfeller. La oss ta en eiendomsmegler som eksempel. Man kan se for seg at det er ønskelig at en megler bare skal bruke tid på å signere et dokument først etter at kjøper av boligen har signert. Dette vil være tidsbesparende og fornuftig, ettersom forutsetningen for at megler skal signere er at kjøper har signert. Ved å sette kjøper til å ha order=0 og selger ha order=1 så vil man få denne oppførselen. Tip: Oppdraget vil være like lenge tilgjengelig for alle parter ved kjedet signering. I eksemplet over betyr det at hvis levetiden på signeringsoppdraget settes til 1 uke, og kjøper signerer etter 3 dager, så vil megler fra dette tidspunktet få 1 uke på å signere. Siste dag megler kan signere er derfor 10 dager etter opprettelsestidspunkt (3+7 dager). 20.2 Terminerende handlinger for kjedete signeringsoppdrag En terminerende handling på et kjedet signeringsoppdrag vil føre til at oppdraget avsluttes for alle undertegnere som enda ikke har signert, inkludert de undertegnere som ikke har fått oppdraget tilgjengeliggjort enda. 41

Hvis en undertegner i første gruppe avviser oppdraget eller signeringsfristen går ut, vil oppdraget aldri tilgjengeliggjøres for undertegnerne i de senere gruppene og avsender blir varslet om at oppdraget er fullført med en feilende status. 42 Chapter 20. Kjedet signering

CHAPTER 21 Buy enterprise certificates As a sending organization, you must authenticate with an enterprise certificate issued by Buypass or Commfides. You will need a test certificate and a production certificate. 21.1 Test environment A test certificate must be used against our test environment. The test certificate will be used in the testing phase, and as soon as you are ready to go into production, you will have to replace it with a production certificate. Note: It is not possible to use a test certificate in production or the other way around. Buypass Please select Test- A test certificate can be bought from Buypass, on either their Norwegian or English site. sertifikat/test certificate. When buying an enterprise certificate from Buypass, you will receive an email containing two.p12 files. The two files have different serial numbers, and these refer to certficates used for authentication and encryption (autentisering og kryptering) and signature (signering). You shall only use the one marked for authentication and encryption. Commfides A test certificates can be bought from Commfides, on either their Norwegian or English site. Testsertifikat/Order Test Certificate. Please see Bestill When buying an enterprise certificate from Commfides, you will receive an email containing three.p12 files: auth, enc and sign. You shall use the one named auth with Key Usage = Digital Signature. Caution: Please ask Commfides to create a certificate with CN=Commfides CPN Enterprise-Norwegian SHA256 CA - TEST2. A certificate with CN=Commfides CPN Enterprise-Norwegian SHA256 CA - TEST will not work. 43

21.2 Production environment Danger: Both the production enterprise certificate and the password must be stored securely. Do not under any circumstances send the file or the password to anyone. Buypass A production certificate can be bought from Buypass, on either their Norwegian or English site. Please select Standard sertifikat/standard Certificate. When buying an enterprise certificate from Buypass, you will receive an email containing two.p12 files. The two files have different serial numbers, and these refer to certficates used for authentication and encryption (autentisering og kryptering) and signature (signering). You shall only use the one marked for authentication and encryption. Commfides A production can be bought from Commfides, on either their Norwegian or English site. Please see Bestill Virksomhetssertifikat/Order Enterprise Certificate for use in a production environment. When buying an enterprise certificate from Commfides, you will receive an email containing three.p12 files: auth, enc and sign. You shall use the one named auth with Key Usage = Digital Signature. 44 Chapter 21. Buy enterprise certificates

CHAPTER 22 Install enterprise certificate In order to use the client, the enterprise certificate must be set up according to your environment. We currently support.net Core,.NET Framework and Java. Note: The.NET Framework version of the client only exists for versions 1 to 4. The documentation can be found here. The documentation for installing the certificate is the same, though. 22.1.NET Core 22.1.1 Install the certificate The path and password to the certificate must be put somewhere safe. The path is: Windows %APPDATA%\Microsoft\UserSecrets\<user_secrets_id>\secrets.json macos ~/.microsoft/usersecrets/<user_secrets_id>/secrets.json Linux ~/.microsoft/usersecrets/<user_secrets_id>/secrets.json Tip: For more information, please see the Microsoft documentation. Add the following UserSecretsId element to your.csproj file: 45

<PropertyGroup> <TargetFramework>netcoreapp2.1</TargetFramework> <UserSecretsId>enterprise-certificate</UserSecretsId> </PropertyGroup> This means that the element <user_secrets_id> in the path will be enterprise-certificate. From the command line, navigate to the directory where the current.csproj file is located and run the following commands with your own certificate values. dotnet user-secrets set "Certificate:Path:Absolute" "<your-certificate.p12>" dotnet user-secrets set "Certificate:Password" "<your-certificate-password>" 22.1.2 Trust the certificate In addition to installing the certificate, you must add the certificate to the trust store on the host machine. Windows Double click the enterprise certificate and choose to install on Local Machine or Current user. This will install the intermediate and root certificate on the host, which is what we want. macos Linux 1. Open Keychain Access 2. Choose login keychain 3. Press the plus-symbol in bottom corner - Create a new Keychain item. 4. Choose the business certificate and add. Download the root and intermediate certificates from Difi for your business certificate provider. Note the renaming to have.crt ending for update-ca-certificates: sudo cp Buypass_Class_3_Test4_Root_CA.pem /usr/local/share/ca-certificates/buypass_ Class_3_Test4_Root_CA.crt sudo cp Buypass_Class_3_Test4_CA_3.pem /usr/local/share/ca-certificates/buypass_class_ 3_Test4_CA_3.crt sudo update-ca-certificates 22.2.NET Framework Note:.NET Framework is only supported on the Windows platform. The following steps will install the certificate in the your certificate store. This should be done on the server where your application will run. 1. Double-click on the actual certificate file (CertificateName.p12) 2. Save the certificate in Current User or Local Machine and click Next 3. Use the suggested filename. Click Next 4. Enter password for private key and select Mark this key as exportable... Click Next 46 Chapter 22. Install enterprise certificate

5. Select Automatically select the certificate store based on the type of certificate 6. Click Next and Finish 7. Accept the certificate if prompted 8. When prompted that the import was successful, click OK Note: If you for some reason are not allowed to store the business certificate with the exportable flag, it can be added to the store using the following script: certutil -p <password> -csp Microsoft Enhanced RSA and AES Cryptographic Provider -importpfx <filename> NoExport,AT_SIGNATURE. In order to use the certificate you have just installed, the thumbprint of the certificate must be retrieved. It can be done in the following way: 1. Start mmc.exe (Press the windows button and type mmc.exe) 2. Choose File -> Add/Remove Snap-in... (Ctrl + M) 3. Mark certificate and click Add > 4. If the certificate was installed in Current User choose My User Account and if installed on Local Machine choose Computer Account, click Finish and then OK 5. Expand Certificates node, select Personal and open Certificates 6. Double-click on the installed certificate 7. Go to the Details tab 8. Scroll down to Thumbprint 9. Copy the thumbprint 22.3 Java If you are using the Java client library, there is no need to install the enterprise certificate. It can be loaded directly from file. 22.3. Java 47

48 Chapter 22. Install enterprise certificate

CHAPTER 23 Install client C# The client is available via Nuget. The library has several packages with the prefix Digipost.Signature.Api.Client. If you are using the portal cases, use Digipost.Signature.Api.Client.Portal, and for direct cases, use Digipost. Signature.Api.Client.Direct. Java The client is available via Maven:. Javadoc is available at javadoc.io/doc/no.digipost. 49

50 Chapter 23. Install client

CHAPTER 24 Create client configuration A client configuration includes all organization specific configuration and all settings needed to connect to the correct environment for Posten signering. Java The first step is to load the enterprise certificate (virksomhetssertifikat) through the KeyStoreConfig. It can be created from a Java Key Store (JKS) or directly from a PKCS12-container, which is the usual format of an enterprise certificate. The latter is the recommended way of loading it if you have the certificate stored as a simple file: KeyStoreConfig keystoreconfig; try (InputStream certificatestream = Files.newInputStream(Paths.get("/path/to/ certificate.p12"))) { keystoreconfig = KeyStoreConfig.fromOrganizationCertificate( certificatestream, "CertificatePassword" ); } If you have a Java Key Store file containing the organization certificate, it can be loaded in the following way: KeyStoreConfig keystoreconfig; try (InputStream certificatestream = Files.newInputStream(Paths.get("/path/to/ javakeystore.jks"))) { keystoreconfig = KeyStoreConfig.fromJavaKeyStore( certificatestream, "OrganizationCertificateAlias", "KeyStorePassword", "CertificatePassword" ); } When the certificate has been loaded correctly, a ClientConfiguration can be initialized. A trust store and service Uri needs to be set to properly connect. Please change the trust store and service Uri in the following example when connecting to our production environment. 51

KeyStoreConfig keystoreconfig = null; //As initialized earlier ClientConfiguration clientconfiguration = ClientConfiguration.builder(keyStoreConfig).trustStore(Certificates.TEST).serviceUri(ServiceUri.DIFI_TEST).globalSender(new Sender("123456789")).build(); C# const string organizationnumber = "123456789"; var clientconfiguration = new ClientConfiguration( Environment.DifiTest, CertificateReader.ReadCertificate(), new Sender(organizationNumber) ); Where ReadCertificate is: var pathtosecrets = $"{System.Environment.GetEnvironmentVariable("HOME")}/.microsoft/ usersecrets/enterprise-certificate/secrets.json"; _logger.logdebug($"reading certificate details from secrets file: {pathtosecrets}"); var fileexists = File.Exists(pathToSecrets); if (!fileexists) { _logger.logdebug($"did not find file at {pathtosecrets}"); } var certificateconfig = File.ReadAllText(pathToSecrets); var deserializeobject = JsonConvert.DeserializeObject<Dictionary<string, string>> (certificateconfig); deserializeobject.trygetvalue("certificate:path:absolute", out var certificatepath); deserializeobject.trygetvalue("certificate:password", out var certificatepassword); _logger.logdebug("reading certificate from path found in secrets file: " + certificatepath); return new X509Certificate2(certificatePath, certificatepassword, X509KeyStorageFlags. Exportable); Note: For organizations acting as brokers on behalf of multiple senders, you may specify the sender s organization number on each signature job. The sender specified for a job will always take precedence over the globalsender in ClientConfiguration. 52 Chapter 24. Create client configuration

CHAPTER 25 Direct flow This is an integration pattern suited for senders with their own portals and web solutions, wishing to offer a seamless signing experience as a part of a process where the user is logged in through a senders web portal. The signature prosess will be perceived as an integrated part of the user flow. The user will be redirected to the senders website after the signing is completed. For more information of the flow, please see Signering i direkteflyt. To ease the integration, we provide C# and Java libraries. If you are creating your own client, you will have to interact directly with the API. The message format of the API is XML, and relevant types can be found in direct.xsd. 53

Flow chart for signing in direct flow: The chart shows that a signer is sent to the signing portal from the sender s website and completes the signing process. The sender gets the status, gets the signed document and confirms processing of the job. Solid lines show user flow and dashed lines shows requests to and responses from the API. 25.1 Having problems integrating? Tip: Remember that if you are having problems creating a job in a direct signature flow, you can always get in touch with a human on Github: 54 Chapter 25. Direct flow

C# Get help for your C# integration here. Java Get help for your Java integration here. HTTP Get help for your HTTP integration here. 25.2 Step 1: Create signature job C# ClientConfiguration clientconfiguration = null; //As initialized earlier var directclient = new DirectClient(clientConfiguration); var documenttosign = new Document( "Subject of Message", "This is the content", FileType.Pdf, @"C:\Path\ToDocument\File.pdf"); var exiturls = new ExitUrls( new Uri("http://redirectUrl.no/onCompletion"), new Uri("http://redirectUrl.no/onCancellation"), new Uri("http://redirectUrl.no/onError") ); var signers = new List<Signer> { new Signer(new PersonalIdentificationNumber("12345678910")), new Signer(new PersonalIdentificationNumber("10987654321")) }; var job = new Job(documentToSign, signers, "SendersReferenceToSignatureJob", exiturls); var directjobresponse = await directclient.create(job); Java ClientConfiguration clientconfiguration = null; // As initialized earlier DirectClient client = new DirectClient(clientConfiguration); byte[] documentbytes = null; // Loaded document bytes DirectDocument document = DirectDocument.builder("Subject", "document.pdf", documentbytes).build(); ExitUrls exiturls = ExitUrls.of( "http://sender.org/oncompletion", "http://sender.org/onrejection", "http://sender.org/onerror" ); (continues on next page) 25.2. Step 1: Create signature job 55

(continued from previous page) DirectSigner signer = DirectSigner.withPersonalIdentificationNumber("12345678910"). build(); DirectJob directjob = DirectJob.builder(document, exiturls, signer).build(); DirectJobResponse directjobresponse = client.create(directjob); HTTP The flow starts when the sender sends a request to create the signature job to the API. This request is a multipart message comprised of a document bundle part and a metadata part. The request is a HTTP POST to the resource <rot-url>/direct/signature-jobs. The document bundle is added to the multipart message with application/octet-stream as media type. See Dokumentpakken for more information on the document bundle. The metadata in the multipart request is defined by the direct-signature-job-request element. These are added with media type application/xml. The following example shows the metadata for a signature job: <?xml version="1.0" encoding="utf-8" standalone="yes"?> <direct-signature-job-request xmlns="http://signering.posten.no/schema/v1"> <reference>123-abc</reference> <exit-urls> <completion-url>https://www.sender.org/completed</completion-url> <rejection-url>https://www.sender.org/rejected</rejection-url> <error-url>https://www.sender.org/failed</error-url> </exit-urls> <polling-queue>custom-queue</polling-queue> </direct-signature-job-request> A part of the metadata is a set of URLs defined by the element exit-urls. These URLs will be used by the signature service to redirect the signer back to the sender s portal after completing the signing. The following three URLs must be defined: completion-url: The signer is sent here after a successful signing process. rejection-url: The signer is sent here if he or she chooses to cancel the signing process. error-url: The signer is sent here if something fails during the signing process. This is not a result of a user action. The following is an example of the manifext.xml from the document bundle: <?xml version="1.0" encoding="utf-8" standalone="yes"?> <direct-signature-job-manifest xmlns="http://signering.posten.no/schema/v1"> <signer> <personal-identification-number>12345678910</personal-identification-number> <signature-type>advanced_electronic_signature</signature-type> <on-behalf-of>self</on-behalf-of> </signer> <sender> <organization-number>123456789</organization-number> </sender> <document href="document.pdf" mime="application/pdf"> <title>tittel</title> <description>melding til undertegner</description> (continues on next page) 56 Chapter 25. Direct flow

</document> <required-authentication>3</required-authentication> <identifier-in-signed-documents>personal_identification_number_and_name</ identifier-in-signed-documents> </direct-signature-job-manifest> (continued from previous page) You can specify a signature type and required authentication level. If signature type or required authentication level is omitted, default values as specified by the functional documentation will apply: C# Document documenttosign = null; //As initialized earlier ExitUrls exiturls = null; //As initialized earlier var signers = new List<Signer> { new Signer(new PersonalIdentificationNumber("12345678910")) { SignatureType = SignatureType.AdvancedSignature } }; var job = new Job(documentToSign, signers, "SendersReferenceToSignatureJob", exiturls) { AuthenticationLevel = AuthenticationLevel.Four }; Java //This functionality exists in Java, but the example has not been generated yet. HTTP This functionality exists with integration via HTTP, but the example has not been generated yet. 25.2.1 Other settings Identifier in the signed document C# //This functionality exists in C#, but the example has not been generated yet. Java //This functionality exists in Java, but the example has not been generated yet. HTTP The element identifier-in-signed-documents is used to specify how the signer(s) are to be identified in the signed documents. Allowed values are PERSONAL_IDENTIFICATION_NUMBER_AND_NAME, DATE_OF_BIRTH_AND_NAME and NAME. Please note that applicable values may be restricted by the type of signature job and sender. For more information, see Hvordan identifiseres undertegnere i et ferdig signert dokument?. 25.2. Step 1: Create signature job 57

Status retrieval method C# //This functionality exists in C#, but the example has not been generated yet. Java //This functionality exists in Java, but the example has not been generated yet. HTTP The element status-retrieval-method is used to set how the sender wishes to get status updates for the signature job. WAIT_FOR_CALLBACK is the standard value, and means that the sender waits until a signer is sent to one of the URLs given by the element exit-urls before acting accordingly. The alternative is to use POLLING to specify regular polling to fetch status updates. We recommend using WAIT_FOR_CALLBACK. 25.2.2 Response C# //This functionality exists in C#, but the example has not been generated yet. Java //This functionality exists in Java, but the example has not been generated yet. HTTP The request will result in a response defined by the element direct-signature-job-response. An example of such response for one signer can be seen in the API-specification. This response contains a URL (redirect-url), which redirects the signers browser to initiate the signing process. In addition, the response contains the URL used to retrieve statuses for the job. The sender must wait until the user is redirected to one of the URLs defined in the request, and then send a request to retrieve the latest status update. The status retrieval requires a token that is aquired when the signer is redirected. Please see Step 3: Get status for more information. <direct-signature-job-response xmlns="http://signering.posten.no/schema/v1"> <signature-job-id>1</signature-job-id> <redirect-url> https://signering.posten.no#/redirect/ 421e7ac38da1f81150cfae8a053cef62f9e7433ffd9395e5805e820980653657 </redirect-url> <status-url>https://api.signering.posten.no/api/{sender-identifier}/direct/ signature-jobs/1/status</status-url> </direct-signature-job-response> 25.2.3 The signer Before starting this chapter, please reed up on Kontaktinformasjon Adressering av undertegner. adressed and notified in different ways. Signers can be Adressing the signer C# 58 Chapter 25. Direct flow

//This functionality exists in C#, but the example has not been generated yet. Java //This functionality exists in Java, but the example has not been generated yet. HTTP Social Security Number <signer> <personal-identification-number>12345678910</personal-identification-number> <on-behalf-of>self</on-behalf-of> </signer> For a full example, please see the example manifest for signature type and authentication in the API-specification. Chosen identifier It is possible to use a chosen identifier to create a connection between a person in the senders system and a signature job. A customer number or anything that makes sense the sender can be chosen. <signer> <signer-identifier>kundenummer-134ab47</signer-identifier> <on-behalf-of>self</on-behalf-of> </signer> For a full example, please see eksempelmanifest for selvvalgt identifikator i API-spesifikasjonen. On behalf of A sender can choose if the signer is signing on behalf of himself or by virtue of a role. This is done by setting the attribute on-behalf-of to SELF or OTHER. The signed document will not be sent to the signers digital mailbox if signing on behalf of someone else. <signer> <personal-identification-number>12345678910</personal-identification-number> <on-behalf-of>other</on-behalf-of> </signer> 25.3 Step 2: Signing the document This whole step is carried out in the signing portal. You forward the user to the portal using the URL you receive in response to the creation of the job. This URL contains a one-time token generated by the signature service, and it is this token that allows the user to read the document and complete the signing. If the user aborts the signing, a new redirect URL must be requested in order to access the signature job again. Please see Request new redirect URL to request a new redirect URL. Important: Security in connection with the one-time token: To handle the security of this request, the token will only work once. The user will receive a cookie from the signature service when accessing the URL, so that any refresh does not stop the flow. This URL cannot be reused at a later time. The reason we only allow it to be used only once is that URLs can appear in logs, and it will therefore not be safe to reuse. 25.3. Step 2: Signing the document 59

The user completes the signing and is then returned to the sender s portal via the URL specified by completion url. At the end of this URL, a query parameter (status_query_token) will be added, which you will use later when you ask for the signature job status. If the signer interrupts the signing, or an error occurs, the signer will be sent to the rejection-url or the error-url respectively. 25.4 Step 3: Get status 25.4.1 Status by token The signing process is a synchrounous operation in the direct use case. There is no need to poll for changes to a signature job, as the status is well known to the sender of the job. As soon as the signer completes, rejects or an error occurs, the user is redirected to the respective URLs set in ExitUrls. A status_query_token parameter has been added to the url, use this when requesting a status change. C# ClientConfiguration clientconfiguration = null; //As initialized earlier var directclient = new DirectClient(clientConfiguration); JobResponse jobresponse = null; //As initialized when creating signature job var statusquerytoken = "0A3BQ54C..."; var jobstatusresponse = await directclient.getstatus(jobresponse.responseurls.status(statusquerytoken)); var jobstatus = jobstatusresponse.status; Java DirectClient client = null; // As initialized earlier DirectJobResponse directjobresponse = null; // As returned when creating signature job String statusquerytoken = "0A3BQ54C..."; DirectJobStatusResponse directjobstatusresponse = client.getstatus(statusreference.of(directjobresponse).withstatusquerytoken(statusquerytoken) ); HTTP When the signer is sent back to the sender s portal, you will be able to retrieve the status of the job. This is done by sending an HTTP GET request to the status-url you got in Step 1 where you add the query parameter (status_query_token) you got in Step 2. If the signature job is placed on a specific queue, then the query parameter polling_queue must be set to the queue name. The response from this request is defined by the direct-signature-job-status-response element. An example of this response to a successful signing of a job is shown below: <direct-signature-job-status-response xmlns="http://signering.posten.no/schema/v1"> <signature-job-id>1</signature-job-id> <signature-job-status>completed_successfully</signature-job-status> <status since="2017-01-23t12:51:43+01:00">signed</status> <confirmation-url>https://api.signering.posten.no/api/{sender-identifier}/direct/ signature-jobs/1/complete</confirmation-url> (continues on next page) 60 Chapter 25. Direct flow

<xades-url>https://api.signering.posten.no/api/{sender-identifier}/direct/ signature-jobs/1/xades/1</xades-url> <pades-url>https://api.signering.posten.no/api/{sender-identifier}/direct/ signature-jobs/1/pades</pades-url> </direct-signature-job-status-response> (continued from previous page) 25.4.2 Status by polling If you, for any reason, are unable to retrieve status by using the status query token specified above, you may poll the service for any changes done to your organization s jobs. If the queue is empty, additional polling will give an exception. Note: For the job to be available in the polling queue, make sure to specify the job s StatusRetrievalMethod as illustrated below. C# ClientConfiguration clientconfiguration = null; // As initialized earlier var directclient = new DirectClient(clientConfiguration); // Repeat the polling until signer signs the document, but ensure to do this at a // reasonable interval. If you are processing the result a few times a day in your // system, only poll a few times a day. var change = await directclient.getstatuschange(); switch (change.status) { case JobStatus.NoChanges: // Queue is empty. Additional polling will result in blocking for a defined period. break; case JobStatus.CompletedSuccessfully: // Get PAdES // Get XAdES break; case JobStatus.Failed: break; case JobStatus.InProgress: break; default: throw new ArgumentOutOfRangeException(); } // Confirm status change to avoid receiving it again await directclient.confirm(change.references.confirmation); var pollingwillresultinblock = change.nextpermittedpolltime > DateTime.Now; if (pollingwillresultinblock) { //Wait until next permitted poll time has passed before polling again. } Java 25.4. Step 3: Get status 61

DirectClient client = null; // As initialized earlier DirectJob directjob = DirectJob.builder(document, exiturls, signer).retrievestatusby(statusretrievalmethod.polling).build(); client.create(directjob); DirectJobStatusResponse statuschange = client.getstatuschange(); if (statuschange.is(directjobstatus.no_changes)) { // Queue is empty. Must wait before polling again Instant nextpermittedpolltime = statuschange.getnextpermittedpolltime(); } else { // Received status update, act according to status DirectJobStatus status = statuschange.getstatus(); Instant nextpermittedpolltime = statuschange.getnextpermittedpolltime(); } client.confirm(statuschange); HTTP When the signer is sent back to the sender s portal, you will be able to retrieve the status of the signature job. This is done by sending an HTTP GET request to the status url you received in Step 1. If the signature job is placed on a specific queue, then the query parameter polling_queue must be set to the queue name. The response from this request is defined by the direct-signature-job-status-response element. An example of this response to a successful signing of a job is shown below: <direct-signature-job-status-response xmlns="http://signering.posten.no/schema/v1"> <signature-job-id>1</signature-job-id> <signature-job-status>completed_successfully</signature-job-status> <status since="2017-01-23t12:51:43+01:00">signed</status> <confirmation-url>https://api.signering.posten.no/api/{sender-identifier}/direct/ signature-jobs/1/complete</confirmation-url> <xades-url>https://api.signering.posten.no/api/{sender-identifier}/direct/ signature-jobs/1/xades/1</xades-url> <pades-url>https://api.signering.posten.no/api/{sender-identifier}/direct/ signature-jobs/1/pades</pades-url> </direct-signature-job-status-response> Tip: As illustrated above, you should always query the statuschange to find out when you are allowed to poll for statuses next time. 25.5 Step 4: Get signed documents C# ClientConfiguration clientconfiguration = null; //As initialized earlier var directclient = new DirectClient(clientConfiguration); JobStatusResponse jobstatusresponse = null; // Result of requesting job status (continues on next page) 62 Chapter 25. Direct flow

(continued from previous page) if (jobstatusresponse.status == JobStatus.CompletedSuccessfully) { var padesbytestream = await directclient.getpades(jobstatusresponse.references. Pades); } var signature = jobstatusresponse.getsignaturefor(new PersonalIdentificationNumber( "00000000000")); if (signature.equals(signaturestatus.signed)) { var xadesbytestream = await directclient.getxades(signature.xadesreference); } Java DirectClient client = null; // As initialized earlier DirectJobStatusResponse directjobstatusresponse = null; // As returned when getting job status if (directjobstatusresponse.ispadesavailable()) { InputStream padesstream = client.getpades(directjobstatusresponse.getpadesurl()); } for (Signature signature : directjobstatusresponse.getsignatures()) { if (signature.is(signerstatus.signed)) { InputStream xadesstream = client.getxades(signature.getxadesurl()); } } HTTP In the previous step you got two links: xades-url and pades-url. Do a HTTP GET on these to download the signed document in the two formats. For more information on the format of the signed document, see Signerte dokumenter. 25.6 Steg 5: Confirm finished processing C# //This functionality exists in C#, but the example has not been generated yet. Java //This functionality exists in Java, but the example has not been generated yet. HTTP Finally, make a HTTP POST request to the confirmation-url to confirm that you have completed the job. If Langtidslagring is used, this will mark the assignment as completed and stored. Otherwise, the assignment will be deleted from the signing portal. 25.6. Steg 5: Confirm finished processing 63

25.7 Specifying queues Specifies the queue that jobs and status changes for a signature job will occur in for signature jobs where StatusRetrievalMethod == POLLING. This is a feature aimed at organizations where it makes sense to retrieve status changes from several queues. This may be if the organization has more than one division, and each division has an application that create signature jobs through the API and want to retrieve status changes independent of the other division s actions. To specify a queue, set Sender pollingqueue through when constructing a sender. Please note that the same sender must be specified when polling to retrieve status changes. The Sender can be set globally in ClientConfiguration or on every job. C# ClientConfiguration clientconfiguration = null; // As initialized earlier var directclient = new DirectClient(clientConfiguration); String organizationnumber = "123456789"; var sender = new Sender(organizationNumber, new PollingQueue("CustomPollingQueue")); Document documenttosign = null; // As initialized earlier ExitUrls exiturls = null; // As initialized earlier var signer = new PersonalIdentificationNumber("00000000000"); var job = new Job( documenttosign, new List<Signer> { new Signer(signer) }, "SendersReferenceToSignatureJob", exiturls, sender, StatusRetrievalMethod.Polling ); await directclient.create(job); var changedjob = await directclient.getstatuschange(sender); Java DirectClient client = null; // As initialized earlier Sender sender = new Sender("000000000", PollingQueue.of("CustomPollingQueue")); DirectJob directjob = DirectJob.builder(document, exiturls, signer).retrievestatusby(statusretrievalmethod.polling).withsender(sender).build(); client.create(directjob); DirectJobStatusResponse statuschange = client.getstatuschange(sender); if (statuschange.is(directjobstatus.no_changes)) { // Queue is empty. Must wait before polling again } else { // Recieved status update, act according to status DirectJobStatus status = statuschange.getstatus(); } (continues on next page) 64 Chapter 25. Direct flow

(continued from previous page) client.confirm(statuschange); HTTP This functionality exists with integration via HTTP, but the example has not been generated yet. 25.8 Delete documents After receiving a status change, the documents can be deleted as follows: C# //This functionality exists in C#, but the example has not been generated yet. Java DirectClient client = null; // As initialized earlier DirectJobStatusResponse directjobstatusresponse = null; // As returned when getting job status client.deletedocuments(directjobstatusresponse.getdeletedocumentsurl()); HTTP This functionality exists with integration via HTTP, but the example has not been generated yet. 25.9 Request new redirect URL For security reasons, the redirect URL for a signer can only be used once. If the signing process is to be initiated again, a new redirect URL must be requested. C# If the JobResponse is kept in memory from job creation until a new URL is requested, it can be done like this: ClientConfiguration clientconfiguration = null; //As initialized earlier Job job = null; //As created earlier var directclient = new DirectClient(clientConfiguration); var directjobresponse = await directclient.create(job); var signerfromresponse = directjobresponse.signers.first(s => s.identifier.issameas(new PersonalIdentificationNumber("12345678910")) ); var signerwithupdatedredirecturl = await directclient.requestnewredirecturl(signerfromresponse); var newredirecturl = signerwithupdatedredirecturl.redirecturl; Otherwise, do like this: 25.8. Delete documents 65

ClientConfiguration clientconfiguration = null; //As initialized earlier Job job = null; //As created earlier var directclient = new DirectClient(clientConfiguration); var directjobresponse = await directclient.create(job); // Step 1: foreach (var signer in directjobresponse.signers) { //Persist signer URL in sender system var signerresponsesignerurl = signer.signerurl; } //... some time later... // Step 2: Request new redirect URL for signer Uri persistedsignerurl = null; //Persisted URL from step 1. var signerwithupdatedredirecturl = await directclient.requestnewredirecturl( NewRedirectUrlRequest.FromSignerUrl(persistedSignerUrl) ); var newredirecturl = signerwithupdatedredirecturl.redirecturl; Java If the DirectJobResponse is kept in memory from job creation until a new URL is requested, it can be done like this: ClientConfiguration clientconfiguration = null; // As initialized earlier DirectClient client = new DirectClient(clientConfiguration); DirectJobResponse directjobresponse = null; // As created earlier //Request new redirect URL from response DirectSignerResponse signerfromresponse = directjobresponse.getsigners().stream().filter(s -> s.hasidentifier("12345678910")).findany().orelsethrow(nosuchelementexception::new); DirectSignerResponse signerwithupdatedredirecturl = client.requestnewredirecturl(signerfromresponse); URI newredirecturl = signerwithupdatedredirecturl.getredirecturl(); Otherwise, do like this: ClientConfiguration clientconfiguration = null; // As initialized earlier DirectClient client = new DirectClient(clientConfiguration); DirectJobResponse directjobresponse = null; // As created earlier // Step 1: for (DirectSignerResponse signer : directjobresponse.getsigners()) { //Persist signer URL in sender system URI signerresponsesignerurl = signer.getsignerurl(); } //... some time later... // Step 2: Request new redirect URL for signer URI persistedsignerurl = null; //Persisted URL from step 1 (continues on next page) 66 Chapter 25. Direct flow

DirectSignerResponse signerwithupdatedredirecturl = client.requestnewredirecturl( WithSignerUrl.of(persistedSignerUrl) ); URI newredirecturl = signerwithupdatedredirecturl.getredirecturl(); (continued from previous page) HTTP A new redirect URL can be requested using the href attribute on a signer: <direct-signature-job-response xmlns="http://signering.posten.no/schema/v1"> <signature-job-id>1</signature-job-id> <redirect-url> https://signering.posten.no#/redirect/421e7ac38da1f81150 </redirect-url> <status-url>https://api.signering.posten.no/api/123456789/direct/signature-jobs/1/ status</status-url> <signer href="https://api.signering.posten.no/api/123456789/direct/signature-jobs/ 1/signers/1"> <personal-identification-number>12345678910</personal-identification-number> <redirect-url> https://signering.posten.no#/redirect/421e7ac38da1f81150 </redirect-url> </signer> </direct-signature-job-response> Use the href and do a post with the following body: <direct-signer-update-request xmlns="http://signering.posten.no/schema/v1"> <redirect-url /> </direct-signer-update-request> The response will contain the new redirect URL: <direct-signer-response xmlns="http://signering.posten.no/schema/v1" href="https://api.signering.posten.no/api/123456789/direct/signature-jobs/ 1/signers/1"> <personal-identification-number>12345678910</personal-identification-number> <redirect-url> https://signering.posten.no#/redirect/cwyjozox5joc1bacftdhuipj </redirect-url> </direct-signer-response> 25.9. Request new redirect URL 67

68 Chapter 25. Direct flow

CHAPTER 26 Portal flow 26.1 Having problems integrating? Tip: Remember that if you are having problems creating a job in a portal signature flow, you can always get in touch with a human on Github: C# Get help for your C# integration here. Java Get help for your Java integration here. 26.2 Create job C# ClientConfiguration clientconfiguration = null; //As initialized earlier var portalclient = new PortalClient(clientConfiguration); var documenttosign = new Document( "Subject of Message", "This is the content", FileType.Pdf, @"C:\Path\ToDocument\File.pdf" ); var signers = new List<Signer> { new Signer(new PersonalIdentificationNumber("00000000000"), new NotificationsUsingLookup()), (continues on next page) 69

}; (continued from previous page) new Signer(new PersonalIdentificationNumber("11111111111"), new Notifications( new Email("email1@example.com"), new Sms("999999999"))), new Signer(new ContactInformation {Email = new Email("email2@example.com")}), new Signer(new ContactInformation {Sms = new Sms("88888888")}), new Signer(new ContactInformation { Email = new Email("email3@example.com"), Sms = new Sms("77777777") }) var portaljob = new Job(documentToSign, signers, "myreferencetojob"); var portaljobresponse = await portalclient.create(portaljob); Java ClientConfiguration clientconfiguration = null; // As initialized earlier PortalClient client = new PortalClient(clientConfiguration); byte[] documentbytes = null; // Loaded document bytes PortalDocument document = PortalDocument.builder("Subject", "document.pdf", documentbytes).build(); PortalJob portaljob = PortalJob.builder( document, PortalSigner.identifiedByPersonalIdentificationNumber("12345678910", NotificationsUsingLookup.EMAIL_ONLY).build(), PortalSigner.identifiedByPersonalIdentificationNumber("12345678911", Notifications.builder().withEmailTo("email@example.com").build()). build(), PortalSigner.identifiedByEmail("email@example.com").build() ).build(); PortalJobResponse portaljobresponse = client.create(portaljob); Note: You may identify the signature job s signers by personal identification number IdentifiedByPersonalIdentificationNumber or contact information. When identifying by contact information, you may choose between instantiating a PortalSigner using IdentifiedByEmail, :code:`identifiedbymobilenumber or IdentifiedByEmailAndMobileNumber. You can specify a signature type and required authentication level. If signature type or required authentication level is omitted, default values as specified by the functional documentation will apply: C# Document documenttosign = null; //As initialized earlier var signers = new List<Signer> { new Signer(new PersonalIdentificationNumber("00000000000"), new NotificationsUsingLookup()) { SignatureType = SignatureType.AdvancedSignature } (continues on next page) 70 Chapter 26. Portal flow

}; (continued from previous page) var job = new Job(documentToSign, signers, "myreferencetojob") { AuthenticationLevel = AuthenticationLevel.Four }; Note: Note that only public organizations can do NotificationsUsingLookup. 26.3 Get status changes All changes to signature jobs will be added to a queue. You can poll for these changes. All changes must be confirmed after saving or handling them in your system. The following example shows how this can be handled and examples of data to extract from a change response. Note: If you retrieve a status change, it will be temporarily removed from the queue. If not confirmed it will reappear after some time. C# PortalClient portalclient = null; //As initialized earlier // Repeat the polling until signer signs the document, but ensure to do this at a // reasonable interval. If you are processing the result a few times a day in your // system, only poll a few times a day. var change = await portalclient.getstatuschange(); switch (change.status) { case JobStatus.NoChanges: //Queue is empty. Additional polling will result in blocking for a defined period. break; case JobStatus.Failed: case JobStatus.InProgress: case JobStatus.CompletedSuccessfully: { var signaturejobstatus = change.status; var signatures = change.signatures; var signatureone = signatures.elementat(0); var signatureonestatus = signatureone.signaturestatus; break; } } var pollingwillresultinblock = change.nextpermittedpolltime > DateTime.Now; if (pollingwillresultinblock) { //Wait until next permitted poll time has passed before polling again. } 26.3. Get status changes 71

Java PortalClient client = null; // As initialized earlier PortalJobStatusChanged statuschange = client.getstatuschange(); if (statuschange.is(portaljobstatus.no_changes)) { // Queue is empty. Must wait before polling again Instant nextpermittedpolltime = statuschange.getnextpermittedpolltime(); } else { // Recieved status update, act according to status PortalJobStatus signaturejobstatus = statuschange.getstatus(); Instant nextpermittedpolltime = statuschange.getnextpermittedpolltime(); } 26.4 Get signed documents When getting XAdES and PAdES for a PortalJob, remember that the XAdES is per signer, while there is only one PAdES. C# PortalClient portalclient = null; //As initialized earlier var jobstatuschanged = await portalclient.getstatuschange(); //Get XAdES: var xades = await portalclient.getxades(jobstatuschanged.signatures.elementat(0). XadesReference); //Get PAdES: var pades = await portalclient.getpades(jobstatuschanged.padesreference); Java PortalClient client = null; // As initialized earlier PortalJobStatusChanged statuschange = null; // As returned when polling for status changes // Retrieve PAdES: if (statuschange.ispadesavailable()) { InputStream padesstream = client.getpades(statuschange.getpadesurl()); } // Retrieve XAdES for all signers: for (Signature signature : statuschange.getsignatures()) { if (signature.is(signaturestatus.signed)) { InputStream xadesstream = client.getxades(signature.getxadesurl()); } } //... or for one specific signer: Signature signature = statuschange.getsignaturefrom( SignerIdentifier.identifiedByPersonalIdentificationNumber("12345678910")); if (signature.is(signaturestatus.signed)) { InputStream xadesstream = client.getxades(signature.getxadesurl()); } 72 Chapter 26. Portal flow

26.5 Specifying queues Specifies the queue that jobs and status changes for a signature job will occur in for signature jobs where StatusRetrievalMethod == POLLING. This is a feature aimed at organizations where it makes sense to retrieve status changes from several queues. This may be if the organization has more than one division, and each division has an application that create signature jobs through the API and want to retrieve status changes independent of the other division s actions. To specify a queue, set Sender pollingqueue through when constructing a sender. Please note that the same sender must be specified when polling to retrieve status changes. The Sender can be set globally in ClientConfiguration or on every job. C# PortalClient portalclient = null; //As initialized earlier var organizationnumber = "123456789"; var sender = new Sender(organizationNumber, new PollingQueue("CustomPollingQueue")); var documenttosign = new Document( "Subject of Message", "This is the content", FileType.Pdf, @"C:\Path\ToDocument\File.pdf" ); var signers = new List<Signer> { new Signer(new PersonalIdentificationNumber("00000000000"), new NotificationsUsingLookup()) }; var portaljob = new Job(documentToSign, signers, "myreferencetojob", sender); var portaljobresponse = await portalclient.create(portaljob); var changedjob = await portalclient.getstatuschange(sender); Java ClientConfiguration clientconfiguration = null; // As initialized earlier PortalClient client = new PortalClient(clientConfiguration); Sender sender = new Sender("000000000", PollingQueue.of("CustomPollingQueue")); byte[] documentbytes = null; // Loaded document bytes PortalDocument document = PortalDocument.builder("Subject", "document.pdf", documentbytes).build(); PortalJob portaljob = PortalJob.builder( document, PortalSigner.identifiedByPersonalIdentificationNumber("12345678910", NotificationsUsingLookup.EMAIL_ONLY).build(), PortalSigner.identifiedByPersonalIdentificationNumber("12345678911", Notifications.builder().withEmailTo("email@example.com").build()). build(), PortalSigner.identifiedByEmail("email@example.com").build() (continues on next page) 26.5. Specifying queues 73

).withsender(sender).build(); (continued from previous page) PortalJobResponse portaljobresponse = client.create(portaljob); PortalJobStatusChanged statuschange = client.getstatuschange(sender); 26.6 Delete documents After receiving a status change, the documents can be deleted as follows: Java PortalClient client = null; // As initialized earlier PortalJobStatusChanged statuschange = null; // As returned when polling for status changes client.deletedocuments(statuschange.getdeletedocumentsurl()); 74 Chapter 26. Portal flow

CHAPTER 27 Error handling There are differet forms of exceptions that can occur. Some are more specific than others. All exceptions related to client behavior inherits from SignatureException. C# try { //Some signature action } catch (BrokerNotAuthorizedException notauthorizedexception) { //Not authorized to perform action. The correct access rights for organization are not set. } catch (UnexpectedResponseException unexpectedresponseexception) { //UnexpectedResponseException will normally contain an `Error` object giving a more detailed error description. If this error does not exist, // you can still get the status code and message. var statuscode = unexpectedresponseexception.statuscode; var responsemessage = unexpectedresponseexception.message; if (unexpectedresponseexception.error!= null) { var errormessage = unexpectedresponseexception.error.message; var errortype = unexpectedresponseexception.error.type; } } catch (SignatureException exception) { } Java 75

try { client.confirm(statuschange); } catch (BrokerNotAuthorizedException brokernotauthorized) { // Broker is not authorized to perform action. Contact Difi in order to set up access rights. } catch (UnexpectedResponseException unexpectedresponse) { // The server returned an unexpected response. Response.StatusType httpstatuscode = unexpectedresponse.getactualstatus(); // errorcode and errormesage will normally contain information returned by the server. May be null. String errorcode = unexpectedresponse.geterrorcode(); String errormessage = unexpectedresponse.geterrormessage(); } catch (SignatureException e) { // An unexpected exception was thrown, inspect e.getmessage(). } 76 Chapter 27. Error handling

CHAPTER 28 Debugging 28.1.NET Core 28.1.1 Enabling logging The client library has the ability to log useful information that can be used for debug purposes. To enable logging, supply the Direct or Portal client with an implementation of Microsoft.Extensions.Logging. ILoggerFactory. This is Microsoft s own logging API, and allows the user to chose their own logging framework. Enabling logging on level DEBUG will output positive results of requests and worse, WARN only failed requests or worse, while ERROR will only occur on failed requests to create a signature job. These loggers will be under the Digipost.Signature.Api.Client namespace. Implementing using NLog There are numerous ways to implement a logger, but the following examples will be based on NLog documentation. 1. Install the Nuget-packages NLog, NLog.Extensions.Logging and Microsoft.Extensions. DependencyInjection. 2. Create a nlog.config file. The following is an example that logs to file and to console: <?xml version="1.0" encoding="utf-8"?> <!-- XSD manual extracted from package NLog.Schema: https://www.nuget.org/packages/ NLog.Schema--> <nlog xmlns="http://www.nlog-project.org/schemas/nlog.xsd" xsi:schemalocation="nlog NLog.xsd" xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" autoreload="true" internallogfile="c:\temp\console-example-internal.log" internalloglevel="info"> <!-- the targets to write to --> (continues on next page) 77

(continued from previous page) <targets> <!-- write logs to file --> <target xsi:type="file" name="filetarget" filename="/logs/signature-api-client-dotnet/signature-api-client- dotnet.log" layout="${date} ${level:uppercase=true} ${message} ${exception} $ {logger} ${all-event-properties}" archiveevery="day" archivenumbering="date" archivedateformat="yyyy-mm-dd"/> <!-- write logs to console --> <target xsi:type="console" name="consoletarget" layout="${date} ${level:uppercase=true} ${message} ${exception} $ {logger} ${all-event-properties}" /> </targets> <!-- rules to map from logger name to target --> <rules> <logger name="*" minlevel="trace" writeto="filetarget,consoletarget"/> </rules> </nlog> 3. In your application, do the following to create a logger and supply it to the client: private static IServiceProvider CreateServiceProviderAndSetUpLogging() { var services = new ServiceCollection(); services.addsingleton<iloggerfactory, LoggerFactory>(); services.addsingleton(typeof(ilogger<>), typeof(logger<>)); services.addlogging((builder) => builder.setminimumlevel(loglevel.trace)); var serviceprovider = services.buildserviceprovider(); SetUpLoggingForTesting(serviceProvider); } return serviceprovider; private static void SetUpLoggingForTesting(IServiceProvider serviceprovider) { var loggerfactory = serviceprovider.getrequiredservice<iloggerfactory>(); loggerfactory.addnlog(new NLogProviderOptions {CaptureMessageTemplates = true, CaptureMessageProperties = true}); NLog.LogManager.LoadConfiguration("./nlog.config"); } static void Main(string[] args) { ClientConfiguration clientconfiguration = null; var serviceprovider = CreateServiceProviderAndSetUpLogging(); var client = new PortalClient(clientConfiguration, serviceprovider.getservice <ILoggerFactory>()); } 78 Chapter 28. Debugging

28.1.2 Request and response logging For initial integration and debugging purposes, it can be useful to log the actual request and response going over the wire. This can be enabled by doing the following: Set the property ClientConfiguration.LogRequestAndResponse = true. Warning: Enabling request logging should never be used in a production system. It will severely impact the performance of the client. 28.1.3 Logging of document bundle Logging of document bundle can be enabled via the ClientConfiguration: var clientconfiguration = new ClientConfiguration(Environment.DifiTest, "3k 7f 30 dd 05 d3 b7 fc..."); clientconfiguration.enabledocumentbundlediskdump("/directory/path/for/bundle/disk/dump "); Note: Remember to only set the directory to save the disk dump. A new zip file will be placed there for each created signature job. If you have special needs for the bundle other than just saving it to disk, add your own bundle processor to ClientConfiguration.DocumentBundleProcessors. 28.2 Java 28.2.1 Request and response logging Warning: Enabling request logging should never be used in a production system. It will impact the performance of the client. You may configure the client library to log HTTP requests and responses by calling. enablerequestandresponselogging() when creating the client s configuration. You may configure the logger no.digipost.signature.client.http.requestresponse in order to customize logging. It must be set to at least INFO to write anything to the log. 28.2.2 Writing document bundle to disk You may configure the client library to write a ZIP file with the document bundle by calling. enabledocumentbundlediskdump(path) when creating the client s configuration. The Path parameter is the directory to where the files will be written. This directory must exists as the client library won t try creating it. If you have needs for the document bundle other than just saving it to disk, add your own document bundle processor by calling.adddocumentbundleprocessor(...) with your own DocumentBundleProcessor when creating the client s configuration. 28.2. Java 79

80 Chapter 28. Debugging

CHAPTER 29 Dokumentpakken Dokumentpakken i Posten signering er basert på ASiC-E standarden (Associated Signature Containers, Extended form). Profilen er lagd for å ligne på den som er brukt for Digital postkasse til innbyggere. Les mer om profilen som er benyttet for ASiC i slutten av dette dokumentet. 29.1 Innhold Pakken er i ZIP-format, og inneholder: dokumentet som skal signeres (en PDF eller ren tekstfil) filen manifest.xml som beskriver metadata for dokumentet (emner, hvem som skal signere osv.) filen signatures.xml som er signaturen over hele dokumentpakken. 29.1.1 Dokument For informasjon om dokumentbegrensninger, se Dokumentformat. Denne filen refereres til med det påkrevde hrefattributtet i document-elementet i manifest.xml. Se eksempler for signeringsoppdrag i direkteflyt og signeringsoppdrag i portalflyt. 29.1.2 Manifest Filen manifest.xml følger skjemaet direct-and-portal.xsd, som igjen importerer direct.xsd og portal.xsd. Se Step 1: Create signature job og API-integrasjon for signering i portalflyt for eksempler på forskjellige måter elementene kan bygges opp. 81

29.1.3 Signaturer Filen signatures.xml følger skjemaet http://uri.etsi.org/2918/v1.2.1#. Se Thirdparty (katalog) for kopier av de relevante standardskjemaene. Eksempel på komplett signatures.xml <?xml version="1.0" encoding="utf-8" standalone="no"?> <XAdESSignatures xmlns="http://uri.etsi.org/2918/v1.2.1#"> <Signature xmlns="http://www.w3.org/2000/09/xmldsig#" Id="Signature"> <SignedInfo> <CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n- 20010315"/> <SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa- sha256"/> <Reference Id="ID_0" URI="document.pdf"> <DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/> <DigestValue>LPJNul+wow4m6DsqxbninhsWHlwfp0JecwQzYpOLmCQ=</ DigestValue> </Reference> <Reference Id="ID_1" URI="manifest.xml"> <DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/> <DigestValue>xTqm6xkL7NOjnf5oYa+m0+XKzq1cwWMkcoESLa+/Lko=</ DigestValue> </Reference> <Reference Type="http://uri.etsi.org/01903#SignedProperties" URI=" #SignedProperties"> <Transforms> <Transform Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n- 20010315"/> </Transforms> <DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/> <DigestValue>cV6hPhJ6f8hnl0J9czhubj08rWhJmzCQsomxODfYyYM=</ DigestValue> </Reference> </SignedInfo> <SignatureValue> VTc0CBKyuDD0DRsJx7JJf6c2iH+TndFcx1aj0nP99snV6magufrPR8JSYadWIn4QICpHFcpAp5s+ XgIY9jfkAVLtAbiko9VcRpSopP1zj6tM3lrSaoo/ lbkp0rwnzcqingw8f3pkgbi1bukvwhbri4xf +bc2rzizoawgobyhsfz25hwrl+ggc3pnseza+wn3jbgaq00xtkudrg1vmjdjfsgtmvfyvq0xqluy 5Vxdfovoia3x6zm5zbHWRQdVoUTS3vv5Mv6GAs7JAnDwSNxRVSizN5QB6xB60xRn+BFwdVedQTMa curewixy2r8yocs9mazxfg+4sahgxjjknkglhg== </SignatureValue> <KeyInfo> <X509Data> <X509Certificate>MIIDYzCCAkugAwIBAgIEIyZ/ HzANBgkqhkiG9w0BAQsFADBiMQswCQYDVQQGEwJOTzELMAkGA1UE CBMCTk8xDTALBgNVBAcTBE9zbG8xETAPBgNVBAoTCEF2c2VuZGVyMREwDwYDVQQLEwhBdnNlbmRl cjerma8ga1ueaxmiqxzzzw5kzxiwhhcnmtqwntiwmtixmda3whcnmtuwnte1mtixmda3wjbimqsw CQYDVQQGEwJOTzELMAkGA1UECBMCTk8xDTALBgNVBAcTBE9zbG8xETAPBgNVBAoTCEF2c2VuZGVy (continues on next page) 82 Chapter 29. Dokumentpakken

(continued from previous page) MREwDwYDVQQLEwhBdnNlbmRlcjERMA8GA1UEAxMIQXZzZW5kZXIwggEiMA0GCSqGSIb3DQEBAQUA A4IBDwAwggEKAoIBAQCOq505/ fn9fdczjvmlswjnej0kvlefo233mefhouohu44q7clgljfeidmr ZCzWR58Eo8Fn90bEIosI8rCvw8XsNaDaeVgZ3PDtXTuA8luL/ IphWXfuHxdmFm3LPD0XIQS+V8pg J215NIScrZGkgBKjb7uVo+usGYUpqkbjl5kctTziRZo0k2i73iJd1+DjPGZ2OzAR1lMb8EEWheiX qe+prwphqokmirlnrzxdd1mtjr2rlyyp/ guw93ybigjv4mhv3zpjl8idu2yeckm5p6wg2wfzncyx ZU0E5Us4SvuDPrg48ELe140AtXQb8xyuGrLhCm5JyHhAFJM0IoiGQwqPAgMBAAGjITAfMB0GA1Ud DgQWBBSpQuhFDLFSUauhNrCbx+g8QXv9oTANBgkqhkiG9w0BAQsFAAOCAQEAHAENC+ZsxNSXOb6D e90uhqkejffzf3cfdtrhx23s2wjdfji4cey8whsod90ynoydzv/ swcu1emi1nz7redtt/wkfhidi CBzZ+GkU04niu+jpM9OCk1JS1LU+e+ljz6ZL7OZVegTE6tLI8JwfInf7dBjSBnf69Gs4xRK/TmO5 i5kipdivktgxjcalf8lwfm3bxm5t0h8azbrhc0jvvttxhjbivgg7jhfuic1z1vm6hsploysb9gfp 89AvNttWcdSb0rQAVz0rjl+GKzM07Aw4tYBl8j42POtjMCjV5e0TCeNfLfnZ3r9DCSUNlAwhisoX l5gxsb+yu/rpolg+xh5xra== </X509Certificate> </X509Data> </KeyInfo> <Object> <QualifyingProperties xmlns="http://uri.etsi.org/01903/v1.3.2#" xmlns:ns2="http://www.w3.org/2000/09/xmldsig#" Target="#Signature"> <SignedProperties Id="SignedProperties"> <SignedSignatureProperties> <SigningTime>2015-11-25T15:45:42.115+01:00</SigningTime> <SigningCertificate> <Cert> <CertDigest> <ns2:digestmethod Algorithm="http://www.w3.org/ 2000/09/xmldsig#sha1"/> <ns2:digestvalue>6gko40cr8upgenuaxit6bbvcrfo=</ ns2:digestvalue> </CertDigest> <IssuerSerial> <ns2:x509issuername>cn=avsender, OU=Avsender, O=Avsender, L=Oslo, ST=NO, C=NO</ns2:X509IssuerName> <ns2:x509serialnumber>589725471</ ns2:x509serialnumber> </IssuerSerial> </Cert> </SigningCertificate> </SignedSignatureProperties> <SignedDataObjectProperties> <DataObjectFormat ObjectReference="#ID_0"> <MimeType>application/pdf</MimeType> </DataObjectFormat> <DataObjectFormat ObjectReference="#ID_1"> <MimeType>application/xml</MimeType> </DataObjectFormat> (continues on next page) 29.1. Innhold 83

</SignedDataObjectProperties> </SignedProperties> </QualifyingProperties> </Object> </Signature> </XAdESSignatures> (continued from previous page) 29.2 Standarder brukt i dokumentpakken Integriteten til dokumenter og metadata i signeringstjenesten skal kunne valideres mange år etter mottak. Det er ivaretatt ved at informasjonen pakkes i en dokumentpakke som beskyttes med digitale signaturer som beskrevet nedenfor. I praksis er dette en zip-fil med en gitt struktur som inneholder en digital signatur over innholdet. 29.2.1 Standarder Standard Dokument Versjon ETSI, ETSI TS Electronic Signatures and Infrastructures (ESI); Associated Signature 1 ETSI, 102 918 2013-06. ETSI, ETSI TS Electronic Signatures and Infrastructures (ESI); ASiC Baseline Profile 2 ETSI, 103 174 2013-06. ETSI, ETSI TS Electronic Signatures and Infrastructures (ESI); XML Advanced Electronic ETSI, 101 903 Signatures (XAdES) 6 2010-12. ETSI, ETSI TS Electronic Signatures and Infrastructures (ESI); XAdES Baseline Profile 7 ETSI, 103 171 2012-03. 29.2.2 ASiC-profil for dokumentpakken Dokumentet pakkes i en dokumentpakke sammen med noe metadata i henhold til ASiC (ETSI TS 102 918) 1, og videre begrenset i henhold til profilen definert i Baseline Profile (ETSI TS 103 174) 2. Ytterlige begrensninger følger nedenfor: 1 http://www.etsi.org/deliver/etsi_ts/102900_102999/102918/01.03.01_60/ts_102918v010301p.pdf 2 http://www.etsi.org/deliver/etsi_ts/103100_103199/103174/02.02.01_60/ts_103174v020201p.pdf 6 http://www.etsi.org/deliver/etsi_ts%5c101900_101999%5c101903%5c01.04.02_60%5cts_101903v010402p.pdf 7 http://www.etsi.org/deliver/etsi_ts/103100_103199/103171/02.01.01_60/ts_103171v020101p.pdf 84 Chapter 29. Dokumentpakken

Krav Felt Kommentar krav ASiC conformance Skal være ASiC-E XAdES 6.1 3 krav ASiC-E Media type identification Skal være ASiC file extension is.asice 8.1 4 krav 8.2 4 ASiC-E Signed data object Alle filer utenfor META-INF katalogen skal være signert. krav ASiC-E XAdES signature Det skal kun være en signatur i META-INF katalogen, med navn 8.3.1 5 signatures.xml. Denne signaturen skal dekke alle andre filer i beholderen, og avsenderens virksomhetssertifikat skal benyttes for signering. krav Requirements for the contents of Container refererer til 6.2.2 punkt 4b) Denne filen skal ikke være tilstede. 8.3.2 5 META-INF/manifest.xml if present [... ] i ASiC :etsi1 29.2.3 Signatur i dokumentpakken Dokumentpakken bør være signert av Behandlingsansvarlig, men kan signeres av Databehandler. Signaturen skal være i henhold til XAdES (ETSI TS 101 903) 6 med basisprofilen definert i XAdES Baseline Profile (ETSI TS 103 171) 7 (B-Level Conformance). Ytterlige begrensninger følger nedenfor: of Krav Felt Kommentar krav Algorithm requirementansene Signeringsalgoritmen skal være rsa-sha256. Fingeravtrykksalgoritmen i refer- 5.1 8 skal være sha256. Fingeravtrykksalgoritmen i CertDigest skal være sha1. krav Placement the signing Alle sertifikater fra virkomhetsertifikatet og opp til og inkludert en tiltrodd rot 6.2.1 9 certificate skal være inkludert. krav Canonicalization Bør være xml-c14n11. Kan være REC-xml-c14n-20010315 6.2.2 10 of ds:signedinfo element krav Profile of Alle dokumenter skal være med, og det er ikke lov med referanser utenfor dokumentpakken. 6.2.3 10 ds:reference element krav Transforms within Alle fil-referansene skal være uten transform, og referansen til SignedProperties 6.2.4 11 ds:reference element skal være REC-xml-c14n-20010315 krav Profile of Ingen ytterlige begrensninger. 6.3.1 11 xades:signingcertificate element krav Profile of Tidsangivelsen skal være korrekt innenfor +/- 5 sekunder. 6.3.2 12 xades:signingtime element krav 6.3.3 12 Profile of xades:dataobjectformat element Kun MimeType og ObjectReference skal være med. 3 http://www.etsi.org/deliver/etsi_ts/103100_103199/103174/02.02.01_60/ts_103174v020201p.pdf#page=9 4 http://www.etsi.org/deliver/etsi_ts/103100_103199/103174/02.02.01_60/ts_103174v020201p.pdf#page=11 5 http://www.etsi.org/deliver/etsi_ts/103100_103199/103174/02.02.01_60/ts_103174v020201p.pdf#page=12 29.2. Standarder brukt i dokumentpakken 85

8 http://www.etsi.org/deliver/etsi_ts/103100_103199/103171/02.01.01_60/ts_103171v020101p.pdf#page=8 9 http://www.etsi.org/deliver/etsi_ts/103100_103199/103171/02.01.01_60/ts_103171v020101p.pdf#page=10 10 http://www.etsi.org/deliver/etsi_ts/103100_103199/103171/02.01.01_60/ts_103171v020101p.pdf#page=11 11 http://www.etsi.org/deliver/etsi_ts/103100_103199/103171/02.01.01_60/ts_103171v020101p.pdf#page=12 12 http://www.etsi.org/deliver/etsi_ts/103100_103199/103171/02.01.01_60/ts_103171v020101p.pdf#page=13 86 Chapter 29. Dokumentpakken

CHAPTER 30 API-integrasjon for signering i portalflyt Dette integrasjonsmønsteret passer for tjenesteeiere som ønsker å opprette signeringsoppdrag i portalflyt. Signeringsseremonien gjennomføres av sluttbruker i Signeringsportalen, og tjenesteeier vil deretter kunne polle på status og hente ned det signerte dokumentet. Dette scenariet er utviklet med tanke på å støtte en flyt hvor det er behov for å innhente signaturer fra flere enn én undertegner. Meldingsformatet i APIet er XML, og reelevante typer finnes i filen portal.xsd. 87

Flytskjema signeringsoppdrag i portalflyt: skjemaet viser at avsender sender inn et oppdrag, starter polling, at undertegner(e) signerer oppdraget, og avsender får oppdatert status via polling, og laster ned signert dokument. Dersom du sender et oppdrag til kun én undertegner, kan du se bort i fra den første steg 4 -seksjonen. Heltrukne linjer viser brukerflyt, mens stiplede linjer viser API-kall. 88 Chapter 30. API-integrasjon for signering i portalflyt

30.1 Steg 1: Opprette signeringsoppdraget Flyten begynner ved at tjenesteeier gjør et API-kall for å opprette signeringsoppdraget. Dette kallet gjøres som en multipart-request, der den ene delen er dokumentpakken og den andre delen er metadata. Kallet gjøres som en HTTP POST mot ressursen <rot-url>/portal/signature-jobs. Dokumentpakken legges med multipart-kallet med mediatypen application/octet-stream. Se Dokumentpakken for mer informasjon om dokumentpakken. Metadataene som skal sendes med i dette kallet er definert av elementet portal-signature-job-request. Disse legges i multipart-kallet med mediatypen application/ xml. Følgende er et eksempel på metadata for et signeringsoppdrag i portalflyt: <?xml version="1.0" encoding="utf-8" standalone="yes"?> <portal-signature-job-request xmlns="http://signering.posten.no/schema/v1"> <reference>123-abc</reference> <polling-queue>custom-queue</polling-queue> </portal-signature-job-request> Følgende er et eksempel på manifest.xml fra dokumentpakken for et signeringsoppdrag som skal signeres av fire undertegnere: <?xml version="1.0" encoding="utf-8" standalone="yes"?> <portal-signature-job-manifest xmlns="http://signering.posten.no/schema/v1"> <signers> <signer order="1"> <personal-identification-number>12345678910</personal-identification- number> <signature-type>advanced_electronic_signature</signature-type> <notifications> <!-- Override contact information to be used for notifications --> <email address="signer1@example.com" /> <sms number="00000000" /> </notifications> </signer> <signer order="2"> <personal-identification-number>10987654321</personal-identification- number> <signature-type>authenticated_electronic_signature</signature-type> <notifications> <email address="signer2@example.com" /> </notifications> </signer> <signer order="2"> <personal-identification-number>01013300001</personal-identification- number> <signature-type>authenticated_electronic_signature</signature-type> <notifications-using-lookup> <!-- Try to send notifications in both e-mail and SMS using lookup --> <email/> <sms/> </notifications-using-lookup> </signer> <signer order="3"> <personal-identification-number>02038412546</personal-identification- number> (continues on next page) 30.1. Steg 1: Opprette signeringsoppdraget 89

(continued from previous page) <signature-type>authenticated_electronic_signature</signature-type> <notifications-using-lookup> <email/> </notifications-using-lookup> </signer> </signers> <sender> <organization-number>123456789</organization-number> </sender> <document href="document.pdf" mime="application/pdf"> <title>tittel</title> <nonsensitive-title>sensitiv tittel</nonsensitive-title> <description>melding til undertegner</description> </document> <required-authentication>4</required-authentication> <availability> <activation-time>2016-02-10t12:00:00+01:00</activation-time> <available-seconds>864000</available-seconds> </availability> <identifier-in-signed-documents>personal_identification_number_and_name</ identifier-in-signed-documents> </portal-signature-job-manifest> 30.1.1 Undertegnere Du bør se Kontaktinformasjon og Adressering av undertegner før du starter med dette kapitlet. Undertegnere kan adresseres og varsles på ulike måter: E-post <signer> <identified-by-contact-information/> <notifications> <email address="email@example.com"/> </notifications> <on-behalf-of>self</on-behalf-of> </signer> Mobil <signer> <identified-by-contact-information/> <notifications> <sms number="00000000" /> </notifications> <on-behalf-of>self</on-behalf-of> </signer> E-post og mobil <signer> <identified-by-contact-information/> <notifications> <email address="email@example.com"/> <sms number="00000000" /> (continues on next page) 90 Chapter 30. API-integrasjon for signering i portalflyt

</notifications> <on-behalf-of>self</on-behalf-of> </signer> (continued from previous page) Fødselsnummer Med varsling til gitt epostadresse: <signer> <personal-identification-number>12345678910</personal-identification-number> <notifications> <email address="email@example.com"/> </notifications> <on-behalf-of>self</on-behalf-of> </signer> Med varsling som offentlig virksomhet: Note: Som offentlig virksomhet skal oppslag gjøres vha. Kontakt- og Reservasjonsregisteret. <signer> <personal-identification-number>12345678910</personal-identification-number> <notifications> <notifications-using-lookup/> </notifications> <on-behalf-of>self</on-behalf-of> </signer> På vegne av En avsender kan velge om undertegner signerer på vegne av seg selv eller i kraft av en rolle. Dette gjøres ved å sette attributtet on-behalf-of til enten SELF eller OTHER. Dersom man signerer på vegne av noen andre, vil det i praksis bety at signert dokument ikke sendes videre til undertegners postkasse. For offentlige virksomheter brukes heller ikke Kontakt- og reservasjonsregisteret, og man må adressere undertegner på egenvalgt telefonnummer og e-postadresse. <signer> <personal-identification-number>12345678910</personal-identification-number> <notifications> <email address="email@example.com"/> <sms number="00000000" /> </notifications> <on-behalf-of>other</on-behalf-of> </signer> Note: Elementet notifications-using-lookup er kun tilgjengelig for offentlige virksomheter. Ettersom dette vil slå opp undertegners private kontaktinformasjon, kan man ikke samtidig angi at vedkommende signerer på vegne av noen andre. Altså, man kan ikke sette on-behalf-of til OTHER dersom man ønsker å benytte Kontaktog reservasjonsregisteret for å adressere undertegner. 30.1.2 Andre innstillinger 30.1. Steg 1: Opprette signeringsoppdraget 91

Rekkefølge order-attributtet på signer brukes til å angi rekkefølgen på undertegnerne. I eksempelet over vil signeringsoppdraget først kun bli tilgjengelig for undertegnerne med order="1". Når disse har signert, blir oppdraget tilgjengelig for de med order="2", og for undertegneren med order="3" når de med order="2" har signert. Tilgjengelighet Elementet availability brukes til å kontrollere tidsrommet et signeringsoppdrag er tilgjengelig for undertegner(e). <availability> <activation-time>2016-02-10t12:00:00+01:00</activation-time> <available-seconds>864000</available-seconds> </availability> Tidspunktet angitt i activation-time angir når jobben aktiveres, og de første undertegnerne får mulighet til å signere oppdraget. Varigheten angitt i available-seconds gjelder for alle undertegnere. Det vil si at alle undertegnere vil få like lang tid til å signere eller avvise oppdraget fra det blir tilgjengelig for dem. Dette tidsrommet gjelder altså for hvert sett med undertegnere med samme order. Eksempel, angi 345600 sekunder (4 dager) for undertegnere med rekkefølge: 1. Undertegnere med order=1 får 4 dager fra activation-time til å signere. 2. Undertegnere med order=2 vil få tilgjengeliggjort dokumentet umiddelbart når alle undertegnere med order=1 har signert. De vil da få 4 dager fra tidspunktet de fikk oppdraget tilgjengelig. Note: Dersom man utelater availability vil jobben aktiveres umiddelbart, og oppdraget vil være tilgjengelig i maks 30 dager for hvert sett med order-grupperte undertegnere. Important: Et signeringsoppdrag utløper og stopper dersom minst én undertegner ikke signerer innenfor sitt tidsrom når oppdraget er tilgjengelig. Important: tjenesten. Jobber som angir større available-seconds enn 7 776 000 sekunder (90 dager) blir avvist av Identifikator i signert dokument Elementet identifier-in-signed-documents brukes for å angi hvordan undertegner skal identifiseres i de signerte dokumentene. Tillatte verdier er PERSONAL_IDENTIFICATION_NUMBER_AND_NAME, DATE_OF_BIRTH_AND_NAME og NAME, men ikke alle er gyldige for alle typer signeringsoppdrag og avsendere. For mer informasjon, se Hvordan identifiseres undertegnere i et ferdig signert dokument?. 30.1.3 Respons Som respons på dette kallet vil man få elementet portal-signature-job-response. Denne responsen inneholder en ID generert av signeringstjenesten. Du må lagre denne IDen i dine systemer slik at du senere kan koble resultatene du får fra polling-mekanismen til riktig oppdrag. 92 Chapter 30. API-integrasjon for signering i portalflyt

<portal-signature-job-response xmlns="http://signering.posten.no/schema/v1"> <signature-job-id>1</signature-job-id> <cancellation-url>https://api.signering.posten.no/api/{sender-identifier}/portal/ signature-jobs/1/cancel</cancellation-url> </portal-signature-job-response> 30.2 Steg 2: Polling på status For å finne ut hva statusen er for de signeringsoppdragene du har opprettet, må du jevnlig sende forespørsler til signeringstjenesten (polling). Som avsender må du sjekke hvilket oppdrag statusoppdateringen gjelder for å oppdatere i ditt system og så bekrefte den. Responsen på dette kallet vil være én av to ting: statusoppdatering: en 200 OK-respons som inneholder informasjon om ny status for ett oppdrag. Denne er definert av elementet portal-signature-job-status-change-response. ingen oppdatering tilgjengelig: Dersom det ikke er noen oppdateringer for dine signeringsoppdrag, vil du få en 204 No Content-respons. 30.2.1 Hyppighet Responsene vil alltid inneholde HTTP-headeren X-Next-permitted-poll-time som forteller deg når du kan gjøre neste forespørsel, og det er viktig at dette tidspunktet overholdes. Dersom man sender en forespørsel før dette tidspunktet har passert, vil man få en 429 Too Many Requests-respons tilbake. Denne vil også inneholde headeren X-Next-permitted-poll-time med et nytt tidspunkt. Note: I produksjonsmiljøet vil neste tillatte polling-tidspunkt være om 10 minutter om køen er tom, mens for testmiljøer vil det være mellom 5 og 30 sekunder. I praksis vil tidspunktet for neste tillatte polling-forespørsel være umiddelbart så lenge man får en respons som inneholder en statusoppdatering. 30.2.2 Integrasjon For å polle, så gjør du en HTTP GET mot <rot-url>/portal/signature-jobs. Oppdrag som ikke er lagt på en spesifikk kø vil havne på en standard-kø. Hvis signeringsoppdraget er lagt på en spesifikk kø, så må også query-parameteret polling_queue settes til navnet på køen, f.eks. <rot-url>/portal/signature-jobs? polling_queue=custom-queue. Du skal ikke ha med noen request-body på dette kallet. Følgende er et eksempel på en respons der en del av signeringsoppdraget har blitt fullført: <portal-signature-job-status-change-response xmlns="http://signering.posten.no/schema/ v1"> <signature-job-id>1</signature-job-id> <status>in_progress</status> <confirmation-url>https://api.signering.posten.no/api/{sender-identifier}/portal/ signature-jobs/1/complete</confirmation-url> <signatures> <signature> <status since="2017-01-23t12:51:43+01:00">signed</status> (continues on next page) 30.2. Steg 2: Polling på status 93

(continued from previous page) <personal-identification-number>12345678910</personal-identification- number> <xades-url>https://api.signering.posten.no/api/{sender-identifier}/portal/ signature-jobs/1/xades/1</xades-url> </signature> <signature> <status since="2017-01-23t12:00:00+01:00">waiting</status> <personal-identification-number>98765432100</personal-identification- number> </signature> <pades-url>https://api.signering.posten.no/api/{sender-identifier}/portal/ signature-jobs/1/pades</pades-url> </signatures> </portal-signature-job-status-change-response> Statusoppdateringer du henter vil forsvinne fra køen. Dette gjør det mulig å spørre om statusoppdateringer i parallell, og du vil ikke få samme statusoppdatering to ganger. Det er derfor viktig at du bekrefter mottak av hver statusoppdatering så raskt som mulig, for dersom det likevel skulle skje en feil under overføring eller prosessering, så vil kvitteringen legges på køen igjen etter 10 minutter. Mer informasjon om hvordan du bekrefter en kvittering er beskrevet i Steg 4: Bekrefte ferdig prosessering. 30.3 Steg 3: Laste ned PAdES eller XAdES Responsen i forrige steg inneholder lenkene xades-url og pades-url. Disse kan du gjøre en HTTP GET på for å laste ned det signerte dokumentet i de to formatene. For mer informasjon om format på det signerte dokumentet, se Signerte dokumenter. XAdES-filen laster du ned per undertegner, mens PAdES-filen lastes ned på tvers av alle undertegnere. Denne vil inneholde signeringsinformasjon for alle undertegnere som frem til nå har signert oppdraget. I de aller fleste tilfeller er det ikke aktuelt å laste ned denne før alle undertegnerne har statusen SIGNED. 30.4 Steg 4: Bekrefte ferdig prosessering Til slutt gjør du et HTTP POST-kall mot confirmation-url for å bekrefte at du har mottatt/persistert statusoppdateringen. Dersom statusen indikerer at oppdraget er helt ferdig, så vil dette kallet også bekrefte at du er ferdig med å prosessere hele oppdraget. Hvis Langtidslagring benyttes vil dette markere oppdraget som ferdig og lagret, ellers vil oppdraget slettes fra signeringstjenesten. 94 Chapter 30. API-integrasjon for signering i portalflyt

CHAPTER 31 Sikkerhet Signeringstjenesten benytter to-veis TLS for å sikre konfidensialitet og meldingsintegritet på transportlaget. Dokumentpakken med dokumentet som skal signeres er integritetssikret med ASiC-E. 31.1 To-veis TLS For å benytte APIene trenger du et virksomhetssertifikat. For innkjøp og mer informasjon om virksomhetssertifikat, se innkjøp av virksomhetssertifikat. Her vil du også finne informasjon om hvilke av sertifikatene du har som skal brukes mot vår tjeneste. Se også godkjent virksomhetssertifikat i offentlig sektor og sertifikathåndtering i offentlig sektor for mer informasjon om rot- og mellomliggende sertifikater. De fleste HTTP-klienter har innebygget støtte for toveis TLS. Du kan se eksempler på implementasjonen i klientbibloteket skrevet i C# eller klientbibloteket skrevet i Java. Signeringstjenesten støtter kun TLS 1.2 for to-veis TLS. Du benytter ditt eget sertifikat i keystore (det du skal identifisere deg med), og legger til tillitsankrene (CAsertifikater) i truststore (det serveren skal identifisere seg med). Sertifikatet ditt vil bli brukt for å verifisere deg mot serveren, og serveren vil bruke sertifikatet til Posten Norge AS for å identifisere seg. Ved å ha tillitsankrene i truststore får du mesteparten av valideringen derfra (gitt at ditt språk/rammeverk håndterer dette). Det du manuelt må gjøre er å validere at sertifikatet tilhører Posten Norge AS, ved å sjekke organisasjonsnummeret som står i Common Name. Et godt tips er å benytte eller hente inspirasjon fra Difis sertifikatvalidator. 31.1.1 Vanlige problemer med oppsett av to-veis TLS Det benyttes feil truststore for klienten. I testmiljøet må truststore inneholde testsertifikatene, i produksjon må det være produksjonssertifikater. Sertifikatet som benyttes er ikke et virksomhetssertifikat. Virksomhetssertifikater utstedes typisk av Buypass eller Commfides. Klienten støtter ikke TLS v1.2. Java 6 støtter ikke TLS v1.2, i Java 7 må dette skrus på eksplisitt. 95

Sertifikatet er utstedt av Commfides SHA-1 rotsertifikat. Kun sertifikater med SHA-256 fra Commfides er støttet. Dette gjelder primært eldre sertifikater. 31.1.2 Personopplysninger Personopplysninger og sensitive personopplysninger skal kun legges i følgende felter i XML-en i requestene mot API-et: personal-identification-number undertegners fødselsnummer eller d-nummer title tittelen/emnet til dokumentet, som oppsummerer hva signaturoppdraget handler om description kan inneholde en personlig melding, tilleggsinformasjon til dokumentet eller beskrivelse av dokumentet Øvrige felter skal ikke inneholde sensitive personopplysninger eller personopplysninger. Eksempelvis vil referansen (reference) brukes utenfor en sikker kontekst (f.eks i epost-varslinger), og kan derfor ikke inneholde personopplysninger. Se for øvrig beskrivelse av API-et lenger nede. Se nærmere beskrivelse av begrepene personopplysninger og sensitive personopplysninger på Datatilsynet sine nettsider. 96 Chapter 31. Sikkerhet

CHAPTER 32 Syntax help This is a cheat-sheet for writing the documentation. It is only for internal use, but feel free to browse if you are curious about how we write our documentation. All the following examples are for using restructuredtext instead of Markdown. 32.1 Links `link text <http://google.com>`_ Will generate the following url: link text 32.2 Headers Innhold restructured text 1 ***************************** Innhold restructured text 2 ============================= Innhold restructured text 3 ----------------------------- Innhold restructured text 4 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 97

32.3 Admonitions See more about admonitions here 32.3.1 Example admonitions.. CAUTION:: Caution message.. DANGER:: Danger zone!.. NOTE:: Important note!.. TIP:: Just a tip! Caution: Caution message Danger: Danger zone! Note: Important note! Tip: Just a tip! 32.4 References To reference a chapter anywhere in the documentation, add a label over the heading:.. _my-reference-label: Section to cross-reference -------------------------- This is the text of the section. It refers to the section itself, see :ref:`my-reference-label`. Tip: Always use underscore, _, first in the reference, but never when you use the reference. 32.5 Tabs Tabs are used via an extension and how to use can be found here. 98 Chapter 32. Syntax help

The different tabs are tab, group-tab and code-tab... tabs::.. tab:: Apples Apples are green, or sometimes red... tab:: Pears Pears are green. Tip: The different tabs are tab, group-tab and code-tab. With group-tab, all examples changes tab at the same time. code-tab is self explanatory, but note that it behaves like group-tab. 32.5.1 Example tab Apples Apples are green, or sometimes red. Pears Pears are green. Oranges Oranges are orange. 32.6 Code snippets.. code-block:: language Some code here... 32.7 Numbered lists 3. First numbered item starts with three. 4. The next numbered item, four. #. Auto numbering. Will be 5. Will generate the following list: 3. First numbered item starts with three. 4. The next numbered item, four. 5. Auto numbering. Will be 5. 32.6. Code snippets 99

32.8 Footnotes A footnote can be created: I have something to say [#footnotewithuniquename]_. and used like so:.. rubric:: Footnotes.. [#footnotewithuniquename] Some extra important information! 32.8.1 Example footnote I have something to say 1. 32.9 Images Images can be added by putting an image in the images-folder and using the following code for an image:.. example-image image:: images/exampledocimage.png :alt: alternate text :align: right Tip: Please add the image reference to the bottom of the file. It makes the file so much easier to read. Then, just use example-image where you want the image to be inserted. You can also specify more image tags: :height: 100px :width: 200 px :scale: 50 % :alt: alternate text :align: right 1 Some extra important information! 100 Chapter 32. Syntax help

CHAPTER 33 Ordbok 33.1 Tjenesten Signeringstjenesten på norsk, Signature service på engelsk. 33.2 Nettside På engelsk kaller vi det website 33.3 Bedrift/Virksomhet Bedrift: En organisasjon som ikke er tilknyttet det offentlige. Bruk Privat virksomhet i tilfeller der det kan misforstås. Offentlig virksomhet: En organisasjon tilknyttet det offentlige. Disse begrepene er de vi ønsker å bruke, men om det blir forvirring så skal vi bruke privat virksomhet for bedrift. På engelsk kaller vi det organization. 33.4 Avsender Bedrift/Virksomhet som sender signeringsoppdrag i en Signeringsflyt. Vi skal ikke bruke ord som tjenesteeier. På engelsk kaller vi det sender. 101

33.5 Undertegner Person som undertegner et dokument i et singeringsoppdrag. Vi skal ikke bruke ord som sluttbruker. 33.6 Signeringsflyt Signeringsoppdrag i portalflyt adressering uten fødselsnummer adressering med fødselsnummer Signeringsoppdrag i direkteflyt En Undertegner starter en signering. Vi skal ikke bruke ord som signeringsseremoni. 33.7 Jobb Avhengig av kontekst kan det kalles signeringsjobb eller bare jobb. En jobb har en dokumentpakke På engelsk kaller vi det signature job eller job, og den har en document bundle. 33.8 Portal Avsenderportal: Dette er webgrensesnittet for avsendere. signering.posten.no/virksomhet/ Signeringsportal: Dette er webgrensesnittet for undertegnere. På engelsk kaller vi det sender portal og signing portal. 33.9 API Vi bruker API om det å bruke API-et vårt. Vi skal ikke bruke ord som bak-kanal-kall. 102 Chapter 33. Ordbok

CHAPTER 34 Indices and tables genindex modindex search 103