Встраивание КриптоПро Ключ SDK в мобильное приложение (Android)

Руководство по встраиванию содержит перечень действий, необходимых для встраивания КриптоПро Ключ SDK в собственное мобильное приложение.

Инструкция предназначена для разработчиков мобильных приложений для Android версии 7 и новее. Требуется уровень Android API 24 и выше (minSdkVersion 24, targetSdkVersion 34).

Добавление необходимых файлов в проект

Перейдите в каталог необходимого модуля (уровень приложения). Создайте папку libs. Скопируйте в папку libs файлы:

SharedLibrary.aar
csp-gui.aar
JInitCSP.aar
dssclient-1.1.XXXX-release.aar

В разделе dependencies файла build.gradle добавьте:

implementation fileTree(dir: 'libs', include: ['*.jar', '*.aar'])

В разделе android packagingOptions файла build.gradle добавьте следующее:

packagingOptions {
    exclude 'META-INF/Digest.CP'
    exclude 'META-INF/Sign.CP'
    exclude 'META-INF/NOTICE.txt'
    exclude 'META-INF/LICENSE.txt'
    doNotStrip "*/arm64-v8a/*.so"
    doNotStrip "*/armeabi-v7a/*.so"
    doNotStrip "*/x86_64/*.so"
    doNotStrip "*/x86/*.so"

    jniLibs {
        useLegacyPackaging true
    }
}

Добавьте следующие зависимости, которые используются в КриптоПро Ключ SDK:


/**
* Базовые библиотеки и библиотеки для UI
*/
implementation 'androidx.appcompat:appcompat:1.6.1'
implementation 'com.google.android.material:material:1.6.1'
implementation 'androidx.webkit:webkit:1.5.0'

/**
* Библиотеки для работы с Rest Api
*/
implementation 'com.squareup.retrofit2:retrofit:2.9.0'
implementation 'com.squareup.okhttp3:logging-interceptor:4.8.0'
implementation 'com.squareup.retrofit2:converter-gson:2.9.0'
implementation 'com.squareup.retrofit2:converter-scalars:2.9.0'

/**
* Библиотеки для сериализации/десериализации в/из JSON
*/
implementation 'com.fasterxml.jackson.core:jackson-databind:2.12.2'
implementation 'com.google.code.gson:gson:2.8.6'

/**
* Библиотека для работы с преобразованиями
*/
implementation 'com.google.guava:guava:30.1-jre'

/**
* Библиотека для работы с QR
*/
implementation 'com.google.mlkit:barcode-scanning:17.2.0'

def camerax_version = "1.2.3"
implementation "androidx.camera:camera-core:${camerax_version}"
implementation "androidx.camera:camera-camera2:${camerax_version}"
implementation "androidx.camera:camera-lifecycle:${camerax_version}"
implementation "androidx.camera:camera-view:${camerax_version}"

implementation 'androidx.lifecycle:lifecycle-extensions:2.2.0'
implementation 'androidx.lifecycle:lifecycle-common-java8:2.4.1'

implementation 'androidx.biometric:biometric:1.1.0'

/**
* Библиотека для работы с pdf файлами
*/
implementation 'com.tom-roush:pdfbox-android:1.8.10.3'

/**
* Библиотека для отображения изображения, которое можно скейлить и скроллить
*/
implementation 'com.jsibbold:zoomage:1.3.1'

/**
* Root
*/
implementation 'com.github.scottyab:rootbeer:0.1.0'

/**
* Конфигурация CSP
*/
implementation 'org.ini4j:ini4j:0.5.1'

Поддержка Рутокен NFC

Для встраивания Рутокен NFC необходимо добавить в зависимости библиотеку rtpcscbridge:

implementation 'ru.rutoken.rtpcscbridge:rtpcscbridge:1.1.1'

Настройка манифеста приложения

Откройте манифест проекта AndroidManifest.xml. В манифесте в application добавить свойство extractNativeLibs=true:

<application
    ...
    android:extractNativeLibs="true">
    ...
</application>

Настройка правил минимизации и обфускации

Если в проекте используются инструменты минификации и обфускации proguard или D8, то для корректной работы библиотеки в файл правил proguard (например, proguard-rules.pro) необходимо добавить следующие ограничения:

-keep public class com.digt.sdk.** { *; }
-dontwarn com.digt.sdk.**
-keep public class ru.CryptoPro.** { *; }
-dontwarn ru.CryptoPro.**
-keep public class ru.cprocsp.** { *; }
-dontwarn ru.cprocsp.**
-keep public class org.ini4j.spi.** { *; }
-dontwarn org.ini4j.spi.**

При отсутствии файла proguard-rules.pro в проекте его необходимо создать и добавить в конфигурацию конечной сборки в файле build.gradle:

buildTypes {
    release {
        minifyEnabled true
        proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
        proguardFiles fileTree('proguard').asList().toArray()
    }
    debug {
        minifyEnabled false
        debuggable true
    }
}

Настройка файлового провайдера

UI SDK предоставляет возможность скачать подписываемые (обрабатываемые) документы.

Добавьте файл file_provider_name.xml в ресурсы вашего приложения res/xml.
Укажите в файле file_provider_name.xml идентификатор файлового провайдера - например your_bundle_id.fileprovider.

Настройка корневых сертификатов

Для выполнения защищенных сетевых запросов SDK требуется корневой сертификат, до которого строится цепочка проверки TLS-сертификата сервера. Корневой сертификат должен размещаться в ресурсах приложения.

В ресурсы приложения добавьте файл certs.json. Формат содержимого файла:

{
    "version":1,
    "root": [
    "MIIERDCCA/GgAwIBAgIQQ ... UJYu+Pih2ROUYAYQjPIw==",
    ...
    "MIIFUTCCBP6gAwIBAgIRA ... fYGtCrq1l5FsXZOI5c/2S"],
    "intermediate":[]
}

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

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

private fun initDss() {
    if (!CryptoProDss.isInitialized()) {
        CryptoProDss.init(requireActivity(),object : SdkCryptoProDssInitCallback{
            override fun onInitSuccess(p0: Constants.CSPInitCode?) {

                // TODO: успешная инициалзиация. Можно работать с SDK
                //viewModel.notifyInitializationEnded()
            }

            override fun onInitFailed(p0: Constants.CSPInitCode?) {

                // TODO: произошла ошибка инициализации SDK
                //viewModel.notifyInitializationEnded()
            }
        })
    } else {
        // TODO: SDK уже был инициализирован   
        // viewModel.notifyInitializationEnded()
    }
}

Метод инициализации SDK может отобразить экран безопасности. На экране будет отображён список предупреждений, которые могут повлиять на безопасное использование SDK. Пользователь на экране безопасности может согласиться или отказаться использовать функции SDK.

Примечание

Экран безопасности не будет отображен, если SDK не обнаружит угроз безопасности или пользователь на экране нажмёт кнопку "не напоминать".

Метод init не блокирует main поток. Если метод отобразил экран безопасности, то пока пользователь не ответит на диалог SDK не вернется в callback.

В приложении рекомендуется дождаться завершения метода init до использования других методов SDK. При попытке вызова методов неинициализированного SDK будет получена ошибка NOT_SAFE_USAGE_CANCELLED_BY_USER.

Тестовый пример проекта

Загрузить тестовый проект