commit 382c5c69364cfa687d4da4b895e9d0a09edd545d parent a97ac260ec5196ba730455e0e4d966ae2940523c Author: Matyja Lukas Adam <lukas.matyja@students.bfh.ch> Date: Tue, 5 Mar 2024 23:29:47 +0100 [doc] add bachelor thesis template with the protocol Diffstat:
31 files changed, 1009 insertions(+), 4 deletions(-)
diff --git a/doc/flows/.~lock.timechart.ods# b/doc/flows/.~lock.timechart.ods# @@ -0,0 +1 @@ +,enigma,Debian,04.03.2024 11:40,file:///home/enigma/.config/libreoffice/4; +\ No newline at end of file diff --git a/doc/flows/Makefile b/doc/flows/Makefile @@ -1,4 +0,0 @@ -all: - pdflatex main.tex -clean: - rm *.aux *.log *.pdf *.out diff --git a/doc/flows/bachelor_thesis/README.md b/doc/flows/bachelor_thesis/README.md @@ -0,0 +1,69 @@ +# How to use this template +This is a template for creating a thesis document (BSc or MSc) based on the bfh-ci package using the bfhthesis class. It helps to get started quickly. Problems and improvements can be reported via our issue tracker. Any kind of improvement is welcome, also other templates that cover a use case based on bfhthesis or bfhpub class. + +## Installing the dependencies +Install a recent LaTeX distribution and the latest version of the LaTeX package bfh-ci. How to do this is described in detail in the online manual. Follow the instructions for your operating system. + * https://latex.ti.bfh.ch + +## Information about the structure +The "*.tex" is a LaTeX document with a preamble and a LaTeX body with placeholder text. We recommend that you use this example as a quick introduction to writing short reports, such as a lab report. For an example of how to insert citations to online articles, books, etc., we recommend using biblatex. The bibliography database is stored in a ".bib" file. The content of such a file follows the definitions described in the biblatex user manual. Use the sample.bib file to get started. + +## Parameterization +There is a local `latexmk` configuration file called ".latexmkrc". This file contains some pre-configurations like the name of the output directory ("_build") and the default latex compiler ("lualatex"). Modify or delete this file. + +## Note +We recommend using Git for version control. If you are using Git, create a gitignore file with a good set of ignore patterns. For a quick start, we recommend the following patterns. + * Get a general set of ignore patterns + * https://www.toptal.com/developers/gitignore?templates=latex,windows,linux,vim,emacs,osx + ``` + curl -L -o .gitignore https://www.toptal.com/developers/gitignore/api/latex,windows,linux,vim,emacs,osx + ``` + * Ignore all directories that start with an underscore '_*/' + ``` + echo '_*/' >> .gitignore + ``` + +## Compiling +To compile the LaTeX document, use your favorite LaTeX editor together with the TeX compiler (xelatex and lualatex are supported). Thre is no support for pdflatex compiler. + +If you use latexmk on the command line, the following command will do the compilation. + +#### Running Latexmk + * In the simplest case you just have to type +```bash +latexmk -lualatex +``` + *This runs LaTeX on all .tex files in the current directory using the output format specified by the configuration files.* + + * If you want to make sure to get a .pdf file as output, just mention it: +```bash +latexmk -pdflua +``` + * If you want to compile only one specific .tex file in the current directory, just provide the file name: +```bash +latexmk -lualatex myfile.tex +``` + * If you want to preview the resulting output file(s), just use +```bash +latexmk -pv -lualatex +``` + * And now the killer feature: If you want LaTeXmk to continuously check all input files for changes and re-compile the whole thing if needed and always display the result, type +```bash +latexmk -pvc -lualatex -interaction=nonstopmode +``` +Then, whenever you change something in any of your source files and save your changes, the preview is automatically updated. But: This doesn’t work with all viewers, especially not with Adobe Reader. See the section about configuration files below for setting a suitable viewer application. + + * Of course, options can be combined, e.g. +```bash +latexmk -outdir=_build -pdf -pv myfile.tex +``` + +#### Cleanup + * After running LaTeX, the current directory is contaminated with a myriad of temporary files; you can get rid of them with +```bash +latexmk -c +``` + * Previous command doesn’t delete the final .pdf/.ps/.dvi files. If you want to delete those too, use +```bash +latexmk -C +``` diff --git a/doc/flows/bachelor_thesis/content/.gitkeep b/doc/flows/bachelor_thesis/content/.gitkeep diff --git a/doc/flows/bachelor_thesis/content/abstract.tex b/doc/flows/bachelor_thesis/content/abstract.tex @@ -0,0 +1 @@ +One-paragraph summary of the entire study – typically no more than 250 words in length (and in many cases it is well shorter than that), the Abstract provides an overview of the study. diff --git a/doc/flows/definitions.tex b/doc/flows/bachelor_thesis/content/definitions.tex diff --git a/doc/flows/bachelor_thesis/content/discussion.tex b/doc/flows/bachelor_thesis/content/discussion.tex @@ -0,0 +1,2 @@ +\section{Discussion} +What is the significance of your results? – the final major section of text in the paper. The Discussion commonly features a summary of the results that were obtained in the study, describes how those results address the topic under investigation and/or the issues that the research was designed to address, and may expand upon the implications of those findings. Limitations and directions for future research are also commonly addressed. diff --git a/doc/flows/bachelor_thesis/content/expl_fragments.tex b/doc/flows/bachelor_thesis/content/expl_fragments.tex @@ -0,0 +1,440 @@ +\section{Some \texorpdfstring{\LaTeX}{LaTeX}~Examples} + +\blindtext[1] + +\subsection{Tabular} + +\begin{tabular}[h]{l|l|l} + \centering + Measure & Data & Unit \\ \hline + 1 & 2 & 3 \\ + 4 & 5 & 6 +\end{tabular} + +% Example for a Table in BFH-Style with a simple Design +\begin{table}[ht] + \centering + \begin{bfhTabular}{lll} + Stadtteil & Anzahl Personen & Ausländische + Bevölkerung\\\hline + Innere Stadt & \num{3748} & \SI{17.9}{\percent}\\\hline + Länggasse-Felsenau & \num{17976} & \SI{17.1}{\percent}\\\hline + Mattenhof-Weissenbühl & \num{26895} & \SI{22.4}{\percent}\\\hline + Kirchenfeld-Schlosshalde & \num{23384} & \SI{13.4}{\percent}\\\hline + Breitenrain-Lorraine & \num{24082} & \SI{19.4}{\percent} + \end{bfhTabular} + \caption{Anzahl Personen, ausländischer Bevölkerungsanteil und Arbeitslosenquote pro + Stadtteil Ende 2005 (Statistikdienste der Stadt Bern, 2006)} + \label{tab:tab1} +\end{table} + +\begin{table}[ht] + \centering + \colorlet{BFH-table}{BFH-MediumBlue!10} + \colorlet{BFH-tablehead}{BFH-MediumBlue!50} + \begin{bfhTabular}{lll} + Stadtteil & Anzahl Personen & Ausländische + Bevölkerung\\\hline + Innere Stadt & \num{3748} & \SI{17.9}{\percent}\\\hline + Länggasse-Felsenau & \num{17976} & \SI{17.1}{\percent}\\\hline + Mattenhof-Weissenbühl & \num{26895} & \SI{22.4}{\percent}\\\hline + Kirchenfeld-Schlosshalde & \num{23384} & \SI{13.4}{\percent}\\\hline + Breitenrain-Lorraine & \num{24082} & \SI{19.4}{\percent} + \end{bfhTabular} + \caption{Anzahl Personen, ausländischer Bevölkerungsanteil und Arbeitslosenquote pro + Stadtteil Ende 2005 (Statistikdienste der Stadt Bern, 2006)} + \label{tab:tab2} +\end{table} + +\begin{table}[ht] + \centering + \colorlet{BFH-table}{BFH-MediumRed!10} + \colorlet{BFH-tablehead}{BFH-MediumRed!50} + \begin{bfhTabular}{lll} + Stadtteil & Anzahl Personen & Ausländische + Bevölkerung\\\hline + Innere Stadt & \num{3748} & \SI{17.9}{\percent}\\\hline + Länggasse-Felsenau & \num{17976} & \SI{17.1}{\percent}\\\hline + Mattenhof-Weissenbühl & \num{26895} & \SI{22.4}{\percent}\\\hline + Kirchenfeld-Schlosshalde & \num{23384} & \SI{13.4}{\percent}\\\hline + Breitenrain-Lorraine & \num{24082} & \SI{19.4}{\percent} + \end{bfhTabular} + \caption{Anzahl Personen, ausländischer Bevölkerungsanteil und Arbeitslosenquote pro + Stadtteil Ende 2005 (Statistikdienste der Stadt Bern, 2006)} + \label{tab:tab3} +\end{table} + + +\begin{description} +\item[More about Tables] Further information about tables : \url{https://www.latex-tutorial.com/tutorials/tables/} +\item[Long Tables] Further information about long tables : \url{https://www.overleaf.com/learn/latex/tables} +\end{description} + + +\begin{longtable}{|l|l|l|} +\caption{A sample long table} \label{tab:long} \\ + + +\hline \multicolumn{1}{|c|}{\textbf{First column}} & \multicolumn{1}{c|}{\textbf{Second column}} & \multicolumn{1}{c|}{\textbf{Third column}} \\ \hline +\endfirsthead + +\multicolumn{3}{c}% +{{\tablename\ \thetable{}: \hfill $...$~continued from previous page}} \\ +\hline \multicolumn{1}{|c|}{\textbf{First column}} & \multicolumn{1}{c|}{\textbf{Second column}} & \multicolumn{1}{c|}{\textbf{Third column}} \\ \hline +\endhead + +\hline \multicolumn{3}{|r|}{{Continued on next page$...$}} \\ \hline +\endfoot + +\hline \hline +\endlastfoot +\centering + +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +One & abcdef ghjijklmn & 123.456778 \\ +\end{longtable} + + +\subsection{Math} +%% Mathematical equations +\begin{align} +\left(\begin{array}{r} +\dot{x_{1}} \\ +\dot{x_{2}} \\ +\dot{x_{3}} \\ +\end{array}\right) = +\left[\begin{array}{rrr} +0 & 1 & 0 \\ +0 & -\frac{b_{f}}{J} & \frac{K_{m}}{J} \\ +0 & -\frac{K_{g}}{L} & \frac{R}{L} \\ +\end{array}\right] +\left(\begin{array}{r} +x_{1} \\ +x_{2} \\ +x_{3} \\ +\end{array}\right) + +\left[\begin{array}{rr} +0 & 0 \\ +-\frac{1}{J} & 0 \\ +0 & \frac{1}{L} \\ +\end{array}\right] +\left(\begin{array}{r} +t_{L} \\ +v_{a} \\ +\end{array}\right) +\end{align} + +\subsection{Include pictures} + +\begin{figure}[H] + \centering + \includegraphics[width=.8\textwidth]{placeholder} + \caption{Some meaningful caption} + \label{fig:placeholder:1} +\end{figure} + + +\begin{figure}[h!] + \centering + \begin{minipage}{.4\textwidth} + \centering + \includegraphics[width=\textwidth]{placeholder} + \caption{PLACEHOLDER} + \label{fig:placeholder:2} + \end{minipage} + \hspace{1em} + \begin{minipage}{.4\textwidth} + \centering + \includegraphics[width=\textwidth]{placeholder} + \caption{PLACEHOLDER} + \label{fig:placeholder:3} + \end{minipage}% +\end{figure} + + +%% Source code is stored in the listings folder and will be included from there using its relative path. +\subsection{Code Example} + +{ + \thicklines +% \thinlines +\lstinputlisting[style=bfh-c,language=C,caption={My very first C program.},label={lst:hello}]{listings/expl_hello.c} +} +I developed this very nice application writing "Hello World" to my terminal. +The implementation is shown in listing~\ref{lst:hello}. + + +%% Examples holding dummy content +\subsection{Draw boxes} +\begin{bfhBox}[BFH-DarkPurple]{Purple} + Note\\ +\end{bfhBox} + +\blindtext[1] + +\begin{bfhBox}[BFH-MediumBlue]{Blue} + Note\\ +\end{bfhBox} + +\blindtext[1] + +\begin{bfhBox}[BFH-DarkRed]{Red} + Note\\ +\end{bfhBox} + +\blindtext[2] + +\begin{bfhAlertBox} + An alert box. +\end{bfhAlertBox} + +\begin{bfhWarnBox} + A warning box. +\end{bfhWarnBox} + +\begin{bfhNoteBox} + A note box. +\end{bfhNoteBox} + +\begin{bfhRecycleBox} + A recycle box. +\end{bfhRecycleBox} + + +\begin{bfhBox}{No color set} + Some BFH box without color option set. Using default.\\ +\end{bfhBox} + + +\blindtext[3] + + +\subsection{Some Item-list} +Sometimes you explain this and that using a bullet points. +This can be done in \LaTeX\ using an item list in a item environment. + +\begin{itemize} +\item My first item +\item The second +\item $\cdots$ +\item $\cdots$ +\end{itemize} + +It is also possible to nest such environment and/or enumerate. +\begin{itemize} +\item My first item +\begin{enumerate} +\item My first enumerated item +\item The second +\item $\cdots$ +\end{enumerate} +\item The second +\begin{enumerate} +\item An other enumerated item +\item $\cdots$ +\item $\cdots$ +\end{enumerate} +\end{itemize} + + +\subsection{Multi column environment} +Split a part of a document in multiple columns is not so easy with WYSIWYG tools. +Whit multicols \LaTeX\ package$\cdots$ well you may know. + +\begin{multicols}{3} +\begin{itemize} +\item My first item +\item The second +\item $\cdots$ +\item $\cdots$ +\end{itemize} +\begin{itemize} +\item My first item +\item The second +\item $\cdots$ +\item $\cdots$ +\end{itemize} +\begin{itemize} +\item My first item +\item The second +\item $\cdots$ +\item $\cdots$ +\end{itemize} +\end{multicols} + + +\blindtext[1] + +\begin{multicols}{2} + \blindtext[1] +\end{multicols} + +\begin{multicols}{3} + \blindtext[1] +\end{multicols} + +\begin{multicols}{2} + \blindtext[1] +\end{multicols} + + +\begin{multicols}{3} +\begin{itemize} +\item My first item +\item The second +\item $\cdots$ +\item $\cdots$ +\end{itemize} +\blindtext[1] +\columnbreak +\begin{itemize} +\item My first item +\item The second +\item $\cdots$ +\item $\cdots$ +\end{itemize} +\end{multicols} + +%% forced page break +\newpage + +\subsection{Use Figures} + +\begin{figure}[h!] + \centering + \includegraphics[width=.8\textwidth]{bg-masthead} + \caption{An example of including a PDF figure.} + \label{fig:expl_master} +\end{figure} + +\begin{figure}[h!] + \centering + \includegraphics[width=.8\textwidth]{expl_bode} + \caption{An example of including a PDF figure.} + \label{fig:expl_bode} +\end{figure} +\clearpage + +\subsubsection{Use Subfigures} +These subfigures requires the package \texttt{subcaption}. + +\begin{figure}[h!] + \centering + \begin{subfigure}[b]{0.3\textwidth} + \centering + \includegraphics[width=\textwidth]{placeholder} + \caption{$y=x$} + \label{fig:y equals x} + \end{subfigure} + \hfill + \begin{subfigure}[b]{0.3\textwidth} + \centering + \includegraphics[width=\textwidth]{placeholder} + \caption{$y=3sinx$} + \label{fig:three sin x} + \end{subfigure} + \hfill + \begin{subfigure}[b]{0.3\textwidth} + \centering + \includegraphics[width=\textwidth]{placeholder} + \caption{$y=5/x$} + \label{fig:five over x} + \end{subfigure} + \caption{Three simple graphs} + \label{fig:three graphs} +\end{figure} + + +\section{Example Text With Indices} +In this example, several keywords\index{keywords} will be used +which are important and deserve to appear in the Index\index{Index}. + +Terms like generate\index{generate} and some\index{others} will +also show up. + +\section{Example Text With Glossary} +This \Gls{zynq} introduction summary has been written for bachelor students due to the introduction workshop in the ``Embedded Systems'' course at Bern University of Applied Sciences. The topic \Gls{soc} is introduced by using Xilinx' \Gls{apsoc} platform \Gls{zynq}. The subsequent summery is a brief introduction only. It is based on several tutorials in the field of \Gls{soc} such as the \Gls{zbook} or Xilinx' \Gls{apsoc} manual. We think the script provides a good introduction and helps getting the overall picture of the \Gls{soc} basics. In addition we reference to our wiki tutorials that provide lots of information on how to get started with the \Gls{zboard}.\\ + +Hey folks let's do an \Gls{asic} design and develop some awesome \Gls{rtos}! Yea \Gls{arm} is nice but we can do better, can we? + +\section{Example Text With Citations} +%% Text with citations + +This document is an example of \Gls{BibTeX} using in bibliography management. Three items +are cited: The \LaTeX\ Companion book \cite{latexcompanion}, the Einstein +journal paper \cite{einstein}, and the Donald Knuth's website \cite{knuthwebsite}. +The \LaTeX\ related items are \cite{latexcompanion,knuthwebsite}. + diff --git a/doc/flows/bachelor_thesis/content/glossary.tex b/doc/flows/bachelor_thesis/content/glossary.tex @@ -0,0 +1,54 @@ +\newglossaryentry{BibTeX}{ + name={BibTeX}, + description={Program for the creation of bibliographical references and directories in \TeX or \LaTeX\, documents}, + plural=BibTeXs +} + +\newglossaryentry{zynq}{ + name=Zynq, + description={\textbf{Zynq} Xilinx' AP SoC. The characteristic feature of Zynq is that it combines a dual-core ARM Cortex-A9 processor with traditional Series-7 FPGA logic fabric}, + plural=Zynqs +} + + +\newglossaryentry{soc}{ + name=SoC, + description={\textbf{System-on-Chip (SoC)} A single chip that holds all of the necessary hardware and electronic circuitry for a complete system. SoC includes on-chip memory (RAM and ROM), the microprocessor, peripheral interfaces, I/O logic control, data converters, and other components that comprise a complete computer system}, + plural=SoCs +} + +\newglossaryentry{apsoc}{ + name=AP SoC, + description={\textbf{All Programmable System-on-Chip (AP SoC)} was introduced by Xilinx. It represents a IC which comprise a hard-core processor core surrounded by an FPGA fabric. This type of ICs are highly configurable and provide algorithm partitioning capabilities. This provides high benefit for highly scale-able applications as well as fast time-to-market}, + plural=AP SoCs +} + +\newglossaryentry{zbook}{ + name=Zynq Book, + description={\textbf{Zynq Book} A book that summarizes all the important aspects when working with Zynq and provides a strong and easy understandable introduction to the topic. The book has been written by a team of University of Strathclyde Glasgow in cooperation with Xilinx}, + plural=Zynq Books +} + +\newglossaryentry{zboard}{ + name=ZedBoard, + description={\textbf{ZedBoard} A low cost development board featuring a Zynq-700 0 SoC, and a number of peripherals}, + plural=ZedBoards +} + + +\newglossaryentry{asic}{ + name=ASIC, + description={\textbf{Application-Specific Integrated Circuit (ASIC)} An integrated circuit which is designed for a specific use, rather than general-purpose use}, + plural=ASICs +} + +\newglossaryentry{rtos}{ + name=RTOS, + description={\textbf{Real-Time Operating System (RTOS)} A category of operating systems defined by their ability to respond quickly and predictably for a given task}, + plural=RTOSs +} + +\newglossaryentry{arm}{ + name=ARM, + description={\textbf{ARM} A family of processor architectures. The hard processor type which forms the basis of the Zynq processing system is an ARM Cortex-A9 version. The term ‘ARM’ may also be used to refer to the developer of the processor, i.e. a company of the same name} +} diff --git a/doc/flows/bachelor_thesis/content/introduction.tex b/doc/flows/bachelor_thesis/content/introduction.tex @@ -0,0 +1,4 @@ + +The Donau is a Taler extension which should make it possible to make donations anonymously, but the amount of the donation should be able to be proven to the tax authorities. Similar to the Taler exchange, the Donau has the Donation Authority (or Donau for short). The Donau blindly signs the charity's donation receipts request. For submission to the tax authorities, the donor must submit the donation receipts to the Donau, whereupon the donor receives the donation statement (signature), which is made available to the tax authorities. +\\ +This concept, which has not yet been finalized, is discussed in more detail in the following pages. The API definition, written by us, can be found under this link: \url{https://docs.taler.net/core/api-donau.html}. diff --git a/doc/flows/bachelor_thesis/content/main.tex b/doc/flows/bachelor_thesis/content/main.tex @@ -0,0 +1,203 @@ +% \documentclass{article} +% +% \usepackage[english]{babel} +% \usepackage[utf8]{inputenc} +% \usepackage{amsmath,amssymb} +% \usepackage{parskip} +% \usepackage{graphicx} +% +% \graphicspath{ {./images/} } +% +% % Margins +% \usepackage[top=3cm, left=3cm, right=3cm, bottom=3cm]{geometry} +% % Colour table cells +% \usepackage[table]{xcolor} +% % diagram packages +% \usepackage{tikz, pgfplots} +% \usetikzlibrary{positioning} +% +% \title{Donau protocol overview} +% \author{Johannes Casaburi \and Pius Loosli \and Lukas Matyja} +% \date{\today} +% +% \begin{document} +% \maketitle +% +% \newpage +% +% \input{definitions.tex} + +\section{Overview} +%\includegraphics[width=\textwidth]{overview} + +%\input{diagrams.tex} + +\newpage +\section{Protocol Detail} + +\subsection{Key generation and initial setup} +\subsubsection{Initial Donau setup} +\begin{enumerate} + \item The Donau generates a public key $D^{pub}$ and private key $D^{priv}$ for EdDSA signing. + + \item The Donau generates the \emph{donation unit keys} consisting of $K_x^{pub}$ and $K_x^{priv}$ where $x$ is the associated value. +\end{enumerate} + +\subsubsection{Charity setup (Charity side and Donau side)} +\begin{enumerate} + \item The \textbf{charity} generates the key pair $(C^{pub}, C^{priv})$ and downloads the \emph{donation unit public keys} from the donau. + + \item The \textbf{charity} transmits $C^{pub}$ and the desired yearly donation limit to the party responsible for Donau administration using a \textbf{secure channel}. + + \item The party in charge of \textbf{Donau administration} ensures that the applying party is authentic and if it is publicly recognized as charity organisation. Furthermore, it ensures that all eventual other checks required by law are done. If everything is clear, it registers the public key $C^{pub}$ and sets the requested yearly donation limit for the charitiy. +\end{enumerate} + + +\subsection{Continuously during tax period: get donation receipts} +\subsubsection{Overview} + + +\subsubsection{Donor donates to charity and transmits unique donor ids (future donation receipts)} +\begin{enumerate} + \item The donor downloads the \emph{donation unit public keys} $K_x^{pub}$ for the corresponding year from the Donau. (if not already done) + + \item The donor splits the donation amount into a sum of \emph{donation units} offered by the Donau. \\ + \emph{Example: With donation units \{1,2,4\} available, and a donation with a total value of 7, the donation amount is split into the sum 4+2+1.} + + \item The donor generates as many \emph{unique donor identifiers} as there are terms in the calculated sum. + \emph{Example: In our example, there will be 3 unique donor identifiers: one per donation unit, so one for the value 4, one for the value 2, one for the value 1}.\footnote{If one donation unit is present more than once in the sum, then there is more than one unique donor identifier required for said donation unit. This depends upon the offered donation units.} + \begin{align} + i :&= h(\texttt{taxid, salt})\\ + u_1 :&= \langle i, \texttt{nonce}_1 \rangle \\ + u_2 :&= \langle i, \texttt{nonce}_2 \rangle \\ + u_3 :&= \langle i, \texttt{nonce}_3 \rangle + \end{align} + + \item The donor blinds the \emph{unique donor identifiers} using a \textbf{different} blinding factor $b$ for every \emph{unique donor identifier}.\\ + \emph{Example:} + \begin{align} + \overline u_1 :&= blind (u_1, b_1, K_1^{pub}) \\ + \overline u_2 :&= blind (u_2, b_2, K_2^{pub}) \\ + \overline u_3 :&= blind (u_3, b_3, K_4^{pub}) + \end{align} + + \item So far, the \emph{unique donor identifiers} do not carry information about their value. The \textbf{intended effective value is now indicated} by grouping each \emph{unique donor identifier} with the according (hash of the) \emph{donation unit public key} $K^{pub}_x$. \\ + We call these pairs \emph{blinded unique donor identifier-key-pair}, \emph{budi-key-pair} or even shorter BKP.\\ + \\ + It is only the \textbf{intended effective} value because the value will only be attributed later on with the signature of the Donau. + + \emph{Example: Note: The public key is not in relation with the sequential index of the budi-key-pair, it only relates to the value of the pair!} + \begin{align} + \overline \mu_1 :&= \langle \overline u_1, h(\color{red}{K^{pub}_1}\color{black}{}) \rangle \\ + \overline \mu_2 :&= \langle \overline u_2, h(\color{red}{K^{pub}_2}\color{black}{}) \rangle \\ + \overline \mu_3 :&= \langle \overline u_3, h(\color{red}{K^{pub}_4}\color{black}{}) \rangle + \end{align} + \begin{align} + \vec{\mu} :&= \langle \overline \mu_1, + \overline \mu_2,\overline \mu_3 + \rangle + \end{align} + \item The donor sends all \emph{BKP's} the $\vec{\mu}$ as well as the corresponding payment to the charity. +\end{enumerate} + +\subsubsection{Charity sends signed $BKP$'s to Donau} +\begin{enumerate} + \item The charity verifies that the amount requested (based on the $h(K_x^{pub})$) for signing is lower or equal to the effective amount of the donation. + + \item The charity signs (using EdDSA) a structure containing all unsigned $BKP$'s coming from the donor. + + \begin{align} + \sigma_c = sign(\vec{\mu}, C^{priv}) + \end{align} + + \item The charity sends this structure $\vec{\mu}$ and the signature $\sigma_c$ to the Donau. +\end{enumerate} + +\subsubsection{Donau sends back the blind signed $UDI$'s to charity} +\begin{enumerate} + \item The Donau: + \begin{enumerate} + \item verifies the signature $\sigma_c$ on the structure. + + \begin{align} + verify(\vec{\mu},\sigma_c, C^{pub}) + \end{align} + + \item increments the current amount of donations received per year of the charity. This value is increased by the total amount of the $BUDI$'s, if the increment does not exceed the annual limit. + + \item blind signs all the $blinded$ $UDI$'s, the $BUDI$'s, using the \emph{donation unit private keys} $K_x^{priv}$ matching the public keys $h(K^{pub})$ used in the $BKP$'s. + + \begin{align} + \overline{\beta_1} = blind\_sign(\overline u_1, K_1^{priv}) \\ + \overline{\beta_2} = blind\_sign(\overline u_2, K_2^{priv}) \\ + \overline{\beta_3} = blind\_sign(\overline u_3, K_4^{priv}) + \end{align} + + \item sends back all created blind signatures + $\overline{\beta_1}, \overline{\beta_2}, \overline{\beta_3}$ to the charity. + \end{enumerate} + + \item The charity forwards the blind signatures to the donor. + + \item The donor verifies the signatures. + + \begin{align} + verify\_blind(u_1,\overline{\beta_1}, K_1^{pub}) \\ + verify\_blind(u_2,\overline{\beta_2}, K_2^{pub}) \\ + verify\_blind(u_3,\overline{\beta_3}, K_4^{pub}) + \end{align} + + \item The donor unblinds the signatures of the $BUDI$'s to get the signatures of the $UDI$'s. This results in a collection of \textbf{Donation Receipts} $DR$'s each consisting of the $UDI$, the signature $\beta$ and the Hash of the \emph{donation unit public key} $h(K_x^{pub})$. + + \begin{align} + \beta_1 &= Unblind(\overline{\beta_1}, b_1, K_1^{pub}) \\ + \beta_2 &= Unblind(\overline{\beta_2}, b_2, K_2^{pub}) \\ + \beta_3 &= Unblind(\overline{\beta_3}, b_3, K_4^{pub}) + \end{align} + \begin{align} + r_1 &= \langle UDI_1, \beta_1, h(K_1^{pub}) \rangle \\ + r_2 &= \langle UDI_2, \beta_2, h(K_2^{pub}) + \rangle \\ + r_3 &= \langle UDI_3, \beta_3, h(K_4^{pub}) \rangle + \end{align} +\end{enumerate} + +\subsection{After effective tax period: get tax statement for period from Donau} + +\subsubsection{Donor sends the \emph{Donation receipts} to the Donau to get the \emph{Donation Statement}.} +\begin{enumerate} + \item The donor sends the collection of all \emph{donation receipts} $r_1, r_2, r_3$ to the Donau. This happens manually once per period.\\\ + It is not done continuously to obtain \emph{unlinkability} between the \textbf{issuance} of the donation receipts (which happens upon donation) and their \textbf{submission} for the \emph{donation statement}. + \item For each \emph{donation receipt} the Donau: + \begin{itemize} + \item checks that $K_x^{pub}$ is known. + + \item verifies that the signature $\beta$ is correct using the corresponding public key $K_x^{pub}$. + + \item verifies that the \emph{donor identifier} is the same as in other \emph{donation receipts}.\footnote{With multiple wallets each wallet must simply obtain a separate \emph{donation statement}!} + + \item verifies that the $\texttt{nonce}$ is unique and was not used before by the donor for the corresponding year. + \end{itemize} + + \item The Donau signs over the total \texttt{amount}, + \texttt{year} and \emph{donor identifier} and sends the signature and the total amount so far back to the donor. This results in a final signature called the \textbf{\emph{Donation Statement signature}}. + + \begin{align} + \sigma_s = sign(\langle i, \texttt{amount}_{Total}, \texttt{year}) \rangle, D^{priv}) + \end{align} +\end{enumerate} + +\subsubsection{Donor sends the QR Code to a validator (tax office)} +\begin{enumerate} + \item The donor generates a QR code which contains the following: + \begin{align} + \texttt{QR} = \langle \texttt{taxid}, \texttt{salt}, \texttt{year}, \texttt{amount}, \text{$\sigma_s$} \rangle + \end{align} + + \item The validator scans the QR code and verifies the signature $\sigma_s$. + + \begin{align} + verify(\langle i, \texttt{amount}_{Total}, \texttt{year}) \rangle,\sigma_s, D^{pub}) + \end{align} +\end{enumerate} + diff --git a/doc/flows/bachelor_thesis/content/methods.tex b/doc/flows/bachelor_thesis/content/methods.tex @@ -0,0 +1,2 @@ +\section{Methods} +What did you do? – a section which details how the research was performed. It typically features a description of the participants/subjects that were involved, the study design, the materials that were used, and the study procedure. If there were multiple experiments, then each experiment may require a separate Methods section. A rule of thumb is that the Methods section should be sufficiently detailed for another researcher to duplicate your research. diff --git a/doc/flows/bachelor_thesis/content/results.tex b/doc/flows/bachelor_thesis/content/results.tex @@ -0,0 +1,2 @@ +\section{Results} +What did you find? – a section which describes the data that was collected and the results of any statistical tests that were performed. It may also be prefaced by a description of the analysis procedure that was used. If there were multiple experiments, then each experiment may require a separate Results section. diff --git a/doc/flows/bachelor_thesis/donau_report_project2.pdf b/doc/flows/bachelor_thesis/donau_report_project2.pdf Binary files differ. diff --git a/doc/flows/bachelor_thesis/donau_report_project2.tex b/doc/flows/bachelor_thesis/donau_report_project2.tex @@ -0,0 +1,196 @@ +%============================ MAIN DOCUMENT ================================ +% define document class +\PassOptionsToPackage{table}{xcolor} +\documentclass[ + a4paper, + BCOR=15mm, % Binding correction + twoside, +% openright, +% headings=openright, + bibliography=totoc, % If enabled add bibliography to TOC + listof=totoc, % If enabled add lists to TOC + monolingual, +% bilingual, + invert-title, +]{bfhthesis} + +\LoadBFHModule{listings,terminal,boxes} +%--------------------------------------------------------------------------- +% Documents paths +%--------------------------------------------------------------------------- +\makeatletter +\def\input@path{{content/}} +%or: \def\input@path{{/path/to/folder/}{/path/to/other/folder/}} +\makeatother +%----------------- Base packages -------------------------------------- +% Include Packages +\usepackage[french,ngerman,main=english]{babel} % https://www.namsu.de/Extra/pakete/Babel.html + +\usepackage{amsmath} % various features to facilitate writing math formulas +\usepackage{amsthm} % enhanced version of latex's newtheorem +\usepackage{amsfonts} % set of miscellaneous TeX fonts that augment the standard CM +\usepackage{amssymb} % mathematical special characters + +\usepackage{siunitx} + +\usepackage{graphicx} % integration of images +\usepackage{float} % floating objects + +\usepackage{caption} % for captions of figures and tables +\usepackage{subcaption} % for subcaptions in subfigures +\usepackage{cite} % use bibtex +\usepackage{wrapfig} + +\usepackage{exscale} % mathematical size corresponds to textsize +\usepackage{multirow} % multirow emables combining rows in tables +\usepackage{multicol} + +\usepackage{longtable} + +\usepackage{parskip} + +%--------------------------------------------------------------------------- +% Graphics paths +%--------------------------------------------------------------------------- +\graphicspath{{pictures/}{figures/}} +%--------------------------------------------------------------------------- +% Blind text -> for dummy text +%--------------------------------------------------------------------------- +\usepackage{blindtext} +\usepackage{letltxmacro} +\LetLtxMacro{\blindtextblindtext}{\blindtext} + +\RenewDocumentCommand{\blindtext}{O{\value{blindtext}}}{ + \begingroup\color{BFH-Gray}\blindtextblindtext[#1]\endgroup +} +%--------------------------------------------------------------------------- +% Glossary Package +%--------------------------------------------------------------------------- +% the glossaries package uses makeindex +% if you use TeXnicCenter do the following steps: +% - Goto "Ausgabeprofile definieren" (ctrl + F7) +% - Select the profile "LaTeX => PDF" +% - Add in register "Nachbearbeitung" a new "Postprozessoren" point named Glossar +% - Select makeindex.exe in the field "Anwendung" ( ..\MiKTeX x.x\miktex\bin\makeindex.exe ) +% - Add this [ -s "%tm.ist" -t "%tmx.glg" -o "%tm.gls" "%tm.glo" ] in the field "Argumente" +% +% for futher informations go to http://ewus.de/tipp-1029.html +%--------------------------------------------------------------------------- +\usepackage[nonumberlist]{glossaries-extra} +\makeglossaries +\input{content/glossary} +%--------------------------------------------------------------------------- +% Makeindex Package +%--------------------------------------------------------------------------- +\usepackage{makeidx} +\makeindex +%\usepackage{imakeidx} % To produce index +%\makeindex[columns=2,intoc] % Index-Initialisation +%\makeindex[columns=3,columnseprule,columnsep,intoc] +%--------------------------------------------------------------------------- +% Hyperref Package (Create links in a pdf) +%--------------------------------------------------------------------------- +\usepackage[ + ,bookmarks + ,plainpages=false + ,pdfpagelabels + ,pdfusetitle + ,backref = {false} % No index backreference + ,colorlinks = {true} % Color links in a PDF + ,hypertexnames = {true} % no failures "same page(i)" + ,bookmarksopen = {true} % opens the bar on the left side + ,bookmarksopenlevel = {0} % depth of opened bookmarks + ,linkcolor=. + ,filecolor=. + ,urlcolor=. + ,citecolor=. +]{hyperref} +%--------------------------------------------------------------------------- + +%% %% Customize Footer and Headers in Document +%% \KOMAoptions{headsepline,plainheadsepline,footsepline,plainfootsepline}% +%% \setkomafont{headsepline}{\color{BFH-DarkBlue}}% BFH-DarkBlue required bfhcolors +%% \setkomafont{footsepline}{\color{BFH-DarkBlue}}% +%% \lehead*{lehead} % the * character does replace the header on the first chapter page as well +%% \cehead*{cehead} +%% \rehead*{rehead} +%% \lohead*{lohead} +%% \cohead*{cohead} +%% \rohead*{rohead} + +%% \lefoot*{lefoot} +%% \cefoot*{cefoot} +%% \refoot*{refoot} +%% \lofoot*{lofoot} +%% \cofoot*{cofoot} +%% \rofoot*{rofoot} +%--------------------------------------------------------------------------- +\begin{document} + +%------------ START FRONT PART ------------ +\frontmatter + +\title{DONAU} +\subtitle{A Donation Authority for Taler} +\author{Pius Loosli \and Johannes Casaburi \and Lukas Matyja} +\institution{Bern University of Applied Sciences} +\department{Technik und Informatik} +\institute{Mikro- und Medizintechnik} +\version{1.0} +\titlegraphic*{\includegraphics{somePicture}} +\advisor{Prof. Dr. Christian Grothoff} +\coadvisor{Prof. Dr. Emmanuel Benoist} +\degreeprogram{Project 2} +\setupSignature{ + A. Muster={\includegraphics[width=.5\linewidth]{sig_muster}}, + C. Example={\includegraphics[width=.5\linewidth]{sig_example}} +} + + +%---------------- BFH tile page ----------------------------------------- +\maketitle +%------------ ABSTRACT ---------------- +%\addchap{Abstract} +%\input{content/abstract} + +%------------ TABLEOFCONTENTS ---------------- +\tableofcontents + +%------------ START MAIN PART ------------ +\mainmatter + +\chapter{Introduction} +\input{content/introduction} + +\chapter{Protocol} +\input{content/definitions.tex} +\input{content/main.tex} + +%------------ Authorship declaration translated to main language ------------ +\declarationOfAuthorship + +%----------- Bibliography ---------------- +\clearpage +\bibliographystyle{unsrt} +\bibliography{project} % the project.bib file gets loaded + +%------------ List of Figures ------------ +\listoffigures + +%------------ List of Tables ------------- +\listoftables + +%------------ List of Listings ----------- +\lstlistoflistings + +%------------ Glossary ------------------- +\printglossary + +%------------ Index ---------------------- +\clearpage +\printindex +%------------ Appendix ---------------- +\appendix +\chapter{First Appendix Chapter} + +\end{document} diff --git a/doc/flows/bachelor_thesis/figures/.gitkeep b/doc/flows/bachelor_thesis/figures/.gitkeep diff --git a/doc/flows/bachelor_thesis/figures/expl_bode.pdf b/doc/flows/bachelor_thesis/figures/expl_bode.pdf Binary files differ. diff --git a/doc/flows/bachelor_thesis/listings/.gitkeep b/doc/flows/bachelor_thesis/listings/.gitkeep diff --git a/doc/flows/bachelor_thesis/listings/expl_hello.c b/doc/flows/bachelor_thesis/listings/expl_hello.c @@ -0,0 +1,8 @@ +#include <stdio.h> +#include <stdlib.h> + +int main( /* int argc, char **argv */ ) +{ + printf("Hello World!\n"); + return EXIT_SUCCESS; +} diff --git a/doc/flows/bachelor_thesis/pictures/.gitkeep b/doc/flows/bachelor_thesis/pictures/.gitkeep diff --git a/doc/flows/bachelor_thesis/pictures/bg-masthead.jpg b/doc/flows/bachelor_thesis/pictures/bg-masthead.jpg Binary files differ. diff --git a/doc/flows/bachelor_thesis/pictures/placeholder.jpg b/doc/flows/bachelor_thesis/pictures/placeholder.jpg Binary files differ. diff --git a/doc/flows/bachelor_thesis/pictures/sig_example.png b/doc/flows/bachelor_thesis/pictures/sig_example.png Binary files differ. diff --git a/doc/flows/bachelor_thesis/pictures/sig_muster.png b/doc/flows/bachelor_thesis/pictures/sig_muster.png Binary files differ. diff --git a/doc/flows/bachelor_thesis/pictures/somePicture.jpg b/doc/flows/bachelor_thesis/pictures/somePicture.jpg Binary files differ. diff --git a/doc/flows/bachelor_thesis/project.bib b/doc/flows/bachelor_thesis/project.bib @@ -0,0 +1,25 @@ +@article{einstein, + author = "Albert Einstein", + title = "{Zur Elektrodynamik bewegter K{\"o}rper}. ({German}) + [{On} the electrodynamics of moving bodies]", + journal = "Annalen der Physik", + volume = "322", + number = "10", + pages = "891--921", + year = "1905", + DOI = "http://dx.doi.org/10.1002/andp.19053221004" +} + +@book{latexcompanion, + author = "Michel Goossens and Frank Mittelbach and Alexander Samarin", + title = "The \LaTeX\ Companion", + year = "1993", + publisher = "Addison-Wesley", + address = "Reading, Massachusetts" +} + +@misc{knuthwebsite, + author = "Donald Knuth", + title = "Knuth: Computers and Typesetting", + url = "http://www-cs-faculty.stanford.edu/\~{}uno/abcde.html" +} +\ No newline at end of file diff --git a/doc/flows/definitions.tex b/doc/flows/protocol/definitions.tex diff --git a/doc/flows/main.tex b/doc/flows/protocol/main.tex diff --git a/doc/flows/timechart.pdf b/doc/flows/timechart.pdf Binary files differ. diff --git a/doc/flows/timechart.ods b/doc/flows/timechart/timechart.ods Binary files differ. diff --git a/doc/flows/timechart/timechart.pdf b/doc/flows/timechart/timechart.pdf Binary files differ.
