PKCS#11 pkcs11-toolilla#

Tässä oppaassa kuvataan PKCS#11-ajurin käyttö NetHSM:ssä. Oppaassa käytetään työkaluja osoitteesta OpenSC. Katso niiden dokumentaatio, jos haluat tietää, miten niitä käytetään käyttöjärjestelmässäsi.

Tärkeä

Tämä ajuri on vielä varhainen Proof of Concept -toteutus, joka toteuttaa vain TLS-palvelinten käyttämiseen tarvittavat toiminnot.

Asennus#

Asenna valmiiksi käännetty kirjasto#

  1. Lataa arkisto, jossa on uusin julkaisu, arkiston releases-sivulta. Käytä julkaisuarkistoa, jonka otsikossa on käyttöjärjestelmäsi nimi.

  2. Pura tiedostot ladatusta arkistosta valitsemallasi arkistointiohjelmalla.

  3. Kopioi purettu kirjasto käyttöjärjestelmäsi vastaavaan polkuun. Polku riippuu OpenSC:n asennuksesta ja kokoonpanosta.

Käännä lähdekoodista#

Tärkeä

Tämä ajuri voidaan kääntää vain virallisella Go-kääntäjällä. Älä käytä GNU Go -kääntäjää (GCC-Go). Tutustu heidän -sivustoonsa saadaksesi lisätietoja sen asentamisesta.

  1. Lataa arkisto, jossa on uusin julkaisu, arkiston releases-sivulta. Käytä julkaisuarkistoa, jonka otsikossa on Lähdekoodi.

  2. Pura tiedostot ladatusta arkistosta valitsemallasi arkistointiohjelmalla.

  3. Suorita seuraava komento kirjaston kääntämiseksi hakemistossa, jossa on poimittu lähdekoodi.

    ./build.sh

  4. Kopioi purettu kirjasto käyttöjärjestelmäsi vastaavaan polkuun. Polku riippuu OpenSC:n asennuksesta ja kokoonpanosta.

Konfigurointi#

Konfigurointitiedosto p11nethsm.conf tarvitaan, ja sitä käytetään PKCS#11-ajurin ja NetHSM:n välisen yhteyden määrittämiseen.

Esimerkki konfigurointitiedostosta näyttää seuraavalta.

YAML 1.1
---
p11nethsm:
  logfile: /tmp/p11nethsm.log
  maxsessioncount: 5
  debug: true
  slots:
  - label: NetHSM1
    description: NetHSM Zone A
    url: "https://nethsmdemo.nitrokey.com/api/v1"
    # certSHA256:
    #   - "0C:66:DC:EB:4D:12:C3:24:FC:82:F4:1D:4C:16:44:12:1D:00:79:FF:36:96:65:E2:21:C4:36:94:F7:8E:22:89"
    user: "operator"
    password: "env:NETHSM_PASS"

Muokkaa asetustiedostoa p11nethsm.conf ympäristösi mukaan.

Konfiguraatiotiedosto voi sisältää useita lähtöpaikkoja, jotka ovat lots-joukon sisällä. Slotit edustavat useita NetHSM-käyttöönottoja. Slotin label-kentän on sisällettävä yksilöllinen nimi. Avaimet url, user ja password ovat pakollisia. Turvallisuussyistä on suositeltavaa antaa salasana ympäristömuuttujassa. Tätä varten env:NETHSM_PASS välitetään password-avaimessa, jossa NETHSM_PASS on salasanan sisältävän ympäristömuuttujan nimi. certSHA256-avain on asetettava, jos TLS-varmenteen allekirjoittajana ei ole käyttöjärjestelmän varmenteiden varastossa oleva varmentaja (CA).

Määritystiedosto on tallennettava joko seuraaviin polkuihin tai siihen hakemistoon, jossa sovellus suoritetaan.

  • $HOME/.nitrokey

  • /etc/nitrokey/

Avainten hallinta#

Info#

Näytä tiedot cryptoki-versiosta ja PKCS#11-ajurista.

$ pkcs11-tool --module p11nethsm.so --show-info

Cryptoki version 2.40
Manufacturer     Nitrokey GmbH
Library          NetHSM PKCS#11 module (ver 0.1)
Using slot 0 with a present token (0x0)

Luettelo peliautomaateista#

Tiedot käytettävissä olevista lähtö- ja saapumisajoista. Luetellut lähtö- ja saapumisajat riippuvat lähtö- ja saapumisaikataulurivin määrityksestä p11nethsm.conf-kokoonpanotiedostossa. Lisätietoja lähtö- ja saapumisaikojen konfiguroinnista on luvussa Konfigurointi.

$ pkcs11-tool --module p11nethsm.so --list-slots

Available slots:
Slot 0 (0x0): NetHSM Zone A
  token label        : NetHSM1
  token manufacturer : Nitrokey GmbH
  token model        : NetHSM
  token flags        : rng, token initialized, PIN initialized, readonly
  hardware version   : 0.1
  firmware version   : 0.1
  serial num         : 0
  pin min/max        : 3/256

Muista

Jos kokoonpanosi tukee useampaa kuin yhtä korttipaikkaa, sinun on ehkä lisättävä –korttipaikka <arg> -vaihtoehto pkcs11-toolin komentoihin, jotta voit käyttää oikeaa korttipaikkaa.

Luo avain#

Luo avainparin ja tallenna se NetHSM:ään.

Muista

PKCS#11-ajuri ei tällä hetkellä tue tätä ominaisuutta. Avainparin voi luoda osoitteessa nitropy tai REST API -pyynnöllä. Lisätietoja avaimen luomisesta on luvussa Generate Key.

Luetteloavaimet#

Näytä tiedot NetHSM:n avainsäilössä Key Store olevista avaimista ja varmenteista.

$ pkcs11-tool --module p11nethsm.so --list-objects

Using slot 0 with a present token (0x0)
Private Key Object; RSA
  label:      myFirstKey
  ID:         6d7946697273744b6579
  Usage:      decrypt, sign
  Access:     sensitive, always sensitive, never extractable
Public Key Object; RSA 0 bits
  label:      myFirstKey
  ID:         6d7946697273744b6579
  Usage:      none
  Access:     none

Lue avaimet#

Lue avaimet ja varmenteet NetHSM:n Key Store -avainvarastosta. Yksityisiä avaimia ei voi lukea NetHSM:stä.

Avainparin julkinen avain voidaan lukea seuraavasti.

$ pkcs11-tool --module p11nethsm.so --read-object --type pubkey --label myFirstKey -o public.key

Avainparin varmenne voidaan lukea seuraavasti.

$ pkcs11-tool --module p11nethsm.so --read-object --type cert --label myFirstKey -o public.key

Palautetut varmenteet tai julkiset avaimet ovat ASN.1-koodattuja. Tiedot voidaan purkaa dumpasn1 -työkalulla, koska ne sisältävät DER-muotoisia tietoja. DER-muoto voidaan muuntaa PEM-muotoon OpenSSL:llä.

Kirjoita näppäimet#

Kirjoita avaimet ja varmenteet NetHSM:ssä olevaan Key Store -avainsäilöön.

Avainparin yksityinen avain voidaan kirjoittaa seuraavasti.

$ pkcs11-tool --module p11nethsm.so --write-object secret.key --type privkey --label myFirstKey

Avainparin julkinen avain voidaan kirjoittaa seuraavasti.

$ pkcs11-tool --module p11nethsm.so --write-object public.key --type pubkey --label myFirstKey

Avainparin varmenne voidaan kirjoittaa seuraavasti.

$ pkcs11-tool --module p11nethsm.so --write-object cert.pub --type cert --label myFirstKey

Tärkeimmät toiminnot#

Salaa#

NetHSM ei voi salata tietoja epäsymmetrisillä avaimilla, mutta se tarjoaa julkisen avaimen, jota voidaan käyttää salaukseen. Lue lisää julkisen avaimen hakemisesta luvusta Näytä avaimen tiedot tai hae avain luvussa Lue avaimet <pkcs11_with_pkcs11.html#read-keys> kuvatulla tavalla. Esimerkissä oletetaan, että julkinen avain on tiedostossa public.pem.

Tiedot voidaan salata OpenSSL:llä seuraavasti.

$ echo 'NetHSM rulez!' | openssl pkeyutl -encrypt -pubin \
   -inkey public.pem \
   -pkeyopt rsa_padding_mode:oaep \
   -pkeyopt rsa_oaep_md:sha512 \
   -pkeyopt rsa_mgf1_md:sha512 \
   -out encrypted.data

Purkakaa salaus#

NetHSM voi purkaa NetHSM:n Key Store -avainvarastoon tallennetun yksityisen avaimen tiedot. Tässä esimerkissä käytetään edellisen luvun Salaa salattua viestiä.

$ pkcs11-tool --module p11nethsm.so --decrypt \
   --mechanism RSA-PKCS-OAEP \
   --input-file encrypted.data \
   --label myFirstKey \
   --hash-algorithm SHA512

NetHSM rulez!

Kirjaudu#

NetHSM voi allekirjoittaa tietoja yksityisellä avaimella, joka on tallennettu NetHSM:n Key Store:iin. RSA- ja ECDSA-avaimella tehtäviä allekirjoituksia varten on ensin laskettava digesti.

Digestin laskemiseksi tarvitaan ensin tiedot. Viesti luodaan seuraavasti.

$ echo 'NetHSM rulez!' | pkcs11-tool --module p11nethsm.so \
   --sign \
   --mechanism SHA512-RSA-PKCS-PSS \
   --output-file sig.data \
   --label myFirstKey

Luotu allekirjoitus voidaan todentaa OpenSSL:llä seuraavasti.

$ echo 'NetHSM rulez!' | openssl dgst -keyform PEM \
   -verify public.pem \
   -sha512 \
   -sigopt rsa_padding_mode:pss \
   -sigopt rsa_pss_saltlen:-1 \
   -signature sig.data