API Gmail S/MIME обеспечивает программный доступ к управлению сертификатами электронной почты S/MIME для пользователей Google Workspace домен.
Чтобы сертификаты работали, администратор должен включить S/MIME для домена .
Стандарт S/MIME определяет спецификацию шифрования с открытым ключом и подписи данных MIME. Настройка сертификатов S/MIME в учётной записи пользователя приводит к тому, что Gmail использует эти сертификаты следующим образом:
- Gmail использует сертификат и закрытый ключ пользователя для подписи исходящей почты.
- Gmail использует закрытый ключ пользователя для расшифровки входящей почты.
- Gmail использует сертификат и открытый ключ получателя для шифрования исходящей почты.
- Gmail использует сертификат отправителя и открытый ключ для проверки входящей почты.
Вы генерируете отдельные сертификаты S/MIME и загружаете их через API. Каждый сертификат S/MIME предназначен для определённого псевдонима учётной записи электронной почты пользователя. Псевдонимы включают в себя основной адрес электронной почты, а также настраиваемые адреса «Отправить как». Для каждого псевдонима по умолчанию используется один сертификат S/MIME.
Разрешение доступа API
Существует две формы авторизации доступа к API:
- Вы можете использовать учетную запись службы с делегированием полномочий на уровне домена . Объяснение этих терминов см. в разделе «Обзор терминов аутентификации и авторизации» . Информация о включении этой опции представлена в разделе «Создание учетной записи службы с делегированием полномочий на уровне домена».
- Вы можете использовать стандартный процесс OAuth2, требующий согласия конечного пользователя для получения токена доступа OAuth2. Подробнее см. в разделе «Обзор аутентификации и авторизации». Чтобы использовать эту опцию, администратор домена должен установить флажок «Доступ конечного пользователя через S/MIME API включён» на панели управления доменом.
Области ACL
Этот API использует те же области ACL , что и методы sendAs в Gmail :
- gmail.settings.basic
- Эта область необходима для обновления основного SendAs S/MIME.
- gmail.settings.sharing
- Эта область необходима для обновления пользовательских данных из S/MIME.
Использование API
Ресурс users.settings.sendAs.smimeInfo предоставляет методы управления сертификатами S/MIME. Каждый сертификат связан с одним псевдонимом пользователя.
Загрузите ключ S/MIME
Используйте метод smimeInfo.insert() для загрузки нового ключа S/MIME для псевдонима пользователя. Целевой псевдоним определяется с помощью следующих параметров:
- ID пользователя
- Адрес электронной почты пользователя. Вы можете использовать специальное значение
me
для указания текущего аутентифицированного пользователя. - sendAsEmail
- Псевдоним, для которого вы загружаете ключ. Это адрес электронной почты, который отображается в поле «От:» для писем, отправленных с использованием этого псевдонима.
Сертификат S/MIME и закрытый ключ должны присутствовать в поле pkcs12
в указанном формате; другие поля в запросе указываться не должны. Поле PKCS12 должно содержать как ключ S/MIME пользователя, так и цепочку сертификатов подписи. API выполняет стандартную проверку этого поля перед его принятием, проверяя следующее:
- Тема соответствует указанному адресу электронной почты.
- Сроки действия действительны.
- Выпустивший сертификат центр сертификации (ЦС) находится в нашем доверенном списке.
- Сертификаты соответствуют техническим ограничениям Gmail.
Если ключ зашифрован, пароль должен быть указан в поле encryptedKeyPassword
. Успешные вызовы insert() вернут идентификатор smimeInfo, который можно будет использовать для ссылки на ключ в будущем.
Список ключей S/MIME пользователя
Используйте метод smimeInfo.list() для возврата списка ключей S/MIME для указанного пользователя и указанного псевдонима. Целевой псевдоним определяется с помощью следующих параметров:
- ID пользователя
- Адрес электронной почты пользователя. Вы можете использовать специальное значение
me
для указания текущего аутентифицированного пользователя. - sendAsEmail
- Псевдоним, для которого нужно вывести список ключей. Это адрес электронной почты, который отображается в заголовке «От:» для писем, отправленных с использованием этого псевдонима.
Получить ключи S/MIME для псевдонима
Используйте метод smimeInfo.get() , чтобы получить конкретные ключи S/MIME для определённого псевдонима пользователя. Целевой псевдоним определяется с помощью следующих параметров:
- ID пользователя
- Адрес электронной почты пользователя. Вы можете использовать специальное значение
me
для указания текущего аутентифицированного пользователя. - sendAsEmail
- Псевдоним, для которого вы получаете ключи. Это адрес электронной почты, который отображается в заголовке «От:» для писем, отправленных с использованием этого псевдонима.
Удалить ключ S/MIME
Используйте метод smimeInfo.delete() для удаления указанного ключа S/MIME из псевдонима. Целевой псевдоним определяется с помощью следующих параметров:
- ID пользователя
- Адрес электронной почты пользователя. Вы можете использовать специальное значение
me
для указания текущего аутентифицированного пользователя. - sendAsEmail
- Псевдоним, для которого вы получаете ключи. Это адрес электронной почты, который отображается в заголовке «От:» для писем, отправленных с использованием этого псевдонима.
- идентификатор
- Неизменяемый идентификатор для SmimeInfo.
Установить ключ S/MIME по умолчанию для псевдонима
Используйте метод smimeInfo.setDefault() , чтобы отметить указанный ключ S/MIME как ключ по умолчанию для указанного псевдонима. Целевой псевдоним определяется с помощью следующих параметров:
- ID пользователя
- Адрес электронной почты пользователя. Вы можете использовать специальное значение
me
для указания текущего аутентифицированного пользователя. - sendAsEmail
- Псевдоним, для которого вы получаете ключи. Это адрес электронной почты, который отображается в заголовке «От:» для писем, отправленных с использованием этого псевдонима.
- идентификатор
- Неизменяемый идентификатор для SmimeInfo.
Пример кода
В следующих примерах кода демонстрируется использование API для управления сертификатами S/MIME для организации с несколькими пользователями.
Создание ресурса SmimeInfo для сертификата S/MIME
В следующем примере кода демонстрируется чтение сертификата из файла, кодирование его в строку base64url и назначение его полю pkcs12
ресурса smimeInfo
:
Ява
Питон
Загрузка сертификата S/MIME
Чтобы загрузить сертификат, вызовите smimeInfo.insert
и укажите ресурс smimeInfo
в теле запроса:
Ява
Питон
Примеры управления сертификатами многих пользователей
Возможно, вам потребуется управлять сертификатами сразу для многих пользователей в организации. В следующих примерах показано, как управлять сертификатами для нескольких пользователей в рамках одного пакетного вызова.
Вставка сертификатов из CSV-файла
Предположим, у вас есть CSV-файл, в котором перечислены идентификаторы пользователей и путь к сертификату каждого пользователя:
$ 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
Ява
Вы можете использовать вызовы createSmimeInfo
и insertSmimeInfo
, описанные ранее, для загрузки сертификатов, как указано в CSV-файле:
Питон
Вы можете использовать вызовы create_smime_info
и insert_smime_info
, описанные ранее, для загрузки сертификатов, как указано в CSV-файле:
Управление сертификатами
В этом примере объединены несколько вызовов API smimeInfo
, демонстрирующих, как можно управлять сертификатами в вашей организации. В нём выводится список сертификатов пользователя, и если сертификат по умолчанию истёк или не установлен, загружается сертификат из указанного файла. Затем в качестве сертификата по умолчанию устанавливается сертификат с самым дальним сроком действия.
Затем он вызывается из функции, которая обрабатывает CSV-файл, как в предыдущем примере.