Questo documento descrive come creare, modificare ed eliminare i keystore e i truststore per Edge per il cloud e per Edge per il private cloud nelle versioni 4.18.01 e successive.
Nota: Private Cloud versione 4.17.09 e precedenti non consente di creare
Attenzione: quando un proxy API in Apigee Edge per il cloud pubblico o privato si connette a un endpoint o a un server target, Apigee non esegue per impostazione predefinita la convalida dell'hostname per il certificato presentato dall'endpoint o dal server target. Per applicare la convalida del nome host, puoi scegliere tra applicare una configurazione a livello di singolo proxy o impostare un flag per attivare l'applicazione per l'intera organizzazione. Per ulteriori informazioni su queste modifiche alla configurazione, consulta il bollettino sulla sicurezza: GCP-2024-006 .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 relative all'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ù :
Implementazione di archivi chiavi e truststore in
Edge
Per configurare le funzionalità che si basano sull'infrastruttura a chiave pubblica, come TLS, devi creare keystore e truststore contenenti 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 . In altre parole, non esiste alcuna differenza di implementazione tra un keystore e un truststore su Edge.
La differenza tra i file keystore e truststore deriva dai tipi di voci che contengono e dal modo in cui vengono utilizzati nel handshake TLS:
keystore: un'entità keystore contenente uno o più
alias , in cui ogni alias contiene una coppia di certificati/chiavi.
truststore: un'entità keystore contenente uno o più
alias , in cui 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 nella procedura di handshake TLS. Quando configuri un endpoint di destinazione o un host virtuale, specifica 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 utilizzati dall'host virtuale per il suo keystore TLS. Utilizza un riferimento per specificare il nome del keystore in modo da poterlo modificare in un secondo momento alla scadenza del certificato. L'alias contiene una coppia di 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 specificarlo:
<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 utilizzata nell'ambito della procedura di handshake TLS.
Formato
Caricamento dell'API e dell'interfaccia utente supportato
Supporto per i flussi in uscita
Convalidato
PEM
Sì
Sì
Sì
* PKCS12
Sì
Sì
Sì
* DER
No
No
Sì
* PKCS7
No
No
No
* Consigliamo di utilizzare PEM, se possibile.
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 in Apigee. Per assistenza con la conversione delle chiavi e dei certificati esistenti nel formato PKCS12/PFX, consulta la sezione Convertire i certificati in formato supportato .
Informazioni sull'implementazione di un alias
Nota : Apigee converte le chiavi e i certificati PKCS12 caricati in formato PEM. Se possibile, consigliamo di utilizzare solo file in formato PEM.
In Edge, un archivio chiavi contiene uno o più alias , ognuno dei quali contiene:
Un 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 un'autorità di certificazione o un certificato autofirmato.
Chiave privata come file PEM o PKCS12/PFX. Edge supporta dimensioni delle chiavi fino a 2048 bit. Una passphrase è facoltativa.
In Edge, un truststore contiene uno o più alias , dove ogni alias contiene:
Un 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 un'autorità di certificazione o un certificato autofirmato.
Edge fornisce un'interfaccia utente e un'API che puoi utilizzare per creare archivi chiavi, creare alias, caricare coppie di certificati/chiavi e aggiornare i certificati. L'interfaccia utente e l'API utilizzate per creare un truststore sono le stesse utilizzate per creare un keystore. La differenza è che quando crei un truststore, crei degli alias
che contengono solo una certificazione.
Puoi rappresentare i certificati e le chiavi come file PEM o come file PKCS12/PFX. I file PEM sono conformi al formato X.509. Se il certificato o la chiave privata non è definito da un file PEM, puoi convertirlo 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-----
I file sono quindi compatibili con il formato PEM e puoi utilizzarli in un keystore o
truststore senza doverli convertire in un file PEM.
Informazioni sulle catene di certificati
Se un certificato fa parte di una catena, viene gestito in modo diverso a seconda che venga utilizzato in un temporaneo 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 singolo 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 singolo 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 del client riesce 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 passa client_cert_2 nell'ambito del handshake TLS, la richiesta viene completata. Questo perché Edge consente il completamento della verifica TLS quando client_cert_2
non esiste nel truststore, ma è stato firmato da un certificato presente nel truststore. Serimuovi il certificato CA ca_cert dal truststore, la verifica TLS non va a buon fine.
Considerazioni relative a FIPS
Se utilizzi Edge for Private Cloud 4.53.00 o versioni successive su un sistema operativo compatibile con FIPS, devi utilizzare solo un keystore PKCS12 per caricare le chiavi e i certificati correlati in Apigee.
Esplorare la pagina Certificati TLS
Accedi alla pagina Magazzini chiavi TLS, come descritto di seguito.
Edge
Per accedere alla pagina delle caselle chiavi TLS utilizzando l'interfaccia utente di Edge:
Accedi a https://apigee.com/edge come amministratore dell'organizzazione .
Seleziona la tua organizzazione.
Seleziona Amministrazione > Ambiente > Magazzini chiavi TLS .
Edge classico (private cloud) Nota: l'interfaccia utente di Edge classica è disponibile solo con Edge per il Private Cloud.Per accedere alla pagina delle caselle portachiavi TLS utilizzando l'interfaccia utente classica di Edge:
Accedi a http://ms-ip :9000 come amministratore dell'organizzazione , dove ms-ip è l'indirizzo IP o il nome DNS del nodo del server di gestione.
Seleziona la tua organizzazione.
Seleziona Amministrazione > Configurazione dell'ambiente > Magazzini chiavi TLS .
Viene visualizzata la pagina Magazzini chiavi TLS:
Come evidenziato nella figura precedente, la pagina Magazzini chiavi TLS ti consente di:
Nota: i passaggi negli argomenti che seguono sono specifici dell'interfaccia utente di Edge. I passaggi per l'interfaccia utente di Edge classica sono simili a quelli descritti.Visualizzare un alias
Per visualizzare un alias:
Accedi alla pagina Certificati TLS .Seleziona l'ambiente (in genere prod o test).
Fai clic sulla riga associata all'alias che vuoi visualizzare.
Vengono visualizzati i dettagli della chiave e del certificato dell'alias.
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). Poi invii la CSR alla tua CA per ottenere un nuovo
certificato.
Aggiorna un certificato. Attenzione : se aggiorni un certificato attualmente in uso da un host virtuale o da un server/endpoint di destinazione, devi contattare l'assistenza Apigee Edge per riavviare i router e gli elaboratori di messaggi. Il modo consigliato per aggiornare un
certificato è:
Crea un nuovo keystore o truststore.
Aggiungi il nuovo certificato al nuovo keystore o truststore.
Aggiorna il riferimento nell'host virtuale o nel
server di destinazione/endpoint di destinazione al
keystore o al truststore. Per saperne di più, consulta
Aggiornare un certificato TLS per il cloud .
Elimina l'alias. Nota : se elimini un alias attualmente in uso da un host virtuale o da un endpoint di destinazione, l'host virtuale o l'endpoint di destinazione non funzionerà.
Creare un archivio chiavi/un archivio attendibile e un alias
Puoi creare un keystore da utilizzare come keystore TLS o come 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 eseguirlo nel tuo 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 di certificati/chiavi (keystore) o solo un certificato (truststore) nell'alias.
Per creare un keystore:
Accedi alla pagina Magazzini chiavi TLS .Seleziona l'ambiente (in genere prod o test).
Fai clic su + Keystore .
Specifica il nome del keystore. Il nome può contenere solo caratteri alfanumerici.
Fai clic su Aggiungi Keystore . Il nuovo keystore viene visualizzato nell'elenco.
Per aggiungere un alias, utilizza una delle seguenti procedure. Consulta anche
Formati file dei certificati supportati .
Creazione di un alias da un certificato (solo truststore)
Per creare un alias da un certificato:
Accedi alla pagina Certificati TLS .Posiziona il cursore sul keystore per visualizzare il menu di azioni e fai clic su + .
Specifica il nome dell'alias .
In Dettagli certificato, seleziona Solo certificato nel menu a discesa Tipo.
Fai clic su Scegli file accanto a File del certificato , vai al
file PEM contenente il certificato e fai clic su Apri .
Per impostazione predefinita, l'API controlla che il certificato non sia scaduto. Se vuoi, seleziona Consenti certificato scaduto per saltare la convalida.
Seleziona Salva per caricare il certificato e creare l'alias.
Creazione di un alias da un file JAR
(solo per l'archivio chiavi)
Per creare un alias da un file JAR:
Accedi alla pagina Certificati TLS .Posiziona il cursore sul keystore per visualizzare il menu di azioni e fai clic su + .
Specifica il nome dell'alias .
In Dettagli certificato, seleziona File JAR nel menu a discesa Tipo.
Fai clic su Scegli file accanto a File JAR , vai al file JAR contenente il certificato e la chiave e fai clic su Apri .
Se la chiave ha una password, specifica la Password . Se la chiave non ha password, lascia questo campo vuoto.
Per impostazione predefinita, l'API controlla che il certificato non sia scaduto. Se vuoi, seleziona Consenti certificato scaduto per saltare la convalida.
Seleziona Salva per caricare la chiave e il certificato e creare l'alias.
Creazione di un alias da un certificato e
una chiave (solo archivio chiavi)
Per creare un alias da un certificato e una chiave:
Accedi alla pagina Certificati TLS .Posiziona il cursore sul keystore per visualizzare il menu di azioni e fai clic su + .
Specifica il nome dell'alias .
In Dettagli certificato, seleziona Certificato e chiave nel menu a discesa Tipo.
Fai clic su Scegli file accanto a File del certificato , vai al file PEM contenente il certificato e fai clic su Apri .
Se la chiave ha una password, specifica la Password chiave . Se la chiave non ha password, lascia questo campo vuoto.
Fai clic su Scegli file accanto a File della chiave , vai al file PEM contenente la chiave e fai clic su Apri .
Per impostazione predefinita, l'API controlla che il certificato non sia scaduto. Se vuoi, seleziona Consenti certificato scaduto per saltare la convalida.
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:
Accedi alla pagina Certificati TLS .Posiziona il cursore sul keystore per visualizzare il menu di azioni e fai clic su + .
Specifica il nome dell'alias .
In Dettagli certificato, seleziona PKCS12/PFX nel menu a discesa Tipo.
Fai clic su Scegli file accanto a PKCS12/PFX , vai al
file contenente la chiave e il certificato e fai clic su Apri .
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.
Per impostazione predefinita, l'API controlla che il certificato non sia scaduto. Se vuoi, seleziona Consenti certificato scaduto per saltare la convalida.
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 private e li carica nell'alias.
Per creare un alias da un certificato autofirmato:
Accedi alla pagina Certificati TLS .Posiziona il cursore sul keystore per visualizzare il menu di azioni e fai clic su + .
Specifica il nome dell'alias .
In Dettagli certificato, seleziona Certificato autofirmato nel menu a discesa Tipo.
Compila il modulo utilizzando la tabella seguente.
Seleziona Salva per creare la coppia di certificati e chiavi private e caricarli nell'alias.
Nel certificato generato, vedrai i seguenti campi aggiuntivi:
Emittente Validità
La tabella seguente descrive i campi del modulo:
Campo modulo
Descrizione
Predefinito
Obbligatorio
Nome dell'alias
Nome dell'alias. La lunghezza massima è di 128 caratteri.
N/D
Sì
Dimensioni della chiave
Dimensioni della chiave, in bit. Il valore predefinito e massimo è 2048 bit.
2048
No
Algoritmo di firma
Algoritmo di firma per generare la chiave privata. I valori validi sono "SHA512withRSA",
"SHA384withRSA" e "SHA256withRSA" (valore predefinito).
SHA256withRSA
No
Validità del certificato in giorni
Durata di validità del certificato, in giorni. Accetta un valore positivo diverso da zero.
365
No
Nome comune
Il nome comune (CN) dell'organizzazione identifica i nomi di dominio completi associati al certificato. È costituito in genere da un host e da un nome di dominio.
Ad esempio, api.enterprise.apigee.com, www.apigee.com e così via. La lunghezza massima è di 64 caratteri.
A seconda del tipo di certificato , il valore CN può essere costituito da uno o più nomi host appartenenti allo stesso dominio (ad es. example.com, www.example.com), da un nome con carattere jolly (ad es. *.example.com) o da un elenco di domini. Non
includere alcun protocollo (http:// o https://), numero di porta o percorso della risorsa.
Il certificato è valido solo se il nome host della richiesta corrisponde ad almeno uno dei nomi comuni del certificato.
N/D
Sì
Email
Indirizzo email. La lunghezza massima è di 255 caratteri.
N/D
No
Nome unità organizzativa
Nome del team dell'organizzazione. La lunghezza massima è di 64 caratteri.
N/D
No
Nome dell'organizzazione
Nome dell'organizzazione. La lunghezza massima è di 64 caratteri.
N/D
No
Località
Nome della città. La lunghezza massima è di 128 caratteri.
N/D
No
Provincia
Nome dello stato o della provincia. La lunghezza massima è di 128 caratteri.
N/D
No
Paese
Codice paese di due lettere. Ad esempio, IN per l'India, US per gli Stati Uniti d'America.
N/D
No
Nomi alternativi
Elenco di nomi host alternativi. Consente di associare identità aggiuntive all'oggetto
del certificato. Le opzioni definite includono un indirizzo email di internet, un nome DNS, un indirizzo IP e un URI (Uniform Resource Identifier).
Massimo 255 caratteri per ogni valore. Puoi separare i nomi con una virgola o premendo il tasto Invio dopo ogni nome.
N/D
No
Testare un keystore o un truststore
Puoi testare il truststore e il keystore nell'interfaccia utente di Edge per verificare che siano configurati correttamente. L'interfaccia utente di Test 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:
Accedi alla pagina Certificati TLS .Seleziona l'ambiente (in genere prod o test).
Posiziona il cursore del mouse sopra il 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:
Inserisci il nome host del servizio di backend.
Inserisci il numero di porta TLS (in genere 443).
Se vuoi, specifica eventuali protocolli o algoritmi di crittografia.
Seleziona Testa .
Per testare TLS bidirezionale:
Per il truststore desiderato, seleziona il pulsante Test .
Nella finestra di dialogo, seleziona Bidirezionale per il Tipo di test SSL .
Viene visualizzata la seguente finestra di dialogo:
Specifica il nome del keystore utilizzato in TLS bidirezionale.
Specifica il nome dell'alias nell'archivio chiavi contenente il certificato e la chiave.
Inserisci il nome host del servizio di backend.
Inserisci il numero di porta TLS (in genere 443).
Se vuoi, specifica eventuali protocolli o algoritmi di crittografia.
Seleziona Testa .
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 una catena di certificati o CA per ogni client autorizzato a inviare 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:
Assicurati di utilizzare un riferimento al truststore nell'host virtuale.
Carica un nuovo certificato nel truststore come descritto sopra in
Creare un alias da un certificato (solo truststore) .
Aggiorna il riferimento al truststore impostandolo sullo 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 keystore/truststore 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 target o un server target, tutte le chiamate API tramite l'host virtuale o l'endpoint/il server target non andranno a buon fine.
In genere, la procedura utilizzata per eliminare un keystore/truststore o un alias è la seguente:
Crea un nuovo keystore/truststore o alias come descritto sopra.
Per le connessioni in entrata , ovvero una richiesta API in Edge, aggiorna la configurazione dell'hosting virtuale in modo che faccia riferimento al nuovo archivio chiavi e all'alias chiave.
Per le connessioni in uscita , ovvero da Apigee a un server di backend:
Aggiorna la configurazione di TargetEndpoint per tutti i proxy API che facevano riferimento al vecchio
keystore e all'alias chiave in modo che facciano riferimento al nuovo keystore e all'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 chiave.
Se il riferimento a keystore e truststore avviene direttamente dalla definizione di TargetEndpoint, devi eseguire nuovamente il deployment del proxy. Se TargetEndpoint fa riferimento a una definizione di TargetServer e la definizione di TargetServer fa riferimento al keystore e al truststore, non è necessario il ricollocamento del proxy.
Verifica che i proxy API funzionino correttamente.
Elimina il keystore/truststore o l'alias.
Eliminare un archivio chiavi
Per eliminare un keystore o un truststore, posiziona il cursore sul keystore o sul truststore nell'elenco per visualizzare il menu delle azioni e fai clic su
Attenzione : non devi 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
Puoi eliminare un alias posizionando il cursore del mouse sull'alias nell'elenco per visualizzare il menu delle azioni e facendo clic su
Attenzione : non devi 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.
