Operatie#

Dit hoofdstuk beschrijft operationele taken voor gebruikers met de rol Administrator en Operator. Zie hoofdstuk Rollen voor meer informatie over de rol.

Belangrijk

Lees de informatie in het begin van dit document ` <index.html>`__ voordat u aan de slag gaat.

Sleutelbeheer#

Genereer sleutels#

De NetHSM kan sleutelparen genereren. Het wordt aanbevolen de sleutel-ID optie te specificeren om het een expressieve naam te geven.

De ondersteunde sleuteltypes en hun overeenkomstige mechanismen zijn de volgende.

Type sleutel

Mechanismen

TAG

RSA_Decryption_RAW RSA_Decryption_PKCS1 RSA_Decryption_OAEP_MD5 RSA_Decryption_OAEP_SHA1 RSA_Decryption_OAEP_SHA224 RSA_Decryption_OAEP_SHA256 RSA_Decryption_OAEP_SHA384 RSA_Decryption_OAEP_SHA512 RSA_Signature_PKCS1 RSA_Signature_PSS_MD5 RSA_Signature_PSS_SHA1 ``RSA_Signature_PSS_SHA224 RSA_Signature_PSS_SHA256 RSA_Signature_PSS_SHA384 RSA_Signature_PSS_SHA512

Curve25519

EdDSA_Signature

USER_ID

EdDSA_Signature

USER_ID

EdDSA_Signature

USER_ID

EdDSA_Signature

USER_ID

EdDSA_Signature

USER_ID

AES_Encryption_CBC AES_Decryption_CBC

De sleutel kan als volgt worden gegenereerd.

Verplichte rol

Deze operatie vereist een authenticatie met de rol Administrator.

Verplichte opties

Optie

Beschrijving

-p, --port INTEGER

Het type voor de gegenereerde sleutel. Mogelijke waarden voor het argument KEYTYPE staan in de bovenstaande tabel.

-m, --mechanism MECHANISM

De mechanismen voor de gegenereerde sleutel. Mogelijke waarden voor het argument MECHANISM staan in de bovenstaande tabel.

-l, --length INTEGER

De lengte van de gegenereerde sleutel

Optionele opties

Optie

Beschrijving

-k, --key-id TEXT

Het ID van de gegenereerde sleutel

Voorbeeld

$ nitropy nethsm --host $NETHSM_HOST generate-key --type RSA --mechanism RSA_Signature_PSS_SHA256 --mechanism RSA_Decryption_PKCS1 --length 2048 --key-id myFirstKey
Key myFirstKey generated on NetHSM localhost:8443

Import Sleutel#

De NetHSM kan bestaande privésleutels importeren in de Key Store.

De ondersteunde sleuteltypes en hun overeenkomstige mechanismen zijn de volgende.

Type sleutel

Mechanismen

TAG

RSA_Decryption_RAW RSA_Decryption_PKCS1 RSA_Decryption_OAEP_MD5 RSA_Decryption_OAEP_SHA1 RSA_Decryption_OAEP_SHA224 RSA_Decryption_OAEP_SHA256 RSA_Decryption_OAEP_SHA384 RSA_Decryption_OAEP_SHA512 RSA_Signature_PKCS1 RSA_Signature_PSS_MD5 RSA_Signature_PSS_SHA1 ``RSA_Signature_PSS_SHA224 RSA_Signature_PSS_SHA256 RSA_Signature_PSS_SHA384 RSA_Signature_PSS_SHA512

Curve25519

EdDSA_Signature

USER_ID

EdDSA_Signature

USER_ID

EdDSA_Signature

USER_ID

EdDSA_Signature

USER_ID

EdDSA_Signature

USER_ID

AES_Encryption_CBC AES_Decryption_CBC

De invoer kan als volgt worden gestart.

Verplichte rol

Deze operatie vereist een authenticatie met de rol Administrator.

Verplichte opties

Optie

Beschrijving

-p, --port INTEGER

Het type voor de gegenereerde sleutel. Mogelijke waarden voor het argument KEYTYPE staan in de bovenstaande tabel.

-m, --mechanism MECHANISM

De mechanismen voor de gegenereerde sleutel. Mogelijke waarden voor het argument MECHANISM staan in de bovenstaande tabel.

-u, --user-id TEXT

De priem p voor RSA-sleutels

-u, --user-id TEXT

De priem q voor RSA-sleutels

-e, --public-exponent TEXT

De openbare exponent voor RSA-sleutels

-d, --data TEXT

De sleutelgegevens voor ED25519- of ECDSA_*-sleutels

Optionele opties

Optie

Beschrijving

-k, --key-id TEXT

De ID van de nieuwe sleutel

Voorbeeld

$ nitropy nethsm --host $NETHSM_HOST add-key \
   --type RSA \
   --mechanism RSA_Signature_PSS_SHA256 \
   --mechanism RSA_Decryption_PKCS1 \
   --key-id myFirstKey \
   --public-exponent AQAB \
   --prime-p "AOnWFZ+JrI/xOXJU04uYCZOiPVUWd6CSbVseEYrYQYxc7dVroePshz29tc+VEOUP5T0O8lXMEkjFAwjW6C9QTAsPyl6jwyOQluMRIkdN4/7BAg3HAMuGd7VmkGyYrnZWW54sLWp1JD6XJG33kF+9OSar9ETPoVyBgK5punfiUFEL" \
   --prime-q "ANT1kWDdP9hZoFKT49dwdM/S+3ZDnxQa7kZk9p+JKU5RaU9e8pS2GOJljHwkES1FH6CUGeIaUi81tRKe2XZhe/163sEyMcxkaaRbBbTc1v6ZDKILFKKt4eX7LAQfhL/iFlgi6pcyUM8QDrm1QeFgGz11ChM0JuQw1WwkX06lg8iv"
Key myFirstKey added to NetHSM localhost:8443

Delete-toets#

De NetHSM kan sleutels uit de Key Store verwijderen.

Verplichte rol

Deze operatie vereist een authenticatie met de rol Administrator.

Argumenten

Argument

Beschrijving

--time

De sleutel-ID van de te verwijderen sleutel

Voorbeeld

$ nitropy nethsm --host $NETHSM_HOST delete-key myFirstKey
Key myFirstKey deleted on NetHSM localhost:8443

Lijst Sleutels#

De NetHSM kan alle beschikbare sleutels in de Key Store opsommen.

De lijst kan als volgt worden opgevraagd.

Verplichte rol

Deze operatie vereist een authenticatie met de rol Administrator of Operator.

Voorbeeld

$ nitropy nethsm --host $NETHSM_HOST list-keys
Keys on NetHSM localhost:8443:

Key ID          Algorithm       Mechanisms                                      Operations     Tags
-----------     ---------       ----------------------------------------------  ----------  ----
myFirstKey      RSA             RSA_Decryption_PKCS1, RSA_Signature_PSS_SHA256  0

Toon sleutel details#

De NetHSM kan meer gedetailleerde informatie over een opgeslagen sleutel weergeven.

De gedetailleerde informatie kan als volgt worden opgevraagd.

Verplichte rol

Deze operatie vereist een authenticatie met de rol Administrator of Operator.

Voorbeeld

$ nitropy nethsm --host $NETHSM_HOST get-key myFirstKey
Key myFirstKey on NetHSM localhost:8443:
Type:            RSA
Mechanisms:      RSA_Decryption_RAW
Operations:      0
Modulus:         r62XHPWMDdEf2I1WEpSxGowY/fQF8lMPtv3EUQJE/PLWBvehF8G0QY3AVVZ3etlQWiKreOuGDx4Nr2PFNYAu5f+JP2Jc1lsFNOYF8D82RF41MBySbQR+k+44N/04B0ahTBCxX+ovFH7Sd6SzvxMPa7EKvhaOsLbgyrPlFZxQnhIEqJRCSo5DRRD+CRCPpGXsVXgFbJrNilh21i8OZCct4nC2OS191MeDKmCH4tjrfLMwOKJE8zKlwhdtA1uMY49+JuaC48GUFsLYwbLp1723Uv1PjZjC5jbUhScD0u9I+iNrqznAeka4dWsJ9jgA+h6hblSgCs0I3MWOsMXx/Y5PGQ==
Public exponent: AQAB

De openbare sleutel van een sleutel kan als volgt worden opgevraagd.

Verplichte rol

Deze operatie vereist een authenticatie met de rol Administrator of Operator.

Voorbeeld

$ nitropy nethsm --host $NETHSM_HOST get-key myFirstKey --public-key
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAr62XHPWMDdEf2I1WEpSx
GowY/fQF8lMPtv3EUQJE/PLWBvehF8G0QY3AVVZ3etlQWiKreOuGDx4Nr2PFNYAu
5f+JP2Jc1lsFNOYF8D82RF41MBySbQR+k+44N/04B0ahTBCxX+ovFH7Sd6SzvxMP
a7EKvhaOsLbgyrPlFZxQnhIEqJRCSo5DRRD+CRCPpGXsVXgFbJrNilh21i8OZCct
4nC2OS191MeDKmCH4tjrfLMwOKJE8zKlwhdtA1uMY49+JuaC48GUFsLYwbLp1723
Uv1PjZjC5jbUhScD0u9I+iNrqznAeka4dWsJ9jgA+h6hblSgCs0I3MWOsMXx/Y5P
GQIDAQAB
-----END PUBLIC KEY-----

De openbare sleutel kan bijvoorbeeld met OpenSSL als volgt worden geïnspecteerd.

Verplichte rol

Deze operatie vereist een authenticatie met de rol Administrator of Operator.

Voorbeeld

nitropy nethsm --host= $NETHSM_HOST get-key myFirstKey --public-key | openssl rsa -pubin -text
Public-Key: (2048 bit)
Modulus:
   00:af:ad:97:1c:f5:8c:0d:d1:1f:d8:8d:56:12:94:
   b1:1a:8c:18:fd:f4:05:f2:53:0f:b6:fd:c4:51:02:
   44:fc:f2:d6:06:f7:a1:17:c1:b4:41:8d:c0:55:56:
   77:7a:d9:50:5a:22:ab:78:eb:86:0f:1e:0d:af:63:
   c5:35:80:2e:e5:ff:89:3f:62:5c:d6:5b:05:34:e6:
   05:f0:3f:36:44:5e:35:30:1c:92:6d:04:7e:93:ee:
   38:37:fd:38:07:46:a1:4c:10:b1:5f:ea:2f:14:7e:
   d2:77:a4:b3:bf:13:0f:6b:b1:0a:be:16:8e:b0:b6:
   e0:ca:b3:e5:15:9c:50:9e:12:04:a8:94:42:4a:8e:
   43:45:10:fe:09:10:8f:a4:65:ec:55:78:05:6c:9a:
   cd:8a:58:76:d6:2f:0e:64:27:2d:e2:70:b6:39:2d:
   7d:d4:c7:83:2a:60:87:e2:d8:eb:7c:b3:30:38:a2:
   44:f3:32:a5:c2:17:6d:03:5b:8c:63:8f:7e:26:e6:
   82:e3:c1:94:16:c2:d8:c1:b2:e9:d7:bd:b7:52:fd:
   4f:8d:98:c2:e6:36:d4:85:27:03:d2:ef:48:fa:23:
   6b:ab:39:c0:7a:46:b8:75:6b:09:f6:38:00:fa:1e:
   a1:6e:54:a0:0a:cd:08:dc:c5:8e:b0:c5:f1:fd:8e:
   4f:19
Exponent: 65537 (0x10001)
writing RSA key
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAr62XHPWMDdEf2I1WEpSx
GowY/fQF8lMPtv3EUQJE/PLWBvehF8G0QY3AVVZ3etlQWiKreOuGDx4Nr2PFNYAu
5f+JP2Jc1lsFNOYF8D82RF41MBySbQR+k+44N/04B0ahTBCxX+ovFH7Sd6SzvxMP
a7EKvhaOsLbgyrPlFZxQnhIEqJRCSo5DRRD+CRCPpGXsVXgFbJrNilh21i8OZCct
4nC2OS191MeDKmCH4tjrfLMwOKJE8zKlwhdtA1uMY49+JuaC48GUFsLYwbLp1723
Uv1PjZjC5jbUhScD0u9I+iNrqznAeka4dWsJ9jgA+h6hblSgCs0I3MWOsMXx/Y5P
GQIDAQAB
-----END PUBLIC KEY-----

Tags voor sleutels#

Tags kunnen worden gebruikt om de toegang tot sleutels te beperken, en zijn een optionele functie. De Operator gebruikers kunnen alle sleutels zien, maar alleen die met minstens één overeenkomstige Tag gebruiken. Als een sleutel geen Tag heeft, kan hij door alle Operator gebruikers worden gebruikt. Een sleutel kan niet worden gewijzigd door een Operator gebruiker.

Voor meer informatie over het gebruik van Tags op Operator accounts, zie hoofdstuk Tags voor gebruikers.

Notitie

Tags worden zonder beperkingen beheerd door gebruikers met de rol Administrator.

De Tag kan als volgt worden toegevoegd.

Verplichte rol

Deze operatie vereist een authenticatie met de rol Administrator.

Argumenten

Argument

Beschrijving

--time

De sleutel-ID om het label op in te stellen

TAG

De tag die op de sleutel moet worden gezet

Voorbeeld

$ nitropy nethsm --host $NETHSM_HOST add-key-tag myFirstKey berlin
Added tag berlin for key myFirstKey on the NetHSM localhost:8443

De Tag kan als volgt worden verwijderd.

Verplichte rol

Deze operatie vereist een authenticatie met de rol Administrator.

Argumenten

Argument

Beschrijving

--time

De sleutel-ID waarop de tag moet worden ingesteld.

TAG

De tag die op de sleutel moet worden gezet.

Voorbeeld

$ nitropy nethsm --host $NETHSM_HOST delete-key-tag myFirstKey berlin
Deleted tag berlin for key myFirstKey on the NetHSM localhost:8443

Sleutelcertificaten#

Het is mogelijk certificaten voor de op een NetHSM opgeslagen sleutels in te stellen en op te vragen.

De ondersteunde MIME-types zijn als volgt.

  • application/x-pem-file

  • application/x-x509-ca-cert

  • application/pgp-keys

Het certificaat kan als volgt worden ingesteld.

Verplichte rol

Deze operatie vereist een authenticatie met de rol Administrator.

Verplichte opties

Optie

Beschrijving

-k, --key-id TEXT

De ID van de sleutel om het certificaat voor in te stellen

Optionele opties

Optie

Beschrijving

-m, --mechanism MECHANISM

Het MIME-type van het certificaat. De beschikbare MIME-types staan hierboven vermeld.

Argumenten

Argument

Beschrijving

FILENAME

Certificaat bestand

Voorbeeld

$ nitropy nethsm --host $NETHSM_HOST set-certificate --key-id myFirstKey --mime-type application/x-pem-file /tmp/cert.pem
Updated the certificate for key myFirstKey on NetHSM localhost:8443

Het certificaat kan als volgt worden opgehaald.

Verplichte rol

Deze operatie vereist een authenticatie met de rol Administrator of Operator.

Verplichte opties

Optie

Beschrijving

-k, --key-id TEXT

De ID van de sleutel om het certificaat voor te krijgen

Voorbeeld

$ nitropy nethsm --host $NETHSM_HOST get-certificate --key-id myFirstKey
-----BEGIN CERTIFICATE-----
MIICeTCCAWECFCbuzdkAvc3Zx3W53IoSnmhUen42MA0GCSqGSIb3DQEBCwUAMHsx
CzAJBgNVBAYTAkRFMQ8wDQYDVQQIDAZCZXJsaW4xDzANBgNVBAcMBkJlcmxpbjER
MA8GA1UECgwITml0cm9rZXkxFTATBgNVBAMMDG5pdHJva2V5LmNvbTEgMB4GCSqG
SIb3DQEJARYRaW5mb0BuaXRyb2tleS5jb20wHhcNMjIwODMwMjAxMzA2WhcNMjMw
ODMwMjAxMzA2WjBxMW8wCQYDVQQGEwJERTANBgNVBAcMBkJlcmxpbjANBgNVBAgM
BkJlcmxpbjAPBgNVBAoMCE5pdHJva2V5MBMGA1UEAwwMbml0cm9rZXkuY29tMB4G
CSqGSIb3DQEJARYRaW5mb0BuaXRyb2tleS5jb20wKjAFBgMrZXADIQDc58LGDY9B
wbJFdXTiDalNXrDC60Sxu3eHcpnh1MSoCjANBgkqhkiG9w0BAQsFAAOCAQEAGip8
aU5nJnzm3eic3t1ihUA3VJ0mAPyfrb1Rn8tEKOZo3vg0jpRd9CSESlBsKqhvxsdQ
A3eomM+W7R37TL5+ISm5QrbijLHz3OHoPM68c1Krz3bXTkJetf4YAxpLOPYfXXHv
weRzwVJb4y3E0lJGhZxI3sUE8Yn/T1UvTbu/o/O5P/XTA8vfFrSNQkQxWBgYh4gC
KjFFALqUPFrctSFIi34aqpdihNJWnjSS2Y7INm3oxwkR3NMKP8x4wBGfZK22nHnu
PPzXuMGJTmQM8GHTzltNvLx5Iv2sXoSHClXSpdIT5IBIcR1GmZ78fmcr75OAU0+z
3XbJq/1ij3tKsjV6WA==
-----END CERTIFICATE-----

Verzoeken om ondertekening van sleutelcertificaten#

De NetHSM ondersteunt het genereren van CSR (Certificate Signing Requests) voor de opgeslagen sleutels.

Verplichte rol

Deze operatie vereist een authenticatie met de rol Administrator.

Verplichte opties

Optie

Beschrijving

-k, --key-id TEXT

De ID van de sleutel om het CSR voor te genereren

--country TEXT

De naam van het land

--state-or-province TEXT

De naam van de staat of provincie

--locality TEXT

De plaatsnaam

--organization TEXT

De naam van de organisatie

--organizational-unit TEXT

De naam van de organisatie-eenheid

--common-name TEXT

De gemeenschappelijke naam

--email-address TEXT

Het e-mailadres

Voorbeeld

$ nitropy nethsm --host $NETHSM_HOST csr --key-id myFirstKey --country="DE" --state-or-province="Berlin" --locality="Berlin" --organization="Nitrokey" --organizational-unit="" --common-name=nitrokey.com --email-address="info@nitrokey.com"
-----BEGIN CERTIFICATE REQUEST-----
MIHxMIGkAgEAMHExbzAJBgNVBAYTAkRFMA0GA1UEBwwGQmVybGluMA0GA1UECAwG
QmVybGluMA8GA1UECgwITml0cm9rZXkwEwYDVQQDDAxuaXRyb2tleS5jb20wHgYJ
KoZIhvcNAQkBFhFpbmZvQG5pdHJva2V5LmNvbTAqMAUGAytlcAMhADJMNAifke6s
u7CYqHGDy3xGtXVOUNbTJG6Gn4oki+j3oAAwBQYDK2VwA0EAQilRK2Mf6kfJ4ByI
WCn9A+8IHsnE7iFcuFZpmaKfcJwZiaQppHvPg/Z0zqldzviPQ1cjKR7hSZG+8GHH
gWjEDg==
-----END CERTIFICATE REQUEST-----

Belangrijkste operaties#

Versleutel#

De NetHSM kan geen gegevens versleutelen, maar levert de openbare sleutel die voor versleuteling kan worden gebruikt. Om te leren hoe de openbare sleutel kan worden opgehaald, zie hoofdstuk Show Key Details.

Gegevens kunnen als volgt worden gecodeerd met OpenSSL.

$ echo 'NetHSM rulez!' | openssl pkeyutl -encrypt -pubin -inkey public.pem | base64 > data.crypt

Dit schrijft het versleutelde en base64-gecodeerde bericht NetHSM rulez! in het bestand data.crypt.

Ontcijfer#

De NetHSM kan gegevens decoderen voor een privésleutel die is opgeslagen in de Key Store op de NetHSM. Dit voorbeeld gebruikt het versleutelde bericht uit het vorige hoofdstuk Encrypt.

De ondersteunde decryptiemodi zijn als volgt.

  • TAG

  • PKCS1

  • FILENAME

  • --network

  • OAEP_SHA224

  • OAEP_SHA224

  • OAEP_SHA224

  • OAEP_SHA224

  • USER_ID

De gegevens kunnen als volgt worden ontcijferd.

Verplichte rol

Deze operatie vereist een authenticatie met de rol Operator.

Verplichte opties

Optie

Beschrijving

-k, --key-id TEXT

De ID van de sleutel om de gegevensbreedte te decoderen

-d, --data TEXT

De gecodeerde gegevens in Base64-codering

-d, --data TEXT

De decryptiemodus. De beschikbare modi staan hierboven vermeld.

Voorbeeld

$ nitropy nethsm -h $NETHSM_HOST decrypt -k myFirstKey -d "$(cat data.crypt)" -m PKCS1 | base64 -d
NetHSM rulez!

Teken#

De NetHSM kan gegevens ondertekenen voor een private sleutel die is opgeslagen in de Key Store op de NetHSM. Voor handtekeningen met een RSA- en ECDSA-sleutel moet eerst een digest worden berekend.

Om een digest te berekenen zijn eerst de gegevens nodig. Een bericht wordt als volgt aangemaakt.

$ echo 'NetHSM rulez!' > data

De digest wordt met OpenSSL als volgt berekend.

$ openssl dgst -sha256 -binary data | base64 > data.digest

De ondersteunde ondertekeningsmodi zijn als volgt.

  • PKCS1

  • USER_ID

  • FILENAME

  • Curve25519

  • Curve25519

  • Curve25519

  • Curve25519

  • PKCS1

  • PKCS1

Uit de digest kan als volgt een handtekening worden gemaakt.

Verplichte rol

Deze operatie vereist een authenticatie met de rol Operator.

Verplichte opties

Optie

Beschrijving

-k, --key-id TEXT

De ID van de sleutel om de gegevensbreedte te ondertekenen

-d, --data TEXT

De te ondertekenen gegevens gecodeerd met Base64

-d, --data TEXT

De tekenmodus

Voorbeeld

$ nitropy nethsm -h $NETHSM_HOST sign -k myFirstKey -m PKCS1 -d "$(cat data.digest)" | base64 -d > data.sig

De aangemaakte handtekening kan als volgt worden geverifieerd met OpenSSL.

$ openssl dgst -sha256 -verify public.pem -signature data.sig -sigopt rsa_padding_mode:pss -sigopt rsa_pss_saltlen:-1 data
Verified OK

Willekeurige#

De NetHSM kan willekeurige bytes leveren als een Base64-string.

Verplichte rol

Deze operatie vereist een authenticatie met de rol Operator.

Argumenten

Argument

Beschrijving

--time

Op te halen bytes

Voorbeeld

nitropy nethsm --host $NETHSM_HOST random 4
94A2rg==