Esecuzione di operazioni crittografiche con l'API PKCS #11

IBM Cloud® Hyper Protect Crypto Services fornisce l'API PKCS #11 standard per accedere all'HSM cloud Hyper Protect Crypto Services per le operazioni crittografiche.

Prerequisiti

Prima di poter impostare e utilizzare l'API PKCS #11 , seguire le Procedure ottimali per configurare i tipi di utenti PKCS #11 per creare chiavi API ID servizio differenti per i diversi tipi di utenti PKCS #11 .

Passo 1: configurare la libreria PKCS #11

È necessario impostare la libreria PKCS #11 sulla stazione di lavoro per renderla disponibile per le applicazioni per richiamare le funzioni PKCS #11 standard.

La libreria PKCS #11 , sia per le piattaforme amd64 che s390x, è supportata solo su Linux.

Se si sta eseguendo un'applicazione Java PKCS #11 utilizzando il provider SunPKCS11 sulla piattaforma IBM Z (s390x), assicurarsi di utilizzare la JVM IBM Semeru più recente e specificare l'opzione -Xjit:noResumableTrapHandler Java quando si avvia l'applicazione. Puoi scaricare la versione s390x più recente di IBM Semeru JVM modificando il campo del filtro Architettura in s390x nella pagina IBM Semeru Runtime Downloads.

  1. Scarica la libreria PKCS #11 più aggiornata. I nomi file della libreria utilizzano la convenzione di denominazione: pkcs11-grep11-<platform>.so.<version>. La piattaforma è amd64 o s390x e la versione è la sintassi standard major.minor.build.
  2. Spostare la libreria in una cartella accessibile dalle applicazioni. Ad esempio, se si sta eseguendo l'applicazione su Linux, è possibile spostare la libreria in /usr/local/lib, /usr/local/lib64 o /usr/lib.

Fase 2: (Facoltativo) Verifica dell'integrità e dell'autenticità della libreria PKCS #11

Per una maggiore sicurezza, verificare l'integrità e l'autenticità della libreria PKCS #11 prima di eseguire le proprie applicazioni PKCS #11 per utilizzare la libreria.

Hyper Protect Crypto Services abilita la verifica codice firmato per garantire che la firma corrisponda al codice originale. Se il file della libreria PKCS #11 scaricato viene modificato o danneggiato, viene prodotta una firma differente e la verifica ha esito negativo. Per assicurarsi che i file non siano alterati o danneggiati durante il processo di download, completare la seguente procedura utilizzando lo strumento della riga comandiOpenSSL.

  1. Scaricare l'ultima versione dei seguenti file dal repository della libreria nella stessa directory in cui si memorizza la libreria PKCS #11 :

    • pkcs11-grep11-<platform>.so.<version>.sig: l'hash crittografico firmato della libreria PKCS #11 , dove la piattaforma è amd64 o s390x e la versione è major.minor.build del file di firma. Sia la piattaforma che la versione **devono corrispondere alla rispettiva piattaforma**e alla** versione** della libreria PKCS #11 utilizzata.

    • signing_cert.pem: il certificato di firma dei file client Hyper Protect Crypto Services PKCS #11 .

    • digicert_cert.pem: un certificato di firma del codice intermedio per provare il certificato di firma dei file client Hyper Protect Crypto Services PKCS #11 .

  2. Estrarre la chiave pubblica dal certificato di firma signing_cert.pem nel file sigkey.pub con il seguente comando:

    openssl x509 -pubkey -noout -in signing_cert.pem -out sigkey.pub

  3. Verificare l'integrità del file della libreria PKCS #11 con il seguente comando:

    openssl dgst -sha256 -verify sigkey.pub -signature pkcs11-grep11-<platform>.so.<version>.sig pkcs11-grep11-<platform>.so.<version>

    Sostituisci platform con amd64 o s390x e sostituisci version con major.minor.build della libreria.

    Quando la verifica ha esito positivo, viene visualizzato Verified OK.

  4. Verificare l'autenticità e la validità del certificato di firma con il seguente comando:

    openssl ocsp -no_nonce -issuer digicert_cert.pem -cert signing_cert.pem -VAfile digicert_cert.pem -text -url http://ocsp.digicert.com -respout ocsptest

    Quando la verifica ha esito positivo, vengono visualizzati Response verify OK e signing_cert.pem: good nell'output.

  5. Se la verifica non riesce, annullare l'installazione e contattare IBM per assistenza.

Passo 3: Impostazione del file di configurazione PKCS #11

Per collegare la libreria PKCS #11 all'HSM cloud Hyper Protect Crypto Services per eseguire le funzioni crittografiche, devi completare la seguente procedura per configurare il file di configurazione.

  1. Creare un file di configurazione denominato grep11client.yaml basato sul seguente esempio. Il repository di librerie fornisce anche un modello da adattare. È possibile fare riferimento ai commenti nel codice per comprendere ogni campo.

    iamcredentialtemplate: &defaultiamcredential
  enabled: true
  endpoint: "https://iam.cloud.ibm.com"

sessionauthtemplate: &defaultsessionauth
  enabled: false
  tokenspaceIDPassword:  # Authenticated keystore password 6-8 characters in length

tokens:
  0:
    grep11connection:
      # The EP11 endpoint address starting from 'ep11'. For example: "<instance_ID>.ep11.us-south.hs-crypto.appdomain.cloud"
      address: "<EP11_endpoint_URL>"
      port: "<EP11_endpoint_port_number>" # The EP11 endpoint port number
      tls:
        enabled: true # EP11 requires TLS connection.
        # Set it 'true' if you want to enable mutual TLS connections.
        # By default, set it 'false' because EP11 requires server-only authentication.
        mutual: <enable_mtls>
        # 'cacert' is a full-path certificate file. In Linux with the 'ca-ca-certificates' package installed, this is normally not needed.
        cacert:
        # Specify the file path of the client certificate if you enable mutual TLS. Otherwise, keep it empty.
        certfile: <client_certificate>
        # Specify the file path of the client certificate private key if you enable mutual TLS. Otherwise, keep it empty.
        keyfile: <client_certificate_private_key>
    storage:
        # 'remotestore' needs to be enabled if you want to generate keys with the attribute CKA_TOKEN.
      remotestore:
        enabled: true
    users:
      0: # The index of the Security Officer (SO) user MUST be 0.
        # The name for the Security Officer (SO) user. For example: "Administrator".
        name: "<SO_user_name>"
        iamauth: *defaultiamcredential
      1: # The index of the normal user MUST be 1.
        # The name for the normal user. For example: "Normal user".
        name: "<normal_user_name>"
        # The 128-bit UUID of the private keystore. For example: "f00db2f1-4421-4032-a505-465bedfa845b".
        tokenspaceID: "<private_keystore_spaceid>"
        iamauth: *defaultiamcredential
        # Do not override the defaultsessionauth template
        # The same values must be used for both the private (normal user) and public (anonymous) keystores
        sessionauth: *defaultsessionauth
      2: # The index of the anonymous user MUST be 2.
        # The name for the anonymous user. For example: "Anonymous".
        name: "<anonymous_user_name>"
        # The 128-bit UUID of the public keystore. For example: "ca22be26-b798-4fdf-8c83-3e3a492dc215".
        tokenspaceID: "<public_keystore_spaceid>"
        iamauth:
          <<: *defaultiamcredential
          # The API key for the anonymous user. All other users can specify API key using the C_Login command.
          apikey: "<apikey_for_anonymous_user>"
        # Do not override the defaultsessionauth template
        # The same values must be used for both the private (normal user) and public (anonymous) keystores
        sessionauth: *defaultsessionauth

logging:
  # Set the logging level.
  # The supported levels, in an increasing order of verboseness: 'panic', 'fatal', 'error', 'warning'/'warn', 'info', 'debug', 'trace'. The Default value is 'warning'.
  loglevel: "<logging_level>"
  logpath: "<log_file_path>" # The full path of your logging file.

    Se vengono utilizzati keystore autenticati, l'opzione di configurazione sessionauth deve essere abilitata per entrambi i keystore e le password di testo con una lunghezza compresa tra 6 e 8 caratteri devono essere identiche per entrambi i keystore nel campo tokenspaceIDPassword.

    Sostituisci le variabili nell'esempio secondo la seguente tabella:

    Se crei le tue istanze dopo il 12 aprile 2024 in alcune regioni, potresti dover utilizzare i nuovi endpoint API con il nuovo formato come <instance_ID>.ep11.<REGION>.hs-crypto.appdomain.cloud. La data di disponibilità varia in base alla regione. Per ulteriori informazioni sulle regioni supportate, sulle date di disponibilità e sui nuovi URL degli endpoint, vedere Nuovi endpoint.

    Tabella 1. Descrive le variabili necessarie per la creazione del file di configurazione PKCS #11
    Variabile Descrizione
    EP11_endpoint_URL L'endpoint API Hyper Protect Crypto Services Enterprise PKCS #11 (EP11). Puoi ottenerlo tramite Overview > Connect > EP11 endpoint URL nell'interfaccia utente oppure puoi dinamicamente richiamare l'URL dell'endpoint con l'API. A seconda se stai utilizzando una rete pubblica o privata, utilizza l'URL dell'endpoint EP11 pubblico o privato.
    EP11_endpoint_port_number Il numero di porta dell'endpoint API EP11. Si trova dopo i due punti nell'URL dell'endpoint.
    enable_mtls I valori validi sono true o false per specificare se si desidera abilitare il TLS reciproco per aggiungere un secondo livello di autenticazione per l'accesso API PKCS #11 per il piano standard Hyper Protect Crypto Services. Per impostazione predefinita, false come EP11 richiede l'autenticazione solo server. Per ulteriori informazioni sulle connessioni TLS reciproche, vedi Abilitazione del secondo livello di autenticazione per le connessioni EP11.
    client_certificate Se si abilitano le connessioni TLS reciproche, specificare il percorso file del certificato client caricato sull'istanza dall'amministratore del certificato. Altrimenti, lasciare vuoto questo campo.
    client_certificate_private_key Se si abilitano le connessioni TLS reciproche, specificare il percorso file della chiave privata del certificato client utilizzata per firmare il certificato. Altrimenti, lasciare vuoto questo campo.
    SO_user_name Il nome per il tipo di utente SO (Security Officer). Lo standard PKCS #11 definisce due tipi di utenti per il login: il responsabile della sicurezza (SO) e l'utente normale. Per ulteriori informazioni sui tipi di utente PKCS #11 , consultare PKCS #11 Cryptographic Token Interface Usage Guide Version 2.40- Users.
    normal_user_name Il nome per il tipo di utente normale. Lo standard PKCS #11 definisce due tipi di utenti per il login: il responsabile della sicurezza (SO) e l'utente normale. Per ulteriori informazioni sui tipi di utente PKCS #11 , consultare PKCS #11 Cryptographic Token Interface Usage Guide Version 2.40- Users.
    private_keystore_spaceid L' UID(Universally Unique IDentifier) a 128 bit del keystore privato. Puoi generare l'UUID con uno strumento di terze parti, come il generatore UUID.

    Hyper Protect Crypto Services ti fornisce due keystore EP11 supportati dal database per una maggiore sicurezza e una migliore gestione dell'accesso utente: il keystore privato a cui può accedere solo il normale tipo di utente e il keystore pubblico a cui possono accedere tutti i tipi di utente. L'UUID deve essere diverso dall'UUID specificato per il parametro public_keystore_spaceid.
    private_keystore_password Le sessioni autorizzate possono essere utilizzate abilitando l'opzione di configurazione sessionauth. Se l'opzione sessionauth è abilitata, deve essere abilitata per entrambi i keystore. Inoltre, una password di testo con una lunghezza compresa tra 6 e 8 caratteri è richiesta per il campo tokenspaceIDPassword e la parola d'ordine deve essere identica per entrambi i keystore. Le sessioni autorizzate sono specifiche di HSM e vengono utilizzate nel flusso PKCS #11 per l'accesso e lo scollegamento e sono richieste per le operazioni di chiavi autenticate. Tutte le chiavi generate utilizzando le sessioni autorizzate vengono memorizzate in un keystore autenticato e codificato. Il campo tokenspaceIDPassword viene utilizzato per proteggere le chiavi in un keystore autenticato e codificato. Per ogni istanza del servizio sono supportati un massimo di cinque keystore autenticati.
    anonymous_user_name Il nome dell'utente anonimo. Lo standard PKCS #11 definisce due tipi di utenti per il login: il responsabile della sicurezza (SO) e l'utente normale. Se un utente non accede utilizzando la funzione C_Login Cryptoki, l'utente è noto come utente anonimo. Per ulteriori informazioni sui tipi di utente PKCS #11 , consultare PKCS #11 Cryptographic Token Interface Usage Guide Version 2.40- Users.
    public_keystore_spaceid L' UUID(Universally Unique IDentifier) a 128 bit del keystore pubblico. Puoi generare l'UUID con uno strumento di terze parti, come il generatore UUID.

    Hyper Protect Crypto Services ti fornisce due keystore EP11 supportati dal database per una maggiore sicurezza e una migliore gestione dell'accesso utente: il keystore privato a cui può accedere solo il normale tipo di utente e il keystore pubblico a cui possono accedere tutti i tipi di utente. L'UUID deve essere diverso dall'UUID specificato per il parametro private_keystore_spaceid.

    Importante: il valore della stringa UUID deve essere uguale alla stringa UID utilizzata per impostare le politiche di accesso per l'utente anonimo. Vedere creazione della politica di accesso utente anonimo.
    apikey_for_anonymous_user La chiave API dell'ID servizio che crei per il tipo di utente anonimo nel passo dei prerequisiti precedente.
    logging_level I livelli di registrazione supportati, in un ordine crescente di verboseness: panic, fatal, error, warning/warn, info, debug e trace. Il valore predefinito è warning.
    log_file_path Il percorso completo del file di registrazione. Salva tutti i log generati quando le tue applicazioni interagiscono con l'HSM cloud Hyper Protect Crypto Services per eseguire funzioni PKCS #11 .

    Per codificare e autenticare il keystore utilizzato da PKCS #11, abilitare il parametro sessionauth e configurare la password per il keystore. Per ogni istanza del servizio sono supportati un massimo di cinque keystore autenticati. La password può contenere da 6 a 8 caratteri. Le password del keystore non sono memorizzate nell'istanza del servizio. L'amministratore del keystore è responsabile della gestione di una copia locale delle password. Se una password viene persa, è necessario contattare il supporto IBM per reimpostare il keystore, il che significa che tutti i dati nel keystore vengono cancellati.

  2. Spostare il file di configurazione nella directory /etc/ep11client. Crea il /etc/ep11client directory se non esiste. In alternativa, è possibile impostare la variabile di ambiente EP11CLIENT_CFG sul percorso completo e sul nome file del file di configurazione. In questo modo, non sarai limitato al grep11client nome del file yaml. Esempio: export EP11CLIENT_CFG=/home/user/pkcs11-config.yaml

Passo 4: utilizza la libreria PKCS #11 per effettuare chiamate API PKCS #11

Dopo aver impostato la libreria e il file di configurazione, i keystore devono essere inizializzati. Per inizializzare i keystore, l'utente SO (security officer) deve eseguire un'operazione C_InitToken.

Dopo l'inizializzazione dei keystore, utilizzare la libreria PKCS #11 per richiamare le funzioni PKCS #11 standard per generare, memorizzare ed elencare le chiavi. Per un elenco dettagliato delle funzioni PKCS #11 supportate, consultare PKCS #11 API reference.

A seconda delle funzioni e dei requisiti di sicurezza della tua applicazione, passa diverse chiavi API dell'ID servizio che hai creato nel passo dei prerequisiti precedenti in modo che le tue applicazioni possano eseguire le corrispondenti operazioni. Ad esempio, se l'applicazione deve eliminare un keystore, fornire la chiave API dell'utente SO. Se la tua applicazione ha bisogno di accedere al keystore privato per memorizzare nuove chiavi, devi fornire la chiave API utente normale. Per ulteriori informazioni sulla gestione dell'accesso utente per l'API PKCS #11 , vedi Procedure ottimali per configurare i tipi di utente PKCS #11.

Se si sta eseguendo un'applicazione Java PKCS #11 utilizzando il provider SunPKCS11 sulla piattaforma IBM Z (s390x), assicurarsi di utilizzare la JVM IBM Semeru più recente e specificare l'opzione -Xjit:noResumableTrapHandler Java quando si avvia l'applicazione. Puoi scaricare la versione s390x più recente di IBM Semeru JVM modificando il campo del filtro Architettura in s390x nella pagina IBM Semeru Runtime Downloads.

Operazioni successive