Questo documento spiega come utilizzare i certificati email S/MIME con l'API Gmail.
L'API Gmail fornisce l'accesso programmatico per gestire i certificati email S/MIME per gli utenti di un dominio Google Workspace.
Affinché i certificati funzionino, un amministratore deve attivare S/MIME ospitata per il dominio.
Lo standard S/MIME fornisce una specifica per la crittografia e la firma con chiave pubblica dei dati MIME. Quando configuri i certificati S/MIME per un account utente, Gmail li utilizza nei seguenti modi:
Firma le email in uscita con il certificato utente e la chiave privata.
Decripta la posta in arrivo con la chiave privata dell'utente.
Cripta la posta in uscita con il certificato e la chiave pubblica del destinatario.
Verifica la posta in arrivo con il certificato del mittente e la chiave pubblica.
Puoi generare singoli certificati S/MIME e caricarli utilizzando l'API Gmail. Ogni certificato S/MIME è per un alias specifico di un account email utente. Gli alias includono l'indirizzo email principale e gli indirizzi personalizzati per l'invio come. L'API contrassegna un singolo certificato S/MIME come predefinito per ogni alias.
Per maggiori informazioni sugli alias, vedi Gestire alias e firme con l'API Gmail.
Autorizzare l'accesso API
Per autorizzare l'accesso all'API Gmail, utilizza uno dei seguenti metodi:
Utilizza un service account con delega dell'autorità a livello di dominio. Per una spiegazione di questi termini, consulta Informazioni su autenticazione e autorizzazione. Per attivare questa opzione, consulta Crea le credenziali di accesso.
Utilizza un flusso OAuth 2.0 standard che richiede il consenso dell'utente per ottenere un token di accesso OAuth 2.0. Per saperne di più, consulta Informazioni su autenticazione e autorizzazione.
Per utilizzare questa opzione, l'amministratore del dominio deve selezionare la casella di controllo Attiva crittografia S/MIME per l'invio e la ricezione di email nella Console di amministrazione Google. Per maggiori informazioni, vedi Attivare la crittografia S/MIME ospitata nella Console di amministrazione.
Ambiti di autorizzazione
L'API Gmail si basa sugli stessi ambiti OAuth dei metodi Gmail sendAs:
gmail.settings.basic: obbligatorio per aggiornare S/MIMESendAsprincipale.gmail.settings.sharing: obbligatorio per aggiornare S/MIME da personalizzato.
Configurare le chiavi S/MIME
La risorsa
settings.sendAs.smimeInfo
fornisce diversi metodi per gestire i certificati S/MIME. Ogni
certificato è associato a un alias Invia come per un utente.
Per determinare gli alias Invia come per un utente, utilizza il metodo
settings.sendAs.list
nella risorsa
settings.sendAs.
Caricare una chiave S/MIME
Utilizza il metodo
settings.sendAs.smimeInfo.insert
nella risorsa settings.sendAs.smimeInfo per caricare una nuova chiave S/MIME
per un alias appartenente a un utente. Identifica l'alias di destinazione utilizzando i seguenti
parametri di percorso:
userId: l'indirizzo email dell'utente. Utilizza il valore specialemeper indicare l'utente autenticato.sendAsEmail: l'alias per cui stai caricando la chiave. Questo indirizzo email viene visualizzato nell'intestazioneFrom:per le email inviate utilizzando questo alias.
Fornisci il certificato S/MIME e la chiave privata nel campo
pkcs12
in formato PKCS #12. Non impostare altri campi nella richiesta. Il campo
pkcs12 contiene sia la chiave S/MIME dell'utente sia la catena di certificati di firma. L'API esegue convalide standard su questo campo prima di accettarlo, verificando quanto segue:
- L'oggetto corrisponde all'indirizzo email specificato.
- Le scadenze sono valide.
- L'autorità di certificazione (CA) che lo ha rilasciato è presente nell'elenco attendibile di Google.
- I certificati corrispondono ai vincoli tecnici di Gmail.
Se la chiave è criptata, fornisci la password nel campo
encryptedKeyPassword. Una chiamata al metodo settings.sendAs.smimeInfo.insert riuscita restituisce la risorsa settings.sendAs.smimeInfo id utilizzata per fare riferimento alla chiave in futuro.
Elenca le chiavi S/MIME di un utente
Utilizza il
metodo settings.sendAs.smimeInfo.list
nella risorsa settings.sendAs.smimeInfo per restituire l'elenco delle chiavi S/MIME
per l'utente specificato per l'alias specificato. Identifica l'alias di destinazione utilizzando i seguenti parametri di percorso:
userId: l'indirizzo email dell'utente. Utilizza il valore specialemeper indicare l'utente autenticato.sendAsEmail: l'alias per cui elencare le chiavi. Questo indirizzo email viene visualizzato nell'intestazioneFrom:per la posta inviata utilizzando questo alias.
Recuperare le chiavi S/MIME per un alias
Utilizza il metodo
settings.sendAs.smimeInfo.get
nella risorsa settings.sendAs.smimeInfo per restituire le chiavi S/MIME
specifiche per un alias Invia come specifico per un utente. Identifica l'alias del target utilizzando
i seguenti parametri di percorso:
userId: l'indirizzo email dell'utente. Utilizza il valore specialemeper indicare l'utente autenticato.sendAsEmail: l'alias per cui stai recuperando le chiavi. Questo indirizzo email viene visualizzato nell'intestazioneFrom:per le email inviate utilizzando questo alias.
Eliminare una chiave S/MIME
Utilizza il metodo
settings.sendAs.smimeInfo.delete
sulla risorsa settings.sendAs.smimeInfo per eliminare la chiave
S/MIME specificata da un alias. Identifica l'alias di destinazione utilizzando i seguenti parametri
del percorso:
userId: l'indirizzo email dell'utente. Utilizza il valore specialemeper indicare l'utente autenticato.sendAsEmail: l'alias da cui stai eliminando la chiave. Questo indirizzo email viene visualizzato nell'intestazioneFrom:per le email inviate utilizzando questo alias.id: l'ID immutabile persmimeInfo.
Una chiave eliminata non è più visibile o utilizzabile. Non puoi decriptare le email S/MIME ricevute che sono state criptate utilizzando la chiave pubblica corrispondente. Prima di eliminare una chiave, revocala con l'autorità di emissione (CA).
Impostare la chiave S/MIME predefinita per un alias
Utilizza il metodo
settings.sendAs.smimeInfo.setDefault
nella risorsa settings.sendAs.smimeInfo per contrassegnare la chiave S/MIME specificata
come predefinita per l'alias specificato. Identifica l'alias di destinazione utilizzando i seguenti parametri di percorso:
userId: l'indirizzo email dell'utente. Utilizza il valore specialemeper indicare l'utente autenticato.sendAsEmail: l'alias per cui impostare la chiave predefinita. Questo indirizzo email viene visualizzato nell'intestazioneFrom:per le email inviate utilizzando questo alias.id: l'ID immutabile persmimeInfo.
Solo una chiave S/MIME è predefinita per l'alias Invia come di un utente. La chiamata al
metodo settings.sendAs.smimeInfo.setDefault annulla l'impostazione predefinita precedente.
Quando un utente riceve messaggi S/MIME firmati con una determinata chiave,
Gmail associa la chiave alla not_before data di validità
più lontana nel futuro come predefinita per la crittografia della posta inviata all'utente
associato. Per garantire che gli utenti di Gmail con cui l'utente
ha già comunicato utilizzino la nuova chiave predefinita, assicurati che la nuova chiave predefinita
abbia una data not_before successiva a quella della chiave predefinita precedente o revoca la
chiave predefinita precedente.
Esempi di codice
I seguenti esempi di codice mostrano come utilizzare l'API Gmail per gestire i certificati S/MIME per un'organizzazione con più utenti:
Crea una risorsa smimeInfo per un certificato S/MIME
Questo esempio di codice mostra come leggere un certificato da un file, codificarlo in una stringa Base64URL e assegnarlo al campo pkcs12 della risorsa settings.sendAs.smimeInfo:
Java
Python
Caricare un certificato S/MIME
Per caricare un certificato, chiama il metodo
settings.sendAs.smimeInfo.insert
e fornisci la risorsa settings.sendAs.smimeInfo nel corpo della
richiesta:
Java
Python
Gestire i certificati di più utenti
Questi esempi di codice mostrano come gestire i certificati per più utenti in un'organizzazione in una singola chiamata batch:
Inserire certificati da un file CSV
Di seguito è riportato un file CSV di esempio che elenca gli ID utente e il percorso del certificato di ciascun utente:
$ cat certificates.csv
user1@example.com,/path/to/user1_cert.p12,cert_password_1
user2@example.com,/path/to/user2_cert.p12,cert_password_2
user3@example.com,/path/to/user3_cert.p12,cert_password_3
Java
Puoi utilizzare gli esempi
CreateSmimeInfo
e InsertSmimeInfo
per caricare i certificati per gli utenti specificati in un file CSV:
Python
Puoi utilizzare gli esempi
create_smime_info
e insert_smime_info
per caricare i certificati per gli utenti specificati in un file CSV:
Gestione dei certificati
Questo esempio combina diversi metodi della risorsa settings.sendAs.smimeInfo
per mostrare come gestire i certificati per la tua organizzazione. Elenca i certificati per l'utente. Se il certificato predefinito è scaduto o non è impostato, carica il certificato trovato nel file specificato. Quindi imposta come predefinito il certificato con la scadenza più lontana nel futuro.
Questa funzione elabora quindi un file CSV, in modo simile all'esempio precedente Inserisci certificati da un file CSV.
Java
Python
Argomenti correlati
- Gestire alias e firme con l'API Gmail
- Scegliere gli ambiti dell'API Gmail
- Attivare la crittografia S/MIME ospitata per la crittografia dei messaggi