Creazione di archivi chiavi e truststore mediante l'API Edge Management

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

Questo documento descrive come creare, modificare ed eliminare archivi chiavi e archivi di attendibilità per Edge per il cloud e Edge per il cloud privato versioni 4.18.01 e successive.

Introduzione

Per configurare la funzionalità che si basa sull'infrastruttura a chiave pubblica, come TLS, devi creare archivi chiavi e truststore che forniscono le chiavi e i certificati digitali necessari.

Per un'introduzione ad archivi chiavi, truststore e alias, consulta archivi chiavi e archivi di attendibilità.

Crea un archivio chiavi

Un archivio chiavi è specifico per un ambiente della 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.

Per creare un archivio chiavi in un ambiente:

  1. Utilizza la chiamata API in questa sezione per creare l'archivio chiavi.
  2. Creare un alias e caricare una coppia di certificato/chiave nell'alias. La modalità di caricamento del certificato e della chiave si basa sul formato della coppia certificato/chiave. Le seguenti sezioni descrivono come caricare ciascun tipo di coppia di certificato/chiave:

Per creare un archivio chiavi, specifica il nome dell'archivio chiavi nell'API Crea un archivio chiavi o un archivio chiavi. Il nome dell'archivio chiavi può contenere solo caratteri alfanumerici:

curl -X POST -u orgAdminEmail:password -H "Content-Type: text/xml" \
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores \
-d '<KeyStore name="myKeystore"/>'

Esempio di risposta:

{
  "certs" : [ ],
  "keys" : [ ],
  "name" : "myKeystore"
}

Carica un certificato e una chiave come file JAR

Devi prima creare 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

Un JAR di un archivio chiavi può contenere solo questi tre file. Se disponi di una catena di certificati, tutti i certificati al suo interno devono essere aggiunti in un unico file PEM, in cui l'ultimo certificato deve essere firmato da una CA radice. I certificati devono essere aggiunti al file PEM nell'ordine corretto, con una riga vuota tra ciascun certificato, ovvero:

cert -> intermediate cert(1) -> intermediate cert(2) -> … -> root

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

Ora puoi caricare i tuoi file JAR che contengono un certificato e una chiave privata utilizzando l'API Crea un alias da un file JAR o PKCS:

curl -u orgAdminEmail:password -X POST -H "Content-Type: multipart/form-data" -F file="@myKeystore.jar" -F password={key_pword} \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases?alias={alias_name}&format=keycertjar"

dove l'opzione -F specifica il percorso del file JAR.

In questa chiamata, specifichi:

  • alias_name: identifica il certificato e la chiave nell'archivio chiavi. Quando crei un host virtuale, fai riferimento al certificato e alla chiave tramite il nome alias.
  • key_pword: 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 -u orgAdminEmail:password -X GET\
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}

Esempio di risposta:

{  
 "certs" : [ "myCertificate" ],
 "keys" : [ "myKey" ],
 "name" : "myKeystore"
}

Carica un certificato e una chiave come file PEM

Carica i file PEM che contengono un certificato e una chiave privata utilizzando l'API Crea un alias da file PEM di certificati e chiavi:

curl -u orgAdminEmail:password -X POST -H "Content-Type: multipart/form-data" -F keyFile="@server.key" -F certFile="@signed.crt" \
-F password={key_pword} \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases?alias={alias_name}&format=keycertfile"

dove l'opzione -F specifica i percorsi dei file PEM.

In questa chiamata, specifichi:

  • alias_name: identifica il certificato e la chiave nell'archivio chiavi. Quando crei un host virtuale, fai riferimento al certificato e alla chiave tramite il nome alias.
  • key_pword: 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 -u orgAdminEmail:password -X GET\
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}

Esempio di risposta:

{  
 "certs" : [ "myCertificate" ],
 "keys" : [ "myKey" ],
 "name" : "myKeystore"
}

Carica un certificato e una chiave come file PKCS12/PFX

Carica un file PKCS12/PFX contenente un certificato e una chiave privata utilizzando l'API Crea un alias da un file JAR o PKCS:

curl -u orgAdminEmail:password -X POST -H "Content-Type: multipart/form-data" \
-F file="@myKeystore.p12" -F password={key_pword} \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases?alias={alias_name}&format=pkcs12"

dove l'opzione -F specifica il percorso al file P12.

In questa chiamata, specifichi:

  • alias_name: identifica il certificato e la chiave nell'archivio chiavi. Quando crei un host virtuale, fai riferimento al certificato e alla chiave tramite il nome alias.
  • key_pword: 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 -u orgAdminEmail:password -X GET\
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}

Esempio di risposta:

{  
 "certs" : [ "myCertificate" ],
 "keys" : [ "myKey" ],
 "name" : "myKeystore"
}

Crea e carica un certificato e una chiave autofirmati

Puoi utilizzare l'API Crea un alias generando un certificato autofirmato per creare un certificato e una chiave autofirmati e caricarli su un alias. La chiamata seguente specifica solo le informazioni richieste per creare l'autofirmato. Puoi modificare questa chiamata per aggiungere ulteriori informazioni:

curl -u orgAdminEmail:password -X POST --header "Content-Type: application/json"  \
-d "{
    "alias": "selfsigned",
    "subject": {
        "commonName": "mycert"
    }
}" \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases?format=selfsignedcert"

La risposta dovrebbe avere il seguente aspetto:

{
  "alias": "selfsigned",
  "certsInfo": {
    "certInfo": [
      {
        "basicConstraints": "CA:FALSE",
        "expiryDate": 1491497204000,
        "isValid": "Yes",
        "issuer": "CN=mycert",
        "publicKey": "RSA Public Key, 2048 bits",
        "serialNumber": "00:d1:b4:78:e1",
        "sigAlgName": "SHA256withRSA",
        "subject": "CN=mycert",
        "subjectAlternativeNames": [],
        "validFrom": 1459961204000,
        "version": 3
      }
    ],
    "certName": "selfsigned-cert"
  },
  "keyName": "selfsigned"
}

Crea un archivio attendibilità

Le API che utilizzi per creare un archivio chiavi sono le stesse utilizzate per creare un archivio chiavi. L'unica differenza è che carichi solo un file di certificato, come file PEM, nell'archivio attendibilità.

Se il certificato fa parte di una catena, devi caricare separatamente tutti i certificati nella catena nell'archivio di attendibilità oppure creare un singolo file contenente tutti i certificati. Devi inserire una riga vuota tra ciascun certificato nel file.

Se vuoi caricare più certificati autofirmati che non fanno parte di una catena, utilizza la stessa tecnica: se ci sono più certificati che vuoi considerare attendibili, caricali in un unico file.

Il certificato finale è in genere firmato dall'emittente. 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 client ha esito positivo quando il server invia client_cert_1 al client nell'ambito del processo di handshake TLS.

In alternativa, puoi disporre di un secondo certificato, client_cert_2, firmato con lo stesso certificato, ca_cert. Tuttavia, non caricherai client_cert_2 nell'archivio attendibilità. L'archivio attendibilità contiene ancora client_cert_1 e ca_cert.

Quando il server passa client_cert_2 come parte 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 di attendibilità, la verifica TLS non va a buon fine.

Crea un archivio chiavi vuoto nell'ambiente utilizzando Crea un archivio chiavi o un archivio chiavi, la stessa API che utilizzi per creare un archivio chiavi:

curl -u orgAdminEmail:password -X POST -H "Content-Type: text/xml" \
-d '<KeyStore name="myTruststore"/>' \
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores

Dopo aver creato l'archivio attendibilità, carica il certificato come file PEM nell'archivio attendibilità utilizzando l'API Crea un alias da un file PEM di certificato:

curl -u orgAdminEmail:password -X POST -H "Content-Type: multipart/form-data" -F certFile="@cert.pem" \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/myTruststore/aliases?alias=myTruststore&format=keycertfile"

dove l'opzione -F specifica il percorso del file PEM.

Ottieni dettagli su un archivio chiavi o un archivio attendibilità esistente

Verifica la presenza di eventuali archivi chiavi esistenti nel tuo ambiente utilizzando l'API List Keystores and Truststores:

curl -u orgAdminEmail:password -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores

Per i clienti 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 eseguire il push delle API in produzione, ma in genere devi creare un archivio chiavi personalizzato, con certificato e chiave personalizzati, prima di eseguire il deployment in produzione.

Per i clienti del cloud privato, l'array restituito è vuoto finché non crei il primo archivio chiavi.

Verifica i contenuti dell'archivio chiavi utilizzando l'API Ottieni un archivio chiavi o un archivio chiavi. 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 -u orgAdminEmail:password -X GET\
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/freetrial

La risposta dovrebbe avere il seguente aspetto:

{
 "certs" : [ "wildcard.apigee.net.crt" ],
 "keys" : [ "freetrial" ],
 "name" : "freetrial"
}

Ottenere dettagli su un alias

Ottieni un elenco di tutti gli alias per gli archivi chiavi utilizzando l'API Elenco alias:

curl -u orgAdminEmail:password -X GET \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases"

La risposta dovrebbe avere il seguente aspetto:

[
  "alias1",
  "alias2",
  "alias3",
]

Per ottenere tutte le informazioni su un alias, come la data di scadenza e l'emittente, utilizza l'API Ottieni alias e specifica il nome dell'alias:

curl  -u orgAdminEmail:password -X GET \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases/{alias_name}"

La risposta dovrebbe avere il seguente aspetto:

{
  "alias": "alias1",
  "certsInfo": {
    "certInfo": [
      {
        "basicConstraints": "CA:TRUE",
        "expiryDate": 1459371335000,
        "isValid": "No",
        "issuer": "EMAILADDRESS=foo@bar.com, CN=smg, OU=doc, O=Internet Widgits Pty Ltd, L=noho, ST=Some-State, C=AU",
        "publicKey": "RSA Public Key, 1024 bits",
        "serialNumber": "00:86:a0:9b:5b:91:a9:fe:92",
        "sigAlgName": "SHA256withRSA",
        "subject": "EMAILADDRESS=foo@bar.com, CN=smg, OU=doc, O=Internet Widgits Pty Ltd, L=noho, ST=Some-State, C=AU",
        "subjectAlternativeNames": [],
        "validFrom": 1456779335000,
        "version": 3
      }
    ],
    "certName": "new\-cert"
  },
  "keyName": "newssl20"
}

Per scaricare il certificato per un alias, utilizza l'API Esporta un certificato per un alias:

curl -u orgAdminEmail:password -X GET \
"https://api.enterprise.apigee.com/v1/e/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases/{alias_name}/certificate"

La risposta dovrebbe avere il seguente aspetto:

-----BEGIN CERTIFICATE-----
MIIDojCCAwugAwIBAgIJAIagm1uRqf6SMA0GCSqGSIb3DQEBCwUAMIGTMQswCQYD
...
RBUkaTe/570sLHY0tvkIm5tEX36ESw==
-----END CERTIFICATE-----

Se hai un certificato scaduto e vuoi rinnovarlo, puoi scaricare una richiesta di firma del certificato (CSR). Successivamente, invierai il file CSR all'autorità di certificazione per ottenerne uno nuovo. Per generare una richiesta di firma del certificato per un alias, utilizza l'API Genera una CSR per un alias:

curl -u orgAdminEmail:password -X GET \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases/{alias_name}/csr"

La risposta dovrebbe avere il seguente aspetto:

-----BEGIN CERTIFICATE REQUEST-----
MIIB1DCCAT0CAQAwgZMxCzAJBgNVBAYTAkFVMRMwEQYDVQQIEwpTb21lLVN0YXRl
...
RF5RMytbkxkvPxIE17mDKJH0d8aekv/iEOItZ+BtQg+EibMUkkjTzQ==
-----END CERTIFICATE REQUEST-----

Aggiungi un certificato a un archivio attendibilità per TLS bidirezionale

Quando utilizzi TLS bidirezionale per le connessioni in entrata, ovvero una richiesta API in Edge, l'archivio di attendibilità contiene un certificato o una catena di CA per ciascun client autorizzato a effettuare richieste a Edge.

Quando configuri per la prima volta l'archivio attendibilità, puoi aggiungere tutti i certificati per i client noti. Tuttavia, nel corso del tempo, potresti voler aggiungere altri certificati all'archivio attendibilità man mano che aggiungi nuovi client.

Per aggiungere nuovi certificati a un archivio attendibilità utilizzato per TLS bidirezionale:

  1. Assicurati di utilizzare un riferimento all'archivio attendibilità nell'host virtuale.
  2. Carica un nuovo certificato nell'archivio attendibilità come descritto sopra in Creare un archivio attendibilità.
  3. Aggiorna il riferimento dell'archivio attendibilità in modo da impostarlo sullo stesso valore. Con questo aggiornamento, Edge ricarica l'archivio di attendibilità e il nuovo certificato.

    Per saperne di più, consulta Modifica di un riferimento.

Elimina un archivio chiavi/un archivio di attendibilità o un alias

Devi fare attenzione quando elimini un archivio chiavi/un archivio di attendibilità o un alias. Se elimini un archivio chiavi, un archivio attendibilità o un alias utilizzato da un host virtuale, un endpoint di destinazione o un server di destinazione, tutte le chiamate API effettuate tramite l'host virtuale o il server di destinazione/endpoint di destinazione avranno esito negativo.

In genere, il processo che utilizzi per eliminare un archivio chiavi/un archivio di attendibilità o un alias è:

  1. Crea un nuovo archivio chiavi/un nuovo archivio di attendibilità o un 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 archivio chiavi e all'alias delle chiavi.
  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 fanno riferimento al vecchio archivio chiavi e all'alias chiavi in modo da fare riferimento al nuovo archivio chiavi e al nuovo alias chiave. Se TargetEndpoint fa riferimento a un TargetServer, aggiorna la definizione di TargetServer in modo che faccia riferimento al nuovo archivio chiavi e al nuovo alias chiave.
    2. Se all'archivio chiavi e all'archivio attendibilità viene fatto riferimento direttamente dalla definizione TargetEndpoint, è necessario eseguire nuovamente il deployment del proxy. Se TargetEndpoint fa riferimento a una definizione di TargetServer e la definizione TargetServer fa riferimento all'archivio chiavi e all'archivio trust, non è necessario un nuovo deployment del proxy.
    3. Verifica che i proxy API funzionino correttamente.
    4. Elimina l'archivio chiavi/l'archivio di attendibilità o l'alias.

Per saperne di più, consulta Aggiornare il certificato in un alias.

Elimina un archivio chiavi o un archivio attendibilità

Puoi eliminare un archivio chiavi o un archivio attendibilità utilizzando l'API Delete a Keystore or Truststore:

curl -u orgAdminEmail:password -X DELETE \
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/myKeystoreName

Se elimini e ricrei un archivio chiavi o un archivio attendibilità utilizzato da un host virtuale, devi eseguire nuovamente il deployment dei proxy API.

Elimina un alias

Puoi eliminare un alias in un archivio chiavi o in un archivio attendibilità utilizzando l'API Elimina alias:

curl -u orgAdminEmail:password -X DELETE \
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/myKeystoreName/aliases/{alias_name}