Commit 6f2b5a1b authored by Elemer Lelik's avatar Elemer Lelik
Browse files

asciidoc added

parent c32e5db3
---
Author: Endre Kulcsár
Version: 155 17-CNL 113 429, Rev. D
Date: 2011-11-29
---
= DNS Protocol Modules for TTCN-3 Toolset with TITAN, Function Specification
:author: Endre Kulcsár
:revnumber: 155 17-CNL 113 429, Rev. D
:revdate: 2011-11-29
:toc:
== How to Read This Document
This is the Function Specification for the set of DNS protocol modules. DNS protocol modules are developed for the TTCN-3 Toolset with TITAN.
== Scope
The purpose of this document is to specify the content of the DNS Test Port and the additional modules containing TTCN-3 type definitions.
= General
The Test Port and the included protocol modules implement message structures of the related protocol in a formalized way, using the standard specification language TTCN-3. Thus allowing definition of test data (using templates) in TTCN-3 core-language format <<_4, [4]>>. The Test Port assures encoding/decoding of messages during test suite execution using the TITAN TTCN-3 test environment.
The DNS protocol modules use external encoding and decoding functions.
The DNS PDU in TTCN-3 is represented in an uncompressed format.
= Functional Specification
== Protocol Versions Implemented
This Protocol Module implements protocol messages and constants of the DNS protocol as decribed in <<_1, [1]>>, <<_2, [2]>>, <<_3, [3]>>, <<_6, [6]>>, <<_7, [7]>> with the modifications specified in <<modifications-deviations-related-to-the-protocol-specification, Modifications/Deviations Related to the Protocol Specification>> Also, valid NAPTR queries and responses needed by the ENUM protocol (specified in <<_5, [5]>>) can be sent and received via the Test Port.
[[modifications-deviations-related-to-the-protocol-specification]]
== Modifications/Deviations Related to the Protocol Specification
=== Unimplemented Messages, Message Fields and Constants
Only the message fields related to Internet and IP are implemented. DNS resource records with class `CS` (CSNET), `CH` (CHAOS) and `HS` (Hesoid) are not supported but will be decoded into a TTCN-3 octetstring.
[[protocol-modifications-deviations]]
=== Protocol Modifications/Deviations
None.
[[encoding-decoding-and-other-related-functions]]
== Encoding/Decoding and Other Related Functions
This product also contains encoding/decoding functions, which assure correct encoding and compression of messages when sent from TITAN, and correct decoding and decompression of messages when received by TITAN. Implemented encoding/decoding functions:
[cols=",,",options="header",]
|=====================================================
|Name |Type of formal parameters |Type of return value
|`enc_PDU_DNS` |PDU_DNS, boolean, boolean |octetstring
|`dec_PDU_DNS` |octetstring |PDU_DNS
|=====================================================
The decoder function can handle both compressed and uncompressed format and the PDU will be visible in uncompressed format in TTCN-3.
The encoder function can be instructed by a boolean parameter to perform compression and by a second boolean parameter to automatically calculate length fields.
= Terminology
No specific terminology is used.
= Abbreviations
ASP:: Abstract Service Primitive
DNS:: Domain Name System
IP:: Internet Protocol
PDU:: Protocol Data Unit
TTCN-3:: Testing and Test Control Notation version 3
= References
[[_1]]
[1] http://www.ietf.org/rfc/rfc1035.txt?number=1035[RFC 1035] +
Domain names – Implementation and specification
[[_2]]
[2] http://www.ietf.org/rfc/rfc2782.txt?number=2782[RFC 2782] +
A DNS RR for specifying the location of services (DNS SRV)
[[_3]]
[3] http://www.ietf.org/rfc/rfc3403.txt?number=3403[RFC 3403] +
Dynamic Delegation Discovery System (DDDS), Part Three: The Domain Name System (DNS) Database
[[_4]]
[4] ETSI ES 201 873-1 v3.1.1 (2005-06) +
The Testing and Test Control Notation version 3; Part 1: Core Language
[[_5]]
[5] http://www.ietf.org/rfc/rfc3761.txt?number=3761[RFC 3761] +
The E.164 to Uniform Resource Identifiers (URI) Dynamic Delegation Discovery System (DDDS) Application (ENUM)
[[_6]]
[6] http://www.ietf.org/rfc/rfc2136.txt?number=2136[RFC 2136] +
Dynamic Updates in the Domain Name System (DNS UPDATE)
[[_7]]
[7] http://www.ietf.org/rfc/rfc1886.txt?number=1886[RFC 1886] +
DNS Extensions to support IP version 6
---
Author: Endre Kulcsár
Version: 198 17-CNL 113 429, Rev. E
Date: 2011-11-29
---
= DNS Protocol Modules for TTCN-3 Toolset with TITAN, Function Specification
:author: Endre Kulcsár
:revnumber: 198 17-CNL 113 429, Rev. E
:revdate: 2011-11-29
:toc:
== About This Document
=== How to Read This Document
This is the User Guide for the set of DNS protocol modules. DNS protocol modules are developed for the TTCN-3 Toolset with TITAN. This document should be read together with Function Specification <<_3, [3]>>.
=== Presumed Knowledge
To use this protocol module the knowledge of the TTCN-3 core-language <<_1, [1]>> and the DNS protocol described in RFC 1035 <<_4, [4]>> is essential.
== System Requirements
The set of DNS protocol modules are a set of source code files that can only be used as part of a TTCN-3 test suite. Hence, protocol modules alone do not put specific requirements on the system used. However in order to compile and execute a TTCN-3 test suite using a set of protocol modules the following system requirements must be satisfied:
* TITAN TTCN-3 Test Executor R7A (1.7.pl0) or higher installed. For installation guide see <<_2, [2]>>.
NOTE: This version of the protocol module is not compatible with TITAN releases earlier than R7A.
= Protocol Modules
== Overview
Protocol modules implement the message structure of the related protocol in a formalized way, using the standard specification language TTCN-3. This allows definition of test data (templates) in TTCN-3 core-language <<_1, [1]>> and correct encoding/decoding of messages during execution of test suites using the TITAN TTCN-3 test environment.
The DNS protocol module implements the following functions:
[source]
----
dec_PDU_DNS(in octetstring stream) return PDU_DNS;
enc_PDU_DNS(in PDU_DNS msg, in boolean doCompression, in boolean autoLengthCalc) return octetstring;
----
The function `dec_PDU_DNS` decodes an octetstring that represents an encoded DNS message. Unsupported resource records (see Function Specification <<_3, [3]>>) will be decoded into field `unsupported` and erroneous resource records will be decoded into field `undecodable` of rData, both fields are of type octetstring. These fields can also be used to encode erroneous or unsupported data. Decoded DNS messages are in uncompressed format.
The function `enc_PDU_DNS` encodes a DNS message given as TTCN-3 data into an octetstring. The latter function has two additional boolean parameters. Parameter `doCompression` specifies whether the encoder should compress domain names or encode them uncompressed. Parameter `autoLengthCalc` specifies whether the encoder should calculate and substitute length fields in resource records automatically. Calculating length fields manually is not recommended unless it is required to encode a faulty DNS message. Fields `qdCount`, `anCount`, `nsCount` and `arCount` of DNS messages are not automatically calculated
NOTE: If resource records are passed to templates as parameters then `sizeof` can be used to calculate these.
== Installation
The Test Port and the protocol module can be used for the development of TTCN-3 test suites. Since the DNS protocol module is used as part of a TTCN-3 test suite, this requires TTCN-3 Test Executor to be installed before the module can be compiled and executed together with other parts of the test suite. For more details on the installation of TTCN-3 Test Executor see the relevant section of <<_2, [2]>>.
The following steps are needed to use the DNS protocol module:
. Copy the source file (__DNS_EncDec.cc__) and the definition module (__DNS_Types.ttcn__) into the directory of the test suite or create symbolic links to them.
. Import module `DNS_Types` to the module(s) where the DNS protocol module is used.
. Create a _Makefile_ or modify the existing one.
== Configuration
None.
= Error Messages
The following error messages can occur while using the DNS protocol module. The error messages are self-explanatory:
`*Error decoding DNS header. Stream doesn’t contain enough octets.*`
`*Error decoding query resource record: not enough octets.*`
`*Error decoding label at octet #_n_: label length is greater than 63, but is not a pointer (_0xXX_).*`
`*Label pointer at octet #_n_ in domain name refers after end of stream.*`
`*Error decoding label: not enough octets. Remaining bytes: _n_, length of label: _m_*`
`*Error decoding resource record: not enough octets. Resource record starts at octet #_n_, number of octets in message: _m_.*`
`*Error encoding DNS header: field 'z' must have a length of 3.*`
`*Domain name should not start with a dot: "…".*`
`*Domain name should not end with a dot: "…".*`
`*Label in domain name is longer than 63 characters: "…"*`
= Warning Messages
The following warning messages can occur while using the DNS protocol module. The warning messages are self-explanatory:
`*While encoding PDU_DNS: 'header.qdCount' (_n_) differs from size of `queries' (_m_).*`
`*While encoding PDU_DNS: 'header.anCount' (_n_) differs from size of `answers' (_m_).*`
`*While encoding PDU_DNS: 'header.nsCount' (_n_) differs from size of `nameServerRecords' (_m_).*`
`*While encoding PDU_DNS: 'header.arCount' (_n_) differs from size of `additionalRecords' (_m_).*`
`*Forward reference in compressed domain name at octet #_n_.*`
`*While decoding resource record: not enough octets, decoding to field `undecodable'. Resource record starts at octet #_n_.*`
`*Resource record class _n_ is not supported. rData will be decoded to field 'unsupported'.*`
`*While decoding address resource record: not enough octets, decoding to field 'undecodable'.*`
`*While decoding SOA resource record: not enough octets, decoding to field 'undecodable'.*`
`*While decoding WKS resource record: not enough octets, decoding to field 'undecodable'.*`
`*While decoding WKS resource record: rdLength is less than 6. Decoding to field 'undecodable'.*`
`*While decoding HINFO resource record: not enough octets, decoding to field 'undecodable'.*`
`*While decoding MX resource record: not enough octets, decoding to field 'undecodable'.*`
`*While decoding AAAA resource record: not enough octets, decoding to field 'undecodable'.*`
`*While decoding SRV resource record: not enough octets, decoding to field 'undecodable'.*`
`*While decoding NAPTR resource record: not enough octets, decoding to field 'undecodable'.*`
`*Resource record type _n_ is not supported. RData will be decoded to field 'unsupported'.*`
`*While decoding resource record: rdLength (_n_) does not equal the length of decoded resource record data (_m_). Resource record starts at octet #_k_.*`
`*Length of rData (_n_) in octets differs from rdLength (_m_) in resource record: "…"*`
`*While encoding domain name: domain name is empty.*`
`*In case of Resource record class n rdLength and ttl fields must be zero. rData will be decoded to field 'unsupported'.*`
= Examples
The demo directory of the deliverable contains the following examples:
* __DNS_Types.ttcn__ - definition module.
* __DNS_EncDec.cc__ - source file.
* __DNS_Demo.ttcn__ - demo testcases for DNS protocol module.
* __DNS_Mapping.ttcn__ - mapping module.
* _Makefile_
* __UDPasp_PortType.ttcn__ - port type definition for UDP test port (CNL 113 346).
* __UDPasp_Types.ttcn__ - type definitions for UDP test port.
* __UDPasp_PT.cc__ - source file of UDP test port.
* __UDPasp_PT.hh__ - header file of UDP test port.
* _config.cfg_ - example runtime configuration file.
* _readme.txt_ - brief description of how to use the demo.
= Terminology
No specific terminology is used.
= Abbreviations
ASP:: Abstract Service Primitive
DDDS:: Dynamic Delegation Discovery System
DNS:: Domain Name System
DNS RR:: Domain Name System Resource Record
PDU:: Protocol Data Unit
RFC:: Request For Comments
TTCN-3:: Testing and Test Control Notation version 3
= References
[[_1]]
[1] ETSI ES 201 873-1 v3.1.1 (2005-06) +
The Testing and Test Control Notation version 3; Part 1: Core Language
[[_2]]
Programmer’s Technical Reference for TITAN TTCN-3 Test Executor
[[_3]]
[3] DNS Protocol Modules for TTCN-3 Toolset with TITAN, Function Specification
[[_4]]
[4] http://www.ietf.org/rfc/rfc1035.txt?number=1035[RFC 1035] +
Domain names – Implementation and specification
[[_5]]
[5] http://www.ietf.org/rfc/rfc2782.txt?number=2782[RFC 2782] +
A DNS RR for specifying the location of services (DNS SRV)
[[_6]]
[6] http://www.ietf.org/rfc/rfc3403.txt?number=3403[RFC 3403] +
Dynamic Delegation Discovery System (DDDS), Part Three: The Domain Name System (DNS) Database
[[_7]]
[7] http://www.ietf.org/rfc/rfc2136.txt?number=2136[RFC 2136] +
Dynamic Updates in the Domain Name System (DNS UPDATE)
[[_8]]
[8] http://www.ietf.org/rfc/rfc1886.txt?number=1886[RFC 1886] +
DNS Extensions to support IP version 6
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment