Stai visualizzando la documentazione di Apigee Edge.
Vai alla
documentazione di Apigee X. informazioni
Questo documento descrive come creare, modificare ed eliminare archivi chiavi e truststore per Edge per il cloud privato versione 4.17.09 e precedenti.
Informazioni su archivi chiavi e truststore
Gli archivi chiavi e gli archivi di attendibilità definiscono i repository di certificati di sicurezza utilizzati per la crittografia TLS. La differenza principale tra i due sta nel punto in cui vengono utilizzati nel processo di handshake TLS:
- Un keystore contiene un certificato TLS e una chiave privata utilizzati per identificare l'entità durante l'handshake TLS.
Nel protocollo 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 tale certificato con un'autorità di certificazione (CA), come Symantec o VeriSign.
Nella crittografia TLS bidirezionale, sia il client sia il server mantengono un archivio chiavi con il proprio certificato e la propria chiave privata utilizzata per l'autenticazione reciproca. - Un archivio attendibilità contiene certificati utilizzati per verificare i certificati ricevuti nell'ambito dell'handshake TLS.
Nella crittografia TLS unidirezionale, non è necessario un archivio 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 alla CA una richiesta di autenticazione del 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 una CA attendibile. In questo scenario, il client completa il proprio archivio attendibilità con certificati che considera attendibili. Poi, quando il client riceve un certificato del server, il certificato in entrata viene convalidato in base ai certificati nel suo archivio 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. Al contrario, il client precarica il certificato autofirmato del server nel proprio archivio attendibilità. Quindi, quando il client tenta di connettersi al server, utilizza il proprio archivio di attendibilità per convalidare il certificato ricevuto dal server.
Per il protocollo TLS a due vie, sia il client TLS sia il server TLS possono utilizzare un archivio attendibilità. È richiesto un archivio attendibilità per l'esecuzione di 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 generata da te. Se hai accesso a una CA, segui le istruzioni fornite da quest'ultima per generare chiavi e emettere certificati. Se non hai accesso a una CA, puoi generare un certificato autofirmato utilizzando uno dei numerosi strumenti senza costi disponibili pubblicamente, come Opensl.
Implementazione di un archivio chiavi e di un archivio attendibilità su Edge
In 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.
- Chiave privata come file PEM. Edge supporta dimensioni della chiave fino a 2048 bit. La passphrase è facoltativa.
Un archivio 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/l'archivio attendibilità deve contenere tutti i certificati nella catena, come singoli file PEM o come singolo file. Se utilizzi un solo file, i certificati devono essere nell'ordine in cui il primo certificato nel file è quello utilizzato per TLS seguito dalla catena di certificati, in ordine, al certificato CA. Devi inserire una riga vuota tra ciascun certificato nel file.
Edge fornisce un'API che puoi utilizzare per creare archivi chiavi e truststore. 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 attendibilità, passi solo il certificato come file PEM.
Informazioni sul formato dei file del certificato e della chiave
Gli esempi in questo documento mostrano la chiave e il certificato 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 convertirli in un file PEM utilizzando utilità come Opensl.
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 archivio chiavi o in un archivio attendibilità senza convertirli in un file PEM.
Se disponi di una catena di certificati e vuoi utilizzarla in un archivio chiavi o in un archivio attendibilità, puoi combinare tutti i certificati in un unico file PEM, con una nuova riga tra un certificato e l'altro. 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-----
Recupero dei dettagli su un archivio chiavi esistente
Verifica la presenza di eventuali archivi chiavi esistenti nel tuo ambiente utilizzando l'API Elenca archivi chiavi e truststore:
curl -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores \
-u email:password
Per i clienti del cloud, viene fornito un archivio chiavi predefinito per le organizzazioni di prova senza costi sia negli ambienti di test che di produzione. Dovresti vedere i seguenti risultati per questa chiamata per entrambi gli ambienti:
[ "freetrial" ]
Puoi utilizzare questo archivio chiavi predefinito per testare le API ed eseguirne il push in produzione, ma in genere devi creare un archivio chiavi personalizzato, con un certificato e una chiave personali, prima di eseguire il deployment in produzione.
Per i clienti del cloud privato, l'array restituito è vuoto fino a quando non crei il primo archivio chiavi.
Controlla i contenuti dell'archivio chiavi mediante l'API Ottieni un archivio chiavi o un archivio attendibilità. Per un cliente cloud, dovresti vedere 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:password
La risposta dovrebbe essere visualizzata come segue:
{
"certs" : [ "wildcard.apigee.net.crt" ],
"keys" : [ "freetrial" ],
"name" : "freetrial"
}
Puoi visualizzare queste informazioni anche nell'interfaccia utente di gestione perimetrale:
- Accedi all'interfaccia utente di gestione perimetrale 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 Edge, seleziona Amministrazione > Certificati TLS.
Recupero dettagli certificato TLS
Puoi utilizzare l'API Ottieni dettagli certificato da un archivio chiavi o un truststore per visualizzare i dettagli dei certificati TLS nell'archivio chiavi, 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:password
Esempio di risposta:
{
"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
Esempio di risposta:
{
"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 perimetrale:
- Accedi all'interfaccia utente di gestione perimetrale 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 Edge, seleziona Amministrazione > Certificati TLS.
Nella UI di Edge, puoi specificare l'anticipo con cui Edge indica che un certificato sta per scadere. Per impostazione predefinita, l'interfaccia utente evidenzia tutti i certificati che scadono nei 10 giorni successivi.
Crea un archivio chiavi
Un archivio chiavi è specifico per un ambiente nella tua 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 prevede 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 tua chiave privata, il tuo certificato e un file 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 il seguente
contenuto:
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 tuo 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 nell'API Crea un archivio chiavi o un archivio attendibilità. 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
Esempio di risposta:
{
"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 mediante il nome alias.password: la password per la chiave privata. Ometti questo parametro se la chiave privata non ha una password.
Verifica che il tuo archivio chiavi sia stato caricato correttamente:
curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/myKeystore \
-u email:password
Esempio di risposta:
{
"certs" : [ "myCertificate" ],
"keys" : [ "myKey" ],
"name" : "myKeystore"
}
Crea un archivio attendibilità
Le API che utilizzi per creare un archivio attendibilità sono le stesse utilizzate per creare un archivio chiavi. L'unica differenza è che il file del certificato viene trasferito come file PEM anziché come file JAR.
Se il certificato fa parte di una catena, devi caricare separatamente tutti i certificati della catena nell'archivio di attendibilità oppure creare un singolo file contenente tutti i certificati e includere una nuova riga tra ciascun 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
attendibilità. L'archivio 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 riuscita della verifica TLS quando client_cert_2 non esiste nell'archivio attendibilità, ma è stato firmato da un certificato esistente nell'archivio attendibilità. Se rimuovi il certificato CA, ca_cert, dall'archivio attendibilità, la verifica TLS non andrà a buon fine.
Per creare un archivio attendibilità vuoto nell'ambiente, utilizza Crea un archivio chiavi o un archivio attendibilità, 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 attendibilità utilizzando l'API Carica un certificato in un archivio attendibilità:
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.
Eliminazione di un archivio chiavi o di un archivio attendibilità
Puoi eliminare un archivio chiavi o un archivio attendibilità utilizzando l'API Delete a Keystore or Truststore (Elimina un archivio chiavi o un archivio attendibilità):
curl -X DELETE \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/myKeystoreName \
-u email:password
Esempio di risposta:
{
"certs" : [ ],
"keys" : [ ],
"name" : "myKeystoreName"
}
Se elimini un archivio chiavi o un archivio 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/server di destinazione avranno esito negativo.