Creazione di archivi chiavi e truststore mediante l'UI Edge

Stai visualizzando la documentazione di Apigee Edge.
Consulta la documentazione di Apigee X. info

Questo documento descrive come creare, modificare ed eliminare keystore e truststore per Edge per il cloud e per Edge per Private Cloud versioni 4.18.01 e successive.

Informazioni su keystore/truststore e host virtuali per Edge Cloud

La procedura di creazione di keystore/truststore per Edge Cloud richiede di seguire tutte le regole sull'utilizzo degli host virtuali. Ad esempio, con gli host virtuali nel cloud:

• Gli host virtuali devono utilizzare TLS.
• Gli host virtuali possono utilizzare solo la porta 443.
• Devi utilizzare un certificato TLS firmato. I certificati non firmati non sono consentiti per l'utilizzo con gli host virtuali nel cloud.
• Il nome di dominio specificato dal certificato TLS deve corrispondere all'alias host dell'host virtuale.

Scopri di più:

• Informazioni su TLS/SSL
• Utilizzo di TLS con Edge
• Domande frequenti sulla configurazione degli host virtuali
• Informazioni sugli host virtuali

Implementazione di keystore e truststore in Edge

Per configurare funzionalità che si basano sull'infrastruttura a chiave pubblica, come TLS, devi creare keystore e truststore che contengano le chiavi e i certificati digitali necessari.

In Edge, i keystore e i truststore sono entrambi rappresentati da un'entità keystore che contiene uno o più alias. ovvero non esiste alcuna differenza di implementazione tra un keystore e un truststore su Edge.

La differenza tra keystore e truststore deriva dai tipi di voci che contengono e dal modo in cui vengono utilizzati nell'handshake TLS:

• archivio chiavi: un'entità archivio chiavi che contiene uno o più alias, dove ogni alias contiene una coppia certificato/chiave.
• truststore: un'entità keystore che contiene uno o più alias, dove ogni alias contiene solo un certificato.

Quando configuri TLS per un host virtuale o un endpoint di destinazione, i keystore e i truststore svolgono ruoli diversi nel processo di handshake TLS. Quando configuri un host virtuale o un endpoint di destinazione, devi specificare i keystore e i truststore separatamente nel tag <SSLInfo>, come mostrato di seguito per un host virtuale:

<VirtualHost name="myTLSVHost"> 
    <HostAliases> 
        <HostAlias>apiTLS.myCompany.com</HostAlias> 
    </HostAliases> 
    <Interfaces/> 
    <Port>9006</Port> 
    <SSLInfo> 
        <Enabled>true</Enabled> 
        <ClientAuthEnabled>false</ClientAuthEnabled> 
        <KeyStore>ref://keystoreref</KeyStore> 
        <KeyAlias>myKeyAlias</KeyAlias> 
    </SSLInfo>
</VirtualHost>

In questo esempio, specifichi il nome del keystore e l'alias utilizzato dall'host virtuale per il keystore TLS. Utilizzi un riferimento per specificare il nome del keystore in modo da poterlo modificare in un secondo momento quando il certificato scade. L'alias contiene una coppia certificato/chiave utilizzata per identificare l'host virtuale a un client TLS che accede all'host virtuale. In questo esempio, non è richiesto alcun truststore.

Se è necessario un truststore, ad esempio per una configurazione TLS bidirezionale, utilizza il tag <TrustStore> per specificare il truststore:

<VirtualHost name="myTLSVHost"> 
    <HostAliases> 
        <HostAlias>apiTLS.myCompany.com</HostAlias> 
    </HostAliases> 
    <Interfaces/> 
    <Port>9006</Port> 
    <SSLInfo> 
        <Enabled>true</Enabled> 
        <ClientAuthEnabled>true</ClientAuthEnabled> 
        <KeyStore>ref://keystoreref</KeyStore> 
        <KeyAlias>myKeyAlias</KeyAlias> 
        <TrustStore>ref://truststoreref</TrustStore>
    </SSLInfo>
</VirtualHost>

In questo esempio, il tag <TrustStore> fa riferimento solo a un keystore e non specifica un alias specifico. Ogni alias nel keystore contiene un certificato o una catena di certificati che viene utilizzato nell'ambito della procedura di handshake TLS.

Formati di certificato supportati

* Se possibile, ti consigliamo di utilizzare PEM.

Utilizzo di keystore PKCS12 con Edge for Private Cloud 4.53.00 o versioni successive

Se utilizzi Edge for Private Cloud 4.53.00 o versioni successive, devi utilizzare solo un keystore PKCS12 per caricare le chiavi e i certificati correlati su Apigee. Per assistenza con la conversione delle chiavi e dei certificati esistenti nel formato PKCS12/PFX, consulta l'articolo Conversione dei certificati nel formato supportato.

Informazioni sull'implementazione di un alias

Su Edge, un archivio chiavi contiene uno o più alias, dove ogni alias contiene:

• Certificato TLS come file PEM o PKCS12/PFX: un certificato firmato da un'autorità di certificazione (CA), un file contenente una catena di certificati in cui l'ultimo certificato è firmato da una CA o un certificato autofirmato.
• Chiave privata come file PEM o PKCS12/PFX. Edge supporta dimensioni delle chiavi fino a 2048 bit. Una passphrase è facoltativa.

Su Edge, un truststore contiene uno o più alias, dove ogni alias contiene:

• Certificato TLS come file PEM: un certificato firmato da un'autorità di certificazione (CA), una catena di certificati in cui l'ultimo certificato è firmato da una CA o un certificato autofirmato.

Edge fornisce una UI e un'API che utilizzi per creare keystore, creare alias, caricare coppie di certificati/chiavi e aggiornare i certificati. La UI e l'API che utilizzi per creare un truststore sono le stesse che utilizzi per creare un keystore. La differenza è che quando crei un truststore, crei alias che contengono solo un certificato.

Informazioni sul formato dei file cert e key

Puoi rappresentare i certificati e le chiavi come file PEM o PKCS12/PFX. I file PEM sono conformi al formato X.509. Se il certificato o la chiave privata non sono definiti da un file PEM, puoi convertirli in un file PEM utilizzando utilità come openssl.

Tuttavia, molti file .crt e .key sono già in formato PEM. Se questi file sono file di testo e sono racchiusi in:

-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----

oppure:

-----BEGIN ENCRYPTED PRIVATE KEY-----
-----END ENCRYPTED PRIVATE KEY-----

In questo modo, i file sono compatibili con il formato PEM e puoi utilizzarli in un keystore o truststore senza convertirli in un file PEM.

Informazioni sulle catene di certificati

Se un certificato fa parte di una catena, la gestione varia a seconda che venga utilizzato in un keystore o in un truststore:

• Keystore: se un certificato fa parte di una catena, devi creare un unico file contenente tutti i certificati della catena. I certificati devono essere in ordine e l'ultimo deve essere un certificato radice o un certificato intermedio firmato da un certificato radice.
• Truststore: se un certificato fa parte di una catena, devi creare un unico file contenente tutti i certificati e caricarlo in un alias oppure caricare tutti i certificati della catena separatamente nel truststore utilizzando un alias diverso per ogni certificato. Se li carichi come un unico certificato, i certificati devono essere in ordine e l'ultimo deve essere un certificato radice o un certificato intermedio firmato da un certificato radice.
• Se crei un unico file contenente più certificati, devi inserire una riga vuota tra ogni certificato.

Ad esempio, puoi combinare tutti i certificati in un unico file PEM. I certificati devono essere in ordine e l'ultimo deve essere un certificato radice o un certificato intermedio firmato da un certificato radice:

-----BEGIN CERTIFICATE----- 
(Your Primary TLS certificate) 
-----END CERTIFICATE----- 

-----BEGIN CERTIFICATE----- 
(Intermediate certificate) 
-----END CERTIFICATE-----
 
-----BEGIN CERTIFICATE----- 
(Root certificate or intermediate certificate signed by a root certificate) 
-----END CERTIFICATE-----

Se i certificati sono rappresentati come file PKCS12/PFX, puoi utilizzare il comando openssl per creare un file PKCS12/PFX dalla catena di certificati, come mostrato di seguito:

openssl pkcs12 -export -out certificate.pfx -inkey privateKey.key -in certificate.crt -certfile CACert.crt

Quando lavori con le catene di certificati in un truststore, non devi sempre caricare tutti i certificati della catena. Ad esempio, carichi un certificato client, client_cert_1, e il certificato dell'emittente del certificato client, ca_cert.

Durante l'autenticazione TLS bidirezionale, l'autenticazione client ha esito positivo quando il server invia client_cert_1 al client nell'ambito della procedura di handshake TLS.

In alternativa, hai un secondo certificato, client_cert_2, firmato dallo stesso certificato, ca_cert. Tuttavia, non carichi client_cert_2 nel truststore. Il truststore contiene ancora solo client_cert_1 e ca_cert.

Quando il server trasmette client_cert_2 nell'ambito dell'handshake TLS, la richiesta va a buon fine. Questo perché Edge consente la verifica TLS quando client_cert_2 non esiste nell'archivio attendibile, ma è stato firmato da un certificato presente nell'archivio attendibile. Se rimuovi il certificato CA, ca_cert, dal truststore, la verifica TLS non riesce.

Considerazioni relative a FIPS

Se utilizzi Edge for Private Cloud 4.53.00 o versioni successive su un sistema operativo abilitato per FIPS, devi utilizzare solo un keystore PKCS12 per caricare le chiavi e i certificati correlati su Apigee.

Esplorare la pagina Archivi chiavi TLS

Viene visualizzata la pagina Archivi chiavi TLS:

Come evidenziato nella figura precedente, la pagina TLS Keystores ti consente di:

• Seleziona un ambiente
• Creare un archivio chiavi e un alias
• Test ed elimina i keystore
• Visualizza ed elimina gli alias

Visualizzare un alias

Per visualizzare un alias:

1. Accedi alla pagina TLS Keystores.
2. Seleziona l'ambiente (in genere prod o test).
3. Fai clic sulla riga associata all'alias che vuoi visualizzare.

   Vengono visualizzati i dettagli del certificato e della chiave dell'alias.
   
   Puoi visualizzare tutte le informazioni sull'alias, inclusa la data di scadenza.

4. Gestisci il certificato utilizzando i pulsanti nella parte superiore della pagina per:
   • Scarica il certificato come file PEM.
   • Genera una CSR. Se hai un certificato scaduto e vuoi rinnovarlo, puoi scaricare una richiesta di firma del certificato (CSR). A questo punto, invia la richiesta CSR alla tua CA per ottenere un nuovo certificato.
   • Aggiorna un certificato. Attenzione: se aggiorni un certificato attualmente utilizzato da un host virtuale o da un server di destinazione/endpoint di destinazione, devi contattare l'assistenza Apigee Edge per riavviare i router e i processori di messaggi. Il modo consigliato per aggiornare un certificato è:
     1. Crea un nuovo keystore o truststore.
     2. Aggiungi il nuovo certificato al nuovo keystore o truststore.
     3. Aggiorna il riferimento nell'host virtuale o nel server di destinazione/endpoint di destinazione al keystore o truststore. Per saperne di più, consulta Aggiornare un certificato TLS per Cloud.
     4. Elimina l'alias. Nota: se elimini un alias e questo viene attualmente utilizzato da un host virtuale o da un endpoint di destinazione, l'host virtuale o l'endpoint di destinazione non funzionerà.

Creare un archivio chiavi/archivio attendibile e un alias

Puoi creare un keystore da utilizzare come keystore TLS o truststore TLS. Un keystore è specifico per un ambiente della tua organizzazione, ad esempio l'ambiente di test o di produzione. Pertanto, se vuoi testare il keystore in un ambiente di test prima di eseguirne il deployment nell'ambiente di produzione, devi crearlo in entrambi gli ambienti.

Per creare un keystore in un ambiente, devi solo specificare il nome del keystore. Dopo aver creato un keystore denominato in un ambiente, puoi creare alias e caricare una coppia certificato/chiave (keystore) o caricare solo un certificato (truststore) nell'alias.

Per creare un keystore:

1. Accedi alla pagina TLS Keystores.
2. Seleziona l'ambiente (in genere prod o test).
3. Fai clic su + Keystore.
4. Specifica il nome del keystore. Il nome può contenere solo caratteri alfanumerici.
5. Fai clic su Aggiungi keystore. Il nuovo keystore viene visualizzato nell'elenco.
6. Utilizza una delle seguenti procedure per aggiungere un alias. Vedi anche Formati file dei certificati supportati.
   • Creazione di un alias da un certificato (solo truststore)
   • Creazione di un alias da un file JAR (solo archivio chiavi)
   • Creare un alias da un certificato e una chiave (solo archivio chiavi)
   • Crea un alias da un file PKCS12/PFX (solo archivio chiavi)
   • Creazione di un alias da un certificato autofirmato (solo archivio chiavi)

Creazione di un alias da un certificato (solo truststore)

Per creare un alias da un certificato:

1. Accedi alla pagina TLS Keystores.
2. Posiziona il cursore sul keystore per visualizzare il menu Azioni e fai clic su +.
3. Specifica il Nome alias.
4. Nella sezione Dettagli certificato, seleziona Solo certificato nel menu a discesa Tipo.
5. Fai clic su Scegli file accanto a File certificato, vai al file PEM contenente il certificato e fai clic su Apri.
6. Per impostazione predefinita, l'API verifica che il certificato non sia scaduto. (Facoltativo) Seleziona Consenti certificato scaduto per ignorare la convalida.
7. Seleziona Salva per caricare il certificato e creare l'alias.

Creazione di un alias da un file JAR (solo archivio chiavi)

Per creare un alias da un file JAR:

1. Accedi alla pagina TLS Keystores.
2. Posiziona il cursore sul keystore per visualizzare il menu Azioni e fai clic su +.
3. Specifica il Nome alias.
4. Nella sezione Dettagli certificato, seleziona File JAR nel menu a discesa Tipo.
5. Fai clic su Scegli file accanto a File JAR, vai al file JAR contenente il certificato e la chiave e fai clic su Apri.
6. Se la chiave ha una password, specifica la password. Se la chiave non ha password, lascia questo campo vuoto.
7. Per impostazione predefinita, l'API verifica che il certificato non sia scaduto. (Facoltativo) Seleziona Consenti certificato scaduto per ignorare la convalida.
8. Seleziona Salva per caricare la chiave e il certificato e creare l'alias.

Creazione di un alias da un certificato e da una chiave (solo archivio chiavi)

Per creare un alias da un certificato e una chiave:

1. Accedi alla pagina TLS Keystores.
2. Posiziona il cursore sul keystore per visualizzare il menu Azioni e fai clic su +.
3. Specifica il Nome alias.
4. In Dettagli certificato, seleziona Certificato e chiave nel menu a discesa Tipo.
5. Fai clic su Scegli file accanto a File del certificato, vai al file PEM contenente il certificato e fai clic su Apri.
6. Se la chiave ha una password, specifica la password della chiave. Se la chiave non ha una password, lascia questo campo vuoto.
7. Fai clic su Scegli file accanto a File chiave, vai al file PEM contenente la chiave e fai clic su Apri.
8. Per impostazione predefinita, l'API verifica che il certificato non sia scaduto. (Facoltativo) Seleziona Consenti certificato scaduto per ignorare la convalida.
9. Seleziona Salva per caricare la chiave e il certificato e creare l'alias.

Creazione di un alias da un file PKCS12/PFX (solo archivio chiavi)

Per creare un alias da un file PKCS12 contenente il certificato e la chiave:

1. Accedi alla pagina TLS Keystores.
2. Posiziona il cursore sul keystore per visualizzare il menu Azioni e fai clic su +.
3. Specifica il Nome alias.
4. In Dettagli certificato, seleziona PKCS12/PFX nel menu a discesa Tipo.
5. Fai clic su Scegli file accanto a PKCS12/PFX, vai al file contenente la chiave e il certificato e fai clic su Apri.
6. Se la chiave ha una password, specifica la password per il file PKCS12/PFX. Se la chiave non ha una password, lascia vuoto questo campo.
7. Per impostazione predefinita, l'API verifica che il certificato non sia scaduto. (Facoltativo) Seleziona Consenti certificato scaduto per ignorare la convalida.
8. Seleziona Salva per caricare il file e creare l'alias.

Creazione di un alias da un certificato autofirmato (solo keystore)

Per creare un alias che utilizza un certificato autofirmato, compila un modulo con le informazioni necessarie per creare il certificato. Edge crea quindi il certificato e una coppia di chiavi privata e li carica nell'alias.

Per creare un alias da un certificato autofirmato:

1. Accedi alla pagina TLS Keystores.
2. Posiziona il cursore sul keystore per visualizzare il menu Azioni e fai clic su +.
3. Specifica il Nome alias.
4. Nella sezione Dettagli certificato, seleziona Certificato autofirmato nel menu a discesa Tipo.
5. Compila il modulo utilizzando la tabella riportata di seguito.
6. Seleziona Salva per creare la coppia di certificato e chiave privata e caricarli nell'alias.

Nel certificato generato, vedrai i seguenti campi aggiuntivi:

• Emittente
  L'entità che ha firmato ed emesso il certificato. Per un certificato autofirmato, questo è il CN specificato durante la creazione del certificato.
• Validità
  Il periodo di validità del certificato rappresentato da due date: la data di inizio e la data di fine del periodo di validità del certificato. Entrambi possono essere codificati come valori UTCTime o GeneralizedTime.

La tabella seguente descrive i campi del modulo:

Testare un keystore o un truststore

Puoi testare il truststore e il keystore nella UI di Edge per verificare che siano configurati correttamente. Test Ui convalida una richiesta TLS da Edge a un servizio di backend. Il servizio di backend può essere configurato per supportare TLS unidirezionale o bidirezionale.

Per testare TLS unidirezionale:

1. Accedi alla pagina TLS Keystores.
2. Seleziona l'ambiente (in genere prod o test).
3. Posiziona il cursore sul keystore TLS che vuoi testare per visualizzare il menu delle azioni e fai clic su Test. Viene visualizzata la seguente finestra di dialogo che mostra il nome del truststore:
   
4. Inserisci il nome host del servizio di backend.
5. Inserisci il numero di porta TLS (in genere 443).
6. (Facoltativo) Specifica eventuali protocolli o cifrari.
7. Seleziona Prova.

Per testare TLS bidirezionale:

1. Per l'archivio attendibile che preferisci, seleziona il pulsante Testa.
2. Nella finestra di dialogo, seleziona Bidirezionale per Tipo di test SSL. Viene visualizzata la seguente finestra di dialogo:
   
3. Specifica il nome del keystore utilizzato in TLS bidirezionale.
4. Specifica il nome dell'alias nell'archivio chiavi contenente il certificato e la chiave.
5. Inserisci il nome host del servizio di backend.
6. Inserisci il numero di porta TLS (in genere 443).
7. (Facoltativo) Specifica eventuali protocolli o cifrari.
8. Seleziona Prova.

Aggiungere un certificato a un truststore per TLS bidirezionale

Quando utilizzi TLS bidirezionale per le connessioni in entrata, ovvero una richiesta API in Edge, il truststore contiene un certificato o una catena di CA per ogni client autorizzato a effettuare richieste a Edge.

Quando configuri inizialmente il truststore, puoi aggiungere tutti i certificati per i client noti. Tuttavia, nel tempo potresti voler aggiungere altri certificati al truststore man mano che aggiungi nuovi client.

Per aggiungere nuovi certificati a un truststore utilizzato per TLS bidirezionale:

1. Assicurati di utilizzare un riferimento al truststore nell'host virtuale.
2. Carica un nuovo certificato nel truststore come descritto sopra in Creazione di un alias da un certificato (solo truststore).

3. Aggiorna il riferimento al truststore in modo che abbia lo stesso valore. Questo aggiornamento fa sì che Edge ricarichi il truststore e il nuovo certificato.

   Per saperne di più, consulta Modificare un riferimento.

Eliminare un archivio chiavi/archivio attendibile o un alias

Devi prestare attenzione quando elimini un keystore/truststore o un alias. Se elimini un keystore, un truststore o un alias utilizzato da un host virtuale, un endpoint di destinazione o un server di destinazione, tutte le chiamate API tramite l'host virtuale o l'endpoint/il server di destinazione non andranno a buon fine.

In genere, la procedura che utilizzi per eliminare un keystore/truststore o un alias è:

1. Crea un nuovo keystore/truststore o alias come descritto sopra.
2. Per le connessioni in entrata, ovvero una richiesta API in Edge, aggiorna la configurazione dell'host virtuale in modo che faccia riferimento al nuovo keystore e all'alias della chiave.
3. Per le connessioni in uscita, ovvero da Apigee a un server di backend:
   1. Aggiorna la configurazione TargetEndpoint per tutti i proxy API che facevano riferimento al vecchio keystore e alias chiave in modo che facciano riferimento al nuovo keystore e alias chiave. Se TargetEndpoint fa riferimento a un TargetServer, aggiorna la definizione di TargetServer in modo che faccia riferimento al nuovo keystore e all'alias della chiave.
   2. Se il keystore e l'archivio attendibilità vengono referenziati direttamente dalla definizione di TargetEndpoint, devi rifare il deployment del proxy. Se TargetEndpoint fa riferimento a una definizione TargetServer e quest'ultima fa riferimento al keystore e al truststore, non è necessario eseguire nuovamente il deployment del proxy.
4. Verifica che i proxy API funzionino correttamente.
5. Elimina l'archivio chiavi/archivio attendibile o l'alias.

Eliminare un archivio chiavi

Puoi eliminare un keystore o un truststore posizionando il cursore sopra il keystore o il truststore nell'elenco per visualizzare il menu delle azioni e facendo clic su . Se elimini un keystore o un truststore utilizzato da un host virtuale o da un endpoint/server di destinazione, tutte le chiamate API tramite l'host virtuale o l'endpoint/server di destinazione non andranno a buon fine.

Attenzione: non eliminare un keystore finché non hai convertito gli host virtuali e gli endpoint/i server di destinazione in modo che utilizzino un nuovo keystore.

Eliminare un alias

Per eliminare un alias, posiziona il cursore sopra l'alias nell'elenco per visualizzare il menu delle azioni e fai clic su . Se elimini un alias utilizzato da un host virtuale o da un endpoint/server di destinazione, tutte le chiamate API tramite l'host virtuale o l'endpoint/server di destinazione non andranno a buon fine.

Attenzione: non eliminare un alias finché non hai convertito gli host virtuali e gli endpoint/i server di destinazione in modo che utilizzino un nuovo keystore e un nuovo alias.