Esimerkki varmenteen uusimisesta ja allekirjoituspyynnöstä (CSR)

Tämä ohje kuvaa yhden tavan suorittaa Verohallinnon varmennepalvelun myöntämän varmenteen uusiminen ja allekirjoituspyynnön luominen käyttäen Verohallinnon varmennepalvelun PKI-järjestelmän Web Service -rajapintaa. Esimerkin perusteella varmenteen uusimisen voi toteuttaa omaan ohjelmistoon.

Ohjeessa on kuvattu varmenteen uusiminen. Ohje on sovellettavissa testi - ja tuotantovarmenteen uusimiseen.

Testiympäristössä käytetään keinotekoisia testitunnuksia ja testiympäristön osoitetta. Testiympäristössä ei saa käyttää tuotannon asiakastietoja. Tuotantovarmenteen uusimisessa käytetään aitoja asiakastietoja ja varmennepalvelun tuotanto-osoitetta.

Varmenteen uusiminen varmennepalvelun web service-rajapintaa käyttäen

Tarvittavat asiat:
- PKI-osaamista avainparin muodostamista ja allekirjoituspyynnön muodostamista varten
- Ohjelmointiosaamista, allekirjoitusohjelman kääntäminen ja suorittaminen
- Varmennepalvelun sanomarakenteet, WSDL-paketti: https://vero.fi/globalassets/tietoa-verohallinnosta/ohjelmistokehittajille/varmennepalvelu/varmennepalvelu-rajapinta_v1.01.zip
- Uusi avainpari varmenteen allekirjoituspyyntöä varten (CSR)
- Nykyinen varmenne ja siihen liittyvä yksityinen avain xml-sanoman allekirjoittamista varten
- Organisaatiosi käytössä oleva Web Service -varmenteen keinotekoinen Y-tunnus ja keinotekoinen yrityksen nimi
- Mahdollinen pfx-tiedosto, jossa nykyiseen varmenteeseen liittyvä yksityinen avain
- Nykyisen pfx-tiedoston salasana
Tarvittavat työvälineet:
- OpenSSL: https://wiki.openssl.org/index.php/Binaries
- .NET: .NET Downloads (Linux, macOS, and Windows) (microsoft.com)
- Visual Studio Code: https://code.visualstudio.com/
- Verohallinnon esimerkkiohjelman lähdekoodi (SignXmlNew) - XML-sanoman allekirjoittamiseen varmenteen uusimisrajapintaa varten.
- SoapUI: https://www.soapui.org/downloads/soapui/ tai Curl: https://curl.se/download.html
Lisätietoja:
- Ohjeet uusimiseen: Varmenteen uusiminen
- Dokumentaatio Verohallinnon varmennepalvelun sivuilla: Tekniset ohjeet - vero.fi
- Varmennepalvelun testipenkin ohje: Tekniset ohjeet - vero.fi dokumentin luvussa 7
- Verohallinnon varmennepalvelun havaintolomake

Esimerkkiohjelman lähdekoodi (SignXmlNew)

Verohallinnon esimerkkiohjelman lähdekoodi (SignXmlNew) - XML-sanoman allekirjoittamiseen varmenteen uusimisrajapintaa varten.

using System;
using System.IO;
using System.Security.Cryptography;
using System.Security.Cryptography.Xml;
using System.Security.Cryptography.X509Certificates;
using System.Text;
using System.Xml;

namespace SignXmlNew
{
    class Program
    {
        static void Main(string[] args)
        {
            try
            {
                // Check command line parameters and, if necessary, throw an exception with usage instructions
                if (args.Length != 3 ) throw new ArgumentException("Usage: xmlFile certPfxFile certPassword");

                string xmlFile = args[0];
                var certPfxFile = args[1];
                var password = args[2];


                XmlDocument doc = new XmlDocument();
                doc.PreserveWhitespace = true;
                doc.Load(xmlFile);

                X509Certificate2 cert = new X509Certificate2(certPfxFile, password);

                SignDocumentRsaSha256(doc, cert);

                // Write the destination file that includes the Signature element
                string destination = Path.GetFileNameWithoutExtension(xmlFile) + "_signed" + Path.GetExtension(xmlFile);
                doc.Save(destination);
                Console.WriteLine("OK, created: " + destination);
            }
            catch (Exception ex)
            {
                Console.WriteLine("Error: " + ex);
                return;
            }
        }

        ///
        /// Signs the given XmlDocument using RSA-SHA256 and the provided X509 certificate.
        /// 
        ///The XmlDocument to be signed.
        ///The X509Certificate2, containing the private key for signing.
        private static void SignDocumentRsaSha256(XmlDocument xmlDoc, X509Certificate2 cert)
        {
            var rsaKey = cert.GetRSAPrivateKey();
            SignedXml signedXml = new SignedXml(xmlDoc);
            signedXml.SignedInfo.CanonicalizationMethod = "http://www.w3.org/2001/10/xml-exc-c14n#";
            signedXml.SigningKey = rsaKey;
            Reference reference = new Reference();
            reference.Uri = "";
            XmlDsigEnvelopedSignatureTransform env = new XmlDsigEnvelopedSignatureTransform();
            reference.AddTransform(env);
            signedXml.AddReference(reference);
            var keyInfo = new KeyInfo();
            keyInfo.AddClause(new KeyInfoX509Data(cert));
            signedXml.KeyInfo = keyInfo;
            signedXml.ComputeSignature();
            XmlElement xmlDigitalSignature = signedXml.GetXml();
            xmlDoc.DocumentElement.AppendChild(xmlDoc.ImportNode(xmlDigitalSignature, true));
        }
    }
}

Testivarmenteen uusiminen

1

Luo uutta varmennetta varten uusi yksityinen avain
Luo yksityinen avain OpenSSL-ohjelmalla komennolla:
openssl genrsa -out newprivate.key 3072

Varmennepalvelu tukee 2048, 3072 ja 4096 -bittisiä avaimia. Verohallinto suosittelee vähintään 3072 bittisen avaimen käyttöä varmenteiden luomiseen. Vaihda yllä olevan Open SSL komennon loppuun teksti: 2048, 3072 tai 4096 riippuen, minkä kokoisen avaimen ja varmenteen haluat luoda.

Uusi luotu yksityinen avain muodostuu tiedostoon newprivate.key
2

Luo uusi varmenteen allekirjoituspyyntö uusimista varten
Muodosta varmenteen allekirjoituspyyntö (CSR) käyttäen kohdassa 1 luotua yksityistä avainta esim. OpenSSL-ohjelmalla komennolla:
openssl req -new -key newprivate.key -out certificaterequest.csr

Syötä seuraavat tiedot OpenSSL:lle uusittavan varmenteen tietojen mukaisesti:
Country Name = FI
Organization Name = Käytössänne olevan testiyrityksen nimi
Common Name = käytössänne oleva keinotekoinen y-tunnus

Uusi varmenteen allekirjoituspyyntö muodostuu tiedostoon certificaterequest.csr
3

Muodosta xml-sanoma allekirjoittamista varten
Muodosta varmenteen uusimisen xml-sanoman sisältöosa uusimisrajapintaa varten. Vain tämä osuus sanomasta allekirjoitetaan. Käytä oheista templatea, huomaa että editorit saattavat lisätä rivinvaihtoja, eli suositellaan poistamaan rivinvaihdot templaatista ennen allekirjoituksen muodostamista:

<cer:RenewCertificateRequest xmlns:cer="http://certificates.vero.fi/2017/10/certificateservices" xmlns:xd="http://www.w3.org/2000/09/xmldsig#">
<Environment>TEST</Environment>
<CustomerId>Käytössänne oleva keinotekoinen y-tunnus</CustomerId>
<CustomerName>Testiyrityksen nimi</CustomerName>
<CertificateRequest>Kohdassa 2 muodostettu varmenteen allekirjoituspyyntö eli csr-tiedoston sisältämä base64 merkkijono ilman --- begin certificate request -- ja --- end certificate request --- otsikoita</CertificateRequest>
</cer:RenewCertificateRequest>

Täytä esimerkkisanoman kenttiin testivarmenteesi Y-tunnus (keinotunnus), keinotekoinen yrityksen nimi sekä kohdassa 2 luomasi uusi varmenteen allekirjoituspyyntö (base 64 merkkijono, ilman "--- begin certificate request---" alku- ja loppuotsikoita). Tallenna xml-tiedosto levylle allekirjoittamista varten, ilman rivinvaihtoja.
4

Allekirjoita xml-sanoma
Muodosta allekirjoitus sanoman sisältöosalle eli osalle, joka on muodostettu kohdassa 3. Voit käyttää valmiita ratkaisuja esim. XML Signer -ohjelmaa tai toteuttaa itse tai käyttää Verohallinnon esimerkkitoteutusta. Tämä ohje hyödyntää Verohallinnon C#-toteutusta. Esimerkkitoteutus olettaa, että nykyinen varmenne on pfx-tiedostossa.

Hae allekirjoitusohjelman esimerkkitoteutuksen lähdekoodi kohdasta Esimerkkiohjelman lähdekoodi (SignXmlNew). Lataa tarvittavat .NET -kirjastot sekä sopiva kehitysympäristö, esimerkiksi Visual Studio Code, ohjelman kääntämistä varten.
5

Muodosta pfx-tiedosto allekirjoitusohjelmalle Open SSL:n avulla
Suorita oheinen komento, joka muodostaa pfx-tiedoston. Tiedostoon viedään nykyinen varmenne ja yksityinen avain, jolla se on muodostettu.

Jos pfx-tiedostoa ei jo ole, muodosta pfx-tiedosto seuraavalla komennolla, jolloin siihen viedään yksityinen avain sekä nykyinen varmenne (tallennettu cert.cer-tiedostoon base64 muodossa):
openssl.exe pkcs12 -export -out new.pfx -inkey private.key -in cert.cer

Nykyisin käytössä olevan varmenteen yksityinen avain on komennon syötteessä private.key-tiedostossa base64-muodossa suojaamattomana sekä varmenteen julkinen osa (= allekirjoitettu julkinen avain) on cert.cer-tiedostossa base64-muodossa.

OpenSSL kysyy salasanaa, jolla pfx-tiedosto suojataan. Salasanaa tarvitaan allekirjoitusohjelmassa. Lopputuloksena muodostuu new.pfx-tiedosto.

Jos kokeilet testipenkissä:
Muodosta pfx-tiedosto yllä olevalla komennolla, jolloin siihen viedään yksityinen avain, testipenkin SignNewCertificate_Private.key-tiedosto sekä testipenkistä noudettu nykyinen varmenne, joka on tallennettu cert.cer-tiedostoon base64 muodossa.
6

Aja allekirjoitusohjelma
Käännä ja suorita allekirjoitusohjelma (SignXmlNew.exe) ja anna komentoriviparametrina kohdassa 3 luomasi allekirjoitettava xml-sanoma, pfx-tiedosto ja sille luomasi salasana:
SignXmlNew.exe renew.xml new.pfx password
Lopputuloksena syntyy allekirjoitettu xml-tiedosto renew_signed.xml, alla oleva esimerkki testipenkistä:

<cer:RenewCertificateRequest xmlns:cer="http://certificates.vero.fi/2017/10/certificateservices" xmlns:xd="http://www.w3.org/2000/09/xmldsig#">
<Environment>TEST</Environment>
<CustomerId>0123456-7</CustomerId>
<CustomerName>Ab PKI Developer Company Oy</CustomerName>

<CertificateRequest>
MIICjTCCAXUCAQAwSDELMAkGA1UEBhMCRkkxEzARBgNVBAgMClNvbWUtU3RhdGUx
JDAiBgNVBAoMG0FiIFBLSSBEZXZlbG9wZXIgQ29tcGFueSBPeTCCASIwDQYJKoZI
hvcNAQEBBQADggEPADCCAQoCggEBAJkBP88eLdbxbJfPluDI/rNP0EUpluRohxgx
MNfuYVV9kXgrMsOZpCsV/QjwZFpWBSFy6PDJIKyvAqe83XSfoGPt9apy3QaUJuXR
4/P5H6VT+eZpt1TCf5CEaKb0aW4bZ1kN9BLerrJ81HsR6cutpE/t0bzArc4kna/l
rz/yB3tlU34YoHyx9bXNwKSPsUdL7N32vIuSO8Me/3NjFzA9CBYRrP58qnXIyTmm
0x5GJXGBJqJM2xBRCmpMWg5WGUOF8mAGxkPDxyEfZpaHXbSLaBQ1nJyDPg0+n/Ak
rcweydE0BKmMh3rSITH/M5DYZ6yKgHABEWERg1Nz06ei+a+KJUcCAwEAAaAAMA0G
CSqGSIb3DQEBCwUAA4IBAQBsIqCulgyrfU+DVZxS60Hvu4d8GcKKRGCtFBt508BM
c+NSnevgakWZXXMWKOJStsDHsOPnwfaIvlmFLWRkAsqxt2dIGgWMzFh9NaX0Anwm
CbiUruot9C8zguP7Y/67AFSeageNYrHmgIBHoZyNIe+tPR4Y5DxcQBl/6HtyzJ/q
Nej5mp2zSlW5P1QoEkS3MU8Gm0mpCBylyAvCzeYHOop6caZMQctVCmPto+0PYx0T
qEmO15vGj/rIN4btjEKSYfjNj56MMN8lsIc/6vqdikKKmMwTLRXjq73liOYyJ11s
9433VK1J/UMvay3y2jYKVDUUw567HD8C3lsT+A+ifkCo
</CertificateRequest>
<Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
<SignedInfo>
<CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
<SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256" />
<Reference URI="">
<Transforms><Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature" />
</Transforms>
<DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256" />
<DigestValue>i13a6CV9yr+uqy/qx4yhvyysDvcKnoiNIjUdj7Arr1A=
</DigestValue>
</Reference>
</SignedInfo>
<SignatureValue>
VEja46Y17IaMXHMJfcZMRM+3zPTLSepv/zWeR2JLMMCz3nWl
dJynhs1MjGMbqJ3gLsebomkE3UX10ToZ0LObtbeACFYz78dDKbWHTc4cU1IWkZU3
DpXQ5svgJWNk1L+B2SDH7V+ethFNqBmwLCgsE2dT8pt7rXwsBOnZe/Rt30flEMd5
sSWYYJeb1FzMXAcafVIoVs31T9HcoCFupgMH9YWsgzpknQHTSTKfjBZbhsjBnvnD
IwSceFhxxNpcmY/zVjRVB56WeC2qhQgZFN7PsnCJ6KnNOTkYr2w7CVCFNwofCMU3
eXUl+n5khTJmNQV+SZ2S0qPzBSp6TD/reCVJHA==
</SignatureValue>
<KeyInfo>
<X509Data>
<X509Certificate>
MIIFqzCCA5OgAwIBAgIIGZoeTGyXo3IwDQYJKoZIhvcNAQELBQAwSjEkMCIGA1UE
AwwbUEtJIFNlcnZpY2UgRGV2ZWxvcGVyIENBIHYxMRUwEwYDVQQKDAxWZXJvaGFs
bGludG8xCzAJBgNVBAYTAkZJMB4XDTIwMDcwNjA4MzYzMloXDTMwMDcwNDA4MzYz
MlowcjESMBAGA1UEAwwJMDEyMzQ1Ni03MSkwJwYDVQQFEyBDNDY4MTkxMDdCNDAx
NUI0MUIzMTA0MTExMUE0REE2RDEkMCIGA1UECgwbQWIgUEtJIERldmVsb3BlciBD
b21wYW55IE95MQswCQYDVQQGEwJGSTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCC
AQoCggEBAMrf+WUx2nuYBOeG3PxqzIeMmMVRwlqmBTH/jdW0AmRZ34cuh+Do/T6U
0mqg9G4lVsj8WaM8fmh7tdCQ3xcCPnqpQrkeGuWQV4nIhok74kDnQb12FrOKCsLI
OMONHS2+9E8HKwS8giFXzKP8UUnJK8PmptJQo+E6jlEy+vzSsHouf0UMCgp9MutN
9RlAtjqS6lyHtqp8BLn2hdEM1srIqCXBRigkAH5w1mqbBSiVkgsCaYJ+I5AY201Z
TUlb138SY/bYk9gfLS1aY1gEF+667Bmys0aJk4JRLHujMqfkEuHrfRWo1ps739H+
8UPqkRmJfNybGFUPoJEwcfGIkXdYGPUCAwEAAaOCAWswggFnMAwGA1UdEwEB/wQC
MAAwHwYDVR0jBBgwFoAUT1PJe8BCr9h+uQE8W6CNC7/QfeYwUwYIKwYBBQUHAQEE
RzBFMEMGCCsGAQUFBzAChjdodHRwOi8vY3JsLXRlc3RpLnZlcm8uZmkvY2EvUEtJ
U2VydmljZURldmVsb3BlckNBdjEuY3J0MBMGA1UdJQQMMAoGCCsGAQUFBwMCMIGc
BgNVHR8EgZQwgZEwgY6gPKA6hjhodHRwOi8vY3JsLXRlc3RpLnZlcm8uZmkvY3Js
L1BLSVNlcnZpY2VEZXZlbG9wZXJDQXYxLmNybKJOpEwwSjEkMCIGA1UEAwwbUEtJ
IFNlcnZpY2UgRGV2ZWxvcGVyIENBIHYxMRUwEwYDVQQKDAxWZXJvaGFsbGludG8x
CzAJBgNVBAYTAkZJMB0GA1UdDgQWBBQwtQwXI5AZJVyZf4DEemCYLnw+mzAOBgNV
HQ8BAf8EBAMCBaAwDQYJKoZIhvcNAQELBQADggIBADZkkj4T+rVlAe9a53/9zrWL
uJqe+WePxIoEk5ozXWDb2FeR0uEyUS2Ba0gVJwPm9Go6CAia3J9nFGyVUUNCm2of
dDGxEX4JkrRc7cO8JPaMY74tJR9wwj8R5sshAXPDVMWh9Ml8LHG6hqz0ic0lK9cS
sAHBGJ3GBlckS/6y+SPWGKMHOf0QIm5of63qQ8aI950y4aUjL7td2Yxiu6jKUfP4
haL0BvJFM///o6Ge5LxT3nfPZxESBLbLE21D0ksyO+fZIjIeflxIeQk9rWY7zYq/
Go9+EIvElLXE2aDjqQrwoNIQHmqLgG0DuKpJKzSi7nRvDVHaB5YIdtLDJ4PXZlTk
ib8QBOZWmHCw58IvfEdL0WfuRpzJmlCf8oyzLWRagtnEQhwnWnkXOtPqivRq3Rh3
5M4mQPNVPikduzYlhvQzwCAVkzgspEZVT5hQlTEXBiZZQ8jC8Mb6U1u7G/NndHGw
dWn0WtNYDMrhqEZGoHxgLTLwaU4d5suHzkv0gIxkreR4fnVdiVWd4zCNQk6rt9Jo
3p0yLFGM49G3kszHPcYxxBmzqSrSBoBKX5Sn9+jOF39fxE6LNCmJBiZz49WhSOTS
LjX/kL8B0T4NBCtz6EdhQk0lz1JC5GvNuVVnmKeZYElt3qLvx4ktc6QxlH2zZ48B
R+m/cXycvyLzy2fgyAlW
</X509Certificate>
</X509Data>
</KeyInfo>
</Signature>
</cer:RenewCertificateRequest>

Huomaa, että allekirjoitusohjelma on lisännyt RenewCertificateRequest-lohkon loppuun Signature-lohkon.

Tärkeää on, että tiedoston sisältöä ei saa muuttaa millään tavalla ennen sen lähetystä PKI-järjestelmän rajapintaan, jotta allekirjoitettu sisältö ei muuttuisi. Muutoksen aiheuttavat myös rivinvaihdot tai muut muotoilut, jolloin allekirjoitus ei ole enää validi ja varmennepalvelu vastaa virhekoodilla PKI010.
7

Lähetä allekirjoitettu sanoma varmennepalvelun PKI-järjestelmän rajapintaan
Lähetä allekirjoitettu testivarmenteen uusimisen sanoma esimerkiksi SoapUI-ohjelmalla varmennepalvelun PKI-järjestelmän testiosoitteeseen:
https://pkiws-testi.vero.fi/2017/10/CertificateServices

Lataa SoapUI:hin WSDL-kuvauksen perusteella sanomarakenteiden pohjat. Lataa varmennepalvelun WSDL rajapintapaketti: https://vero.fi/globalassets/tietoa-verohallinnosta/ohjelmistokehittajille/varmennepalvelu/varmennepalvelu-rajapinta_v1.01.zip. Avaa WSDL-tiedosto SoapUI:lla.

Muodosta lähtevä sanoma siten, että allekirjoitettu sisältö on muuttumattomana soap-envelopen body-elementin sisällä. Älä muotoile millään tavalla allekirjoitettua sisältöä.

Esimerkki soap-envelopesta ja kohta mihin sisältö viedään:
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xs="http://www.w3.org/2001/XMLSchema" ><env:Body>
tähän allekirjoitettu sisältö sellaisenaan, joka muodostettu ohjeen kohdassa 4
</env:Body></env:Envelope>

Tarkista URL ja lähetä sanoma. Vastauksena tulee OK sekä retrievalID, jolla uusitun varmenteen voi noutaa GetCertificate-operaatiolla.

SoapUI:n sijaan voi käyttää CURL-ohjelmaa, jolloin mm. Windows-ympäristössä on oltava tarkkana, että rivinvaihtoja ei saa olla allekirjoitettavassa sisällössä vaan kaiken sisällön on oltava yhdellä rivillä. Muista lisätä allekirjoitettuun tiedostoon soap-envelope. Oheisella CURL-komennolla voi lähettää uusimispyynnön:
curl -i -v -d @template_signed_env.xml --header "SOAPAction:renewCertificate" -H "Content-Type: text/xml;charset=UTF-8" -H "Accept-Encoding: gzip,deflate https://pkiws-testi.vero.fi/2017/10/CertificateServices
8

Nouda uusittu varmenne GetCertificate-operaatiolla
Hyödynnä noutamisessa varmennepalvelun ohjeistusta.
Säilö pfx-tiedosto ja yksityinen avain huolellisesti.

Esimerkki varmenteen uusimisesta ja allekirjoituspyynnöstä (CSR)

Varmenteen uusiminen varmennepalvelun web service-rajapintaa käyttäen

Esimerkkiohjelman lähdekoodi (SignXmlNew)

Testivarmenteen uusiminen

Luo uutta varmennetta varten uusi yksityinen avain

Luo uusi varmenteen allekirjoituspyyntö uusimista varten

Muodosta xml-sanoma allekirjoittamista varten

Allekirjoita xml-sanoma

Muodosta pfx-tiedosto allekirjoitusohjelmalle Open SSL:n avulla

Aja allekirjoitusohjelma

Lähetä allekirjoitettu sanoma varmennepalvelun PKI-järjestelmän rajapintaan

Nouda uusittu varmenne GetCertificate-operaatiolla

Kirjeet vain sähköisesti

Syventävät vero-ohjeet

Verohallinto