RFC 6087 Guidelines for Authors and Reviewers of YANG Data Model Documents

Internet Engineering Task Force (IETF)                        A. Bierman
Request for Comments: 6087                                       Brocade
Category: Informational                                     January 2011
ISSN: 2070-1721

Guidelines for Authors and Reviewers of YANG Data Model Documents

Рекомендации для авторов и рецензентов документов с моделями YANG

PDF

Аннотация

Этот документ содержит руководство для авторов и рецензентов спецификаций Standards Track, содержащих модули с моделями данных YANG. Применимые части документа могут служить основой для рецензирования других документов с моделями данных YANG. Заданы рекомендации и процедуры, предназначенные для улучшения совместимости и применимости реализация протокола конфигурации сети (Network Configuration Protocol или NETCONF), использующих модули моделей данных YANG.

Статус документа

Документ не относится к категории Internet Standards Track и публикуется лишь для информации.

Документ не содержит стандарта Internet и публикуется с информациоными целями.

Документ является результатом работы IETF1 и представляет согласованный взгляд сообщества IETF. Документ прошёл открытое обсуждение и был одобрен для публикации IESG2. Не все документы, одобренные IESG претендуют на статус Internet Standard. Дополнительную информацию о стандартах Internet можно найти в разделе 2 в RFC 5741.

Информация о текущем статусе документа, найденных ошибках и способах обратной связи доступна по ссылке http://www.rfc-editor.org/info/rfc6087.

Авторские права

Copyright (c) 2011. Авторские права принадлежат IETF Trust и лицам, указанным в качестве авторов документа. Все права защищены.

К документу применимы права и ограничения, указанные в BCP 78 и IETF Trust Legal Provisions и относящиеся к документам IETF (http://trustee.ietf.org/license-info), на момент публикации данного документа. Прочтите упомянутые документы внимательно. Фрагменты программного кода, включённые в этот документ, распространяются в соответствии с упрощённой лицензией BSD, как указано в параграфе 4.e документа IETF Trust Legal Provisions, без каких-либо гарантий (как указано в Simplified BSD License).

1. Введение

Стандартизация интерфейсов настройки сети для использования с протоколом NETCONF [RFC4741] требует модульного набора моделей данных, которые можно применять неоднократно и расширять с течением времени.

Этот документ задаёт набор рекомендаций для документов Standards Track с моделями данных YANG [RFC6020]. Язык YANG служит для определения структур данных, протокольных операций и содержимого уведомлений, используемых на серверах NETCONF. Сервер, поддерживающий конкретный модуль YANG, позволяет клиентам NETCONF запрашивать операции, как указано конкретным содержимым модуля YANG.

Этот документ по назначению и структуре похож на рекомендации по использованию Structure of Management Information version 2 (SMIv2) [RFC4181]. Однако упомянутый документ бы написан через 10 лет после начала использования модулей SMIv2 и опубликован в серии обмена опытом (Best Current Practice или BCP). Данный документ не является BCP и служит, скорее, информационным справочником, предназначенным для обеспечения согласованности документов, содержащих модули YANG.

Многие конструкции YANG, такие как оператор описания (description) определены как необязательные. Однако для обеспечения совместимости реализаций NETCONF, использующих модели данных YANG, желательно задать директивы, которые могут требовать более высокого уровня соответствия, нежели минимальный уровень, заданный спецификацией YANG.

Кроме того, YANG допускает такие конструкции, как идентификаторы, строки и обязательные узлы верхнего уровня бесконечного размера, которые реализация сервера не обязана поддерживать. В модулях IETF YANG следует применять лишь такие конструкции, которые поддерживают все серверы.

Этот документ задаёт рекомендации по использованию, относящиеся к операционному уровню и уровню содержимого NETCONF, как указано в [RFC4741]. Рекомендации предназначены для разработчиков и рецензентов с целью повышения удобочитаемости и функциональной совместимости публикуемых моделей данных YANG.

2. Терминология

2.1. Уровни требований

Ключевые слова необходимо (MUST), недопустимо (MUST NOT), требуется (REQUIRED), нужно (SHALL), не следует (SHALL NOT), следует (SHOULD), не нужно (SHOULD NOT), рекомендуется (RECOMMENDED), не рекомендуется (NOT RECOMMENDED), возможно (MAY), необязательно (OPTIONAL) в данном документе интерпретируются в соответствии с [RFC2119].

Соглашения RFC 2119 здесь служат для представления взглядов рабочей группы NETMOD в части содержимого модулей YANG. Модули YANG, соответствующие этому документу будут трактовать соглашения RFC 2119 как описанные в документах BCP.

2.2. Термины NETCONF

Ниже указаны термины, определённые в [RFC4741] и не пререопределяемые здесь.

  • capabilities – возможности;
  • client – клиент;
  • operation – операция;
  • server – сервер.

2.3. Термины YANG

Ниже указаны термины, определённые в [RFC6020] и не пререопределяемые здесь.

  • data node – узел данных;
  • module – модуль;
  • namespace – пространство имён;
  • submodule – субмодуль;
  • version – версия;
  • YANG;
  • YIN.

Отметим, что термин «модуль» может применяться к модулям и субмодулям YANG. При описании субмодулей применяется термин «субмодуль».

2.4. Термины

Ниже определены два используемых в документе термина.

published – опубликованный

Стабильный выпуск модуля или субмодуля, оычно содержащийся в RFC.

unpublished – неопубликованный

Нестабильный выпуск модуля или субмодуля, оычно содержащийся в Internet-Draft.

3. Общие рекомендации

Рецензируемые модули данных вероятно будут содержаться в Internet-Draft. Должны выполняться все рекомендации для авторов Internet-Draft. RFC Editor представляет рекомендации для авторов RFC, которые впервые публикуются как Internet-Draft. Следует соблюдать рекомендации, опубликованные в [RFC2223] и обновлённые в [RFC5741] и RFC Document Style [RFC-STYLE].

Ниже указаны разделы, которые должны присутствовать в Internet-Draft с модулем

  • Описательные разделы.
  • Раздел определений.
  • Раздел Security Considerations.
  • Раздел IANA Considerations.
  • Раздел ссылок.

3.1. Авторские права на модуль

Оператор описания модуля должен включать ссылку на последнее заявление авторских прав IETF Trust Copyright, которое доступно по ссылке http://trustee.ietf.org/license-info/

Каждый модуль или субмодуль YANG, содержащийся в Internet-Draft или RFC считается кодом. Для идентификации кода должны использоваться строки <CODE BEGINS> и <CODE ENDS>.

После тега <CODE BEGINS> следует помещать строку с именем модуля, описанную в параграфе 5.2 [RFC6020]. Ниже приведён пример для выпуска 2010-01-18 модуля ietf-foo.

   <CODE BEGINS> file "ietf-foo@2010-01-18.yang"
   module ietf-foo {
       // ...
      revision 2010-01-18 {
         description "Последний выпуск";
         reference "RFC XXXX";
      }
      // ...
   }
   <CODE ENDS>

3.2. Описательные разделы

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

Если определяемые спецификацией модули импортируют определения из других модулей (за исключением определённых в YANG [RFC6020] и YANG Types [RFC6021]) или всегда реализуется в сочетании с другими модулями, этот факт должен быть указан в обзорном разделе и должны быть отмечены любые специальные интерпретации определений из других модулей.

3.3. Раздел определений

Этот раздел содержит модули, заданные спецификацией. Эти модули должны использовать синтаксис YANG, определённый в [RFC6020]. В документ может также включаться версия YIN. Возможно включение в документ других типов модулей, таких как SMIv2, к которым эти рекомендации не применяются.

Рекомендации по использованию YANG приведены в разделе 4. Рекомендации по использованию YANG.

3.4. Раздел Security Considerations

Каждая спецификация, определяющая модуль или модули, должна включать раздел посвящённый соображениям безопасности, применимым к этим модулям. Этот раздел должен соответствовать последнему утвержденному шаблону (http://www.ops.ietf.org/netconf/yang-security-considerations.txt). В параграфе 6.1 приведён шаблон раздела от 16 июня 2010 г. Авторы должны проверить его соответствие приведённой выше ссылке.

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

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

  • Операции (YANG rpc), которые могут негативно влиять на поведение системы или нарушать приватность, , должны быть явно указаны по именам и должны быть отмечены причины возможных проблем.

3.5. Раздел IANA Considerations

В соответствии с правилами IESG (http://www.ietf.org/id-info/checklist.html) каждый документ Internet-Draft, представленный IESG для публикации, должен включать раздел IANA Considerations. Требования к разделу зависят от действий, которые нужно выполнить IANA. Если действий IANA не требуется, раздел IANA Considerations, заявляющий об этом, RFC Editor удаляет перед публикацией. Более подробные сведения приведены в [RFC5226].

3.5.1. Документы, создающие новые пространства имен

Если Internet-Draft задаёт новое пространство имён, администрируемое IANA, документ должен включать раздел IANA Considerations, указывающий, как администрируется пространство имён. В частности, если значение оператора namespace в модуле YANG ещё не зарегистрировано в IANA, должна запрашиваться новая запись в реестре YANG Namespace. В спецификации YANG [RFC6020] указана процедура для этого.

3.5.2. Документы, расширяющие пространства имен

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

3.6. Разделы ссылок

Для каждого оператора import или include в модуле, указывающего модуль из отдельного документа, должна быть включена соответствующая ссылка в разделе Normative References. Эта ссылка должна соответствовать версии модуля, фактически использованной в спецификации.

Для каждого нормативного оператора reference в модуле, указывающего модуль из отдельного документа, следует включать ссылку на соответствующий документ в раздел Normative References. Этой ссылке следует указывать документ с фактически используемой версией модуля. Если оператор reference указывает ненормативную ссылку на другой документ, этот документ можно включить в раздел Informative References.

4. Рекомендации по использованию YANG

В общем случае модули из спецификаций IETF Standards Track должны соответствовать всем синтаксическим и сементическим требованиям YANG [RFC6020]. Рекомендации этого раздела дополняют спецификацию YANG, задающую минимальный набор требований по соответствию.

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

4.1. Соглашения по именованию модулей

Модули в документах Standards Track следует именовать в соответствии с разделом IANA Considerations в [RFC6020].

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

Имена всех публикуемых модулей должны быть уникальными. Для модулей YANG, публикуемых в RFC, такую уникальность гарантирует IANA. Для неопубликованных модулей авторы должны проверить другие незавершенные работы на предмет совпадения имен.

После публикации имени модуля недопустимо использовать его ещё раз, даже при переводе RFC с этим модулем в статус Historic.

4.2. Идентификаторы

Все идентификаторы в опубликованных модулях YANG должны иметь размер от 1 до 64 символов. Это включает конструкции, заданные как identifier-arg-str в ABNF (раздел 12 в [RFC6020]).

4.3. Значения по умолчанию

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

 

Оператор

Значение по умолчанию

config

true

mandatory

false

max-elements

unbounded

min-elements

0

ordered-by

system

status

current

yin-element

false

 

4.4. Операторы условий

Модуль можно концептуально разделить на части, используя операторы if-feature и/или when.

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

Если определение данный не является обязательным и зависит от поддержки сервером возможностей протокола NETCONF, следует использовать оператор YANG feature для указания поддержки функции SHOULD в модели данных.

Если какие-либо данные уведомления или определение данных для не относящегося к конфигурации узла не являются обязательными, сервер может (но не обязан) возвращать экземпляр этого узла данных. Если имеются какие-либо условные требования для возврата узла данных в уведомлении или ответе на поисковый запрос, они должны быть указаны в документации. Например, к узлу данных может применяться оператор when или if-feature или условия могут быть разъяснены в операторе description внутри узла данных или одном из его предков (при наличии таковых).

4.5. Использование XPath

В этом параграфе даны рекомендации по использованию языка путей XML (XML Path Language или XPath) [W3C.REC-xpath-19991116] в модулях YANG.

Оси attribute и namespace не поддерживаются в YANG и могут быть пустыми в реализации сервер NETCONF. Функции position и last применять не следует. Это относится и к неявному использования функции position (например, //chapter[42]). От сервера требуется поддержка лишь относительного порядка документов XML всех экземпляров из конкретного, упорядоченного пользователем list или leaf-list. Функции position и last можно применять, если они оцениваются в контексте, где узел контекста является упорядоченным пользователем list или leaf-list.

Оси preceding и following применять не следует. Эти конструкции основаны на порядке документов XML в базе данных конфигурации сервера NETCONF, который не может поддерживаться согласованно и давать надёжные результате в разных реализациях. Взамен следует использовать выражения предикатов, основанные на статических свойствах узла (например, имя элемента или значение осей ancestor или descendant). Оси preceding и following можно применять, если порядок документов не связан с результатом выражения (например, проверка глобальной уникальности значения параметра).

Оси preceding-sibling и following-sibling не следует использовать. От сервера требуется лишь поддержка относительного порядка документов всех экземпляров из конкретного, упорядоченного пользователем list или leaf-list. Оси preceding-sibling и following-sibling можно применять, если они оцениваются в контексте, где узел контекста является упорядоченным пользователем list или leaf-list.

Узлы данных, использующие встроенные типы int64 и uint64, не следует применять в численных выражениях. Имеются граничные условия, при которых преобразование 64-битовогог типа YANG в число XPath может давать некорректный результат. В частности, число XPath с двойной точностью и плавающей точкой, не может представлять очень большие или отрицательные 64-битовые значения и ограничено лишь 53 битами. Типы int64 и uint64 можно применять в численных выражениях, если для представления значение не требуется более 53 битов.

Специалисты по моделированию данных должны быть осторожны, чтобы не спутать пространства значений YANG и XPath. Типы данных не одинаковы в этих случаях и преобразования между YANG и XPath следует выполнять с осторожностью.

Можно использовать явные преобразования типа данных XPath (например, функции string, boolean, number) вместо неявных.

4.6. Управление жизненным циклом

Оператор status должен присутствовать, если он имеет значение deprecated или obsolete.

Модуль или субмодуль недопустимо изменять после публикации содержащего его документа. Значение URI пространства имён модуля недопустимо изменять после публикации содержащего модуль документа.

Субоператор revision-date в операторе imports следует включать при использовании любой группировки из внешнего модуля. Субоператор revision-date в операторе include следует включать при использовании любой группировки из внешнего модуля.

При использовании субмодулей в содержащем их основном модуле должна обновляться дата выпуска в соответствии с датой выпуска изменённого (напрямую или опосредованно) субмодуля, включённого в него.

4.7. Заголовок модуля, операторы Meta и Revision

Для опубликованных модулей пространство имён должно быть указано глобально уникальным URI, как указано в [RFC3986]. Эти значения обычно выделяются IANA.

Должен присутствовать оператор organization, а для модулей Standards Track в этом операторе следует указывать рабочую группу IETF, уполномоченную на создание документа.

Должен присутствовать оператор contact, а для модулей Standards Track в этом операторе должна быть указана web-страница рабочей группы и следует также указывать контактные данные основного автора или редактора документа. Если имеется несколько авторов, можно включить их контактные данные. Дополнительно можно указать Area Director и другие сведения о контактах.

Должен присутствовать оператор, а также должен включаться подходящий текст IETF Trust Copyright, как указано в параграфе 3.1. Авторские права на модуль.

Если модуль зависит от сведений из других документов, отличающихся от подразумеваемых операторами import в модуле, эти документы должны быть указаны в операторе reference.

Оператор revision должен присутствовать для каждой опубликованной версии модуля и каждый такой оператор должен включать субоператор reference, указывающий опубликованный документ, где содержится модуль. Модули часто извлекаются из более обширных документов, а разработчикам и операторам полезно знать, как найти исходный документ. В операторы revision можно включать субоператор description. Каждый новый выпуск модуля должен включать дату выпуска, которая позже даты предшествующего выпуска. Дату выпуска не требуется обновлять, если в новой редакции документа содержимое модуля не меняется.

Допускается неоднократно использовать один и тот же оператор revision в разных выпусках неопубликованного модуля (Internet-Draft), но дата выпуска должна обновляться при каждой «публикации» документа Internet-Draft.

4.8. Назначение пространств имён

Рекомендуется включать в документы лишь действительные модули YANG, независимо от публикации. Это позволит:

  • корректно компилировать модули, не получая сообщений о критических ошибках;

  • применять модули в ранних реализациях, не выбирая случайных значений для пространства имён XML;

  • заранее проверить совместимость, поскольку независимые реализации будут использовать одно пространство имён XML.

Пока IANA не назначит URI, в операторе namespace внутри модуля YANG должно указываться предложенное значение URI пространства имён. Значение следует выбирать так, чтобы не возникало конфликтов с другими пространствами имён YANG. Недопустимо применять для этого стандартные имена модулей, префиксы и строки URI, уже включённые в реестр YANG Module Names.

Стандартному оператору namespace следует иметь форму

   <URN prefix string>:<module-name>

Для опубликованных и неопубликованных модулей YANG следует применять строку префикса URN вида

   urn:ietf:params:xml:ns:yang:

Ниже даны примеры действительных URN для временных операторов namespace в модулях Standards Track.

      urn:ietf:params:xml:ns:yang:ietf-netconf-partial-lock
      urn:ietf:params:xml:ns:yang:ietf-netconf-state
      urn:ietf:params:xml:ns:yang:ietf-netconf

Отметим, что для модулей, не относящихся к Standards Track следует применять иную строку префикса URN, которую следует выбирать в соответствии с рекомендациями [RFC6020]. Ниже приведены примеры для модулей, на являющихся Standards Track. Этот документ не содержит рекомендаций для этого типа URN.

      http://example.com/ns/example-interfaces
      http://example.com/ns/example-system

4.9. Определения данных верхнего уровня

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

В именах и организации данных следует отражать неизменную информацию, такую как имя протокола. Имена рабочих групп применять не следует, поскольку они могут меняться.

Обязательное определение данных базы задаётся как узел, который клиент должен предоставить, чтобы база данных была действительной. От сервера не требуется предоставлять это значение.

Определениям данных базы на верхнем уровне недопустимо быть обязательными. Если обязательный узел задать на верхнем уровне, это сразу сделает базу данных недействительной. Это может произойти при загрузке сервера или динамической загрузке модуля в процессе работы.

4.10. Типы данных

Выбор подходящего типа данных (встроенного, имеющегося или нового производного типа) является очень субъективным, поэтому для него не задаётся жёстких требований.

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

Если нужна расширяемость набора перечисляемых значений, следует применять тип identityref вместо enumeration или встроенного типа.

Для строк данных при возможности задать машиночитаемый шаблон с подходящей семантикой, следует применять один или несколько операторов pattern. Если размер строки требуется ограничить для всех реализаций, должен использоваться оператор length.

Для численных типов следует применять оператор range, если предполагаемая семантика отличается от разрешённой неограниченным внутренним типом данных (например, int32). Численные типы со знаком (int8, int16, int32, int64) не следует применять, если желаемая семантика не включает отрицательных значений.

Для типов enumeration и bits следует документировать семантику каждого enum и bit и в таких случаях следует применять каждый раз свой оператор description (внутри enum или bit).

4.11. Определения типов многократного использования

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

Если с желаемой семантикой можно связать подходящий идентификатор единицы измерения, следует применять оператор units.

Если с желаемой семантикой можно связать подходящее значение по умолчанию, следует включать оператор default.

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

Должен присутствовать оператор description.

Если семантика определения типа задана в другом документе (отличном от указанного в операторе import модуля YANG), должен присутствовать оператор reference.

4.12. Определения данных

Оператор description должен присутствовать в операторах YANG:

  • anyxml;
  • augment;
  • choice;
  • container;
  • extension;
  • feature;
  • grouping;
  • identity;
  • leaf;
  • leaf-list;
  • list;
  • notification;
  • rpc;
  • typedef.

Если семантика определения данных задана в другом документе (отличном от указанного в операторе import модуля YANG), должен присутствовать оператор reference.

Конструкция anyxml может быть полезна для представления заголовков (banner) HTML с элементами разметки, такими как <b> и </b>, и может применяться в таких случаях. Однако её не следует использовать, если для желаемого синтаксиса и семантики подходит иной тип данных YANG.

Если с желаемой семантикой, которая может быть представлена с XPath, связаны ограничения целостности ссылок, следует включать 1 или несколько операторов must.

Для определений данных list и leaf-list следует применять оператор max-elements, если нужно ограничить число возможных экземпляров во всех реализациях.

Если в определении данных имеются операторы must или when, в оператор description этого определения следует помещать описание назначения.

4.13. Определения операций

Если семантика операции задана в другом документе (отличном от указанного в операторе import модуля YANG), должен присутствовать оператор reference.

Если операция влияет на поведение системы, это следует отметить в операторе description.

Если операция может быть опасной для поведения системы, это должно быть отмечено в разделе документа Security Considerations.

4.14. Определения уведомлений

Должен присутствовать оператор description.

Если семантика уведомления задана в другом документе (отличном от указанного в операторе import модуля YANG), должен присутствовать оператор reference.

5. Взаимодействие с IANA

Этот документ регистрирует URI in the IETF XML в реестре [RFC3688].

   URI: urn:ietf:params:xml:ns:yang:ietf-template
   Registrant Contact: The NETMOD WG of the IETF.
   XML: N/A, запрошенный URI является пространством имён XML.

В соответствии с этим документом в реестр YANG Module Names внесён шаблон модуля YANG из Приложения B.

 

Поле

Значение

Name

ietf-template

Namespace

urn:ietf:params:xml:ns:yang:ietf-template

Prefix

temp

Reference

RFC6087

 

6. Вопросы безопасности

Этот документ содержит рекомендации по документированию содержимого NETCONF, определённого на языке моделирования данных YANG. Рекомендации по написанию разделов Security Considerations для модулей YANG приведены в документе http://www.ops.ietf.org/netconf/yang-security-considerations.txt

Этот документ не вносит новых и не меняет существующих рисков для систем управления.

В следующем параграфе представлен шаблон для раздела Security Considerations от 16 июня 2010 г. Следует пользоваться приведённой выше ссылкой, чтобы проверить наличие новой версии шаблона.

Каждая спецификация, задающая 1 или несколько модулей YANG, должна включать раздел с обсуждением вопросов безопасности, связанных с этими модулями. Этот раздел должен следовать последнему опубликованному шаблону (http://www.ops.ietf.org/netconf/yang-security-considerations.txt).

В частности, доступные для записи узлы данных, которые могут быть особо разрушительными при злоупотреблении, должны быть явно указаны по именам, а связанные с ними риски безопасности должны быть разъяснены.

Доступные для чтения узлы с конфиденциальными или приватными сведениями должны быть явно указаны по именам, а связанные с ними риски утечек и уязвимостей должны быть разъяснены.

При определении новых операций RPC должны быть рассмотрены вопросы безопасности для каждой новой операции RPC.

6.1. Шаблон раздела Security Considerations

X. Security Considerations

Модуль YANG, заданный в этом документе, предназначен для доступа по протоколу NETCONF [RFC4741]. Нижним уровнем NETCONF является защищённый транспорт с обязательной реализацией SSH [RFC4742].

Если имеются открытые для записи узлы данных (config true, как принято по умолчанию), нужно описать их конкретную чувствительность или уязвимости.

В этом модуле YANG имеется множество узлов данных, доступных для записи, создания, удаления (т. е. с принятым по умолчанию config true). Эти узлы могут быть чувствительными или уязвимыми в некоторых сетевых средах. Операции записи (например, edit-config) в такие узлы без подобающей защиты могут оказывать негативное влияние на работу сети. Ниже указаны ветви и узлы данных и их уязвимости.

    <список ветвей и узлов данных с указанием причин их чувствительности>

Для всех модулей YANG требуется оценить, являются ли доступные лишь для чтения узлы (config false и другие узлы, поскольку они могут быть считаны такими операциями, как get или get-config) чувствительными или уязвимыми (например, могут раскрывать сведения о клиенте или нарушать законы о персональных данных).

Некоторые из доступных для чтения узлов этого модуля YANG могут быть конфиденциальными или уязвимыми в некоторых сетевых средах. Важно контролировать доступ к считыванию таких узлов данных (например, через операции get, get-config, notification). Ниже указаны ветви и узлы данных конфиденциальные или уязвимые в плане их чтения.

    <список ветвей и узлов данных с указанием причин их чувствительности>

Если модуль YANG определяет операции RPC, должна быть описана их чувствительность или уязвимости.

Некоторые из операций RPC с этом модуле YANG могут быть конфиденциальными или уязвимыми в некоторых сетевых средах. Важно контролировать доступ к таким операциям. Ниже указаны такие операции и их уязвимости.

    <список операций RPC с указанием причин их чувствительности>

7. Благодарности

Структура и содержимое этого документа основаны на Guidelines for MIB Documents [RFC4181] от C. M. Heard.

Рабочая группа благодарит Martin Bjorklund и Juergen Schoenwaelder за обстоятельные рецензии и вклад в документ.

8. Литература

8.1. Нормативные документы

[RFC2119] Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels”, BCP 14, RFC 2119, March 1997.

[RFC2223] Postel, J. and J. Reynolds, “Instructions to RFC Authors”, RFC 2223, October 1997.

[RFC3688] Mealling, M., “The IETF XML Registry”, BCP 81, RFC 3688, January 2004.

[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax”, STD 66, RFC 3986, January 2005.

[RFC4741] Enns, R., “NETCONF Configuration Protocol”, RFC 4741, December 2006.

[RFC5378] Bradner, S. and J. Contreras, “Rights Contributors Provide to the IETF Trust”, BCP 78, RFC 5378, November 2008.

[RFC5741] Daigle, L., Kolkman, O., and IAB, “RFC Streams, Headers, and Boilerplates”, RFC 5741, December 2009.

[W3C.REC-xpath-19991116] DeRose, S. and J. Clark, “XML Path Language (XPath) Version 1.0”, World Wide Web Consortium Recommendation REC-xpath-19991116, November 1999, <http://www.w3.org/TR/1999/REC-xpath-19991116>.

[RFC6020] Bjorklund, M., “YANG – A Data Modeling Language for the Network Configuration Protocol (NETCONF)”, RFC 6020, October 2010.

[RFC6021] Schoenwaelder, J., “Common YANG Data Types”, RFC 6021, October 2010.

8.2. Дополнительная литература

[RFC4181] Heard, C., “Guidelines for Authors and Reviewers of MIB Documents”, BCP 111, RFC 4181, September 2005.

[RFC5226] Narten, T. and H. Alvestrand, “Guidelines for Writing an IANA Considerations Section in RFCs”, BCP 26, RFC 5226, May 2008.

[RFC-STYLE] Braden, R., Ginoza, S., and A. Hagens, “RFC Document Style”, September 2009, <http://www.rfc-editor.org/rfc-style-guide/rfc-style>.

Приложение A. Контрольный список рецензирования модуля

Этот раздел заимствован из RFC 4181.

Цель рецензирования модуля YANG состоит в проверке технической корректности и соответствия требованиям IETF к документации. Ниже приведён контрольный список, которых может быть полезен при рецензировании Internet-Draft.

  1. Шаблон I-D. Проверяется использование требуемого шаблона Internet-Draft (http://www.ietf.org/id-info/guidelines.html), включая соответствующее заявление с разрешением публикации как RFC и отсутствие в шаблоне I-D ссылок и номеров разделов.

  2. Аннотация. Проверяется отсутствие ссылок и номера раздела, а также соответствие содержимого рекомендациям http://www.ietf.org/id-info/guidelines.html.

  3. Авторские права. Проверяется наличие подходящего текста относительно авторских прав, которые участники предоставляют IETF Trust [RFC5378]. Проверка наличия полного уведомления об авторских паравах IETF Trust в начале документа. IETF Trust Legal Provisions (TLP) можно найти по ссылке http://trustee.ietf.org/license-info/.

  4. Раздел Security Considerations. Проверяется использование последнего утверждённого шаблона из области OPS (http://www.ops.ietf.org/netconf/yang-security-considerations.txt) и следование этому шаблону.

  5. Раздел IANA Considerations должен присутствовать всегда. Для каждого модуля в документе раздел IANA Considerations должен указывать приведённые ниже реестры IANA.

    XML Namespace Registry – регистрация пространства имён модуля YANG.

    YANG Module Registry – регистрация имени модуля YANG, префикса, пространства имён и номера RFC в соответствии с правилами [RFC6020].

  6. Ссылки. Проверяется корректность деления на нормативные документы и дополнительную литературу, наличие RFC 2119 в числе нормативных документов, если применяется соответствующая терминология, наличие все требуемых шаблоном ссылок, указание в нормативных документах всех импортируемых модулей YANG, ссылки на последние RFC, если нет конкретных причин указывать предшествующие версии (например, включение в дополнительную литературу ссылку на предыдущую спецификацию для разъяснения функций совместимости с прежними версиями). Проверяется наличие в тексте документа (вне модуля YANG) ссылок на все импортируемые модули.

  7. Лицензия. Проверяется указание Simplified BSD License в каждом модуле и субмодуле. Некоторые рекомендации по этой части даны в параграфе 3.1. Проверяется корректность указания года во всех упоминаниях авторских прав. Используется утвержденный текст из документа (Trust Legal Provisions или TLP), доступного по ссылке http://trustee.ietf.org/license-info/

  8. Другие вопросы. Проверяется наличие проблем, указанных в http://www.ietf.org/id-info/checklist.html, которые не рассмотрены.

  9. Техническое содержимое. Просматривается фактическое техническое содержимое на предмет соответствия рекомендациям этого документа. Для проверки синтаксических ошибок рекомендуется применять компилятор YANG. Список свободно распространяемых инструментов доступен по ссылке http://trac.tools.ietf.org/wg/netconf/trac/wiki

    Checking for correct syntax, however, is only part of the job. It is just as important to actually read the YANG module document from the point of view of a potential implementor. It is particularly important to check that description statements are sufficiently clear and unambiguous to allow interoperable implementations to be created.

Приложение B. Шаблон модуля YANG

<CODE BEGINS> file "ietf-template@2010-05-18.yang"

module ietf-template {

    // Указывается уникальное значение URN пространства имён 
    namespace
      "urn:ietf:params:xml:ns:yang:ietf-template";

    // Указывается уникальный префикс
    prefix "temp";


    // Операторы import, например
    // import ietf-yang-types { prefix yang; }
    // import ietf-inet-types { prefix inet; }

    // Указывается рабочая группа IETF (если применимо)
    organization
       "IETF NETMOD (NETCONF Data Modeling Language) Working Group";

    // Указываются сведения об авторах
    contact
       "WG Web:   <http://tools.ietf.org/wg/your-wg-name/>
        WG List:  <mailto:your-wg-name@ietf.org>

        WG Chair: your-WG-chair
                  <mailto:your-WG-chair@example.com>

        Editor:   your-name
                  <mailto:your-email@example.com>";


    // В первом абзаце даётся кратное описание модуля.
    // Указываются авторские права для последней версии,
    // если она обновилась с момента публикации документа.
    description
     "Этот модуль задаёт шаблон для других модулей YANG.

      Авторские права (Copyright (c) ГОД) принадлежат IETF Trust
      и лицам, указанным в качестве авторов кода. Все права защищены.

      Распространение и использование в исходной или двоичной форме с
      изменениями или без таковых разрешено в соответствии с лицензией
      Simplified BSD, изложенной в разделе 4  IETF Trust's Legal
      Provisions применительно к документам IETF
      (http://trustee.ietf.org/license-info). 
 
      Эта версия данного модуля YANG является частью RFC XXXX, где
      правовые вопросы рассмотрены более полно.";

    // RFC Ed.: Заменить XXXX фактическим номером RFC и удалить примечание

    reference "RFC XXXX";

    // RFC Ed.: Удалить это примечание
    // Примечание: Извлечено из RFC 6087


    // Заменить 2010-05-18 датой публикации модуля в формате
    // (год-месяц-число)
    revision "2010-05-18" {
      description
        "исходный выпуск";
    }

    // Операторы extension

    // Операторы feature

    // Операторы identity

    // Операторы typedef

    // Операторы grouping

    // Операторы определения данных

    // Операторы augment

    // Операторы rpc

    // Операторы notification

    // НЕ ВКЛЮЧАЙТЕ операторы deviation в опубликованные модули

}
<CODE ENDS>

Адрес автора

Andy Bierman
Brocade
EMail: andy.bierman@brocade.com

Перевод на русский язык

Николай Малых

nmalykh@protokols.ru

1Internet Engineering Task Force – комиссия по решению инженерных задач Internet.

2Internet Engineering Steering Group – комиссия по инженерным разработкам Internet.

Запись опубликована в рубрике RFC. Добавьте в закладки постоянную ссылку.

Добавить комментарий