Indledning

Dette dokument henvender sig til anvendere af Seal.Java. Dette dokument giver en mere overordnet introduktion til Seal.Java og der er nogle undersider der fokuserer på nogle konkreteanvendelser af Seal.Java.

I dette dokument beskrives følgende:

• Forudsætninger for at kunne anvende Seal.Java
• Hvad kan Seal.Java anvendes til?
• Hvordan kommer man som anvender i gang med at bruge Seal.Java?
• Give en oversigt over de mest centrale klasser og metoder.
• Forskelle på Seal.Java 2 og Seal.Java 3.

Der findes konkrete kodeeksempler i undersiderne til dette dokument, så man kan se hvordan Seal.Java kan anvendes.

Forudsætninger

Seal.Java er i modsætning til de øvrige NSP komponenter et kodebibliotek og anvenderne forventes at have andre og mere tekniske forudsætninge.

Man bør som minimum have kendskab til følgende for at kunne anvende Seal.Java:

• Java
• XML
• SOAP
• SAML2
• WS-Security
• X.509
• OCES3

Der vil være en indledende beskrivelse som ikke forudsætter ovenstående.

Hvad kan Seal.Java anvendes til?

Seal.Java anvendes til at sikre, at DGWS og IDWS standarden bliver overholdt.

Seal.Java har følgende tre overordnede anvendelser:

1. Som Consumer, hvor den benyttes til at opbygge DGWS/IDWS requests.
2. Som Provider, hvor den benyttes til at modtage DGWS/IDWS requests.
3. Som Security Token Service, hvor den udsteder et token til en Consumer og som Provider stoler på.

De tre måder at anvende Seal.Java på kan illustreres på følgende måde:

Hvordan kommer man igang med at anvende Seal.Java?

Dette afsnit beskriver hvordan man rent praktisk kommer igang med at anvende Seal.Java i en komponent og hvordan navigere man rundt i koden.

Hvis man vil anvende Seal.Java er det nødvendigt at have kendskab til de Factory klasser og mdoelobjekter der findes i Seal.Java.

Ønsker man selv at kunne bygge Seal.Java, så henvises til Seal.Java - Guide til udviklere.

Distribution

De binære pakker er tilgængelige igennem NSPOPs Nexus (pakke manager):

https://nexus.nspop.dk/nexus/service/rest/repository/browse/public/dk/sosi/seal/seal/

Her findes også SNAPSHOT udgaver, som kan bruges under udvikling af funktionalitet, der skal testes inden release.

Man anvender Seal.Java fra en komponent ved at tilføje følgende Maven dependency:

<dependency>
	<groupId>dk.sosi.seal</groupId>
	<artifactId>seal</artifactId>
	<version>3.x.x</version>
</dependency>

Kodestruktur

Modelobjekter

De helt centrale byggeblokke i Seal.Java er en række modelobjekter der afspejler eksempelvis et request, response eller en sikkerhedsbillet (OIO SAML assertion eller ID-kort).

Disse modelobjekter konstrueres vha. af en række model-builder klasser og kaldene til disse er samlet i nogle factory-klasser, så der kun er en enkelt indgang pr. omveksling.

Modelobjekterne bliver signeret som en del af opbygningen.

Ud over metoder til konstruktion af modeobjekter, så indeholder factory-klasserne også indgange til følgende:

• DOM-builders benyttes til at serialisere modelobjekter til XML dokumenter.
• Model-builders benyttes til at deserialisere XML dokumenter til modelobjekter

I det følgende vises et pseudokode eksempel på hvordan et request der indeholder et bootstrap Token opbygges:

// Brug denne factory
OIOSAMLFactory factory = new OIOSAMLFactory();


// Opbyg NSP OIO SAML Bootstrap Token
OIO3BSTCitizenSAMLAssertionBuilder oio3bstCitizenSAMLAssertionBuilder = factory.createOIO3BSTCitizenSAMLAssertionBuilder();
oio3bstCitizenSAMLAssertionBuilder.setSigningVault(signingVault);
...
OIOBSTSAMLAssertion oiobstsamlAssertion = oio3bstCitizenSAMLAssertionBuilder.build();


// Opbyg STS request (serialisering)
OIOBootstrapToIdentityTokenRequestDOMBuilder requestDomBuilder = factory.createOIOBootstrapToIdentityTokenRequestDOMBuilder();
requestDomBuilder.setOIOBootstrapToken(oiobstsamlAssertion);
requestDomBuilder.setSigningVault(signingVault);
...
Document consumerStsRequestDocument = requestDomBuilder.build();

// STS modtager request (deserialisering)
OIOBootstrapToIdentityTokenRequest stsRequest = factory.createOIOBootstrapToIdentityTokenRequestModelBuilder().build(consumerStsRequestDocument);

I underdokumenter til anvenderguiden findes der komplette eksempler der vises hele flowet mellem consumer, provider og STS.

Factory klasser

Der findes en række factory klasser der fungerer som indgange til anvendelse af modelklasserne. De kan grupperes på følgende måde:

Signering

Et andet centralt begreb i Seal.Java er CredentialVault, der benyttes til at afkoble brugen af certifikater og keystores. Dermed behøver man ikke kende til den underliggende implementation. Det giver mulighed for at udskifte implementering, f.eks. at bruge Java KeyStore, HSM (Hardware Security Module),  filbaseret vault eller noget andet.

Oversigt over klasser og metoder

Service Consumer

I den følgende tabel vises en oversigt over de omvekslinger Seal.Java understøtter når man vil benytte den som Consumer. 

Omvekslingerne er grupperet efter samme farveskema der er anvendt i dokumentationen for NSP Security Token Service. Se STS - Guide til anvendere.

Ud for de enkelte omvekslinger findes et link til en anvenderguider der specifikt handler om denne omveksling. Her vil man også kunne finde konkrete kodeeksempler der viser hvordan den anvendes.

Security Token Service

I den følgende tabel vises en oversigt over de omvekslinger Seal.Java understøtter når man vil benytte den som en del af en Security Token Service. 

Omvekslingerne er grupperet efter samme farveskema der er anvendt i dokumentationen for NSP Security Token Service. Se STS - Guide til anvendere.

Ud for de enkelte omvekslinger findes et link til en anvenderguider der specifikt handler om denne omveksling. Her vil man også kunne finde konkrete kodeeksempler der viser hvordan den anvendes.

Service Provider

Forskelle på Seal.Java 2 og Seal.Java 3

Dette afsnit beskriver hvad man skal være opmærksom på hvis man anvender Seal.Java 2.6.x eller 2.7.x og vil skifte til Seal.Java 3.0.x

Seal.Java 3

Den oprindelige udgave af Seal.Java er baseret på Java 8 og den er afhængig af en række eksterne biblioteker til bla. signering, kryptering og håndtering af XML. Disse biblioteker er centrale for sikkerheden i Seal.Java og det er en udfordrende opgave at holde dem up-to-date hele tiden. Der findes tilsvarende funktionalitet indbygget som standard i Java og hvis man anvender den, så undgår man disse ekstern afhængigheder. I processen med at skifte til at bruge de indbyggede sikkerhedsbiblioteker blev det besluttet at benytte Java 21 i stedet for Java 8, da NSPs måde at anvende dem på ikke var fuldt understøttet i Java 8.

 Overgang til Seal.Java 3

På følgende punkter er der væsentlige ændringer i forhold til Seal.Java 2:

• Modulet 'demo' er blevet fjernet.
• Methoden SignatureUtil.getSignedInfoBytes() er udgået, da det ikke er understøttet i JDK'en at beregne digest værdier på denne måde.
• Der er ikke længere understøttelse for at repræsentere certifikatet som tekst (isAddCertificateAsReference).