11. Криптография

Наш API по криптографии базируется на Windows CryptoAPI.

See also

• Список алгоритмов хеширования Windows CryptoAPI.
• Список OID Windows CryptoAPI.
• Руководство разработчика CryptoPro.
  • Список алгоритмов хеширования CryptoPro.
  • Список OID CryptoPro.
• Внешняя библиотека ЭЦП

11.1. Cryptor

class Cryptor

Статический класс, содержит криптографические методы.

See also

• Пример генерации подписи XML(XAdES-BES)
• Пример рассчёта хеша файла
• Пример шифрования содержимого XML
• Пример шифрования содержимого в PKCS #7

CreateHashByCert(Cert: TbtkCryptorCertificate; AlgID: String = ''): TbtkCryptorHash

Создать экземпляр объекта хеширования в соответствии с указанным сертификатом. Если сертификат обладает закрытым ключём - хешер будет ассоциирован с ним (можно подписать хеш закрытым ключём сертификата - TbtkCryptorHash.Sign())

Parameters:

• Cert (TbtkCryptorCertificate) – Сертификат на основании которого будет создан объект хеширования. По умолчанию из сертификата берутся и алгоритм хеширования - согласно указанному в нём алгоритму подписи.
• AlgID (String) – Опциональный параметр. Позволяет указать алгоритм хеширования отличный от того что соответствует алгоритму подписи указанному в сертификате.

Return type:

TbtkCryptorHash

New in version 5.5.0.3950.

CreateProvByType(Type: Integer): TbtkCryptorProvider

Создать новый экземпляр криптопровайдеда, с указанием поддерживаемого функционала.

Parameters:

• Type (Integer) –

  Тип криптопровайдера. Примеры:

  • Стандартные типы, MSDN
  • PROV_GOST_94_DH = 71
  • PROV_GOST_2001_DH = 75
• Flags = CRYPT_VERIFYCONTEXT (Integer) – Флаги создания экземпляра, см. MSDN , параметр dwFlags.

Return type:

TbtkCryptorProvider

New in version 5.5.8.4460.

CreateCertBySign(Sign: Blob): TbtkCryptorCertificate

Создаёт экземпляр сертификата по подписи (подпись возвращаемая методом Cryptor.SignMessage())

Parameters:Sign (Blob) – блоб, содержащий подпись Return type:TbtkCryptorCertificate

New in version 5.5.0.3950.

CreateCertByID(ID: String): TbtkCryptorCertificate

Создаёт экземпляр сертификата с указанным ID - TbtkCryptorCertificate.ID.

Parameters:ID (String) – ID сертификата Return type:TbtkCryptorCertificate

Note

• в случае если такой сертификат не существует - возбуждается исключение.
• ID может быть получен методом TbtkCryptorCertificate.OpenCertificateDlg(), или у другого экземпляра сертификата через свойство TbtkCryptorCertificate.ID.

New in version 5.5.0.3950.

CreateCertByBlob(Data: Blob): TbtkCryptorCertificate

Создаёт экземпляр сертификата безопасности по его бинарному представлению (значение TbtkCryptorCertificate.RawData).

Parameters:Data (Blob) – Бинарное представление сертификата безопасности. Return type:TbtkCryptorCertificate

New in version 5.5.0.3950.

CreateCertByDialog(): TbtkCryptorCertificate

Создаёт экземпляр сертификата выбранного пользователем с помощью UI.

Return type:TbtkCryptorCertificate

Note

• в случае отмены возбуждается исключение EbtkUserCancel.
• данный способ идеологически заменяет вызов “устаревшего” TbtkCryptorCertificate.OpenCertificateDlg()
• результат возвращаемый TbtkCryptorCertificate.OpenCertificateDlg() можно получить через свойство TbtkCryptorCertificate.ID

New in version 5.5.0.3950.

EncryptSessionKey(Key: TbtkCryptorCertificate; RecipientKey: Blob): Blob;

Зашифровать сессионный ключ (ключ симметричного шифрования) и закодировать в транспортную ASN1-структуру GostR3410-KeyTransport, см. RFC4490

Parameters:

• Key (TbtkCryptorKey) – Выгружаемый/шифруемый ключ симметричного шифрования
• RecipientKey (Blob) – Блоб публичного ключа получателя, в формате выгрузки CSP, см TbtkCryptorKey.Export()

New in version 5.5.8.4460.

DecryptSessionKey(Transport: Blob; PrivateKey: TbtkCryptorKey): TbtkCryptorKey;

Декодировать и расшифровать сессионный ключ из структуры GostR3410-KeyTransport, см. RFC4490

Метод обратный к EncryptSessionKey().

Parameters:

• Transport (Blob) – Транспортный блоб, структура GostR3410-KeyTransport
• PrivateKey (TbtkCryptorKey) – Приватный ключ для расшифровки декодированного сессионного ключа.

Return type:

TbtkCryptorKey

New in version 5.5.8.4460.

GetRawDataByCertID(CertID: String): Blob

Массив данных сертификата. Возвращается в виде массива байт.

Parameters:CertID (String) – Идентификатор сертификата. Полученный, например, с помощью Cryptor.OpenCertificateDlg(). Return type:Blob

Пример использования

<pascal>
  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);
</pascal>

Deprecated since version 5.5.0.3950: Следует использовать TbtkCryptorCertificate.RawData.

CertInfoByCertID(СertID: String; out Issuer: String; out Subject: String; out NotBefore: TDateTime; out NotAfter: TDateTime; out SignatureAlgorithm: String): boolean

Получить данные сертификата по ID

Parameters:

• CertID (String) – ID сертификата.
• Issuer (String) – out параметр. Наименование организации выдавшей сертификат.
• Subject (String) – out параметр. Наименование субъекта которому выдан сертификат.
• NotBefore (TDateTime) – out параметр. Дата с которой сертификат считается валидным.
• NotAfter (TDateTime) – out параметр. Дата с которой сертификат считается невалидным.
• SignatureAlgorithm (String) – out параметр. OID алгоритма подписи сертификата.

Return type:

boolean

CertInfoBySign(Sign: Blob; out Issuer: String; out Subject: String; out NotBefore: TDateTime; out NotAfter: TDateTime; out SignatureAlgorithm: String): boolean

Получить данные сертификата из подписи.

Parameters:

• Sign (Blob) – Подпись.
• Issuer (String) – out параметр. Наименование организации выдавшей сертификат.
• Subject (String) – out параметр. Наименование субъекта которому выдан сертификат.
• NotBefore (TDateTime) – out параметр. Дата с которой сертификат считается валидным.
• NotAfter (TDateTime) – out параметр. Дата с которой сертификат считается невалидным.
• SignatureAlgorithm (String) – out параметр. OID алгоритма подписи сертификата.

Return type:

boolean

CertInfoByBlob(Data: Blob; out Issuer: String; out Subject: String; out NotBefore: TDateTime; out NotAfter: TDateTime; out SignatureAlgorithm: String): boolean

Получить данные сертификата из его бинарного представления (TbtkCryptorCertificate.RawData).

Parameters:

• Data (Blob) – Бинарное представление сертификата.
• Issuer (String) – out параметр. Наименование организации выдавшей сертификат.
• Subject (String) – out параметр. Наименование субъекта которому выдан сертификат.
• NotBefore (TDateTime) – out параметр. Дата с которой сертификат считается валидным.
• NotAfter (TDateTime) – out параметр. Дата с которой сертификат считается невалидным.
• SignatureAlgorithm (String) – out параметр. OID алгоритма подписи сертификата.

Return type:

boolean

GetThumbprintHexStringByCertID(CertID: String): String

Отпечаток сертификата в виде строки шестнадцатеричных цифр без пробелов.

Например:

ca28201a69d921711ba37eac4676028647b5fb12

Parameters:CertID (String) – Идентификатор сертификата. Полученный, например, с помощью Cryptor.OpenCertificateDlg(). Return type:String

Пример использования

<PASCAL>
  CertID := Cryptor.OpenCertificateDlg;
  thumbPrint := Cryptor.GetThumbprintHexStringByCertID(CertID);
  ShowMessage('Отпечаток выбранного сертификата = ' + thumbPrint);
</PASCAL>

Deprecated since version 5.5.0.3950: Следует использовать TbtkCryptorCertificate.Thumbprint.

VerifyCertFromSignInCRL(Sign: Blob): Boolean

Проверяет наличие сертификата из подписи в списках отозванных.

Parameters:Sign (Blob) – ЭЦП. Return type:Boolean

Пример использования

<pascal>
if VerifyCertFromSignInCRL(sign) then
  ShowMessage('Сертификату, которым была создана данная подпись, можно доверять')
else
  ShowMessage('Сертификат, которым создали данну подпись, был отозван');
</pascal>

VerifyCertInCRL(CertID: String): Boolean

Проверяет наличие сертификата в списках отозванных по идентификатору сертификата.

Parameters:CertID (String) – Идентификатор сертификата. Return type:Boolean

Пример использования

<pascal>
  CertID := Cryptor.OpenCertificateDlg;
  if VerifyCertFromSignInCRL(CertID) then
    ShowMessage('Сертификату можно доверять')
  else
    ShowMessage('Сертификат отозван');
</pascal>

RefreshCRL(Sign: Blob; Log: Sting; Force: Boolean): Boolean

Обновляет списки отозванных сертификатов.

Parameters:

• Sign (Blob) – ЭЦП.
• Log (String) – Строка, в которую будет записана информация об ошибках при их наличии.
• Force (Boolean) – Если установлен в False, то функция проверяет действительность списка отозванных сертификатов и обновляет его только при необходимости, иначе обновляет без проверки.

Return type:

Boolean

Пример использования

<pascal>
  var
    spLog: string;
  begin
    if RefreshCRL(sign, spLog, true) then
      ShowMessage('Списки были удачно обновлены')
    else
      ShowMessage(spLog);
  end;
</pascal>

IsCRLOutOfDate(Sign: Blob): Boolean

Проверка актуальности списка отозванных сертификатов.

Parameters:Sign (Blob) – Подпись Return type:Boolean Returns:

False

Список актуален.

True

Нет списка или он устарел.

Пример использования

<pascal>
  if IsCRLOutOfDate(sign) then
    ShowMessage('Нет списка или он устарел');
  else
    ShowMessage('Список актуален');
</pascal>

LoadCRLByURL(Url: String; out Crl: Blob): Boolean

Функция загружает по заданному адресу список отозванных сертификатов.

Parameters:

• Url (String) – URL адрес, с которого загружается список сертификатов.
• Crl (Blob) – out параметр. Cписок сертификатов.

Return type:

Boolean

Пример использования

<pascal>
var
  crl: string;
Begin
  if LoadCRLByURL('http://test.ru/my.crl', crl) then
    ShowMessage('Список отозванных сертификатов загружен')
  else
    ShowMessage('Ошибка загрузки');
end.
</pascal>

AddCRLToRoot(Crl: Blob): Boolean

Добавление списка отозванных сертификатов в хранилище “Доверенные корневые центры сертификации”.

Parameters:Crl (Blob) – Список сертификатов. Return type:Boolean

Пример использования

<pascal>
  var
    crl: text;
  begin
    if LoadCRLByURL('http://aaaaa.ru/new.crl', crl) then
      ShowMessage('crl загружен');

    if AddCRLToRoot(crl) then
      ShowMessage('crl установлен');
  end;
</pascal>

SignMessage(Data: Variant; CertID: String; out Sign: Blob; DetachedSignature: boolean = True)

Подписывает переданные данные указанным сертификатом. Если подписать не удаётся возбуждается исключение.

Note

Метод не предполагает возвращение результата, кроме подписи возвращаемой через out параметр. Из-за ошибки допущенной при реализации, метод изначально возвращал True. В старой прикладной логике может встречаться проверка возвращаемого результата, такой код будет работать и в этом клиенте. В целях совместимости метод всё ещё возвращает True. Но пользы от этих проверок нет.

Parameters:

• Data (Variant) –

  Данные для подписания. Blob, либо строка.

  Attention

  Не рекомендуется передавать в метод строку. Нет гарантии что кодировки строк на подписывающей и верифицирующей стороне будут совпадать.

• CertID (String) – Идентификатор сертификата, либо пустая строка. Если передана пустая строка либо сертификат по указанному ID не найден, отобразится диалоговое окно выбора сертификата.
• Sign (Blob) – Сформированная ЭЦП.
• DetachedSignature (boolean) –

  Подписать с откреплённой подписью.

  Необязательный параметр. Значение по-умолчанию - True

Changed in version Global_5.10.0_ms5: Добавлена возможность подписывать Blob

Changed in version Global_5.12.0_ms14: Добавлен параметр DetachedSignature

Пример использования

<pascal>
  blob := StringToBlob('Some text', 65001);
  cryptor.SignMessage(blob, certID, sign);
</pascal>

GetDateFromSign(Sign: Blob; out Date: TDateTime): Boolean

Получение даты подписи. По умолчанию при подписании данных ставится дата UTC

Parameters:

• Sign (Blob) – ЭЦП.
• Date (TDateTime) – out параметр. Дата подписи.

Return type:

Boolean

Пример использования

<pascal>
  var
    d: TDateTime;
  Begin
    if GetDateFromSign(sign, d) then
      ShowMessage(DateTimeToStr(d));
  end.
</pascal>

VerifyCertificate(CertID, MessageError: String): Integer

Проверка сертификата на возможность его использовать, а именно: даты действия, построение цепочки сертификатов и т.д.

Parameters:

• CertID (String) – серийный номер сертификата
• MessageError (String) – возвращаемое текстовое сообщение в результате не прохождения проверки сертификата

Return type:

Integer

Returns:

0 - в результате успешного прохождения проверки сертификата или код ошибки.

Пример использования

<pascal>
  if Cryptor.VerifyCertificate(VerifyCertID, messageError) = 0 then
    ShowMessage('Сертификат подтверждён')
  else
    ShowMessage('Сертификат не подтверждён: ' + messageError);
</pascal>

VerifyMessage(Data: Variant; Sign: Blob; Log: String; DetachedSignature: Boolean): Boolean

Метод верифицирует ЭЦП.

Parameters:

• Data (Variant) –

  Данные для проверки. Blob, либо строка.

  Attention

  Не рекомендуется передавать строку. Нет гарантии что кодировки строк на подписывающей и верифицирующей стороне будут совпадать.

• Sign (Blob) – Проверяемая ЭЦП
• Log (String) – В случае успеха содержит серийный номер сертификата, с помощью которого была создана ЭЦП, либо текст ошибки в противном случае.
• DetachedSignature (Boolean) –

  Проверяемая ЭЦП подписана с откреплённой подписью.

  Необязательный параметр. Значение по-умолчанию - True.

Return type:

Boolean

Returns:

True

Подпись подтверждена.

False

Подпись не подтверждена.

Changed in version Global_5.10.0_ms5: Добавлена возможность верифицировать подпись для Blob

Changed in version Global_5.12.0_ms15: Добавлен параметр DetachedSignature

Пример использования

<pascal>
  if Cryptor.VerifyMessage(data, sign, spLog) then
    ShowMessage('Подпись подтверждена!')
  else
    ShowMessage('Подпись не подтверждена! Причина:' + spLog );
</pascal>

OpenCertificateDlg(): String

Открывает диалоговое окно выбора сертификата.

Return type:String Returns:серийный номер сертификата в шестнадцатеричной системе счисления.

Пример использования

<pascal>
  var
    CertID: string;
  begin
    CertID := Cryptor.OpenCertificateDlg;
    ShowMessage(CertID);
  end.
</pascal>

SignAndEncryptMessage(BlobToSignAndEncrypt: Blob; SignerCert, RecipientCert: TbtkCryptorCertificate; EncryptionAlgorithm: String): TbtkSignAndEncryptMessageResult

Подписывает и зашифровывает данные в формате PKCS #7.

Parameters:

• BlobToSignAndEncrypt (Blob) – Данные для подписания и зашифрования.
• SignerCert (TbtkCryptorCertificate) – Сертификат отправителя. Этим сертификатом данные будут подписаны.
• RecipientCert (TbtkCryptorCertificate) – Сертификат получателя. Данные будут зашифрованы с помощью открытого ключа из этого сертификата.
• EncryptionAlgorithm (String) – OID алгоритма шифрования.

Return type:

TbtkSignAndEncryptMessageResult

Пример использования

<pascal>
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;
</pascal>

See also

• Cryptor.DecryptAndVerifyMessageSignature()
• Пример шифрования содержимого в PKCS #7

New in version Global_5.9.0.

DecryptAndVerifyMessageSignature(SignedAndEncryptedBlob: Blob; CertStores: array of String = ['CA', 'MY', 'ROOT']; SignerIndex: Integer = 0): TbtkDecryptAndVerifyMessageSignatureResult

Расшифровывает данные из PKCS #7 и проверяет подпись.

Указание сертификатов для проверки подписи и расшифрования не поддерживается. Требуемые сертификаты будут искаться в хранилищах указанных в параметре CertStores и при успешном завершении вызова будут возвращены в качестве результата.

Parameters:

• SignedAndEncryptedBlob (Blob) – Зашифрованные подписанные данные.
• CertStores (array of String) – Имена хранилищ, в которых будут искаться сертификаты для проверки подписи и расшифрования данных. Если указывается одно хранилище можно передать просто строку а не массив. Поддерживаются хранилища CA, MY и ROOT. Должно быть указано хотя бы одно хранилище, передача пустой строки, пустого массива либо Null приведет к ошибке. Если не передавать значение параметра то по умолчанию поиск осуществляется во всех трёх хранилищах.
• SignerIndex = 0 (Integer) – Индекс подписи отправителя которую требуется проверить. Первая подпись имеет индекс 0. Для проверки нескольких подписей следует вызвать метод несколько раз, с разным значением SignerIndex. Если при выполнении метода вернется ошибка CRYPT_E_NO_SIGNER = $8009200E, значит предыдущая подпись была последней. Заранее определить количество подписей или проверить подпись по конкретному сертификату, метод не позволяет.

Return type:

TbtkDecryptAndVerifyMessageSignatureResult

Пример использования

<pascal>
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;
</pascal>

See also

• Cryptor.SignAndEncryptMessage()
• Пример шифрования содержимого в PKCS #7

New in version Global_5.9.0.

11.2. TbtkCryptorKey

class TbtkCryptorKey

Объект высокоуровневого взаимодействия с “MS CryptoAPI”. Реализует сущность “Ключ шифрования”. Служит для шифрования и расшифровывания данных.

New in version 5.5.8.4460.

11.2.1. Все ключи

EncryptData(Data: Blob; Hash: TbtkCryptorHash = nil): Blob

Зашифровать данные

Parameters:

• Data (Blob) – Данные для зашифрования
• Hash = nil (TbtkCryptorHash) – Хеш данных до зашифрования

DecryptData(Data: Blob; Hash: TbtkCryptorHash = nil): Blob

Расшифровать данные. Метод обратный к EncryptData()

Parameters:

• Data (Blob) – Данные для расшифровки
• Hash = nil (TbtkCryptorHash) – Хеш расшифрованных данных

Export(BlobType: Integer; EncKey: TbtkCryptorKey = nil; Flags: Integer = 0): Blob

Сериализовать (выгрузить) ключ шифрования в указанном формате CSP

Parameters:

• BlobType (Integer) –

  Формат предусмотренный CSP для сериализации ключей.

  Доступные варианты:

  • `SIMPLEBLOB` = $1; - сессионный ключ
  • `PUBLICKEYBLOB` = $6; - публичный ключ
  • `PRIVATEKEYBLOB` = $7; - секретный ключ
  • `PLAINTEXTKEYBLOB`  $8; - ключ в открытом формате
  • Также, некоторые CSP могут определять свои форматы.
• EncKey = nil (TbtkCryptorKey) – Ключ которым будет шифроваться сериализованный ключ. Параметр применим, среди стандартных способов сериализации, для выгрузки сессионных ключей.
• Flags = 0 (Integer) – Определяет дополнительные опции выгрузки, см. MSDN , параметр dwFlags

DuplicateKey(): TbtkCryptorKey

Метод создаёт дубликат ключа. Может быть полезно, если ожидается модификация ключа, но в будущем потребуется ключ с изначальными параметрами.

Return type:TbtkCryptorKey

AlgID: String

Алгоритм ключа в представлении OID-идентификатора

AlgID: Integer

Алгоритм ключа в числовом представлении. Не каждому алгоритму ключа будет соответствовать международный стандартизированный идентификатор (Object ID), в связи с чем реализована возможность задать его значение специфичным для CSP.

Например, смешанным (mixture) ключам по алгоритму Диффи-Хеллмана присущ алгоритм выгрузки сессионных ключей, но такие алгоритмы локальной значимости не стандартизируются.

В CSP CryptoPro реализованы два таких алгоритма выгрузки:

• CALG_PRO_EXPORT = 661F
• CALG_SIMPLE_EXPORT = 6620

BlockLen: Integer

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

Может зависеть от CypherMode

Атрибут только для чтения

KeyLen: Integer

Действительная (без учёта выравниваний) длина ключа, в битах.

Атрибут только для чтения

Salt: Blob

Значение соли ключа шифрования

11.2.2. Блочные ключи

CypherMode: Integer

Режим шифрования

Стандартные режимы :

• CBC = 1
• ECB = 2
• OFB = 3
• CFB = 4
• CTS = 5
• Могут дополняться (и запрещаться) реализацией используемого CSP

CypherModeBits: Integer

Дополнительный параметр для режимов шифрования CFB и OFB. Количество передаваемых от блока к блоку бит.

Padding: Integer

Способ дополнения блоков блочного шифра

Доступные варианты:

• PKCS5_PADDING = 1
• RANDOM_PADDING = 2
• ZERO_PADDING = 3

Vector: Blob

Вектор инициализации (IV) алгоритма блочного шифра

11.2.3. Разрешения ключа

AllowArchive: Boolean

Свойство сообщает, что данный ключ доступен для выгрузки. Но только до момента закрытия объекта ключа. Выставляется флагами при генерации ключа и сбрасывается CSP после (открыв ключ в слелующи раз - будет невыгружаемым)

Атрибут только для чтения

AllowDecrypt: Boolean

Ключ можно использовать в методах дешифрации

Атрибут только для чтения

AllowEncrypt: Boolean

Ключ можно использовать в методах шифрования

Атрибут только для чтения

AllowExport: Boolean

Ключ можно выгрузить в открытом виде.

Атрибут только для чтения

AllowExportKey: Boolean

ключ может использоваться для шифрования экспортируемых ключей

Атрибут только для чтения

AllowImportKey: Boolean

ключ может использоваться для расшифровки импортируемых ключей

Атрибут только для чтения

AllowRead: Boolean

Значение CRYPT_READ бита в параметре KP_PERMISSIONS.

Атрибут только для чтения

AllowWrite: Boolean

Значение CRYPT_WRITE бита в параметре KP_PERMISSIONS.

Атрибут только для чтения

11.3. TbtkCryptorHash

class TbtkCryptorHash

Объект высокоуровневого взаимодействия с “MS CryptoAPI”. Реализует сущность “Хешер”.

Время жизни управляется счётчиком ссылок :

• освобождается простым занулением переменной где он хранится
• можно смело передавать его между операциями и выборками, даже асинхронными

See also

• TbtkCryptorProvider.CreateHash()
• Cryptor.CreateHashByCert()
• TbtkCryptorCertificate

New in version 5.5.0.3950.

Value(): Blob

Получить рассчитанный хеш данных.

Return type:Blob

Attention

после вызова - хеш изменить будет невозможно TbtkCryptorHash.HashData()

Sign(): Blob

Подписать рассчитанный хеш (TbtkCryptorHash.Value()) данных ассоциированным с хешером набором ключей шифрования(TbtkCryptorHash.Keyset())

Return type:Blob Raises:Если ключи не ассоциированы с хешером (TbtkCryptorHash.Keyset = TbtkCryptKeyset.ckNone).

Attention

после вызова - хеш изменить будет невозможно TbtkCryptorHash.HashData()

VerifySign(Sign: Blob; PubKey: TbtkCryptorKey; Flags: Integer = 0): Boolean

Проверить подпись на соответствие хешу. Результат True - фактическое подтверждение, что держатель сертификата (которому принадлежит публичный ключ) подтверждает целостность (неизменённость) данных, по которым рассчитан хеш.

Parameters:

• Sign (Blob) – Значение цифровой подписи.
• PubKey (TbtkCryptorKey) – Публичный ключ сертификата, которым подписаны данные.
• Flags (Integer) – Управляющие флаги, необязательный параметр. Использование флагов регламентируется конкретной реализацией CSP. В подавляющем большинстве случаев их передача не требуется.

Пример использования

<PASCAL>
  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));
</PASCAL>

Keyset(): TbtkCryptKeyset

Набор ключей который будет использован для подписания (TbtkCryptorHash.Sign()) хеша.

Return type:TbtkCryptKeyset

Note

если ключи не ассоциированы с хешером (TbtkCryptKeyset.ckNone) - метод TbtkCryptorHash.Sign() возбудит исключение.

HashData(Data: Blob)

Метод хеширует указанные данные.

Поддерживается итеративное хеширование - можно последовательно вызвать метод для добавления в хеш новых пакетов данных, что равносильно тому как если бы все пакеты данных были последовательно помещены в один большой блоб и метод был бы вызван один раз. Такой подход позволяет парциально хешировать сколь угодно большой объём данных.

Parameters:Data (Blob) – Очередной блоб данных для хеширования.

Note

добавлять порции в хеш можно до тех пор пока не будет вызван метод получения хеша (TbtkCryptorHash.Value() или TbtkCryptorHash.Sign()).

HashSessionKey(Key: TbtkCryptorKey)

Добавить к значению хеша данные ключа шифрования.

Param:

TbtkCryptorKey Key

Ключ симметричного шифрования

New in version 5.5.8.4460.

11.4. TbtkCryptorProvider

class TbtkCryptorProvider

Объект высокоуровневого взаимодействия с “MS CryptoAPI”. Объект доступа к хранилищу секретных ключей с использованием выбранного (по типу реализуемого функционала, или иным признакам) CSP(алгоритмов).

New in version 5.5.8.4460.

CreateHash(AlgID: String): TbtkCryptorHash

Создать новый объект хеширования

Parameters:AlgID (String) –

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”

Return type:TbtkCryptorHash

CreateKeyByPrivate(KeySet: TbtkCryptKeyset = ckKeyExchange): TbtkCryptorKey

Создать объект секретного ключа из контейнера с которым ассоциирован провайдер

Parameters:KeySet = ckKeyExchange (TbtkCryptKeyset) – Указывает из какой пары ключ. Ключ обмена данными, или подписания данных. По умолчанию, как наиболее востребованный,- ключ обмена данными. Raises:Если ключ запрошенного типа отсутствует в провайдере. Return type:TbtkCryptorKey

CreateKeyByPublic(Cert: TbtkCryptorCertificate): TbtkCryptorKey

Создать объект публичного ключа из сертификата безопасности разместив ключ в провайдере

Parameters:Cert (TbtkCryptorCertificate) – Сертификат, из которого будет загружен публичный ключ Return type:TbtkCryptorKey

CreateKeyByImport(KeyBlob: Blob; EncKey: TbtkCryptorKey = nil; Flags: Integer = CRYPT_EXPORTABLE): TbtkCryptorKey

Загрузить ключевой блоб в криптопровайдер. Тип ключа и параметры определяются самим блобом. Метод комплементарен TbtkCryptorKey.Export().

Parameters:

• KeyBlob (Blob) – Сериализованный CSP ключ шифрования
• EncKey = nil (TbtkCryptorKey) – Ключ которым зашифрован KeyBlob. Необходимость в ключе шифрования определяется типом загружаемого ключа и алгоритмами CSP. Для загрузки блобов публичных ключей ключ шифрования не требуется.
• Flags = CRYPT_EXPORTABLE (integer) – Флаги создания ключа, см. MSDN , параметр dwFlags.

Return type:

TbtkCryptorKey

CreateKeyByGenKey(AlgID: String; Flags: Integer = CRYPT_EXPORTABLE): TbtkCryptorKey

Сгенерировать новый ключ со случайными параметрами по указанному алгоритму.

Parameters:

• AlgID (String) – Алгоритм ключа. Например, 1.2.643.2.2.21 - ключ симметричного шифрования, ГОСТ 28147.
• Flags = CRYPT_EXPORTABLE (Integer) – Флаги создания ключа, см. MSDN , параметр dwFlags.

Return type:

TbtkCryptorKey

CreateKeyByHash(AlgID: String; Hash: TbtkCryptorHash; Flags: Integer = CRYPT_EXPORTABLE): TbtkCryptorKey

Создать новый ключ шифрования по данным хеша

Parameters:

• AlgID (String) – Алгоритм ключа. Например, 1.2.643.2.2.21 - ключ симметричного шифрования, ГОСТ 28147.
• Hash (TbtkCryptorHash) – Хеш-объект из значения которого будет сконструирован ключ. Для одинаковых хешей будут сконкструированы одинаковые ключи.
• Flags = CRYPT_EXPORTABLE (Integer) – Флаги создания ключа, см. MSDN , параметр dwFlags.

Return type:

TbtkCryptorKey

KeyExchangeKeySetExists: Boolean

Содержатся ли в контейнере ключи обмена данными.

Атрибут только для чтения

SignatureKeySetExists: Boolean

Содержатся ли в контейнере ключи подписания данных.

Атрибут только для чтения

11.5. TbtkCryptorCertificate

class TbtkCryptorCertificate

Объект высокоуровневого взаимодействия с “MS CryptoAPI”. Реализует сущность “Сертификат безопасности”.

Время жизни управляется счётчиком ссылок :

• освобождается простым занулением переменной где он хранится
• можно смело передавать его между операциями и выборками, даже асинхронными

See also

• Cryptor.CreateCertByDialog()
• Cryptor.CreateCertByBlob()
• Cryptor.CreateCertByID()
• Cryptor.CreateCertBySign()
• TbtkCryptorHash

Thumbprint: Blob

Хеш бинарного представления сертификата (TbtkCryptorCertificate.RawData) рассчитанный алгоритмом SHA1.

Return type:Blob

SerialNumber: Blob

Порядковый номер сертификата присвоенный ему издателем. Integer неограниченной длинны (в нотации BigEndian).

Return type:Blob

RawData: Blob

Бинарное представление сертификата.

Return type:Blob

SignatureAlgorithm: String

OID алгоритма подписи сертификата.

Return type:String

PublicKeyAlgorithm: String

OID алгоритма хеширования публичного ключа.

Return type:String

NotBefore: TDateTime

Дата с которой сертификат считается валидным.

Return type:TDateTime

NotAfter: TDateTime

Дата с которой сертификат считается невалидным.

Return type:TDateTime

KeepLoggedIn: Boolean

True

Не перезапрашивать пароль на доступ к хранилищу закрытого ключа.

False

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

Return type:Boolean

ID: String

Строка используемая для идентификации сертификата в методах Cryptor. Свойство добавлено для обратной совместимости с ранее реализованным процедурным подходом.

Return type:String

SubjectName(Format: TbtkCertNameFormat = cnfX500; Flags: Variant = null): String

Наименование субъекта которому выдан сертификат.

Parameters:

• Format (TbtkCertNameFormat) – Представление в котором будет возвращено имя.
• Flags (Variant) – Зарезервировано. Не используется. Управляющие флаги, могут использоваться различные значения в зависимости от используемого представления.

Return type:

String

IssuerName(Format: TbtkCertNameFormat = cnfX500; Flags: Variant = null): String

Наименование организации выдавшей сертификат.

Parameters:

• Format (TbtkCertNameFormat) – Представление в котором будет возвращено имя.
• Flags (Variant) – Зарезервировано. Не используется. Управляющие флаги, могут использоваться различные значения в зависимости от используемого представления.

Return type:

String

Provider: TbtkCryptorProvider

Хранилище приватных ключей сертификата. Если с сертификатом не ассоциированно такого хранилища - генерируется исключение.

Атрибут только для чтения

Return type:TbtkCryptorProvider

11.6. TbtkCertNameFormat

class TbtkCertNameFormat

Перечисление. Формат в котором представлено наименование сертификата.

See also

• TbtkCryptorCertificate.IssuerName()
• TbtkCryptorCertificate.SubjectName()

cnfX500

Имя формируется по правилам определённым Microsoft в CryptoAPI. При формировании используются заголовки (буквенные обозначения) параметров имени.

cnfOid

Имя формируется по правилам определённым Microsoft в CryptoAPI. При формировании используются OID параметров имени.

cnfSimple

Имя формируется по правилам определённым Microsoft в CryptoAPI. Формируется из одних только значений параметров, без заголовков.

cnfRFC1779

Имя формируется в точном соответствии RFC1779, без лирических отступлений Microsoft от стандарта.

11.7. TbtkCryptKeyset

class TbtkCryptKeyset

Перечисление. Набор ключей шифрования.

See also

• TbtkCryptorHash.Keyset

ckKeyExchange

Набор ключей для обмена данными. Также подходит и для подписывания данных (более широкий чем TbtkCryptKeyset.ckSignature)

ckSignature

Набор ключей для подписывания данных. Вместо него также может использоваться набор ключей TbtkCryptKeyset.ckKeyExchange

ckNone

Набор ключей шифрования отсутствует.

11.8. TbtkSignAndEncryptMessageResult

class TbtkSignAndEncryptMessageResult

Агрегирует информацию о результате выполнения Cryptor.SignAndEncryptMessage().

New in version Global_5.9.0.

IsSuccessful: Boolean

True если данные успешно подисаны и зашифрованы, False в противном случае.

SignedAndEncryptedBlob: Blob

Содержит зашифрованные и подписанные данные, если вызов завершился успешно.

ErrorCode: Integer;

Содержит код ошибки, если вызов не завершился успешно.

ErrorMessage: String;

Содержит текст ошибки, если вызов не завершился успешно.

See also

• Cryptor.SignAndEncryptMessage()

11.9. TbtkDecryptAndVerifyMessageSignatureResult

class TbtkDecryptAndVerifyMessageSignatureResult

Агрегирует информацию о результате выполнения Cryptor.DecryptAndVerifyMessageSignature().

New in version Global_5.9.0.

IsSuccessful: Boolean

True если данные успешно расшифрованы и подпись проверена, False в противном случае.

DecryptedBlob: Blob

Содержит расшифрованные данные, если вызов завершился успешно.

SignerCert: TbtkCryptorCertificate

Содержит сертификат отправителя, если вызов завершился успешно.

RecipientCert: TbtkCryptorCertificate

Содержит сертификат получателя, если вызов завершился успешно.

ErrorCode: Integer;

Содержит код ошибки, если вызов не завершился успешно.

ErrorMessage: String;

Содержит текст ошибки, если вызов не завершился успешно.

See also

• Cryptor.DecryptAndVerifyMessageSignature()