Integrazione#

Il capitolo descrive i processi per i vari compiti e si rivolge a tutti i gruppi di utenti.

Driver PKCS#11#

Importante

Questo driver è ancora una prima implementazione Proof of Concept che implementa solo le funzioni necessarie per il funzionamento dei server TLS, come ad esempio un server HTTPS.

  1. Scarica il driver PKCS#11 per NetHSM.

  2. Modificate il file di configurazione p11nethsm.conf secondo la vostra configurazione (es. indirizzo, nome dell’operatore) e memorizzarlo in $HOME/.nitrokey, /etc/nitrokey/, o nella cartella dove viene eseguita la vostra applicazione.

Crittografia e decrittografia#

Dopo aver creato una chiave (qui: ID 42) con il meccanismo corrispondente, è possibile utilizzarla per la crittografia e la decrittografia, ma prima è necessario creare la chiave:

$ KEYID=42
$ HEXID=$(echo ${KEYID}'\c' | xxd -ps)
$ curl -s -X GET https://nethsmdemo.nitrokey.com/api/v1/keys/$KEYID/public.pem -o public.pem

Ora è possibile crittografare:

$ 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

E decifrare:

$ pkcs11-tool --module p11nethsm.so -v --decrypt --mechanism RSA-PKCS-OAEP --input-file encrypted.data --id $HEXID --hash-algorithm SHA512

Firma#

Per prima cosa creare nuovamente la chiave:

$ KEYID=23
$ HEXID=$(echo ${KEYID}'\c' | xxd -ps)
$ curl -s -X GET https://nethsmdemo.nitrokey.com/api/v1/keys/$KEYID/public.pem -o public.pem

Dopo aver creato una chiave (in questo caso: ID 23) con il meccanismo corrispondente, è possibile utilizzarla per la firma:

$ echo 'NetHSM rulez!' | pkcs11-tool --module p11nethsm.so -v --sign --mechanism SHA512-RSA-PKCS-PSS --output-file sig.data --id $HEXID
$ echo 'NetHSM rulez!' | openssl dgst -keyform PEM -verify public.pem -sha512 -sigopt rsa_padding_mode:pss -sigopt rsa_pss_saltlen:-1 -signature sig.data

Sviluppo e test#

Un’istanza demo pubblica di NetHSM è disponibile su nethsmdemo.nitrokey.com.

In alternativa potete eseguire il contenitore Docker NetHSM localmente. Il contenitore NetHSM richiede una virtualizzazione annidata per una forte separazione con altri contenitori. Quindi, per avviare un contenitore NetHSM hai bisogno di un host Linux con /dev/kvm disponibile. Esegui questo comando:

$ sudo docker run --rm -ti --device=/dev/net/tun:/dev/net/tun --cap-add=NET_ADMIN -p8443:8443 nitrokey/nethsm:testing

Integrazione all’applicazione personalizzata#

Per integrare NetHSM nelle proprie applicazioni personalizzate, sono disponibili librerie client per quasi tutti i linguaggi di programmazione. Pertanto, si consiglia di utilizzare ` OpenAPI Generator <https://github.com/OpenAPITools/openapi-generator>`_.

L’elenco di tutte le lingue disponibili può essere recuperato come segue.

$ docker run --pull --rm -ti openapitools/openapi-generator-cli list -i stable

Il client NetHSM può essere generato per il vostro linguaggio di programmazione come segue.

$ docker run --rm -ti -v "${PWD}/out:/out" openapitools/openapi-generator-cli generate -i=https://nethsmdemo.nitrokey.com/api_docs/nethsm-api.yaml -o out -g javascript

Il codice client generato, in questo esempio JavaScript, sarà creato nella cartella ./out/. Questa cartella contiene anche la documentazione necessaria al suo utilizzo.

REST-API#

Le specifiche API di NetHSM’sono disponibili nel formato OpenAPI e possono essere ispezionate e testate nel browser API.