Stai visualizzando la documentazione di Apigee Edge.
Consulta la
documentazione di Apigee X. info
Questo documento descrive come creare, modificare ed eliminare gli archivi chiavi e gli archivi di attendibilità per Edge per la versione 4.17.09 e precedenti di Private Cloud.
Informazioni sugli archivi chiavi e sugli archivi di attendibilità
Gli archivi chiavi e gli archivi di attendibilità definiscono i repository di certificati di sicurezza utilizzati per la crittografia TLS. La principale differenza 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.
Nel TLS unidirezionale, quando un client si connette all'endpoint TLS sul server, l'archivio chiavi del server presenta il certificato del server (certificato pubblico) al client. Il client convalida quindi il certificato con un'autorità di certificazione (CA), come Symantec o VeriSign.
Nel TLS bidirezionale, sia il client che il server mantengono un archivio chiavi con il proprio certificato e la chiave privata utilizzati per l'autenticazione reciproca. - Un truststore contiene i certificati utilizzati per verificare i certificati ricevuti nell'ambito dell'handshake TLS.
Nel TLS unidirezionale, non è necessario un archivio di attendibilità se il certificato è firmato da una CA valida. Se il certificato ricevuto da un client TLS è firmato da una CA valida, il client invia una richiesta alla CA per autenticare il certificato. Un client TLS in genere utilizza un archivio di attendibilità per convalidare i certificati autofirmati ricevuti dal server TLS o i certificati non firmati da una CA attendibile. In questo scenario, il client popola il proprio archivio di attendibilità con i certificati che considera attendibili. Quando il client riceve un certificato del server, il certificato in entrata viene convalidato rispetto ai certificati presenti nel suo archivio di attendibilità.
Ad esempio, un client TLS si connette a un server TLS in cui il server utilizza un certificato autofirmato Poiché si tratta di un certificato autofirmato, il client non può convalidarlo con una CA. Il client precarica invece il certificato autofirmato del server nel proprio archivio di attendibilità. Quindi, quando il client tenta di connettersi al server, il client utilizza il proprio archivio attendibilità per convalidare il certificato ricevuto dal server.
Per il TLS bidirezionale, sia il client TLS che il server TLS possono utilizzare un archivio attendibilità. È necessario un archivio attendibilità quando si esegue il TLS bidirezionale quando Edge funge da server TLS.
I certificati possono essere emessi da un'autorità di certificazione (CA) o possono essere autofirmati dalla chiave privata che generi. Se hai accesso a una CA, segui le istruzioni fornite dalla tua CA per generare le chiavi ed emettere i certificati. Se non hai accesso a una CA, puoi generare un certificato autofirmato utilizzando uno dei tanti strumenti senza costi disponibili pubblicamente, come openssl.
Implementare un archivio chiavi e un archivio di attendibilità su Edge
Su Edge, un archivio chiavi contiene uno o più file JAR, dove il file JAR 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 cert.
- Chiave privata come file PEM. Edge supporta dimensioni delle chiavi fino a 2048 bit. Una passphrase è facoltativa.
Un archivio di attendibilità è simile a un archivio chiavi, tranne per il fatto che contiene solo certificati come file PEM, ma non chiavi private.
Se il certificato fa parte di una catena, l'archivio chiavi/di attendibilità deve contenere tutti i certificati della catena, come singoli file PEM o come un singolo 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, al certificato CA. Devi inserire una riga vuota tra ogni certificato nel file.
Edge fornisce un'API che utilizzi per creare archivi chiavi e archivi di attendibilità. Le API effettive sono le stesse. La differenza è che quando crei un archivio chiavi, passi un file JAR che contiene il certificato e la chiave privata. Quando crei un archivio di attendibilità, passi solo il certificato come file PEM.
Informazioni sul formato dei file di certificati e chiavi
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 sono definiti da un file PEM, puoi convertire li 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 compatibili con il formato PEM e puoi utilizzarli in un archivio chiavi o in un archivio di attendibilità senza convertirli in un file PEM.
Se hai una catena di certificati e vuoi utilizzarla in un archivio chiavi o in un archivio attendibilità, allora 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 certificato 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 archivio chiavi esistente
Controlla l'ambiente per verificare la presenza di archivi chiavi esistenti 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 archivio chiavi predefinito per le organizzazioni di prova senza costi sia nell'ambiente di test che in quello di produzione. Dovresti visualizzare i seguenti risultati per questa chiamata per entrambi gli ambienti:
[ "freetrial" ]
Puoi utilizzare questo archivio chiavi predefinito per testare le tue API e inviarle in produzione, ma tu in genere crei il tuo archivio chiavi, con il tuo certificato e la tua chiave, prima di eseguire il deployment in produzione.
Per i clienti di Private Cloud, l'array restituito è vuoto finché non crei il primo archivio chiavi.
Controlla i contenuti dell'archivio chiavi utilizzando l'API Get a Keystore or Truststore. Per un cliente cloud, dovresti visualizzare un singolo certificato TLS del server, 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:passwordLa risposta dovrebbe essere simile alla seguente:
{ "certs" : [ "wildcard.apigee.net.crt" ], "keys" : [ "freetrial" ], "name" : "freetrial" }
Puoi visualizzare queste informazioni anche 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.
Visualizzare i dettagli del certificato TLS
Puoi utilizzare l'API Get Cert Details from a Keystore or Truststore per visualizzare i dettagli dei certificati TLS in the keystore, come la data di scadenza e l'emittente. Innanzitutto, recupera il nome del certificato che ti interessa. Questo esempio recupera le informazioni per l'archivio chiavi denominato "freetrial".
curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/freetrial \
-u email:passwordRisposta di esempio:
{ "certs" : [ "wildcard.apigee.net.crt" ], "keys" : [ "freetrial" ], "name" : "freetrial" }
Quindi, utilizza il valore della proprietà certs per visualizzare 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 visualizzare queste informazioni anche 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 tutti i certificati la cui scadenza è prevista nei prossimi 10 giorni.
Creare un archivio chiavi
Un archivio chiavi è specifico per un ambiente dell'organizzazione, ad esempio l'ambiente di test o di produzione. Pertanto, se vuoi testare l'archivio chiavi in un ambiente di test prima di eseguirne il deployment nell'ambiente di produzione, devi crearlo in entrambi gli ambienti.
La creazione di un archivio chiavi è 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.
Creare 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
denominato 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
Creare l'archivio chiavi e caricare il file JAR
Per creare un archivio chiavi in un ambiente, devi solo specificare il nome dell'archivio chiavi all'API Create a Keystore or Truststore. 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 Upload a JAR file to a Keystore:
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 in base al nome dell'alias.password- La password per la chiave privata. Ometti questo parametro se la chiave privata non ha una password.
Verifica che l'archivio chiavi 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" }
Creare un archivio di attendibilità
Le API che utilizzi per creare un archivio attendibilità sono le stesse utilizzate per creare un archivio chiavi. L' unica differenza è che passi 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
nell'archivio di attendibilità o creare un singolo file contenente tutti i certificati. Includi una nuova riga tra ogni certificato nel file.
Il certificato finale è in genere firmato dall'emittente del certificato. Ad esempio, nell'archivio attendibilità, 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 ha esito positivo quando il server invia
client_cert_1 al client nell'
ambito del processo di handshake TLS.
In alternativa, hai un secondo certificato, client_cert_2, firmato dallo stesso certificato,
ca_cert. Tuttavia, non carichi client_cert_2 nell'archivio di attendibilità. L'archivio di attendibilità contiene ancora client_cert_1 e ca_cert.
Quando il server passa client_cert_2 nell'ambito dell'handshake TLS, la
richiesta ha esito positivo. Questo perché Edge consente la verifica TLS quando client_cert_2 non esiste nell'
archivio di attendibilità, ma è stato firmato da un certificato esistente nell'archivio di attendibilità. Se rimuovi il certificato CA
, ca_cert, dall'
archivio attendibilità, la verifica TLS non riesce.
Crea un archivio di attendibilità vuoto nell'ambiente utilizzando Create a Keystore or Truststore, la stessa API che utilizzi 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 nell'archivio di attendibilità utilizzando l'API Upload a Certificate to a 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 archivio chiavi o un archivio di attendibilità
Puoi eliminare un archivio chiavi o un archivio di attendibilità utilizzando l'API Delete a Keystore or 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 archivio chiavi o un archivio di attendibilità utilizzato da un host virtuale o da un endpoint/target/server di destinazione, tutte le chiamate API tramite l'host virtuale o l'endpoint/il server di destinazione non andranno a buon fine.