Скачать capillary - скачать capillary исходный код

Капилляр

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

Установка

Чтобы добавить зависимость, используя Maven:

Для сервера на основе Java:

< dependency >
  < groupId >com.google.capillary</ groupId >
  < artifactId >lib</ artifactId >
  < version >1.0.0</ version >
</ dependency >

Для Android:

< dependency >
  < groupId >com.google.capillary</ groupId >
  < artifactId >lib-android</ artifactId >
  < version >1.0.0</ version >
</ dependency >

Чтобы добавить зависимость, используя Gradle:

Для сервера на основе Java:

 dependencies {
  compile 'com.google.capillary:lib:1.0.0'
}

Для Android:

 dependencies {
  compile 'com.google.capillary:lib-android:1.0.0'
}

API документы

Java:
- 1.0.0
Android:
- 1.0.0

Введение

Чтобы использовать услуги обмена толкательными сообщениями для отправки сообщений на подключенные устройства, разработчики должны отправлять их через стороннюю службу обмена сообщениями, такую как обмен облачными сообщениями Firebase (FCM). Это просто зашифровать содержимое сообщений между разработчиком и службой обмена сообщениями с использованием HTTPS. Основные услуги обмена сообщениями, включая FCM, также шифруют сообщения между их серверами и клиентскими устройствами.

Тем не менее, сообщения между сервером разработчиков и пользовательскими устройствами не зашифрованы в скромные (E2E):

Нет E2EE

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

с капилляром

Капилляр обрабатывает эти операции для служб обмена сообщениями, используемых приложениями Android. Он включает в себя:

Функциональность крипто и управление ключами во всех версиях Android обратно в Kitkat (уровень API 19).
Ключевые поколения и регистрация рабочих процессов.
Шифрование сообщений (на сервере) и дешифрование (на клиенте).
Защита целостности для предотвращения изменения сообщения.
Крайные склады, такие как пользователи, добавляя/сброс блокировки устройства после установки приложения, сброс пользователей хранилища приложений и т. Д.

В качестве бонуса это также позволяет разработчикам требовать, чтобы устройства разблокировались, прежде чем выбранные сообщения могут быть расшифрованы. Это включает в себя сообщения на устройствах с использованием шифрования на основе файлов (FBE). Зашифрованные сообщения кэшируются в зашифрованном устройстве (DE) клавишах хранения, а уделка сообщений хранятся в Android-магазине, требующих аутентификации пользователя. Это позволяет разработчикам указать сообщения с конфиденциальным контентом, чтобы оставаться зашифрованными в кэшированной форме, пока пользователь не разблокирует и расшифровывает свое устройство.

Варианты API

Web Push против RSA-ECDSA

Веб -толчок
PRO: Следовательно, следует за IETF RFC 8291, поэтому позволяет разработчикам обмениваться кодом и ключевой инфраструктурой хранения с существующими реализациями веб -push. Протокол Web Push основан на алгоритме обмена ключами Elliptic Curve Diffie-Hellman (ECDH), который высокоэффективен для устройств с ограниченными характеристиками. Обратите внимание, что приложения (в отличие от браузеров) не могут получать необработанные веб -push -сообщения через FCM, но сообщения Web Push могут быть легко обернуты в соответствующий FCM JSON с помощью прокси -реализации, позволяя вам использовать ту же инфраструктуру с незначительными модификациями.
CON: Android Key Store не поддерживает операции ECDH. Клавики включены в гибридные зашифрованные с помощью клавиши RSA, хранящегося в магазине ключей, что означает, что открытый текст EC закрытого ключа доступен в пользовательской памяти во время криптографических операций.
RSA-ECDSA
PRO: Гибрид-закорочные средства-сообщение с общедоступным ключом RSA, созданным клиентом (для конфиденциальности), и подписывает шиферный текст с генерируемым разработчиком ECDSA Public Key (для целостности). Crypto Operations RSA (Encrypt, Decrypt) поддерживаются Android -магазином ключей из версий SDK 18 (желе) и выше, что означает, что ключевой материал не доступен за пределами доверенной среды исполнения. Это означает, что даже сложный злоумышленник с доступом к памяти устройства не может получить доступ к материалу частного ключа (например, для расшифровки будущих сообщений, прибывающих в режим прямого загрузки).
CON: менее эффективно, чем ECDH и клавиши, не совместимы со стандартом обмена сообщениями Web Push.

Автор против Ноат

Auth Bound Keys гарантирует, что сообщения не могут быть прочитаны пользователями, когда их устройство заблокировано, что означает, что конфиденциальное содержание не будет читаемым на плечах или если устройство будет потеряно или украдено.

Обзор API

Capillary предоставляет основную крипто -функциональность, необходимую для отправки (с сервера приложений) и получения зашифрованных push -сообщений в приложениях Android. Это покрывает:

Создание и хранение ключей на клиенте.
Шифрование и подпись сообщений на сервере.
Дешифрование и проверка зашифрованных сообщений на клиенте.
Определение зашифрованных сообщений, которые следует хранить для последующего, если получено, когда устройство заблокировано.

Поскольку серверные архитектуры и товарные сообщения обмена сообщениями многочисленны и разнообразны, не практично предоставлять API на стороне сервера для обработки всех возможных реализаций Push Message. Таким образом, мы отделили функциональность криптографии выше от передачи сообщений и функций хранения/поиска на стороне сервера. Однако мы предоставили полную реализацию, которая использует капилляр для отправки e2e-шифрованных Push-сообщений с сервера на основе Java для клиентов Android в демонстрационном приложении. Таким образом, вам нужно будет реализовать следующие аспекты решения самостоятельно (используя демонстрационную приложение и инструкции ниже для руководства, где это необходимо):

Зарегистрирование общедоступных ключей, сгенерированных капилляром с вашим сервером приложений.
(на сервере) Индексируя общедоступные ключи против ваших пользователей/устройств, чтобы вы могли легко извлечь их для шифрования сообщения.
Отправка сообщений зашифровано с использованием капилляров на устройства. Наше демонстрационное приложение использует FCM. Но капилляр также можно использовать с другими услугами обмена сообщениями.
Передача зашифрованных сообщений Push в капилляр для дешифрования.
Запрашивая капилляр для расшифровки любых кэшированных зашифров (то есть те, которые были получены во время заблокированного устройства), как только устройство находится в аутентифицированном контексте (то есть пользователи разблокировали экран).
Отображение или иное обращение с сообщениями, расширенные капиллярной библиотекой.

Интеграция API

Пожалуйста, выполните следующие шаги для интеграции с капиллярной библиотекой.

Предварительные условия

Прежде чем капиллярная библиотека могла быть использована, она должна быть инициализирована во время выполнения следующим образом:

 import com . google . capillary . Config ;

Config . initialize ();

Если вы используете алгоритм RSA-ECDSA, вам необходимо генерировать пару публичных/закрытых ключей ECDSA и сделать открытый ключ доступным для вашего приложения Android (например, в качестве необработанного ресурса) и закрытого ключа, доступным для вашего сервера приложений. Используйте коммунальную программу, которую мы предоставили для создания таких пар клавиш ECDSA:

$ ./gradlew tools:installDist
$ ./tools/build/install/tools/bin/ecdsa-key-pair-generator 
> --ecdsa_public_key_path= < path to new public key > 
> --ecdsa_private_key_path= < path to new private key >

На Android клиентов

Реализация капиллярного обработчика

Капиллярная библиотека использует методы интерфейса CapillaryHandler для предоставления ответов, таких как общественные ключи, расшифрованные равнины и т. Д., Возвращаясь к приложению Android. Таким образом, первым шагом в интеграции приложения Android с капиллярной библиотекой является реализация интерфейса CapillaryHandler с вашей логикой для конкретной приложения для обработки ответов, упомянутых выше. Вы можете увидеть, как демонстрационное приложение Android от капиллярной библиотеки реализует интерфейс CapillaryHandler в классе DemoCapillaryHandler .

Ключевое поколение

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

 import android . content . Context ;
import com . google . capillary . android . RsaEcdsaKeyManager ;
import com . google . capillary . android . WebPushKeyManager ;
import java . io . InputStream ;

Context context = ... // The current app context.
String keychainId = ... // Some identifier for the key pair.
boolean isAuth = ... // Whether the private key usage should be guarded by the device lock.

// To generate an RSA-ECDSA key pair.
InputStream senderVerificationKey = ... // The ECDSA public key of the server.
RsaEcdsaKeyManager . getInstance ( context , keychainId , senderVerificationKey ). generateKeyPair ( isAuth );

// To generate a Web Push key pair.
WebPushKeyManager . getInstance ( context , keychainId ). generateKeyPair ( isAuth );

Существует также метод GenerateKeypairs для генерации ключей Auth и Noauth в одном вызове метода.

Поиск общедоступного ключа

После создания пары капиллярных ключей вы можете получить сгенерированный открытый ключ в массиве байтов следующим образом:

 import android . content . Context ;
import com . google . capillary . android . CapillaryHandler ;
import com . google . capillary . android . RsaEcdsaKeyManager ;
import com . google . capillary . android . WebPushKeyManager ;
import java . io . InputStream ;

Context context = ... // The current app context.
String keychainId = ... // The identifier for the key pair.
boolean isAuth = ... // Whether the private key usage is guarded by the device lock.
CapillaryHandler handler = ... // An implementation of CapillaryHandler interface.
Object extra = ... // Any extra information to be passed back to the handler.

// To obtain an RSA-ECDSA public key.
InputStream senderVerificationKey = ... // The ECDSA public key of the server.
RsaEcdsaKeyManager . getInstance ( context , keychainId , senderVerificationKey )
    . getPublicKey ( isAuth , handler , extra );

// To obtain a Web Push public key.
WebPushKeyManager . getInstance ( context , keychainId ). getPublicKey ( isAuth , handler , extra );

// The Capillary library returns a byte array representing the Capillary public key via the
// handlePublicKey method of the CapillaryHandler instance.

Дешифрование

После получения зашифрованного текста, сгенерированного с использованием открытого ключа капилляра, вы можете расшифровать его следующим образом:

 import android . content . Context ;
import com . google . capillary . android . CapillaryHandler ;
import com . google . capillary . android . RsaEcdsaKeyManager ;
import com . google . capillary . android . WebPushKeyManager ;
import java . io . InputStream ;

byte [] ciphertext = ... // The ciphertext received through FCM.
Context context = ... // The current app context.
String keychainId = ... // The identifier for the key pair.
CapillaryHandler handler = ... // An implementation of CapillaryHandler interface.
Object extra = ... // Any extra information to be passed back to the handler.

// To decrypt a ciphertext and pass the plaintext to the CapillaryHandler instance,
// (e.g. for display to the user):

// For RSA-ECDSA:
InputStream senderVerificationKey = ... // The ECDSA public key of the server.
RsaEcdsaKeyManager . getInstance ( context , keychainId , senderVerificationKey )
    . getDecrypterManager (). decrypt ( ciphertext , handler , extra );

// For Web Push:
WebPushKeyManager . getInstance ( context , keychainId )
    . getDecrypterManager (). decrypt ( ciphertext , handler , extra );

// The Capillary library returns a byte array representing the plaintext via the handleData
// method of the CapillaryHandler instance.

Имейте в виду, что во время расшифровки библиотека капилляров может автоматически переосмыслить базовые пары капиллярных клавиш, если эти пары клавиш неверно повреждены, что может произойти, например, когда пользователь добавляет/сбрасывает блокировку устройства, сбрасывает приложение и т. Д. CapillaryHandler

Если Ciphertext был сгенерирован с использованием клавиши Auth, но устройство Android находится в неавенгшированном контексте, капиллярная библиотека внутренне сохраняет зашифрованный текст, который будет расшифрован позже, и информирует приложение Android с помощью метода AuthcipherTextSavedForLater. Это позволяет приложению Android обрабатывать кэшированные шифроты, например, сообщив, что сообщения пользователя доступны при разблокировке. После того, как пользователь разблокирует устройство, вы можете получить капиллярную библиотеку расшифровки любых сохраненных шифров.

 import android . content . Context ;
import com . google . capillary . android . CapillaryHandler ;
import com . google . capillary . android . RsaEcdsaKeyManager ;
import com . google . capillary . android . WebPushKeyManager ;
import java . io . InputStream ;

Context context = ... // The current app context.
String keychainId = ... // The identifier for the key pair.
CapillaryHandler handler = ... // An implementation of CapillaryHandler interface.
Object extra = ... // Any extra information to be passed back to the handler.

// To decrypt saved ciphertexts and pass the plaintexts to the CapillaryHandler instance,
// (e.g. for display to the user):

// For RSA-ECDSA:
InputStream senderVerificationKey = ... // The ECDSA public key of the server.
RsaEcdsaKeyManager . getInstance ( context , keychainId , senderVerificationKey )
    . getDecrypterManager (). decryptSaved ( handler , extra );

// For Web Push:
WebPushKeyManager . getInstance ( context , keychainId )
    . getDecrypterManager (). decryptSaved ( handler , extra );

// For each decrypted ciphertext, the Capillary library returns a byte array representing the
// plaintext via the handleData method of the CapillaryHandler instance.

Есть несколько способов запустить обработчик для кэшированного зашифрованного текста при разблокировке устройства. Подход, используемый в приложении Android от капиллярной библиотеки, предназначен для прослушивания намерения Action_user_present. См. DeviceUnlockedBroadcastReceiver для получения более подробной информации.

Ключевое удаление

Чтобы удалить пару капиллярных ключей:

 import android . content . Context ;
import com . google . capillary . android . RsaEcdsaKeyManager ;
import com . google . capillary . android . WebPushKeyManager ;
import java . io . InputStream ;

Context context = ... // The current app context.
String keychainId = ... // The identifier for the key pair.
boolean isAuth = ... // Whether the private key usage is guarded by the device lock.

// To delete an RSA-ECDSA key pair.
InputStream senderVerificationKey = ... // The ECDSA public key of the server.
RsaEcdsaKeyManager . getInstance ( context , keychainId , senderVerificationKey ). deleteKeyPair ( isAuth );

// To delete a Web Push key pair.
WebPushKeyManager . getInstance ( context , keychainId ). deleteKeyPair ( isAuth );

На Java -Servers

Капиллярная библиотека обеспечивает функциональность для шифрования сообщений на серверах приложений на основе Java.

Шифрование

Чтобы зашифровать сообщение с использованием капиллярного открытого ключа:

 import com . google . capillary . EncrypterManager ;
import com . google . capillary . RsaEcdsaEncrypterManager ;
import com . google . capillary . WebPushEncrypterManager ;
import java . io . InputStream ;

byte [] recipientPublicKey = ... // The Capillary public key of the client.
byte [] message = ... // The message to be sent to the client.

// To create an RSA-ECDSA ciphertext.
InputStream senderSigningKey = ... // The ECDSA private key of the server.
EncrypterManager rsaEcdsaEncrypterManager = new RsaEcdsaEncrypterManager ( senderSigningKey );
rsaEcdsaEncrypterManager . loadPublicKey ( recipientPublicKey );
byte [] ciphertext = rsaEcdsaEncrypterManager . encrypt ( message );
// This step is not strictly necessary, but it ensures that the EncrypterManager releases the
// stored public key for garbage collection.
rsaEcdsaEncrypterManager . clearPublicKey ();

// To create a Web Push ciphertext.
EncrypterManager webPushEncrypterManager = new WebPushEncrypterManager ();
webPushEncrypterManager . loadPublicKey ( recipientPublicKey );
byte [] ciphertext = webPushEncrypterManager . encrypt ( message );
webPushEncrypterManager . clearPublicKey ();