asn

ИМЯ

asn — кодировщик/декодировщик ASN.1 BER

Содержание

Содержание
Краткое описание
Описание
ПУБЛИЧНЫЙ API
ПРИМЕРЫ
Ошибки, идеи и отзывы
Категория
Авторские права

КРАТКОЕ ОПИСАНИЕ

package require Tcl 8.5 9
package require asn ?0.8.5?

::asn::asnSequence evalue...
::asn::asnSequenceFromList elist
::asn::asnSet evalue...
::asn::asnSetFromList elist
::asn::asnApplicationConstr appNumber evalue...
::asn::asnApplication appNumber data
::asn::asnChoice appNumber evalue...
::asn::asnChoiceConstr appNumber evalue...
::asn::asnInteger number
::asn::asnEnumeration number
::asn::asnBoolean bool
::asn::asnContext context data
::asn::asnContextConstr context evalue...
::asn::asnObjectIdentifier idlist
::asn::asnUTCTime utcstring
::asn::asnNull
::asn::asnBitString string
::asn::asnOctetString string
::asn::asnNumericString string
::asn::asnPrintableString string
::asn::asnIA5String string
::asn::asnBMPString string
::asn::asnUTF8String string
::asn::asnString string
::asn::defaultStringType ?type?
::asn::asnPeekByte data_var byte_var
::asn::asnGetLength data_var length_var
::asn::asnGetResponse chan data_var
::asn::asnGetInteger data_var int_var
::asn::asnGetEnumeration data_var enum_var
::asn::asnGetOctetString data_var string_var
::asn::asnGetString data_var string_var ?type_var?
::asn::asnGetNumericString data_var string_var
::asn::asnGetPrintableString data_var string_var
::asn::asnGetIA5String data_var string_var
::asn::asnGetBMPString data_var string_var
::asn::asnGetUTF8String data_var string_var
::asn::asnGetUTCTime data_var utc_var
::asn::asnGetBitString data_var bits_var
::asn::asnGetObjectIdentifier data_var oid_var
::asn::asnGetBoolean data_var bool_var
::asn::asnGetNull data_var
::asn::asnGetSequence data_var sequence_var
::asn::asnGetSet data_var set_var
::asn::asnGetApplication data_var appNumber_var ?content_var? ?encodingType_var?
::asn::asnGetContext data_var contextNumber_var ?content_var? ?encodingType_var?
::asn::asnPeekTag data_var tag_var tagtype_var constr_var
::asn::asnTag tagnumber ?class? ?tagstyle?
::asn::asnRetag data_var newTag

ОПИСАНИЕ

Пакет asn предоставляет команды для частичного кодирования и декодирования данных ASN.1, закодированных в BER. Его также можно использовать для декодирования DER — ограниченного подмножества BER.

ASN.1 — это стандартная абстрактная синтаксическая нотация, а BER — её базовые правила кодирования.

Дополнительные сведения о стандарте см. на странице http://asn1.elibel.tm.fr/en/standards/index.htm.

Также см. http://luca.ntop.org/Teaching/Appunti/asn1.html: Руководство для неспециалистов по подмножеству ASN.1, BER и DER — техническую заметку RSA Laboratories, подготовленную Burton S. Kaliski Jr. (пересмотрена 1 ноября 1993 г.). Текстовая версия этой заметки входит в исходные тексты модуля; её следует прочитать всем, кто занимается реализацией.

ПУБЛИЧНЫЙ API

КОДИРОВЩИК

::asn::asnSequence evalue...

Принимает ноль или более закодированных значений, объединяет их в последовательность ASN и возвращает её закодированное двоичное представление.
::asn::asnSequenceFromList elist

Принимает список закодированных значений, объединяет их в последовательность ASN и возвращает её закодированное двоичное представление.
::asn::asnSet evalue...

Принимает ноль или более закодированных значений, объединяет их в набор ASN и возвращает его закодированное двоичное представление.
::asn::asnSetFromList elist

Принимает список закодированных значений, объединяет их в набор ASN и возвращает его закодированное двоичное представление.
::asn::asnApplicationConstr appNumber evalue...

Принимает ноль или более закодированных значений, объединяет их в конструкцию ASN приложения и возвращает её закодированное двоичное представление.
::asn::asnApplication appNumber data

Принимает одно закодированное значение data, помещает его в конструкцию ASN приложения и возвращает её закодированное двоичное представление.
::asn::asnChoice appNumber evalue...

Принимает ноль или более закодированных значений, объединяет их в конструкцию ASN choice и возвращает её закодированное двоичное представление.
::asn::asnChoiceConstr appNumber evalue...

Принимает ноль или более закодированных значений, объединяет их в конструкцию ASN choice и возвращает её закодированное двоичное представление.
::asn::asnInteger number

Возвращает закодированное представление указанного целого числа number.
::asn::asnEnumeration number

Возвращает закодированное представление указанного идентификатора перечисления number.
::asn::asnBoolean bool

Возвращает закодированное представление указанного логического значения bool.
::asn::asnContext context data

Принимает закодированное значение и помещает его в конструкцию с тегом приложения и номером context.
::asn::asnContextConstr context evalue...

Принимает ноль или более закодированных значений и помещает их в конструкцию с тегом приложения и номером context.
::asn::asnObjectIdentifier idlist

Принимает список как минимум из двух целых чисел, описывающих значение идентификатора объекта (OID), и возвращает закодированное значение.
::asn::asnUTCTime utcstring

Возвращает закодированное представление указанной строки времени UTC.
::asn::asnNull

Возвращает кодировку NULL.
::asn::asnBitString string

Возвращает закодированное представление указанной строки string.
::asn::asnOctetString string

Возвращает закодированное представление указанной строки string.
::asn::asnNumericString string

Возвращает строку string, закодированную как ASN.1 NumericString. Вызывает ошибку, если string содержит символы, отличные от десятичных цифр и пробела.
::asn::asnPrintableString string

Возвращает строку string, закодированную как ASN.1 PrintableString. Вызывает ошибку, если string содержит символы, недопустимые для типа данных Printable String. Допустимы символы A-Z, a-z, 0-9, пробел, апостроф, двоеточие, круглые скобки, плюс, минус, запятая, точка, косая черта, вопросительный знак и знак равенства.
::asn::asnIA5String string

Возвращает строку string, закодированную как ASN.1 IA5String. Вызывает ошибку, если string содержит символы за пределами диапазона US-ASCII.
::asn::asnBMPString string

Возвращает строку string, закодированную как строку ASN.1 Basic Multilingual Plane (по сути, UCS2 с порядком байтов от старшего к младшему).
::asn::asnUTF8String string

Возвращает строку string, закодированную как UTF8 String. Учтите, что некоторые устаревшие приложения, например Windows CryptoAPI, не поддерживают строки UTF8. Если вы не уверены, используйте BMPStrings.
::asn::asnString string

Возвращает закодированное представление строки string, выбирая наиболее ограниченный из возможных типов строк ASN.1. Если строка содержит символы, отличные от ASCII, можно использовать несколько типов строк. См. ::asn::defaultStringType.
::asn::defaultStringType ?type?

Выбирает тип строки для кодирования строк, содержащих символы, отличные от ASCII. При вызове без аргумента возвращает текущее значение по умолчанию. Если указан аргумент type, он должен быть равен UTF8 или BMP, чтобы выбрать соответственно UTF8String или BMPString.

ДЕКОДИРОВЩИК

Общие замечания:

Почти все команды декодирования принимают два аргумента. Это имена переменных, за исключением ::asn::asnGetResponse. Первая переменная изначально содержит закодированное значение ASN, которое нужно декодировать в начале данных; вторая переменная предназначена для сохранения значения. Оставшаяся после декодированного значения часть входных данных записывается обратно в переменную с данными.
После извлечения сначала всегда изменяется переменная с данными, и только затем извлечённое значение записывается в указанную переменную. Это означает, что если оба аргумента ссылаются на одну и ту же переменную, после вызова в ней всегда будет находиться извлечённое значение, а не оставшаяся часть входных данных.
::asn::asnPeekByte data_var byte_var

Извлекает первый байт данных, не изменяя data_var. Это можно использовать для проверки неявных тегов.
::asn::asnGetLength data_var length_var

Декодирует информацию о длине блока данных BER. Тег к этому моменту уже должен быть удалён из данных.
::asn::asnGetResponse chan data_var

Считывает из канала chan закодированную ASN последовательность и сохраняет её в переменной, имя которой указано в data_var.
::asn::asnGetInteger data_var int_var

Предполагает, что в начале данных, хранящихся в переменной data_var, находится закодированное целое число, извлекает его и сохраняет в переменной, имя которой указано в int_var. Кроме того, удаляет из данных все байты, относящиеся к этому значению, чтобы их могли обработать последующие команды декодирования.
::asn::asnGetEnumeration data_var enum_var

Предполагает, что в начале данных, хранящихся в переменной data_var, находится идентификатор перечисления, и сохраняет его в переменной, имя которой указано в enum_var. Кроме того, удаляет из данных все байты, относящиеся к этому значению, чтобы их могли обработать последующие команды декодирования.
::asn::asnGetOctetString data_var string_var

Предполагает, что в начале данных, хранящихся в переменной data_var, находится строка, и сохраняет её в переменной, имя которой указано в string_var. Кроме того, удаляет из данных все байты, относящиеся к этому значению, чтобы их могли обработать последующие команды декодирования.
::asn::asnGetString data_var string_var ?type_var?

Декодирует строку, предназначенную для чтения пользователем. Эта вспомогательная функция автоматически распознаёт все поддерживаемые типы строк ASN.1 и соответствующим образом преобразует входное значение. Команды преобразования для конкретных типов см. ниже: ::asn::asnGetPrintableString, ::asnGetIA5String и т. д.

Если указан необязательный третий аргумент type_var, тип входящей строки сохраняется в переменной с указанным именем.

Если встречается неподдерживаемый тип строки Unsupported, функция вызывает ошибку "Invalid command name asnGetSome__UnsupportedString__". При необходимости в приложении можно создать соответствующую функцию "asn::asnGetSome__UnsupportedString__".
::asn::asnGetNumericString data_var string_var

Предполагает, что в начале данных, хранящихся в переменной data_var, находится числовая строка, и сохраняет её в переменной, имя которой указано в string_var. Кроме того, удаляет из данных все байты, относящиеся к этому значению, чтобы их могли обработать последующие команды декодирования.
::asn::asnGetPrintableString data_var string_var

Предполагает, что в начале данных, хранящихся в переменной data_var, находится печатная строка, и сохраняет её в переменной, имя которой указано в string_var. Кроме того, удаляет из данных все байты, относящиеся к этому значению, чтобы их могли обработать последующие команды декодирования.
::asn::asnGetIA5String data_var string_var

Предполагает, что в начале данных, хранящихся в переменной data_var, находится строка IA5 (ASCII), и сохраняет её в переменной, имя которой указано в string_var. Кроме того, удаляет из данных все байты, относящиеся к этому значению, чтобы их могли обработать последующие команды декодирования.
::asn::asnGetBMPString data_var string_var

Предполагает, что в начале данных, хранящихся в переменной data_var, находится строка BMP (двухбайтовый Unicode), и сохраняет её в переменной, имя которой указано в string_var, преобразуя её в корректную строку Tcl. Кроме того, удаляет из данных все байты, относящиеся к этому значению, чтобы их могли обработать последующие команды декодирования.
::asn::asnGetUTF8String data_var string_var

Предполагает, что в начале данных, хранящихся в переменной data_var, находится строка UTF8, и сохраняет её в переменной, имя которой указано в string_var, преобразуя её в корректную строку Tcl. Кроме того, удаляет из данных все байты, относящиеся к этому значению, чтобы их могли обработать последующие команды декодирования.
::asn::asnGetUTCTime data_var utc_var

Предполагает, что в начале данных, хранящихся в переменной data_var, находится значение времени UTC, и сохраняет его в переменной, имя которой указано в utc_var. Значение времени UTC сохраняется в виде строки, которую нужно декодировать стандартными командами clock scan. Кроме того, удаляет из данных все байты, относящиеся к этому значению, чтобы их могли обработать последующие команды декодирования.
::asn::asnGetBitString data_var bits_var

Предполагает, что в начале данных, хранящихся в переменной data_var, находится битовая строка, и сохраняет её в переменной, имя которой указано в bits_var, в виде строки, содержащей только 0 и 1. Кроме того, удаляет из данных все байты, относящиеся к этому значению, чтобы их могли обработать последующие команды декодирования.
::asn::asnGetObjectIdentifier data_var oid_var

Предполагает, что в начале данных, хранящихся в переменной data_var, находится значение идентификатора объекта (OID), и сохраняет его в переменной, имя которой указано в oid_var, в виде списка целых чисел. Кроме того, удаляет из данных все байты, относящиеся к этому значению, чтобы их могли обработать последующие команды декодирования.
::asn::asnGetBoolean data_var bool_var

Предполагает, что в начале данных, хранящихся в переменной data_var, находится логическое значение, и сохраняет его в переменной, имя которой указано в bool_var. Кроме того, удаляет из данных все байты, относящиеся к этому значению, чтобы их могли обработать последующие команды декодирования.
::asn::asnGetNull data_var

Предполагает, что в начале данных, хранящихся в переменной data_var, находится значение NULL, и удаляет из данных байты, использованные для его кодирования.
::asn::asnGetSequence data_var sequence_var

Предполагает, что в начале данных, хранящихся в переменной data_var, находится последовательность ASN, и сохраняет её в переменной, имя которой указано в sequence_var. Кроме того, удаляет из данных все байты, относящиеся к этому значению, чтобы их могли обработать последующие команды декодирования.

Данные в sequence_var представлены в закодированном двоичном виде и должны быть декодированы далее в соответствии с определением последовательности с помощью приведённых здесь команд декодирования.
::asn::asnGetSet data_var set_var

Предполагает, что в начале данных, хранящихся в переменной data_var, находится набор ASN, и сохраняет его в переменной, имя которой указано в set_var. Кроме того, удаляет из данных все байты, относящиеся к этому значению, чтобы их могли обработать последующие команды декодирования.

Данные в set_var представлены в закодированном двоичном виде и должны быть декодированы далее в соответствии с определением набора с помощью приведённых здесь команд декодирования.
::asn::asnGetApplication data_var appNumber_var ?content_var? ?encodingType_var?

Предполагает, что в начале данных, хранящихся в переменной data_var, находится конструкция ASN приложения, и сохраняет её идентификатор в переменной, имя которой указано в appNumber_var. Кроме того, удаляет из данных все байты, относящиеся к этому значению, чтобы их могли обработать последующие команды декодирования. Если указан аргумент content_var, команда помещает все связанные с ним данные в переменную с указанным именем в двоичном виде, пригодном для обработки командами декодирования этого пакета. Если указан аргумент encodingType_var, этой переменной присваивается значение 1, если кодировка является конструктивной, и 0, если она примитивная.

В противном случае вызывающий код должен самостоятельно декодировать оставшуюся часть конструкции приложения на основе идентификатора, полученного этой командой, используя команды декодирования данного пакета.
::asn::asnGetContext data_var contextNumber_var ?content_var? ?encodingType_var?

Предполагает, что в начале данных, хранящихся в переменной data_var, находится конструкция с контекстным тегом ASN, и сохраняет её идентификатор в переменной, имя которой указано в contextNumber_var. Кроме того, удаляет из данных все байты, относящиеся к этому значению, чтобы их могли обработать последующие команды декодирования. Если указан аргумент content_var, команда помещает все связанные с ним данные в переменную с указанным именем в двоичном виде, пригодном для обработки командами декодирования этого пакета. Если указан аргумент encodingType_var, этой переменной присваивается значение 1, если кодировка является конструктивной, и 0, если она примитивная.

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

ОБРАБОТКА ТЕГОВ

При работе с ASN.1 часто требуется декодировать тегированные значения, в которых используется тег, отличный от универсального тега типа. В таких случаях для декодирования значения необходимо заменить тег универсальным тегом соответствующего типа. Для декодирования тегированного значения используйте ::asn::asnRetag, чтобы заменить тег на подходящий тип и применить одну из команд декодирования примитивных значений. Для этого модуль содержит три функции:

::asn::asnPeekTag data_var tag_var tagtype_var constr_var

Команду ::asn::asnPeekTag можно использовать для просмотра данных и декодирования значения тега, не удаляя его из данных. В tag_var записывается номер тега, а в tagtype_var — класс тега (UNIVERSAL, CONTEXT, APPLICATION или PRIVATE). В constr_var записывается 1, если тег относится к конструктивному значению, и 0, если значение не является конструктивным. Команда возвращает длину тега.
::asn::asnTag tagnumber ?class? ?tagstyle?

Команду ::asn::asnTag можно использовать для создания значения тега. Аргумент tagnumber задаёт номер тега, а class — один из его классов (UNIVERSAL, CONTEXT, APPLICATION или PRIVATE). Название класса можно сократить до первой буквы (U, C, A, P); по умолчанию используется UNIVERSAL. Аргумент tagstyle принимает значение C для конструктивной кодировки или P для примитивной кодировки. По умолчанию используется P. Вместо C и P можно также указать 1 и 0 соответственно, чтобы напрямую использовать значения, возвращаемые командой ::asn::asnPeekTag.
::asn::asnRetag data_var newTag

Заменяет тег в начале данных в data_var на newTag. Новый тег можно создать с помощью команды ::asn::asnTag.

ПРИМЕРЫ

Примеры использования этого пакета можно найти в реализации пакета ldap.

Ошибки, идеи и отзывы

В этом документе и описываемом в нём пакете неизбежно могут быть ошибки и другие проблемы. Сообщайте о них в категории asn системы отслеживания ошибок Tcllib. Также сообщайте о любых идеях по улучшению пакета и/или документации.

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

Обратите внимание: вложения предпочтительнее встроенных патчей. Чтобы добавить вложение, откройте форму Edit соответствующей заявки сразу после её создания и нажмите самую левую кнопку на дополнительной панели навигации.

КАТЕГОРИЯ

Сетевое взаимодействие

АВТОРСКИЕ ПРАВА

Licensed under the BSD license
https://core.tcl-lang.org/tcllib/doc/trunk/embedded/md/tcllib/files/modules/asn/asn.md