Tink для Python: инструкция

В этом документе представлены инструкции и фрагменты кода на Python для выполнения типичных задач в Tink (https://github.com/google/tink).

Инструкции по настройке

Для работы с Tink требуется Python 3.7 или выше.

Самый простой способ — установить бинарный релиз из PyPi (https://pypi.org/project/tink/):

pip3 install tink

На данный момент опубликованы следующие наборы бинарных колёс:

• Linux: Python 3.7, Python 3.8, Python 3.9;
• macOS: Python 3.7, Python 3.8, Python 3.9.

Помимо бинарных колёс, также публикуется исходный дистрибутив. Если pip не находит подходящее бинарное колесо для вашей среды, он будет использовать исходный дистрибутив для сборки проекта. Этот процесс имеет те же требования, что и сборка из исходного кода ниже.

Общие проблемы при настройке

• Если вы получаете ошибку относительно корневых сертификатов при использовании интеграции GCP KMS, вам придётся установить корневые сертификаты (https://github.com/googleapis/google-cloud-cpp/blob/master/google/cloud/bigtable/examples/README.md#configure-grpc-root-certificates).

Сборка из исходного кода

Tink поддерживает две системы сборки для использования с Python:

• Bazel (https://bazel.build/);
• Setuptools для создания пакета Python.

Обратите внимание, что в обоих случаях требуется Bazel, так как он нужен для компиляции оболочки вокруг реализации C++, которая использует pybind11 (https://github.com/pybind/pybind11).

Сборка с помощью Bazel

Чтобы собрать реализацию Python:

cd python
bazel build ...

Создание пакета Python с помощью pip

Предоставляется скрипт настройки, который позволяет создать пакет Python с помощью pip.

Скрипт настройки требует:

• Bazel;
• компилятор protobuf (https://github.com/protocolbuffers/protobuf#protocol-compiler-installation).

Чтобы создать и установить пакет Python:

cd python
pip3 install .

Запуск тестов

Чтобы запустить все тесты, можно выполнить:

cd python
bazel test ...

Инициализация Tink

Tink предоставляет настраиваемую инициализацию, которая позволяет выбирать конкретные реализации (идентифицированные типами ключей) желаемых примитивов. Эта инициализация происходит через регистрацию реализаций.

Например, если вы хотите использовать все стандартные реализации всех примитивов в текущей версии Tink, инициализация будет выглядеть следующим образом:

import tink
from tink import tink_config
tink_config.register()

Чтобы использовать стандартные реализации только одного примитива, скажем AEAD:

import tink
from tink import aead
aead.register()

Регистрация пользовательских менеджеров ключей может осуществляться непосредственно через класс core.Registry:

import tink
from tink import core
core.Registry.register_key_manager(CustomAeadKeyManager())

Генерация новых ключей и наборов ключей

Каждый менеджер ключей (KeyManager) предоставляет метод new_key_data(key_template), который генерирует новые ключи соответствующего типа ключа. Однако, чтобы избежать случайной утечки конфиденциального ключевого материала, следует избегать смешивания генерации ключей с использованием ключей в коде.

Чтобы поддержать разделение между этими действиями, пакет Tink предоставляет инструмент командной строки под названием Tinkey (TINKEY.md), который можно использовать для общих задач управления ключами.

Тем не менее, если необходимо сгенерировать KeysetHandle со свежим ключевым материалом непосредственно в коде Python, можно использовать tink.new_keyset_handle:

import tink
from tink import aead

key_template = aead.aead_key_templates.AES128_EAX
keyset_handle = tink.new_keyset_handle(key_template)
# use the keyset...

где key_template можно получить из классов утилит, соответствующих примитивам Tink, например mac_key_templates (https://github.com/google/tink/blob/master/python/tink/mac/_mac_key_templates.py), aead_key_templates (https://github.com/google/tink/blob/master/python/tink/aead/_aead_key_templates.py) или hybrid_key_templates (https://github.com/google/tink/blob/master/python/tink/hybrid/_hybrid_key_templates.py).

Загрузка существующих наборов ключей

Чтобы загрузить зашифрованные наборы ключей, используйте... Получение и использование примитивов

Примитивы в Tink представляют собой криптографические операции, поэтому они составляют основу API Tink. Примитив — это всего лишь интерфейс, который определяет, какие операции предлагает примитив. У примитива может быть несколько реализаций, и вы выбираете желаемую реализацию с помощью ключа соответствующего типа (подробнее см. раздел «Ключ, набор ключей и дескриптор набора ключей»).

Tink для Python поддерживает те же примитивы, что и Tink для C++. Список примитивов и их реализаций, которые в настоящее время поддерживаются Tink на C++, можно найти здесь.

Вы получаете примитив, вызывая метод primitive объекта KeysetHandle.

Симметричное шифрование с аутентификацией

Можно получить и использовать примитив AEAD (аутентифицированное шифрование со связанными данными) для шифрования или дешифрования данных:

import tink
from tink import aead

plaintext = b'your data...'
associated_data = b'context'

# Регистрируем все примитивы AEAD
aead.register()

# 1. Получаем дескриптор материала ключа.
keyset_handle = tink.new_keyset_handle(aead.aead_key_templates.AES256_GCM)

# 2. Получаем примитив.
aead_primitive = keyset_handle.primitive(aead.Aead)

# 3. Используем примитив.
ciphertext = aead_primitive.encrypt(plaintext, associated_data)

Детерминированное симметричное шифрование

Также можно получить и использовать детерминированный примитив AEAD для шифрования или дешифрования данных:

import tink
from tink import daead

plaintext = b'your data...'
associated_data = b'context'

# Регистрируем все детерминированные примитивы AEAD
daead.register()

# 1. Получаем дескриптор материала ключа.
keyset_handle = tink.new_keyset_handle(daead.deterministic_aead_key_templates.AES256_SIV)

# 2. Получаем примитив.
daead_primitive = keyset_handle.primitive(daead.DeterministicAead)

# 3. Используем примитив.
ciphertext = daead_primitive.encrypt_deterministically(plaintext, associated_data)

Шифрование потоковых данных

Кроме того, можно получить и использовать потоковый примитив AEAD для шифрования и дешифрования потоков данных:

import tink
from tink import streaming_aead

long_plaintext = b'your data...'
associated_data = b'context'

# Регистрируем все потоковые примитивы AEAD
streaming_aead.register()

# 1. Получаем дескриптор материала ключа
keyset_handle = tink.new_keyset_handle(streaming_aead.streaming_aead_key_templates.AES256_CTR_HMAC_SHA256_4KB)

# 2. Получаем примитив.
streaming_aead_primitive = keyset_handle.primitive(streaming_aead.StreamingAead)

# 3. Используем примитив.
output_file = open("ciphertext.out", 'wb')
with streaming_aead_primitive.new_encrypting_stream(output_file, associated_data) as enc_stream:
  bytes_written = enc_stream.write(long_plaintext)

Код аутентификации сообщения

Наконец, можно вычислить или проверить MAC:

import tink
from tink import mac

data = b'your data...'

# Регистрируем все MAC