.. currentmodule:: TatInternalObject .. _crypto: Криптография ====================================================================== .. warning:: |not_supported| Наш API по криптографии базируется на `Windows CryptoAPI `__. .. seealso:: - `Список алгоритмов хеширования Windows CryptoAPI `__. - `Список OID Windows CryptoAPI `__. - `Руководство разработчика CryptoPro `__. - `Список алгоритмов хеширования CryptoPro `__. - `Список OID CryptoPro `__. - :ref:`Внешняя библиотека ЭЦП ` Cryptor ---------------------------------------------------------------------- .. pas:class:: Cryptor Статический класс, содержит криптографические методы. .. seealso:: - :ref:`Пример генерации подписи XML(XAdES-BES) ` - :ref:`Пример рассчёта хеша файла ` - :ref:`Пример шифрования содержимого XML ` - :ref:`Пример шифрования содержимого в PKCS #7 ` .. pas:method:: CreateHashByCert(Cert: TbtkCryptorCertificate; AlgID: String = ''): TbtkCryptorHash Создать экземпляр объекта хеширования в соответствии с указанным сертификатом. Если сертификат обладает закрытым ключём - хешер будет ассоциирован с ним (можно подписать хеш закрытым ключём сертификата - :pas:meth:`TbtkCryptorHash.Sign`) :param TbtkCryptorCertificate Cert: Сертификат на основании которого будет создан объект хеширования. По умолчанию из сертификата берутся и алгоритм хеширования - согласно указанному в нём алгоритму подписи. :param String AlgID: Опциональный параметр. Позволяет указать алгоритм хеширования отличный от того что соответствует алгоритму подписи указанному в сертификате. :rtype: TbtkCryptorHash .. versionadded:: 5.5.0.3950 .. pas:method:: CreateProvByType(Type: Integer): TbtkCryptorProvider Создать новый экземпляр криптопровайдеда, с указанием поддерживаемого функционала. :param Integer Type: Тип криптопровайдера. Примеры: - Стандартные типы, `MSDN `__ - PROV\_GOST\_94\_DH = 71 - PROV\_GOST\_2001\_DH = 75 :param Integer Flags = CRYPT_VERIFYCONTEXT: Флаги создания экземпляра, см. `MSDN `__ , параметр `dwFlags`. :rtype: TbtkCryptorProvider .. versionadded:: 5.5.8.4460 .. pas:method:: CreateCertBySign(Sign: Blob): TbtkCryptorCertificate Создаёт экземпляр сертификата по подписи (подпись возвращаемая методом :pas:meth:`Cryptor.SignMessage`) :param Blob Sign: :term:`блоб `, содержащий подпись :rtype: TbtkCryptorCertificate .. versionadded:: 5.5.0.3950 .. pas:method:: CreateCertByID(ID: String): TbtkCryptorCertificate Создаёт экземпляр сертификата с указанным *ID* - :pas:attr:`TbtkCryptorCertificate.ID`. :param String ID: ID сертификата :rtype: TbtkCryptorCertificate .. note:: - в случае если такой сертификат не существует - возбуждается исключение. - ID может быть получен методом :pas:meth:`TbtkCryptorCertificate.OpenCertificateDlg`, или у другого экземпляра сертификата через свойство :pas:attr:`TbtkCryptorCertificate.ID`. .. versionadded:: 5.5.0.3950 .. pas:method:: CreateCertByBlob(Data: Blob): TbtkCryptorCertificate Создаёт экземпляр сертификата безопасности по его бинарному представлению (значение :pas:attr:`TbtkCryptorCertificate.RawData`). :param Blob Data: Бинарное представление сертификата безопасности. :rtype: TbtkCryptorCertificate .. versionadded:: 5.5.0.3950 .. pas:method:: CreateCertByDialog(): TbtkCryptorCertificate Создаёт экземпляр сертификата выбранного пользователем с помощью UI. :rtype: TbtkCryptorCertificate .. note:: - в случае отмены возбуждается исключение EbtkUserCancel. - данный способ идеологически заменяет вызов "устаревшего" :pas:meth:`TbtkCryptorCertificate.OpenCertificateDlg` - результат возвращаемый :pas:meth:`TbtkCryptorCertificate.OpenCertificateDlg` можно получить через свойство :pas:attr:`TbtkCryptorCertificate.ID` .. versionadded:: 5.5.0.3950 .. pas:method:: EncryptSessionKey(Key: TbtkCryptorCertificate; RecipientKey: Blob): Blob; Зашифровать сессионный ключ (ключ симметричного шифрования) и закодировать в транспортную `ASN1`-структуру `GostR3410-KeyTransport`, см. `RFC4490 `__ :param TbtkCryptorKey Key: Выгружаемый/шифруемый ключ симметричного шифрования :param Blob RecipientKey: :term:`Блоб ` публичного ключа получателя, в формате выгрузки CSP, см :pas:meth:`TbtkCryptorKey.Export` .. versionadded:: 5.5.8.4460 .. pas:method:: DecryptSessionKey(Transport: Blob; PrivateKey: TbtkCryptorKey): TbtkCryptorKey; Декодировать и расшифровать сессионный ключ из структуры `GostR3410-KeyTransport`, см. `RFC4490 `__ Метод обратный к :pas:meth:`EncryptSessionKey`. :param Blob Transport: Транспортный :term:`блоб `, структура `GostR3410-KeyTransport` :param TbtkCryptorKey PrivateKey: Приватный ключ для расшифровки декодированного сессионного ключа. :rtype: TbtkCryptorKey .. versionadded:: 5.5.8.4460 .. pas:method:: GetRawDataByCertID(CertID: String): Blob Массив данных сертификата. Возвращается в виде массива байт. :param String CertID: Идентификатор сертификата. Полученный, например, с помощью :pas:meth:`Cryptor.OpenCertificateDlg`. :rtype: Blob .. code-block:: delphi :caption: Пример использования CertID := Cryptor.OpenCertificateDlg; rawData := Cryptor.GetRawDataByCertID(CertID); // красивый вывод на экран strRawData := 'RawData = ' + #13#10; for i := 0 to length(rawData)-1 do begin strRawData := strRawData + IntToStr(rawData[i]) + ', '; if (i mod 20 = 0) and (i <> 0) then strRawData := strRawData + #13#10; end; ShowMessage(strRawData); .. deprecated:: 5.5.0.3950 Следует использовать :pas:attr:`TbtkCryptorCertificate.RawData`. .. pas:method:: CertInfoByCertID(СertID: String; out Issuer: String; out Subject: String; out NotBefore: TDateTime; out NotAfter: TDateTime; out SignatureAlgorithm: String;): boolean Получить данные сертификата по ID :param String CertID: ID сертификата. :param String Issuer: out параметр. Наименование организации выдавшей сертификат. :param String Subject: out параметр. Наименование субъекта которому выдан сертификат. :param TDateTime NotBefore: out параметр. Дата с которой сертификат считается валидным. :param TDateTime NotAfter: out параметр. Дата с которой сертификат считается невалидным. :param String SignatureAlgorithm: out параметр. OID алгоритма подписи сертификата. :rtype: boolean .. pas:method:: CertInfoBySign(Sign: Blob; out Issuer: String; out Subject: String; out NotBefore: TDateTime; out NotAfter: TDateTime; out SignatureAlgorithm: String;): boolean Получить данные сертификата из подписи. :param Blob Sign: Подпись. :param String Issuer: out параметр. Наименование организации выдавшей сертификат. :param String Subject: out параметр. Наименование субъекта которому выдан сертификат. :param TDateTime NotBefore: out параметр. Дата с которой сертификат считается валидным. :param TDateTime NotAfter: out параметр. Дата с которой сертификат считается невалидным. :param String SignatureAlgorithm: out параметр. OID алгоритма подписи сертификата. :rtype: boolean .. pas:method:: CertInfoByBlob(Data: Blob; out Issuer: String; out Subject: String; out NotBefore: TDateTime; out NotAfter: TDateTime; out SignatureAlgorithm: String;): boolean Получить данные сертификата из его бинарного представления (:pas:attr:`TbtkCryptorCertificate.RawData`). :param Blob Data: Бинарное представление сертификата. :param String Issuer: out параметр. Наименование организации выдавшей сертификат. :param String Subject: out параметр. Наименование субъекта которому выдан сертификат. :param TDateTime NotBefore: out параметр. Дата с которой сертификат считается валидным. :param TDateTime NotAfter: out параметр. Дата с которой сертификат считается невалидным. :param String SignatureAlgorithm: out параметр. OID алгоритма подписи сертификата. :rtype: boolean .. pas:method:: GetThumbprintHexStringByCertID(CertID: String): String Отпечаток сертификата в виде строки шестнадцатеричных цифр без пробелов. Например:: ca28201a69d921711ba37eac4676028647b5fb12 :param String CertID: Идентификатор сертификата. Полученный, например, с помощью :pas:meth:`Cryptor.OpenCertificateDlg`. :rtype: String .. code-block:: delphi :caption: Пример использования CertID := Cryptor.OpenCertificateDlg; thumbPrint := Cryptor.GetThumbprintHexStringByCertID(CertID); ShowMessage('Отпечаток выбранного сертификата = ' + thumbPrint); .. deprecated:: 5.5.0.3950 Следует использовать :pas:attr:`TbtkCryptorCertificate.Thumbprint`. .. pas:method:: VerifyCertFromSignInCRL(Sign: Blob): Boolean Проверяет наличие сертификата из подписи в списках отозванных. :param Blob Sign: :term:`ЭЦП`. :rtype: Boolean .. code-block:: delphi :caption: Пример использования if VerifyCertFromSignInCRL(sign) then ShowMessage('Сертификату, которым была создана данная подпись, можно доверять') else ShowMessage('Сертификат, которым создали данну подпись, был отозван'); .. pas:method:: VerifyCertInCRL(CertID: String): Boolean Проверяет наличие сертификата в списках отозванных по идентификатору сертификата. :param String CertID: Идентификатор сертификата. :rtype: Boolean .. code-block:: delphi :caption: Пример использования CertID := Cryptor.OpenCertificateDlg; if VerifyCertFromSignInCRL(CertID) then ShowMessage('Сертификату можно доверять') else ShowMessage('Сертификат отозван'); .. pas:method:: RefreshCRL(Sign: Blob; Log: Sting; Force: Boolean): Boolean Обновляет списки отозванных сертификатов. :param Blob Sign: :term:`ЭЦП`. :param String Log: Строка, в которую будет записана информация об ошибках при их наличии. :param Boolean Force: Если установлен в **False**, то функция проверяет действительность списка отозванных сертификатов и обновляет его только при необходимости, иначе обновляет без проверки. :rtype: Boolean .. code-block:: delphi :caption: Пример использования var spLog: string; begin if RefreshCRL(sign, spLog, true) then ShowMessage('Списки были удачно обновлены') else ShowMessage(spLog); end; .. pas:method:: IsCRLOutOfDate(Sign: Blob): Boolean Проверка актуальности списка отозванных сертификатов. :param Blob Sign: Подпись :rtype: Boolean :returns: False Список актуален. True Нет списка или он устарел. .. code-block:: delphi :caption: Пример использования if IsCRLOutOfDate(sign) then ShowMessage('Нет списка или он устарел'); else ShowMessage('Список актуален'); .. pas:method:: LoadCRLByURL(Url: String; out Crl: Blob): Boolean Функция загружает по заданному адресу список отозванных сертификатов. :param String Url: URL адрес, с которого загружается список сертификатов. :param Blob Crl: out параметр. Cписок сертификатов. :rtype: Boolean .. code-block:: delphi :caption: Пример использования var crl: string; Begin if LoadCRLByURL('http://test.ru/my.crl', crl) then ShowMessage('Список отозванных сертификатов загружен') else ShowMessage('Ошибка загрузки'); end. .. pas:method:: AddCRLToRoot(Crl: Blob): Boolean Добавление списка отозванных сертификатов в хранилище "Доверенные корневые центры сертификации". :param Blob Crl: Список сертификатов. :rtype: Boolean .. code-block:: delphi :caption: Пример использования var crl: text; begin if LoadCRLByURL('http://aaaaa.ru/new.crl', crl) then ShowMessage('crl загружен'); if AddCRLToRoot(crl) then ShowMessage('crl установлен'); end; .. pas:method:: SignMessage(Data: Variant; CertID: String; out Sign: Blob; DetachedSignature: boolean = True) Подписывает переданные данные указанным сертификатом. Если подписать не удаётся возбуждается исключение. .. note:: Метод не предполагает возвращение результата, кроме подписи возвращаемой через out параметр. Из-за ошибки допущенной при реализации, метод изначально возвращал ``True``. В старой прикладной логике может встречаться проверка возвращаемого результата, такой код будет работать и в этом клиенте. В целях совместимости метод всё ещё возвращает True. Но пользы от этих проверок нет. :param Variant Data: Данные для подписания. :term:`Blob`, либо строка. .. attention:: Не рекомендуется передавать в метод строку. Нет гарантии что кодировки строк на подписывающей и верифицирующей стороне будут совпадать. :param String CertID: Идентификатор сертификата, либо пустая строка. Если передана пустая строка либо сертификат по указанному ID не найден, отобразится диалоговое окно выбора сертификата. :param Blob Sign: Сформированная :term:`ЭЦП`. :param boolean DetachedSignature: Подписать с откреплённой подписью. Необязательный параметр. Значение по-умолчанию - ``True`` .. versionchanged:: Global_5.10.0_ms5 Добавлена возможность подписывать :term:`Blob` .. versionchanged:: Global_5.12.0_ms14 Добавлен параметр DetachedSignature .. code-block:: delphi :caption: Пример использования blob := StringToBlob('Some text', 65001); cryptor.SignMessage(blob, certID, sign); .. pas:method:: GetDateFromSign(Sign: Blob; out Date: TDateTime): Boolean Получение даты подписи. По умолчанию при подписании данных ставится дата UTC :param Blob Sign: :term:`ЭЦП`. :param TDateTime Date: out параметр. Дата подписи. :rtype: Boolean .. code-block:: delphi :caption: Пример использования var d: TDateTime; Begin if GetDateFromSign(sign, d) then ShowMessage(DateTimeToStr(d)); end. .. pas:method:: VerifyCertificate(CertID, MessageError: String): Integer Проверка сертификата на возможность его использовать, а именно: даты действия, построение цепочки сертификатов и т.д. :param String CertID: серийный номер сертификата :param String MessageError: возвращаемое текстовое сообщение в результате не прохождения проверки сертификата :rtype: Integer :returns: **0** - в результате успешного прохождения проверки сертификата или код ошибки. .. code-block:: delphi :caption: Пример использования if Cryptor.VerifyCertificate(VerifyCertID, messageError) = 0 then ShowMessage('Сертификат подтверждён') else ShowMessage('Сертификат не подтверждён: ' + messageError); .. pas:method:: VerifyMessage(Data: Variant; Sign: Blob; Log: String; DetachedSignature: Boolean): Boolean Метод верифицирует :term:`ЭЦП`. :param Variant Data: Данные для проверки. :term:`Blob`, либо строка. .. attention:: Не рекомендуется передавать строку. Нет гарантии что кодировки строк на подписывающей и верифицирующей стороне будут совпадать. :param Blob Sign: Проверяемая :term:`ЭЦП` :param String Log: В случае успеха содержит серийный номер сертификата, с помощью которого была создана :term:`ЭЦП`, либо текст ошибки в противном случае. :param Boolean DetachedSignature: Проверяемая :term:`ЭЦП` подписана с откреплённой подписью. Необязательный параметр. Значение по-умолчанию - ``True``. :rtype: Boolean :returns: True Подпись подтверждена. False Подпись не подтверждена. .. versionchanged:: Global_5.10.0_ms5 Добавлена возможность верифицировать подпись для :term:`Blob` .. versionchanged:: Global_5.12.0_ms15 Добавлен параметр DetachedSignature .. code-block:: delphi :caption: Пример использования if Cryptor.VerifyMessage(data, sign, spLog) then ShowMessage('Подпись подтверждена!') else ShowMessage('Подпись не подтверждена! Причина:' + spLog ); .. pas:method:: OpenCertificateDlg(): String Открывает диалоговое окно выбора сертификата. :rtype: String :returns: серийный номер сертификата в шестнадцатеричной системе счисления. .. code-block:: delphi :caption: Пример использования var CertID: string; begin CertID := Cryptor.OpenCertificateDlg; ShowMessage(CertID); end. .. pas:method:: SignAndEncryptMessage(BlobToSignAndEncrypt: Blob; SignerCert, RecipientCert: TbtkCryptorCertificate; EncryptionAlgorithm: String): TbtkSignAndEncryptMessageResult Подписывает и зашифровывает данные в формате PKCS #7. :param Blob BlobToSignAndEncrypt: Данные для подписания и зашифрования. :param TbtkCryptorCertificate SignerCert: Сертификат отправителя. Этим сертификатом данные будут подписаны. :param TbtkCryptorCertificate RecipientCert: Сертификат получателя. Данные будут зашифрованы с помощью открытого ключа из этого сертификата. :param String EncryptionAlgorithm: OID алгоритма шифрования. :rtype: TbtkSignAndEncryptMessageResult .. code-block:: delphi :caption: Пример использования var res: TbtkSignAndEncryptMessageResult; begin res := Cryptor.SignAndEncryptMessage(blobToSignAndEncrypt, signerCert, recipientCert, encryptionAlgorithm); if res.IsSuccessful then ProcessEncryptedData(res.SignedAndEncryptedBlob) else Raise(Format('Не удалось зашифровать или подписать сообщение.'#13#10#13#10'Код ошибки:'#13#10' $%x'#13#10'Текст ошибки:'#13#10' "%s"', [res.ErrorCode, res.ErrorMessage])); end; .. seealso:: - :pas:meth:`Cryptor.DecryptAndVerifyMessageSignature` - :ref:`Пример шифрования содержимого в PKCS #7 ` .. versionadded:: Global_5.9.0 .. pas:method:: DecryptAndVerifyMessageSignature(SignedAndEncryptedBlob: Blob; CertStores: array of String = ['CA', 'MY', 'ROOT']; SignerIndex: Integer = 0): TbtkDecryptAndVerifyMessageSignatureResult Расшифровывает данные из PKCS #7 и проверяет подпись. Указание сертификатов для проверки подписи и расшифрования не поддерживается. Требуемые сертификаты будут искаться в хранилищах указанных в параметре ``CertStores`` и при успешном завершении вызова будут возвращены в качестве результата. :param Blob SignedAndEncryptedBlob: Зашифрованные подписанные данные. :param CertStores: Имена хранилищ, в которых будут искаться сертификаты для проверки подписи и расшифрования данных. Если указывается одно хранилище можно передать просто строку а не массив. Поддерживаются хранилища ``CA``, ``MY`` и ``ROOT``. Должно быть указано хотя бы одно хранилище, передача пустой строки, пустого массива либо ``Null`` приведет к ошибке. Если не передавать значение параметра то по умолчанию поиск осуществляется во всех трёх хранилищах. :type CertStores: array of String :param Integer SignerIndex = 0: Индекс подписи отправителя которую требуется проверить. Первая подпись имеет индекс 0. Для проверки нескольких подписей следует вызвать метод несколько раз, с разным значением ``SignerIndex``. Если при выполнении метода вернется ошибка ``CRYPT_E_NO_SIGNER = $8009200E``, значит предыдущая подпись была последней. Заранее определить количество подписей или проверить подпись по конкретному сертификату, метод не позволяет. :rtype: TbtkDecryptAndVerifyMessageSignatureResult .. code-block:: delphi :caption: Пример использования var res: TbtkDecryptAndVerifyMessageSignatureResult; begin res := Cryptor.DecryptAndVerifyMessageSignature(blobToDecryptAndVerifyMessageSignature); if res.IsSuccessful then ProcessDecryptedBlob(res.DecryptedBlob) else Raise(Format('Не удалось расшифровать сообщение.'#13#10#13#10'Код ошибки:'#13#10' $%x'#13#10'Текст ошибки:'#13#10' "%s"', [res.ErrorCode, res.ErrorMessage])); end; .. seealso:: - :pas:meth:`Cryptor.SignAndEncryptMessage` - :ref:`Пример шифрования содержимого в PKCS #7 ` .. versionadded:: Global_5.9.0 TbtkCryptorKey -------------- .. pas:class:: TbtkCryptorKey Объект высокоуровневого взаимодействия с "MS CryptoAPI". Реализует сущность "Ключ шифрования". Служит для шифрования и расшифровывания данных. .. versionadded:: 5.5.8.4460 Все ключи ~~~~~~~~~ .. pas:class:: .. pas:method:: EncryptData(Data: Blob; Hash: TbtkCryptorHash = nil): Blob Зашифровать данные :param Blob Data: Данные для зашифрования :param TbtkCryptorHash Hash = nil: Хеш данных до зашифрования .. pas:method:: DecryptData(Data: Blob; Hash: TbtkCryptorHash = nil): Blob Расшифровать данные. Метод обратный к :pas:meth:`EncryptData` :param Blob Data: Данные для расшифровки :param TbtkCryptorHash Hash = nil: Хеш расшифрованных данных .. pas:method:: Export(BlobType: Integer; EncKey: TbtkCryptorKey = nil; Flags: Integer = 0): Blob Сериализовать (выгрузить) ключ шифрования в указанном формате CSP :param Integer BlobType: Формат предусмотренный CSP для сериализации ключей. Доступные варианты: - ```SIMPLEBLOB` = $1;`` - сессионный ключ - ```PUBLICKEYBLOB` = $6;`` - публичный ключ - ```PRIVATEKEYBLOB` = $7;`` - секретный ключ - ```PLAINTEXTKEYBLOB` $8;`` - ключ в открытом формате - Также, некоторые `CSP` могут определять свои форматы. :param TbtkCryptorKey EncKey = nil: Ключ которым будет шифроваться сериализованный ключ. Параметр применим, среди стандартных способов сериализации, для выгрузки сессионных ключей. :param Integer Flags = 0: Определяет дополнительные опции выгрузки, см. `MSDN `__ , параметр ``dwFlags`` .. pas:method:: DuplicateKey(): TbtkCryptorKey Метод создаёт дубликат ключа. Может быть полезно, если ожидается модификация ключа, но в будущем потребуется ключ с изначальными параметрами. :rtype: TbtkCryptorKey .. pas:attribute:: AlgID: String Алгоритм ключа в представлении OID-идентификатора .. pas:attribute:: AlgID: Integer Алгоритм ключа в числовом представлении. Не каждому алгоритму ключа будет соответствовать международный стандартизированный идентификатор (Object ID), в связи с чем реализована возможность задать его значение специфичным для CSP. Например, смешанным (`mixture`) ключам по алгоритму Диффи-Хеллмана присущ алгоритм выгрузки сессионных ключей, но такие алгоритмы локальной значимости не стандартизируются. В CSP CryptoPro реализованы два таких алгоритма выгрузки: - ``CALG_PRO_EXPORT = 661F`` - ``CALG_SIMPLE_EXPORT = 6620`` .. pas:attribute:: BlockLen: Integer Свойство присущее ключам блочного шифрования - размер блока шифра, исчисляется в битах. Может зависеть от :pas:attr:`CypherMode` Атрибут только для чтения .. pas:attribute:: KeyLen: Integer Действительная (без учёта выравниваний) длина ключа, в битах. Атрибут только для чтения .. pas:attribute:: Salt: Blob Значение соли ключа шифрования Блочные ключи ~~~~~~~~~~~~~ .. pas:class:: .. pas:attribute:: CypherMode: Integer Режим шифрования `Стандартные режимы `__ : - ``CBC = 1`` - ``ECB = 2`` - ``OFB = 3`` - ``CFB = 4`` - ``CTS = 5`` - Могут дополняться (и запрещаться) реализацией используемого CSP .. pas:attribute:: CypherModeBits: Integer Дополнительный параметр для режимов шифрования ``CFB`` и ``OFB``. Количество передаваемых от блока к блоку бит. .. pas:attribute:: Padding: Integer Способ дополнения блоков блочного шифра Доступные варианты: - ``PKCS5_PADDING = 1`` - ``RANDOM_PADDING = 2`` - ``ZERO_PADDING = 3`` .. pas:attribute:: Vector: Blob Вектор инициализации (`IV`) алгоритма блочного шифра Разрешения ключа ~~~~~~~~~~~~~~~~ .. pas:class:: .. pas:attribute:: AllowArchive: Boolean Свойство сообщает, что данный ключ доступен для выгрузки. Но только до момента закрытия объекта ключа. Выставляется флагами при генерации ключа и сбрасывается CSP после (открыв ключ в слелующи раз - будет невыгружаемым) Атрибут только для чтения .. pas:attribute:: AllowDecrypt: Boolean Ключ можно использовать в методах дешифрации Атрибут только для чтения .. pas:attribute:: AllowEncrypt: Boolean Ключ можно использовать в методах шифрования Атрибут только для чтения .. pas:attribute:: AllowExport: Boolean Ключ можно выгрузить в открытом виде. Атрибут только для чтения .. pas:attribute:: AllowExportKey: Boolean ключ может использоваться для шифрования экспортируемых ключей Атрибут только для чтения .. pas:attribute:: AllowImportKey: Boolean ключ может использоваться для расшифровки импортируемых ключей Атрибут только для чтения .. pas:attribute:: AllowRead: Boolean Значение CRYPT_READ бита в параметре KP_PERMISSIONS. Атрибут только для чтения .. pas:attribute:: AllowWrite: Boolean Значение CRYPT_WRITE бита в параметре KP_PERMISSIONS. Атрибут только для чтения TbtkCryptorHash --------------- .. pas:class:: TbtkCryptorHash Объект высокоуровневого взаимодействия с "MS CryptoAPI". Реализует сущность "Хешер". Время жизни управляется счётчиком ссылок : - освобождается простым занулением переменной где он хранится - можно смело передавать его между операциями и выборками, даже асинхронными .. seealso:: - :pas:meth:`TbtkCryptorProvider.CreateHash` - :pas:meth:`Cryptor.CreateHashByCert` - :pas:class:`TbtkCryptorCertificate` .. versionadded:: 5.5.0.3950 .. pas:method:: Value(): Blob Получить рассчитанный хеш данных. :rtype: Blob .. attention:: после вызова - хеш изменить будет невозможно :pas:meth:`TbtkCryptorHash.HashData` .. pas:method:: Sign(): Blob Подписать рассчитанный хеш (:pas:meth:`TbtkCryptorHash.Value`) данных ассоциированным с хешером набором ключей шифрования(:pas:meth:`TbtkCryptorHash.Keyset`) :rtype: Blob :raises: Если ключи не ассоциированы с хешером (:pas:attr:`TbtkCryptorHash.Keyset` = :pas:attr:`TbtkCryptKeyset.ckNone`). .. attention:: после вызова - хеш изменить будет невозможно :pas:meth:`TbtkCryptorHash.HashData` .. pas:method:: VerifySign(Sign: Blob; PubKey: TbtkCryptorKey; Flags: Integer = 0): Boolean Проверить подпись на соответствие хешу. Результат `True` - фактическое подтверждение, что держатель сертификата (которому принадлежит публичный ключ) подтверждает целостность (неизменённость) данных, по которым рассчитан хеш. :param Blob Sign: Значение цифровой подписи. :param TbtkCryptorKey PubKey: Публичный ключ сертификата, которым подписаны данные. :param Integer Flags: Управляющие флаги, необязательный параметр. Использование флагов регламентируется конкретной реализацией CSP. В подавляющем большинстве случаев их передача не требуется. .. code-block:: delphi :caption: Пример использования cert := Cryptor.CreateCertByDialog; hash := Cryptor.CreateHashByCert(cert); hash.HashData([1,2,3,4,5,6]); sig := hash.Sign; hash := nil; newOneHash := Cryptor.CreateHashByCert(cert); newOneHash.HashData([1,2,3,4,5,6]); ok := newOneHash.VerifySign(sig, cert.Provider.CreateKeyByPublic(cert)); .. pas:method:: Keyset(): TbtkCryptKeyset Набор ключей который будет использован для подписания (:pas:meth:`TbtkCryptorHash.Sign`) хеша. :rtype: TbtkCryptKeyset .. note:: если ключи не ассоциированы с хешером (:pas:attr:`TbtkCryptKeyset.ckNone`) - метод :pas:meth:`TbtkCryptorHash.Sign` возбудит исключение. .. pas:method:: HashData(Data: Blob) Метод хеширует указанные данные. Поддерживается итеративное хеширование - можно последовательно вызвать метод для добавления в хеш новых пакетов данных, что равносильно тому как если бы все пакеты данных были последовательно помещены в один большой :term:`блоб ` и метод был бы вызван один раз. Такой подход позволяет парциально хешировать сколь угодно большой объём данных. :param Blob Data: Очередной :term:`блоб ` данных для хеширования. .. note:: добавлять порции в хеш можно до тех пор пока не будет вызван метод получения хеша (:pas:meth:`TbtkCryptorHash.Value` или :pas:meth:`TbtkCryptorHash.Sign`). .. pas:method:: HashSessionKey(Key: TbtkCryptorKey) Добавить к значению хеша данные ключа шифрования. :param: TbtkCryptorKey Key Ключ симметричного шифрования .. versionadded:: 5.5.8.4460 TbtkCryptorProvider ------------------- .. pas:class:: TbtkCryptorProvider Объект высокоуровневого взаимодействия с "MS CryptoAPI". Объект доступа к хранилищу секретных ключей с использованием выбранного (по типу реализуемого функционала, или иным признакам) CSP(алгоритмов). .. versionadded:: 5.5.8.4460 .. pas:method:: CreateHash(AlgID: String): TbtkCryptorHash Создать новый объект хеширования :param String AlgID: OID алгоритма хеширования. Примеры: - szOID\_RSA\_MD5 = "1.2.840.113549.2.5" - szOID\_RSA\_SHA1RSA = "1.2.840.113549.1.1.5" - szOID\_CP\_GOST\_R3411 = "1.2.643.2.2.9" :rtype: TbtkCryptorHash .. pas:method:: CreateKeyByPrivate(KeySet: TbtkCryptKeyset = ckKeyExchange): TbtkCryptorKey Создать объект секретного ключа из контейнера с которым ассоциирован провайдер :param TbtkCryptKeyset KeySet = ckKeyExchange: Указывает из какой пары ключ. Ключ обмена данными, или подписания данных. По умолчанию, как наиболее востребованный,- ключ обмена данными. :raises: Если ключ запрошенного типа отсутствует в провайдере. :rtype: TbtkCryptorKey .. pas:method:: CreateKeyByPublic(Cert: TbtkCryptorCertificate): TbtkCryptorKey Создать объект публичного ключа из сертификата безопасности разместив ключ в провайдере :param TbtkCryptorCertificate Cert: Сертификат, из которого будет загружен публичный ключ :rtype: TbtkCryptorKey .. pas:method:: CreateKeyByImport(KeyBlob: Blob; EncKey: TbtkCryptorKey = nil; Flags: Integer = CRYPT_EXPORTABLE): TbtkCryptorKey Загрузить ключевой :term:`блоб ` в криптопровайдер. Тип ключа и параметры определяются самим блобом. Метод комплементарен :pas:meth:`TbtkCryptorKey.Export`. :param Blob KeyBlob: Сериализованный CSP ключ шифрования :param TbtkCryptorKey EncKey = nil: Ключ которым зашифрован KeyBlob. Необходимость в ключе шифрования определяется типом загружаемого ключа и алгоритмами CSP. Для загрузки блобов публичных ключей ключ шифрования не требуется. :param integer Flags = CRYPT_EXPORTABLE: Флаги создания ключа, см. `MSDN `__ , параметр ``dwFlags``. :rtype: TbtkCryptorKey .. pas:method:: CreateKeyByGenKey(AlgID: String; Flags: Integer = CRYPT_EXPORTABLE): TbtkCryptorKey Сгенерировать новый ключ со случайными параметрами по указанному алгоритму. :param String AlgID: Алгоритм ключа. Например, ``1.2.643.2.2.21`` - ключ симметричного шифрования, `ГОСТ 28147`. :param Integer Flags = CRYPT_EXPORTABLE: Флаги создания ключа, см. `MSDN `__ , параметр ``dwFlags``. :rtype: TbtkCryptorKey .. pas:method:: CreateKeyByHash(AlgID: String; Hash: TbtkCryptorHash; Flags: Integer = CRYPT_EXPORTABLE): TbtkCryptorKey Создать новый ключ шифрования по данным хеша :param String AlgID: Алгоритм ключа. Например, ``1.2.643.2.2.21`` - ключ симметричного шифрования, `ГОСТ 28147`. :param TbtkCryptorHash Hash: Хеш-объект из значения которого будет сконструирован ключ. Для одинаковых хешей будут сконкструированы одинаковые ключи. :param Integer Flags = CRYPT_EXPORTABLE: Флаги создания ключа, см. `MSDN `__ , параметр ``dwFlags``. :rtype: TbtkCryptorKey .. pas:attribute:: KeyExchangeKeySetExists: Boolean Содержатся ли в контейнере ключи обмена данными. Атрибут только для чтения .. pas:attribute:: SignatureKeySetExists: Boolean Содержатся ли в контейнере ключи подписания данных. Атрибут только для чтения TbtkCryptorCertificate ----------------------- .. pas:class:: TbtkCryptorCertificate Объект высокоуровневого взаимодействия с "MS CryptoAPI". Реализует сущность "Сертификат безопасности". Время жизни управляется счётчиком ссылок : - освобождается простым занулением переменной где он хранится - можно смело передавать его между операциями и выборками, даже асинхронными .. seealso:: - :pas:meth:`Cryptor.CreateCertByDialog` - :pas:meth:`Cryptor.CreateCertByBlob` - :pas:meth:`Cryptor.CreateCertByID` - :pas:meth:`Cryptor.CreateCertBySign` - :pas:class:`TbtkCryptorHash` .. pas:attribute:: Thumbprint: Blob Хеш бинарного представления сертификата (:pas:attr:`TbtkCryptorCertificate.RawData`) рассчитанный алгоритмом **SHA1**. :rtype: Blob .. pas:attribute:: SerialNumber: Blob Порядковый номер сертификата присвоенный ему издателем. Integer неограниченной длинны (в нотации BigEndian). :rtype: Blob .. pas:attribute:: RawData: Blob Бинарное представление сертификата. :rtype: Blob .. pas:attribute:: SignatureAlgorithm: String OID алгоритма подписи сертификата. :rtype: String .. pas:attribute:: PublicKeyAlgorithm: String OID алгоритма хеширования публичного ключа. :rtype: String .. pas:attribute:: NotBefore: TDateTime Дата с которой сертификат считается валидным. :rtype: TDateTime .. pas:attribute:: NotAfter: TDateTime Дата с которой сертификат считается невалидным. :rtype: TDateTime .. pas:attribute:: KeepLoggedIn: Boolean True Не перезапрашивать пароль на доступ к хранилищу закрытого ключа. False При каждом обращении к закрытому ключу сертификата будет запрашиваться пароль от хранилища. :rtype: Boolean .. pas:attribute:: ID: String Строка используемая для идентификации сертификата в методах :pas:class:`Cryptor`. Свойство добавлено для обратной совместимости с ранее реализованным процедурным подходом. :rtype: String .. pas:method:: SubjectName(Format: TbtkCertNameFormat = cnfX500; Flags: Variant = null): String Наименование субъекта которому выдан сертификат. :param TbtkCertNameFormat Format: Представление в котором будет возвращено имя. :param Variant Flags: Зарезервировано. Не используется. Управляющие флаги, могут использоваться различные значения в зависимости от используемого представления. :rtype: String .. pas:method:: IssuerName(Format: TbtkCertNameFormat = cnfX500; Flags: Variant = null): String Наименование организации выдавшей сертификат. :param TbtkCertNameFormat Format: Представление в котором будет возвращено имя. :param Variant Flags: Зарезервировано. Не используется. Управляющие флаги, могут использоваться различные значения в зависимости от используемого представления. :rtype: String .. pas:attribute:: Provider: TbtkCryptorProvider Хранилище приватных ключей сертификата. Если с сертификатом не ассоциированно такого хранилища - генерируется исключение. Атрибут только для чтения :rtype: TbtkCryptorProvider TbtkCertNameFormat -------------------- .. pas:class:: TbtkCertNameFormat Перечисление. Формат в котором представлено наименование сертификата. .. seealso:: - :pas:meth:`TbtkCryptorCertificate.IssuerName` - :pas:meth:`TbtkCryptorCertificate.SubjectName` .. pas:attribute:: cnfX500 Имя формируется по правилам определённым Microsoft в CryptoAPI. При формировании используются заголовки (буквенные обозначения) параметров имени. .. pas:attribute:: cnfOid Имя формируется по правилам определённым Microsoft в CryptoAPI. При формировании используются OID параметров имени. .. pas:attribute:: cnfSimple Имя формируется по правилам определённым Microsoft в CryptoAPI. Формируется из одних только значений параметров, без заголовков. .. pas:attribute:: cnfRFC1779 Имя формируется в точном соответствии **RFC1779**, без лирических отступлений Microsoft от стандарта. TbtkCryptKeyset ---------------- .. pas:class:: TbtkCryptKeyset Перечисление. Набор ключей шифрования. .. seealso:: - :pas:attr:`TbtkCryptorHash.Keyset` .. pas:attribute:: ckKeyExchange Набор ключей для обмена данными. Также подходит и для подписывания данных (более широкий чем :pas:attr:`TbtkCryptKeyset.ckSignature`) .. pas:attribute:: ckSignature Набор ключей для подписывания данных. Вместо него также может использоваться набор ключей :pas:attr:`TbtkCryptKeyset.ckKeyExchange` .. pas:attribute:: ckNone Набор ключей шифрования отсутствует. TbtkSignAndEncryptMessageResult ------------------------------- .. pas:class:: TbtkSignAndEncryptMessageResult Агрегирует информацию о результате выполнения :pas:meth:`Cryptor.SignAndEncryptMessage`. .. versionadded:: Global_5.9.0 .. pas:attribute:: IsSuccessful: Boolean ``True`` если данные успешно подисаны и зашифрованы, ``False`` в противном случае. .. pas:attribute:: SignedAndEncryptedBlob: Blob Содержит зашифрованные и подписанные данные, если вызов завершился успешно. .. pas:attribute:: ErrorCode: Integer; Содержит код ошибки, если вызов не завершился успешно. .. pas:attribute:: ErrorMessage: String; Содержит текст ошибки, если вызов не завершился успешно. .. seealso:: - :pas:meth:`Cryptor.SignAndEncryptMessage` TbtkDecryptAndVerifyMessageSignatureResult ------------------------------------------ .. pas:class:: TbtkDecryptAndVerifyMessageSignatureResult Агрегирует информацию о результате выполнения :pas:meth:`Cryptor.DecryptAndVerifyMessageSignature`. .. versionadded:: Global_5.9.0 .. pas:attribute:: IsSuccessful: Boolean ``True`` если данные успешно расшифрованы и подпись проверена, ``False`` в противном случае. .. pas:attribute:: DecryptedBlob: Blob Содержит расшифрованные данные, если вызов завершился успешно. .. pas:attribute:: SignerCert: TbtkCryptorCertificate Содержит сертификат отправителя, если вызов завершился успешно. .. pas:attribute:: RecipientCert: TbtkCryptorCertificate Содержит сертификат получателя, если вызов завершился успешно. .. pas:attribute:: ErrorCode: Integer; Содержит код ошибки, если вызов не завершился успешно. .. pas:attribute:: ErrorMessage: String; Содержит текст ошибки, если вызов не завершился успешно. .. seealso:: - :pas:meth:`Cryptor.DecryptAndVerifyMessageSignature`