Posted on 03.02.2016 in

Загальні відомості

Програмний інтерфейс плагіна передбачає виклик асинхронних операцій, реалізованих з урахуванням об'єктів promise. Докладніше про використану в реалізації плагіна специфікацію можна прочитати. На promise необхідно встановлювати обробники двох типів:

onFulfilled– спрацьовують, коли promise може «виконаний успішно»;
onRejected– спрацьовують, коли promise може «завершено з помилкою».

Універсальний метод для встановлення обробників має такий вигляд: promise.then(onFulfilled, onRejected)

Ініціалізація плагіна

Для роботи з плагіном необхідно викликати функцію ініціалізації PKCS#11-компонента plugin.initPKCS11. Ця функція як параметри приймає перелік назв модулів (як масиву). Перелік передбачених модулів можна переглянути. Якщо модулі не вказані, плагін здійснить ініціювання всіх модулів.
При необхідності вказати, які криптопровайдери слід використовувати при роботі модуля capi, слід використовувати наступний формат запису:

Capi:(prov1),(mode):(prov2),(mode)

У цьому записі:

prov1, prov2 – назва криптопровайдера. В даний час підтримуються такі значення:

Crypto-Pro GOST R 34.10-2001 Cryptographic Service Provider;
Crypto-Pro GOST R 34.10-2012 Cryptographic Service Provider;
Crypto-Pro GOST R 34.10-2012 Strong Cryptographic Service Provider;
Signal-COM CPGOST Cryptographic Provider;
Signal-COM GOST R 34.10-2012 (256) Cryptographic Provider;
Signal-COM GOST R 34.10-2012 (512) Cryptographic Provider;
Infotecs Cryptographic Service Provider.

mode – режим відображення вікна введення пін-коду. Може приймати такі значення:

0 – режим за замовчуванням, передбачений криптопровайдером;
1 – відображення нативного вікна криптопровайдера.
Примітка: під час роботи з Crypto-Pro у Linux відображення нативного вікна криптопровайдера недоступне.
2 – відображення вікна в інтерфейсі плагіна.
Примітка: під час використання Signal-COM відображення вікна в інтерфейсі плагіна недоступне.

Для отримання ключів із системного сховища Windows слід як провайдер вказати , а як режим - My.
Приклад ініціювання всіх модулів:

Plugin.initPKCS11(["ISBC ESMART", "Aladdin R.D. Unified JaCarta", "Rutoken", "SafeNet", "capi:Crypto-Pro GOST R 34.10-2001 Cryptographic Service Provider,0:Crypto-Pro GOST R 3421 Cryptographic Service Provider,0:Crypto-Pro GOST R 34.10-2012 Strong Cryptographic Service Provider,0:Signal-COM CPGOST Cryptographic Provider,0:Signal-COM GOST R 34.10-2012 (256) Cryptographic Provider,0 R 34.10-2012 (512) Cryptographic Provider,0:Infotecs Cryptographic Service Provider,0: ,My"])

Приклад ініціювання модуля для отримання ключів із системного сховища Windows:

Plugin.initPKCS11(["capi: ,My"])

При успішній ініціалізації функція повертає об'єкт (тут і далі – за допомогою механізму promise), що має функції modules та getCertsForSign.

Перегляд переліку модулів та їх стану

Для перегляду переліку модулів та їх стану необхідно викликати функцію modules.
Приклад запиту:

Pkcs11.modules.then(onFulfilled, onRejected);

Приклад відповіді функції (розриви дано для зручності читання):

[ ( "enable": true, "name": "Aladdin R.D. Unified JaCarta" ), ( "enable": true, "name": "Rutoken ECP" ), ( "enable": false, "error": "100 :failed to load p11 module", "name": "ISBC ESMART" ] ]

Перегляд списку сертифікатів

Для перегляду списку виявлених сертифікатів необхідно викликати функцію getCertsForSign. Як параметр виклику функції необхідно вказати, чи слід використовувати паралельний режим опитування ініціалізованих PKCS#11 модулів:

true– паралельне звернення до модулів (рекомендований режим);
false- Послідовне звернення до модулів.

Перелік сертифікатів є масивом (JavaScript Array), елементами якого є об'єкти сертифікатів. На об'єкті сертифіката можна виконати функції full_info, cms_sign_on_it та start_signing.

Перегляд даних про конкретний сертифікат

Для перегляду даних про конкретний сертифікат необхідно викликати властивість full_info , що повертає відомості про сертифікат у вигляді об'єкта json. Він включає наступні параметри:

sn– серійний номер сертифікату;
subject– дані про суб'єкта, якому видано даний сертифікат електронного підпису. Повертається у вигляді json у форматі параметр: значення, де параметр – це назва відповідного об'єктного ідентифікатора (OID). Всім стандартним об'єктним ідентифікаторам надано загальноприйняті позначення, наприклад, CN (Common Name).
issuer– дані про видавця сертифіката ключа електронного підпису. Повертається у вигляді json у форматі параметр: значення, де параметр – це назва відповідного об'єктного ідентифікатора (OID). Всім стандартним об'єктним ідентифікаторам надано загальноприйняті позначення;
not_before– час початку дії сертифіката (тип даних – рядок формату ASN1_TIME);
not_after– час закінчення дії сертифіката (тип даних – рядок формату ASN1_TIME);
key_usage– інформація про призначення ключа, що повертається у вигляді масиву.

Час початку / закінчення дії сертифіката у форматі ASN1_TIME може бути переведено у стандартний формат за допомогою функції new Date(ASN1_TIME) .

Перегляд даних про ключ електронного підпису

Для перегляду даних про конкретний ключ електронного підпису сертифіката необхідно викликати метод token_info. Метод повертає json-об'єкт із такими даними:

label– ім'я ключового контейнера засобу електронного підпису;
manufacturerID– ідентифікатор виробника засобу електронного підпису;
model– модель засобу електронного підпису;
serialNumber- Серійний номер засобу електронного підпису.

Для ключів, що працюють через capi-модуль, дані, що повертаються, мають інший вигляд. Атрибут model завжди набуває значення “capi”, атрибут serialNumber відсутній, manufacturerID відповідає назві криптопровайдера, а label – це назва контейнера.

Операція підписання за допомогою вибраного сертифіката

Простий режим підписання

Щоб підписати рядок за допомогою вибраного сертифіката, необхідно викликати функцію cms_sign_on_it , яка приймає наступні вхідні параметри:

рядок для підпису;
тип підпису — чи є підпис приєднаним (необхідно передавати значення true) чи від'єднаним (false).

Як відповідь, функція повертає рядок з підписом у форматі CAdES-BES / PKCS#7 attached/detached.
Приклад виклику функції, яка має бути викликана на об'єкті сертифіката: cms_sign_on_it("1234", 3, true).then(function(cms)(console.log(cms)));

Розширений режим підписання

Розширений режим дозволяє:

підписувати дані великого обсягу, наприклад файли;
підписувати кілька файлів без повторного запиту на пін-код.

Для підписання даних за допомогою вибраного сертифіката необхідно попередньо ініціалізувати об'єкт signer за допомогою функції start_signing на об'єкті сертифіката. Параметри функції:

тип підпису — чи є підпис приєднаним (необхідно передавати значення true) чи від'єднаним (false);
кількість спроб введення пін-коду (наприклад, значення «1» означає, що користувач має лише одну спробу, після чого функція повертає помилку).

На об'єкті signer будуть доступні методи:

add_data_in_hex(hexDataString) - приймає на вхід дані у вигляді hex рядка;
add_data_in_base64(base64DataString) - приймає на вхід дані у вигляді base64 рядка;
add_data_in_string(stringData) - приймає на вхід дані у вигляді utf-8 рядка;
free() — повертає значення true/false , що дозволяє перевірити, чи сертифікат готовий до підписання. Потрібно використовувати для випадку, коли кілька ітерацій підпису здійснюється на різних сертифікатах. Іншими словами, якщо здійснюється послідовне підписання на кількох сертифікатах, перед підписанням необхідно викликати цей метод і переконатися, що він повернув true ;
finish() — фіналізує підпис і повертає його у форматі CAdES-BES/PKCS#7.

Як відповідь, функція повертає рядок з підписом у форматі CAdES-BES / PKCS#7 attached/detached.

Підписання рядка

Приклад команди, яка дозволяє підписати рядок:

Signer.add_data_in_string("1234").then(function(res)( return signer.finish();)).then(function(cms)(console.log(cms))));

У цій команді "1234" - це рядок, який необхідно підписати.

Встановлення кількох підписів

Після завершення підпису об'єкт signer повертається у вихідний стан. У рамках сесії його можна використовувати повторно для підписання інших даних, наприклад нового файлу. У цьому випадку пін-код не буде запрошено повторно.

Щоб підписати на іншому сертифікаті, необхідно очистити об'єкт signer . У більшості браузерів цей об'єкт очищається автоматично, коли він залишає область видимості (scope). Однак в Internet Explorer можливі ситуації, коли очищення signer не відбувається, що призводить до помилки. Для уникнення помилки рекомендується очищати signer.free() . Цю операцію можна проводити у всіх браузерах, щоб уніфікувати код. Приклад підпису на сертифікаті з очищенням об'єкта signer:

Function sign(cert, info) ( function successCms(signature) ( alert(signature); ) cert.start_signing(false, 3) .then(function(signer) ( signer.add_data_in_base64("MTIzNDU2") .then(function() ( var data = signer.finish(); var free = signer.free(); return data; ), e) .then(successCms, e); ), e);

Підписання файлу великого обсягу

Function readFileByChunk(file, cbToRead, cbToFinish) ( var fileSize = file.size; var chunkSize = 1024 * 1024; // bytes var offset = 0; var chunkReaderBlock = null; var self = this; var var if (evt.target.error == null) ( cbToRead(evt.target.result, offset, fileSize); offset += evt.target.result.byteLength; ) else ( console.error("Read error: " + evt .target.error); showError("Помилка читання файлу: " + evt.target.error); return; ) if (offset >= fileSize) , file); ) chunkReaderBlock = function(_offset, _chunkSize, _file) ( var r = new FileReader(); if (_file.slice) ( var blob = _file.slice(_offset, _chunkSize + _offset); ) else if (_ .webkitSlice) ( var blob = _file.webkitSlice(_offset, _chunkSize + _offset); ) else if (_file.mozSlice) ( var blob = _file.mozSlice(_offset, _chunkSize + _offset); ) r.onload readAsArrayBuffer(blob); ) // start reading the first block chunkReaderBlock(offset, chunkSize, file); )

Слід врахувати, що оскільки підписання виконується локально, то для подальшої передачі вибраного користувачем файлу та підпису на сервер необхідно реалізувати відповідну логіку на веб-сторінці.

У програмуванні ініціалізація даних є важливим завданням, оскільки на цьому кроці ми задаємо попередні умови для програми – атрибути, необхідні файли та дані, з'єднання з базою даних тощо.

У WordPress існує фіксована процедура ініціалізації. При реалізації життєвого циклу сторінки платформа WordPress запускає безліч дій, багато з яких було розкрито нами раніше. У системі існує набір ініціалізаційних хуків, які використовуються для ініціалізації програми перед виконанням його базової функціональності.

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

У цій статті ми розкриємо всю важливість хуків ініціалізації в WordPress, а також покажемо, як використовувати їх у різних ситуаціях.

Введення в хуки ініціалізації

WordPress пропонує широкий спектр хуків, які можуть використовуватись у розробці плагінів та тем.

У разі типового запиту сторінки всі хуки дій виконуються у порядку. Взагалі всі хуки виконуються після того, як базова програма WordPress завершить своє завантаження.

Таким чином, хуки ініціалізації в основному використовуються для того, щоб, як ви могли здогадатися, ініціалізувати процес їхньої роботи в плагінах та темах. Давайте поглянемо на доступні init-хуки WordPress в порядку їх виконання:

Init запускається після того, як WordPress закінчить своє завантаження, але перед тим, як будуть передані будь-які хедери. Взагалі цей хук використовується плагінами для ініціалізації процесу їх роботи.
widgets_init використовується для реєстрації віджетів програми у сайдбарі. Функція register_widget виконується в межах цього хука.
admin_init виконується як перша дія після того, як користувач отримав доступ до панелі адміністрування WordPress. В цілому він використовується для того, щоб ініціалізувати параметри, специфічні для області адміністратора.

Крім цих трьох хуків, WordPress також існує ще один хук під назвою admin_bar_init, який виконується після того, як адмін-бар був ініціалізований. WordPress Codex не містить у собі опис даного хука, проте він використовується лише невеликою кількістю плагінів.

Ви можете вивчити повний процес виконання дій в WordPress в кодексі .

WordPress виконує кожен хук у певному порядку (який описаний у кодексі). Також важливо розглянути порядок появи подій у кожному хуку дій. Давайте розглянемо такі ситуації, щоб зрозуміти різницю.

Визначаємо admin_init усередині хука init

Якщо нам потрібне, ми можемо визначити хуки WordPress в межах інших хуків. У типовому запиті хук init виконується перед хуком admin_init. Давайте спробуємо щось вивести на екран, розмістивши admin_init всередині хука init:

Add_action("init", "test_init"); function test_init()( add_action("admin_init", "test_admin_init"); ) function test_admin_init() ( echo "Admin Init Inside Init"; )

Після виконання цього коду ми отримаємо бажаний висновок за допомогою оператора echo.

Визначаємо init усередині хука admin_init

Давайте подивимося на код і виведення сценарію, коли більш ранній хук визначений у хуку, що йде пізніше, у порядку виконання.

Add_action("admin_init", "test_admin_init"); function test_admin_init() ( add_action("init", "test_init"); ) function test_init() ( echo "Init Inside Admin Init"; )

В даному випадку ми не отримаємо ніякого висновку – як і очікувалося – оскільки хук init виконується перед admin_init, а це неприпустимо після визначення admin_init.

Як ви можете бачити, дуже важливо розуміти процедуру виконання хуків для створення успішних плагінів. Порядок появи подій є важливим для всіх хуків WordPress.

Досліджуємо хуки init та admin_init

Серед усіх хуків ініціалізації дуже важливо звернути увагу саме на init та admin_init, оскільки ці два хуки використовуються дуже часто у багатьох плагінах. Використання решти ініціалізаційних хуків у рази простіше проти цими двома хуками.

Також ми подивимося на функціональність хуків init та admin_init.

Хук init виконується при кожному запиті як для фронтенду, так і для бекенду сайту WordPress.

Хук admin_init виконується після того, як секція адміністратора завершила процес завантаження. Таким чином, цей хук виконується для всіх запитів до будь-якої сторінки адміністратора. Користувачі повинні бути зареєстровані для того, щоб використовувати в своїх інтересах даний хук.

Оскільки обидва ці хуки виконуються при кожному запиті, ми повинні відповідним чином продумати функціональність, що базується на реалізації цих хуків, оскільки це може помітно вплинути на продуктивність сайту.

Як використовувати init хуки

Найчастіше хуки ініціалізації використовуються більшістю існуючих WordPress-плагінів, і дуже важливі керувати процесом їх виконання.

WordPress не вказує на те, що саме ми повинні, а що не повинні підключати; тому розробники можуть припускатися незначних помилок, які, своєю чергою, здатні призводити до помітного зниження продуктивності. У цій секції ми покажемо вам, як ефективно використовувати хуки init та admin_init.

Погляньмо на найкращі практики використання ініціалізаційних хуків:

Хук init

Реєстрація довільних типів записів – розробники WordPress рекомендують використовувати хук init для реєстрації нових довільних типів записів.
Ініціалізація конфігурації та налаштувань плагіна – параметри налаштування та конфігурації плагіна необхідно визначити для кожного запиту, а отже, хороша практика полягає в тому, щоб помістити їх усередині цього хука.
Доступ до надісланих даних користувача (використовуючи $_GET і $_POST) – ми можемо перехопити передані дані без використання будь-яких дій, проте в цьому випадку рекомендується використовувати init хук, оскільки він гарантує виконання для кожного запиту.
Додавання нових правил перезапису – ми можемо задавати нові правила перезапису, використовуючи хук init, але вони працюватимуть лише після скидання.
Додавання або видалення довільних дій – плагіни містять багато довільних дій для розширення функціональності. Можуть виникнути ситуації, коли нам доведеться додати нові дії або видалити старі. У таких випадках важливо застосувати ці дії в хуку init.
Завантаження текстового домену плагіна – WordPress підтримує численні мови, і таким чином ми можемо завантажувати файл, що містить перекладені рядки. Це має робитися теж у хуку init.

Хук admin_init

Керування доступом – важливо перевірити права доступу користувачів, що увійшли до системи, перед тим, як дозволити користувальницький доступ до певного набору особливостей і функціональності. admin_init – перша дія, яка буде виконуватися в області адміністратора, тому ми можемо використовувати її для керування доступом.
Додавання нових параметрів – ми можемо використовувати цей хук для додавання нових сторінок налаштувань або параметрів у існуючу область параметрів WordPress.

Існує багато інших можливих варіантів застосування цих хуків, однак у цих особливостей існують і свої власні хуки, тому хуки ініціалізації використовувати не потрібно.

Загальні помилки використання хуків ініціалізації

Найчастіше ми стикаємося із ситуаціями, коли розробники неправильно розуміють використання ініціалізаційних хуків. Неправильне використання зазначених хуків може призвести до серйозних проблем із продуктивністю.

Давайте визначимо часті помилки, а також способи їхнього обходу:

Оновлення правил перезапису – це дуже ресурсомістка операція, в процесі якої всі правила перезапису оновлюються та переупорядковуються для додавання нових або видалення старих правил. Багато розробників оновлюють правила перезапису всередині init-дій. Це призводить до того, що виникають непотрібні витрати щодо продуктивності у кожному запиті. Ми повинні визначити спосіб ручного оновлення правил перезапису за допомогою кнопок або оновлення правил для рідкісних дій, як, наприклад, збереження опцій плагіна.

Доступ до бази даних – для реалізації різної функціональності повинен бути доступ до бази даних, проте важливо також запобігти непотрібним зверненням до бази даних усередині ініціалізаційних хуків, оскільки вони виконуються при кожному запиті. Для цієї мети ідеальним рішенням буде прив'язати хуки бази даних до хуків з певною функціональністю, уникнувши потужних витрат продуктивності.

Виконання процедур оновлення – плагіни повинні включати процедури оновлення, щоб оновлювати свої можливості у нових версіях. Зазвичай, розробники використовують хуки ініціалізації для перевірки версії плагіна та існуючих параметрів перед виконанням процесу оновлення. Ми можемо запропонувати користувачам оновлювати плагін на окремому екрані замість того, щоб автоматично перевіряти при кожному запиті.

Використання хуків ініціалізації замість хуків для певної функціональності – це найпоширеніша помилка, яка відбувається численними розробниками. У WordPress існує широкий спектр хуків, пов'язаних із унікальною функціональністю. Дуже важливо використовувати функціональні хуки, щоб обійти конфлікти і зробити код, що розширюється. Хуки, такі як init та admin_init, можуть використовуватись замість специфічних хуків, тому багато розробників схильні звертатися до них, не розуміючи того, який руйнівний ефект це несе.

Приклади поширених сценаріїв використання хуків init та admin_init розробниками замість рекомендованих хуків:

admin_menu – ми можемо додавати сторінки меню за допомогою функції add_menu_page. Для створення сторінок у меню адміністратора рекомендується використовувати хук admin_menu. Однак багато розробників використовують хук admin_init, оскільки він виконується після хука admin_menu.
wp_enqueue_scripts – рекомендований спосіб додавання стилів та скриптів полягає у використанні хука wp_enqueue_scripts. Однак багато розробників використовують wp_enqueue_script усередині хука init для завантаження скриптів та стилів.

Існує маса подібних ситуацій, коли розробники використовують загальний хук init замість спеціального хука для певної функціональності і від такого підходу необхідно по можливості відмовитися.

Висновок

Хуки ініціалізації WordPress відіграють життєво важливу роль у розробці плагінів та тем. Багато розробників неправильно використовують хуки, створюючи зайве навантаження на продуктивність. У цій статті ми обговорили правильне використання цих хуків, а також загальні помилки їх застосування та способи їхнього обходу.

Тепер ми можемо застосувати ті самі методики до хуків, що використовуються в плагінах. Багато розробників плагінів використовують власні хуки дій, щоб зробити плагіни розширюваними. Для таких плагінів ми можемо визначити специфічні для плагіна хуки ініціалізації, щоб розробникам дозволити «повісити» завдання ініціалізації на зумовлені хуки.

На деяких сайтах доводиться мати справу із сертифікатами та електронними ключами, і спочатку доводиться вирішувати різні проблеми, щоби все запрацювало. У цій статті йтиметься про помилку роботи CAdES plugin'у, коли він завантажений, а об'єкти не створюються.

Вирішення проблеми з плагіном

Як і випливає зі змісту помилки, сам собою CAdES plugin як завантажений, тобто. він є у системі, проте щось заважає його роботі. Зазвичай проблема виникає у старих версіях Firefox аж до версії 51 (у новіших плагін просто не працює). У цій статті як приклад взято електронний торговий майданчик, і є три способи, як можна вирішити проблему.

Спосіб 1: Включити плагін для поточного сайту

Включення плагіна тільки для поточного сайту виправдане міркуваннями безпеки, коли браузер використовується для особистих цілей та відкриття різних сторінок. А також якщо потрібно виконати завдання з електронними ключами лише один раз.

Спосіб 2: Увімкнути плагін для всіх сайтів

Якщо питання безпеки дуже турбує, т.к. комп'ютер використовується виключно для роботи на декількох сайтах, можна увімкнути CAdES plugin для всіх сайтів. Тоді він працюватиме відразу після завантаження сторінки. Це може допомогти й у тому випадку, коли неможливо знайти темно-сірий квадрат для включення плагіна.

Спосіб 3: Використання іншого браузера

Через якісь непередбачені причини CAdES plugin все одно може відмовлятися працювати. Тому ще один спосіб усунути помилку – використовувати інший браузер. Більшість браузерів засновано на движку Chromium, вони чимось схожі, тому розглянемо на прикладі Google Chrome.

Висновок

Як видно, є кілька способів вирішити проблему з некоректною роботою плагіна. Залежно від переваг та обставин, можна вибрати для себе той, який найбільше підходить.

) у розділі "Продукти" -> "КриптоПро ЕЦП Browser plug-in"

При запуску завантаженого файлу система надасть запит на підвищення прав до адміністратора системи. Встановлення без адміністраторських прав неможливе.

Після встановлення обов'язково перезапустіть ваш браузер! Іноді (у разі використання Chrome) потрібне перезавантаження системи, т.к. Закриття всіх вікон chrome не завжди вивантажує браузер з оперативної пам'яті.

Додаткові налаштування для FireFox версії 52.0 та новіші

Не забудьте виконати установки плагіна

Для роботи плагіна у FireFox починаючи з версії 52 необхідно встановити свіжу версію плагіна (не нижче 2.0.12888)(див. ) та спеціальне розширення для FireFox.

Для встановлення розширення перейдіть з вашого FireFox за посиланням. Після переходу Вам буде запропоновано встановити розширення для FireFox - необхідно підтвердити установку, натиснувши Install (Встановити).

Додаткові налаштування для FireFox версії до 52.0, FireFox ESR (Помилка: Плагін завантажений, але не створюються об'єкти)

Після встановлення надбудови її запуск дозволено лише після підтвердження користувачем. Дозволити запуск надбудови можна лише для поточного сайту або назавжди для всіх сайтів

Варіант 1:налаштування дозволу використання надбудови тільки для поточного сайту (https://www.сайт)

Коли виникла помилка: Плагін завантажений, але не створюються об'єктизверніть увагу на адресний рядок - у ньому з'явився значок надбудови:

Натисніть на цей значок - вам буде запропоновано запустити надбудову та запам'ятати дозвіл запускати надбудову для цього сайту назавжди.

Варіант 2:налаштування дозволу використання надбудови для всіх сайтів

Відкрийте сторінку із встановленими додатками FireFox

У списку додатків знайдіть CryptoPro CAdES NPAPI Browser Plug-in та змініть його режим запуску на "Включати завжди"

Додаткові налаштування для Opera

Відкрийте сторінку з пошуком доповнення для встановлення:

Введіть у рядок пошуку "CryptoPro" - знайдено розширення "CryptoPro Extension for CAdES Browser Plug-in". Натисніть "Додати до Opera" для встановлення.