PDFium Delphi Component Docs

Модуль FPdfAsn1

Модуль: FPdfAsn1
Кодирует, обходит, декодирует и проверяет данные ASN.1 Distinguished Encoding Rules с ограниченным расходом ресурсов

Public Types

TypeDescription
TAsnTagКонстанты универсальных тегов (BOOLEAN, INTEGER, OCTET STRING, OID, SEQUENCE, SET, формы времени и строк), используемые при построении и проверке идентификаторов
TAsnClassКласс идентификатора: asnClassUniversal, asnClassApplication, asnClassContextSpecific или asnClassPrivate
TAsnIdentifierКласс идентификатора, признак constructed и 64-битный номер тега, включая форму старших номеров тегов
TDerTlvРазобранный TLV с полями Offset, HeaderLength, ContentOffset, ContentLength, NextOffset и Identifier без копирования исходного буфера
TDerWriterМногоразовый выходной буфер DER и типизированный кодировщик
TDerReaderОграниченный читатель с операциями просмотра, продвижения, пропуска, проверки ожидаемого тега, дочернего окна, срезов и типизированного декодирования
TDerByteArraysДинамический массив TBytes, используемый ConcatMany и другими помощниками над несколькими буферами
TDerValidationErrorKindКатегории ошибок проверки: dvekMalformedTlv, dvekTrailingData, лимиты глубины, узлов и содержимого (dvekDepthLimit, dvekNodeLimit, dvekContentLimit), dvekUniversalForm, канонические сбои по типам (dvekBoolean, dvekInteger, dvekBitString, dvekNull, dvekOid, dvekString, dvekTime) и dvekSetOrder
TDerValidationErrorЗапись об ошибке, учитывающая смещение и Depth, с полем Kind и понятным человеку текстом сообщения
TDerValidationErrorsДинамический массив TDerValidationError, возвращаемый внутри TDerValidationResult
TDerValidationOptionsЛимиты MaxDepth, MaxNodes, MaxContentLength и MaxErrors, флаг RequireSingleRoot, необязательный ValidateSetOrder и метод класса Default
TDerValidationResultСтатус проверки с IsValid, NodeCount, MaximumDepth и учитывающими смещение Errors, плюс помощники ErrorCount и FirstError

Writer APIs

APIDescription
Clear, IsEmpty, Count, Capacity, Bytes, FinishСброс или осмотр буферизованных данных, копирование снимка либо передача готового массива со сбросом писателя
Reserve, Append, AppendMany, AppendByteОднократное расширение и добавление массивов, буферов вызывающего кода, нескольких массивов или одного байта с проверками переполнения
Wrap, WrapIdentifier, WrapConstructedОбёртывание содержимого сырым октетом идентификатора, любым классом идентификатора с 64-битным номером тега или constructed-идентификатором
ContextSpecific, ApplicationSpecific, PrivateSpecificКодирование младших или старших номеров тегов без усечения идентификатора
Sequence, SequenceOf, SetOf, SetOfSortedКомпоновка закодированных значений в контейнеры SEQUENCE или SET; SetOfSorted сортирует значения по закодированным байтам
BooleanOf, IntegerOf, UnsignedIntegerOf, IntegerBytes, EnumeratedOfКодирование BOOLEAN, знакового или беззнакового INTEGER, проверенного содержимого INTEGER произвольной длины и значений ENUMERATED
OctetString, OctetStringOf, BitString, Null, OIDКодирование двоичных значений, битовых строк, NULL и идентификаторов объектов как самостоятельных TLV
PrintableString, Ia5String, Utf8StringКодирование поддерживаемых форм символьных строк ASN.1
UTCTime, GeneralizedTime, UTCTimeOf, GeneralizedTimeOf, TimeOfКодирование канонического текста времени или значений UTC TDateTime, где TimeOf выбирает правильный тип времени DER
AlgId, AlgIdWithParamsПостроение SEQUENCE AlgorithmIdentifier с параметрами NULL или явными

Reader APIs

APIDescription
Initialize, AtEnd, EffectiveLimit, RemainingИнициализация читателя и осмотр его ограниченного окна и оставшегося числа байтов
TryReadTlvAt, PeekTlvРазбор младших или старших номеров тегов и минимальных определённых длин без изменения Position
ReadNextTlv, SkipTlvПродвижение только после того, как доступен полный корректный TLV
TryReadExpectedПродвижение только при совпадении класса, формы constructed и номера тега
EnterConstructedСоздание дочернего окна читателя над тем же исходным массивом без копирования содержимого
ContentBytes, EncodedBytesКопирование проверенного содержимого или полного среза TLV, когда требуется владение данными
TryReadBoolean, TryReadUnsignedInteger, TryReadBitStringДекодирование канонических примитивных значений с проверками диапазона и неиспользуемых битов
TryReadString, TryReadTime, TryReadNullДекодирование проверенного содержимого UTF8String, PrintableString, IA5String, времени DER или NULL
ReadTlv, TryReadOID, ReadOID, TryReadInteger, ReadIntegerОбеспечивают совместимый доступ к сырым смещениям TLV, а также декодирование идентификаторов объектов и знаковых целых

Validation

function ValidateDer(const Data: TBytes): TDerValidationResult; overload;
function ValidateDer(const Data: TBytes; const Options: TDerValidationOptions): TDerValidationResult; overload;

ValidateDer проверяет минимальность идентификаторов и длин, границы буфера, универсальные примитивные формы, BOOLEAN, INTEGER, ENUMERATED, BIT STRING, NULL, OBJECT IDENTIFIER, поддерживаемые строки и канонические значения времени

Лимиты по умолчанию допускают глубину не более 64, 100000 узлов, 64 МиБ на значение содержимого и 32 сообщаемые ошибки, требуя один корневой TLV

ValidateSetOrder по умолчанию отключён, поскольку DER без схемы не отличает каждый SET от SET OF; включайте его для известных контейнеров SET OF, например коллекций атрибутов CMS

TDerValidationOptions.Default задаёт ограниченные значения по умолчанию, а TDerValidationResult.ErrorCount и FirstError упрощают обработку диагностики

Public helper functions

function AsnIdentifier(TagClass: TAsnClass; TagNumber: UInt64; Constructed: Boolean = False): TAsnIdentifier;
function EncodeIdentifier(const Identifier: TAsnIdentifier): TBytes;
function ConcatBytes(const A, B: TBytes): TBytes;
function Concat3(const A, B, C: TBytes): TBytes;
function Concat4(const A, B, C, D: TBytes): TBytes;
function ConcatMany(const Values: TDerByteArrays): TBytes;
function EncodeOIDContent(const Dotted: AnsiString): TBytes;
function DerValidationErrorKindName(Kind: TDerValidationErrorKind): string;

FunctionDescription
AsnIdentifierСтроит TAsnIdentifier из класса, номера тега и признака constructed; используется для TDerReader.TryReadExpected
EncodeIdentifierКодирует TAsnIdentifier в байты идентификатора DER, включая форму старших номеров тегов
ConcatBytes, Concat3, Concat4, ConcatManyСоединяют два, три, четыре элемента или динамический массив TBytes в одно выделение памяти; широко используются построителем CMS
EncodeOIDContentКодирует строку OID с точками-разделителями в байты содержимого без тега и длины, чтобы вызывающий код мог изучить или заново обернуть OID
DerValidationErrorKindNameВозвращает отображаемое имя TDerValidationErrorKind для диагностики

Example

uses FPdfAsn1;

var
  Child: TDerReader;
  Data: TBytes;
  Reader: TDerReader;
  Tlv: TDerTlv;
  Validation: TDerValidationResult;
  Writer: TDerWriter;
begin
  Writer := TDerWriter.Create;
  try
    Data := Writer.Sequence(Writer.UnsignedIntegerOf(42));
  finally
    Writer.Free;
  end;

  Validation := ValidateDer(Data);
  if not Validation.IsValid then
    raise EConvertError.Create(Validation.Errors[0].MessageText);

  Reader.Initialize(Data);
  if Reader.TryReadExpected(AsnIdentifier(asnClassUniversal, 16, True), Tlv) then
    Reader.EnterConstructed(Tlv, Child);
end;

Remarks