1. Formål

Formålet med dette dokument er at beskrive hvordan et udviklingsmiljø, til videreudvikling af Seal.Java services, kan sættes op, samt hvordan koden bygges, deployes og testes.
Først beskrives de softwaremæssige krav, der er til miljøet, samt hvordan kode hentes og bygges. Dernæst beskrives deploymentmiljøet.

2. Opsætning

Seal.java 3.x kræver Java 21 (Amazon Coretto)  for at bygge.

Hvis man bygger lokalt skal Java 21 være konfigureret som beskrevet i Seal.Java Installationsvejledning

2.1. Kildekode

Kildekoden til Seal.java findes i SDS Bitbucket:

https://git.nspop.dk/projects/LIB/repos/seal.java/browse

2.2. 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.

2.3. Bygge og unittest

Koden bygges vha. Maven vha. følgende kommando i roden af projektet:

mvn clean install

Unittests afvikles under byg, men kan også kaldes selvstændigt vha.:

mvn test

3. Udvikling

Herunder vejledning til udviklingen i forskellige områder af Seal.java. I Seal.Java stiller helt overordnet følgende funktionalitet til rådighed:

• Signering og validering af digitale XML signaturer.
• Kryptering og dekryptering af XML dokumenter.

3.1. Signering og validering af digitale XML signaturer

Seal.Java har funktionalitet  der kan lave digital signering af et W3C dokument. Der er også funktionalitet til at validere den digitale signatur. Denne funktionalitet findes i klasserne SignAndValidate og ExternalSigning. 

Klassen SignAndValidate anvender Seal.Java internt til digital signering og validering. ExternalSigning kan anvendes udefra til digital signering, hvor der er mulighed for at opbygge dele af signaturen.

3.1.1.  Eksempel på digital signering

Simpelt eksempel på en digital signatur. Vi vil gerne signerer dette simple XML dokument:

<?xml version="1.0" encoding="UTF-8" ?>
<person xmlns="http://www.sosi.dk/" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
  <fornavn id="elmtosign"><value>Hans</value></fornavn>
  <efternavn><value>Hansen</value></efternavn>
</person>

Når det skal signeres skal man medsende en konfiguration der angiver hvilken del af dokumentet der skal signeres og i dette tilfælde er det elemetet med attributten "id=elemtosign". 

Efter signering ser dokumentet således ud (bemærk: signatur-værdien og certifikatet er beskåret af hensyn til læsbarheden):

<?xml version="1.0" encoding="UTF-8"?>
<person xmlns="http://www.sosi.dk/"
    xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
    <fornavn id="elmtosign">
        <value>Hans</value>
        <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#" Id="OCESSignature">
            <ds:SignedInfo>
                <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
                <ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1" />
                <ds:Reference URI="#elmtosign">
                    <ds:Transforms>
                        <ds:Transform
                            Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature" />
                        <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
                    </ds:Transforms>
                    <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
                    <ds:DigestValue>QW77ZSa8bItvTzJ6Mx3U0UuhCBo=</ds:DigestValue>
                </ds:Reference>
            </ds:SignedInfo>
            <ds:SignatureValue>
                LvPqO4dbw9UglyNnkaIKN4oKaYCzv/pqcfNRzPd8UdUYiyRKY3zkCMdDB9EsjOp7ZsVym/O2mODQs8V34JjCVBQVHfwsQv8Ku0v...
            </ds:SignatureValue>
            <ds:KeyInfo>
                <ds:X509Data>
                    <ds:X509Certificate>
                      MIIGyzCCBP+gAwIBAgIUIp4rXilrr1cv616bbYPuFN68rIowQQYJKoZIhvcNAQEKMDSgDzANBglghkgBZQMEAgEFAKEcMBoG...
                    </ds:X509Certificate>
                </ds:X509Data>
            </ds:KeyInfo>
        </ds:Signature>
    </fornavn>
    <efternavn>
        <value>Hansen</value>
    </efternavn>
</person>

Signaturen kan man bryde op i følgende dele:

• <ds:Signature>: angiver at her starter den digitale signatur.
• <ds:SignedInfo>: indeholder følgende information
  • <ds:CanonicalizationMethod>: hvilken kanoniseringsalgoritme er blevet brugt for at normalisere dokumentet før signering.
  • <ds:SignatureMethod>: hvilken algoritme er brugt til generingen af signaturen.
  • <ds:Reference>: hvilket element er blevet signeret.
• <ds:SignatureValue: indeholder den digitale signatur. Værdien kan verificeres vha. den public key der findes under <ds:KeyInfo>
• <ds:KeyInfo>: indeholder X.509 certifikat der kan bruges til at autentificere underskriveren og validere signaturen.

3.2.  Kryptering og dekryptering af XML dokumenter

Følgende to metoder kan anvendes til kryptering og dekryptering af XML dokumenter:

• EncryptionUtility.encrypt(Element, PublicKey)
• EncryptionUtility.decrypt(Element, PrivateKey)

Disse er lavet så de er kompatible med tidligere versioner af Seal.Java. Tidligere versioner af Seal.Java brugte Apache Santuario til kryptering/dekryptering, så det generede dokument skal være kompatibel med Seal.Java 3.x.

Der er lavet følgende tests i Seal.Java der tjekker dette:

Den grundlæggende forskel på Seal.Java 2.x og Seal.Java 3.x er at førstnævnte benytter Apache Santuario, hvor det krypterede dokument har et bestemt format.

I Seal.Java 3.x benytter Java eget bibliotek til kryptering/dekryptering og her arbejdes kun med de rene krypteringsstrenge og resultatet bliver ikke pakket ind i et bestemt format.

Der skal Seal.Java 3.x selv kunne opbygge disse formater så de accepteres af Seal.Java 2.x.

Simpelt eksempel, hvor dette XML dokument ønskes krypteret:

<root>
    <ToEncrypt>
        <foo>bar</foo>
    </ToEncrypt>
</root>

Den krypterede udgave ser således ud: