otaman/README_RUS.md

OTAMan — SIM OTA toolkit: PWA + локальный сервер карт

OTAMan — автономный offline-PWA (HTML/JS) для создания APDU-команд (SIM, USIM, GlobalPlatform RAM), сборки защищённых пакетов SCP80 по ETSI TS 102 225 и построения Expanded Remote Application data format APDU по ETSI TS 102 226. В комплекте — pysim-otaman-server — локальный HTTP-сервер поверх pySim для работы с картой: файловый менеджер, сырые APDU, меню SIM Toolkit и доставка OTA.

Демо: otaman.atroshin.ru — только PWA, для экспериментов. Для функций картридера установите сервер (ниже).

Быстрый старт

Только PWA (клиентские функции): откройте frontend/index.html в любом браузере или раздайте frontend/ любым статическим сервером. Python не нужен.

Полная установка (PWA + сервер карт):

git clone https://github.com/anttro/otaman.git
cd otaman
./setup.sh     # или setup.bat в Windows — создаёт .venv, ставит pysim + сервер
./start.sh     # или start.bat — запускает сервер (он же раздаёт PWA)

Затем откройте http://127.0.0.1:8080 — интерфейс и API на одном origin, поэтому CORS и разрешения браузера не нужны.

Сборка

Для стилей используется Tailwind CSS. После клонирования пересоберите CSS:

cd frontend
npm install
npm run build

Интерфейс

Четыре вкладки: C-APDU, SCP80, Response parser, Card reader. Вкладки C-APDU и SCP80 имеют подвкладки.

---

Вкладка C-APDU

Построение команд APDU (C-APDU). Пять подвкладок для разных поколений карт и наборов команд.

SIM RFM

CLA = A0 (GSM 11.11 / ISO 7816-4).

Команды

Команда	INS	Описание
SELECT	A4	Выбор EF/DF по FID, пути, dfname или цепочке
UPDATE RECORD	DC	Обновление записи
UPDATE BINARY	D6	Обновление бинарных данных
READ RECORD	B2	Чтение записи
READ BINARY	B0	Чтение бинарных данных
ERASE BINARY	0E	Стирание бинарных данных
ACTIVATE FILE	44	Активация файла
DEACTIVATE FILE	04	Деактивация файла
VERIFY PIN	20	Проверка PIN1 или PIN2
CHANGE PIN	24	Смена PIN1 или PIN2

Методы SELECT

Метод	P1	P2	Ввод
By FID	00	00	FID (4 hex)
By full path from MF	08	00	Полный путь от MF
By DF name / AID	04	00	AID
ADF RFM chain	00	00	FID через запятую

Опции

• Start with SELECT — добавить SELECT перед командой.
• Selection mode (P2) — для record-команд: Absolute (04), Next (06), Previous (02).
• Record size — дополнить/обрезать данные до указанного размера.
• Allow P1/P2 editing — ручное редактирование P1/P2.

Ссылки

• ISO/IEC 7816-4: Organization, security and commands for interchange
• ETSI TS 102 226: Remote APDU structure for UICC based applications
• GSM 11.11: SIM-ME Interface

USIM RFM

CLA = 00 (ETSI TS 102 221). Те же команды, что и SIM, но SELECT использует P1=09, P2=0C.

Ссылки

• ETSI TS 102 221: UICC-Terminal Interface
• ETSI TS 102 226: Remote APDU structure

Expanded Script

Построение Expanded Remote Application data format по ETSI TS 102 226 §5.2.1.

Формат

• Definite (AA): AA + длина + Command TLV
• Indefinite (AE): AE + 80 + Command TLV + 00 00

Command TLV

Тип	Тег	Описание
C-APDU	22	APDU
Immediate Action	81	Proactive-команда или action indicator
Error Action	82	Proactive-команда при ошибке
Script Chaining	83	Данные для многопакетных скриптов

Сборщик Immediate Action

• Action indicator: 81 / 82
• Proactive command: REFRESH, DISPLAY TEXT, PLAY TONE
• Custom hex: ручной ввод

Ссылки

• ETSI TS 102 226 §5.2.1
• ETSI TS 102 223: Card Application Toolkit
• ETSI TS 101 220: BER-TLV tag assignments

RAM/GP

CLA = 80 (GlobalPlatform v2.3.1). Удалённое управление содержимым карты через SCP80.

Справочник GP-команд

Команда	INS	P1	Описание
INSTALL [for load]	E6	02	Регистрация загружаемого файла
INSTALL [for install]	E6	0C	Установка приложения или SD
INSTALL [for make selectable]	E6	10	Сделать приложение выбираемым
INSTALL [for registry update]	E6	01	Обновление реестра
INSTALL [for extradition]	E6	04	Перемещение между SD
LOAD	E8	00	Загрузка кода
DELETE	E4	00/80	Удаление приложения или SD
GET STATUS	F2	80/40/20/10	Статус карты
GET DATA	CA	tag	Чтение объектов данных
STORE DATA	E2	00/40/80/C0	Запись данных
SET STATUS	F0	80/40/60	Управление жизненным циклом
EXTERNAL AUTHENTICATE	82	00	Аутентификация SCP
INTERNAL AUTHENTICATE	88	00	Challenge-response

Привилегии (INSTALL [for install])

Три байта привилегий по GP Spec Tables 11-7, 11-8, 11-9.

Байт 1:

Бит	Привилегия
b8	Security Domain
b7	DAP Verification
b6	Delegated Management
b5	Card Lock
b4	Card Terminate
b3	Card Reset
b2	CVM Management

Байт 2:

Бит	Привилегия
b8	Trusted Path
b7	Authorized Management
b6	Token Verification
b5	Global Delete
b4	Global Lock
b3	Global Registry
b2	Final Application

Байт 3:

Бит	Привилегия
b8	Receipt Generation

Параметры SIM/UICC Toolkit

• Tag CA (SIM Toolkit): Priority, Timers, Text Length, Menu Entries, Positions, Channels, MSL, TAR, Access Domain
• Tag 80 (UICC Toolkit, внутри EA): те же поля без Access Domain

MSL (Minimum Security Level):

Значение	Описание
00	Нет проверки
11	RC/CC/DS
12	RC/DS/CC
15	RC/DS/CC + MAC
16	RC/DS/CC + MAC + Cipher
19	RC/DS/CC + MAC + Cipher + DS

GET STATUS P1

Значение	Описание
80	Issuer Security Domain (ISD)
40	Applications и SSD
20	Executable Load Files
10	ELF и модули

GET STATUS P2

Значение	Описание
40	Первые/все, GP TLV (по умолчанию)
42	Следующие, GP TLV
00	Первые/все, старый формат (deprecated)
02	Следующие, старый формат (deprecated)

GET DATA теги

Тег	Объект данных
42	Issuer Identification Number (IIN)
45	Card Image Number (CIN)
66	Card Data / SD Management Data
67	Card Capability Information
E0	Key Information Template
D3	Current Security Level
2F00	List of Applications
FF21	Extended Card Resources Info
5F50	SD Manager URL
C1	Sequence Counter (SCP02/03)
C2	Confirmation Counter
7F21	Certificate (SD public key)
5031	Certificate info (EF.OD)

DELETE P1

Значение	Описание
00	Только AID
80	AID и связанные объекты

STORE DATA P1

Значение	Описание
00	Последний блок, без шифрования
40	Ещё блоки, без шифрования
80	Последний блок, с шифрованием
C0	Ещё блоки, с шифрованием

SET STATUS

P1: 80 = ISD, 40 = Приложение или SSD, 60 = SD и его приложения

P2: 00 = Разблокировать, 80 = Заблокировать (LOCKED)

Ссылки

• GlobalPlatform Card Specification v2.3.1
• ETSI TS 102 226 §8.2.1.3.2: Параметры SIM/UICC Toolkit

Конвертация (боковые панели SIM/USIM)

IMSI → EF.IMSI

15-значный IMSI → 9 байт EF.IMSI.

MSISDN → BCD

Удаление +, добавление f, обмен полубайтов.

ICCID → hex

Обмен полубайтов строки ICCID.

Provider Name → SPN

По 3GPP TS 31.102 §4.2.5. Три варианта кодирования:

1. GSM 7-bit packed
2. UCS2 non-BMP
3. UCS2 BMP non-GSM7

PLMN → EF_PLMNsel / PLMNwAcT

3-байтное BCD-кодирование + опциональный Access Technology.

Nibble swap

Обмен полубайтов hex-строки.

Ссылки

• 3GPP TS 31.102
• 3GPP TS 23.038
• ETSI TS 102 225
• pySim: enc_imsi()

---

Вкладка SCP80

Вкладка SCP80 группирует SCP80-виды, переключаемые тремя пиллами: Secured Packet, Cards и RAM. Сборка защищённых пакетов по ETSI TS 102 225.

Secured Packet

Сборка защищённых пакетов SCP80 по ETSI TS 102 225.

Структура пакета

Поле	Размер	Описание
CPI	1	Command Packet Identifier (02)
CPL	1	Command Packet Length
CHI	1	Command Header Identifier (01)
CHL	1	Command Header Length
SPI	2	Security Parameter Indicator
KIc	1	Key Identifier для шифрования
KID	1	Key Identifier для MAC
TAR	3	Toolkit Application Reference
CNTR	5	Счётчик повторов
PCNTR	1	Padding counter
RC/CC/DS	8	Контрольная сумма / MAC
Secured Data	переменная	APDU (с шифрованием при необходимости)

SPI1 (Уровень безопасности)

Битовое поле SPI1 (TS 102 225 §5.1.1): b8–b6 — паддинг, b5–b4 — счётчик, b3 — шифрование, b2–b1 — RC/CC/DS.

Значение	Безопасность	Шифрование	Счётчик (b5 b4)
00	Нет	Нет	00 нет
01	RC	Нет	00 нет
02	CC/MAC	Нет	00 нет
06	CC/MAC	Да	00 нет
0A	CC/MAC	Нет	01 available
0E	CC/MAC	Да	01 available
12	CC/MAC	Нет	10 higher
16	CC/MAC	Да	10 higher
1A	CC/MAC	Нет	11 +1
1E	CC/MAC	Да	11 +1

AES требует b5 b4 = 10 (higher) или 11 (+1) согласно TS 102 225 §5.1.2 и §5.1.3.1. Значения 00/01/02/06 (без счётчика) допустимы только для 3DES.

SPI2 (PoR)

Значение	Режим
00	No PoR
01	PoR required, no security
05	PoR required, RC
09	PoR required, CC
0D	PoR required, DS
11	PoR required, ciphered
02	PoR on error, no security
06	PoR on error, RC

Крипто

• 3DES-CBC шифрование, ключи 8/16/24 байт — устарело с Rel-18, но поддерживается для обратной совместимости
• AES-CBC шифрование (нулевой ICV, дополнение нулями до 16), ключи 16/24/32 байта (TS 102 225 §5.1.2, KIc x2)
• Retail MAC (ISO 9797-1 MAC algorithm 3) для DES/3DES
• AES-CMAC (NIST SP 800-38B, усечённый до 8 октетов) для AES (TS 102 225 §5.1.3.1, KID x2)
• Padding byte: 00 (по умолчанию) или FF

PoR (Proof of Reception)

PoR подтверждает, что карта получила и выполнила защищённый пакет. Два режима:

SPI2 (бит 5)	Режим	Описание
0x00	Delivery PoR	PoR возвращается в ответе ENVELOPE (SW+данные)
0x20	Submit PoR	PoR отправляется обратно как SMS-SUBMIT через прокоманду FETCH

Delivery PoR (SPI2 01) проще — карта возвращает PoR напрямую в ответе ENVELOPE. Submit PoR (SPI2 21) используется, когда карта не может ответить inline (ограничено пространство ответа ENVELOPE).

Ссылки

• ETSI TS 102 225 V18.1.0
• ETSI TS 102 226
• ISO 9797-1
• NIST SP 800-38B (CMAC)

Cards

Пилл Cards управляет сохранёнными конфигурациями карт (пресеты). Каждый пресет хранит криптографические ключи, настройки TAR и счётчик повторов для SCP80-операций.

Поле	Описание
SPI1 / SPI2	Уровень безопасности и настройки PoR
Ключ KIc / KID	Hex ключи шифрования и MAC
Индекс KIc / KID	Номер версии ключа
TAR	Toolkit Application Reference (3 байта)
Счётчик (CNTR)	10-значный hex счётчик повторов, автоматически увеличивается после каждой успешной отправки SCP80

Добавить карту: заполните имя, SPI1/SPI2, ключи KIc/KID и их индексы, TAR, нажмите Add. Карта появится в списке и станет доступна в выпаданом списке Card preset на RAM-вкладке.

Редактировать карту: выберите карту в списке, измените поля, нажмите Save.

Удалить карту: выберите карту, нажмите Delete. Удаляет пресет из localStorage.

Счётчик: 10-значный hex-счётчик (CNTR) автоматически увеличивается после каждой успешной отправки SCP80 (ручные отправки Secured Packet и RAM-операции). Обновлённый счётчик автоматически сохраняется обратно в пресет.

RAM

Все операции RAM отправляются как защищённые пакеты SCP80 (ETSI TS 102 225) через SMS-PP-DOWNLOAD ENVELOPE. Карта должна поддерживать SCP03 (AES или 3DES) для безопасной транспортировки.

Выберите сохранённую конфигурацию карты из выпадающего списка Card preset. Если пресет не выбран, RAM-вкладка предупреждает и отказывается выполнять.

В RAM-подвкладке доступны две операции через выпадающий список Operation:

Операция	Описание
Explore Card (all GP data)	Запрос GET STATUS для ISD, приложений, ELF и модулей ELF, а также GET DATA FF21 для информации о памяти. Результаты отображаются в обзоре с кнопками Delete для каждого элемента.
Install Package (.cap file)	Отправка .cap файла на карту через сервер: INSTALL[for load] → LOAD ×N → INSTALL[for install (+make selectable)].

Обзор карты (Explorer View)

После выполнения "Explore Card" отображается:

• ISD — AID, жизненный цикл, привилегии (без удаления; ISD нельзя удалить)
• Приложения — AID, жизненный цикл, привилегии, связанный ELF/SD. Каждое имеет кнопку Delete (GP DELETE по AID).
• Executable Load Files — AID, жизненный цикл, версии, AID модулей. Каждый имеет Delete (только ELF) и Delete All (каскадное: ELF + модули + установленные приложения, P2=0x80).

Удаление подтверждается через диалог браузера перед отправкой команды GP DELETE через SCP80. Обзор автоматически обновляется после успешного удаления.

---

Вкладка Response parser

Декодирование ответа команды: выберите отправленную команду, введите SW (например, 9000) и данные ответа в hex, затем нажмите Decode.

• Команда — группа SIM/USIM (SELECT, STATUS, READ/UPDATE, операции с PIN, CAT-команды TERMINAL PROFILE/ENVELOPE/FETCH/TERMINAL RESPONSE, MANAGE CHANNEL, ...) или группа RAM/GP (INSTALL, LOAD, DELETE, GET/STORE DATA, аутентификация, команды SCP).
• Декодирование SW — статусные слова по картам generic, UICC (TS 102 221) и GlobalPlatform с автоопределением контекста.
• Декодирование привилегий — байты привилегий из ответов GET DATA / INSTALL в читаемые флаги.
• Данные ответа — hex с интерпретацией по команде (например, шаблоны FCP из SELECT).

---

Card Reader (интеграция с pySim)

Подключение к встроенному pysim-otaman-server для работы с картой.

Ограничение браузера: если PWA раздаётся с публичного HTTPS-хоста, для доступа к локальному серверу (http://127.0.0.1:8080) нужны два условия: сервер должен отправлять Access-Control-Allow-Private-Network: true (pysim-otaman-server ≥ 1.6.1 делает это автоматически), и браузеру должно быть разрешено обращаться к локальной сети — в Chrome/Edge/Vivaldi: Настройки сайта → Доступ к локальной сети → разрешить сайт (или подтвердить запрос). Без разрешения браузера запрос к 127.0.0.1 блокируется ещё до отправки preflight.

Файловый менеджер

Дерево файлов UICC. Отображаются имена, FID и AID (для ADF). Клик для чтения содержимого.

• Read — чтение файла (автоопределение transparent/record)
• Edit — режим редактирования, измените hex-данные и нажмите Save для записи
• Raw / Decoded — переключение между hex-дампом и декодированным JSON

Пользовательские файлы

Файлы, отсутствующие в модели pysim, можно добавить вручную:

1. Перейдите на вкладку Custom files
2. Введите путь (например, 3F00/6F46) и псевдоним (например, EF.SPN)
3. Нажмите Add — файл появится в дереве курсивом (непроверенный)
4. Кликните для проверки существования — при успехе работает как обычный файл

Пользовательские файлы сохраняются в localStorage. Экспорт/импорт в JSON для обмена.

Proactive UICC

Подраздел Proactive UICC во вкладке Card Reader обеспечивает взаимодействие с CAT-сессией в реальном времени:

Subscribed Events — список событий SET UP EVENT LIST с кнопками Send. Клик открывает форму для конкретного типа события:

• События без данных (User Activity, Idle Screen и др.) — однократное уведомление
• Location Status — выпадающий список: Normal / Limited / No service
• Access Technology Change — 13 типов RAT
• Network Rejection — полная адаптивная форма: тип регистрации (LU / GPRS / EPS / 5GS), поля локации (MCC, MNC, LAC, RAC, TAC), доступные технологии, 53-позиционный выпадающий список причин отказа (EMM, GMM, 5GMM, LU)

Proactive Command Log — хронологический список проактивных команд. Каждая строка показывает время, код типа, имя и декодированный квалификатор.

PLI Data Dictionary — редактируемые hex-значения для всех 22 квалификаторов PROVIDE LOCAL INFORMATION (TS 102 223 + TS 131 111). 10 квалификаторов имеют встроенные формы декодирования/кодирования:

Код	Декодированные поля
00	MCC, MNC, LAC/TAC
01	IMEI (15 цифр)
03	Дата, время, TZ
04	Язык (2-символьный код)
05	ME Status, Timing Advance
06	Access Technology (выпадающий список)
08	IMEISV (16 цифр)
09	Search Mode (Auto/Manual)
0A	Battery charge (%)
0E	Multiple Access Technologies (список через запятую)

Значения сохраняются на сервере до перезапуска. Apply → hex обновляется; Save → POST на сервер.

Подсказки команд

Введите имя команды в pySim command line. Подсказки по использованию появляются через 300 мс. Автодополнение команд — над полем ввода.

---

PWA

OTAMan — Progressive Web App. Можно установить для offline-использования через кнопку INSTALL PWA или через браузер.

• Service worker кеширует все ресурсы при первом посещении
• Иконки 192×192 и 512×512

Тема

Тёмная тема поддерживается. Следует системной теме, переключается вручную кнопкой (🌙/☀️). Выбор сохраняется в localStorage.

Локализация

Интерфейс на английском с поддержкой русского языка. Язык определяется из navigator.language. Кнопка переключения (EN/RU) в заголовке сохраняет выбор в localStorage.

Совместимость версий

PWA (OTAMan)	Сервер	Статус
1.x.x	1.x.x	✅ Совместимы
1.x.x	0.x.x	❌ Сервер устарел
1.x.x	2.x.x+	⚠️ Сервер новее — обновите PWA

PWA проверяет версию сервера при подключении через GET /api/version.

---

Сервер (pysim-otaman-server)

Встроенный Python-сервер оборачивает pySim и раздаёт как PWA (из frontend/), так и JSON API по /api/*.

Требования

• Python 3.8+ с pip, и Git
• Смарт-картридер (PC/SC или serial/FTDI) — предпочтителен PC/SC (pcsc-lite + ccid на Linux)
• Windows — используйте Python 3.10–3.13 (рекомендуется 3.13): у pyscard есть готовые wheel. На 3.9 / 3.14 он собирается из исходников (нужны MSVC C++ Build Tools). SMPP-мост (smpp.twisted3) в Windows сознательно не ставится.

Скрипты

Скрипт	Назначение
setup.sh / setup.bat	Создаёт .venv/, ставит pysim и сервер. Запускать один раз после клонирования.
start.sh / start.bat	Запускает сервер из venv (раздаёт PWA + API на :8080).

start.sh автоопределяет ридер (PC/SC при работающем pcscd, иначе /dev/ttyUSB0); start.bat всегда использует -p 0. Без ридера сервер всё равно стартует («Reader: none») — карту можно инициализировать позже кнопкой Equip.

Ручная установка

python3 -m venv .venv
source .venv/bin/activate          # Linux/macOS   (Windows: .venv\Scripts\activate)
pip install git+https://github.com/osmocom/pysim.git
pip install -e .                   # editable — раздаёт frontend/ из исходного дерева
pysim-otaman-server --http-port 8080

Параметры CLI

Параметр	Описание
--http-host	Адрес привязки (по умолчанию 127.0.0.1)
--http-port	Порт (по умолчанию 8080)
--web-dir	Каталог со статикой PWA (по умолчанию <repo>/frontend)
-p / --pcsc-device	Номер слота PC/SC
-d / --device	Путь к serial-устройству
--no-card-init	Пропустить инициализацию карты (сохранить CAT-сессию)
--apdu-trace	Лог APDU-трафика в stderr
--log-requests	Лог запросов/ответов в stderr
--poll-interval	Интервал автоопроса STATUS (по умолчанию 30с)

Устранение неполадок

• "Failed to establish context: Access denied" — pcscd не запущен или нет прав: sudo systemctl enable --now pcscd && sudo usermod -a -G pcscd $USER.
• "device file /dev/ttyUSB0 does not exist" — нет serial-ридера; подключите USB-ридер или укажите -d. Сервер всё равно стартует без ридера.

Справочник API

Полный справочник endpoints: docs/api.md.