Stai visualizzando la documentazione di Apigee Edge.
Vai alla documentazione di Apigee X. info
Questo documento descrive come creare, modificare ed eliminare i keystore e i truststore per Edge per la versione 4.17.09 e precedenti di Private Cloud.
Informazioni su archivi chiavi e truststore
I keystore e i truststore definiscono i repository dei certificati di sicurezza utilizzati per la crittografia TLS. La differenza principale tra i due è dove vengono utilizzati nel processo di handshake TLS:
- Un archivio chiavi contiene un certificato TLS e una chiave privata utilizzati per identificare l'entità durante l'handshake TLS.
In TLS unidirezionale, quando un client si connette all'endpoint TLS sul server, il keystore del server presenta al client il certificato del server (certificato pubblico). Il client convalida poi il certificato con un'autorità di certificazione (CA), come Symantec o VeriSign.
In TLS bidirezionale, sia il client sia il server gestiscono un archivio chiavi con il proprio certificato e la propria chiave privata utilizzati per l'autenticazione reciproca. - Un truststore contiene i certificati utilizzati per verificare i certificati ricevuti nell'ambito dell'handshake TLS.
In TLS unidirezionale, un truststore non è necessario se il certificato è firmato da una CA valida. Se il certificato ricevuto da un client TLS è firmato da un'autorità di certificazione valida, il client invia una richiesta all'autorità di certificazione per autenticare il certificato. In genere, un client TLS utilizza un archivio attendibilità per convalidare i certificati autofirmati ricevuti dal server TLS o i certificati non firmati da un'autorità di certificazione attendibile. In questo scenario, il client compila il truststore con i certificati di cui sifida. Quando il client riceve un certificato del server, questo viene convalidato in base ai certificati nel truststore.
Ad esempio, un client TLS si connette a un server TLS che utilizza un certificato autofirmato. Poiché si tratta di un certificato autofirmato, il client non può convalidarlo con un'autorità di certificazione. Il client precompila invece il certificato autofirmato del server nel proprio truststore. Poi, quando il client tenta di connettersi al server, utilizza il proprio truststore per convalidare il certificato ricevuto dal server.
Per TLS bidirezionale, sia il client TLS sia il server TLS possono utilizzare un truststore. È necessario un truststore quando esegui TLS bidirezionale quando Edge agisce come server TLS.
I certificati possono essere emessi da un'autorità di certificazione (CA) o essere autofirmati dalla chiave privata che generi. Se hai accesso a un'autorità di certificazione, segui le istruzioni fornite dall'autorità per la generazione delle chiavi e il rilascio dei certificati. Se non hai accesso a un'autorità di certificazione, puoi generare un certificato autofirmato utilizzando uno dei molti strumenti senza costi disponibili pubblicamente, come openssl.
Implementazione di un archivio chiavi e un archivio attendibilità su Edge
In Edge, un archivio chiavi contiene uno o più file JAR, in cui il file JAR 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.
- Chiave privata come file PEM. Edge supporta dimensioni delle chiavi fino a 2048 bit. Una passphrase è obbligatoria.
Un truststore è simile a un keystore, tranne per il fatto che contiene solo certificati come file PEM, ma nessuna chiave privata.
Se il certificato fa parte di una catena, il keystore/truststore deve contenere tutti i certificati della catena come singoli file PEM o come un unico file. Se utilizzi un singolo file, i certificati devono essere in ordine, dove il primo certificato nel file è il certificato utilizzato per TLS seguito dalla catena di certificati, in ordine, fino al certificato CA. Devi inserire una riga vuota tra ogni certificato nel file.
Edge fornisce un'API che utilizzi per creare keystore e truststore. Le API effettive rimangono invariate. La differenza è che quando crei un archivio chiavi, passi un file JAR contenente il certificato e la chiave privata. Quando crei un truststore, passi solo il certificato come file PEM.
Informazioni sul formato dei file del certificato e della chiave
Gli esempi in questo documento mostrano il certificato e la chiave TLS definiti come file PEM, 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.
Se hai una catena di certificati e vuoi utilizzarla in un keystore o truststore, puoi combinare tutti i certificati in un unico file PEM con una nuova riga tra ogni certificato. 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-----
Visualizzare i dettagli di un keystore esistente
Controlla se sono presenti archivi chiavi esistenti nel tuo ambiente utilizzando l'API List Keystores and Truststores:
curl -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores \
-u email:password
Per i clienti cloud, viene fornito un keystore predefinito per le organizzazioni con prova senza costi sia negli ambienti di test che di produzione. Per questa chiamata dovresti vedere i seguenti risultati per entrambi gli ambienti:
[ "freetrial" ]
Puoi utilizzare questo keystore predefinito per testare le API e spingerle in produzione, ma in genere crei il tuo keystore con il tuo certificato e la tua chiave prima di eseguire il deployment in produzione.
Per i clienti Private Cloud, l'array restituito è vuoto fino a quando non crei il primo impostazione di sicurezza.
Controlla i contenuti del keystore utilizzando l'API Get a Keystore or Truststore. Per un cliente cloud, dovresti vedere un singolo certificato TLS del server, ovvero il certificato predefinito fornito da Apigee Edge per gli account di prova senza costi.
curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/freetrial \
-u email:password
La risposta dovrebbe essere simile alla seguente:
{
"certs" : [ "wildcard.apigee.net.crt" ],
"keys" : [ "freetrial" ],
"name" : "freetrial"
}
Puoi anche visualizzare queste informazioni nell'interfaccia utente di gestione di Edge:
- Accedi all'interfaccia utente di gestione di Edge all'indirizzo https://enterprise.apigee.com (cloud) o
http://<ms-ip>:9000(on-premise), dove<ms-ip>è l'indirizzo IP del nodo del server di gestione. - Nel menu dell'interfaccia utente di gestione di Edge, seleziona Amministrazione > Certificati TLS.
Ottenere i dettagli del certificato TLS
Puoi utilizzare l'API Get Cert Details from a Keystore or Truststore per visualizzare i dettagli dei certificati TLS nel keystore, ad esempio la data di scadenza e l'emittente. Innanzitutto, ottieni il nome del certificato che ti interessa. Questo esempio recupera le informazioni per il keystore chiamato "freetrial".
curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/freetrial \
-u email:password
Risposta di esempio:
{
"certs" : [ "wildcard.apigee.net.crt" ],
"keys" : [ "freetrial" ],
"name" : "freetrial"
}
Quindi, utilizza il valore della proprietà certs per ottenere i dettagli del certificato:
curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/freetrial/certs/wildcard.apigee.net.crt \
-u email:password
Risposta di esempio:
{
"certInfo" : [ {
"expiryDate" : "Wed, 23 Apr 2014 20:50:02 UTC",
"isValid" : "Yes",
"issuer" : "CN=Go Daddy Secure Certificate Authority - G2, OU=http://certs.godaddy.com/repository/, O="GoDaddy.com, Inc.", L=Scottsdale, ST=Arizona, C=US",
"subject" : CN=*.example.apigee.net, OU=Domain Control Validated",
"subjectAlternativeNames" : ["*.example.apigee.net","*.example.apigee.net" ],
"validFrom" : "Tue, 15 Apr 2014 09:17:03 UTC",
"version" : 3
} ],
"name" : "example.apigee.net.crt"
}
Puoi anche visualizzare queste informazioni nell'interfaccia utente di gestione di Edge:
- Accedi all'interfaccia utente di gestione di Edge all'indirizzo https://enterprise.apigee.com (cloud) o
http://<ms-ip>:9000(on-premise), dove<ms-ip>è l'indirizzo IP del nodo del server di gestione. - Nel menu dell'interfaccia utente di gestione di Edge, seleziona Amministrazione > Certificati TLS.
Nell'interfaccia utente di Edge, puoi specificare con quanto anticipo Edge indica che un certificato sta per scadere. Per impostazione predefinita, l'interfaccia utente evidenzia i certificati in scadenza nei prossimi 10 giorni.
Crea un archivio chiavi
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.
La creazione di un keystore è un processo in due passaggi:
- Crea un file JAR contenente il certificato e la chiave privata.
- Crea l'archivio chiavi e carica il file JAR.
Crea un file JAR contenente il certificato e la chiave privata
Crea un file JAR con la chiave privata, il certificato e un manifest. Il file JAR deve contenere i seguenti file e directory:
/META-INF/descriptor.properties myCert.pem myKey.pem
Nella directory contenente la coppia di chiavi e il certificato, crea una directory denominata
/META-INF. Quindi, crea un file chiamato descriptor.properties in /META-INF con i seguenti contenuti:
certFile={myCertificate}.pem
keyFile={myKey}.pem
Genera il file JAR contenente la coppia di chiavi e il certificato:
jar -cf myKeystore.jar myCert.pem myKey.pem
Aggiungi descriptor.properties al file JAR:
jar -uf myKeystore.jar META-INF/descriptor.properties
Crea l'archivio chiavi e carica il file JAR
Per creare un archivio chiavi in un ambiente, devi solo specificare il nome dell'archivio chiavi all'API Crea un archivio chiavi o un archivio attendibile. Il nome può contenere solo caratteri alfanumerici:
curl -X POST -H "Content-Type: text/xml" \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores \
-d '<KeyStore name="myKeystore"/>' -u email:password
Risposta di esempio:
{
"certs" : [ ],
"keys" : [ ],
"name" : "myKeystore"
}
Dopo aver creato un archivio chiavi denominato in un ambiente, puoi caricare i file JAR che contengono un certificato e una chiave privata utilizzando l'API carica un file JAR in un archivio chiavi:
curl -X POST -H "Content-Type: multipart/form-data" \
-F file="@myKeystore.jar" -F password={key_pass} \ "https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/{myKeystore}/keys?alias={key_alias}" \
-u email:password
dove l'opzione -F specifica
il percorso del file JAR.
In questa chiamata, specifichi due parametri di query:
alias: identifica il certificato e la chiave nell'archivio chiavi. Quando crei un host virtuale, fai riferimento al certificato e alla chiave tramite il nome dell'alias.password: la password per la chiave privata. Ometti questo parametro se la chiave privata non ha una password.
Verifica che il keystore sia stato caricato correttamente:
curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/myKeystore \
-u email:password
Risposta di esempio:
{
"certs" : [ "myCertificate" ],
"keys" : [ "myKey" ],
"name" : "myKeystore"
}
Crea un truststore
Le API utilizzate per creare un truststore sono le stesse utilizzate per creare un keystore. L'unica differenza è che devi passare il file del certificato come file PEM anziché come file JAR.
Se il certificato fa parte di una catena, devi caricare tutti i certificati della catena separatamente
nel truststore o creare un singolo file contenente tutti i certificati, includendo una nuova riga tra
ogni certificato nel file. Il certificato finale è in genere firmato dall'emittente del certificato. Ad esempio, nel truststore 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 caricare client_cert_2 nel truststore. Il truststore contiene ancora client_cert_1 e ca_cert.
Quando il server passa client_cert_2 nell'ambito del handshake TLS, la richiesta va a buon fine. Questo accade perché Edge consente il completamento della verifica TLS quando client_cert_2 non esiste nel truststore, ma è stato firmato da un certificato esistente nel truststore. Se rimuovi il certificato CA ca_cert dal truststore, la verifica TLS non va a buon fine.
Crea un truststore vuoto nell'ambiente utilizzando Crea un archivio chiavi o un truststore, la stessa API utilizzata per creare un archivio chiavi:
curl -X POST -H "Content-Type: text/xml" -d \
'<KeyStore name="myTruststore"/>' \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores \
-u email:password
Carica il certificato come file PEM nel truststore utilizzando l'API Carica un certificato in un truststore:
curl -X POST -H "Content-Type: multipart/form-data" -F file="@trust.pem" \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/myTruststore/certs?alias=myTruststore \
-u email:password
dove l'opzione -F specifica il percorso del file PEM.
Eliminare un keystore o un truststore
Puoi eliminare un keystore o un truststore utilizzando l'API Elimina un keystore o un truststore:
curl -X DELETE \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/myKeystoreName \
-u email:password
Risposta di esempio:
{
"certs" : [ ],
"keys" : [ ],
"name" : "myKeystoreName"
}
Se elimini un keystore o un truststore utilizzato da un endpoint/target/server o da un host virtuale, tutte le chiamate API tramite l'endpoint/target/server o l'host virtuale non andranno a buon fine.