IPS-PKI signering med IPS-Bx
Language
Note: This part of the documentation is in Norwegian only. An English version can be provided if needed.
Innhold på denne siden:
- 1.1 Language
- 2 PKI Signering
- 2.1 Hva er en IPS signering?
- 2.2 Hvordan er prinsippene ift What-you-see-is-what-you-sign implementert i IPS ?
- 2.3 SignatureProvider plugin
- 2.3.1 Signaturformater
- 2.3.2 Dokumentformater
- 2.3.3 Nedlasting av dokumenter til sluttbruker
- 2.3.4 SignaturFormat BPESIG0101 - PKCS#7 v1.5 SDO
- 2.3.5 SignaturFormat BPESIG0201 - ETSI TS 101 733 CAdES-BES SDO
- 2.3.6 SignaturFormat BPESIG0301 - SEID-SDO-Basic
- 2.3.7 SignaturFormat BPESIG0401 - PDF signatur, usynlig signatur
- 2.3.8 SignaturFormat BPESIG0402 - PDF signatur, synlig signatur
- 2.4 Sammensetting av forespørselen
Relatert informasjon:
PKI Signering
Her finner du dokumentasjon på hva en IPS signering er og fungerer, hvordan du bygger opp en signerings forespørselen og tolker responsen. Du finner også informasjon om de forskjellige signeringsformatene som er støttet, hvordan dette brukes og hvordan man trygt kan overføre dokumentet til klientsiden.
Merk at eksempelkodene i denne siden er kun ment som illustrasjonseksempeler på kjernemekanismene, og bør "robustifieres"/justeres med feilhåndtering og/eller andre nødvendige tilpasninger før en ev. produksjonssetting.
Hva er en IPS signering?
En signering gjennom IPS gir en sluttbruker mulighet for å se på og signere et dokument med sin PKI. Dokumentet tilgjengeliggjøres på brukerstedets server, og lastes ned til klienten. På klienten kan sluttbrukeren se på dokumentet gjennom sin installerte "viewer" for det aktuelle dokumentformatet før det signeres. Når dokumentet er signert, vil IPS verifisere signaturen, og returnere signatur og sertifikat tilbake til brukerstedet. På brukerstedssiden vil brukerstedet kunne sette sammen den angitte SDO typen basert på disse elementene, og verifisere signaturen/SDO'en om ønskelig. Signaturformatene støttes gjennom en SignatureProvider plugin arkitektur. Etter hvert som det tilkommer støtte for flere signaturformater, kan disse lastes ned fra disse sidene. Man kan også implementere egne plugins hvis ønskelig, men kravet til input data til eventuelle egenutviklede plugins må samsvare med en av de eksisterende SignatureProvider plugin'ene.
Hvordan er prinsippene ift What-you-see-is-what-you-sign implementert i IPS ?
For å kunne sannsynliggjøre at det du ser er det du signerer (WYSIWYS-prinsippet), er det viktig å ha en så nære knyttning som mulig mellom "se-på prosessen" og signeringsprosessen. Helst bør dette skje i en egen ekstern "signerings-terminal" som er lukket og beskyttet fra PC'en ellers. Allikevel må man ha tilitt til denne signerings-terminalen, og det får man gjerne gjennom dokumentasjon, sertifiseringer og andre bekreftelser fra anerkjente leverandører.
For å kunne tilby en signeringsløsning på Internet uten en slik "signerings-terminal", er det viktig at de som bruker signeringsløsningen og de som tilbyr signering gjennom en slik løsning, kjenner til hvordan man i størst mulig grad sannsynliggjør at det du faktisk ser er det du faktisk signerer. Derfor er det viktig at denne informasjonen er tilgjengelig, og at man da selv kan ta stilling til om man syntes disse mekanismene sannsynliggjør dette i tilstrekkelig grad.
I IPS er dette sannsynliggjort ved at dokumentet lastes ned på klienten, og inn i samme prosess som skal styre den faktiske signeringen mot Smartkortet. Dataene fra samme prosess tilgjengeliggjøres for visning, sammen med mime-typen brukerstedet selv har angitt for innholdet (f.eks. "application/pdf"). På denne måten startes så det aktuelle programmet sluttbrukeren har installert for den gitte mime-typen (f.eks. Adobe Reader), og dokumentet vises i dette programmet. Når sluttbrukeren har sett på dokumentet/filen som skal signeres, taster brukeren PIN-kode, og korrekt preprosessert DTBS (Data-To-Be-Signed) i forhold til angitt signaturformat over de samme dataene signeres.
SignatureProvider plugin
Signaturformatsøttten i integrasjonsbibliotekene er implementert gjennom en såkalt SignatureProvider plugin arkitektur. En SignatureProvider plugin tilbyr encoding og verifisering av sine relevante formater og delstrukturer. F.eks. vil BPESIG0101 plugin, som støtter basic PKCS#7 SDO'er, tilby støtte for encoding av alle relevante delstrukturer som brukes i en basic PKCS#7 signering. Det samme gjelder for de andre signaturformatene.
SignatureProvider kode pattern for SDO generering vil være slik:
// get the correct provider instance
SignatureProvider sp = SignatureProvider.getInstance([format]);
sp.initializeForEncode([encoding mode]);
// add all required parameters
sp.setParam([dataparam name-1],[value-1]);
..
sp.setParam([dataparam name-n],[value-n]);
// encode the given structure
byte[] encodedData = sp.encode();
SignatureProvider kode pattern for SDO verifisering vil være slik:
// get the correct provider instance
SignatureProvider sp = SignatureProvider.getInstance([format]);
sp.initializeForVerify([verification mode]);
// add all required parameters
sp.setParam([dataparam name-1],[value-1]);
..
sp.setParam([dataparam name-n],[value-n]);
// verify the given structure
boolean verifiedOk = sp.verify();
Under følger en global liste over alle dataparameter typer.
Følgende dataparametere er felles for alle BPESIG SignatureProvider plugins
Parameter | Type | Beskrivelse |
|---|---|---|
DTBS | byte[] | Data-To-Be-Signed - dette er de faktiske binære dataene som signeres etter all nødvendig preprosessering, uten padding. |
CONTENT | byte[] | Eksakt binær representasjon av dokumentet/filen som skal signeres. |
CONTENT_SHA1_DIGEST | byte[] | Hash av CONTENT i henhold til spesifisert hash-algoritme |
CMS_SIGNED_ATTRIBUTES | byte[] | CMS SignedAttributes. Den binære representasjonen av en PKCS#7 v1.5 SignedAttributes som skal brukes ved signering/verifisering. |
CLAIMED_SIGNING_TIME | Date (Java)/ | Datoobjekt som representerer brukerstedets oppfatning av tidspunkt for signering. |
CERTIFICATE | byte[] | Binær representasjon av X509 Sertifikatet som skal brukes ved signering. |
SIGNATURE | byte[] | Binør representasjon av signaturen. For en 1024 bits RSA signering vil denne eksempelvis være 128 bytes lang. |
CMS_SIGNED_DATA_OBJECT | byte[] | CMS SignedDataObject. Den binære representasjon av en PKCS#7 v1.5 SignedDataObject som skal brukes ved signering/verifisering. |
SEID_INCLUDE_SIGNEDOBJECT | String ("1"/"0") | 1 hvis CONTENT skal være med i SEID_SDO'en, 0 hvis ikke |
SEID_INCLUDE_HASHEDDATA | String ("1"/"0") | 1 hvis HashedData elementet skal være med i SEID_SDO'en, 0 hvis ikke |
PDF_SIGNED | ||
SIGNATURE_CONTEXT | cnl.wips.remote.tools.crypto.SignatureContext | Tilstandsholder objekt gjennom de forskjellige fasene av encoding. Et tomt SignatureContext objekt opprettes gjennom å kalle SignatureProvider.createSignatureContext() på den aktuelle SignatureProvideren |
VISIBLE_SIGNATURE_PAGE | String | Side nummer som den synlige signaturen skal ligge på |
VISIBLE_SIGNATURE_X | String | Den horisontale posisjonen til den synlige signaturen |
VISIBLE_SIGNATURE_Y | String | Den vertikale posisjonen til den synlige signaturen |
VISIBLE_SIGNATURE_WIDTH | String | Bredden til den synlige signaturen |
VISIBLE_SIGNATURE_HEIGHT | String | Høyden til den synlige signaturen |
REASON | String | Tekstlig beskrivelse av grunn/årsak til at signaturen lages. |
SIGNED_LOCATION | String | Tekstlig beskrivelse av signeringssted. |
Under følger en global liste over alle encoding modes
Følgende encoding mode identifikatorere er felles for alle BPESIG SignatureProvider plugins
Parameter | Beskrivelse |
|---|---|
DTBS | Data-To-Be-Signed - genererer de faktiske binære dataene som signeres etter all nødvendig preprosessering, uten padding. |
CMS_SIGNED_ATTRIBUTES | CMS SignedAttributes. Genererer den binære represenatsjonen av en PKCS#7 v1.5 SignedAttributes som skal brukes ved signering. |
CMS_SIGNED_DATA_OBJECT | CMS SignedDataObject. Genererer den binære represenatsjonen av en PKCS#7 v1.5 SignedDataObject som skal brukes ved signering. |
SEID_SDO_BASIC | Genererer den binære representasjonen av en SEID_SDO_Basic XML struktur. |
PDF_SIGNED | Genererer den signerte PDF'en. |
Under følger en global liste over alle verification modes
Følgende verification mode identifikatorere er felles for alle BPESIG SignatureProvider plugins
Parameter | Beskrivelse |
|---|---|
CMS_SIGNED_DATA_OBJECT_INTEGRITY | Verifiserer signatur objektets integritet. Dvs at strukturen i seg selv blir verifisert; signatur mot innhold og innhold i signed attributes, integretet og levetid på sertifikat, men ingen revokeringssjekk. |
SEID_SDO_BASIC_CMS_INTEGRITY | Verifiserer det interne CMS signatur objektets integritet i SEID_SDO'en. Dvs at den interne CMS strukturen i seg selv blir verifisert; signatur mot innhold og innhold i signed attributes, integretet og levetid på sertifikat, men ingen revokeringssjekk. |
PDF_SIGNED | Verifiserer det interne PDF dokumentet opp mot signaturen, integretet og levetid på sertifikat, men ingen revokeringssjekk eller sjekk mot CA sertifikat. |
Signaturformater
Følgende signatur formater støttes av IPS:
Verdi | Fra versjon | Beskrivelse |
|---|---|---|
BPESIG0101 | 1.0.1 | CMS basert signatur basert på PKCS#7, v1.5. Gir mulighet for å inkludere claimed signing-time i signatur grunnlaget (signed-attributes) |
BPESIG0201 | 1.0.1 | CMS basert signatur basert på ETSI 101 733 v1.7.3. Dataene signeres og formateres iht CAdES-BES formatert signaturer. Gir mulighet for å inkludere claimed signing-time i signatur grunnlaget. |
BPESIG0301 | 1.0.1 | CMS og XML basert signatur. Dataene signeres og formateres iht SEID SDO Basic (Type 1) profilen. |
BPESIG0401 | 1.0.3 | Adobe PDF signatur, usynlig signatur. |
BPESIG0402 | 1.0.3 | Adobe PDF signatur, visuelt synlig signatur i dokumentet |
Du finner mer informasjon om de ulike signaturformatene lenger ned.
Dokumentformater
IPS har ikke noe teknisk forhold til formatet på dokumentet utover mime-typen som anngis for det for det aktuelle formatet av brukerstedet selv. Dette betyr at man i prinsippet står fritt til å signere alle type dokumenter/filer, fra PDF'er og Word dokumenter til .exe filer og .zip filer. "Viewer" prosessen blir da håndtert slik den aktuelle applikasjonen for den gitte mime-typen håndterer det. Av sikkerhetsmessige årsaker har Buypass begrenset IPS til å kun signere PDF (application/pdf) og rene tekstfiler (text/plain). Hvis det er behov for å kunne signere andre type formater, kontakt Buypass for videre diskusjon.
Nedlasting av dokumenter til sluttbruker
Som tidligere nevnt, lastes det aktuelle dokumentet over til kundens PC i forkant av selve signeringen. Det finnes det flere varianter å tilgjengeliggjøre dokumentet på. Dokumentet må på en eller annen måte tilgjengeliggjøres for signeringsappleten, slik at denne kan lastes ned for visning- og signering. Det finnes følgende alternativer for tilgjengeliggjøring:
Tilgjengeliggjøre dokumentet på åpen, ikke-gjettbar/uforutsigbar, URL
Tilgjengeliggjøre dokumentet på en sesjonsbasert URL. Sesjonscookien sendes da med i forespørselen til IPS
Tilgjengeliggjøre en kryptert (3DES/168bit) utgave dokumentet på en åpen eller sesjonsbasert URL. Dekrypteringsnøkkelen (og ev. sesjonscookien) sendes da med i forespørselen til IPS. WIRI tilbyr støttefunksjonalitet for kryptering, nøkkelgenering og base64 encoding av dokumenter som tilgjengeliggjøres på denne måten.
Sende dokumentet med i forespørselen til IPS. Dette anbefales kun for små dokumenter. Total maks størrelse på en forespørsel til IPS er 256kb, men det anbefales uansett ikke å sende større dokumenter enn 3-5kb via IPS, da dokumentet må lastes opp (x1) og ned (x2) 3 ganger før det er "fremme" hos sluttbrukeren.
Hvis dokumentet tilgjengeliggjøres på Internet, bør dokumentet tilgjengeliggjøres på en SSL adresse. Alternativt krypteres som i alternativ 3), og tilgjengeliggjøres over http.
SignaturFormat BPESIG0101 - PKCS#7 v1.5 SDO
BPESIG0101 som signaturformat er basert på PKCS#7 v1.5 / RFC 2315. Utover det som er påkrevd, inkluderes også såkalt Claimed Signing Time som i dette tilfellet er brukerstedets oppfatning av signeringstidspunktet.
Tabellen under viser hvilke felter som er påkrevd for de forskjellige relevante operasjonene for BPESIG0101 SignatureProvider. Se kapittelet om SignatureProvider for detaljert beskrivelse av hva de forskjellige parameterne betyr.
Modus | Encoding/Verification name | Påkrevde Felter | Overordnet beskrivelse |
|---|---|---|---|
Encoding | CMS_SIGNED_DATA_OBJECT | CONTENT | Genrerer hele PKCS#7 SDO'en |
Verifisering | CMS_SIGNED_DATA_OBJECT_INTEGRITY | CMS_SIGNED_DATA_OBJECT | Verifiserer integriteten i PKCS#7 SDO'en (ingen revokeringssjekk) |
Under er et kodeeksempel på sammensetting av en PKCS#7. Eksempelet er basert på at man har fått tilbake signatur og sertifikat etter signering, og at man har det signerte dokumentet og signeringstidspunkt tilgjengelig.
byte[] document = // the document
byte[] signature = // the signature
byte[] certificate = // the encoded certificate
Date signingTime = // the given signingTime
// get the BPESIG0101 signature provider
SignatureProvider sp = SignatureProvider.getInstance("BPESIG0101");
// initialize for encoding of the PKCS#7 signature SDO
sp.initializeForEncode("CMS_SIGNED_DATA_OBJECT");
// add required parameters
sp.setParam("CONTENT", document); // the excact binary representation
sp.setParam("CLAIMED_SIGNING_TIME", signingTime); // same as the SigningTime sent to IPS
sp.setParam("CERTIFICATE", certificate); // certificate from IPS
sp.setParam("SIGNATURE", signature); // signature from IPS
// get the encoded PKCS#7 signature SDO
byte[] pkcs7 = sp.encode();
Under er et kodeeksempel på verifisering av et signert dokument (verifisering av PKCS#7'en).
byte[] pkcs7 = // the signature, or from previous sample
// get the BPESIG0101 signature provider
SignatureProvider sp = SignatureProvider.getInstance("BPESIG0101");
// initialize for signature verification of the PKCS#7 signature SDO
sp.initializeForVerify("CMS_SIGNED_DATA_OBJECT_INTEGRITY");
// add required parameters (the signature)
sp.setParam("CMS_SIGNED_DATA_OBJECT", pkcs7);
// verify SDO integrity
boolean verifiedOk = sp.verify();SignaturFormat BPESIG0201 - ETSI TS 101 733 CAdES-BES SDO
BPESIG0201 som signaturformat er basert på PKCS#7 v1.5 / RFC 2315, men inkluderer i tillegg påkrevde elementer for å være konform med ETSI TS 101 733 CAdES-BES. Tilleggs elementene er hentet fra ESS RFC263 (Enhanced Security Servies), og består av signing-certificate elementet eller other-signing-certificate. IPS inkluderer signing-certificate elementet, som kort fortalt består av en SHA-1 Hash over signerers sertifikat. Dette inkluderes i signaturgrunnlaget for å sikre en entydig knytning mellom signatur og et faktiske sertifikatet som ble brukt. Utover det som er påkrevd, inkluderes også Claimed Signing Time som i dette tilfellet er brukerstedets oppfatning av signeringstidspunktet.
Tabellen under viser hvilke felter som er påkrevd for de forskjellige relevante operasjonene for BPESIG0201 SignatureProvider. Se kapittelet om SignatureProvider for detaljert beskrivelse av hva de forskjellige parameterne betyr.
Modus | Encoding/Verification name | Påkrevde Felter | Overordnet beskrivelse |
|---|---|---|---|
Encoding | CMS_SIGNED_DATA_OBJECT | CONTENT | Genrerer hele CAdES-BES SDO'en |
Verifisering | CMS_SIGNED_DATA_OBJECT_INTEGRITY | CMS_SIGNED_DATA_OBJECT | Verifiserer integriteten i CAdES-BES SDO'en (ingen revokeringssjekk) |
Under er et kodeeksempel på sammensetting av en CAdES-BES SDO. Eksempelet er basert på at man har fått tilbake signatur og sertifikat etter signering, og at man har det signerte dokumentet og signeringstidspunkt tilgjengelig.
Under er et kodeeksempel på verifisering av et signert dokument (verifisering av CAdES-BES SDO'en).
SignaturFormat BPESIG0301 - SEID-SDO-Basic
BPESIG0301 som signaturformat er basert på SEID-SDO-Basic profilen, som igjen er basert på PKCS#7 v1.5 / RFC 2315, men inkluderer i tillegg påkrevde elementer for å være konform med ETSI TS 101 733 CAdES-BES - som er påkrevd i SEID standarden. Tilleggs elementene er hentet fra ESS RFC263 (Enhanced Security Servies), og består av signing-certificate elementet eller other-signing-certificate. IPS inkluderer signing-certificateelementet, som kort fortalt består av en SHA-1 Hash over signerers sertifikat. Dette inkluderes i signaturgrunnlaget for å sikre en entydig knytning mellom signatur og et faktiske sertifikatet som ble brukt. Utover det som er påkrevd, inkluderes også Claimed Signing Time som i dette tilfellet er brukerstedets oppfatning av signeringstidspunktet.
SEID spesifiserer flere sett med profiler. BPESIG0301 er i.h.t. SEID-SDO-Basic profilen.
Tabellen under viser hvilke felter som er påkrevd for de forskjellige relevante operasjonene for BPESIG0301 SignatureProvider. Se kapittelet om SignatureProvider for detaljert beskrivelse av hva de forskjellige parameterne betyr.
Modus | Encoding/Verification name | Påkrevde Felter | Overordnet beskrivelse |
|---|---|---|---|
Encoding | SEID_SDO_BASIC | CONTENT | Genrerer hele SEID SDO'en (XML) |
Verifisering | SEID_SDO_BASIC_CMS_INTEGRITY | SEID_SDO_BASIC | Verifiserer integriteten i CMS delen av SDO'en (ingen revokeringssjekk) |
Under er et kodeeksempel på sammensetting av en SEID SDO. Eksempelet er basert på at man har fått tilbake signatur og sertifikat etter signering, og at man har det signerte dokumentet og signeringstidspunkt tilgjengelig.
SignaturFormat BPESIG0401 - PDF signatur, usynlig signatur
BPESIG0401 som signaturformat er basert på Adobes PDF signeringsformat. Signaturene som er opprettet ved hjelp av BPESIG0401 er ikke synlige i dokumentet ved f.eks. print, men sjekkes/verifiseres gjennom en PDF viewer (som Adobe Reader).
SignaturFormat BPESIG0402 - PDF signatur, synlig signatur
BPESIG0402 som signaturformat er basert på Adobes PDF signeringsformat. Signaturene som er opprettet ved hjelp av BPESIG0402 er synlige i dokumentet ved f.eks. print, og kan sjekkes/verifiseres gjennom en PDF viewer (som Adobe Reader).
Sammensetting av forespørselen
Sammensetting av signeringsforespørselen skjer typisk når en sluttbruker ønsker å signere noe. Ved sammensetting av en signeringsforespørsel, er det flere ting man må ta stilling til:
Hvordan skal dokumentet tilgjengeliggjøres for sluttbrukeren?
Påstått signeringstidspunkt
Signaturformat
Dokumentformat/MIME-type
Hvilke returverdier du ønsker om sluttbrukeren
Hvilket brukergrensesnitt du ønsker å bruke
Retur URL (ved redirigerte forespørseler)
Pr des-08 er det kun Smartkort med PKI som kan brukes til signering.
Påstått signeringstidspunkt anngis gjennom MerchantSigningTime elementet.
Brukergrensesnitt kode anngis gjennom RequestAttribute elementet.
Retur URL anngis i ResponseUrl elementet.
Returverdier anngis gjennom ResponseAttribute elementet. Data om brukeren blir returnert gjennom IdToken elementet i responsen.
Støttebiblioteket vil hjelpe deg med de resterende påkrevde elementene.
Under er et JSP eksempel på en komplett sammensatt forespørsel, hvor vi tilgjengeliggjør dokumentet på en sesjonsbasert URL, kryptert. Nøkkelen og sesjonscookien utveksels i forespørselen til IPS, slik at innholdet i praksis kun kan leses av IPS klienten. Vi ønsker å få fødselsnummeret i retur, og vi ønsker også å bruke et "FULLSIZE" brukergrensesnitt, og må derfor anngi dette gjennom RequestAttribute elementet. Dokumentet er et PDF dokument, og vi bruker derfor mime-typen "application/pdf". Eksempelet under spesifiserer et BPESIG0201 signaturformat, som er komform med ETSI 101 733 CAdES-BES signaturer.
Relevante elementer å forholde seg til ifm sammensetting av en signeringsforespørsel er:
SignRequest
SignRequestData
SignResponseData
ResponseURL
RequestAttribute
ResponseAttribute
Tilgjengeliggjøring av dokumentet for sluttbrukeren
Dokumentet må tilgjengeliggjøres for signeringsklienten som nevnt over. Under er et eksempel på hvordan en "getcontent.jsp", som det refereres til i eksempelet over, kan se ut. Eksempelet er en JSP fil, som kjøres på Tomcat (ref work-around for tomcat i eksempelet under). Koden under er kun ment som et eksempel og for å komplettere forståelsen av sammenhengen i de vedlagte eksempelkodene.
Redirigering/sending av forespørselen til IPS
Når signeringsforespørselen er satt sammen og klar, må den sendes til IPS. Dette gjøres ved å sende PSE og E parameteren til IPS, sammen med OP (operasjonstype) og M (merchantID) parameterene i en HTML form. HTML form'en returneres tilbake til nettleseren, og sendes automatisk til IPS (v.h.a. "auto-submit"/submit på body-on-load eventen). Under er et eksempel på en side som gjør dette basert på "pse" og "e" variablene fra det første eksempelet over. I eksempelet under er merchantID=32.
Javascript støtte er påkrevd i nettleseren for bruk av IPS.
Mottak og tolking av responsen
Returdataene fra signeringen "kommer tilbake" til brukerstedet på samme måte som de ble sendt til IPS. Det vil si at IPS vil returnere signeringsresponsen tilbake til nettleseren, som vil bli POST'et tilbake til brukerstedet på anngitt adresse (ResponseUrl).
Parameteren som inneholder returverdiene heter PE. Denne leses typisk ved å kalle
i en JSP fil. For å kunne dekryptere denne, må det korresponderende BxRequest objektet være tilgjengelig. I eksempelene over, ble dette lagt på sesjonsobjektet for å kunne brukes til dekryptering av responsen. Her er et eksempel på lesing, dekryptering og parsing:
I koden over har nå BxRequest objektet fra sesjonen blitt tilordnet responsen, og responsen er dekryptert og parset. Neste steg blir å lese ut dataene fra responseobjektene.
Sertifikat og signatur er nå hentet ut å ligger i scert og ssign variablene.
Sammensetting og verifisering av signaturobjektene
Under er et eksempel på sammensetning av SDO'en basert på response dataene fra eksempelet over. Etter å ha lest ut response dataene (i eksempelet over), bruker vi sertifikatet, signaturen, dokumentet og signeringstidspunktet til å generere PKCS#7 strukturen. Deretter verifiseres denne.