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

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 il cloud e per Edge per il cloud privato versioni 4.18.01 e successive.

Introduzione

Per configurare funzionalità che si basano sull'infrastruttura a chiave pubblica, come TLS, devi creare archivi chiavi e archivi di attendibilità che forniscano le chiavi e i certificati digitali necessari.

Per un'introduzione agli archivi chiavi, agli archivi di attendibilità e agli alias, consulta Archivi chiavi e archivi di attendibilità.

Creare 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. Crea un alias e carica una coppia certificato/chiave nell'alias. La modalità di caricamento del certificato e della chiave dipende dal formato della coppia certificato/chiave. Le sezioni seguenti descrivono come caricare ogni tipo di coppia certificato/chiave:

Per creare un archivio chiavi, specifica il nome dell'archivio chiavi nell'API Create a Keystore or Truststore. 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"
}

Caricare 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 file JAR dell'archivio chiavi può contenere solo questi tre file. Se hai una catena di certificati, tutti i certificati della catena devono essere aggiunti a un singolo 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 ogni 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 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 a file JAR:

jar -uf myKeystore.jar META-INF/descriptor.properties

Ora puoi caricare i file JAR contenenti un certificato e una chiave privata utilizzando l'API Create an alias from a JAR or PKCS file:

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 in l'archivio chiavi. Quando crei un host virtuale, fai riferimento al certificato e alla chiave in base al suo 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"
}

Caricare un certificato e una chiave come file PEM

Carica i file PEM contenenti un certificato e una chiave privata utilizzando l'API Create an alias from certificate and key PEM files:

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 in l'archivio chiavi. Quando crei un host virtuale, fai riferimento al certificato e alla chiave in base al suo 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"
}

Caricare un certificato e una chiave come file PKCS12/PFX

Carica un file PKCS12/PFX contenente un certificato e una chiave privata utilizzando l'API Create an alias from a JAR or PKCS file:

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 del file P12.

In questa chiamata, specifichi:

  • alias_name - Identifica il certificato e la chiave in l'archivio chiavi. Quando crei un host virtuale, fai riferimento al certificato e alla chiave in base al suo 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"
}

Creare e caricare un certificato e una chiave autofirmati

Puoi utilizzare l'API Create an alias by generating a self-signed certificate per creare un certificato e una chiave autofirmati e caricarli in un alias. La seguente chiamata specifica solo le informazioni richieste per creare il certificato 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 essere simile alla seguente:

{
  "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"
}

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 carichi solo un file di certificato, come file PEM, nell'archivio di attendibilità.

Se il certificato fa parte di una catena, devi caricare tutti i certificati della catena separatamente nell'archivio di attendibilità oppure creare un singolo file contenente tutti i certificati. Devi inserire una riga vuota tra ogni 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 di cui vuoi fidarti, caricali in un unico file.

Il certificato finale viene in genere firmato dall'emittente del certificato. Ad esempio, nell' archivio di attendibilità carichi un certificato client, client_cert_1, e il certificato dell'emittente del certificato client , ca_cert.

Durante l'autenticazione TLS reciproca, l'autenticazione del client ha esito positivo quando il server invia client_cert_1 al client come parte 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 di 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 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 di 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 -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 Create an alias from a certificate PEM file:

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.

Visualizzare i dettagli di un archivio chiavi o di attendibilità esistente

Controlla l'ambiente per verificare la presenza di archivi chiavi esistenti 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 nell'ambiente di test sia in quello di produzione. Dovresti vedere 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 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 del cloud privato, 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 vedere 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 essere simile alla seguente:

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

Visualizzare i dettagli di un alias

Recupera un elenco di tutti gli alias per un archivio chiavi utilizzando l'API List aliases:

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 essere simile alla seguente:

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

Per ottenere tutte le informazioni su un alias, come la data di scadenza e l'emittente, utilizza l'API Get 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 essere simile alla seguente:

{
  "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 Export a certificate for an 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 essere simile alla seguente:

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

Se hai un certificato scaduto e vuoi rinnovarlo, puoi scaricare una richiesta di firma del certificato (CSR). Quindi invia la CSR alla tua CA per ottenere un nuovo certificato. Per generare una CSR per un alias, utilizza l'API Generate a CSR for an 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 essere simile alla seguente:

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

Aggiungere un certificato a un archivio attendibilità per TLS reciproco

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

Quando configuri inizialmente l'archivio di attendibilità, puoi aggiungere tutti i certificati per i client noti. Tuttavia, nel 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 reciproco:

  1. Assicurati di utilizzare un riferimento all'archivio attendibilità nell'host virtuale.
  2. Carica un nuovo certificato nell'archivio di attendibilità come descritto sopra in Creare un archivio di attendibilità.

  3. Aggiorna il riferimento all'archivio di attendibilità impostandolo sullo stesso valore. Questo aggiornamento fa sì che Edge ricarichi l'archivio di attendibilità e il nuovo certificato.

    Per ulteriori informazioni, consulta Modificare un riferimento.

Eliminare un archivio chiavi/di attendibilità o un alias

Devi prestare attenzione quando elimini un archivio chiavi/archivio 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 tramite l'host virtuale o l'endpoint di destinazione/il server di destinazione non andranno a buon fine.

In genere, la procedura che utilizzi per eliminare un archivio chiavi/di attendibilità o un alias è la seguente:

  1. Crea un nuovo archivio chiavi/di attendibilità o un nuovo alias come descritto sopra.
  2. Per le connessioni in entrata, ovvero una richiesta API a Edge, aggiorna la configurazione dell'host virtuale in modo che faccia riferimento al nuovo archivio chiavi e all'alias della chiave.
  3. Per le connessioni in uscita, ovvero da Apigee a un server di backend:
    1. Aggiorna la configurazione di TargetEndpoint per tutti i proxy API che facevano riferimento al vecchio archivio chiavi e all'alias della chiave in modo che facciano riferimento al nuovo archivio chiavi e all'alias della chiave. Se TargetEndpoint fa riferimento a un TargetServer, aggiorna la definizione di TargetServer in modo che faccia riferimento al nuovo archivio chiavi e all'alias della chiave.
    2. Se si fa riferimento all'archivio chiavi e all'archivio attendibilità direttamente dalla definizione di TargetEndpoint, devi rifare il deployment del proxy. Se TargetEndpoint fa riferimento a una definizione di TargetServer e la definizione di TargetServer fa riferimento all'archivio chiavi e all' archivio di attendibilità, non è necessario eseguire di nuovo il deployment del proxy.
    3. Verifica che i proxy API funzionino correttamente.
    4. Elimina l'archivio chiavi/archivio attendibilità o l'alias.

Per ulteriori informazioni, consulta Aggiornare il certificato in un alias.

Eliminare un archivio chiavi o di attendibilità

Puoi eliminare un archivio chiavi o di 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 di attendibilità utilizzato da un host virtuale, allora devi eseguire di nuovo il deployment dei proxy API.

Eliminare un alias

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

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