SoC/2017: Difference between revisions

From SambaWiki
No edit summary
Line 54: Line 54:
* dimgrav/Samba-GSOC2017: [ link]
* dimgrav/Samba-GSOC2017: [ link]
* dimgrav/samba (fork): [ link]
* dimgrav/samba (fork): [ link]

=== The libcli/dns library ===
=== The libcli/dns library ===

Revision as of 09:48, 28 August 2017

Initial task description

Improve libcli/dns

Samba comes with its own asynchronous DNS parser framework developed for the internal DNS server. Basic calls have been implemented for a client-side library as well, but a more fleshed out implementation would be needed. The goal of this project is to implement more high-level calls handling DNS requests, such as UDP/TCP switchover and client-side GSS-TSIG cryptography. A test suite excercising all the functions is required and can be used to cross-check and complement the existing DNS server tests already shipped by Samba. This testsuite should use cmocka.

  • Difficulty: Medium
  • Language(s): C
  • Mentors: Kai Blin, David Disseldorp
  • Student: Dimitris Gravanis

Project Summary

Project Information

Client-side DNS call handling with GSS-TSIG

Unix SMB/CIFS implementation

Dimitrios Gravanis (C) 2017

Based on the existing work by Samba Team


For the Samba AD DC, libcli/dns is a library that allows the handling of DNS calls (send/receive requests) and uses GSS-TSIG encryption protocol for signed packets, to accommodate encrypted client-server communication.

The project goal was to enhance client-server communication features, by implementing TCP request send/receive handling, in addition to he existing UDP asynchronous request capabilites, and sign client-side packets with GSS-TSIG signatures, to provide security.

It consists of its respective function and structure libraries, that provide definitions for client-side functionality.

For more information on the project goals, read the GSoC proposal here.

The project timeline and development journal is documented in its dedicated blogspot.

  • Individual project "mirror" repository (requires Samba source code for integration - NOT STANDALONE): link
  • Personal samba-team/samba fork with integrated changes in libcli/dns: link
  • Samba GitHub repository: link

  • dimgrav/Samba-GSOC2017: link
  • dimgrav/samba (fork): link

The libcli/dns library

To integrate the functionality described in the project goals, the entire libcli/dns structure had to be reorganized, since the vast majority of the current code in libcli/dns was created during the GSoC project duration, with the old code being integrated or submitted to minor changes, such as renames (for reasons of semantics and integration of the new code) and small additions, mainly to incorporate all the new code into the Samba building scripts.

The project code is currently under review by Samba.

libcli/dns contents

The project generated code and the difference in libcli/dns structure is demonstrated as follows:

Initial libcli/dns structure: (before)

  • dns.c
  • dns.h
  • libdns.h
  • wscript_build

Project libcli/dns structure: (after)

  • cli-fn/
    • client_crypto.c
    • dns_tcp.c
    • dns_udp.c
  • cmocka-tests/
    • test-fn/
      • cli_crypto_test.c
      • dns_tcp_test.c
      • dns_udp_test.c
      • wscript
    • cli_tests.c
    • wscript_build
  • cli_dns.c (replaces dns.c)
  • dns.h
  • libtcp.h
  • libudp.h (renamed from libdns.h)
  • libtsig.h
  • libwrap.h
  • wrap_cli.c
  • wscript_build

The README files document features and provide useful information on building with Waf.

Other changes

In Samba/source4/dns_server/dns_query.c:

@@ -30,7 +30,7 @@
 #include "dsdb/samdb/samdb.h"
 #include "dsdb/common/util.h"
 #include "dns_server/dns_server.h"
-#include "libcli/dns/libdns.h"
+#include "libcli/dns/libudp.h"
 #include "lib/util/dlinklist.h"
 #include "lib/util/util_net.h"
 #include "lib/util/tevent_werror.h"

In Samba/libcli/dns/wscript_build:

@@ -1,5 +1,7 @@
#!/usr/bin/env python

+# builds a library for DNS TCP/UDP calls that utilizes GSS-TSIG encryption
-         source='dns.c',
-         public_deps='LIBTSOCKET tevent-util')
+	  source='cli_dns.c',
+	  public_deps='LIBTSOCKET tevent-util',
+	  deps='gensec auth samba_server_gensec dnsserver_common')

In Samba/wscript_build:

@@ -120,12 +120,14 @@ bld.RECURSE('libcli/lsarpc')
+    bld.RECURSE('libcli/dns/cmocka-tests/test-fn')
 if bld.CONFIG_GET('KRB5_VENDOR') in (None, 'heimdal'):

DNS client and features

This section provides information on cli_dns functionality.

TCP/UDP requests

The client may use either TCP or UDP protocols to send a DNS name request to the server, then handle the reception of the appropriate server response.


  • UDP async request send/receive
  • TCP async request send/receive
  • GSS-TSIG generation
  • DNS name packet parsing and signing

The library consists of cli_dns.c, that includes functions, and dns.h, libtcp.h, libtsig.h, libudp.h, that provide definitions and structures.


wrap_cli.c provides multiple wrapping of the above functionality, to hide buffer creation, DNS packet parsing and signature generation. Definitions of the wrapped functions are provided in libwrap.h.

Test suite

In cmocka-tests, cli_tests.c provides a test suite for the complete client-side functionality, as defined by the functions in libcli/dns/cli_dns.c. The API used for unit testing is Cmocka.

In cmocka-tests/test-fn, there are individual unit tests for every feature library in libcli/dns. All of these tests are incorporated in cmocka-tests/cli_tests.c These tests can be built by using waf-samba and the intended configuration in cmocka-tests/test-fn/wscript. The purpose of these test suites is to facilitate future additions and features in Samba client-side code, without the necessity to integrate them directly to cli_dns.c, thus making changes easier to test and encourage future contributions.

To-do list

Potential improvements include:


I was unable to run the test suites myself in the given time. The code however was integrated and built with samba without problems, though it is essential to work on the tests and ensure that they are functional and serve their purpose.

All included tests have room for refinement, improvement and more thorough function checks. A few specific points of interest would be:

  1. cmocka-tests/test-fn: wscript needs to be properly configured to enable standalone test builds for the feature libraries.
  2. cmocka-tests/cli_tests.c: TCP/UDP callbacks may be additionally tested for internal error output in their respective test functions.


GSoC 2017 has been a massively influential experience for me. I will never forget how overwhelmingly excited I was when I received the acceptance e-mail, during class. Being actively involved in a large scale programming project, being part of the Open Source community, for me is its own reward and something that fulfilled a goal (dare I say dream) that I set in my early teens.

During the first period of the programme, I was knee-deep in classes and MSc exams, but I tried to go through every bit of documentation I could come across, study RFCs for networking protocols, read articles on active directories in a network, search for tutorials, I would literally consume every tiny bit of credible information I could get my hands on. This quest for knowledge was also expanded in better understanding Linux/UNIX systems. Having set my milestones in a way that could support the need for better comprehension of the fundamentals, as well as other information that would come up during the project, helped significantly.

When the coding period started, I quickly came to realize that my programming skills in C and Python had to be majorly extended to include all the Samba APIs, and this should also happen fast! By far the hardest part during the coding process, was learning to properly read Samba code and learn how to use the APIs to add the features required for my project. And this was NOT easy! I learned a great deal about how C handles a number of conventions, how the Samba APIs fit the job that they're used for (Metze wrote on an e-mail, that once I got around talloc, I'd never want to use anything else - and he was right!), I learned how to integrate new code into existing and make it work together. Honestly, I can write so much about the technical knowledge I acquired during working on Samba during GSoC, it would get tiring for the person reading this!

I must however mention what are probably the most important pieces of knowledge I received:

  • the importance of standardized mailing list conventions in a project's work flow
  • the awesomeness of Git for version control

Overall, the last three months were really tough, spending more than 10-11 hours/day working on the project. There were many frustrating moments, so much fatigue from the whole year, summer temptations that made it tough not to lose focus. And if I had to choose again between spending this summer coding in 40 °C, or laying on a beach at a Greek island, I'd choose the first in a blink of an eye!

I want to thank Jeremy, Stefan (Metze), Andreas, Ralph (Slow), Simo and everyone else from Samba Team that took the time to answer to my, on occasion, preposterous questions! :)

My dearest thanks go to my mentors, Kai and David, who allowed me to take part in GSoC and helped me troubleshoot my way through crashes, bugs, miscomprehensions. Especially David, whose replies to my e-mails during those late hours at the final stage of the project, provided much needed answers.

If there is a small piece of advice that I can share with future participants, is to give yourselves 110% to your projects and remember that they are meant to be educative and fun. The rewards for your efforts will be far more meaningful than you might initially think.