Verohallinnon nimissä on lähetetty huijausviestejä. Lue lisää huijauksista.

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

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

     

  2. Tarvittavat työvälineet:

     

  3. Lisätietoja:

     

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.
Sivu on viimeksi päivitetty 16.5.2025