diff options
Diffstat (limited to 'doc')
77 files changed, 14064 insertions, 99 deletions
diff --git a/doc/.gitignore b/doc/.gitignore index d4fa2be60..f7b3a16cd 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -1,7 +1,6 @@ *.aux *.dvi *.log -*.pdf *.out *.snm *.toc @@ -25,3 +24,6 @@ taler-exchange.html taler-exchange.fn taler-exchange.cp taler-exchange.auxtaler-exchange.cps +cbdc-es/cbdc-es.pdf +cbdc-it/cbdc-it.pdf +audit/response-202109.pdf diff --git a/doc/Makefile.am b/doc/Makefile.am index 70f10c34f..ca973a1a5 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -9,37 +9,56 @@ infoimagedir = $(infodir)/images man_MANS = \ prebuilt/man/taler.conf.5 \ prebuilt/man/taler-config.1 \ + prebuilt/man/taler-aggregator-benchmark.1 \ prebuilt/man/taler-auditor.1 \ prebuilt/man/taler-auditor-dbinit.1 \ - prebuilt/man/taler-auditor-exchange.1 \ prebuilt/man/taler-auditor-httpd.1 \ prebuilt/man/taler-auditor-offline.1 \ prebuilt/man/taler-auditor-sign.1 \ prebuilt/man/taler-auditor-sync.1 \ - prebuilt/man/taler-bank-transfer.1 \ + prebuilt/man/taler-bank-benchmark.1 \ prebuilt/man/taler-exchange-aggregator.1 \ prebuilt/man/taler-exchange-benchmark.1 \ prebuilt/man/taler-exchange-closer.1 \ + prebuilt/man/taler-exchange-dbconfig.1 \ prebuilt/man/taler-exchange-dbinit.1 \ + prebuilt/man/taler-exchange-drain.1 \ + prebuilt/man/taler-exchange-expire.1 \ prebuilt/man/taler-exchange-httpd.1 \ + prebuilt/man/taler-exchange-kyc-aml-pep-trigger.1 \ + prebuilt/man/taler-exchange-kyc-tester.1 \ prebuilt/man/taler-exchange-offline.1 \ + prebuilt/man/taler-exchange-router.1\ + prebuilt/man/taler-exchange-secmod-cs.1\ prebuilt/man/taler-exchange-secmod-eddsa.1\ prebuilt/man/taler-exchange-secmod-rsa.1 \ prebuilt/man/taler-exchange-transfer.1\ - prebuilt/man/taler-exchange-wirewatch.1 \ prebuilt/man/taler-exchange-wire-gateway-client.1\ + prebuilt/man/taler-exchange-wirewatch.1 \ + prebuilt/man/taler-fakebank-run.1 \ prebuilt/man/taler-helper-auditor-aggregation.1 \ prebuilt/man/taler-helper-auditor-coins.1\ prebuilt/man/taler-helper-auditor-deposits.1\ + prebuilt/man/taler-helper-auditor-purses.1\ prebuilt/man/taler-helper-auditor-reserves.1\ - prebuilt/man/taler-helper-auditor-wire.1 + prebuilt/man/taler-helper-auditor-wire.1 \ + prebuilt/man/taler-terms-generator.1 \ + prebuilt/man/taler-unified-setup.1 info_TEXINFOS = \ prebuilt/texinfo/taler-auditor.texi \ - prebuilt/texinfo/taler-bank.texi \ prebuilt/texinfo/taler-developer-manual.texi \ prebuilt/texinfo/taler-exchange.texi +install-info-local: + @echo " $(MKDIR_P) '$(DESTDIR)$(infodir)/taler-auditor-figures'"; \ + $(MKDIR_P) "$(DESTDIR)$(infodir)/taler-auditor-figures" || exit 1; \ + @echo " $(MKDIR_P) '$(DESTDIR)$(infodir)/taler-exchange-figures'"; \ + $(MKDIR_P) "$(DESTDIR)$(infodir)/taler-exchange-figures" || exit 1; \ + echo " $(INSTALL_DATA) auditor-db.png replication.png '$(DESTDIR)$(infodir)/taler-auditor-figures'"; \ + $(INSTALL_DATA) '$(srcdir)/prebuilt/texinfo/taler-auditor-figures/auditor-db.png' '$(srcdir)/prebuilt/texinfo/taler-auditor-figures/replication.png' "$(DESTDIR)$(infodir)/taler-auditor-figures" || exit 1; + echo " $(INSTALL_DATA) kyc-process.png exchange-db.png '$(DESTDIR)$(infodir)/taler-exchange-figures'"; \ + $(INSTALL_DATA) '$(srcdir)/prebuilt/texinfo/taler-exchange-figures/kyc-process.png' '$(srcdir)/prebuilt/texinfo/taler-exchange-figures/exchange-db.png' "$(DESTDIR)$(infodir)/taler-exchange-figures" || exit 1; EXTRA_DIST = \ $(man_MANS) \ @@ -47,16 +66,5 @@ EXTRA_DIST = \ $(info_TEXINFOS) \ prebuilt/texinfo/taler-auditor-figures/auditor-db.png \ prebuilt/texinfo/taler-auditor-figures/replication.png \ - prebuilt/texinfo/taler-bank-figures/arch-api.png \ - prebuilt/texinfo/taler-bank-figures/auditor-db.png \ - prebuilt/texinfo/taler-bank-figures/exchange-db.png \ - prebuilt/texinfo/taler-bank-figures/merchant-db.png \ - prebuilt/texinfo/taler-bank-figures/replication.png \ - prebuilt/texinfo/taler-developer-manual-figures/arch-api.png \ - prebuilt/texinfo/taler-developer-manual-figures/auditor-db.png \ - prebuilt/texinfo/taler-developer-manual-figures/exchange-db.png \ - prebuilt/texinfo/taler-developer-manual-figures/merchant-db.png \ - prebuilt/texinfo/taler-developer-manual-figures/replication.png \ - prebuilt/texinfo/taler-exchange-figures/auditor-db.png \ - prebuilt/texinfo/taler-exchange-figures/exchange-db.png\ - prebuilt/texinfo/taler-exchange-figures/replication.png + prebuilt/texinfo/taler-exchange-figures/kyc-process.png \ + prebuilt/texinfo/taler-exchange-figures/exchange-db.png diff --git a/doc/cbdc-it/agsm-mod.bst b/doc/cbdc-it/agsm-mod.bst new file mode 100644 index 000000000..ac1bbd052 --- /dev/null +++ b/doc/cbdc-it/agsm-mod.bst @@ -0,0 +1,1375 @@ +% BibTeX standard bibliography style `agsm' (one of the harvard family) + % version 0.99a for BibTeX versions 0.99a or later, LaTeX version 2.09. + % Copyright (C) 1991, all rights reserved. + % Copying of this file is authorized only if either + % (1) you make absolutely no changes to your copy, including name, or + % (2) if you do make changes, you name it something other than + % btxbst.doc, plain.bst, unsrt.bst, alpha.bst, abbrv.bst, agsm.bst, + % dcu.bst or kluwer.bst. + % This restriction helps ensure that all standard styles are identical. + % The file harvard.tex has the documentation for this style. + +% ACKNOWLEDGEMENT: +% This document is a modified version of alpha.bst to which it owes much of +% its functionality. + +% AUTHOR +% Peter Williams, Key Centre for Design Quality, Sydney University +% e-mail: peterw@archsci.arch.su.oz.au + +ENTRY + { address + author + booktitle + chapter + edition + editor + howpublished + institution + journal + key + month + note + number + organization + pages + publisher + school + series + title + type + URL + volume + year + } + { field.used etal.allowed etal.required} %%%XXX change + { extra.label sort.label list.year } + +INTEGERS { output.state before.all mid.sentence after.sentence after.block } + +FUNCTION {init.state.consts} +{ #0 'before.all := + #1 'mid.sentence := + #2 'after.sentence := + #3 'after.block := +} + +STRINGS { s t f } + +FUNCTION {output.nonnull} +{ 's := + output.state mid.sentence = + { ", " * write$ } + { output.state after.block = + { add.period$ write$ + newline$ + "\newblock " write$ + } + { output.state before.all = + 'write$ + { add.period$ " " * write$ } + if$ + } + if$ + mid.sentence 'output.state := + } + if$ + s +} + +FUNCTION {output} +{ duplicate$ empty$ + 'pop$ + 'output.nonnull + if$ +} + +FUNCTION {output.check} +{ 't := + duplicate$ empty$ + { pop$ "empty " t * " in " * cite$ * warning$ } + 'output.nonnull + if$ +} + +FUNCTION {item.check} +{ 't := + empty$ + { "empty " t * " in " * cite$ * warning$ } + { skip$ } + if$ +} + +FUNCTION {fin.entry} +{ add.period$ + write$ + newline$ +} + +FUNCTION {new.block} +{ output.state before.all = + 'skip$ + { after.block 'output.state := } + if$ +} + +FUNCTION {not} +{ { #0 } + { #1 } + if$ +} + +FUNCTION {and} +{ 'skip$ + { pop$ #0 } + if$ +} + +FUNCTION {or} +{ { pop$ #1 } + 'skip$ + if$ +} + +FUNCTION {field.or.null} +{ duplicate$ empty$ + { pop$ "" } + 'skip$ + if$ +} + +FUNCTION {emphasize} +{ duplicate$ empty$ + { pop$ "" } + { "{\em " swap$ * "}" * } + if$ +} + +FUNCTION {embolden} +{ duplicate$ empty$ + { pop$ "" } + { "{\bf " swap$ * "}" * } + if$ +} + +%%ORIGINAL KEPT HERE FOR REFERENCE: +%%FUNCTION {quote} +%%{ duplicate$ empty$ +%% { pop$ "" } +%% { "`" swap$ * "'" * } +%% if$ +%%} + +%%USE GUILLEMETS +FUNCTION {quote} +{ duplicate$ empty$ + { pop$ "" } + { "«" swap$ * "»" * } + if$ +} +%%END USE GUILLEMETS + +FUNCTION {write.url} +{ URL empty$ + { skip$ } + { "\newline\harvardurl{" URL * "}" * write$ newline$ } + if$ +} + +INTEGERS { nameptr namesleft numnames } + +FUNCTION {format.names} +{ 's := + 'f := + #1 'nameptr := + s num.names$ 'numnames := + numnames 'namesleft := + { namesleft #0 > } + { s nameptr f format.name$ 't := + nameptr #1 > + { namesleft #1 > + { ", " * t * } + { t "others" = + { " et~al." * } + { " \harvardand\ " * t * } + if$ + } + if$ + } + 't + if$ + nameptr #1 + 'nameptr := + namesleft #1 - 'namesleft := + } + while$ +} + +FUNCTION {format.authors} +{ author empty$ + { "" } + { "{vv~}{ll}{, jj}{, f.}" author format.names } + if$ +} + +FUNCTION {format.editors} +{ editor empty$ + { "" } + { "{vv~}{ll}{, jj}{, f.}" editor format.names + editor num.names$ #1 > + { ", eds" * } + { ", ed." * } + if$ + } + if$ +} + +FUNCTION {format.editors.reverse} +{ editor empty$ + { "" } + { "{f.~}{vv~}{ll}{, jj}" editor format.names + editor num.names$ #1 > + { ", eds" * } + { ", ed." * } + if$ + } + if$ +} + +%%ORIGINAL KEPT HERE FOR REFERENCE: +%%FUNCTION {format.title} +%%{ title empty$ +%% { "" } +%% { title "t" change.case$ } +%% if$ +%%} + +%%REMOVE SINGLE QUOTES +FUNCTION {format.title} +{ title empty$ + { "" } + { title "t" change.case$ quote} + if$ +} +%%END REMOVE SINGLE QUOTES + +FUNCTION {n.dashify} +{ 't := + "" + { t empty$ not } + { t #1 #1 substring$ "-" = + { t #1 #2 substring$ "--" = not + { "--" * + t #2 global.max$ substring$ 't := + } + { { t #1 #1 substring$ "-" = } + { "-" * + t #2 global.max$ substring$ 't := + } + while$ + } + if$ + } + { t #1 #1 substring$ * + t #2 global.max$ substring$ 't := + } + if$ + } + while$ +} + +FUNCTION {format.btitle} +{ title emphasize +} + +FUNCTION {tie.or.space.connect} +{ duplicate$ text.length$ #3 < + { "~" } + { " " } + if$ + swap$ * * +} + +FUNCTION {either.or.check} +{ empty$ + 'pop$ + { "can't use both " swap$ * " fields in " * cite$ * warning$ } + if$ +} + +FUNCTION {format.bvolume} +{ volume empty$ + { "" } + { "Vol." volume tie.or.space.connect + series empty$ + 'skip$ + { " of " * series emphasize * } + if$ + "volume and number" number either.or.check + } + if$ +} + +FUNCTION {format.number.series} +{ volume empty$ + { number empty$ + { series field.or.null } + { output.state mid.sentence = + { "number" } + { "Number" } + if$ + number tie.or.space.connect + series empty$ + { "there's a number but no series in " cite$ * warning$ } + { " {\em in} " * series quote * } + if$ + } + if$ + } + { "" } + if$ +} + +FUNCTION {format.edition} +{ edition empty$ + { "" } + { output.state mid.sentence = + { edition "l" change.case$ " edn" * } + { edition "t" change.case$ " edn" * } + if$ + } + if$ +} + +INTEGERS { multiresult } + +FUNCTION {multi.page.check} +{ 't := + #0 'multiresult := + { multiresult not + t empty$ not + and + } + { t #1 #1 substring$ + duplicate$ "-" = + swap$ duplicate$ "," = + swap$ "+" = + or or + { #1 'multiresult := } + { t #2 global.max$ substring$ 't := } + if$ + } + while$ + multiresult +} + +FUNCTION {format.pages} +{ pages empty$ + { "" } + { pages multi.page.check + { "pp.~" pages n.dashify * } + { "p.~" pages * } + if$ + } + if$ +} + +FUNCTION {format.vol.num.pages} +{ volume embolden field.or.null + number empty$ + 'skip$ + { "(" number * ")" * * + volume empty$ + { "there's a number but no volume in " cite$ * warning$ } + 'skip$ + if$ + } + if$ + pages empty$ + 'skip$ + { duplicate$ empty$ + { pop$ format.pages } + { ",~" * pages n.dashify * } + if$ + } + if$ +} + +FUNCTION {format.chapter.pages} +{ chapter empty$ + 'format.pages + { type empty$ + { "chapter" } + { type "l" change.case$ } + if$ + chapter tie.or.space.connect + pages empty$ + 'skip$ + { ", " * format.pages * } + if$ + } + if$ +} + +%%REMOVE ITALICS FROM WORD "IN" +FUNCTION {format.in.ed.booktitle} +{ booktitle empty$ + { "" } + { editor empty$ + %%{ "{\em in} " booktitle * } ORIGINAL + { "{in} " booktitle * } + %%{ "{\em in} " format.editors.reverse * ", " * booktitle * } ORIGINAL + { "{in} " format.editors.reverse * ", " * booktitle * } + if$ + } + if$ +} +%%END REMOVE ITALICS FROM WORD "IN" + +FUNCTION {empty.misc.check} +{ author empty$ title empty$ howpublished empty$ + month empty$ year empty$ note empty$ + and and and and and + key empty$ not and + { "all relevant fields are empty in " cite$ * warning$ } + 'skip$ + if$ +} + +FUNCTION {format.thesis.type} +{ type empty$ + 'skip$ + { pop$ + type "t" change.case$ + } + if$ +} + +FUNCTION {format.tr.number} +{ type empty$ + { "Technical Report" } + 'type + if$ + number empty$ + { "t" change.case$ } + { number tie.or.space.connect } + if$ +} + +FUNCTION {format.article.crossref} +{ key empty$ + { journal empty$ + { "need key or journal for " cite$ * " to crossref " * crossref * + warning$ + "" + } + { "in {\em " journal * "\/} \cite{" * crossref * "}" *} + if$ + } + { "{\em in} \citeasnoun{" crossref * "}" * } + if$ + +} + +FUNCTION {format.book.crossref} +{ volume empty$ + { "empty volume in " cite$ * "'s crossref of " * crossref * warning$ + "in " + } + { "Vol." volume tie.or.space.connect + " of " * + } + if$ + editor empty$ + editor field.or.null author field.or.null = + or + { key empty$ + { series empty$ + { "need editor, key, or series for " cite$ * " to crossref " * + crossref * warning$ + "" * + } + { "{\em " * series * "\/} \cite{" * crossref * "}" *} + if$ + } + { " \citeasnoun{" * crossref * "}" * } + if$ + } + { " \citeasnoun{" * crossref * "}" * } + if$ +} + +FUNCTION {format.incoll.inproc.crossref} +{ editor empty$ + editor field.or.null author field.or.null = + or + { key empty$ + { booktitle empty$ + { "need editor, key, or booktitle for " cite$ * " to crossref " * + crossref * warning$ + "" + } + { "in {\em " booktitle * "\/}" * " \cite{" * crossref * "}" *} + + if$ + } + { "{\em in} \citeasnoun{" crossref * "}" * } + if$ + } + { "{\em in} \citeasnoun{" crossref * "}" * } + if$ + +} + +INTEGERS { len } + +FUNCTION {chop.word} +{ 's := + 'len := + s #1 len substring$ = + { s len #1 + global.max$ substring$ } + 's + if$ +} + +INTEGERS { ind tsslen } + +STRINGS { tss ret rss istr } + +FUNCTION {replace.substring}{ + 'rss := + 'tss := + 'istr := + "" 'ret := + tss text.length$ 'tsslen := + #1 'ind := + { istr ind tsslen substring$ "" = not } + { istr ind tsslen substring$ tss = + { ret rss * 'ret := + ind tsslen + 'ind := + } + { ret istr ind #1 substring$ * 'ret := + ind #1 + 'ind := + } + if$ + } + while$ + ret +} + +FUNCTION {format.lab.names.abbr} +{ 's := + s num.names$ 'numnames := + numnames #1 > + { numnames #2 > + { s #1 "{vv~}{ll}" format.name$ " et~al." * } + { s #2 "{ff }{vv }{ll}{ jj}" format.name$ "others" = + { s #1 "{vv~}{ll}" format.name$ " et~al." * } + { s #1 "{vv~}{ll}" format.name$ " \harvardand\ " * + s #2 "{vv~}{ll}" format.name$ * + } + if$ + } + if$ + } + { s #1 "{vv~}{ll}" format.name$ } + if$ +} + +FUNCTION {format.lab.names.full} +{ 's := + #1 'nameptr := + s num.names$ 'numnames := + numnames 'namesleft := + { namesleft #0 > } + { s nameptr "{vv~}{ll}" format.name$ 't := + nameptr #1 > + { namesleft #1 > + { ", " * t * } + { t "others" = + { " et~al." * } + { " \harvardand\ " * t * } + if$ + } + if$ + } + 't + if$ + nameptr #1 + 'nameptr := + namesleft #1 - 'namesleft := + } + while$ +} + +INTEGERS { author.field editor.field organization.field title.field key.field } + +FUNCTION {init.field.constants} +{ #0 'author.field := + #1 'editor.field := + #2 'organization.field := + #3 'title.field := + #4 'key.field := +} + +FUNCTION {make.list.label} +{ author.field field.used = + { format.authors } + { editor.field field.used = + { format.editors } + { organization.field field.used = + { "The " #4 organization chop.word #3 text.prefix$ } + { title.field field.used = + { format.btitle } + { key.field field.used = + { key #3 text.prefix$ } + { "Internal error :001 on " cite$ * " label" * warning$ } + if$ + } + if$ + } + if$ + } + if$ + } + if$ +} + +FUNCTION {make.full.label} +{ author.field field.used = + { author format.lab.names.full } + { editor.field field.used = + { editor format.lab.names.full } + { organization.field field.used = + { "The " #4 organization chop.word #3 text.prefix$ } + { title.field field.used = + { format.btitle } + { key.field field.used = + { key #3 text.prefix$ } + { "Internal error :001 on " cite$ * " label" * warning$ } + if$ + } + if$ + } + if$ + } + if$ + } + if$ +} + +FUNCTION {make.abbr.label} %%%XXX change +{ + etal.allowed + { author.field field.used = + { author format.lab.names.abbr } + { editor.field field.used = + { editor format.lab.names.abbr } + { organization.field field.used = + { "The " #4 organization chop.word #3 text.prefix$ } + { title.field field.used = + { format.btitle } + { key.field field.used = + { key #3 text.prefix$ } + {"Internal error :001 on " cite$ * " label" * warning$ } + if$ + } + if$ + } + if$ + } + if$ + } + if$ + } + { make.full.label } + if$ +} + +FUNCTION {output.bibitem} +{ newline$ + etal.allowed %%%XXX change + etal.required + and + { + "\harvarditem[" write$ + make.abbr.label write$ + "]{" write$ + } + { + "\harvarditem{" write$ + } + if$ + make.full.label write$ + "}{" write$ + list.year write$ + "}{" write$ + cite$ write$ + "}" write$ + newline$ + "" + before.all 'output.state := +} + +FUNCTION {list.label.output} +{ make.list.label " " * write$ +} + +FUNCTION {article} +{ output.bibitem + list.label.output + " \harvardyearleft " list.year * "\harvardyearright " * output.nonnull + author "author" item.check + title.field field.used = + { skip$ } + { format.title "title" output.check } + if$ + crossref missing$ + { journal emphasize "journal" duplicate$ item.check + " " * format.vol.num.pages * output + } + { format.article.crossref output.nonnull + format.pages output + } + if$ + new.block + note output + fin.entry + write.url +} + +FUNCTION {book} +{ output.bibitem + list.label.output + " \harvardyearleft " list.year * "\harvardyearright " * output.nonnull + author empty$ + { editor "author and editor" item.check } + { crossref missing$ + { "author and editor" editor either.or.check } + 'skip$ + if$ + } + if$ + title.field field.used = + { skip$ } + { format.btitle "title" output.check } + if$ + crossref missing$ + { format.bvolume output + format.number.series output + format.edition output + publisher "publisher" output.check + address output + } + { format.book.crossref output.nonnull + format.edition output + } + if$ + new.block + note output + fin.entry + write.url +} + +FUNCTION {booklet} +{ output.bibitem + list.label.output + " \harvardyearleft " list.year * "\harvardyearright " * output.nonnull + title.field field.used = + { skip$ } + { format.title "title" output.check } + if$ + howpublished output + address output + new.block + note output + fin.entry + write.url +} + +FUNCTION {inbook} +{ output.bibitem + list.label.output + " \harvardyearleft " list.year * "\harvardyearright " * output.nonnull + author empty$ + { editor "author and editor" item.check } + { crossref missing$ + { "author and editor" editor either.or.check } + 'skip$ + if$ + } + if$ + title.field field.used = + { skip$ } + { format.btitle "title" output.check } + if$ + crossref missing$ + { format.bvolume output + format.number.series output + format.edition output + publisher "publisher" output.check + address output + } + { format.book.crossref output.nonnull + format.edition output + } + if$ + format.chapter.pages "chapter and pages" output.check + new.block + note output + fin.entry + write.url +} + +FUNCTION {incollection} +{ output.bibitem + list.label.output + " \harvardyearleft " list.year * "\harvardyearright " * output.nonnull + title.field field.used = + { skip$ } + { format.title "title" output.check } + if$ + author "author" item.check + crossref missing$ + { format.in.ed.booktitle "booktitle" output.check + format.edition output + format.bvolume output + format.number.series output + publisher "publisher" output.check + address output + } + { format.incoll.inproc.crossref output.nonnull + } + if$ + format.chapter.pages output + new.block + note output + fin.entry + write.url +} + +FUNCTION {inproceedings} +{ output.bibitem + list.label.output + " \harvardyearleft " list.year * "\harvardyearright " * output.nonnull + title.field field.used = + { skip$ } + { format.title "title" output.check } + if$ + author "author" item.check + crossref missing$ + { format.in.ed.booktitle "booktitle" output.check + format.bvolume output + format.number.series output + address empty$ + { organization output + publisher output + } + { organization output + publisher output + address output.nonnull + } + if$ + } + { format.incoll.inproc.crossref output.nonnull + } + if$ + format.pages output + new.block + note output + fin.entry + write.url +} + +FUNCTION {conference} { inproceedings } + +FUNCTION {manual} +{ output.bibitem + list.label.output + " \harvardyearleft " list.year * "\harvardyearright " * output.nonnull + title.field field.used = + { skip$ } + { format.btitle "title" output.check } + if$ + format.edition output + author empty$ + { organization empty$ + { address output } + 'skip$ + if$ + } + { organization output + address output + } + if$ + new.block + note output + fin.entry + write.url +} + +FUNCTION {mastersthesis} +{ output.bibitem + list.label.output + " \harvardyearleft " list.year * "\harvardyearright " * output.nonnull + author "author" item.check + title.field field.used = + { skip$ } + { format.title "title" output.check } + if$ + "Master's thesis" format.thesis.type output.nonnull + school "school" output.check + address output + new.block + note output + fin.entry + write.url +} + +FUNCTION {misc} +{ output.bibitem + list.label.output + " \harvardyearleft " list.year * "\harvardyearright " * output.nonnull + title.field field.used = + { skip$ } + { format.title output } + if$ + howpublished output + new.block + note output + fin.entry + write.url + empty.misc.check +} + +FUNCTION {phdthesis} +{ output.bibitem + list.label.output + " \harvardyearleft " list.year * "\harvardyearright " * output.nonnull + author "author" item.check + title.field field.used = + { skip$ } + { title "title" output.check } + if$ + "PhD thesis" format.thesis.type output.nonnull + school "school" output.check + address output + new.block + note output + fin.entry + write.url +} + +FUNCTION {proceedings} +{ output.bibitem + list.label.output + " \harvardyearleft " list.year * "\harvardyearright " * output.nonnull + title.field field.used = + { skip$ } + { format.btitle "title" output.check } + if$ + format.bvolume output + format.number.series output + address empty$ + { editor empty$ + { skip$ } + { organization output + } + if$ + publisher output + } + { editor empty$ + 'skip$ + { organization output } + if$ + publisher output + address output.nonnull + } + if$ + new.block + note output + fin.entry + write.url +} + +FUNCTION {techreport} +{ output.bibitem + list.label.output + " \harvardyearleft " list.year * "\harvardyearright " * output.nonnull + author "author" item.check + title.field field.used = + { skip$ } + { format.title "title" output.check } + if$ + format.tr.number output.nonnull + institution "institution" output.check + address output + new.block + note output + fin.entry + write.url +} + +FUNCTION {unpublished} +{ output.bibitem + list.label.output + " \harvardyearleft " list.year * "\harvardyearright " * output.nonnull + author "author" item.check + title.field field.used = + { skip$ } + { format.title "title" output.check } + if$ + new.block + note "note" output.check + fin.entry + write.url +} + +FUNCTION {default.type} { misc } + +MACRO {jan} {"January"} + +MACRO {feb} {"February"} + +MACRO {mar} {"March"} + +MACRO {apr} {"April"} + +MACRO {may} {"May"} + +MACRO {jun} {"June"} + +MACRO {jul} {"July"} + +MACRO {aug} {"August"} + +MACRO {sep} {"September"} + +MACRO {oct} {"October"} + +MACRO {nov} {"November"} + +MACRO {dec} {"December"} + +MACRO {acmcs} {"ACM Computing Surveys"} + +MACRO {acta} {"Acta Informatica"} + +MACRO {cacm} {"Communications of the ACM"} + +MACRO {ibmjrd} {"IBM Journal of Research and Development"} + +MACRO {ibmsj} {"IBM Systems Journal"} + +MACRO {ieeese} {"IEEE Transactions on Software Engineering"} + +MACRO {ieeetc} {"IEEE Transactions on Computers"} + +MACRO {ieeetcad} + {"IEEE Transactions on Computer-Aided Design of Integrated Circuits"} + +MACRO {ipl} {"Information Processing Letters"} + +MACRO {jacm} {"Journal of the ACM"} + +MACRO {jcss} {"Journal of Computer and System Sciences"} + +MACRO {scp} {"Science of Computer Programming"} + +MACRO {sicomp} {"SIAM Journal on Computing"} + +MACRO {tocs} {"ACM Transactions on Computer Systems"} + +MACRO {tods} {"ACM Transactions on Database Systems"} + +MACRO {tog} {"ACM Transactions on Graphics"} + +MACRO {toms} {"ACM Transactions on Mathematical Software"} + +MACRO {toois} {"ACM Transactions on Office Information Systems"} + +MACRO {toplas} {"ACM Transactions on Programming Languages and Systems"} + +MACRO {tcs} {"Theoretical Computer Science"} + +READ + +EXECUTE {init.field.constants} + +FUNCTION {sortify} +{ purify$ + "l" change.case$ +} + +FUNCTION {sortify.names} +{ " \harvardand\ " " " replace.substring + " et~al." " zzz" replace.substring + sortify +} + +FUNCTION {author.key.label} +{ author empty$ + { key empty$ + { title.field 'field.used := } + { key.field 'field.used := } + if$ + } + { author.field 'field.used := } + if$ +} + +FUNCTION {author.editor.key.label} +{ author empty$ + { editor empty$ + { key empty$ + { title.field 'field.used := } + { key.field 'field.used := } + if$ + } + { editor.field 'field.used := } + if$ + } + { author.field 'field.used := } + if$ +} + +FUNCTION {author.key.organization.label} +{ author empty$ + { key empty$ + { organization empty$ + { title.field 'field.used := } + { organization.field 'field.used := } + if$ + } + { key.field 'field.used := } + if$ + } + { author.field 'field.used := } + if$ +} + +FUNCTION {editor.key.organization.label} +{ editor empty$ + { key empty$ + { organization empty$ + { title.field 'field.used := } + { organization.field 'field.used := } + if$ + } + { key.field 'field.used := } + if$ + } + { editor.field 'field.used := } + if$ +} + +FUNCTION {sort.format.title} +{ 't := + "A " #2 + "An " #3 + "The " #4 t chop.word + chop.word + chop.word + sortify + #1 global.max$ substring$ +} + +FUNCTION {calc.label} %%%XXX change +{ make.abbr.label + title.field field.used = + { sort.format.title } + { sortify.names } + if$ + year field.or.null purify$ #-1 #4 substring$ sortify + * + 'sort.label := +} + +FUNCTION {preliminaries} %%%XXX change +{ type$ "book" = + type$ "inbook" = + or + 'author.editor.key.label + { type$ "proceedings" = + 'editor.key.organization.label + { type$ "manual" = + 'author.key.organization.label + 'author.key.label + if$ + } + if$ + } + if$ + author.field field.used = %%%XXX change + { + author num.names$ #2 > + { #1 } + { #0 } + if$ + 'etal.required := + } + { + editor.field field.used = + { + editor num.names$ #2 > + { #1 } + { #0 } + if$ + } + { #0 } + if$ + 'etal.required := + } + if$ + #1 'etal.allowed := +} + +FUNCTION {first.presort} +{ calc.label + sort.label + title.field field.used = + { skip$ } + { " " + * + make.list.label sortify.names + * + " " + * + title field.or.null + sort.format.title + * + } + if$ + #1 entry.max$ substring$ + 'sort.key$ := +} + +ITERATE {preliminaries} + +ITERATE {first.presort} + +SORT + +STRINGS { last.sort.label next.extra last.full.label} + +INTEGERS { last.extra.num last.etal.allowed} + +FUNCTION {initialize.confusion} +{ #0 int.to.chr$ 'last.sort.label := + #0 int.to.chr$ 'last.full.label := + #1 'last.etal.allowed := +} + +FUNCTION {confusion.pass} +{ last.sort.label sort.label = + { last.etal.allowed + { last.full.label make.full.label sortify.names = + { skip$ } + { #0 'etal.allowed := + #0 'last.etal.allowed := + } + if$ + } + { #0 'etal.allowed := } + if$ + } + { sort.label 'last.sort.label := + make.full.label sortify.names 'last.full.label := + #1 'last.etal.allowed := + } + if$ +} + +EXECUTE {initialize.confusion} + +ITERATE {confusion.pass} + +EXECUTE {initialize.confusion} + +REVERSE {confusion.pass} + +FUNCTION {initialize.last.extra.num} +{ #0 int.to.chr$ 'last.sort.label := + "" 'next.extra := + #0 'last.extra.num := +} + +FUNCTION {forward.pass} +{ last.sort.label sort.label = + { last.extra.num #1 + 'last.extra.num := + last.extra.num int.to.chr$ 'extra.label := + } + { "a" chr.to.int$ 'last.extra.num := + "" 'extra.label := + sort.label 'last.sort.label := + } + if$ +} + +FUNCTION {reverse.pass} +{ next.extra "b" = + { "a" 'extra.label := } + 'skip$ + if$ + year empty$ + { "n.d." extra.label emphasize * 'list.year := } + { year extra.label emphasize * 'list.year := } + if$ + extra.label 'next.extra := +} + +ITERATE {first.presort} + +SORT + +EXECUTE {initialize.last.extra.num} + +ITERATE {forward.pass} + +REVERSE {reverse.pass} + +FUNCTION {second.presort} +{ make.list.label + title.field field.used = + { sort.format.title } + { sortify.names } + if$ + " " + * + list.year field.or.null sortify + * + " " + * + title.field field.used = + { skip$ } + { title field.or.null + sort.format.title + * + } + if$ + #1 entry.max$ substring$ + 'sort.key$ := +} + +ITERATE {second.presort} + +SORT + +FUNCTION {begin.bib} +{ preamble$ empty$ + 'skip$ + { preamble$ write$ newline$ } + if$ + "\begin{thebibliography}{xx}" write$ newline$ +} + +EXECUTE {begin.bib} + +EXECUTE {init.state.consts} + +ITERATE {call.type$} + +FUNCTION {end.bib} +{ newline$ + "\end{thebibliography}" write$ newline$ +} + +EXECUTE {end.bib} diff --git a/doc/cbdc-it/cbdc-it.bib b/doc/cbdc-it/cbdc-it.bib new file mode 100644 index 000000000..639bb0c45 --- /dev/null +++ b/doc/cbdc-it/cbdc-it.bib @@ -0,0 +1,561 @@ +%% To be used with modified bibliography style agsm-mod + hyperref + natbib + italian babel + +@article{Adrian, + author = {Adrian, Tobias and Mancini-Griffoli}, + year = {2019}, + title = {{The Rise of Digital Money}}, + journal = {IMF Fintech Note}, + volume = {19/01}, +} + +@article{Agarwal, + author = {Agarwal, Ruchir and Miles S. Kimball}, + year = {2019}, + title = {{Enabling Deep Negative Rates to Fight Recessions: A Guide}}, + journal = {IMF Working Paper}, + volume = {19/84}, +} + + +@article{Agur, + author = {Agur, Itai and Anil Ari and Giovanni Dell'Ariccia}, + year = {2019}, + title = {{Designing Central Bank Digital Currencies}}, + journal = {IMF Working Paper}, + volume = {19/252}, +} + +@article{Allen, + author = {Allen, Sarah and Srđjan Čapkun and Ittay Eyal and Giulia Fanti and Bryan A. Ford and James Grimmelmann and Ari Juels and Kari Kostiainen and Sarah Meiklejohn and Andrew Miller and Eswar Prasad and Karl Wüst and Fan Zhang}, + year = {2020}, + title = {{Design Choices for Central Bank Digital Currency: Policy and Technical Considerations}}, + journal = {NBER Working Paper}, + volume = {27634}, +} + +@article{Alves, + author = {Alves, Tiago and Don Felton}, + year = {2004}, + title = {TrustZone: Integrated hardware and software security}, + journal = {ARM IQ}, + volume = {3}, + number = {4}, + pages = {18--24}, +} + +@article{AuerBoehme, + author = {Auer, Raphael and Rainer Böhme}, + year = {2020}, + title = {The technology of retail central bank digital currency}, + journal = {BIS Quarterly Review}, + month = {March}, + pages = {85--96}, +} + +@article{AuerCornelli, + author = {Auer, Raphael and Giulio Cornelli and Jon Frost}, + year = {2020}, + title = {{Taking stock: ongoing retail CBDC projects}}, + journal = {BIS Quarterly Review}, + month = {March}, + pages = {97--98}, +} + +@booklet{BIS, + author = {{Bank for International Settlements}}, + year = {2018}, + title = {{Central Bank Digital Currencies. Joint Report of the Committee on Payments and Market Infrastructures and Markets Committee}}, +} + +@booklet{BoE, + author = {{Bank of England}}, + year = {2020}, + title = {{Central Bank Digital Currency: Opportunities, Challenges and Design. Discussion Paper}}, + month = {March}, +} + +@article{Baiocchi, + author = {Baiocchi, Giovanni and Walter Distaso}, + year = {2003}, + title = {{GRETL: Econometric Software for the GNU Generation}}, + journal = {Journal of Applied Econometrics}, + volume = {18}, + pages = {105-110}, +} + +@article{Bech, + author = {Bech, Morten and Rodney Garratt}, + year = {2017}, + title = {Central bank cryptocurrencies}, + journal = {BIS Quarterly Review}, + month = {September}, + pages = {55--70}, +} + +@article{Berentsen, + author = {Berentsen, Aleksander and Fabian Schär}, + year = {2018}, + title = {{The Case for Central Bank Electronic Money and the Non-case for Central Bank Cryptocurrencies}}, + journal = {Federal Reserve Bank of St. Louis Review}, + volume = {100}, + number = {2}, + pages = {97--106}, +} + +@article{Bernstein2020, + author = {Bernstein, Daniel J. and Tanja Lange}, + year = {2020}, + title = {{eBACS: ECRYPT Benchmarking of Cryptographic Systems}}, + url = {\url{https://bench.cr.yp.to}, consultato il 17 marzo 2020}, +} + +@article{Bernstein2012, + author = {Bernstein, Daniel J. and Niels Duif and Tanja Lange and Peter Schwabe and Bo-Yin Yang}, + year = {2012}, + title = {High-speed high-security signatures}, + journal = {Journal of Cryptographic Engineering}, + volume = {2}, + pages = {77--89}, +} + +@InCollection{Bindseil, + author = {Bindseil, Ulrich}, + year = {2020}, + title = {{Tiered CBDC and the financial system}}, + publisher = {European Central Bank}, + series = {ECB Working Paper}, + number = {2351}, + month = {January}, +} + +@article{Boar, + author = {Boar, Codruta and Henry Holden and Amber Wadsworth}, + year = {2020}, + title = {Impending arrival - a sequel to the survey on central bank digital currency}, + journal = {BIS Papers}, + volume = {107}, +} + +@article{Boneh, + author = {Boneh, Dan}, + year = {1999}, + title = {{Twenty Years of Attacks on the RSA Cryptosystem}}, + journal = {Notices of the AMS}, + volume = {42}, + number = {2}, + pages = {202--213}, +} + +@InCollection{Bordo, + author = {Bordo, Michael D. and Andrew T. Levin}, + year = {2017}, + title = {Central bank digital currency and the future of monetary policy}, + publisher = {National Bureau of Economic Research}, + series = {NBER Working Paper Series}, + number = {23711}, +} + +@article{Brunnermeier, + author = {Brunnermeier, Markus and Dirk Niepelt}, + year = {2019}, + title = {{On the Equivalence of Private and Public Money}}, + journal = {Journal of Monetary Economics}, + volume = {106}, + pages = {27--41}, +} + +@article{Buiter, + author = {Buiter, Willem H. and Nikolaos Panigirtzoglou}, + year = {2003}, + title = {{Overcoming the Zero Bound on Nominal Interest Rates with Negative Interest on Currency: Gesell's Solution}}, + journal = {The Economic Journal}, + volume = {113}, + number = {490}, + pages = {723--746}, +} + +@InCollection{Bullmann, + author = {Bullmann, Dirk and Jonas Klemm and Andrea Pinna}, + year = {2019}, + title = {In search for stability in crypto-assets: are stablecoins the solution?}, + publisher = {European Central Bank}, + series = {ECB Occasional Paper Series}, + number = {230}, +} + +@inproceedings{Camenisch2007, + author = {Camenisch, Jan and Aanna Lysyanskaya and Mira Meyerovich}, + year = {2007}, + title = {{Endorsed E-Cash}}, + booktitle = {\textit{2007 IEEE Symposium on Security and Privacy (SP'07)}}, + month = {May}, + pages = {101--115}, +} + +@inproceedings{Camenisch2005, + author = {Camenisch, Jan and Susan Hohenberger and Anna Lysyanskaya}, + year = {2005}, + title = {{Compact E-Cash}}, + booktitle = {\textit{Advances in Cryptology -- EUROCRYPT 2005: 24th Annual International Conference on the Theory and Applications of Cryptographic Techniques}}, + address = {Aarhus, Denmark}, + month = {May}, + day = {22-26}, + editor = {Ed. di Ronald Cramer}, + publisher = {Springer-Verlag Berlin Heidelberg}, +} + + + +@inproceedings{Canard, + author = {Canard, Sébastien and Aline Gouget}, + year = {2007}, + title = {Divisible e-cash systems can be truly anonymous}, + booktitle = {\textit{Annual International Conference on the Theory and Applications of Cryptographic Techniques}}, + pages = {482--497}, +} + +@misc{CCC, + author = {{CCC e.V.}}, + year = {2017}, + title = {{Chaos Computer Club hacks e-motor charging stations}}, + howpublished = {34c3}, +} + +@article{Chapman, + author = {Chapman, James and Rodney Garratt and Scott Hendry and Andrew McCormack and Wade McMahon}, + year = {2017}, + title = {{Project Jasper: Are Distributed Wholesale Payment Systems Feasible Yet?}}, + journal = {Financial System Review}, + publisher = {Bank of Canada}, + month = {June}, + pages = {59--69}, +} + +@inproceedings{Chaum1983, + author = {Chaum, David}, + year = {1983}, + title = {Blind signatures for untraceable payments}, + booktitle = {\textit{Advances in Cryptology: Proceedings of Crypto `82}}, + pages = {199--203}, +} + +@inproceedings{Chaum1990, + author = {Chaum, David and Amos Fiat and Moni Naor}, + year = {1990}, + title = {Untraceable electronic cash}, + booktitle = {\textit{Advances in Cryptology: Proceedings of CRYPTO '88}}, + pages = {319--327}, +} + +@inproceedings{Danezis, + author = {Danezis, George and Sarah Meiklejohn}, + year = {2016}, + title = {{Centrally Banked Cryptocurrencies}}, + booktitle = {\textit{23nd Annual Network and Distributed System Security Symposium, NDSS2016}}, + address = {San Diego, California, USA}, + month = {February}, + day = {21--24}, + publisher = {The Internet Society}, +} + +@article{Diffie, + author = {Diffie, Whitfield and Martin Hellmann}, + year = {1976}, + title = {{New Directions in Cryptography}}, + journal = {IEEE Trans. on Inf. Theory, IT-22}, + pages = {644--654}, +} + +@phdthesis{Dold, + author = {Dold, Florian}, + year = {2019}, + title = {{The GNU Taler System: Practical and Provably Secure Electronic Payments. PhD Thesis}}, + school = {University of Rennes 1}, +} + +@article{ECB, + author = {{European Central Bank}}, + year = {2019}, + title = {Exploring anonymity in central bank digital currencies}, + journal = {In Focus}, + number = {4}, + month = {December}, +} + +@inproceedings{Fuchsbauer, + author = {Fuchsbauer, Georg and David Pointcheval and Damien Vergnaud}, + year = {2009}, + title = {Transferable constant-size fair e-cash}, + booktitle = {International Conference on Cryptology and Network Security}, + publisher = {Springer-Verlag Berlin Heidelberg}, + pages = {226--247}, +} + +@inproceedings{Garcia, + author = {Garcia, Flavio and Gerhard de Koning Gans and Ruben Muijrers and Peter van Rossum and Roel Verdult and Ronny Wichers Schreur and Bart Jacobs}, + year = {2008}, + title = {{Dismantling MIFARE Classic}}, + booktitle = {\textit{European Symposium on Research in Computer Security}}, +} + +@article{Garratt, + author = {Garratt, Rod and Michael Lee and Brendan Malone and Antoine Martin}, + year = {2020}, + title = {{Token- or Account-Based? A Digital Currency Can Be Both}}, + journal = {Liberty Street Economics}, + publisher = {Federal Reserve Bank of New York}, + month = {August}, + day = {12}, +} + +@article{Goodfriend, + author = {Goodfriend, Marvin}, + year = {2000}, + title = {{Overcoming the Zero Bound on Interest Rate Policy}}, + journal = {Journal of Money, Credit, and Banking}, + volume = {32}, + number = {4}, + pages = {1007--1035}, +} + +@article{Johnston, + author = {Johnston, Casey}, + year = {2010}, + title = {PS3 hacked through poor cryptography implementation}, + journal = {Ars Technica}, + month = {December}, + day = {30}, +} + +@Misc{Jordan, + note = {Discorso in occasione del 30º anniversario del Centro di scienze economiche (WWZ) e dell’Associazione degli economisti basilesi (VBÖ)}, + author = {Jordan, Thomas J.}, + year = {2019}, + title = {Valute, moneta e token digitali}, + publisher = {University of Basel}, + month = {September}, + howpublished = {\url{https://www.snb.ch/it/mmr/speeches/id/ref_20190905_tjn/source/ref_20190905_tjn.it.pdf}}, +} + +@article{Kahn2009, + author = {Kahn, Charles M. and William Roberds}, + year = {2009}, + title = {{Why Pay? An Introduction to Payments Economics}}, + journal = {Journal of Financial Intermediation}, + number = {18}, + pages = {1--23}, +} + +@article{Kahn2005, + author = {Kahn, Charles M. and James McAndrews and William Roberds}, + year = {2005}, + title = {{Money is Privacy}}, + journal = {International Economic Review}, + volume = {46}, + number = {2}, + pages = {377--399}, +} + +@article{Kasper, + author = {Kasper, Timo and Michael Silbermann and Christof Paar}, + year = {2010}, + title = {All you can eat or breaking a real-world contactless payment system}, + journal = {Financial Cryptography and Data Security, Lecture Notes in Computer Science}, + volume = {6052}, + pages = {343--50}, +} + +@inproceedings{Katzenbeisser, + author = {Katzenbeisser, Stefan and Ünal Kocabaş and Vladimir Rožić and Ahmad-Reza Sadeghi and Ingrid Verbauwhede and Christian Wachsmann}, + year = {2012}, + title = {{PUFs: Myth, Fact or Busted? A Security Evaluation of Physically Unclonable Functions (PUFs) Cast in Silicon}}, + booktitle = {\textit{Cryptographic Hardware and Embedded Systems -- CHES 2012. Lecture Notes in Computer Science}}, + volume = {7428}, + pages = {283--301}, +} + +@book{Keynes, + author = {Keynes, John Maynard}, + year = {1936}, + title = {The General Theory of Employment, Interest and Money}, + publisher = {Macmillan}, +} + +@article{Kiff, + author = {Kiff, John and Jihad Alwazir and Sonja Davidovic and Aquiles Farias and Ashraf Khan and Tanai Khiaonarong and Majid Malaika and Hunter Monroe and Nobu Sugimoto and Hervé Tourpe and Peter Zhou}, + year = {2020}, + title = {{A Survey of Research on Retail Central Bank Digital Currency}}, + journal = {IMF Working Paper}, + volume = {20/104}, +} + +@InCollection{Kumhof, + author = {Kumhof, Michael and Clare Noone}, + year = {2018}, + title = {Central bank digital currencies - design principles and balance sheet implications}, + publisher = {Bank of England}, + series = {Staff Working Paper}, + number = {725}, +} + +@inproceedings{Lapid, + author = {Lapid, Ben and Avishai Wool}, + year = {2018}, + title = {{Cache-Attacks on the ARM TrustZone Implementations of AES-256 and AES-256-GCM via GPU-Based Analysis}}, + booktitle = {\textit{International Conference on Selected Areas in Cryptography. Lecture Notes in Computer Science}}, + volume = {11349}, +} + +@article{Lerner, + author = {Lerner, Josh and Jean Tirole}, + year = {2005}, + title = {{The Scope of Open Source Licensing}}, + journal = {Journal of Law, Economics \& Organization}, + volume = {21}, + pages = {20-56}, +} + +@misc{Libra, + author = {{Libra Association}}, + year = {2020}, + title = {{Libra White Paper v2.0}}, + url = {\url{https://libra.org/en-US/white-paper}}, +} + +@inproceedings{Lim, + author = {Lim, Chae Hoon and Phil Joong Lee}, + year = {1997}, + title = {A key recovery attack on discrete log-based schemes using a prime order subgroup}, + booktitle = {\textit{CRYPTO 1997. Lecture Notes in Computer Science}}, + volume = {1294}, +} + +@InCollection{Lyons, + author = {Lyons, Richard K. and Ganesh Viswanath-Natraj}, + year = {2020}, + title = {{What Keeps Stablecoins Stable?}}, + publisher = {National Bureau of Economic Research}, + series = {NBER Working Paper Series}, + number = {27136}, + month = {May}, +} + +@article{Mancini-Griffoli, + author = {Mancini-Griffoli and Maria Soledad Martinez Peria and Itai Agur and Anil Ari and John Kiff and Adina Popescu and Celine Rochon}, + year = {2018}, + title = {{Casting Light on Central Bank Digital Currency}}, + journal = {IMF Staff Discussion Notes}, + volume = {18/08}, + publisher = {International Monetary Fund}, +} + +@misc{Nakamoto, + author = {Nakamoto, Satoshi}, + year = {2008}, + title = {{Bitcoin: A Peer-to-Peer Electronic Cash System}}, + url = {\url{https://www.bitcoin.com/bitcoin.pdf}}, +} + +@book{Narayanan, + author = {Narayanan, Arvind and Joseph Bonneau and Edward Felten and Andrew Miller and Steven Goldfeder}, + year = {2016}, + title = {Bitcoin and Cryptocurrency Technologies: A Comprehensive Introduction}, + publisher = {Princeton University Press}, +} + +@misc{Niepelt, + author = {Niepelt, Dirk}, + year = {2020}, + title = {Digital money and central bank digital currency: An executive summary for policymakers}, + howpublished = {\url{https://voxeu.org/article/digital-money-and-central-bank-digital-currency-executive-summary}}, +} + +@inproceedings{Okamoto, + author = {Okamoto, Tatsuaki}, + year = {1995}, + title = {{An Efficient Divisible Electronic Cash Scheme}}, + booktitle = {\textit{Advances in Cryptology --- CRYPT0'95: 15th Annual International Cryptology Conference Santa Barbara, California, USA, 27--31 agosto, 1995 Proceedings}}, + editor = {Ed. di Don Coppersmith}, + publisher = {Springer-Verlag Berlin Heidelberg}, + pages = {438--451}, +} + +@article{Pinto, + author = {Pinto, S. and N. Santos}, + year = {2019}, + title = {{Demystifying ARM TrustZone: A Comprehensive Survey}}, + journal = {ACM Computing Surveys}, + volume = {51}, + number = {6}, + month = {January}, + pages = {1--31} +} + +@article{Rivest, + author = {Rivest, Ronald L. and Adi Shamir and Leonard Adleman}, + year = {1978}, + title = {{A Method for Obtaining Digital Signatures and Public Key Cryptosystems}}, + journal = {Comm. ACM}, + volume = {21}, + number = {2}, +} + +@book{Solove, + author = {Solove, Daniel J.}, + year = {2011}, + title = {Nothing to Hide: The false tradeoff between privacy and security}, + publisher = {New Haven \& London: Yale University Press}, +} + +@article{Soukup, + author = {Soukup, Michael and Bruno Muff}, + year = {2007}, + title = {{Die Postcard lässt sich fälschen}}, + journal = {Sonntagszeitung}, + month = {April}, + day = {22}, +} + +@article{Stallman, + author = {Stallman, Richard}, + year = {1985}, + title = {{The GNU manifesto}}, + journal = {Dr. Dobb's Journal of Software Tools}, + volume = {10}, + number = {3}, + pages = {30--35}, +} + +@TechReport{Riksbank, + author = {{Sveriges Riksbank}}, + year = {2020}, + title = {{The Riksbank's e-krona project}}, + month = {February}, + institution = {Sveriges Riksbank}, + url = {\url{https://www.riksbank.se/globalassets/media/rapporter/e-krona/2019/the-riksbanks-e-krona-pilot.pdf}}, +} + +@misc{Wojtczuk, + author = {Wojtczuk, Rafal and Joanna Rutkowska}, + year = {2009}, + title = {{Attacking Intel Trusted Execution Technology}}, + howpublished = {BlackHat-DC 2009}, +} + +@article{Yalta2010, + author = {Yalta, A. Talha and A. Yasemin Yalta}, + year = {2010}, + title = {{Should Economists Use Open Source Software for Doing Research?}}, + journal = {Computational Economics}, + volume = {35}, + pages = {371--394}, +} + +@article{Yalta2008, + author = {Yalta, A. Talha and Riccardo Lucchetti}, + year = {2008}, + title = {{The GNU/Linux Platform and Freedom Respecting Software for Economists}}, + journal = {Journal of Applied Econometrics}, + volume = {23}, + pages = {279-286}, +} diff --git a/doc/cbdc-it/cbdc-it.tex b/doc/cbdc-it/cbdc-it.tex new file mode 100644 index 000000000..a5c939086 --- /dev/null +++ b/doc/cbdc-it/cbdc-it.tex @@ -0,0 +1,1304 @@ +\documentclass[a4paper]{article} +\usepackage[T1]{fontenc} +\usepackage[utf8]{inputenc} +\usepackage[top=2cm,bottom=2cm]{geometry} +\usepackage{url} +\usepackage{amsmath} +\usepackage{hyperref} +\usepackage{graphicx} +\usepackage{natbib} +\usepackage[italian]{babel} +\title{Come una banca centrale dovrebbe emettere una moneta digitale} +\author{David Chaum\footnote{david@chaum.com} \\ + xx Network \and + Christian Grothoff\footnote{christian.grothoff@bfh.ch} \\ + BFH\footnote{Università di Scienze Applicate di Berna} + \ e Progetto GNU \and + Thomas Moser\footnote{thomas.moser@snb.ch} \\ + Banca Nazionale Svizzera} +\date{Questa versione: febbraio 2022 \\ + Prima versione: maggio 2020} + +\setlength\parskip{5pt plus 1pt} % More space between paragraphs +\addto\captionsitalian{\renewcommand{\figurename}{Diagramma}} +\AtBeginDocument{\renewcommand{\harvardand}{\&}} +\hyphenation{CBDC} + +\begin{document} + +\maketitle + +\begin{abstract} +Con l'emergere di Bitcoin e delle criptovalute stabili (per es. Diem, +già nota come Libra) recentemente proposte dai colossi del web, le +banche centrali affrontano una crescente concorrenza da parte di +operatori privati che offrono la propria alternativa digitale al +contante fisico. Non trattiamo qui la questione normativa se una banca +centrale debba emettere o meno una moneta digitale. Contribuiamo invece +all'attuale dibattito di ricerca spiegando in che modo una banca centrale +potrebbe farlo, se lo volesse. Proponiamo un sistema basato su token +senza tecnologia di registro distribuito, e mostriamo che le monete +elettroniche emesse in passato, basate solo su software, possono essere +migliorate per tutelare la privacy nelle transazioni, soddisfare i +requisiti normativi in modo efficace e offrire un livello di protezione +resistente ai computer quantistici contro il rischio sistemico per +la privacy. Né la politica monetaria né la stabilità del sistema +finanziario sarebbero realmente interessate da questo sistema, dal +momento che una moneta emessa in questo modo replicherebbe il contante +fisico anziché i depositi bancari. \\ + +JEL: E42, E51, E52, E58, G2 +\\ + +Parole chiave: monete digitali, banca centrale, CBDC, firma cieca (\textit{blind signatures}), +criptovalute stabili, \textit{stablecoins} +\end{abstract} + +\vspace{40pt} + +\section*{Ringraziamenti} +Vorremmo ringraziare Michael Barczay, Roman Baumann, Morten Bech, +Nicolas Cuche, Florian Dold, Andreas Fuster, Stefan Kügel, Benjamin +Müller, Dirk Niepelt, Oliver Sigrist, Richard Stallman, Andreas Wehrli +e tre collaboratori anonimi per i loro commenti e suggerimenti. Le +posizioni, le opinioni, i risultati e le conclusioni o raccomandazioni +espresse in questo documento sono strettamente quelle degli autori. +Non riflettono necessariamente le posizioni della Banca nazionale +svizzera (BNS). La BNS declina ogni responsabilità per eventuali +errori, omissioni o inesattezze che dovessero comparire nel documento. + +Traduzione: Dora Scilipoti, con contributi da Luca Saiu +\newpage + +%\tableofcontents + +%\bibpunct{(}{)}{ e }{a}{}{,} + +\section{Introduzione}\label{1.-introduzione} + +Dall'avvento dei personal computer negli anni ottanta, e più +specificamente da quando nel 1991 la \textit{National Science +Foundation} revocò le restrizioni sull'uso di Internet per scopi +commerciali, c'è stata una ricerca sulla creazione di moneta digitale +per i pagamenti online. La prima proposta è stata quella +di~\cite{Chaum1983}. Sebbene tali metodi siano stati attuati, non hanno +preso piede; le carte di credito sono invece diventate il metodo più +diffuso per i pagamenti online. La proposta di~\cite{Nakamoto} per una +versione puramente \textit{peer-to-peer} di moneta digitale e il +conseguente lancio di Bitcoin avvenuto con successo hanno inaugurato +una nuova era di ricerca e sviluppo di valute digitali. La piattaforma +CoinMarketCap elenca oltre 5.000 criptovalute. Recentemente le banche +centrali hanno iniziato a considerare, o almeno a studiare, +l'emissione di monete digitali~\cite[vedi][]{AuerBoehme,AuerCornelli,Boar,Kiff,Mancini-Griffoli}. + +Attualmente, le banche centrali emettono due tipi di moneta: (i) +riserve sotto forma di conti di regolamento presso le banche centrali, +destinate solo agli operatori dei mercati finanziari, e (ii) divisa +disponibile per tutti sotto forma di banconote. Di conseguenza, la +letteratura sulla moneta digitale di banca centrale (\textit{Central Bank +Digital Currency} - CBDC) distingue tra (a) CBDC all'ingrosso ad +accesso ristretto e (b) CBDC al dettaglio disponibile per il +pubblico~\cite[si veda, ad esempio,][]{Bech}. +Una CBDC all'ingrosso sarebbe meno destabilizzante per il sistema attuale +dato che le banche e gli operatori dei mercati finanziari hanno già +accesso alla moneta digitale della banca centrale sotto forma di conti +presso questa istituzione, che utilizzano per regolare i pagamenti +interbancari. La domanda qui è se la tokenizzazione della moneta di banca +centrale e la tecnologia di registro distribuito (\textit{Distributed Ledger +Technology} - DLT) offrano vantaggi particolari rispetto ai sistemi con +regolamento lordo in tempo reale (\textit{Real-Time Gross Settlement} - RTGS) +esistenti. Finora la risposta è negativa, almeno per i pagamenti +interbancari nazionali~\cite[vedi][]{Chapman}. + +Una CBDC al dettaglio, che sarebbe una nuova forma di moneta di banca +centrale disponibile per il pubblico, potrebbe essere più destabilizzante +per il sistema attuale, a seconda di come è progettata. Più una CBDC +compete con i depositi delle banche commerciali, maggiore è la minaccia +ai finanziamenti bancari, con effetti potenzialmente negativi sul credito +bancario e sull'attività economica~\cite[vedi][]{Agur}. Tuttavia, una +CBDC al dettaglio potrebbe anche essere +vantaggiosa~\cite[vedi][]{Bordo,Berentsen,Bindseil,Niepelt,Riksbank,BoE}. +Mettere a disposizione di tutti una moneta elettronica di banca centrale +esente dal rischio di controparte potrebbe migliorare la stabilità e la +resilienza del sistema di pagamenti al dettaglio. Potrebbe inoltre fornire +un'infrastruttura di pagamento neutrale per incoraggiare la concorrenza, +l'efficienza e l'innovazione. Nel complesso, è probabile che i costi e i +benefici di una CBDC al dettaglio differiscano da un paese all'altro. Per +il punto di vista della Banca nazionale svizzera, che non ha in programma +l'emissione di una CBDC al dettaglio, si veda~\cite{Jordan}. + +Nel presente documento analizziamo la CBDC al dettaglio, ma senza +affrontare la questione se una banca centrale \emph{debba o meno} emetterla. +Ci concentriamo invece sul possibile design di una CBCD. L'interesse +per la progettazione di CBDC è recentemente aumentato +considerevolmente~\cite[si veda, ad esempio,][]{Allen,BoE}. Il design che +proponiamo differisce notevolmente da altre proposte. Il nostro sistema +si basa sulla tecnologia eCash descritta da~\cite{Chaum1983} e \cite{Chaum1990}, +migliorandola. In particolare, proponiamo una CBDC basata su token, solo +con software e senza tecnologia di registro distribuito. La DLT è +un'architettura interessante in assenza di un operatore centrale o se le +entità che interagiscono non accettano di nominare un operatore centrale +fidato. Questo non è certo il caso di una CBDC al dettaglio emessa da una +\emph{banca centrale}. Distribuire il registro delle transazioni della +banca centrale con una \textit{blockchain} non fa che aumentare i costi +di transazione; non porta alcun vantaggio tangibile nell'implementazione +da parte di una banca centrale. L'utilizzo della DLT per emettere moneta +digitale può essere utile in assenza di una banca centrale (ad esempio, +il progetto Sovereign delle Isole Marshall) o se l'intenzione esplicita +è quella di fare a meno di una banca centrale (ad esempio, +Bitcoin).\footnote{Potrebbero esserci casi opportuni di utilizzo della +DLT per le infrastrutture dei mercati finanziari, come gli scambi digitali, +dove sorge la questione di come incorporare la moneta della banca centrale +all'interno di una struttura DLT per eseguire i regolamenti. Tuttavia, +in tali situazioni i potenziali benefici della DLT, ad esempio costi +inferiori o riconciliazione automatica, non derivano da un'emissione +decentralizzata di moneta di banca centrale.} + +La CBDC basata su token che proponiamo consente anche di preservare +una caratteristica fondamentale del contante fisico: la privacy nelle +transazioni. Spesso si sostiene che l'uso della crittografia per la +tutela della privacy richieda così tanta potenza di calcolo da rendere +impraticabile la sua implementazione su dispositivi +portatili~\cite[vedi][]{Allen}. Sebbene questo possa essere vero nel +caso di una tecnologia di registro distribuito, dove la tracciabilità +delle transazioni è necessaria per prevenire la doppia spesa~\cite[][]{Narayanan}, +non lo è nel caso proposto in questo documento, dove si ha un protocollo +di firma cieca di tipo Chaum e la partecipazione di una banca centrale. +La nostra CBDC, basata su firme cieche e un'architettura a due livelli, +garantisce una tutela della privacy nelle transazioni perfetta e +quanto-resistente, fornendo al contempo protezioni sociali che sono di +fatto più potenti rispetto a quelle delle banconote per la lotta al +riciclaggio di denaro (\textit{Anti-Money Laundering} - AML) e al +finanziamento del terrorismo (\textit{Counter Terrorism Financing} - CFT). + +La privacy nelle transazioni è importante per tre motivi. In primo luogo, +protegge gli utenti dal potenziale abuso di monitoraggio e sorveglianza +da parte dei governi. Anche se si pensa di non avere nulla da nascondere, +i piani di sorveglianza di massa restano problematici, se non altro per +il rischio di errori e abusi, soprattutto se condotti senza trasparenza +e responsabilità~\cite[vedi][]{Solove}. In secondo luogo, la privacy nelle +transazioni protegge gli utenti dallo sfruttamento dei dati da parte dei +fornitori di servizi di pagamento. Infine, salvaguarda gli utenti dalla +controparte nelle transazioni in quanto esclude possibili comportamenti +opportunistici successivi o rischi per la sicurezza dovuti a negligenza +o mancata protezione dei dati dei clienti~\cite[vedi][]{Kahn2005}. + +Questo documento è strutturato come segue: nella Sezione II si spiega +la differenza tra la moneta di banca centrale e altri tipi di moneta. +Nella Sezione III si esaminano i modelli di CBDC tipici e generici prima +di proporre il nostro progetto nella Sezione IV. Si considerano poi +gli aspetti normativi e le politiche (V) e il relativo lavoro (VI). +Infine, si conclude (VII). + + +\section{Cos'è la moneta di banca centrale?} + \label{2.-cos'è-la-moneta-di-banca-centrale} + +La moneta è un attivo che può essere utilizzato per acquistare beni e +servizi. Per essere considerato moneta, l'attivo deve essere accettato +da entità diverse dall'emittente. Ecco perché i voucher, ad esempio, +non sono considerati moneta. La moneta autentica deve essere +\emph{comunemente} accettata come mezzo di scambio. Sebbene la moneta +abbia altre funzioni, ad esempio come unità di conto e riserva di valore, +la sua caratteristica distintiva è la sua funzione di mezzo di scambio. +Normalmente l'unità di conto (cioè come avvengono la fissazione dei +prezzi e la contabilizzazione dei debiti) coincide per ragioni +pratiche con il mezzo di scambio. Una separazione può tuttavia +verificarsi se il valore del mezzo di scambio manca di stabilità +rispetto ai beni e servizi scambiati.\footnote{Ciò può accadere +spontaneamente in un ambito caratterizzato da un'inflazione elevata, +ad esempio quando i prezzi sono quotati in USD ma i pagamenti vengono +effettuati in valuta locale. Lo stesso vale per i pagamenti in Bitcoin, +dove i prezzi sono solitamente fissati in USD o altre valute locali a +causa dell'elevata volatilità del Bitcoin. Una separazione può anche +essere progettata appositamente, come nel caso +dell'\textit{Unidad de Fomento} (UF) in Cile o i Diritti Speciali di +Prelievo (DSP) del Fondo Monetario Internazionale (FMI). Tuttavia, +anche in questi casi lo scopo è quello di avere un'unità di conto più +stabile.} La moneta deve anche essere una riserva di valore per fungere +da mezzo di scambio perché deve preservare il suo potere d'acquisto tra +il momento in cui si riceve e quello in cui si spende. In ogni modo, +ci sono molti altri attivi che fungono da riserva di valore, come azioni, +obbligazioni, metalli preziosi e immobili. Pertanto, la caratteristica +di riserva di valore non è distintiva della moneta. + +In un'economia moderna, il pubblico utilizza due tipi diversi di +moneta: (a) moneta statale e (b) moneta privata. La moneta statale viene +generalmente emessa dalla banca centrale, che agisce in qualità di +agente dello Stato. La moneta della banca centrale è disponibile per +alcune istituzioni finanziarie sotto forma di depositi presso la banca +centrale (riserve) e per il pubblico sotto forma di valuta (banconote e +monete), nota anche come «contante». In una economia moderna con valuta +fiat, tale moneta non ha un valore intrinseco. Legalmente è una passività +della banca centrale, sebbene non sia rimborsabile. Nella maggior parte +dei paesi, la moneta della banca centrale è definita come avente corso +legale, il che significa che deve essere accettata per il pagamento dei +debiti monetari, comprese le tasse e le sanzioni legali. Sebbene ciò +garantisca un certo valore alla moneta della banca centrale, lo status +di corso legale non è sufficiente per mantenere un valore stabile. È la +politica monetaria della banca centrale che mantiene il valore della +moneta. Mantenere la stabilità dei prezzi, vale a dire un valore stabile +della moneta rispetto a quello dei beni e dei servizi scambiati, è +infatti una delle principali responsabilità delle banche centrali. + +La maggior parte dei pagamenti in un'economia moderna vengono effettuati +con moneta privata emessa dalle banche commerciali ed è costituita da +depositi bancari a vista che le persone detengono presso queste banche. +Sono depositi che si posssono utilizzare mediante assegni, carte di +debito, carte di credito e altri mezzi di trasferimento di denaro e +costituiscono una passività della banca commerciale di riferimento. Una +caratteristica fondamentale di questi depositi è che le banche commerciali +garantiscono la convertibilità su richiesta in moneta della banca centrale +ad un prezzo fisso, vale a dire, alla pari. I depositanti possono prelevare +i propri fondi in contante o trasferirli ad un valore fisso di 1:1. Le +banche commerciali mantengono stabile il valore della propria moneta +ancorandola a quella della banca centrale. + +Tuttavia, in un sistema di riserva frazionaria, una banca commerciale, +anche se solvibile, potrebbe non avere liquidità a sufficienza per +onorare la sua promessa di convertire i depositi bancari in moneta +della banca centrale (ad esempio, nel caso di una corsa agli sportelli) +in modo tale che i clienti non possano prelevare i propri soldi. Una +banca può anche diventare insolvente e fallire, e di conseguenza i +clienti possono perdere denaro. Per questo motivo le banche commerciali +sono soggette a regolamentazioni volte a mitigare tali rischi. + +Una differenza notevole tra la moneta di una banca centrale e la +moneta privata emessa da una banca commerciale è, pertanto, che +quest'ultima comporta un rischio di controparte. Una banca centrale +può sempre adempiere ai suoi obblighi utilizzando la propria moneta +non rimborsabile. In un'economia nazionale, la moneta della banca +centrale è l'unico attivo monetario esento da rischi di credito e di +liquidità. È pertanto l'attivo tipicamente preferito per regolare i +pagamenti nelle infrastrutture dei mercati finanziari (si veda, per +esempio, \textit{CPMI-IOSCO Principles for Financial Market +Infrastructures}, 2012). Un'altra differenza risiede nella capacità +della moneta della banca centrale di sostenere il sistema monetario +nazionale fornendo un valore di riferimento con cui la moneta delle +banche commerciali mantiene la piena convertibilità. + +A parte le banche commerciali, altre entità private tentano +occasionalmente di emettere moneta; le criptovalute sono solo il +tentativo più recente. Ma a differenza dei depositi bancari, tale +moneta non è comunemente accettata come mezzo di scambio. Questo vale +anche per Bitcoin, la criptovaluta più ampiamente accettata. Un +ostacolo all'utilità delle criptovalute come mezzo di scambio è l'elevata +volatilità del loro valore. In risposta a questo problema sono emerse +le criptovalute stabili, cosiddette «stablecoins». Le +\textit{stablecoin} generalmente tentano di stabilizzare il proprio +valore in due modi: imitando le banche centrali (\textit{stablecoin} +algoritmiche) o imitando le banche commerciali e strumenti di +investimento (\textit{stablecoin} ancorate ad attivi).\footnote{Per una +tassonomia delle \textit{stablecoin}, si veda~\cite{Bullmann}.} + +Le «\textit{stablecoin} algoritmiche» si basano su algoritmi per regolare +l'offerta della moneta. In altre parole, cercano di stabilizzarne il +prezzo attraverso una «politica monetaria algoritmica». Esistono +esempi di tali \textit{stablecoin} (per esempio, Nubits), ma finora nessuna è +riuscita a stabilizzare il proprio valore per molto tempo. + +Le \textit{stablecoin} «ancorate ad attivi» differiscono in base al tipo +di attivo che utilizzano e ai diritti concessi ai possessori. I tipi di +attivi generalmente utilizzati sono: valuta (riserve di banche centrali, +banconote o depositi presso banche commerciali), materie prime (come +l'oro), titoli e talvolta altre criptovalute. La capacità di un tale +schema di stabilizzare il valore della moneta rispetto agli attivi +sottostanti dipende in modo cruciale dai diritti legali acquisiti dai +detentori della moneta. Se una \textit{stablecoin} è riscattabile ad un +prezzo fisso (per es. 1 moneta = 1 USD \\ o 1 moneta = 1 oncia d'oro), +la stabilità si può teoricamente ottenere.\footnote{Se possa stabilizzare +il valore della \textit{stablecoin} anche rispetto ai beni e servizi +scambiati dipende essenzialmente da quanto sia stabile il valore degli +attivi su cui poggia rispetto al valore dei beni e servizi.} Tale strategia +riproduce essenzialmente quella delle banche commerciali garantendo la +convertibilità nell'attivo sottostante su richiesta. Tuttavia, a differenza +dei depositi bancari, che in genere sono coperti solo parzialmente dalle +riserve della banca centrale, le \textit{stablecoin} sono spesso +completamente garantite dalle riserve di attivi sottostanti al fine di +evitare il rischio di liquidità, principalmente perché non dispongono di +tutele pubbliche tali come l'assicurazione dei depositi e il prestatore +di ultima istanza che offrono invece le banche regolamentate. + +Le \textit{stablecoin} che utilizzano le valute come attivi sono anche +dette «stablecoin a valuta fiat». Detenere il 100\% delle +garanzie sotto forma di valuta (banconote o depositi bancari) non risulta però +molto redditizio. Di conseguenza, i fornitori di \textit{stablecoin} hanno +un buon motivo per rispiarmiare sugli attivi passando ad un sistema di +riserva frazionaria, proprio come hanno fatto le banche +commerciali.\footnote{L'incertezza sulla garanzia delle +\textit{stablecoin} può essere uno dei motivi per cui vengono scambiate +al di sotto del loro valore nel mercato parallelo~\cite[vedi][]{Lyons}. +Casi simili si sono storicamente verificati anche con le banconote, quando +erano ancora emesse dalle banche commerciali. Le banconote venivano +scambiate a prezzi scontati nel mercato parallelo prima che l'emissione +fosse nazionalizzata e trasferita alle banche centrali come monopolio.} +Ciò comporta la riduzione degli attivi meno redditizi al minimo ritenuto +necessario per soddisfare il requisito di convertibilità e l'aumento +degli attivi liquidi a rendimento più elevato come i titoli di stato. +Questo migliora la redditività ma aumenta nel contempo il livello +di rischio. Tuttavia, anche se una \textit{stablecoin} fosse garantita +interamente da depositi presso le banche commerciali, rimarrebbe comunque +vulnerabile ai rischi di insolvenza del credito e di liquidità della +relativa banca. Tale rischio può essere evitato effettuando i depositi +presso la banca centrale in modo che siano le riserve di quest'ultima a +garantire la \textit{stablecoin}. Tali \textit{stablecoin} sono state +chiamate «CBDC sintetiche»~\cite[][]{Adrian}. È importante sottolineare che +queste \textit{stablecoin} non sono moneta di banca centrale e quindi +non costituiscono una CBDC in quanto non sono registrate come passività +della banca centrale e, pertanto, rimangono soggette al rischio di +controparte, ovvero al rischio di fallimento dell'emittente. + +Se una \textit{stablecoin} non è rimborsabile ad un prezzo fisso, la sua +stabilità rispetto all'attivo sottostante non è garantita. Se la +\textit{stablecoin} rappresenta comunque una quota di proprietà +dell'attivo sottostante, lo schema ricorda quello di un fondo comune di +investimento chiuso o di un fondo indicizzato quotato (\textit{Exchange-Traded +Fund} - ETF) e si applicano i relativi rischi. Il valore +della moneta dipenderà dal valore patrimoniale netto del fondo, ma il +suo valore effettivo può variare. Se ci sono partecipanti autorizzati +a creare e riscattare \textit{stablecoin} e quindi ad agire come +arbitraggisti, come nel caso degli ETF e come previsto per la +Diem~\cite[][]{Libra}, la deviazione si presume minima. + +Nel complesso, le \textit{stablecoin} hanno maggiori possibilità di +diventare moneta rispetto alle criptovalute, soprattutto se +adeguatamente regolamentate, anche se la disponibilità di CBDC +limiterebbe notevolmente la loro utilità. + +\section{Modelli generici di CBDC} \label{3.-modelli-generici-di-cbdc} + +Come abbiamo visto, la CBDC sarebbe una passività della banca +centrale. Due modelli possibili che si trovano nella letteratura +sull'argomento sono (a) CBDC basata su conti e (b) CBDC basata su +token (o sul valore). Questi modelli corrispondono ai due tipi +esistenti di moneta delle banche centrali e ai relativi sistemi di +pagamento~\cite[][]{Kahn2009}: riserve delle banche centrali +(sistema basato su conti) e banconote (sistema basato su token). Un +pagamento si verifica quando un'attivo monetario viene trasferito da un +pagatore a un beneficiario. In un sistema basato su conti, il +trasferimento avviene addebitando sul conto del pagatore e +accreditando sul conto del beneficiario. In un sistema basato su +token, il trasferimento avviene trasferendo il valore stesso o il +token, ovvero un oggetto che rappresenta l'attivo monetario. Il miglior +esempio di token è il contante (monete o banconote). Pagare in contanti +equivale a consegnare una moneta o una banconota. Non è necessario +registrare il trasferimento, il semplice possesso del token è +sufficiente. Pertanto, le parti non sono tenute a rivelare la propria +identità in nessun momento durante la transazione, entrambe possono +rimanere anonime. Ciononostante, il beneficiario deve essere in grado di +verificare l'autenticità del token. Questo è il motivo per cui le +banche centrali investono notevoli risorse nelle caratteristiche di +sicurezza delle banconote. + +È stato suggerito che la distinzione tra sistemi basati su conti e +quelli basati su token non sia applicabile alle monete digitali~\cite[][]{Garratt}. +Noi al contrario riteniamo che ci sia una differenza significativa. La +differenza essenziale risiede nelle informazioni contenute nell'attivo. +In un sistema basato su conti, gli attivi (i conti) sono riconducìbili +ad una cronologia delle transazioni che include tutte le operazioni di +credito e addebito dei conti. In un sistema basato su token, gli attivi +(i token) contengono solo informazioni sul valore del token e +sull'entità che lo ha emesso. I sistemi basati su token sono quindi +l'unica possibilità per ottenere la stessa privacy nelle transazioni che +offre il contante.\footnote{Sebbene il termine «Bitcoin» suggerisca +l'uso di token, Bitcoin è un sistema basato su conti. L'unica differenza +tra un sistema tradizionale basato su conti e una \textit{blockchain} è +che i conti non sono conservati in un database centrale ma in un +database decentralizzato di solo accodamento.} + +\subsection{CBDC basata su conti}\label{cbdc-basata-su-conti} + +Il modo più semplice per avviare una CBDC sarebbe consentire al +pubblico di detenere conti deposito presso la banca centrale. Ciò +comporta che la banca centrale si facesse responsabile dei controlli per +conoscere i propri clienti (\textit{Know-Your-Customer} - KYC) e di +garantire la conformità con i requisiti per la lotta al riciclaggio di +denaro e al finanziamento del terrorismo. Ciò includerebbe non solo la +gestione del processo iniziale di conoscenza del cliente, ma anche +l'autenticazione dei clienti per le transazioni bancarie, la gestione +delle frodi e delle autenticazioni false positive e false negative. +Data la scarsa presenza fisica delle banche centrali nella società e il +fatto che probabilmente oggi non siano disposte ad eseguire l'autenticazione +dei cittadini su larga scala, qualsiasi CBDC basata su conti richiederebbe +alla banca centrale di delegare questi compiti. Tutti i servizi di +assistenza e manutenzione di tali conti potrebbero essere affidati ad +operatori esterni~\cite[][]{Bindseil}, oppure le banche commerciali potrebbero +essere obbligate per legge ad aprire conti presso la banca centrale per i +propri clienti~\cite[][]{Berentsen}. + +Una CBDC basata su conti darebbe potenzialmente alla banca centrale +l'accesso a molti dati aggiuntivi. Uno dei motivi di preoccupazione è +che i governi potrebbero facilmente mettere in atto una sorveglianza +di massa e imporre sanzioni ai singoli titolari dei conti. La natura +centralizzata di tali interventi li rende poco costosi e facili da +applicare nei confronti di persone o gruppi. Ci sono molti esempi di +sorveglianza abusiva contro critici e oppositori politici, anche nelle +democrazie. Si potrebbe argomentare che le banche centrali indipendenti +siano in grado di salvaguardare tali informazioni dall'intrusione del +governo e dagli abusi politici, ma ciò aprirebbe comunque una nuova +strada alle pressioni politiche che minacciano l'indipendenza delle +banche centrali. Inoltre, un database centrale sarebbe un obiettivo +cospicuo per gli attacchi: anche l'accesso in sola lettura ad una parte +del database potrebbe creare rischi significativi per le persone i cui +dati sarebbero esposti. + +Se dovessero fornire conti bancari per il pubblico, le banche centrali +entrerebbero in diretta concorrenza con le banche commerciali, competizione +che comporterebbe due rischi. In primo luogo, potrebbe minacciare la base +dei depositi delle banche e, all'estremo, portare alla disintermediazione +bancaria. Ciò potrebbe influire negativamente sulla disponibilità di +credito per il settore privato e, di conseguenza, sull'attività +economica~\cite[][]{Agur}. La disintermediazione delle banche potrebbe anche +condurre alla centralizzazione dell'allocazione del credito all'interno +della banca centrale, con ripercussioni negative sulla produttività e +sulla crescita economica. In secondo luogo, la possibilità per le persone +di trasferire i propri depositi nel porto sicuro di una banca centrale +potrebbe accelerare le corse agli sportelli nei periodi di crisi economica. + +Vi sono però argomentazioni contrarie. \cite{Brunnermeier} +sostengono che i trasferimenti di fondi dai depositi ai conti +CBDC porterebbero alla sostituzione automatica del finanziamento +mediante depositi con il finanziamento tramite la banca centrale, il +che andrebbe ad esplicitare la garanzia finora implicita di prestatore +di ultima istanza delle banche centrali. \cite{Berentsen} +sostengono che la concorrenza delle banche centrali potrebbe persino +avere un effetto disciplinare sulle banche commerciali e quindi +aumentare la stabilità del sistema finanziario, dato che queste ultime +sarebbero costrette a consolidare la sicurezza dei propri modelli +economici per eviatare corse agli sportelli. + +% References to Kumhof, Bindseil below should render like this: +% valore (Kumhof &amp; Noone, 2018 e Bindseil, 2020). +% This was fixed by replacing "," with "and" to separate authors in the bib file. +% It also fixed {Kumhof} to render as "Kumhof & Noone". + +Esistono anche proposte per ridurre il rischio di disintermediazione +restringendo o scoraggiando l'uso della CBDC come riserva di valore. Una +delle proposte è di limitare la quantità di CBDC che si può possedere. +Una seconda proposta consiste nell'applicare un tasso di interesse +variabile ai conti in CBDC, in modo che il rendimento sia sempre +sufficientemente inferiore a quello dei conti nelle banche commerciali, +arrivando eventualmente fino a tassi negativi, in modo da rendere la CBDC +meno attraente come riserva di valore~\cite[][]{Kumhof,Bindseil}. Oltre a ciò, +per evitare le corse agli sportelli \citet{Kumhof} suggeriscono che la +CBDC non dovrebbe essere emessa a fronte di depositi bancari ma solo a +fronte di obbligazioni come i titoli di stato. Nel complesso, una CBDC +basata su conti richiederebbe un'analisi più approfondita di queste +problematiche. + +% Back to default style. +%\bibpunct{(}{)}{ e }{,}{}{,} + + +\subsection{CBDC Basata su token e legata al hardware} +\label{cbdc-basata-su-token-e-legata-al-hardware} + +% References to Wojtczuk,Johnston,Lapid below do not render correctly in pdf. Should be: +% compromesse (si veda, ad esempio, Wojtczuk &amp; Rutkowska 2009, Johnston 2010 e Lapid &amp; Wool 2018). +% but we can only either use "," or "e", but not switch AFAIK. +% This was fixed by replacing "," with "and" to separate authors in the bib file. +% It also fixed {Katzenbeisser} to render as "Katzenbeisser et al." + +In alternativa ai conti deposito, una banca centrale potrebbe emettere +token elettronici. Tecnicamente ciò richiede un sistema per garantire che +i token elettronici non possano essere copiati facilmente. Le funzioni +fisicamente non clonabili~\cite[vedi][]{Katzenbeisser} e le aree +sicure nell'hardware~\cite[vedi][]{Alves,Pinto} sono due tecnologie +possibili per la prevenzione della copia digitale. Le funzioni +fisicamente non clonabili, tuttavia, non possono essere scambiate su +Internet (eliminando di fatto l'uso principale delle CBDC) e le precedenti +funzionalità di sicurezza nell'hardware per la prevenzione della copia +sono state ripetutamente +compromesse~\cite[si veda, ad esempio,][]{Wojtczuk,Johnston,Lapid}. + +Un vantaggio fondamentale delle CBDC basate su token rispetto a quelle +basate su conti è che i sistemi tokenizzati funzionerebbero offline, +ovvero, gli utenti potrebbero scambiare token (\textit{peer-to-peer}) +senza coinvolgere la banca centrale, proteggendo così la privacy e la +libertà delle persone. Tuttavia, la disintermediazione che si verifica +quando gli utenti possono scambiare token elettronici senza +intermediari bancari che eseguano i controlli per la conoscenza dei +clienti e le procedure per la lotta al riciclaggio di denaro e al +finanziamento del terrorismo renderebbe difficile la lotta alla +criminalità. + +% References to Soukup,Garcia,Kasper,CCC below do not render correctly in pdf. Should be: +% L’esperienza (si veda, ad esempio, Soukup &amp; Muff 2007, Garcia et al. 2008, Kasper et al. 2010 e CCC e.V. 2017) suggerisce +% but we can only either use "," or "e", but not switch AFAIK. +% This was fixed by replacing "," with "and" to separate authors in the bib file. + +Le schede SIM sono oggi il mezzo più ampiamente disponibile per un +sistema di pagamento sicuro basato su hardware, ma comportano anche +dei rischi. L'esperienza~\cite[si veda, ad esempio,][]{Soukup,Garcia,Kasper,CCC} +suggerisce che qualsiasi dispositivo economicamente riproducibile in grado +di memorizzare token con valore monetario, che una persona possa possedere +e che consenta transazioni offline --- e quindi il furto mediante +clonazione delle informazioni in esso contenute --- sarà l'obiettivo di +attacchi di contraffazione riusciti non appena il valore economico +dell'attacco risulti sostanziale. Tali attacchi provengono anche da +utenti che forzano il proprio hardware~\cite[vedi][]{Allen}. Per +limitare l'impatto di una compromissione, i sistemi con carte di pagamento +che sono stati precedentemente implementati dipendono dalla resistenza +alle manomissioni in combinazione con il rilevamento delle frodi. +Tuttavia, il rilevamento delle frodi richiede la capacità di identificare +i pagatori e tenere traccia dei clienti, il che non è compatibile con la +privacy nelle transazioni. + +\section{Una CBDC basata su token progettata per tutelare la privacy} +\label{4.-una-cbdc-basata-su-token-progettata-per-tutelare-la-privacy} + +La CBDC qui proposta è di tipo «solo software», semplicemente +un'applicazione per smartphone che non richiede alcun hardware aggiuntivo. +Il design fa affidamento su eCash e GNU Taler. Taler fa parte del progetto +GNU, il cui fondatore, Richard Stallman, ha coniato il termine +«\emph{Software Libero}», ora spesso indicato come \textit{Free/Libre +and Open Source Software} (FLOSS).\footnote{Per ulteriori informazioni +su GNU, si veda \url{https://www.gnu.org} e \cite{Stallman}. GNU Taler +è rilasciato sotto la licenza libera \textit{GNU Affero General Public +License} del Progetto GNU. Altri programmi del progetto GNU noti tra gli +economisti sono \textit{R} e \textit{GNU Regression, Econometrics and +Time-series Library} (GRETL). Per un'analisi dei vantaggi del FLOSS +rispetto al software proprietario nel campo della ricerca, si +veda~\cite{Baiocchi}, \cite{Yalta2008} e \cite{Yalta2010}. +Sulle licenze libere e open source, si veda~\cite{Lerner}.} Il software +è considerato libero se la sua licenza concede agli utenti quattro libertà +essenziali: la libertà di eseguire il programma come si desidera, la +libertà di studiare il programma e modificarlo, la libertà di ridistribuire +copie del programma e la libertà di distribuire copie delle versioni +modificate del programma. Il software libero non impedisce la +commercializzazione; fornire supporto tecnico per il software è un modello +di business standard per il FLOSS. + +Dato il gran numero di parti interessate coinvolte in una CBDC al +dettaglio (la banca centrale, il settore finanziario, i venditori e +i clienti) e l'importanza critica dell'infrastruttura, una CBDC al +dettaglio deve essere basata sul FLOSS. Imporre una soluzione +proprietaria, che comporta la dipendenza da un fornitore specifico, +sarebbe probabilmente un ostacolo all'adozione fin dall'inizio. Con il +FLOSS, tutte le parti interessate hanno accesso a ogni dettaglio della +soluzione e il diritto di adattare il software alle proprie esigenze. +Ciò facilita l'integrazione e migliora l'interoperabilità e la +concorrenza tra i fornitori.\footnote{Tuttavia, l'hardware privato +potrebbe avere un ruolo da svolgere. La protezione degli archivi delle +chiavi e di alcune funzioni di controllo, ad esempio, può essere un'area +dove l'hardware dedicato valutato solo da un numero limitato di esperti +può presentare dei vantaggi, nella misura in cui tale sicurezza sia solo +additiva.} Consente inoltre alla banca centrale di soddisfare i requisiti +di trasparenza e responsabilità. I vantaggi del FLOSS riguardo la +sicurezza sono anche ampiamente riconosciuti. La disponibilità del codice +sorgente e la libertà di modificarlo facilitano l'identificazione degli +errori e la loro rapida correzione. \footnote{Ad esempio, un bollettino +sulla sicurezza informatica emesso dall'Agenzia per la sicurezza nazionale +degli Stati Uniti (NSA) nell'aprile 2020 esorta gli utenti a dare la +priorità al software libero nella scelta e nell'utilizzo dei servizi +collaborativi per le comunicazioni su Internet: «Lo sviluppo open source +garantisce trasparenza sulla robustezza del codice e la sua conformità +alle migliori pratiche di programmazione, evitando l'introduzione di +vulnerabilità o punti deboli che potrebbero mettere a rischio utenti e +dati» (U/OO/134598-20).} + +Nell'architettura che proponiamo, tutte le interazioni tra consumatori +e venditori si fanno con le banche commerciali, ma la creazione di moneta +e il database sono forniti esclusivamente dalla banca centrale. Le banche +commerciali autenticano i clienti quando ritirano CBDC così come i +venditori o beneficiari quando le ricevono. Quando spendono CBDC, +invece, i clienti o pagatori devono solo autorizzare le transazioni senza +bisogno di identificarsi. I pagamenti risultano più economici, più facili +e più veloci, evitando al contempo interferenze con la privacy~\cite[][]{Dold}. +L'autenticazione dei clienti quando ritirano CBDC, nonché dei venditori +o beneficiari quando le ricevono, consente altresì di adempire alle +normative sulla conoscenza dei clienti e sulla lotta al riciclaggio di +denaro e al finanziamento del terrorismo. + +La CBDC che si propone in questo documento è un vero e proprio +strumento digitale al portatore perché quando l'utente preleva una +somma di denaro sotto forma di numero, tale numero viene «accecato» o +nascosto dallo smartphone con un'apposita crittografia. Nel sistema +stesso, una moneta è una coppia di chiavi pubblica-privata dove la +chiave privata è nota solo al proprietario della moneta.\footnote{In +Bitcoin, un sistema basato su conti, la coppia di chiavi è un conto +dove la chiave pubblica rappresenta l'«indirizzo» e quindi una sorta di +«identità», anche se pseudonimo.} La moneta trae il suo valore +finanziario dalla firma della banca centrale apposta sulla chiave +pubblica della moneta. La banca centrale firma con la propria chiave +privata e detiene più coppie di chiavi di valore per apporre la firma +cieca su monete di diverso valore unitario. Il venditore può utilizzare +la corrispondente «chiave pubblica» della banca centrale per verificare +la firma. Tuttavia, al fine di garantire che la moneta non sia stata +copiata e già ritirata da un altro beneficiario (cioè che non sia stata +«spesa due volte»), il venditore deve depositare la moneta affinché la +banca centrale possa confrontarla con un archivio di monete ritirate. +Poiché né la banca commerciale né la banca centrale vedono il numero +della moneta durante il prelievo, in seguito, quando il venditore +deposita la moneta, non si sa quale utente l'abbia ritirata. L'accecamento +e la privacy che ne deriva fanno di questa tipologia di CBDC un vero e +proprio strumento digitale al portatore. + +Nell'analisi che segue forniamo una panoramica approfondita della +tecnologia e mostriamo come si può integrare con il sistema bancario +esistente per creare una CBDC. \citet{Dold} fornisce ulteriori +dettagli. + +\subsection{Componenti fondamentali}\label{componenti-fondamentali} + +Di seguito si descrivono i componenti principali del protocollo, comprese +le basi matematiche per una delle possibili rappresentazioni delle +primitive crittografiche utilizzate, allo scopo di illustrare in +che modo potrebbe funzionare un'implementazione. Considerando che +esistono altri modelli matematici equivalenti per ciascun componente, +presentiamo solo la più semplice delle soluzioni sicure a noi note. + +\emph{Firme digitali.} L'idea che sta alla base delle firme digitali in +uno schema di firma a chiave pubblica è quella di garantire che il +titolare della chiave privata sia l'unico in grado di firmare un +messaggio, mentre la chiave pubblica consente a chiunque di verificare +la validità della firma.\footnote{La crittografia a chiave pubblica è +stata introdotta da~\cite{Diffie} e le prime implementazioni di firme +digitali sono state quelle di~\cite{Rivest}.} Il risultato della funzione +di verifica della firma è la dichiarazione binaria «vero» o «falso». Se +il messaggio è firmato con la chiave privata che appartiene alla chiave +pubblica di verifica, il risultato è «vero», altrimenti è «falso». +Nella nostra proposta il messaggio è una moneta o una banconota con un +numero di serie, e la firma della banca centrale ne attesta la +validità. Sebbene GNU Taler utilizzi per impostazione predefinita le +moderne firme EdDSA~\cite[vedi][]{Bernstein2012}, qui presentiamo un +semplice schema di firma crittografica basato su RSA~\cite[][]{Rivest}, un +sistema crittografico ben studiato.\footnote{Per un'analisi della +lunga storia del crittosistema RSA e uno studio degli attacchi a questo +sistema, si veda~\cite{Boneh}.} Tuttavia, in linea di principio, è +possibile utilizzare qualsiasi tecnologia di firma crittografica +(DSA, ECDSA, EdDSA, RSA, ecc.) + + +Per generare una chiave RSA, il firmatario prende prima due grandi +numeri primi indipendenti $p$ e $q$ e calcola $n = \emph{pq}$, +nonché la funzione phi di Eulero +$\phi(n) = (p - 1)(q - 1)$. +Quindi, si può utilizzare qualsiasi $e$ con $1 < e < \phi(n)$ e +$\gcd(e, \phi(n)) = 1$ per definire una chiave pubblica $(e,n)$. +La condizione che il massimo comune denominatore ($\texttt{MCD}$) di $e$ e +$\phi(n)$ debba essere 1 (cioè, che devono essere +primi tra loro) assicura che l'inverso di +$e \mod \phi(n)$ esista. +Questo inverso è la +corrispondente chiave privata $d$. Data $\phi(n)$, la chiave +privata $d$ può essere calcolata mediante l'algoritmo esteso +di Euclide tale che +$d \cdot e \equiv 1 \mod \phi(n)$. + +Data la chiave privata $d$ e la chiave pubblica $(e, n)$, una semplice +firma RSA +$s$ su un messaggio $m$ è +$s \equiv m^{d} \mod n$. +Per verificare la firma si calcola +$m' \equiv s^{e} \mod n$. +Se $m'$ e $m$ corrispondono, la firma è valida e dimostra che il +messaggio è stato firmato con la chiave privata che corrisponde alla +chiave pubblica di verifica (autenticazione del messaggio) e che il +messaggio non è stato modificato durante il transito (integrità del +messaggio). In pratica, le firme vengono poste sull'hash dei messaggi +piuttosto che sui messaggi stessi. Le funzioni di hash calcolano le +impronte digitali dei messaggi (\textit{digest}), che sono identificatori +univoci e brevi per i messaggi. Firmare un hash breve è molto più veloce +che firmare un messaggio di grandi dimensioni, e la maggior parte degli +algoritmi di firma funzionano solo su input relativamente brevi.\footnote{Nel +caso del crittosistema RSA, il limite di lunghezza è di +$\log_{2}n$ bit.} + +\emph{Firme cieche.} Utilizziamo le firme cieche introdotte +da~\cite{Chaum1983} per tutelare la privacy degli acquirenti. Una firma +cieca viene utilizzata per creare una firma crittografica per un messaggio +senza rivelare al firmatario il contenuto del messaggio. Nella nostra proposta, +ciò impedisce alle banche commerciali e alla banca centrale di poter risalire +all'acquirente tracciando gli acquisti. In linea di principio, la nostra +proposta funziona con qualsiasi sistema di firma cieca, ma la soluzione migliore +rimane la variante basata su RSA descritta da~\cite{Chaum1983}. + +L'accecamento viene eseguito dai clienti, che accecano le proprie +monete prima di trasmetterle alla banca centrale per la firma. I +clienti non devono quindi affidare alla banca centrale la tutela della +propria privacy. Inoltre, l'accecamento con RSA fornirebbe protezione +della privacy anche contro gli attacchi informatici quantistici. La +banca centrale, dal canto suo, predispone più coppie di chiavi di +valore per apporre la firma cieca su monete di diverso valore +unitario, e fornisce le corrispondenti chiavi pubbliche +$(e, n)$ per tali valori. + +Sia $f$ il valore di hash di una moneta e quindi l'identificatore +univoco per questa moneta. Il cliente che preleva la moneta prima +genera un fattore di accecamento casuale $b$ e calcola +$f' \equiv fb^{e} \mod n$ +con la chiave pubblica della banca centrale per quel valore. +La moneta accecata $f'$ viene quindi trasmessa alla banca centrale per +la firma. La banca centrale firma $f'$ con la sua chiave +privata $d$ calcolando la firma cieca +$s' \equiv \left(f' \right)^{d} \mod n$, appone +la firma $s'$ alla moneta accecata $f'$ e restituisce la coppia +$(s',f')$ al cliente. Il cliente può quindi rimuovere l'accecamento +della firma calcolando +$s \equiv s'b^{- 1} \mod n$. +Ciò è possibile perché +$\left( f' \right)^d = f^db^{ed} = f^db$, e quindi +moltiplicando $s'$ con $b^{- 1}$ si ottiene $f^d$, che è una firma RSA +valida su $f$ come prima: +$s^e \equiv f^{de} \equiv f \mod n$. + +Nella proposta originale di Chaum, le monete erano dei semplici +gettoni. Quel che vogliamo, invece, è che i consumatori possano +utilizzare le firme digitali per stipulare contratti. A tal fine, ogni +volta che un portafoglio digitale preleva una moneta, in primo luogo +crea per la moneta una chiave privata casuale $c$ e calcola la +corrispondente chiave pubblica $C$ per creare firme digitali con i +normali sistemi di firma crittografica (come DSA, ECDSA, EdDSA e +RSA). Quindi si deriva $f$ mediante una funzione di hash crittografica +dalla chiave pubblica $C$, prima che la banca centrale ne apponga la +firma cieca (utilizzando un nuovo fattore di accecamento casuale per +ciascuna moneta). Ora il cliente può utilizzare $c$ per firmare +elettronicamente gli acquisti, spendendo così la moneta. + +Come visto sopra, la banca centrale andrebbe a predisporre coppie di +chiavi diverse per ogni valore unitario di moneta e pubblicherebbe le +chiavi pubbliche che i clienti userebbero per prelevare denaro. Queste +chiavi di valore, e quindi le monete, avrebbero una data di scadenza +prima della quale dovrebbero essere spese o scambiate con monete +nuove. Ai clienti verrebbe concesso un certo periodo di tempo per +scambiare le monete. Un processo simile esiste per le banconote +fisiche, dove le serie di banconote vengono regolarmente rinnovate per +essere dotate delle più recenti caratteristiche di sicurezza, tranne +per il fatto che le banconote generalmente rimangono in circolazione +per decenni anziché per pochi anni o mesi.\footnote{In Svizzera, +ad esempio, la Banca nazionale svizzera ha iniziato a ritirare dalla +circolazione l'ottava serie di banconote nell'aprile 2016. Questa serie +era stata messa in circolazione alla fine degli anni novanta. Dal 1 +gennaio 2020, tuttavia, tutte le banconote a partire dalla sesta serie +(emesse nel 1976) fino alle serie future restano valide e possono essere +scambiate a tempo indeterminato con banconote correnti.} + +Da un punto di vista tecnico, una data di scadenza offre due vantaggi. +In primo luogo, migliora l'efficienza del sistema perché la banca +centrale può cancellare i dati scaduti, evitando così di dover +archiviare e poi cercare in un elenco sempre crescente di monete +(spese) per rilevare una doppia spesa. In secondo luogo, riduce i +rischi per la sicurezza dato che la banca centrale non deve +preoccuparsi di attacchi alle proprie chiavi (private) di valore ($d$) +scadute. Inoltre, anche se una chiave privata venisse compromessa, il +periodo durante il quale l'attaccante può utilizzarla è breve. In aggiunta, +l'addebito di una commissione di cambio consentirebbe alla banca centrale di +applicare tassi di interesse negativi, se ritenuto necessario. La banca centrale +potrebbe anche, se lo desidera, fissare un limite di conversione per cliente in +considerazione dell'antiriciclaggio e l'antiterrorismo (soglia di «contante») o +per motivi di stabilità finanziaria (per prevenire accaparramenti e corse agli +sportelli). + +\emph{Protocollo di scambio di chiavi.} GNU Taler utilizza un protocollo +di scambio di chiavi in un modo particolare per fornire un collegamento +tra la moneta originale e il resto reso per quella stessa moneta. Ciò +garantisce che il resto possa sempre essere reso senza compromettere +la trasparenza del reddito e la privacy dei consumatori. Lo stesso +meccanismo si può utilizzare per i rimborsi anonimi ai clienti. Il +protocollo gestisce anche i guasti alla rete e ai componenti, +assicurando che i pagamenti siano andati a buon fine o siano stati +definitivamente annullati e che tutte le parti abbiano una prova +crittografica dell'esito. Questo corrisponde all'incirca agli scambi +atomici nei protocolli \textit{interledger} o allo scambio equo nei +tradizionali sistemi \textit{e-cash}. + +La costruzione matematica più comune per un protocollo di scambio di +chiavi è la costruzione~\cite{Diffie}, che +consente a due parti di derivare una chiave segreta condivisa. A tale +scopo, condividono due parametri di dominio $p$ e $g$, che possono +essere pubblici, dove $p$ è un numero primo grande e $g$ è una radice +primitiva modulo $p$.\footnote{Un intero $g$ è una radice primitiva +modulo $p$ se per ogni intero $a$ coprimo a $p$ esiste un intero $k$ +per il quale +$g^k \equiv a \mod p$. +In pratica, $g$ dovrebbe essere una radice primitiva $(p-1)$-esima, detta +anche generatore, al fine di prevenire attacchi a sottogruppi come quelli +Pohlig-Hellman~\cite[vedi][]{Lim}.} Ora, le due parti scelgono le loro +chiavi private \emph{a} e \emph{b}, che sono due numeri interi grandi. +Con queste chiavi private e i parametri di dominio, generano le +rispettive chiavi pubbliche +$A \equiv g^{a} \mod p$ e $B \equiv g^{b} \mod p$. +Ciascuna parte può ora utilizzare la propria chiave privata e la chiave +pubblica dell'altra parte per calcolare la chiave segreta condivisa +$k \equiv \left( g^b \right)^{a} \equiv \left( g^{a} \right)^{b} \equiv g^{\text{ab}} \mod p$.\footnote{ +Lo stesso meccanismo potrebbe essere utilizzato per garantire +che le monete non vengano trasferite a terzi durante il prelievo. A +questo scopo, gli utenti devono salvaguardare una chiave di identità a +lungo termine. Il processo di prelievo potrebbe quindi essere +costruito allo stesso modo di quello utilizzato da GNU Taler per dare +il resto, tranne per il fatto che quando si preleva dal conto bancario +del cliente verrebbe utilizzata la chiave d'identità a lungo termine +del cliente al posto della moneta originale. Tuttavia, le garanzie +sulla privacy potrebbero decadere se il cliente non protegge la chiave +d'identità a lungo termine, con il conseguente rischio di furto di +tutte le monete residue. Dato che il rischio nei trasferimenti a terzi +quando si prelevano monete è basso, non è chiaro se questa riduzione +del rischio possa essere un buon compromesso.} + +Per ottenere il resto, il cliente parte dalla chiave privata della +moneta parzialmente spesa $c$. Sia $C$ la chiave pubblica corrispondente, +per esempio +$C = g^{c} \mod p$. +Quando la moneta fu parzialmente spesa in precedenza, la banca centrale +registrò la transazione relativa a $C$ nel proprio database. Per +semplicità, assumiamo che esista un valore unitario che corrisponda +esattamente a questo valore residuo. In caso contrario, il protocollo si +riavvia finché non viene reso tutto il resto. Sia $(e,n)$ la +chiave di valore per il resto da rendere. + +Per ottenere il resto, l'acquirente crea prima $\kappa$ chiavi di +trasferimento private $t_{i}$ per \\ +$i \in \left\{ 1,\ldots,\kappa \right\}$ e calcola le +corrispondenti chiavi pubbliche $T_{i}$. Queste chiavi di +trasferimento $\kappa$ sono semplicemente coppie di chiavi +pubbliche-private che consentono al cliente di eseguire localmente il +protocollo di scambio di chiavi, con il cliente che gioca su entrambi +i lati del processo, $\kappa$ volte tra $c$ e ogni $t_{i}$. +Se si usa Diffie-Hellman come protocollo per lo scambio di chiavi, si +ottiene +$T_{i} \equiv g^{t_{i}} \mod p$. + +Il risultato è composto da tre trasferimenti +$K_{i} \equiv \emph{KX}(c,t_{i})$. Il protocollo di scambio di chiavi +può essere utilizzato in diversi modi per ottenere lo stesso valore +$K_{i} \equiv \emph{KX}(C,t_{i}) = \emph{KX}(c,T_{i})$. +Data $K_{i}$, il cliente utilizza una funzione crittografica hash $H$ +per ricavare i valori +$(b_{i},c_{i}) \equiv H(K_{i})$, dove +$b_{i}$ è un fattore di accecamento valido per la chiave di valore +$(e,n)$ e $c_{i}$ +è una chiave privata per la nuova moneta da ottenere come resto. +$c_{i}$ deve essere adatta sia per creare firme crittografiche sia per +un uso futuro con il protocollo di scambio di chiavi +(come $c$, per ottenere resto a partire dal resto). +Sia $C_{i}$ la chiave pubblica corrispondente a $c_{i}$. +Il cliente chiede quindi alla banca centrale di creare una firma cieca su +$C_{i}$ per $i \in \{ 1,\ldots,\kappa\}$.\footnote{Se dovesse essere +utilizzato il crittosistema RSA per le firme cieche, useremmo +$f \equiv \emph{FDH}_{n}(C_{i})$, dove +$\emph{FDH}_{n}()$ +è l'hash del dominio completo sul dominio $n$.} In questa richiesta, il +cliente si impegna anche con le chiavi pubbliche +$T_{i}$. +La richiesta è autorizzata mediante una firma effettuata con la chiave +privata $c$. + +Invece di restituire direttamente la firma cieca, la banca centrale +chiede prima al cliente di dimostrare che ha utilizzato correttamente la +costruzione di cui sopra fornendo +$\gamma \in \left\{ 1,\ldots,\kappa \right\}$. +Il cliente deve quindi mostrare alla banca centrale la +$t_{i}$ per $i \neq \gamma$. +La banca centrale può quindi calcolare +$K_{i} \equiv \emph{KX}(C,t_{i})$ e ricavare i valori +$(b_{i},c_{i})$. Se per tutte le +$i \neq \gamma$ la $t_{i}$ fornita dimostra che il cliente ha utilizzato +correttamente la costruzione, la banca centrale restituisce la firma +cieca su $C_{\gamma}$. +Se il cliente non fornisce una prova corretta, il valore residuo della +moneta originale viene perso. Questo penalizza efficacemente coloro che +tentano di eludere la trasparenza del reddito con un'aliquota fiscale +stimata di $1 - \frac{1}{\kappa}$. + +Per evitare che un cliente cospiri con un venditore che sta tentando di +evadere il fisco, la banca centrale consente a chiunque +conosca $C$ di ottenere, in qualsiasi momento, i valori di +$T_{\gamma}$ +e le firme cieche di tutte le monete collegate alla moneta originaria $C$. +Ciò permette al possessore della moneta originaria, che conosce $c$, di +calcolare +$K_{\gamma} \equiv \emph{KX}( c,T_{\gamma})$ +e da lì ricavare +$(b_{i},c_{i})$ +per, infine, rimuovere la firma cieca. Di conseguenza, un venditore che +nasconde il proprio reddito in questo modo formerebbe solo un'accordo +economico limitato con il cliente invece di ottenere il controllo esclusivo. + +\hypertarget{architettura-del-sistema}{% +\subsection{Architettura del sistema}\label{architettura-del-sistema}} + +Uno degli obiettivi principali della nostra architettura è garantire +che le banche centrali non debbano interagire direttamente con i +clienti né conservare alcuna informazione su di loro, ma solo tenere +un elenco delle monete spese. L'autenticazione è delegata alle banche +commerciali, che dispongono già dell'infrastruttura necessaria. I +protocolli di prelievo e deposito raggiungono la banca centrale +tramite una banca commerciale in qualità di intermediaria. Dal punto +di vista del cliente, il processo è analogo al prelievo di contanti da +un bancomat. La transazione tra la banca commerciale dell'utente e la +banca centrale avviene in background. La procedura per il prelievo di +CBDC è illustrata nel diagramma~\ref{fig:fig1}. + +\begin{figure}[h!] + \includegraphics[width=\textwidth]{diagramma1-it.png} + \caption{Prelievo di CBDC} + \label{fig:fig1} +\end{figure} + +Il cliente (1) invia i dati di accesso alla propria banca commerciale +utilizzando le relative procedure di autenticazione e autorizzazione. +Quindi il telefono (o il computer) del cliente ottiene la chiave di +valore pubblica $(e, n)$ fornita dalla banca centrale per quel valore; (2) +calcola quindi una coppia di chiavi per la moneta, con una chiave +privata $c$ e una chiave pubblica $C$, e sceglie un fattore di accecamento +$b$. La chiave pubblica della moneta viene quindi sottoposta a hash \\ +($\to$ $f$) e accecata ($\to$ $f'$). Quindi il dispositivo del cliente (3) +invia $f'$ insieme all'autorizzazione a prelevare la moneta e ad +addebitarla dal conto del cliente presso la banca commerciale tramite un +canale sicuro stabilito. La banca commerciale (4) addebita quindi +l'importo dal conto deposito del cliente, (5) autorizza digitalmente la +richiesta utilizzando la firma digitale specifica della propria filiale +e inoltra la richiesta e la moneta accecata alla banca centrale per la +firma. La banca centrale (6) sottrae il valore della moneta dal conto +della banca commerciale, appone la firma cieca sulla moneta +utilizzando la chiave privata che detiene per il relativo valore e (7) +restituisce la firma cieca $s'$ alla banca commerciale. La banca +commerciale (8) inoltra la firma cieca $s'$ al portafoglio elettronico +del cliente. Infine, il dispositivo del cliente (9) utilizza $b$ per +rimuovere l'accecamento dalla firma ($\to$ $f$) e salva la moneta appena +coniata $(c, s)$. + +Per spendere CBDC, la procedura è analoga al pagamento in contanti. +Tuttavia, per consolidare la transazione, il venditore deve depositare +la moneta. La procedura per spendere CBDC è illustrata nel diagramma 2. + +\begin{figure}[h!] + \includegraphics[width=\textwidth]{diagramma2-it.png} + \caption{Spendere e depositare CBDC} + \label{fig:fig2} +\end{figure} + +Un cliente e un venditore negoziano un contratto commerciale. Il +cliente (1) utilizza una moneta elettronica per firmare il contratto o +l'atto di vendita con la chiave privata $c$ della moneta e trasmette la +firma al venditore. La firma di una moneta su un contratto con una +moneta valida è l'istruzione del cliente di pagare il venditore, che è +identificato dal conto bancario nel contratto. Se una singola moneta +non fosse sufficiente per coprire l'importo totale, i clienti possono +firmare il contratto con più monete. Il venditore (2) convalida quindi +la firma della moneta sul contratto e la firma $s$ della banca centrale +su $f$, che corrisponde a quella della moneta $C$ con le rispettive +chiavi pubbliche, e inoltra la moneta firmata (insieme alle +informazioni sul conto del venditore) alla banca commerciale del +venditore. La banca commerciale del venditore (3) conferma che il +venditore è un suo cliente e inoltra la moneta firmata alla banca +centrale. La banca centrale (4) verifica le firme e controlla il +proprio database per accertarsi che la moneta non sia già stata spesa. +Se tutto è in ordine, la banca centrale (5) aggiunge la moneta +all'elenco delle monete spese, l'accredita sul conto della banca +commerciale presso la banca centrale e (6) invia una conferma in tal +senso alla banca commerciale. Quindi la banca commerciale (7) +accredita la moneta sul conto del venditore e (8) gli invia una +notifica. Il venditore (9) consegna il prodotto o servizio al cliente. +L'intera operazione richiede poche centinaia di millisecondi. + +\hypertarget{considerazioni-sulla-sicurezza}{% +\subsection{Considerazioni sulla sicurezza} +\label{considerazioni-sulla-sicurezza}} + +Nella nostra proposta, occorre che la banca centrale gestisca un +database e un servizio online ad alta disponibilità. Poiché le monete +elettroniche possono essere copiate dagli utenti, solo con i controlli +online si può prevenire in modo efficace la doppia spesa. Sebbene +nella teoria esistano soluzioni per identificare a posteriori gli +utenti che effettuano una doppia spesa~\cite[vedi][]{Chaum1990}, +queste soluzioni creano rischi economici sia per gli utenti che per la +banca centrale a causa del ritardo nell'identificazione di +transazioni fraudolente. Il rilevamento online della doppia spesa +elimina questo rischio, ma significa anche che sarà impossibile +effettuare le transazioni se la connessione Internet alla banca +centrale non è disponibile. + +La banca centrale dovrà anche proteggere la riservatezza delle chiavi +private che utilizza per firmare le monete e altri messaggi di +protocollo. Se le chiavi di firma della banca centrale dovessero +essere compromesse, ad esempio da un computer quantistico, da un +attacco fisico ai \textit{datacenter} o anche da qualche nuovo algoritmo +% FIXME: +% forme alternative: +% 1) "rimborsare AGLI utenti ... tutte le monete non spese" +% 2) "rimborsare gli utenti ... DI tutte le monete non spese" +%FIXED +imprevisto, è possibile rimborsare agli utenti --- in tutta sicurezza e +senza compromettere la privacy --- tutte le monete non spese. La banca +centrale annuncerebbe la revoca della chiave tramite l'\textit{Application +Programming Interface} (API), che verrebbe rilevata dai portafogli, +avviando quindi il seguente protocollo di aggiornamento: l'utente +svela alla banca centrale la chiave pubblica $C$ della moneta, la firma +$s$ della banca centrale e il fattore di accecamento $b$, consentendo così +alla banca centrale di verificare il legittimo prelievo dell'utente e +di rimborsare il valore della moneta non spesa. Per rilevare una +possibile compromissione della propria chiave, la banca centrale può +monitorare il database in cerca di depositi che eccedano i prelievi. + +\subsection{Scalabilità e costi}\label{scalabilità-e-costi} + +Lo schema che proponiamo sarebbe efficiente ed economico quanto i +moderni sistemi RTGS attualmente utilizzati dalle banche centrali. + +La scalabilità si riferisce al costo di aumentare la potenza di +calcolo in modo che si possa concludere un numero crescente di +transazioni in tempi adeguati. Il costo complessivo del sistema può +essere basso in quanto la CBDC qui proposta si basa interamente su +software. Le monete spese devono essere conservate fino alla scadenza +della coppia di chiavi di valore utilizzata per firmare le monete, ad +esempio tramite un ciclo annuale continuo, che mantiene limitata la +dimensione del database. La potenza di calcolo e la larghezza di banda +necessarie aumentano della stessa quantità per ogni transazione, spesa +o deposito addizionali, dato che le transazioni sono intrinsecamente +indipendenti l'una dall'altra. Questa ulteriore potenza si ottiene +semplicemente aggiungendo più hardware, una pratica spesso conosciuta +come partizionamento o \textit{sharding}. Grazie al cosiddetto +\textit{consistent hashing}, le aggiunte di hardware non risultano +dirompenti. Si può anche utilizzare qualsiasi tipo di database. + +Più nello specifico, la logica del \textit{front-end} presso la banca +centrale deve solo eseguire poche operazioni di firma, e un singolo +processore può eseguirne alcune migliaia al secondo~\cite[vedi][]{Bernstein2020}. +Se un unico sistema non fosse sufficiente, è facile aggiungere altri +server \textit{front-end} e invitare le varie banche commerciali a +bilanciare le loro richieste nella \textit{server farm} o +utilizzare un sistema di bilanciamento del carico per distribuire le +richieste all'interno dell'infrastruttura della banca centrale. + +I server \textit{front-end} devono comunicare con un database per +effettuare le transazioni e prevenire la doppia spesa. Un unico server +di database moderno dovrebbe essere in grado di gestire in modo +affidabile decine di migliaia di operazioni al secondo. Le operazioni +possono essere facilmente distribuite su più server di database +semplicemente assegnando a ciascuno un intervallo di valori da +gestire. Tale configurazione garantisce che le singole transazioni non +incrocino mai le partizioni. Pertanto, anche i sistemi \textit{back-end} +dovrebbero scalare in modo lineare con le risorse di calcolo messe a +disposizione, partendo sempre da una solida base di riferimento per un +singolo sistema. + +I \textit{front-end} devono anche comunicare con i \textit{back-end} per +mezzo di un'interconnessione. Queste interconnessioni possono +supportare un gran numero di transazioni al secondo. La dimensione di +una singola transazione è in genere di circa 1–10 kilobyte. Pertanto, +i \textit{datacenter} di oggi, che scambiano informazioni a 400 Gbit/s, +possono supportare milioni di transazioni al secondo. + +%FIXME: +% +% Sotto appare "Probabilmente + congiuntivo". Suggerirei +% di cambiarlo con una forma all'indicativo. Qui si trova +% una discussione a riguardo: +% https://italian.stackexchange.com/questions/3653/probabilmente-indicativo-o-congiuntivo +% Not incorrect but FIXED anyway. + +Infine, il costo totale del sistema è basso. Il costo principale è +rappresentato dall'archiviazione a lungo termine di 1–10 kilobyte +per transazione. Gli esperimenti su un prototipo di GNU Taler che +utilizzava i prezzi di \textit{Amazon Web Service} hanno stabilito +che il costo del sistema (archiviazione, larghezza di banda e capacità +di calcolo) su larga scala sarebbe inferiore a 0,0001 USD per +transazione~\cite[per i dettagli sui dati, si veda][]{Dold}. + +\section{Considerazioni normative e politiche} + \label{5.-considerazioni-normative-e-politiche} + +Nella soluzione che proponiamo, la banca centrale non conosce +l'identità dei consumatori o dei venditori né l'importo totale delle +transazioni, ma vede solo il momento in cui le monete elettroniche vengono +rilasciate e quando vengono riscattate. Le banche commerciali continuano a +fornire l'autenticazione cruciale di consumatori e venditori e, in particolare, +custodiscono le informazioni che acquisiscono per la conoscenza dei clienti +(KYC). Le banche commerciali osservano quando i venditori ricevono fondi e, se +necessario, possono limitare la quantità di CBDC per transazione che +un singolo venditore può ricevere. Inoltre, le transazioni sono +collegate ai relativi contratti con i clienti. La conseguente +trasparenza del reddito consente al sistema di soddisfare i requisiti +delle normative sulla lotta al riciclaggio di denaro e al +finanziamento del terrorismo (AML e CFT). In caso vengano rilevate +anomalie nei redditi dei venditori, la banca commerciale e +l'autorità fiscale o giudiziaria possono ottenere e ispezionare i +contratti relativi ai pagamenti sospetti al fine di verificarne la +legittimità. La trasparenza del reddito risultante è anche una forte +misura contro l'evasione fiscale perché i venditori non possono +sottodichiarare il proprio reddito o evadere le tasse sulle vendite. +Nel complesso, il sistema implementa gli approcci~\textit{privacy-by-design} +e \textit{privacy-by-default} (come richiesto, ad esempio, +dal Regolamento generale sulla protezione dei dati dell'UE, GDPR). I +venditori non apprendono necessariamente l'identità dei propri clienti, +le banche possiedono solo le informazioni necessarie sulle attività dei +propri clienti e la banca centrale non ha accesso ai dettagli sulle +attività dei cittadini. + +In alcuni paesi le normative impongono limiti per i prelievi e i +pagamenti in contanti. Tali restrizioni possono essere implementate +anche per la CBDC nel progetto proposto. Ad esempio, è possibile +stabilire una soglia per l'importo giornaliero che i consumatori possono +prelevare, oppure limitare l'importo totale di CBDC che le banche +commerciali possono convertire. + +La disintermediazione del settore bancario è uno dei rischi di +instabilità finanziaria spesso sollevato per quanto riguarda la CBDC +al dettaglio. In particolare, una CBDC al dettaglio potrebbe +facilitare l'accumulo di ingenti somme di denaro della banca +centrale, il che potrebbe avere un impatto negativo sul finanziamento +alle banche mediante depositi perché il pubblico deterrebbe meno +denaro sotto forma di depositi bancari. Per i paesi le cui valute +fungono da valute rifugio, ciò potrebbe anche portare ad un aumento +degli afflussi di capitali durante i periodi globali di avversione al +rischio, dando luogo ad ulteriori pressioni sui tassi di cambio. +Quello che quindi potrebbe rappresentare un serio problema nel caso di +una CBDC basata su conti, lo sarebbe molto meno con una CBDC basata +su token. Innanzitutto, l'accumulo di una CBDC basata su token comporta +rischi di furto o perdita simili a quelli legati all'accumulo di +contanti. Tenere poche centinaia di dollari su uno smartphone è +probabilmente un rischio accettabile per molti, ma detenere una somma +molto alta è probabilmente un rischio meno accettabile. Pertanto, non +ci aspettiamo un accaparramento significativamente maggiore rispetto a +quello del denaro fisico. + +Tuttavia, se l'accumulo o la massiccia conversione dei depositi +bancari in CBDC dovessero destare preoccupazione, la banca centrale +avrebbe diverse opzioni. Come si è spiegato, secondo il progetto +proposto le banche centrali fissano una data di scadenza per tutte le +chiavi di firma, il che implica che in una data prestabilita le monete +firmate con quelle chiavi diventano non valide. Alla scadenza delle +chiavi di valore, i consumatori devono scambiare con monete nuove le +monete che erano state firmate con le vecchie chiavi; l'autorità di +regolamentazione può facilmente fissare una soglia di conversione per +cliente per creare un limite rigido alla quantità di CBDC che ogni +individuo può accumulare. Inoltre, la banca centrale potrebbe addebitare +commissioni, se necessario. Una commissione di aggiornamento quando le monete +stanno per scadere significherebbe nella pratica tassi di interesse negativi +sulla CBDC per limitare il suo fascino come riserva di valore, come +suggerisce~\cite{Bindseil}. Si tratterebbe infatti della diretta attuazione +dell'idea di Silvio Gesell di applicare una tassa di possesso sulla moneta, +notoriamente citata da~\cite{Keynes} e ripresa da~\cite{Goodfriend}, +\cite{Buiter} e~\cite{Agarwal}. + +Per quanto riguarda le implicazioni in termini di politica monetaria, +non dovrebbero esserci cambiamenti reali perché la nostra CBDC è +progettata per replicare il contante piuttosto che i depositi bancari. +L'emissione, il prelievo e il deposito della nostra CBDC corrispondono +esattamente all'emissione, al prelievo e al deposito di banconote. È +possibile che la velocità di circolazione di una CBDC al dettaglio sia +diversa da quella del contante fisico, ma questo non dovrebbe +rappresentare un problema significativo per la politica monetaria. + +\hypertarget{lavori-correlati}{% +\section{Lavori correlati}\label{6.-lavori-correlati}} + +Come segnalato in precedenza, la CBDC che si propone in questo documento +si basa su eCash e GNU Taler.\footnote{L'implementazione di eCash +da parte della società DigiCash negli anni novanta è documentata su \\ +\url{https://www.chaum.com/ecash}.} A partire dalla proposta originale +e-Cash di Chaum, la ricerca si è concentrata su tre questioni principali. +In primo luogo, nella proposta originale di Chaum le monete avevano un +valore fisso e potevano essere spese solo nella loro totalità. Pagare +grandi somme con monete denominate in centesimi sarebbe stato poco +efficiente; quindi~\cite{Okamoto}, \cite{Camenisch2005}, \cite{Canard} +e~\cite{Dold} idearono modi per affrontare il problema. Queste soluzioni +comprendono protocolli per dare il resto o rendere divisibili le monete. + +Un secondo problema riguarda gli errori nelle transazioni dovuti ad +interruzioni della rete. In questo caso, il sistema deve garantire che +i fondi rimangano in possesso del consumatore senza pregiudicare la +privacy. L'\textit{Endorsed E-Cash} proposto da~\cite{Camenisch2007}, +così come da~\cite{Dold}, affrontano entrambi questo problema. Molte +delle soluzioni violano le garanzie sulla privacy per i clienti che +utilizzano queste funzionalità e tutte, tranne Taler, violano il +requisito della trasparenza del reddito. + +La terza questione importante, spesso trascurata, è la trasparenza del +reddito e quindi la conformità con i requisiti AML e KYC. \cite{Fuchsbauer} +hanno deliberatamente progettato il loro sistema di disintermediazione +per fornire una semantica più simile al contante. Tuttavia, la +disintermediazione totale è in genere difficile da concialiare con le +normative AML e KYC dato che diventa impossibile raggiungere qualsiasi +livello di responsabilità. Un esempio di tale architettura è ZCash, un +registro distribuito (\textit{ledger}) che nasconde dalla rete le +informazioni sul pagatore, sul beneficiario e sull'importo della +transazione, rendendolo quindi il sistema di pagamento perfetto per la +criminalità online. Solo Taler offre sia una privacy costante per i +clienti che la trasparenza del reddito, fornendo al contempo un sistema +di resto efficiente, scambi atomici~\cite[vedi][]{Camenisch2007} e la +possibilità di ripristinare i portafogli dal backup. + +Per quanto riguarda i sistemi di pagamento per le CBDC, \cite{Danezis} +hanno progettato un \textit{ledger} scalabile per RSCoin. Si tratta +fondamentalmente di un sistema RTGS che viene protetto utilizzando la +stessa crittografia che si usa in Bitcoin. Come Taler, il design utilizza +lo \textit{sharding} del database per consentire la scalabilità lineare. +Tuttavia, la soluzione di Danezis e Meiklejohn non prevede alcuna +disposizione per la privacy e manca di elementi per l'integrazione +pratica del design con i sistemi e i processi bancari esistenti. + +L'EUROchain della Banca Centrale Europea\cite[vedi][]{ECB} è un altro +prototipo di CBDC con registro distribuito. Simile all'architettura +proposta in questo documento, EUROchain utilizza un'architettura a due +livelli in cui le banche commerciali agiscono come intermediari. Una +differenza cruciale è il modo in cui i sistemi cercano di combinare +privacy e conformità con la normativa antiriciclaggio (AML). Mentre nel +nostro progetto l'autorità di regolamentazione può imporre un limite +alla somma di denaro elettronico che un titolare di conto bancario può +prelevare in un determinato periodo di tempo, EUROchain emette un numero +limitato di «voucher di anonimato» che garantiscono al destinatario un +numero limitato di transazioni senza controlli AML. Poiché questi voucher +sembrano essere privi di qualsiasi token di valore, non è chiaro come +il design possa impedire l'emergere di un mercato nero per i «voucher +di anonimato». Inoltre, la nozione di anonimato di EUROchain è molto +diversa, in quanto i loro «voucher di anonimato» eliminano solo alcuni +controlli AML, preservando la capacità delle banche commerciali di +sapere in che modo i clienti spendono il denaro elettronico. Laddove chi +paga utilizzando Taler interagisce direttamente con i venditori per +spendere il proprio contante elettronico, il sistema EUROchain chiede +ai pagatori di istruire le proprie banche commerciali per accedere alle +CBDC. Pertanto, EUROchain non emette direttamente token di valore ai +consumatori, affida invece ai consumatori il compito di autenticarsi +presso la propria banca commerciale per accedere alle CBDC che la +banca centrale detiene effettivamente in deposito a garanzia. Non è +quindi evidente quali siano i vantaggi di EUROchain in termini di +privacy, prestazioni o sicurezza rispetto all'attuale denaro in deposito. + +\section{Conclusione}\label{7.-conclusione} + +Con l'emergere di Bitcoin e valute digitali come Diem (già nota come +Libra) recentemente proposte dai colossi del web, le banche centrali +affrontano una crescente concorrenza da parte di operatori privati che +offrono la propria alternativa digitale al contante fisico. Le decisioni +delle banche centrali sull'emissione o meno di una CBDC dipendono dalla +loro valutazione dei benefici e dei rischi di una CBDC. È probabile che +questi vantaggi e rischi, nonché le circostanze giurisdizionali +specifiche che definiscono l'ambito di applicazione di una CBDC al +dettaglio, differiscano da un paese all'altro. + +Se una banca centrale decide di emettere una CBDC al dettaglio, +proponiamo una CBDC basata su token che combina la privacy delle +transazioni con la conformità alle normative KYC, AML e CFT. Tale CBDC +non sarebbe in concorrenza con i depositi presso le banche commerciali, +replicherebbe piuttosto il contante fisico, limitando quindi i rischi di +stabilità finanziaria e di perturbazione della politica monetaria. + +Abbiamo dimostrato che lo schema qui proposto sarebbe efficiente ed +economico quanto i moderni sistemi RTGS gestiti dalle banche centrali. +I pagamenti elettronici con la nostra CBDC richiederebbero solo un +semplice database e minuscole quantità di larghezza di banda per le +transazioni. L'efficienza e l'economicità di questa soluzione, insieme +alla maggiore facilità d'uso da parte del consumatore determinata dal +passaggio dall'autenticazione all'autorizzazione, rendono questo schema +probabilmente il primo a supportare l'annoso obiettivo dei micropagamenti +online. Inoltre, l'uso di monete per firmare crittograficamente contratti +elettronici consente anche l'impiego di contratti intelligenti. Ciò +potrebbe anche portare all'emergere di applicazioni completamente nuove +per i sistemi di pagamento. Sebbene il nostro sistema non sia basato su +DLT, può essere facilmente integrato con tali tecnologie se richiesto +dalle future infrastrutture del mercato finanziario. + +Altrettanto importante, una CBDC al dettaglio deve rimanere, come il +contante fisico, un bene rispettoso della privacy sotto il controllo +individuale dei cittadini. Lo schema proposto in questo studio soddisfa +questo criterio e consente alle banche centrali di evitare gravi sfide +alla loro politica monetaria e alla stabilità finanziaria sfruttando al +contempo i vantaggi del passaggio al digitale. + +\newpage +\bibliographystyle{agsm-mod} +\bibliography{cbdc-it} +\end{document} diff --git a/doc/cbdc-it/cbdc.bib b/doc/cbdc-it/cbdc.bib new file mode 100644 index 000000000..fe0ea6265 --- /dev/null +++ b/doc/cbdc-it/cbdc.bib @@ -0,0 +1,566 @@ +@article{Adrian, + author = {Adrian, Tobias and Tommaso Mancini-Griffoli}, + year = {2019}, + title = {The Rise of Digital Money}, + journal = {IMF Fintech Note}, + volume = {19/01}, +} + +@article{Agarwal, + author = {Agarwal, Ruchir and Miles S. Kimball}, + year = {2019}, + title = {Enabling Deep Negative Rates to Fight Recessions: A Guide}, + journal = {IMF Working Paper}, + volume = {19/84}, +} + + +@article{Agur, + author = {Agur, Itai and Anil Ari and Giovanni Dell'Ariccia}, + year = {2019}, + title = {Designing Central Bank Digital Currencies}, + journal = {IMF Working Paper}, + volume = {19/252}, +} + +@article{Allen, + author = {Allen, Sarah and Srđjan Čapkun and Ittay Eyal and Giulia Fanti and Bryan A. Ford and James Grimmelmann and Ari Juels and Kari Kostiainen and Sarah Meiklejohn and Andrew Miller and Eswar Prasad and Karl Wüst and Fan Zhang}, + year = {2020}, + title = {Design Choices for Central Bank Digital Currency: Policy and Technical Considerations}, + journal = {NBER Working Paper}, + volume = {27634}, +} + +@article{Alves, + author = {Alves, Tiago and Don Felton}, + year = {2004}, + title = {TrustZone: Integrated hardware and software security}, + journal = {ARM IQ}, + volume = {3}, + number = {4}, + pages = {18--24}, +} + +@article{AuerBoehme, + author = {Auer, Raphael and Rainer Böhme}, + year = {2020}, + title = {The technology of retail central bank digital currency}, + journal = {BIS Quarterly Review}, + month = {March}, + pages = {85--96}, +} + +@article{AuerCornelli, + author = {Auer, Raphael and Giulio Cornelli and Jon Frost}, + year = {2020}, + title = {Taking stock: ongoing retail {CBDC} projects}, + journal = {BIS Quarterly Review}, + month = {March}, + pages = {97--98}, +} + +@booklet{BIS, + author = {{Bank for International Settlements}}, + year = {2018}, + title = {Central Bank Digital Currencies. Joint Report of the Committee on Payments and Market Infrastructures and Markets Committee}, +} + +@booklet{BoE, + author = {{Bank of England}}, + year = {2020}, + title = {Central Bank Digital Currency: Opportunities, Challenges and Design. Discussion Paper}, + month = {March}, +} + +@article{Baiocchi, + author = {Baiocchi, Giovanni and Walter Distaso}, + year = {2003}, + title = {{GRETL}: Econometric Software for the {GNU} Generation}, + journal = {Journal of Applied Econometrics}, + volume = {18}, + pages = {105-110}, +} + +@article{Bech, + author = {Bech, Morten and Rodney Garratt}, + year = {2017}, + title = {Central bank cryptocurrencies}, + journal = {BIS Quarterly Review}, + month = {September}, + pages = {55--70}, +} + +@article{Berentsen, + author = {Berentsen, Aleksander and Fabian Schär}, + year = {2018}, + title = {The Case for Central Bank Electronic Money and the Non-case for Central Bank Cryptocurrencies}, + journal = {Federal Reserve Bank of St. Louis Review}, + volume = {100}, + number = {2}, + pages = {97--106}, +} + +@article{Bernstein2020, + author = {Bernstein, Daniel J. and Tanja Lange}, + year = {2020}, + title = {{eBACS}: {ECRYPT} Benchmarking of Cryptographic Systems}, + url = {\url{https://bench.cr.yp.to}, accessed 17 March 2020}, +} + +@article{Bernstein2012, + author = {Bernstein, Daniel J. and Niels Duif and Tanja Lange and Peter Schwabe and Bo-Yin Yang}, + year = {2012}, + title = {High-speed high-security signatures}, + journal = {Journal of Cryptographic Engineering}, + volume = {2}, + pages = {77--89}, +} + +@InCollection{Bindseil, + author = {Bindseil, Ulrich}, + year = {2020}, + title = {Tiered {CBDC} and the financial system}, + publisher = {European Central Bank}, + series = {ECB Working Paper}, + number = {2351}, + month = {January}, +} + +@article{Boar, + author = {Boar, Codruta and Henry Holden and Amber Wadsworth}, + year = {2020}, + title = {Impending arrival - a sequel to the survey on central bank digital currency}, + journal = {BIS Papers}, + volume = {107}, +} + +@article{Boneh, + author = {Boneh, Dan}, + year = {1999}, + title = {Twenty Years of Attacks on the {RSA} Cryptosystem}, + journal = {Notices of the AMS}, + volume = {42}, + number = {2}, + pages = {202--213}, +} + + +@InCollection{Bordo, + author = {Bordo, Michael D. and Andrew T. Levin}, + year = {2017}, + title = {Central bank digital currency and the future of monetary policy}, + publisher = {National Bureau of Economic Research}, + series = {NBER Working Paper Series}, + number = {23711}, +} + +@article{Brunnermeier, + author = {Brunnermeier, Markus and Dirk Niepelt}, + year = {2019}, + title = {On the Equivalence of Private and Public Money}, + journal = {Journal of Monetary Economics}, + volume = {106}, + pages = {27--41}, +} + +@article{Buiter, + author = {Buiter, Willem H. and Nikolaos Panigirtzoglou}, + year = {2003}, + title = {Overcoming the Zero Bound on Nominal Interest Rates with Negative Interest on Currency: Gesell's Solution}, + journal = {The Economic Journal}, + volume = {113}, + number = {490}, + pages = {723--746}, +} + +@InCollection{Bullmann, + author = {Bullmann, Dirk and Jonas Klemm and Andrea Pinna}, + year = {2019}, + title = {In search for stability in crypto-assets: are stablecoins the solution?}, + publisher = {European Central Bank}, + series = {ECB Occasional Paper Series}, + number = {230}, +} + +@inproceedings{Camenisch2007, + author = {Camenisch, Jan and Aanna Lysyanskaya and Mira Meyerovich}, + year = {2007}, + title = {Endorsed E-Cash}, + booktitle = {2007 IEEE Symposium on Security and Privacy (SP'07)}, + month = {May}, + pages = {101--115}, +} + +@inproceedings{Camenisch2005, + author = {Camenisch, Jan and Susan Hohenberger and Anna Lysyanskaya}, + year = {2005}, + title = {Compact E-Cash}, + booktitle = {Advances in Cryptology -- EUROCRYPT 2005: 24th Annual International Conference on the Theory and Applications of Cryptographic Techniques}, + address = {Aarhus, Denmark}, + month = {May}, + day = {22-26}, + editor = {Ed. by Ronald Cramer}, + publisher = {Springer-Verlag Berlin Heidelberg}, +} + + + +@inproceedings{Canard, + author = {Canard, Sébastien and Aline Gouget}, + year = {2007}, + title = {Divisible e-cash systems can be truly anonymous}, + booktitle = {Annual International Conference on the Theory and Applications of Cryptographic Techniques}, + pages = {482--497}, +} + + + +@misc{CCC, + author = {{CCC e.V.}}, + year = {2017}, + title = {Chaos Computer Club hacks e-motor charging stations}, + howpublished = {34c3}, +} + +@article{Chapman, + author = {Chapman, James and Rodney Garratt and Scott Hendry and Andrew McCormack and Wade McMahon}, + year = {2017}, + title = {Project {J}asper: Are Distributed Wholesale Payment Systems Feasible Yet?}, + journal = {Financial System Review}, + publisher = {Bank of Canada}, + month = {June}, + pages = {59--69}, +} + +@inproceedings{Chaum1983, + author = {Chaum, David}, + year = {1983}, + title = {Blind signatures for untraceable payments}, + booktitle = {Advances in Cryptology: Proceedings of Crypto `82}, + pages = {199--203}, +} + +@inproceedings{Chaum1990, + author = {Chaum, David and Amos Fiat and Moni Naor}, + year = {1990}, + title = {Untraceable electronic cash}, + booktitle = {Advances in Cryptology: Proceedings of CRYPTO '88}, + pages = {319--327}, +} + +@inproceedings{Danezis, + author = {Danezis, George and Sarah Meiklejohn}, + year = {2016}, + title = {Centrally Banked Cryptocurrencies}, + booktitle = {23nd Annual Network and Distributed System Security Symposium, NDSS2016}, + address = {San Diego, California, USA}, + month = {February}, + day = {21--24}, + publisher = {The Internet Society}, +} + +@article{Diffie, + author = {Diffie, Whitfield and Martin Hellmann}, + year = {1976}, + title = {New Directions in Cryptography}, + journal = {IEEE Trans. on Inf. Theory, IT-22}, + pages = {644--654}, +} + +@phdthesis{Dold, + author = {Dold, Florian}, + year = {2019}, + title = {The {GNU} {T}aler System: Practical and Provably Secure Electronic Payments. PhD Thesis}, + school = {University of Rennes 1}, +} + +@article{ECB, + author = {{European Central Bank}}, + year = {2019}, + title = {Exploring anonymity in central bank digital currencies}, + journal = {In Focus}, + number = {4}, + month = {December}, +} + +@inproceedings{Fuchsbauer, + author = {Fuchsbauer, Georg and David Pointcheval and Damien Vergnaud}, + year = {2009}, + title = {Transferable constant-size fair e-cash}, + booktitle = {International Conference on Cryptology and Network Security}, + publisher = {Springer-Verlag Berlin Heidelberg}, + pages = {226--247}, +} + +@inproceedings{Garcia, + author = {Garcia, Flavio and Gerhard de Koning Gans and Ruben Muijrers and Peter van Rossum and Roel Verdult and Ronny Wichers Schreur and Bart Jacobs}, + year = {2008}, + title = {Dismantling MIFARE Classic}, + booktitle = {European Symposium on Research in Computer Security}, +} + +@article{Garratt, + author = {Garratt, Rod and Michael Lee and Brendan Malone and Antoine Martin}, + year = {2020}, + title = {Token- or Account-Based? A Digital Currency Can Be Both}, + journal = {Liberty Street Economics}, + publisher = {Federal Reserve Bank of New York}, + month = {August}, + day = {12}, +} + +@article{Goodfriend, + author = {Goodfriend, Marvin}, + year = {2000}, + title = {Overcoming the Zero Bound on Interest Rate Policy}, + journal = {Journal of Money, Credit, and Banking}, + volume = {32}, + number = {4}, + pages = {1007--1035}, +} + +@article{Johnston, + author = {Johnston, Casey}, + year = {2010}, + title = {PS3 hacked through poor cryptography implementation}, + journal = {Ars Technica}, + month = {December}, + day = {30}, +} + + + +@Misc{Jordan, + note = {Speech given at the 30th anniversary of the WWZ and VBÖ}, + author = {Jordan, Thomas J.}, + year = {2019}, + title = {Currencies, money and digital tokens}, + publisher = {University of Basel}, + month = {September}, + howpublished = {\url{https://www.snb.ch/en/mmr/speeches/id/ref\_20190905\_tjn/source/ref\_20190905\_tjn.en.pdf}}, +} + + +@article{Kahn2009, + author = {Kahn, Charles M. and William Roberds}, + year = {2009}, + title = {Why Pay? An Introduction to Payments Economics}, + journal = {Journal of Financial Intermediation}, + number = {18}, + pages = {1--23}, +} + +@article{Kahn2005, + author = {Kahn, Charles M. and James McAndrews and William Roberds}, + year = {2005}, + title = {Money is Privacy}, + journal = {International Economic Review}, + volume = {46}, + number = {2}, + pages = {377--399}, +} + +@article{Kasper, + author = {Kasper, Timo and Michael Silbermann and Christof Paar}, + year = {2010}, + title = {All you can eat or breaking a real-world contactless payment system}, + journal = {Financial Cryptography and Data Security, Lecture Notes in Computer Science}, + volume = {6052}, + pages = {343--50}, +} + +@inproceedings{Katzenbeisser, + author = {Katzenbeisser, Stefan and Ünal Kocabaş and Vladimir Rožić and Ahmad-Reza Sadeghi and Ingrid Verbauwhede and Christian Wachsmann}, + year = {2012}, + title = {{PUF}s: Myth, Fact or Busted? A Security Evaluation of Physically Unclonable Functions ({PUF}s) Cast in Silicon}, + booktitle = {Cryptographic Hardware and Embedded Systems -- CHES 2012. Lecture Notes in Computer Science}, + volume = {7428}, + pages = {283--301}, +} + +@book{Keynes, + author = {Keynes, John Maynard}, + year = {1936}, + title = {The General Theory of Employment, Interest and Money}, + publisher = {Macmillan}, +} + +@article{Kiff, + author = {Kiff, John and Jihad Alwazir and Sonja Davidovic and Aquiles Farias and Ashraf Khan and Tanai Khiaonarong and Majid Malaika and Hunter Monroe and Nobu Sugimoto and Hervé Tourpe and Peter Zhou}, + year = {2020}, + title = {A Survey of Research on Retail Central Bank Digital Currency}, + journal = {IMF Working Paper}, + volume = {20/104}, +} + +@InCollection{Kumhof, + author = {Kumhof, Michael and Clare Noone}, + year = {2018}, + title = {Central bank digital currencies - design principles and balance sheet implications}, + publisher = {Bank of England}, + series = {Staff Working Paper}, + number = {725}, +} + +@inproceedings{Lapid, + author = {Lapid, Ben and Avishai Wool}, + year = {2018}, + title = {Cache-Attacks on the {ARM} TrustZone Implementations of {AES}-256 and {AES}-256-{GCM} via {GPU}-Based Analysis}, + booktitle = {International Conference on Selected Areas in Cryptography. Lecture Notes in Computer Science}, + volume = {11349}, +} + +@article{Lerner, + author = {Lerner, Josh and Jean Tirole}, + year = {2005}, + title = {The Scope of Open Source Licensing}, + journal = {Journal of Law, Economics \& Organization}, + volume = {21}, + pages = {20-56}, +} + +@misc{Libra, + author = {{Libra Association}}, + year = {2020}, + title = {Libra White Paper v2.0}, + url = {\url{https://libra.org/en-US/white-paper}}, +} + +@inproceedings{Lim, + author = {Lim, Chae Hoon and Phil Joong Lee}, + year = {1997}, + title = {A key recovery attack on discrete log-based schemes using a prime order subgroup}, + booktitle = {CRYPTO 1997. Lecture Notes in Computer Science}, + volume = {1294}, +} + +@InCollection{Lyons, + author = {Lyons, Richard K. and Ganesh Viswanath-Natraj}, + year = {2020}, + title = {What Keeps Stablecoins Stable?}, + publisher = {National Bureau of Economic Research}, + series = {NBER Working Paper Series}, + number = {27136}, + month = {May}, +} + +@article{Mancini-Griffoli, + author = {Mancini-Griffoli, Tommaso and Maria Soledad Martinez Peria and Itai Agur and Anil Ari and John Kiff and Adina Popescu and Celine Rochon}, + year = {2018}, + title = {Casting Light on Central Bank Digital Currency}, + journal = {IMF Staff Discussion Notes}, + volume = {18/08}, + publisher = {International Monetary Fund}, +} + +@misc{Nakamoto, + author = {Nakamoto, Satoshi}, + year = {2008}, + title = {Bitcoin: A Peer-to-Peer Electronic Cash System}, + url = {\url{https://www.bitcoin.com/bitcoin.pdf}}, +} + +@book{Narayanan, + author = {Narayanan, Arvind and Joseph Bonneau and Edward Felten and Andrew Miller and Steven Goldfeder}, + year = {2016}, + title = {Bitcoin and Cryptocurrency Technologies: A Comprehensive Introduction}, + publisher = {Princeton University Press}, +} + +@misc{Niepelt, + author = {Niepelt, Dirk}, + year = {2020}, + title = {Digital money and central bank digital currency: An executive summary for policymakers}, + url = {https://voxeu.org/article/digital-money-and-central-bank-digital-currency-executive-summary}, +} + +@inproceedings{Okamoto, + author = {Okamoto, Tatsuaki}, + year = {1995}, + title = {An Efficient Divisible Electronic Cash Scheme}, + booktitle = {Advances in Cryptology --- CRYPT0'95: 15th Annual International Cryptology Conference Santa Barbara, California, USA, August 27--31, 1995 Proceedings}, + editor = {Ed. by Don Coppersmith}, + publisher = {Springer-Verlag Berlin Heidelberg}, + pages = {438--451}, +} + +@article{Pinto, + author = {Pinto, S. and N. Santos}, + year = {2019}, + title = {Demystifying {ARM} TrustZone: A Comprehensive Survey}, + journal = {ACM Computing Surveys}, + volume = {51}, + number = {6}, + month = {January}, + pages = {1--31} +} + +@article{Rivest, + author = {Rivest, Ronald L. and Adi Shamir and Leonard Adleman}, + year = {1978}, + title = {A Method for Obtaining Digital Signatures and Public Key Cryptosystems}, + journal = {Comm. ACM}, + volume = {21}, + number = {2}, +} + +@book{Solove, + author = {Solove, Daniel J.}, + year = {2011}, + title = {Nothing to Hide: The false tradeoff between privacy and security}, + publisher = {New Haven \& London: Yale University Press}, +} + +@article{Soukup, + author = {Soukup, Michael and Bruno Muff}, + year = {2007}, + title = {Die {P}ostcard lässt sich fälschen}, + journal = {Sonntagszeitung}, + month = {April}, + day = {22}, +} + +@article{Stallman, + author = {Stallman, Richard}, + year = {1985}, + title = {The {GNU} manifesto}, + journal = {Dr. Dobb's Journal of Software Tools}, + volume = {10}, + number = {3}, + pages = {30--35}, +} + + +@TechReport{Riksbank, + author = {{Sveriges Riksbank}}, + year = {2020}, + title = {The {R}iksbank's e-krona project}, + month = {Feb}, + institution = {Sveriges Riksbank}, + url = {\url{https://www.riksbank.se/globalassets/media/rapporter/e-krona/2019/the-riksbanks-e-krona-pilot.pdf}}, +} + +@misc{Wojtczuk, + author = {Wojtczuk, Rafal and Joanna Rutkowska}, + year = {2009}, + title = {Attacking {I}ntel Trusted Execution Technology}, + howpublished = {BlackHat-DC 2009}, +} + +@article{Yalta2010, + author = {Yalta, A. Talha and A. Yasemin Yalta}, + year = {2010}, + title = {Should Economists Use Open Source Software for Doing Research?}, + journal = {Computational Economics}, + volume = {35}, + pages = {371--394}, +} + +@article{Yalta2008, + author = {Yalta, A. Talha and Riccardo Lucchetti}, + year = {2008}, + title = {The {GNU/L}inux Platform and Freedom Respecting Software for Economists}, + journal = {Journal of Applied Econometrics}, + volume = {23}, + pages = {279-286}, +} diff --git a/doc/cbdc-it/diagramma1-it.png b/doc/cbdc-it/diagramma1-it.png Binary files differnew file mode 100644 index 000000000..bd38d1df0 --- /dev/null +++ b/doc/cbdc-it/diagramma1-it.png diff --git a/doc/cbdc-it/diagramma2-it.png b/doc/cbdc-it/diagramma2-it.png Binary files differnew file mode 100644 index 000000000..171cb1045 --- /dev/null +++ b/doc/cbdc-it/diagramma2-it.png diff --git a/doc/cbdc-it/graphics-it.odp b/doc/cbdc-it/graphics-it.odp Binary files differnew file mode 100644 index 000000000..4c165ad5e --- /dev/null +++ b/doc/cbdc-it/graphics-it.odp diff --git a/doc/cs/ads/abbreviation.tex b/doc/cs/ads/abbreviation.tex new file mode 100644 index 000000000..9da168dcc --- /dev/null +++ b/doc/cs/ads/abbreviation.tex @@ -0,0 +1,48 @@ +%!TEX root = ../dokumentation.tex +\chapter*{Abbreviations} +\begin{acronym}[YTMMM] + \acro{AES}{Advanced Encryption Standard} + \acro{AML}{Anti Money Laundering} + \acro{API}{Application Programming Interface} + \acrodefplural{API}[APIs]{Application Programming Interfaces} + \acro{BIP}{Bitcoin Improvement Proposal} + \acro{CA}{Certificate Authority} + \acro{CDH}{Computational Diffie-Hellman} + \acro{CFT}{Combating Financing of Terrorism} + \acro{CMA}{Choosen-Message Attack} + \acro{CS}{Clause Blind Schnorr Signature Scheme} + \acro{CSRF}{Client-Side Request Forgery} + \acro{CWE}{Common Weakness Enumeration} + \acro{DDH}{Decisional Diffie-Hellman} + \acro{DHKE}{Diffie-Hellman key exchange} + \acro{DLP}{Discrete Logarithm Problem} + \acro{DSA}{Digital Signature Algorithm} + \acro{ECC}{Elliptic Curve Cryptography} + \acro{ECDH}{Elliptic Curve Diffie Hellman} + \acro{EdDSA}{Edwards-curve Digital Signature Algorithm} + \acro{EUF}{Existentially Unforgeability} + \acro{FDH}{Full-Domain Hash} + \acro{GNU AGPL}{GNU Affero General Public License} + \acro{GNU GPL}{GNU General Public License} + \acro{GNU LGPL}{GNU Lesser General Public License} + \acro{IPC}{Inter Process Communication} + \acro{JSON}{JavaScript Object Notation} + \acro{KDF}{Key Derivation Function} + \acro{KYC}{Know Your Customer} + \acro{MAC}{Message Authentication Code} + \acro{NIST}{National Institute of Standards and Technology} + \acro{MK}{Master Key} + \acro{PKI}{Public Key Infrastructure} + \acro{PRF}{Pseudo Random Function} + \acro{PoS}{Point-of-Sales} + \acro{PRNG}{Pseudo Random Number Generator} + \acro{RNG}{Random Number Generator} + \acro{ROS}{Random inhomogeneities in an Overdetermined, Solvable system of linear equations} + \acro{RT}{Round-Trip} + \acro{RTT}{Round-Trip Time} + \acro{SPOF}{Single Point of Failure} + \acro{SSRF}{Server-Side Request Forgery} + \acro{Taler}{GNU Taler} + \acro{TRNG}{True Random Number Generator} + \acro{URL}{uniform resource locator} +\end{acronym} diff --git a/doc/cs/ads/abstract.tex b/doc/cs/ads/abstract.tex new file mode 100644 index 000000000..0610eb10b --- /dev/null +++ b/doc/cs/ads/abstract.tex @@ -0,0 +1,26 @@ +\chapter*{Abstract} +GNU Taler is an intuitive, fast and socially responsible digital payment system implemented as free software. +While preserving the customers privacy, GNU Taler is still compliant to regulations. +\\\\ +The goal of this thesis is to improve Taler's performance and provide cipher agility by adding support for Schnorr's blind signatures. +To achieve this goal, the current state in research for Schnorr signatures needs to be analyzed. +After choosing a signature scheme, it has to be integrated into the Taler protocols. +Besides implementing the redesigned protocols in Taler, an implementation of the cryptographic routines is needed. +\\\\ +The paper "Blind Schnorr +Signatures and Signed ElGamal Encryption in the Algebraic Group Model" \cite{cryptoeprint:2019:877} from 2019 (updated in 2021) introducing \gls{CSBS} is used as theoretical basis for our improvements. +The paper explains why simple Blind Schnorr Signatures are broken and how the Clause Schnorr Blind Signature scheme is secured against this attack.\\ +Compared to the currently used \gls{RSABS}, the new scheme has an additional request, two blinding factors instead of one and many calculations are done twice to prevent attacks. +\\\\ +The Taler protocols were redesigned to support the Clause Blind Schnorr Signature scheme, including slight alterations to ensure \textit{abort-idempotency}, and then further specified. +Before starting with the implementation of the redesigned protocols, the cryptographic routines for \gls{CSBS} were implemented as part of the thesis. \\ +All of the implemented code is tested and benchmarks are added for the cryptographic routines. +\\\\ +Multiple results were achieved during this thesis: +The redesigned protocols Taler protocols with support for \gls{CSBS}, the implementation of the cryptographic routines, the implementation of Talers core protocols and a detailed comparison between \gls{RSABS} and \gls{CSBS}. +Overall, the \gls{CSBS} are significantly faster, require less disk space, and bandwidth and provide \textit{cipher agility} for Taler. + +\section*{Acknowledgement} +We would like to kindly thank Christian Grothoff (Bern University of Applied Sciences) for his extensive advice, support and very helpful feedback during our whole thesis.\\ +We also kindly thank Jeffrey Burdges (Web 3, Switzerland) for reviewing the proposal containing the redesigned protocols and giving feedback.\\ +Further, we kindly thank Jacob Appelbaum (Bern University of Applied Sciences, Eindhoven University of Technology) for further results for the performance measurements of our cryptographic routines and the insightful conversations. diff --git a/doc/cs/ads/glossary.tex b/doc/cs/ads/glossary.tex new file mode 100644 index 000000000..7132f89a5 --- /dev/null +++ b/doc/cs/ads/glossary.tex @@ -0,0 +1,53 @@ +%!TEX root = ../thesis.tex + +% +% vorher in Konsole folgendes aufrufen: +% makeglossaries makeglossaries dokumentation.acn && makeglossaries dokumentation.glo +% + +% +% Glossareintraege --> reference, name, beschreibung +% Aufruf mit \gls{...} +% +% \newglossaryentry{non-repudiation}{name={non-repudiation},plural={non-repudiation},description={After a message is signed, one can not dispute that a message was signed}} +% \newglossaryentry{sender_authenticity}{name={sender authenticity},plural={sender authenticity},description={The origin/sender of a message can not be forged}} +% \newglossaryentry{message_integrity}{name={message integrity},plural={message integrity},description={No unauthorized change to the message can be made, the message is tamperproof}} +\newglossaryentry{hkdf}{ + name = {HKDF}, + description = {The HMAC-based Extract-and-Expand Key Derivation Function is a function that takes potentially weak keying material as input and outputs high entropy keying material. For more information see section \ref{sec:kdf}} +} + +\newglossaryentry{25519}{ + name = {Curve25519}, + description = {A popular elliptic curve used in many cryptographic systems based on elliptic curve cryptography. See section \ref{par:curve25519}} +} + +\newglossaryentry{fdh}{ + name = {FDH}, + description = {A Full-Domain Hash is a hash function with an image size equal to the original gorup. See section \ref{sec:rsa-fdh}}. +} + +\newglossaryentry{idempotence}{ + name = {idempotence}, + description = {Idempotence in the context of computer science is a property to ensure that the state of system will not change, no matter how many times the same request was made. See section \ref{abort-idempotency}} +} + +\newglossaryentry{abort-idempotency}{ + name = {abort-idempotency}, + description = {Abort-idempotency is a special case of \gls{idempotence}. On every step in a protocol it needs to be ensured that even on an abort, the same request always receives the same response. See section \ref{abort-idempotency}} +} + +\newglossaryentry{RSABS}{ + name = {RSA Blind Signatures}, + description = {Chaums Blind Signature Scheme based on RSA. See section \ref{sec:blind-rsa-sign}} +} + +\newglossaryentry{CSBS}{ + name = {Clause Blind Schnorr Signatures}, + description = {A secure variant of Blind Schnorr Signature Schemes introduced in section \ref{sec:clause-blind-schnorr-sig}} +} + +% \newglossaryentry{25519}{ + % name = {}, + % description = {} +% } diff --git a/doc/cs/ads/header.tex b/doc/cs/ads/header.tex new file mode 100644 index 000000000..0b53317b5 --- /dev/null +++ b/doc/cs/ads/header.tex @@ -0,0 +1,71 @@ +% Hyperlinks +\usepackage[ + hidelinks, + pdfusetitle, +]{hyperref} + +% Grafiken +\usepackage{graphicx} +%Bildpfad +\graphicspath{{images/}} + +% Micro sign +\usepackage{siunitx} + +% Farben +\usepackage{color} +\definecolor{LinkColor}{rgb}{0,0,0.2} + +% Glossar +\usepackage[ + nonumberlist, %keine Seitenzahlen anzeigen + %acronym, %ein Abkürzungsverzeichnis erstellen + %section, %im Inhaltsverzeichnis auf section-Ebene erscheinen + toc, %Einträge im Inhaltsverzeichnis +]{glossaries} +\makeglossaries +\input{ads/glossary} + +%Nomenklatur +\usepackage{nomencl} +\makenomenclature + +%PDF pages +\usepackage{pdfpages} + +%Adjustbox (tikz figures of Taler) +\usepackage{adjustbox} + +%BFH Boxes +% see BFH example for usage, looks nice!<< +\LoadBFHModule{listings,terminal,boxes} + +%Akronyme +\usepackage[printonlyused,footnote]{acronym} + +% Literaturverweise +\usepackage[ + backend=biber, + style=alphabetic, + %citestyle=authoryear +]{biblatex} +\addbibresource{bibliography.bib} +\addbibresource{bibliography_projekt2.bib} + +% TODOs in text +% documentation: http://tug.ctan.org/macros/latex/contrib/todonotes/todonotes.pdf +\usepackage{todonotes} + +%Crypto Grafiken +\usepackage{cryptocode} +%\usepackage{amsmath} + +\usepackage{listings} +\usepackage{xcolor} + +\definecolor{mGreen}{rgb}{0,0.6,0} +\definecolor{mGray}{rgb}{0.5,0.5,0.5} +\definecolor{mPurple}{rgb}{0.58,0,0.82} +\definecolor{backgroundColour}{rgb}{0.95,0.95,0.92} +\definecolor{ApiColor}{HTML}{307FCB} +\definecolor{whyite}{HTML}{A1C66C} % Needs to be here due to some typo in BFH-CI stuff. Thanks BFH. diff --git a/doc/cs/ads/history.tex b/doc/cs/ads/history.tex new file mode 100644 index 000000000..376ee587a --- /dev/null +++ b/doc/cs/ads/history.tex @@ -0,0 +1,12 @@ +\chapter*{Document History} +\addcontentsline{toc}{chapter}{Document History} + +%\begin{center} +\begin{tabular}{ ||l|l|l|l|| } + \hline + Version & Date & Comment & Author \\ + \hline\hline + 0.0.1 & 30.09.2021 & Document created & Gian Demarmels \& Lucien Heuzeveldt \\ + \hline +\end{tabular} +%\end{center}
\ No newline at end of file diff --git a/doc/cs/bibliography.bib b/doc/cs/bibliography.bib new file mode 100644 index 000000000..014958986 --- /dev/null +++ b/doc/cs/bibliography.bib @@ -0,0 +1,362 @@ +@misc{project-definition, + author = {Dr. Emmanuel Benoist}, + title = {Adding Schnorr's blind signature in Taler}, + howpublished = {\url{https://fbi.bfh.ch/fbi/2022/Studienbetrieb/BaThesisHS21/aufgabestellungen/BIE1-1-21-en.html}}, + year = {2021} +} + +@misc{swot-analysis, + author = {Will Kenton}, + title = {Strength, Weakness, Opportunity, and Threat (SWOT) Analysis}, + year = {2021}, + howpublished = {\url{https://www.investopedia.com/terms/s/swot.asp}}, + note = {[Online; accessed 01-October-2021]} +} + + @misc{enwiki:1040250156, + author = {{Wikipedia contributors}}, + title = {Project management triangle --- {Wikipedia}{,} The Free Encyclopedia}, + year = {2021}, + url = {https://en.wikipedia.org/w/index.php?title=Project_management_triangle&oldid=1040250156}, + note = {[Online; accessed 1-October-2021]} +} + +@misc{ionos:waterfall_model, + author = {ionos.com}, + title = {Waterfall methodology}, + year = {2019}, + url = {https://www.ionos.com/digitalguide/websites/web-development/waterfall-methodology/}, + note = {[Online; accessed 1-October-2021]} +} + +@misc{schwab:anforderungen, + author = {Gerhard Schwab}, + title = {Lerneinheit 4 - Anforderungen ermitteln}, + howpublished = {BFH Moodle}, + year = {2017} +} + +@techreport{rfc2104, + shorthand = {RFC2104}, + author = {H. Krawczyk, M.Bellare, R. Canetti}, + title = {HMAC: Keyed-Hashing for Message Authentication}, + howpublished = {Internet Requests for Comments}, + type = {RFC}, + number = 2104, + year = {1997}, + issn = {2070-1721}, + month = {02}, + publisher = {IETF}, + institution = {IETF}, + url = {https://tools.ietf.org/html/rfc2104} +} + +@techreport{rfc5869, + shorthand = {RFC5869}, + author = {H. Krawczyk, P.Eronen}, + title = {HMAC-based Extract-and-Expand Key Derivation Function (HKDF)}, + howpublished = {Internet Requests for Comments}, + type = {RFC}, + number = 5869, + year = {2010}, + issn = {2070-1721}, + month = {05}, + publisher = {IETF}, + institution = {IETF}, + url = {https://tools.ietf.org/html/rfc5869} +} + +@misc{cryptoeprint:2019:877, + author = {Georg Fuchsbauer and + Antoine Plouviez and + Yannick Seurin}, + title = {Blind Schnorr Signatures and Signed ElGamal Encryption in the Algebraic Group Model}, + howpublished = {Cryptology ePrint Archive, Report 2019/877}, + year = {2019}, + note = {\url{https://ia.cr/2019/877} and \url{https://www.youtube.com/watch?v=W-uwVdGeUUs}} +} + + +@misc{bip:schnorr-bitc, + author = {Pieter Wuille, Jonas Nick, Tim Ruffing}, + title = {Schnorr Signatures for secp256k1}, + howpublished = {Bitcoin Improvement Proposal, bip-0340}, + year = {2020}, + note = {\url{https://github.com/bitcoin/bips/blob/master/bip-0340.mediawiki}} +} + +@misc{git:secp256k1-schnorr, + author = {Bitcoin Repository}, + title = {BIP-340 - Module for Schnorr signatures in libsecp256k1}, + howpublished = {\url{https://github.com/bitcoin/bitcoin/tree/master/src/secp256k1}} +} + +@misc{btc:releasnotes-0.21, + author = {Bitcoin.org }, + title = {0.21.1 Release Notes}, + howpublished = {\url{https://bitcoin.org/en/releases/0.21.1/}} +} + +@inproceedings{spring:wallet-db-with-observers, + author = {Chaum, David + and Pedersen, Torben Pryds}, + editor = {Brickell, Ernest F.}, + title = {Wallet Databases with Observers}, + booktitle = {Advances in Cryptology --- CRYPTO' 92}, + year = {1993}, + publisher = {Springer Berlin Heidelberg}, + address = {Berlin, Heidelberg}, + pages = {89--105}, + abstract = {Previously there have been essentially only two models for computers that people can use to handle ordinary consumer transactions: (1) the tamper-proof module, such as a smart card, that the person cannot modify or probe; and (2) the personal workstation whose inner working is totally under control of the individual. The first part of this article argues that a particular combination of these two kinds of mechanism can overcome the limitations of each alone, providing both security and correctness for organizations as well as privacy and even anonymity for individuals.}, + isbn = {978-3-540-48071-6} +} + +@misc{schnorr:perfect-dl-signatures, + author = {Claus Peter Schnorr}, + title = {Enhancing the Security of Perfect Blind DL-Signatures.}, + howpublished = {Universität Frankfurt}, + year = {2004}, + note = {\url{https://www.math.uni-frankfurt.de/~dmst/teaching/SS2012/Vorlesung/EBS5.pdf}} +} + +@misc{wagner:generalized-bday-prob, + author = {David Wagner}, + title = {A Generalized Birthday Problem}, + howpublished = {University of California Berkeley}, + year = {2002}, + note = {\url{https://www.iacr.org/archive/crypto2002/24420288/24420288.pdf}} +} + +@inproceedings{Schnorr01securityof, + author = {Claus Peter Schnorr}, + title = {Security of Blind Discrete Log Signatures against Interactive Attacks}, + booktitle = {ICICS 2001, LNCS 2229}, + year = {2001}, + pages = {1--12}, + publisher = {Springer-Verlag} +} + +@misc{pic:simple-diagram, + author = {GNU Taler}, + title = {Simple Taler Diagram}, + year = {[Online; accessed 2-November-2021]}, + note = {\url{https://taler.net/images/diagram-simple.png}} +} + +@misc{pic:refresh-prot, + author = {GNU Taler}, + title = {Taler Refresh protocol}, + year = {[Online; accessed 2-November-2021]}, + note = {\url{https://git.taler.net/marketing.git/plain/presentations/comprehensive/main.pdf}} +} + +@misc{pic:taler-overview, + author = {GNU Taler}, + title = {Operations}, + howpublished = {\url{https://git.taler.net/marketing.git/plain/presentations/comprehensive/operations.png}}, + year = {[Online; accessed 2-November-2021]}, +} + +@misc{pic:coin-state-machine, + author = {GNU Taler}, + howpublished = {\url{https://git.taler.net/exchange.git/tree/doc/system/taler/coin.pdf}}, + title = {Coin State Machine}, + year = {[Online; accessed 13 January 2022]} +} + +@misc{pic:deposit-state-machine, + author = {GNU Taler}, + howpublished = {\url{https://git.taler.net/exchange.git/tree/doc/system/taler/deposit.pdf}}, + title = {Deposit State Machine}, + year = {[Online; accessed 13 January 2022]} +} + +@misc{gnunet-git, + author = {GNUnet Git Repositories}, + title = {gnunet.git}, + howpublished = {\url{https://git.gnunet.org/gnunet.git/}} +} + +@misc{libsodium:finite-field-arithmetic, + author = {libsodium documentation}, + howpublished = {\url{https://doc.libsodium.org/advanced/point-arithmetic}}, + title = {Finite field arithmetic} +} + +@misc{bernlange:safecurves, + author = {Daniel J. Bernstein and Tanja Lange}, + title = {SafeCurves: choosing safe curves for elliptic-curve cryptography.}, + howpublished = {\url{https://safecurves.cr.yp.to}}, + year = {accessed 17 October 2021. } +} + +@misc{matt:unix-domain-sockets, + author = {Matt Lim}, + title = {Getting Started With Unix Domain Sockets}, + howpublished = {\url{https://medium.com/swlh/getting-started-with-unix-domain-sockets-4472c0db4eb1}}, + year = {accessed 08 January 2022. } +} + +@misc{rfc7748, + shorthand = {RFC7748}, + series = {Request for Comments}, + number = 7748, + howpublished = {RFC 7748}, + publisher = {RFC Editor}, + doi = {10.17487/RFC7748}, + url = {https://rfc-editor.org/rfc/rfc7748.txt}, + author = {Adam Langley and Mike Hamburg and Sean Turner}, + title = {{Elliptic Curves for Security}}, + pagetotal = 22, + year = 2016, + month = jan, + abstract = {This memo specifies two elliptic curves over prime fields that offer a high level of practical security in cryptographic applications, including Transport Layer Security (TLS). These curves are intended to operate at the \textasciitilde{}128-bit and \textasciitilde{}224-bit security level, respectively, and are generated deterministically based on a list of required properties.} +} + +@misc{ganapati:rsactftool, + author = {Ganapati}, + title = {RsaCtfTool}, + howpublished = {\url{https://github.com/Ganapati/RsaCtfTool}}, + year = {accessed 13 January 2022. } +} + +@misc{perez:stoprsa, + author = {Ben Perez}, + title = {Seriously, stop using RSA}, + howpublished = {\url{https://blog.trailofbits.com/2019/07/08/fuck-rsa/}}, + year = {accessed 13 January 2022. } +} + +@misc{geeks:rtt, + author = {preetikagupta8171}, + title = {What is RTT(Round Trip Time)?}, + howpublished = {\url{https://www.geeksforgeeks.org/what-is-rttround-trip-time/}}, + year = {accessed 13 January 2022. } +} + +@misc{madden:curve25519-clamping, + author = {Neil Madden}, + howpublished = {\url{https://neilmadden.blog/2020/05/28/whats-the-curve25519-clamping-all-about/}}, + title = {What’s the Curve25519 clamping all about?}, + year = {2020} +} + +@misc{bern:tweetnacl, + author = {Daniel J. Bernstein, Bernard van Gastel, Wesley Janssen}, + title = {TweetNaCl: a crypto library in 100 tweets.}, + howpublished = {\url{https://tweetnacl.cr.yp.to/papers.html}}, + year = {17.09.2014} +} + +@misc{taler-presentation, + author = {GNU Taler}, + howpublished = {\url{https://git.taler.net/marketing.git/tree/presentations/comprehensive/main.pdf}}, + title = {GNU Taler}, + year = {2021} +} + +@misc{cryptoeprint:2020:945, + author = {Fabrice Benhamouda and + Tancrède Lepoint and + Julian Loss and + Michele Orrù and + Mariana Raykova}, + title = {On the (in)security of ROS}, + howpublished = {Cryptology ePrint Archive, Report 2020/945}, + year = {2020}, + note = {\url{https://ia.cr/2020/945}} +} + +@misc{rfc5246, + series = {Request for Comments}, + number = 5246, + howpublished = {RFC 5246}, + publisher = {RFC Editor}, + doi = {10.17487/RFC5246}, + url = {https://rfc-editor.org/rfc/rfc5246.txt}, + author = {Eric Rescorla and Tim Dierks}, + title = {{The Transport Layer Security (TLS) Protocol Version 1.2}}, + pagetotal = 104, + year = 2008, + month = aug, + abstract = {This document specifies Version 1.2 of the Transport Layer Security (TLS) protocol. The TLS protocol provides communications security over the Internet. The protocol allows client/server applications to communicate in a way that is designed to prevent eavesdropping, tampering, or message forgery. {[}STANDARDS-TRACK{]}} +} + +@misc{rfc6071, + series = {Request for Comments}, + number = 6071, + howpublished = {RFC 6071}, + publisher = {RFC Editor}, + doi = {10.17487/RFC6071}, + url = {https://rfc-editor.org/rfc/rfc6071.txt}, + author = {Sheila Frankel and Suresh Krishnan}, + title = {{IP Security (IPsec) and Internet Key Exchange (IKE) Document Roadmap}}, + pagetotal = 63, + year = 2011, + month = feb, + abstract = {Over the past few years, the number of RFCs that define and use IPsec and Internet Key Exchange (IKE) has greatly proliferated. This is complicated by the fact that these RFCs originate from numerous IETF working groups: the original IPsec WG, its various spin-offs, and other WGs that use IPsec and/or IKE to protect their protocols' traffic. This document is a snapshot of IPsec- and IKE-related RFCs. It includes a brief description of each RFC, along with background information explaining the motivation and context of IPsec's outgrowths and extensions. It obsoletes RFC 2411, the previous "IP Security Document Roadmap." The obsoleted IPsec roadmap (RFC 2411) briefly described the interrelationship of the various classes of base IPsec documents. The major focus of RFC 2411 was to specify the recommended contents of documents specifying additional encryption and authentication algorithms. This document is not an Internet Standards Track specification; it is published for informational purposes.} +} + + @misc{enwiki:1055393696, + author = {{Wikipedia contributors}}, + title = {RSA Factoring Challenge --- {Wikipedia}{,} The Free Encyclopedia}, + year = {2021}, + howpublished = {\url{https://en.wikipedia.org/w/index.php?title=RSA_Factoring_Challenge&oldid=1055393696}}, + note = {[Online; accessed 16-January-2022]} +} + +@misc{cryptoeprint:2015:625, + author = {Mike Hamburg}, + title = {Ed448-Goldilocks, a new elliptic curve}, + howpublished = {Cryptology ePrint Archive, Report 2015/625}, + year = {2015}, + note = {\url{https://ia.cr/2015/625}}, +} + +@misc{bern:curve25519, + author = {Daniel J. Bernstein}, + title = {Curve25519: new Diffie-Hellman speed records}, + howpublished = {\url{https://cr.yp.to/ecdh/curve25519-20060209.pdf}}, + year = {02.09.2006} +} + +@misc{yuchen:idempotence, + author = {Yuchen Z.}, + title = {A Deep Dive Into Idempotence}, + year = {2021}, + howpublished = {\url{https://betterprogramming.pub/a-deep-dive-into-idempotence-1a39393df7e6}}, + note = {[Online; accessed 16-January-2022]} +} + +@misc{tibouchi:attacks-schnorr-nonce, + author = {Mehdi Tibouchi}, + title = {Attacks on Schnorr signatures with biased nonces}, + howpublished = {\url{https://ecc2017.cs.ru.nl/slides/ecc2017-tibouchi.pdf}}, + year = {13.11.2017} +} + +@article{wang:bitcoin-ecdsa-vuln, +author = {Wang, Ziyu and Yu, Hui and Zhang, Zongyang and Piao, Jiaming and Liu, Jianwei}, +year = {2019}, +month = {09}, +pages = {}, +title = {ECDSA weak randomness in Bitcoin}, +volume = {102}, +journal = {Future Generation Computer Systems}, +doi = {10.1016/j.future.2019.08.034} +} + +@misc{buchanan:ps3-ecdsa-vuln, + author = {Prof Bill Buchanan OBE}, + title = {Not Playing Randomly: The Sony PS3 and Bitcoin Crypto Hacks}, + howpublished = {\url{https://medium.com/asecuritysite-when-bob-met-alice/not-playing-randomly-the-sony-ps3-and-bitcoin-crypto-hacks-c1fe92bea9bc}}, + year = {12.11.2018} +} + +@misc{gian:nonce-sense, + author = {Gian Demarmels}, + title = {Nonce-Sense - Romhack CTF Crypto Challenge}, + howpublished = {\url{https://blog.c4pr1c0rn.ch/writeups/romhack_21/nonce_sence.html}}, + year = {2021}, + note = {[Online; accessed 19-January-2022]} +}
\ No newline at end of file diff --git a/doc/cs/bibliography_projekt2.bib b/doc/cs/bibliography_projekt2.bib new file mode 100644 index 000000000..1f20b8c59 --- /dev/null +++ b/doc/cs/bibliography_projekt2.bib @@ -0,0 +1,442 @@ +% see here for standard templates: https://en.wikibooks.org/wiki/LaTeX/Bibliography_Management#Standard_templates + +@misc{chaum-grothoff-moser:issue-cdbc, + author = {Chaum David, Grothoff Christian, Moser Thomas}, + title = {How to issue a central bank digital currency}, + howpublished = {\url{https://www.snb.ch/en/mmr/papers/id/working_paper_2021_03}}, + year = {2021} +} + +@phdthesis{dold:the-gnu-taler-system, + author = {Florian Dold}, + title = {The GNU Taler System}, + howpublished ={\url{https://taler.net/papers/thesis-dold-phd-2019.pdf}}, + school = {Université de Rennes}, + year = {2019} +} + +@misc{schneier:value-privacy, + author = {Bruce Schneier}, + title = {The Value of Privacy}, + howpublished = {\url{https://www.schneier.com/blog/archives/2006/05/the_value_of_pr.html}}, + year = {2006} +} + +@misc{qualcomm:mobile-rng, + author = {Liang Kai}, + title = {Guard your data with the Qualcomm Snapdragon mobile platform}, + howpublished = {\url{https://www.qualcomm.com/media/documents/files/guard-your-data-with-the-qualcomm-snapdragon-mobile-platform.pdf}}, + year = {2019} +} + +@misc{chaum:blind-sign, + author = {Chaum David}, + title = {Blind Signatures for Untraceable Payments}, + howpublished = {\url{https://www.chaum.com/publications/Chaum-blind-signatures.PDF}}, + year = {1983} +} + +@misc{grothoff-dold:euro-bearer-online, + author = {Christian Grothoff, Florian Dold}, + title = {Why a Digital Euro should be Online-first and Bearer-based}, + howpublished = {\url{https://taler.net/papers/euro-bearer-online-2021.pdf}}, + year = {2021} +} + +@misc{website:bigcommerce-payment-fraud, + author = {BigCommerce}, + title = {Payment fraud: What is it and how it can be avoided?}, + howpublished = {\url{https://www.bigcommerce.com/ecommerce-answers/payment-fraud-what-it-and-how-it-can-be-avoided/}} +} + +@misc{nist:recommendation-for-key-management, + author = {Elaine Barker}, + title = {Recommendation for Key Management}, + howpublished = {\url{https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-57pt1r5.pdf}}, + year = {2020} +} + +@misc{taler:snackautomat, + author = {Berner Fachhochschule}, + title = {GNU Taler Snackautomat}, + howpublished = {\url{https://www.bfh.ch/de/forschung/referenzprojekte/gnu-taler-snackautomat/}} +} + +@book{modernCrypto, + author = {Nigel P. Smart}, + editor = {David Basin, Kenny Paterson}, + title = {Cryptography Made Simple}, + publisher = {Springer International Publishing Switzerland AG}, + year = {2016} +} + +@inbook{Crépeau2005, + author = {Cr{\'e}peau, Claude}, + title = {Cut-and-choose protocols}, + publisher = {School of Computr Science, McGill University, Montréal (QC), Canada}, + url = {http://crypto.cs.mcgill.ca/~crepeau/EoC/Cut&Choose.pdf} +} + +% author from github: https://github.com/chaos-eng/chaos-eng.github.io +@misc{chaos-engineering, + author = {chaos-eng}, + title = {PRINCIPLES OF CHAOS ENGINEERING}, + howpublished = {\url{https://principlesofchaos.org/}}, + year = {2019} +} + +@misc{businger:public-key-crytpo, + author = {Walter Businger}, + title = {Skript Public-Key Kryptographie}, + year = {2021} +} + +@misc{rutishauser:fuzzing, + author = {Dobin Rutishauser}, + title = {Fuzzing}, + howpublished = {Course material of BFH module Forensics and Code Security}, + year = {2021} +} + +@misc{codeblau:taler-audit, + author = {Code Blau GmbH}, + title = {Report for the GNU Taler security audit in Q2/Q3 2020}, + howpublished = {\url{https://taler.net/papers/codeblau-report-2020-q2.pdf}}, + year = {2020} +} + +@misc{pentest-execution-standard, + author = {The Penetration Testing Execution Standard}, + title = {Main Page}, + howpublished = {\url{http://www.pentest-standard.org/index.php/Main_Page}} +} + +@misc{owasp:top-ten, + author = {OWASP Foundation}, + title = {OWASP Top Ten}, + howpublished = {\url{https://owasp.org/www-project-top-ten/}} +} + +@misc{owasp:mobile-top-ten, + author = {OWASP Foundation}, + title = {OWASP Mobile Top 10}, + howpublished = {\url{https://owasp.org/www-project-mobile-top-10/}} +} + +@misc{owasp:api-security-project, + author = {OWASP Foundation}, + title = {OWASP API Security Project}, + howpublished = {\url{https://owasp.org/www-project-api-security/}} +} + +@misc{owasp:web-security-testing-guide, + author = {OWASP Foundation}, + title = {OWASP Web Security Testing Guide}, + howpublished = {\url{https://owasp.org/www-project-web-security-testing-guide/}} +} + +@misc{owasp:mobile-security-testing-guide, + author = {OWASP Foundation}, + title = {OWASP Mobile Security Testing Guide}, + howpublished = {\url{https://owasp.org/www-project-mobile-security-testing-guide/}} +} + +@misc{owasp:application-security-verification-standard, + author = {OWASP Foundation}, + title = {OWASP Application Security Verification Standard}, + howpublished = {\url{https://owasp.org/www-project-application-security-verification-standard/}} +} + +@misc{owasp:mobile-application-security-verification-standard, + author = {OWASP Foundation}, + title = {OWASP Mobile Application Security Verification Standard}, + howpublished = {\url{https://github.com/OWASP/owasp-masvs}} +} + +@misc{osstmm, + author = {ISECOM}, + title = {OSSTMM 3}, + howpublished = {\url{https://www.isecom.org/OSSTMM.3.pdf}} +} + +@misc{emscripten, + author = {Emscripten Contributors}, + title = {Emscripten documentation}, + howpublished = {\url{https://emscripten.org/}} +} + +@misc{emscripten:paper, + author = {Alon Zakai}, + title = {Emscripten: an LLVM-to-JavaScript compiler}, + howpublished = {\url{https://www.researchgate.net/publication/221320724_Emscripten_an_LLVM-to-JavaScript_compiler}}, + year = {2011} +} + +@misc{cwe, + author = {Common Weakness Enumeration}, + title = {CWE - Common Weakness Enumeration}, + howpublished = {\url{https://cwe.mitre.org/index.html}} +} + +@misc{cwe:toctou, + author = {Common Weakness Enumeration}, + title = {CWE-367: Time-of-check Time-of-use (TOCTOU) Race Condition}, + howpublished = {\url{https://cwe.mitre.org/data/definitions/367.html}}, + year = {2021} +} + +@misc{cwe:c-weaknesses, + author = {Common Weakness Enumeration}, + title = {CWE VIEW: Weaknesses in Software Written in C}, + howpublished = {\url{https://cwe.mitre.org/data/definitions/658.html}} +} + +% ---------- Taler documentation and repos +@misc{taler-documentation, + author = {Taler Systems SA}, + title = {GNU Taler Documentation}, + howpublished = {\url{https://docs.taler.net/}} +} + +@misc{taler-documentation:backup-synchronization, + author = {Taler Systems SA}, + title = {Backup and Synchronization Service API}, + howpublished = {\url{https://docs.taler.net/core/api-sync.html}} +} + +@misc{taler-documentation:auditor-operator-manual, + author = {Taler Systems SA}, + title = {GNU Taler Auditor Operator Manual}, + howpublished = {\url{https://docs.taler.net/taler-auditor-manual.html}} +} + +@misc{taler-documentation:exchange-operator-manual, + author = {Taler Systems SA}, + title = {GNU Taler Exchange Operator Manual}, + howpublished = {\url{https://docs.taler.net/taler-exchange-manual.html}} +} + +@misc{taler-documentation:merchant-backend-operator-manual, + author = {Taler Systems SA}, + title = {GNU Taler Merchant Backend Operator Manual}, + howpublished = {\url{https://docs.taler.net/taler-merchant-manual.html}} +} + +@misc{taler-documentation:merchant-api, + author = {Taler Systems SA}, + title = {GNU Taler Merchant API Tutorial}, + howpublished = {\url{https://docs.taler.net/taler-merchant-api-tutorial.html}} +} + +@misc{taler-documentation:back-office, + author = {Taler Systems SA}, + title = {Back-office Web service manual}, + howpublished = {\url{https://docs.taler.net/taler-backoffice-manual.html}} +} + +@misc{taler-documentation:pos-manual, + author = {Taler Systems SA}, + title = {GNU Taler Merchant POS Manual}, + howpublished = {\url{https://docs.taler.net/taler-merchant-pos-terminal.html}} +} + +@misc{taler-documentation:wallet-developer-manual, + author = {Taler Systems SA}, + title = {GNU Taler Wallet Developer Manual}, + howpublished = {\url{https://docs.taler.net/taler-wallet.html}} +} + +@misc{taler-documentation:wallet-cli-manual, + author = {Taler Systems SA}, + title = {GNU Taler Wallet CLI Manual}, + howpublished = {\url{https://docs.taler.net/taler-wallet-cli-manual.html}} +} + +@misc{taler-documentation:, + author = {Taler Systems SA}, + title = {}, + howpublished = {\url{}} +} + +@misc{taler-documentation:, + author = {Taler Systems SA}, + title = {}, + howpublished = {\url{}} +} + +@misc{taler-documentation:, + author = {Taler Systems SA}, + title = {}, + howpublished = {\url{}} +} + +% see https://git.taler.net/ + +@misc{taler-git, + author = {GNU Taler Git Repositories}, + title = {GNU Taler Git Repositories}, + howpublished = {\url{https://git.taler.net/}} +} + +@misc{taler-git:exchange, + author = {GNU Taler Git Repositories}, + title = {exchange.git}, + howpublished = {\url{https://git.taler.net/exchange.git/}} +} + +@misc{taler-git:merchant, + author = {GNU Taler Git Repositories}, + title = {merchant.git}, + howpublished = {\url{https://git.taler.net/merchant.git/}} +} + +@misc{taler-git:wallet-core, + author = {GNU Taler Git Repositories}, + title = {wallet-core.git}, + howpublished = {\url{https://git.taler.net/wallet-core.git/}} +} + +@misc{taler-git:auditor, + author = {GNU Taler Git Repositories}, + title = {auditor.git}, + howpublished = {\url{https://git.taler.net/auditor.git/}} +} + +@misc{taler-git:backoffice, + author = {GNU Taler Git Repositories}, + title = {backoffice.git}, + howpublished = {\url{https://git.taler.net/backoffice.git/}} +} + +@misc{taler-git:android, + author = {GNU Taler Git Repositories}, + title = {taler-android.git}, + howpublished = {\url{https://git.taler.net/taler-android.git}} +} + +@misc{taler-git:ios, + author = {GNU Taler Git Repositories}, + title = {taler-ios.git}, + howpublished = {\url{https://git.taler.net/taler-ios.git/}} +} + +@misc{taler-git:django-payments, + author = {GNU Taler Git Repositories}, + title = {django-payments-taler.git}, + howpublished = {\url{https://git.taler.net/django-payments-taler.git/}} +} + +@misc{taler-git:woocommerce, + author = {GNU Taler Git Repositories}, + title = {woocommerce-taler.git}, + howpublished = {\url{https://git.taler.net/woocommerce-taler.git/}} +} + +@misc{taler-git:saleor, + author = {GNU Taler Git Repositories}, + title = {saleor-frontend.git}, + howpublished = {\url{https://git.taler.net/saleor-frontend.git/}} +} + +@misc{taler-git:merchant-demos, + author = {GNU Taler Git Repositories}, + title = {taler-merchant-demos.git}, + howpublished = {\url{https://git.taler.net/taler-merchant-demos.git/}} +} + +% ---------- Wikipedia +@misc{dewiki:205456999, + author = {Wikipedia}, + title = {Know your customer --- Wikipedia{,} Die freie Enzyklopädie}, + year = {2020}, + url = {\url{https://de.wikipedia.org/w/index.php?title=Know_your_customer&oldid=205456999}}, + note = {[Online; Stand 3. April 2021]} +} + +@misc{enwiki:1013094030, + author = {{Wikipedia contributors}}, + title = {EdDSA --- {Wikipedia}{,} The Free Encyclopedia}, + year = {2021}, + howpublished = {\url{https://en.wikipedia.org/w/index.php?title=EdDSA&oldid=1013094030}}, + note = {[Online; accessed 22-April-2021]} +} + +@misc{enwiki:1020240018, + author = {{Wikipedia contributors}}, + title = {Birthday problem --- {Wikipedia}{,} The Free Encyclopedia}, + year = {2021}, + howpublished = {\url{https://en.wikipedia.org/w/index.php?title=Birthday_problem&oldid=1020240018}}, + note = {[Online; accessed 28-April-2021]} +} + +@misc{enwiki:1019272750, + author = {{Wikipedia contributors}}, + title = {Birthday attack --- {Wikipedia}{,} The Free Encyclopedia}, + year = {2021}, + howpublished = {\url{https://en.wikipedia.org/w/index.php?title=Birthday_attack&oldid=1019272750}}, + note = {[Online; accessed 24-April-2021]} +} + +@misc{enwiki:blind-sign, + author = {{Wikipedia contributors}}, + title = {Blind signature --- {Wikipedia}{,} The Free Encyclopedia}, + year = {2021}, + howpublished = {\url{https://en.wikipedia.org/w/index.php?title=Blind_signature&oldid=1001105629}}, + note = {[Online; accessed 12-April-2021]} +} + +@misc{enwiki:1024158358, + author = "{Wikipedia contributors}", + title = "Scalability --- {Wikipedia}{,} The Free Encyclopedia", + year = "2021", + howpublished = "\url{https://en.wikipedia.org/w/index.php?title=Scalability&oldid=1024158358}", + note = "[Online; accessed 17-June-2021]" +} + +@misc{enwiki:1024197377, + author = "{Wikipedia contributors}", + title = "Chaos engineering --- {Wikipedia}{,} The Free Encyclopedia", + year = "2021", + howpublished = "\url{https://en.wikipedia.org/w/index.php?title=Chaos_engineering&oldid=1024197377}", + note = "[Online; accessed 17-June-2021]" +} + +@misc{enwiki:1026754635, + author = "{Wikipedia contributors}", + title = "Replay attack --- {Wikipedia}{,} The Free Encyclopedia", + year = "2021", + howpublished = "\url{https://en.wikipedia.org/w/index.php?title=Replay_attack&oldid=1026754635}", + note = "[Online; accessed 17-June-2021]" +} + +% ---------- RFCs +@misc{rfc8032, + series = {Request for Comments}, + number = 8032, + howpublished = {RFC 8032}, + publisher = {RFC Editor}, + doi = {10.17487/RFC8032}, + url = {https://rfc-editor.org/rfc/rfc8032.txt}, + author = {Simon Josefsson and Ilari Liusvaara}, + title = {{Edwards-Curve Digital Signature Algorithm (EdDSA)}}, + pagetotal = 60, + year = 2017, + month = jan, + abstract = {This document describes elliptic curve signature scheme Edwards-curve Digital Signature Algorithm (EdDSA). The algorithm is instantiated with recommended parameters for the edwards25519 and edwards448 curves. An example implementation and test vectors are provided.}, +} + +@misc{rfc6265, + series = {Request for Comments}, + number = 6265, + howpublished = {RFC 6265}, + publisher = {RFC Editor}, + doi = {10.17487/RFC6265}, + url = {https://rfc-editor.org/rfc/rfc6265.txt}, + author = {Adam Barth}, + title = {{HTTP State Management Mechanism}}, + pagetotal = 37, + year = 2011, + month = apr, + abstract = {This document defines the HTTP Cookie and Set-Cookie header fields. These header fields can be used by HTTP servers to store state (called cookies) at HTTP user agents, letting the servers maintain a stateful session over the mostly stateless HTTP protocol. Although cookies have many historical infelicities that degrade their security and privacy, the Cookie and Set-Cookie header fields are widely used on the Internet. This document obsoletes RFC 2965. {[}STANDARDS-TRACK{]}}, +} + diff --git a/doc/cs/content/1_introduction.tex b/doc/cs/content/1_introduction.tex new file mode 100644 index 000000000..e0fdaa018 --- /dev/null +++ b/doc/cs/content/1_introduction.tex @@ -0,0 +1,72 @@ +\chapter{Introduction} + +\section{Motivation} +Public key cryptography based on elliptic curves allows smaller key sizes compared to other cryptographic systems. +While still providing equivalent security, the smaller key size leads to huge performance benefits. +\\ +Blind Signatures are one of the key components upon which Taler's privacy is built upon. +Our thesis adds support for a modern cryptographic scheme called the Clause Blind Schnorr Signature scheme \cite{cryptoeprint:2019:877}.\\ +Additionally to the benefits of ellicptic curve cryptography, adding a second blind signature scheme makes Taler independent of a single cryptographic scheme and thus provides \textit{cipher agility}. + + +\section{Goals} +\label{sec:goals} +The project definition is as follows \cite{project-definition}: + +The students will implement the blind Schnorr signature inside Taler. +Taler is a system for the management of virtual money. +Taler is based on coins that need to be signed by an exchange (for instance a bank). +In the actual version of the system, coins are signed by the exchange using Schaum's bind-signature protocol. +This allows users to have signed coins, without the exchange knowing what it signed. +This step is fundamental for the privacy protection of the system. +\\The students have to insert the Schnorr blind signature algorithm inside the protocol for the creation of coins. +But they also need to change the Taler subsystems where the verification of the signature is done. +\\The actual Taler system allows people to let an exchange sign a coin for which they do not have the private key. +This is a security issue (for misuse of coins on the dark-net for instance). +An optional task for the project is to prevent a user to let an exchange sign a public key when the client does not have access to the corresponding private key. +\\Here is a list of the tasks that the students must do: +\begin{itemize} + \item Design a protocol integrating Schnorr blind signature in the creation of Taler coins. + \item Implement the protocol inside the exchange application and the wallet app. + \item Analyze the different Taler subsystems to find where the blind signature is verified. + \item Replace verification of the blind signature everywhere it occurs. + \item Compare both blind signature systems (Schaum's and Schnorr's), from the point of view of security, privacy protection, speed, \dots + \item Write tests for the written software. + \item Conduct tests for the written software. + \item Transfer the new software the Taler developers team +\end{itemize} +Here is a list of optional features: +\begin{itemize} + \item Design a protocol, such that the exchange can verify that the user knows the private key corresponding to the coin that is to be signed. + \item Implement that protocol. +\end{itemize} + +\section{Scope} +\label{sec:scope} +In scope are all necessary changes on the protocol(s) and components for the following tasks: +\begin{itemize} + \item Research the current state of Blind Schnorr Signature schemes + \item Redesign the Taler protocols to support Blind Schnorr signatures + \item Add support for a Blind Schnorr Signature Scheme in the exchange, merchant, wallet-core, wallet web-extension and optionally on the android mobile wallet + \item design and implement a protocol where the user proves to the exchange the knowledge of the coin that is to be signed (optional) +\end{itemize} + +Out of scope is production readiness of the implementation. +This is because changes in the protocos and code need to be thoroughly vetted to ensure that no weaknesses or security vulnerabilities were introduced. +Such an audit is out of scope for the thesis and is recommended to be performed in the future. +The iOS wallet will not be considered in this work. +\\ +It is not unusual that a scope changes when a project develops. +Due to different reasons, the scope needed to be shifted. +Since there are no libraries supporting \gls{CSBS}, the signature scheme has to be implemented and tested before integrating it into Taler. +While this is still reasonable to do in this project, it will affect the scope quite a bit. +The analysis of the optional goal showed, that a good solution that aligns with Taler's goals and properties needs more research and is a whole project by itself. + +Scope changes during the project: +\begin{itemize} + \item \textbf{Added:} Implement the cryptographic routines in GNUnet + \item \textbf{Removed: } design and implement a protocol where the user proves to the exchange the knowledge of the coin that is to be signed (optional) + \item \textbf{Adjusted: } Focus is on the implementation of the exchange protocols (Withdraw, Spend, Refresh and cryptographic utilities) + \item \textbf{Adjusted: } Implementation of the refresh protocol and wallet-core are nice-to-have goals + \item \textbf{Removed: } The Merchant and the android wallet implementations are out of scope +\end{itemize} diff --git a/doc/cs/content/3_preliminaries.tex b/doc/cs/content/3_preliminaries.tex new file mode 100644 index 000000000..7d7b7ca2f --- /dev/null +++ b/doc/cs/content/3_preliminaries.tex @@ -0,0 +1,1465 @@ +\chapter{Preliminaries} +\label{chap:preliminaries} +\section{\acl{Taler} Overview} +\label{sec:taler-intro} +This chapter provides an high-level overview of GNU Taler with its core components. +The purpose of this chapter is to provide all the necessary details to understand this work and is not a specification nor a documentation of GNU Taler. +For more information on GNU Taler refer to \cite{dold:the-gnu-taler-system} or the GNU Taler documentation \cite{taler-documentation}. +\\ +Generally, GNU Taler is based on Chaumian e-cash \cite{chaum:blind-sign}. +The following parts discuss the different entities seen in the figure \ref{fig:simple-diagram} + +\subsection{Components} +\label{sec:taler-components} +In this section the different components are described as in \cite{dold:the-gnu-taler-system}. +\begin{figure}[htp] + \includegraphics[height=0.6\textwidth]{diagram-simple.png} + \centering + \caption{GNU Taler simple overview (source: \cite{pic:simple-diagram})} + \label{fig:simple-diagram} +\end{figure} + +\subsubsection{Exchange} +\label{sec:exchange} +The exchange is the payment service provider for financial transactions between a customer and merchant. +The exchange holds bank money as reserve for the anonymous digital coins. +\\ +Details of the exchange's functionality can be found in section 4.3 from Florian Dold's thesis \cite{dold:the-gnu-taler-system} or in the documentation \cite{taler-documentation:exchange-operator-manual}. +\\The code can be found in the exchange's git repository \cite{taler-git:exchange}. + +\subsubsection{Customer (Wallet)} +A customer holds Taler Coins in his electronic wallet. +As we see in figure \ref{fig:simple-diagram}, a customer can withdraw coins from the exchange. +These coins can then be spent with a merchant. +\\ +Details of the wallet's functionality can be found in section 4.6 from Florian Dold's thesis \cite{dold:the-gnu-taler-system} or in the documentations \cite{taler-documentation:wallet-developer-manual} \cite{taler-documentation:wallet-cli-manual}. +\\ +Git Repositories: +\begin{itemize} + \item Main repository \cite{taler-git:wallet-core} \\ + This Repository includes the wallet-core and the implementations for the web extension and CLI. + \item Android app \cite{taler-git:android} + \item iOS app \cite{taler-git:ios} +\end{itemize} + +\subsubsection{Merchant} +A merchant accepts Taler Coins in exchange for goods and services. +The merchant deposits these coins at the exchange and receives bank money in return. +\\ +Details of the wallet's functionality can be found in section 4.5 from Florian Dold's thesis \cite{dold:the-gnu-taler-system} or in the documentations: +\begin{itemize} + \item Operator manual \cite{taler-documentation:merchant-backend-operator-manual} + \item Merchant API \cite{taler-documentation:merchant-api} + \item Back-Office \cite{taler-documentation:back-office} + \item Point-of-Sales \cite{taler-documentation:pos-manual} +\end{itemize} + +\noindent Git Repositories: +\begin{itemize} + \item Backend: \cite{taler-git:merchant} + \item Backoffice: \cite{taler-git:backoffice} + \item Point-of-Sales App: \cite{taler-git:android} (part of android repo) +\end{itemize} + +\noindent Merchant Frontend Repositories: +\begin{itemize} + \item Payments with Django: \cite{taler-git:django-payments} + \item Wordpress woocommerce plugin: \cite{taler-git:woocommerce} + \item Saleor Frontend: \cite{taler-git:saleor} + \item Demo Frontends: \cite{taler-git:merchant-demos} +\end{itemize} + +\subsubsection{Auditor} +The auditors, which are typically run by financial regulators, have the purpose to monitor the behavior of the exchanges to assure that exchanges operate correctly. +\\ +Details of the auditor's functionality can be found in section 4.4 from Florian Dold's thesis \cite{dold:the-gnu-taler-system} or in the documentation \cite{taler-documentation:auditor-operator-manual}. +\\Git Repositories: +\begin{itemize} + \item Main repository \cite{taler-git:exchange} (Part of exchange repository, inside ./src/auditor and ./src/auditordb) + \item Auditor's public website \cite{taler-git:auditor} +\end{itemize} + +\subsubsection{Bank} +The banks receive wire transfer instructions from customers and exchanges. +As long as the banks can make wire transfers to each other, the Taler parties do not have to have the same bank. + +\subsection{Taler Step by Step} +\begin{figure}[htp] + \includegraphics[height=0.65\textwidth]{taler_bigger.png} + \centering + \caption{GNU Taler overview (source: \cite{pic:taler-overview})} + \label{fig:taler-overview-big} +\end{figure} +This is a high-level overview of what Taler generally does. +Many details (like privacy of the buyer, income transparency) are left out and are explained in the following sections. +We see in Figure \ref{fig:taler-overview-big} how Taler works step by step (at a high-level). +\begin{enumerate} + \item The customer decides to withdraw Taler coins. To do this, he goes to his bank and gives the order to pay the exchange. + \item The customers bank receives the customers order and makes a wire transfer to the exchanges Bank. + \item The exchange has received the money and the customer can now withdraw coins to his wallet. + \item The customer can now spend his coins at a merchant or merchants of his choice. + \item The merchant can then deposit the coins at the exchange. + \item The exchanges bank makes a wire transfer to the merchants bank. + \item The merchant has successfully received the money for the goods he sold. +\end{enumerate} + +\subsection{Protocols Overview} +This section provides a high-level overview of the different Taler protocols. +The details are here omitted and discussed later. + +\subsubsection{Refresh Protocol} +Taler has a quite interesting protocol to get change. +The purpose of the protocol is to give unlinkable change. +When a customer buys something from a merchant, in most situations he does not have the exact sum in coins. +For this reason, change is needed to provide a convenient payment system. +A coin can be partially spent. +When this happens, the exchange and the merchant know that this coin is used for that specific contract. +If the rest of this coin would be spent in future, one could link these two transactions. +Therefore, a mechanism to get unlinkable change while still preventing money laundering or tax evasion is needed. + +\subsubsection{Refund} +Taler has a built-in refund functionality. +Merchants can instruct the exchange to refund a transaction before the refund deadline. +The customer then refreshes the coin(s) in order for payments to remain unlinkable. + +\subsubsection{Payment Fees} +The exchange can charge fees for withdrawal, refreshing, deposition of coins. +These fees can depend on the denomination since different denominations can have different storage requirements. +Merchants are able to cover these costs fully or partially. +\\Exchanges are also able to aggregate wire transfers to merchants, thus reducing wire transfer fees. + +\subsubsection{Tipping} +Merchants can give customers a small tip. +This feature can be useful for different use cases, for example a merchant can give a tip when a customer participates in a survey. + +\subsubsection{Auditing} +Financial auditing is built-in to Taler in the form of auditors. +Auditors have read access to certain exchange databases. +Their task is to verify that exchange work as expected, see chapter 4.4 in Florian Dold's thesis \cite{dold:the-gnu-taler-system} for more details. +In future versions, the auditor will provide an interface that can be used by merchants to submit deposit confirmation samples. +This can be used to detect compromised signing keys or a malicious exchange. + +\subsection{Properties} +\label{sec:taler-properties} +This section describes Taler's properties. + +\subsubsection{Free Software} +The core components of \acl{Taler} are under the following licenses: +\begin{itemize} + \item exchange \cite{taler-git:exchange}: \ac{GNU AGPL} + \item merchant \cite{taler-git:merchant}: + \begin{itemize} + \item backend: \ac{GNU GPL}v3+, \ac{GNU AGPL} + \item library: \ac{GNU LGPL} + \end{itemize} + \item wallet-core \cite{taler-git:wallet-core}: \ac{GNU GPL} +\end{itemize} + +\newpage + +\subsubsection{Buyer Privacy Protection} +Taler protects the privacy of buyers during the different stages in the lifetime of a coin: +\begin{enumerate} + \item Reserve: The reserve is identified by a key pair (private and public key). + This means that the exchange doesn't know the identity of the reserve account holder. + Whoever knows the private key is able to withdraw from the corresponding reserve. + \item Withdrawal: The withdrawal process is encrypted with TLS and uses a blind signature scheme. + Therefore the exchange doesn't know which customer holds which coin. + \item Payment: The complete payment process doesn't rely on any information identifying a customer. +\end{enumerate} +Beware that an anonymous bi-directional channel is assumed for communication between the customer and the merchant as well as during the retrieval of denomination key from the exchange and change for partially spent coins (between customer and exchange). + +\subsubsection{Merchant Taxability} +Merchant's incomes are transparent to auditors which makes taxation by the state possible. +\newline +A buyer could theoretically transfer the private key and signature of a coin directly to the merchant to bypass the exchange. +However, this is suboptimal for the merchant because the knowledge of the coin doesn't grant him the sole ownership. +If the customer spends the coin in another transaction before the merchant, the coin is voided before the merchant claims its value, thus rendering this form of payment unusable. +The same principle holds for change (refreshed coins) because it is linked to the original coin. +Whoever knows the private key and signature of the original coin can obtain the change and use it before the merchant. + +\subsubsection{\acl{AML} and \acl{CFT}} +Every transaction contains the cryptographic hash of the associated contract. +This enables the authorities to request the merchant to reveal the transaction details (the contract). +If the merchant isn't able to reveal the contract, in other words fails to deliver a contract with the same hash which is included in the transaction, he risks punishment or further investigation. +\\Another aspect for \ac{AML} and \ac{CFT} are \ac{KYC} checks. +\acl{KYC} checks require certain institutions to verify certain information about their business partners in order to prevent money laundering and terrorism (see \cite{dewiki:205456999}). +\\\acl{Taler} implements these \ac{KYC} checks: +\begin{itemize} + \item Exchanges know the identities of their customers. + \item Merchants might need to pre-register with exchanges (depending on the deployment scenario). +\end{itemize} + +\subsubsection{Payer Fraud Prevention} +The following definition was taken from the BigCommerce website \cite{website:bigcommerce-payment-fraud}. +\begin{center} + \textit{ + "Payment fraud is any type of false or illegal transaction completed by a cybercriminal. The perpetrator deprives the victim of funds, personal property, interest or sensitive information via the internet." + } +\end{center} +Prevention of payment fraud is a design goal for \acl{Taler}. + +\subsubsection{Minimal Information Disclosure} +\acl{Taler} aims to disclose as minimal information as possible. +This mostly concerns customers, but merchants also profit by keeping financial details hidden from competitors. + +\subsubsection{\acl{SPOF} Avoidance} +\ac{SPOF}s are fatal because a failure in this component can bring the complete system to a halt. + +\subsubsection{Offline Payment (unsupported)} +\acl{Taler} doesn't offer offline payments due to the CAP problem (see chapter "Challenges of offline payments" in \cite{grothoff-dold:euro-bearer-online}). + + +\section{Cryptographic Preliminaries} +\label{sec:crypto-preliminaries} +In this section we will cover the necessary preliminaries to understand Taler. +For this part we took most of the information from Nigel P. Smarts book Cryptography made simple \cite{modernCrypto} and from the course "Applied Cryptography" at the BFH. +The chapter includes preliminaries of the already implemented cryptographic schemes and the ones that are implemented during this work. + +\subsection{Hash Functions} +As source for this section, page 271-275 were used in \textit{Cryptography made Simple} \cite{modernCrypto}. +\label{sec:hashfunc} +In this paper a hash function is always a cryptographic hash function. +Cryptographic hash function are one-way functions $H()$, which are calculating the hash value $h$ from a message $m$ so that $ h = H(m)$. +With known input one can easily calculate the hash value. +The other way around is computationally infeasible. +\\ Cryptographic hash functions have the following properties. + +\subsubsection{(First) Preimage Resistance} +\label{sec:first-pre-resist} +It should be hard to find a message with a given hash value. +For a given output $y$ it is impossible to calculate the input $x$ such that $ h(x) = y$. +\\ This basically means, a hash function can not be inverted, not even with unlimited computing power. +Too much information is destroyed by the hash function and there are many values resulting in the same hash. + +\subsubsection{Second Preimage Resistance} +\label{sec:second-pre-resist} +Given one message, it should be hard to find another message with the same hash value. +For a given $x_1$ and $h(x_1)$ it is hard to find a $x_2$ such that $h(x_1) = h(x_2)$. + +\subsubsection{Collision Resistance} +\label{sec:col-resist} +It should be hard to find two messages with the same hash value. +It is quite obvious that collisions are existent, since there are more possible messages than hash values. +This is also known as the pigeonhole principle. +Even if there are hash collisions, it should be hard to find $x_1 \ne x_2$ such that $h(x_1) = h(x_2)$. +Due to the birthday paradoxon (a detailed description can be found under \cite{enwiki:1019272750}) it is easier to cause a collision of two arbitrary messages than of a specific message. + +\subsection{Key Derivation} +\label{sec:kdf} +A \ac{KDF} derives one or more cryptographically strong secret keys from initial keying material by using a \acl{PRF}. +Therefore, input of a \ac{KDF} is some sort of keying material (e.g. from a key exchange). +Output will be a pseudo-random bit-string, which can be used as new key material. + + +\subsubsection{\acl{PRF}} +A \ac{PRF} is a deterministic function whose output appears to be random if the input is unknown. +The output is computationally indistinguishable from a true random source. +Different PRFs exist, for example \ac{AES} or HMAC could be used as \ac{PRF}. +In the case of \gls{hkdf}, HMAC is a suitable choice as \ac{PRF}. + +\subsubsection{HMAC} +\label{sec:hmac} +A \acl{MAC} (\ac{MAC}) provides \textbf{unforgeability}, which means, only a person who knows the key $k$ can compute the MAC. +Further, a MAC protects the \textbf{message integrity}, since unauthorized changes are being detected. +Last but not least, \textbf{message authenticity} is provided too, since only a person who knows the key can compute the HMAC. +However, it does not provide non-repudation because it is a shared secret. +MACs take a message and a key as input and give the MAC tag as output. +\\One way to design such MACs is by using a hash function. +The obvious way one would design such a function would most likely be: $ t = H(k || m || pad)$ +However, this variant would be \textbf{completely insecure} with hash functions based on Merkle-Damgard constructions. +Because of the structure of such hash functions, it is easy to find $H(M || X)$ for an arbitrary $X$ and a hash value $H(M)$, with that a so called \textit{length-extension} attack is possible. +\\HMAC prevents this attack by computing the MAC as follows: $t = $ HMAC$_k(m) = H( (k \oplus opad) || H( (k \oplus ipad) || m) ) $ +\\ H() could be any standard hash functions, for example SHA-256, SHA-512 or SHA-3. +$\oplus$ stands for the XOR operation. +HMAC is specified in \cite{rfc2104}. + +\subsubsection{HKDF} +\gls{hkdf} follows the \textit{extract-then-expand} paradigm and therefore has two phases. +In the extract phase, the input keying material is taken and a fixed-length pseudorandom key $K$ is \textit{extracted}. +This phase is used to generate a high entropy pseudorandom key from potentially weaker input keying material. +This key $K$ is used in the \textit{expand} phase to output a variable-length, pseudorandom key. + +The \gls{hkdf} makes use of HMAC (\ref{sec:hmac}) instantiated with a hashfunction \ref{sec:hashfunc}. +It takes the input keying material, a salt and the length of output keying material as arguments. +\gls{hkdf} is specified in \cite{rfc5869}. + +\subsection{Digital Signatures} +\label{sec:sign-schemes} +As source for this section, page 216-218 were used in \textit{Cryptography made Simple}\cite{modernCrypto}. +A digital signature is a cryptographic function used to verify the origin and integrity of a message. +It provides the following properties: +\begin{itemize} + \item Sender authenticity: The origin/sender of a message can not be forged. + \item Message integrity: No unauthorized change to the message can be made, the message is tamperproof. + \item Non-repudiation: After a message is signed, one can not dispute that a message was signed. +\end{itemize} +If verification is successful, only Alice knows her private key and Bob uses Alice's public key to verify, then Bob knows that this message is really from Alice and the message has not been tampered or further modified. +A digital signature scheme has a message space M, a signature space S and three algorithms: +\begin{itemize} + \item Key generation: $(pk,sk) \gets keyGen()$ + \item Signature generation: $s \gets $sign$_sk(m)$ + \item Verification: $ v \gets $verify$_pk(m,s)$ where $v \in {0,1}$ +\end{itemize} +If the result of the verification algorithm equals 1, a signature for m is called valid. +\\Digital signatures are publicly verifiable, which means anyone can verify that $(m,s)$ is legitimate. + +\subsubsection{Adversary Models \& Provable Security} +\label{sec:euf-cma} +Digital Signature schemes are believed to be secure when they are EUF-CMA secure. +\acl{EUF} (\ac{EUF}) means that given a public key $pk$ the adversary cannot construct a message with a valid signature, except with a negligible probability. +\acl{CMA} (\ac{CMA}) means that an adversary can ask a signing oracle to produce valid signatures $s' = sign_{sk}(m')$ for arbitrary messages $m' \ne m$.\\ +EUF-CMA is therefore existentially unforgeability under chosen message attack and is a standard security model for digital signatures. +More details can be found in page 217-218 in \textit{Cryptography made Simple} \cite{modernCrypto}. + + +\subsubsection{RSA-FDH Signature Scheme} +As source for this section, pages 300-301 and 333-335 were used in \textit{Cryptography made Simple} \cite{modernCrypto}. + +\label{sec:rsa-fdh} +RSA-FDH is a deterministic digital signature scheme which provides authenticity, message integrity and non-repudation. +The RSA signature scheme (without the full domain hash) is NOT \ac{EUF} secure and is vulnerable to existential forgery attacks. +RSA-FDH is one possible solution for a EUF-CMA secure scheme. EUF-CMA and its adversary model is further discussed in section \ref{sec:euf-cma}. +RSA-FDH is EUF-CMA secure under factoring and RSA assumptions. +More details on the hardness assumptions can be found on page 32-49 in \textit{Cryptography made Simple} \cite{modernCrypto}. + +\paragraph{\acl{FDH}} +A \acl{FDH} is a hash function with an \textbf{image size equal to the size of the RSA modulus}. +The hashfunction $h()$ used in the RSA-FDH sign (section \ref{sec:rsa-fdh-sign}) and RSA-FDH verify (section \ref{sec:rsa-fdh-sign}) needs to fulfill all the security properties we defined in chapter \ref{sec:hashfunc}. +This means that the image is a co-domain of the RSA group $\mathbb{Z}_N^*$. +Provided that the hashfunction has properties of a random oracle, \textbf{RSA-FDH is provably EUF-CMA secure} under the RSA assumption. + +\paragraph{RSA Key Generation} +\label{sec:rsa-keygen} +The information in this section is from the script of the BFH module \textit{Public Key Cryptography} taught by Prof. Dr. Walter Businger (\cite{businger:public-key-crytpo}). +The RSA private and public key are generated like this: +\begin{enumerate} + \item Generate two random prime numbers $ p, q $ where $ p \neq q $ + \item Calculate $ N = pq $ + \item Calculate $ \lambda = \text{lcm}(p-1, q-1) $ + \item Randomly choose a number $ d $ which is bigger than $ p $ and $ q $ and where $ \text{gcd}(d, \lambda) = 1 $ + \item Calculate $ e $, the multiplicative inverse of $ d \mod \lambda $ + \item The public key is $ (e, N) $, the private key is $ (d, N) $ + \item Destroy all numbers not included in the private or public key +\end{enumerate} +Note that "lcm" stands for least common multiplier and "gcd" means greatest common divisor. +The original RSA specification uses $ \phi(n) = (p-1)(q-1) $ instead of $ \lambda = \text{lcm}(p-1, q-1) $. +$ \phi(n) $ is a multiple of $ \lambda $ (for details see \cite{businger:public-key-crytpo}). + +\paragraph{Signature Algorithm} +\label{sec:rsa-fdh-sign} +The signature can be calculated as following: +\\ $ s \gets (\text{FDH}(m))^d \mod N$ + +\paragraph{Verification Algorithm} +\label{sec:rsa-fdh-verify} +The signature can be validated as following: +\\ $ \text{FDH}(m) \gets s^e \mod N$ + +\subsubsection{Schnorr Signature Scheme} +\label{sec:schnorr-sig} +The Schnorr Signature scheme is a randomized signature scheme, which is proven to be EUF-CMA secure under \ac{DLP}. +More information about the \ac{DLP} can be found in chapter 3 of \textit{Cryptography made Simple} \cite{modernCrypto}. +In february 2008 the patent expired and Schnorr signatures are now becoming widely deployed. (eg. EdDSA). +Schnorr signatures gained quite some attraction lately, since Bitcoin has announced to support Schnorr signatures starting from Block 709632 (see \cite{bip:schnorr-bitc}, \cite{btc:releasnotes-0.21}, and \cite{git:secp256k1-schnorr}). +As reference for the Schnorr signature scheme (and later Clause Blind Schnorr Signature Scheme) we use the paper \textit{Blind Schnorr Signatures and Signed ElGamal Encryption in the Algebraic Group Model} \cite{cryptoeprint:2019:877} as general source for Schnorr related schemes. + +\paragraph{Setup} +We have a Group $\mathbb{G}$ of order $p$ and a generator $G$ of the group. +Further a Hashfunction $H: \{0,1\}* \rightarrow \mathbb{Z}_p$ is used. + +\paragraph{Key Generation} +The key generation is the same as in \ac{DSA}. +\begin{enumerate} + \item private key is a random integer $x \leftarrow random \in \mathbb{Z}_p$ + \item public key is $X \leftarrow xG$ +\end{enumerate} + +\paragraph{Sign} +The sign function takes the secret key $x$ and the message $m$ to be signed as argument. +The interactive version with a signer and a user can be seen in figure \ref{fig:schnorr-sign-protocol}. +\begin{enumerate} + \item choose $r \leftarrow random \in \mathbb{Z}_p $ + \item calculate $R := rG$ + \item $ c := H(R,m)$ + \item $s := r + cx \mod p$ + \item $\sigma := (R,s)$ + \item return $\sigma$ +\end{enumerate} + +\begin{figure} + \begin{equation*} + \begin{array}{ l c l } + % preliminaries + \text{User} & & \text{Signer} + \\ \text{knows:} & \text{public parameters:} & \text{knows:} + \\ \text{public key } X & \langle p, \mathbb{G}, G, H\rangle & \text{private signing key } x, X := xG + \\ & & n \leftarrow random \in \mathbb{Z}_p + \\ & & R := nG + \\ & \xleftarrow[\rule{2.5cm}{0pt}]{R} & + \\ c := H(R,m) + \\ & \xrightarrow[\rule{2.5cm}{0pt}]{c} & + \\ & & s := n+cx \mod p + \\ & \xleftarrow[\rule{2.5cm}{0pt}]{s} & + \\ \text{check } sG = R + cX + \\ \sigma := \langle R,s \rangle + \end{array} + \end{equation*} + \caption{Schnorr signature protocol with user who wants to sign a message $m$ by the signer} + \label{fig:schnorr-sign-protocol} +\end{figure} + + +\paragraph{Verify} +The verify function takes the public key $X$, the message $m$ and the signature $\sigma$ as argument. +\begin{enumerate} + \item $ c := H(R,m)$ + \item check $sG = R + cX$ + \item return true if check was successful, false otherwise +\end{enumerate} + +The verification holds because $sG = R + cX $ is $ (r + cx)G = rG + cxG$ which is equal. + +\subsubsection{\acl{EdDSA}} +\ac{EdDSA} is a scheme for digital signatures based on twisted Edwards curves and the Schnorr signature scheme. +The information described here originates from \cite{rfc8032} and \cite{enwiki:1013094030}. +\ac{EdDSA} is a general algorithm that can be used with different curves. A choice in curves consists of 11 parameters. These are the most important (the others can be found in \cite{rfc8032}: +\begin{itemize} + \item odd prime power q (used to generate elliptic curve over finite field $ \mathbb{F}_q $) + \item integer b, where $ 2^{b-1} > q $, describing the bit size of various elements + \item cryptographic hash function $ H $ with output size of $ 2b $ + \item base point on curve $ B $ (generator) + \item number $ c $, (either 2 or 3) + \item prime number L where $ LB = 0 $ and $2^c*L = \text{number of points on the curve} $ +\end{itemize} + +\paragraph{Key Creation} +\label{sec:eddsa-keygen} +The private key $ k $ is a random bit-string of length $ b $. +The public key $ A $ is a point on the curve. +To generate it, we calculate $ A = sB $ where $ s = H(k)[:b] $ (meaning that we take the $ b $ least significant bits from the output of the hash function as $ s $). + +\paragraph{Signature Creation} +\label{sec:eddsa-signature-creation} +An \ac{EdDSA} signature of a message $ M $ is composed of $ (R, S )$, which are generated as follows: +\begin{align*} + s & = H(k)[:b] + \\r &= H(H(k)[b + 1:2b] \text{ || } M ) + \\R &= rB + \\S &= (r + H(R || A || M) * s) \mod L +\end{align*} +Note that $ [:b] $ means taking the $ b $ least significant bits, $ [b + 1:2b] $ means taking the b most significant bits and $ R || A $ means concatenating $ R $ and $ A $. + +\paragraph{Signature Verification} +$ (R, S) $ is the signature, $ M $ is the message, $ A $ is the public key and $c, B $ are curve parameters. +To verify a signature, the following equation must be satisfied: +\\$ 2^cSB = 2^cR + 2^cA*H(R || A || M) $ +\\This means that verify() returns 1 if the equation holds and 0 otherwise. + +\paragraph{Ed25519} +\label{par:curve25519} +Ed25519 is an \ac{EdDSA} based signature scheme and uses \gls{25519} (see \cite{bern:curve25519}), which offers 128 security bits. +\gls{25519} gets its name from the prime $ 2^{255} - 19 $ and is designed for fast computation and to resist side channel attacks. +\\These are the most important \ac{EdDSA} parameters for Ed25519 (the others can be found in \cite{rfc8032}): +\begin{itemize} + \item $ q = 2^{255} - 19 $ + \item $ b = 256 $ + \item $ H() $: SHA-512 + \item $ B = (15112221349535400772501151409588531511454012693041857206046113283949847762202, $ + \\ $46316835694926478169428394003475163141307993866256225615783033603165251855960) $ + \item $ c = 3 $ + \item $ L = 2^{252} + 27742317777372353535851937790883648493 $ +\end{itemize} +\subsection{Blind Signature Schemes} +\label{sec:blind-sign-schemes} +\label{sec:blind-sign-perfect-blindness} +One could think of blind signatures as a message put into an envelope made of carbon paper. The signer stamps his signature on the envelope and due to the properties of a carbon paper, the message is now signed too. (the stamp "stamps" through the envelope on the message). +The client then can open the envelope, and he possesses a correctly signed message. +This is achieved by the client by blinding the message with a blinding factor before sending to the signer ("blind()" operation). +The signer signs the blinded message and returns the signature of the blinded message to the client. +The client, who possesses the blinding factor can then unblind the signature and gets a signature of the original message ("unblind()" operation). +The explanation above leads us to the additional security property of a blind signature, the \textit{blindness} of signatures. +This property requires that a signer cannot link a message/signature pair to a particular execution of the signing protocol \cite{cryptoeprint:2019:877}.\\ +A blind signature scheme is called \textit{perfectly blind} if the generated signature (\textit{unblinded} signature) is statistically independent of the interaction with the signer (\textit{blinded} signature). +Thus, blind signatures cannot be linked to the signer interaction in an information theoretic sense. \cite{schnorr:perfect-dl-signatures} \cite{spring:wallet-db-with-observers} +\subsubsection{RSA Blind Signature Scheme} +\label{sec:blind-rsa-sign} +As source for this section, the course material from "Applied Cryptography" from BFH and \cite{chaum:blind-sign} were used. +The process for receiving a valid signature from the exchange uses a blind signature scheme invented by David Chaum (\cite{chaum:blind-sign}) which is based on RSA signatures. +The process is described in figure \ref{fig:blind-sign}. +\\Note that Bob (the signer) uses a standard RSA signature and can't verify if the message from Alice is blinded. +\begin{figure}[htp] + \begin{equation*} + \begin{array}{ l c l } + \text{Alice} & & \text{Bob} + \\ \text{knows:} & & \text{knows:} + \\ \text{RSA public key } D_B = e, N & & \text{RSA keys } d_B, D_B + \\ \text{message } m & & + \\ & & + \\ \text{blind:} & & + \\ r \leftarrow random \in \mathbb{Z}_N^* & & + \\ m' = m*r^{e} \mod N & & + \\ & \xrightarrow[\rule{2.5cm}{0pt}]{m'} & + \\ & & \text{sign:} + \\ & & s' = (m')^{d_B} \mod N + \\ & \xleftarrow[\rule{2.5cm}{0pt}]{s'} & + \\ \text{unblind:}& & + \\ s = s'*r^{-1} & & + \end{array} + \end{equation*} + \caption{Blind signature scheme} + \label{fig:blind-sign} +\end{figure} +Mathematically a blind signature works similar to the "naive" RSA signature scheme. +We consider Alice as the party who wants to have a message $m$ blindly signed by Bob. +Bob has a public key $D_B = (e, N)$ and his corresponding private key $d_B$ known only by Bob. +Alice needs to generate a random blinding factor $r\in \mathbb{Z}_N^*$, which needs to remain secret. +Alice then calculates $m'=m*r^e \mod N$. The blinded value $m'$ will now be sent to Bob by Alice. +Bob on his side calculates now the signature as usual: $s' = m'^{d_B} \mod N$. +The signature $s' $ is sent to Alice by Bob. Alice can calculate the signature as following: \\$s = s' * r^{-1}$. +\\$s$ is a valid signature of $m$, while the signer, Bob, does not know $m$ nor $b$. +\\We now want to analyze this closer to understand why blind signatures work. +Let's look at this equation: +\\$ s' = m'^{d_B} = (m*r^e)^{d_B} = m^{d_B} * (r^e)^{d_B}$. +\\The interesting part for now is $(r^e)^{d_B}$, since this is $r^1$. +This means the signature $s'$ we got from Bob is $s' = m^{d_B} * r^1$. +Now it is quite obvious how the valid signature $s$ can be calculated by multiplying with the inverse of $r$ as in: $ s = m^{d_B} * r^1 * r^{-1} = s' * r^{-1}$. + +\paragraph{Blindness} +\label{par:prop-blindness-rsa} +\gls{RSABS} are considered \textit{perfectly blind} (see \autoref{sec:blind-rsa-sign}). +There exist multiple $\langle r, m \rangle$ pairs that matches $m'$ such that $m' = m * r^e \mod N$. +Thus, \gls{RSABS} achieves \textit{perfect blindness} which cannot be attacked by brute-force or similar attacks. +Even if a valid $\langle r, m \rangle$ pair is found, the attacker has no possibility to know if it is the correct pair without additional information. + +\paragraph{RSA Blinding Attack} +There are also some possible attacks on this scheme. +First this is subject to the RSA blinding attack. +In this attack the property is used, that the signing operation is mathematically equivalent to the encrypt operation in RSA. +The attacker has a ciphertext $c = m^d$ and he wants to break this message. +Now, the attacker uses the ciphertext $c$ as "message" in the blind signature scheme above. +\\$m'' = cr^e \mod n = (m^e \mod n) * r^e \mod n = (mr)^e \mod n$. + \\The Attacker then sends the blinded message $m''$ to the signer who blindly signs the blinded message. + \\$s' = m''^d \mod n = (mr)^{ed} \mod n = m*r \mod n$. +\\The attacker recovers the message now with $m = s'*r^{-1} \mod n$. +\\This attack could be prevented by the use of a padding scheme, however this would break RSA symmetry. +In blind signatures the RSA symmetry is needed, otherwise it would produce an incorrect value in the unblind operation. +\\Due to this issue; One should never use the same key for signing and encryption! +A version of blind signatures, RSA-FDH will be discussed, which solves this issue. \cite{enwiki:blind-sign} + +\paragraph{Low Encryption Exponent Attack} +For this attack a possibly small message $m$ and a small public key $e$ is given. +If now $c = m^e < n$, one could compute $ m = \sqrt[e]{c} $. +Similar to the RSA blinding attack, padding could solve the issue, however RSA symmetry is needed. +To overcome this issue, RSA-FDH blind signatures are introduced in the next chapter. + +\subsubsection{RSA-FDH Blind Signatures} +As source for this section, the course material from "Applied Cryptograhy" from BFH and \cite{chaum:blind-sign} were used. +\label{sec:blind-sign-fdh} +Blind signatures are discussed in \ref{sec:blind-sign-schemes}. +This version is quite similar to the blind signatures already introduced in figure \ref{fig:blind-sign}. +In addition, the \gls{fdh} introduced in section \ref{sec:rsa-fdh} is used. +The difference is that the message does not get directly blinded, it gets hashed before with a \acl{FDH}. +\\Given Alice's message $m$ and Bobs public key $D_B = (e,n)$. +As in the simple \gls{RSABS}, a random blinding factor $r\in \mathbb{Z}_N^*$ is generated. +Before the message is blinded, the \acl{FDH} $ f = \text{FDH}(m)$ is calculated, which then is blinded as in $f' = fr^e \mod n$. +Since the hash function is a \acl{FDH}, $f$ is in the RSA domain $\mathbb{Z}_N^*$. +Now proceed as in the blind signature scheme introduced in the previous section. +The blinded hash $f'$ will be transmitted to Bob who then computes the signature $s' = f'^d \mod n$ and sends $s'$ back. +Alice unblinds $s'$ and gets the valid signature $s = s'r^{-1} \mod n$. + +\begin{figure}[htptp] + \begin{equation*} + \begin{array}{ l c l } + \text{Alice} & & \text{Bob} + \\ \text{knows:} & & \text{knows:} + \\ \text{RSA public key } D_B = e, N & & \text{RSA keys } d_B, D_B + \\ \text{message } m & & + \\ & & + \\ Compute f = FDH(m) & & + \\ & & + \\ \text{blind:} & & + \\ r \leftarrow random \in \mathbb{Z}_N^* & & + \\ f' = f*r^{e} \mod N & & + \\ & \xrightarrow[\rule{2.5cm}{0pt}]{f'} & + \\ & & \text{sign:} + \\ & & s' = (f')^{d_B} \mod N + \\ & \xleftarrow[\rule{2.5cm}{0pt}]{s'} & + \\ \text{unblind:}& & + \\ s = s'*r^{-1} & & + \end{array} + \end{equation*} + \caption{RSA-FDH blind signatues} + \label{fig:rsa-fdh-blind-sign} +\end{figure} + +This version of blind signature is not subject to the attacks introduced in the previous section. + +\subsubsection{Blind Schnorr Signature Scheme} +\label{sec:blind-schnorr-sig} +The Blind Schnorr Signature Scheme \textbf{is considered broken} and should not be implemented. +This section is here to explain how blind Schnorr signatures generally work and should help to understand The Clause Blind Schnorr Signature Scheme \ref{sec:clause-blind-schnorr-sig}. + +For the signer the calculations are the same as in the original Schnorr Signature Scheme \ref{fig:schnorr-sign-protocol}. +The exchange chooses a random $n \leftarrow random \in \mathbb{Z}_p$ and calculates $R := nG$ as before. +In comparison to the Schnorr Signature Scheme (see section \ref{sec:schnorr-sig}) we generate two random blinding factors $\alpha, \beta \leftarrow random \in \mathbb{Z}_p$ to achieve \textit{blindness}. +The User then calculates $R' := R + \alpha G + \beta X$. +This $R'$ is then used to calculate $c' := H(R',m)$ and is blinded with $b$ as in $c := c' + \beta \mod p$. +The challenge $c$ is then blindly signed by the signer $s := n+cx \mod p$. +The User checks if the signature is valid the same way as in the original protocol. +Finally the user has to unblind $s$ as in $s' := s + \alpha \mod p$. +Now the unblinded signature is $\sigma := \langle R',s' \rangle$. +This scheme is described in figure \ref{fig:schnorr-blind-sign-scheme}. +More details can be found in the \textit{Blind Schnorr Signatures and Signed ElGamal Encryption in the Algebraic Group Model} paper \cite{cryptoeprint:2019:877}. + +%The unblinded signature can be verified with $s'G = R' + c'X$, since following equation is satisfied:\\ +%$s'G = sG + \alpha G = (r + cx)G + \alpha G = R + \alpha G + \beta X + (-\beta + c)X = R' + c'X = R' + H(R',m)X$ \cite{cryptoeprint:2019:877}.\\ + +To verify the signature, the verifier has to check if the following equation holds: +\begin{align*} + s'G & = R' + c' X + \\ &= R' + H(R', m) X +\end{align*} +$ s', R' $ together form the signature, $ X $ is the public key and $ m $ is message. + +The reason why this works is that the original Schnorr signature verification algorithm remains the same in blind signatures. +\begin{align*} + sG = R + c X +\end{align*} + +By replacing $ s, R, c, $ with the values used in the blind signature scheme (as in figure \ref{fig:schnorr-blind-sign-scheme}) +\begin{align*} + \\ s &= s' - \alpha + \\ R &= R' - \alpha G - \beta X + \\ c &= c' + \beta +\end{align*} + +we receive the following equation: +\begin{align*} + sG & = R + c X + \\ (s' - \alpha)G &= R' - \alpha G - \beta X + (c' + \beta)X + \\ s'G - \alpha G &= R' - \alpha G + c' X + \\ s'G &= R' + c' X +\end{align*} + +\begin{figure}[htp] + \begin{equation*} + \begin{array}{ l c l } + % preliminaries + \text{User} & & \text{Signer} + \\ \text{knows:} & \text{public parameters:} & \text{knows:} + \\ \text{public key } X & \langle p, \mathbb{G}, G, H\rangle & \text{private signing key } x, X := xG + \\ & & r \leftarrow random \in \mathbb{Z}_p + \\ & & R := rG + \\ & \xleftarrow[\rule{2.5cm}{0pt}]{R} & + \\ \alpha, \beta \leftarrow random \in \mathbb{Z}_p + \\ R' := R + \alpha G + \beta X + \\ c' := H(R',m) + \\ c := c' + \beta \mod p + \\ & \xrightarrow[\rule{2.5cm}{0pt}]{c} & + \\ & & s := r+cx \mod p + \\ & \xleftarrow[\rule{2.5cm}{0pt}]{s} & + \\ \text{check } sG = R + cX + \\ s' := s + \alpha \mod p + \\ \sigma := \langle R',s' \rangle + \end{array} + \end{equation*} + \caption{The broken Schnorr Blind Signature Scheme} + \label{fig:schnorr-blind-sign-scheme} +\end{figure} + +\paragraph{Blindness} +Blind Schnorr Signatures also achieve \textit{perfect blindness} (\autoref{sec:blind-sign-perfect-blindness}). \cite{spring:wallet-db-with-observers} \cite{cryptoeprint:2019:877} + +\paragraph{ROS Problem} +\label{par:ros-problem} +The security of Blind Schnorr Signatures relies on an additional hardness assumption, the \textit{\acl{ROS}} or ROS problem. \cite{Schnorr01securityof} +Solving the \ac{ROS} problem breaks the unforgeability property of blind Schnorr signatures by finding $l + 1$ signatures out of $l$ signing operations. +David Wagner showed in his paper that the \ac{ROS} problem can be reduced to the $(l+1)$-sum problem and therefore showed that an attack is practicable. \cite{wagner:generalized-bday-prob} +More details about \ac{ROS} and Wagner's algorithm can also be found in the paper \textit{Blind Schnorr Signatures and Signed ElGamal Encryption in the Algebraic Group Model} \cite{cryptoeprint:2019:877}. +\\ +Due to the possible attack, Blind Schnorr Signatures are considered \textbf{broken} and should not be used. +The next section \ref{sec:clause-blind-schnorr-sig} introduces a modified version for which the \ac{ROS} problem is much harder to solve. +\\ +The \ac{ROS} problem is a recent research topic. +Recently a paper about the (in)security of \ac{ROS} was published. \cite{cryptoeprint:2020:945} +The scheme introduced in the next section \ref{sec:clause-blind-schnorr-sig} is considered secure in 2021. +It is important to keep in mind that the \ac{ROS} problem is much newer and there is open research done. + +\subsubsection{Clause Blind Schnorr Signature Scheme} +\label{sec:clause-blind-schnorr-sig} +The Clause Blind Schnorr Signature Scheme is a modification of the Blind Schnorr Signature Scheme for which the \ac{ROS} problem is harder to solve. +The Clause Blind Schnorr Signature Scheme does this by choosing two random values $r_0, r_1$ and calculating $R_0 := r_0G; R_1 := r_1G$. +The user generates the blinding factors twice $\alpha_0, \alpha_1, \beta_0, \beta_1 \leftarrow random \in \mathbb{Z}_p$. +The user then calculates the challenges as before $c_0' := H(R_0',m); c_0 := c_0' + \beta_0 \mod p$ and $c_1' := H(R_1',m); c_1 := c_1' + \beta_1 \mod p$. +After the signer receives the two challenges $c_0$ and $c_1$, the signer randomly chooses $b \leftarrow random \{0, 1\}$ and calculates only $s_b$ as in $s := r_b+c_bx \mod p$. +The User receives $s, b$ and can unblind the signature to receive his signature $\sigma := \langle R'_b, s'_b \rangle$. +The verification algorithm remains the same for Clause Blind Schnorr Signature Scheme. +Figure \ref{fig:clause-blind-schnorr-sign-scheme} shows the Clause Blind Schnorr Signature Scheme. +More details about the scheme can be found in the paper \textit{Blind Schnorr Signatures and Signed ElGamal Encryption in the Algebraic Group Model} \cite{cryptoeprint:2019:877}. + + +\begin{figure} + \begin{equation*} + \begin{array}{ l c l } + % preliminaries + \text{User} & & \text{Signer} + \\ \text{knows:} & \text{public parameters:} & \text{knows:} + \\ \text{public key } X & \langle p, \mathbb{G}, G, H\rangle & \text{private signing key } x, X := xG + \\ & & r_0, r_1 \leftarrow random \in \mathbb{Z}_p + \\ & & R_0 := r_0G + \\ & & R_1 := r_1G + \\ & \xleftarrow[\rule{2.5cm}{0pt}]{R_0, R_1} & + \\ \alpha_0, \alpha_1, \beta_0, \beta_1 \leftarrow random \in \mathbb{Z}_p + \\ R_0' := R_0 + \alpha_0 G + \beta_0 X + \\ R_1' := R_1 + \alpha_1 G + \beta_1 X + \\ c_0' := H(R_0',m) + \\ c_1' := H(R_1',m) + \\ c_0 := c_0' + \beta_0 \mod p + \\ c_1 := c_1' + \beta_1 \mod p + \\ & \xrightarrow[\rule{2.5cm}{0pt}]{c_0, c_1} & + \\ & & b \leftarrow random \in \{ 0,1\} + \\ & & s := r_b+c_bx \mod p + \\ & \xleftarrow[\rule{2.5cm}{0pt}]{b, s} & + \\ \text{check } sG = R + cX + \\ s' := s + \alpha_b \mod p + \\ \sigma := \langle R_b',s' \rangle + \end{array} + \end{equation*} + \caption{The Clause Schnorr Blind Signature Scheme} + \label{fig:clause-blind-schnorr-sign-scheme} +\end{figure} + +\paragraph{Blindness} +\label{par:prop-blindness-cs} +\gls{CSBS} also achieve \textit{perfect blindness} as in Schnorr Blind Signatures (see \autoref{sec:blind-rsa-sign}). \cite{cryptoeprint:2019:877} + + +\subsection{Diffie Hellman Key Exchange} +As source for this section, pages 383-386 were used in \textit{Cryptography made Simple} \cite{modernCrypto}. +\label{sec:preliminaries-DHKE} +The \acl{DHKE} is a well proofed and well understood key exchange mechanism. +\ac{DHKE} relies mainly on the \acl{DLP}. +\ac{DHKE} is used for key exchange in many protocols today (e.g. TLS cipher suites). + +\subsubsection{Hardness Assumptions} +\label{sec:dlp} +As already stated, the \ac{DHKE} relies on the assumption that calculating the discrete logarithm is hard. +The \ac{DLP} is in $G$, where $G$ is a finite abelian group of prime order q. +This could either be a subgroup of the multiplicative group of a finite field or the set of points on an elliptic curve over a finite field. +Given $g,h \in G$, find x such that $g^x = h$. + +Further, \ac{CDH} and \ac{DDH} are important hardness assumption, which can be reduced to the \ac{DLP}. +Hardness assumptions are introduced very briefly. +In this work we believe that these well proofed and well tested hardness assumptions hold. +(See Chapter 3.1 \textit{Cryptography made Simple} \cite{modernCrypto} for more details on DH hardness assumptions.) + +\subsubsection{Protocol} +Alice and Bob want to securely exchange a key with \ac{DHKE}. +Alice has a private key $a$ and a corresponding public key $A = g^a \mod p$. +Bob has a private key $b$ and a corresponding public key $B = g^b \mod p$. +With elliptic curves, the private key is a multiplication factor for a base point $g$ (see example on page 385 \textit{Cryptography made Simple} \cite{modernCrypto}). + +Alice now sends her public key $A$ to Bob. +Bob can then calculate $k = A^b \mod p = g^{ab} \mod p$ and sends his public key $B$ to Alice. +Alice can then calculate $k = B^a \mod p = g^{ab} \mod p$. +Both get the same key $k$ as result of the key exchange. +Note: This protocol on its own is not an authenticated key exchange, which means that Man-in-the-Middle attacks are possible. + +A different way of looking at \ac{DHKE} is by thinking of a lock which can be unlocked by two (private) keys. +If one of the two private keys are known, one could calculate $k$ on its own. +Taler's refresh protocol (see \ref{sec:refresh-protocol}) uses \ac{DHKE} in a very interesting way. + +\subsection{Cut and Choose Protocol} +\label{sec:preliminaries-cut-choose} +A good introduction to cut and choose protocols gives the Paper from Claude Crépeau (\cite{Crépeau2005} References to the important examples can be found in the paper.): +\begin{center} + \textit{ + "A cut and choose protocol is a two-party protocol in which one party tries to convince another party that some data he sent to the former was honestly constructed according to an agreed upon method. + Important examples of cut-and-choose protocols are interactive proofs, interactive arguments, zero-knowledge protocols, witness indistinguishable and witness hiding protocols for proving knowledge of a piece of information that is computationally hard to find. + Such a protocol usually carries a small probability that it is successful despite the fact that the desired property is not satisfied. + \\\dots\\ + The expression cut-and-choose was later introduced by David Chaum in analogy to a popular cake sharing problem: + Given a complete cake to be shared among two parties distrusting of each other (for reasons of serious appetite). + A fair way for them to share the cake is to have one of them cut the cake in two equals hares, and let the other one choose his favourite share. + This solution guarantees that it is in the formers best interest to cut the shares as evenly as possible." + } +\end{center} + +Talers cut and choose protocol is \textit{zero knowledge}, which means that nothing about the secret is learned. +The cut and choose protocol used in Taler is explained further when the refresh protocol is discussed (see \ref{sec:refresh-protocol}). + +\section{Taler Protocols} +In section \ref{sec:taler-intro} a brief overview of how \acl{Taler} works is given. All the relevant preliminaries are covered in section \ref{sec:crypto-preliminaries}. +In this section a closer look at the different protocols is taken. + +\subsection{Withdrawal Protocol} +\label{sec:withdrawal} +The withdrawal protocol is described in chapter 4.7.2 of \cite{dold:the-gnu-taler-system}. +Before coins can be withdrawn, the customer generates a reserve key pair $ w_s, W_p \leftarrow Ed25519.KeyGen() $. +He then transfers a certain amount of money from his bank to the exchange's bank via wire transfer. +This payment must include the reserve public key $ W_p $. +The customer will later authorize withdrawals with a signature using his private reserve key. +%The customer can then authenticate, since he is in possession of the private reserve key. +As soon as the exchange has received the payment, the withdrawal for coins with a value $ i $ can begin (described in figure \ref{fig:withdrawal-process}). + +At this stage the client knows the reserve private key and the public denomination key. +The customer can then create coins up to the amount included in the wire transfer. +The coin creation and blind signatures are described in section \ref{sec:blind-sign-fdh}. +So the client generates a planchet (an Ed25519 key pair) and blinds it. +This blinded planchet is then signed by the customers private reserve key, to prove that the customer is eligible to withdraw the coin. +The exchange who receives the blinded planchet and the signature first checks whether the signature is valid with the public reserve key sent with the wire transfer. +When successful, the exchange blindly signs the planchet, returns the signature and notes the amount withdrawn of the reserve. +The customer unblinds the signature, checks its validity and persists the coin. +The state machine of a coin can be seen in figure \ref{fig:coin:states}. + +\begin{figure}[htp] + \begin{center} + \includegraphics[scale=0.58]{coin.pdf} + \end{center} + \caption{State machine of a coin (source: \cite{pic:coin-state-machine})} + \label{fig:coin:states} +\end{figure} + +\begin{figure}[htp] + \begin{equation*} + \resizebox{1.0\textwidth}{!}{$\displaystyle + \begin{array}{ l c l } + \text{Customer} & & \text{Exchange} + \\ \text{knows:} & & \text{knows:} + \\ \text{reserve keys } w_s, W_p & & \text{reserve public key } W_p + \\ \text{denomination public key } D_p = e, N & & \text{denomination keys } d_s, D_p + \\ & & + \\\text{generate coin key pair:} & & + \\ c_s, C_p \leftarrow Ed25519.KeyGen() & & + \\ \text{blind:} & & + \\ r \leftarrow random \in \mathbb{Z}_N^* & & + \\ m' = \text{FDH}(N, C_p)*r^{e} \mod N & & + \\ \text{sign with reserve private key:} & & + \\ \rho_W = D_p, m' & & + \\ \sigma_W = \text{Ed25519.Sign}(w_s, \rho_W) & & + \\ & \xrightarrow[\rule{2.5cm}{0pt}]{\rho = W_p, \sigma_W, \rho_W} & + \\ & & \text{verify if denomination public key} + \\ & & \text{is valid} + \\ & & \text{check } \text{Ed25519.Verify}(W_p, \rho_W, \sigma_W) + \\ & & \text{decrease balance if sufficient} + \\ & & \text{sign:} + \\ & & \sigma'_c = (m')^{d_s} \mod N + \\ & \xleftarrow[\rule{2.5cm}{0pt}]{\sigma'_c} & + \\ \text{unblind:}& & + \\ \sigma_c = \sigma'_c*r^{-1} & & + \\ \text{verify signature:}& & + \\ \text{check } \sigma_c^{e} = \text{FDH}(N, C_p) & & + \\ & & + \\ \text{resulting coin: } c_s, C_p, \sigma_c, D_p & & + \end{array}$ + } + \end{equation*} + \caption{Withdrawal process} + \label{fig:withdrawal-process} +\end{figure} + +\subsubsection{Withdraw Loophole} +\label{sec:withdraw-loophole} +The withdraw loophole allows withdraw operations where owner of the resulting coins isn't the owner of the reserve that the coins where withdrawn from. +It is used for tipping (described in section \ref{sec:tipping}) and can therefore be seen as a feature. + +By misusing the withdraw loophole, untaxed and untraceable payments can be performed. +Figure \ref{fig:withdraw-loophole-exploit} explains how such a payment would work. +Note that we omitted the parts leading up to the coin creation (contract, agreement of price, number of coins and their denominations). +This is how it works on a high level: +\begin{enumerate} + \item The malicious merchant generates and blinds coins, which are then transmitted to the customer + \item The customer authorizes the withdraw from his reserve by signing the blinded coins with the private key of his reserve, thus generating withdraw confirmations. + \item The withdraw confirmations are transmitted to the exchange, which generates the signatures and returns them to the malicious merchant. + \item The malicious merchant unblinds the signatures. + He is now in possession of the coin, thus the payment is completed. +\end{enumerate} + +\begin{figure}[htp] + \begin{equation*} + \resizebox{1.0\textwidth}{!}{$\displaystyle + \begin{array}{ l c l} + % preliminaries + \textbf{Customer} & & \textbf{malicious Merchant} + \\ \text{knows:} & & \text{knows:} + \\ \text{reserve keys } w_s, W_p + \\ \text{denomination public key } D_p = \langle e, N \rangle & & \text{denomination public key } D_p = \langle e, N \rangle + \\ + % generate coin + \\ & & \text{generate coin key pair:} + \\ & & c_s, C_p \leftarrow \text{Ed25519.KeyGen}() + % blind + \\ & & \text{blind:} + \\ & & r \leftarrow random \in \mathbb{Z}_N^* + \\ & & m' := \text{FDH}(N, C_p)*r^{e} \mod N + % sing with reserve sk + \\ & \xleftarrow[\rule{2cm}{0pt}]{m'} + \\ \text{sign with reserve private key:} + \\ \rho_W := \langle D_p, m' \rangle + \\ \sigma_W := \text{Ed25519.Sign}(w_s, \rho_W) + \\ & \xrightarrow[\rule{2cm}{0pt}]{ \langle W_p, \sigma_W, \rho_W \rangle } + \\ + \hline + \\ + \textbf{malicious Merchant} & & \textbf{Exchange} + \\\text{knows:} & & \text{knows:} + \\& & \text{reserve public key } W_p + \\ \text{denomination public key } D_p = \langle e, N \rangle & & \text{denomination keys } d_s, D_p + \\ + \\ & \xrightarrow[\rule{2cm}{0pt}]{ \langle W_p, \sigma_W, \rho_W \rangle } + \\ & & \langle D_p, m' \rangle := \rho_W + \\ & & \text{verify if } D_p \text{ is valid} + \\ & & \textbf{check } \text{Ed25519.Verify}(W_p, \rho_W, \sigma_W) + \\ & & \text{decrease balance if sufficient} + \\ & & \text{sign:} + \\ & & \sigma'_c := (m')^{d_s} \mod N + \\ & \xleftarrow[\rule{2cm}{0pt}]{\sigma'_c} + \\ \text{unblind:} + \\ \sigma_c := \sigma'_c*r^{-1} + \\ \text{verify signature:} + \\ \textbf{check if } \sigma_c = \text{FDH}(N, C_p) + \\ + \\ \text{resulting coin: } \langle c_s, C_p, \sigma_c, D_p \rangle + \end{array}$ + } + \end{equation*} + \caption{Untaxed payment using the withdraw loophole} + \label{fig:withdraw-loophole-exploit} +\end{figure} + +\subsection{Payment Process} +The payment process is divided in two steps described by the spend and deposit protocols. +Details about the payment process can be found in multiple chapters in \cite{dold:the-gnu-taler-system}: +Chapter 4.7.3 describes the spend and deposit protocols. +Chapter 4.1.4 describes more general aspects as well as the contract header and deposit permission structure and details. +\\On a high level, payment works like this: +\begin{enumerate} + \item The customer submits a shopping cart (one or more items to buy) and commits his intent to buy them. + \item The merchant puts together the contract terms containing the necessary information for payment, signs it and sends both to the customer (spend protocol). + \item The customer generates a deposit permission and its signature for each coin used in the transaction (spend protocol). + \item The customer forwards the deposit permission(s) to the merchant (spend protocol). + If the deposit protocol is performed by the customer, this step can be skipped. + \item Either the customer or the merchant sends the deposit permission(s) to the exchange (deposit protocol). + \item The exchange processes the deposit permission and returns a deposition confirmation when successful (deposit protocol). + \item If the deposit protocol was performed by the customer, the deposit confirmation(s) have to be forwarded to the merchant. +\end{enumerate} + +\subsubsection{Spend Protocol} +The payment process begins when a customer submits a shopping cart (one or more items to buy) and commits his intent to buy them. +The merchant has a key pair skM, pkM of which the customer knows the public key. +Note that certain details contained in contract header or deposit permission like merchant \ac{KYC} information, deposit and refund deadlines and fees are left out. +The deposit state machine can be seen in figure \ref{fig:deposit:states}. +\begin{figure}[htp] + \begin{center} + \includegraphics[scale=0.7]{deposit.pdf} + \end{center} + \caption{State machine of a deposit (source: \cite{pic:deposit-state-machine})} + \label{fig:deposit:states} +\end{figure} + +\begin{enumerate} + \item The merchant puts together the following information (without transmitting them) and requests payment: + \begin{itemize} + \item price $ v $ + \item exchange $E_m$ (multiple possible) + \item account $A_m$ at the exchange $E_m$ + \item info (free form details containing the full contract) + \end{itemize} + \item The customer generates an Ed25519 claim key pair $ p_s, P_p $ and submits the public key to the merchant. + This key can be used by the customer to prove that he didn't copy contract terms from another customer. + \item The merchant puts together the contract terms $ \rho $ and signs it with skM, resulting in the signature $ \sigma_P$. + \\The contract terms contains: + \begin{itemize} + \item $E_m$ (exchange) + \item $A_m$ (account at exchange $E_m$) + \item pkM + \item Hash($v$, info) + \item $ P_p $ + \end{itemize} + $ \rho_P $ (contract terms), $ \sigma_P$ (contract terms signature), $ v $ (price) and info are submitted to the customer. + \item The customer does the following checks: + \begin{itemize} + \item Is the signature of the contract terms correct? + \item Is the public key referenced in the contract terms the same as the one generated in step 2? + \item Is the hash of price and info the same as the one in the contract terms? + \end{itemize} + If all checks are successful, the customer chooses one or more coins to be spent. + For each coin, a deposit permission $ \rho_{D} $ and its signature $ \sigma_{D} $ is generated. + The deposit permission contains the following information: + \begin{itemize} + \item Coin public key $ C_p $ + \item Coin denomination public key pkD + \item Coin signature $ \sigma_C $ + \item Value to be spent for this coin $f$ (greater than zero, up to the residual value of the coin) + \item Hash of the contract terms $ \rho_P $ + \item Account of merchant $A_m$ (at exchange $E_m$) + \item Merchant public key pkM + \end{itemize} + The list of deposit permissions and their signatures is transferred to the merchant who then executed the deposit protocol. + Note that the customer is also able to deposit the coins (instead of the merchant), this is used in cases where the merchant doesn't have an internet connection, but the customer does. + This can be useful in cases where the merchant becomes unresponsive. + The customer can prove that he paid in time. + \item The merchant receives the deposit permissions and signatures and uses the deposit protocol to execute the payment. +\end{enumerate} + +Before we continue with the deposit protocol, there are a few interesting details to point out (described in \cite{dold:the-gnu-taler-system} section 4.1.4): +\begin{itemize} + \item The contract terms and the deposit permission are \ac{JSON} objects. + \item The contract terms only contains a cryptographic hash of the contract. + This improves privacy since the exchange doesn't have to know the full contract details, but still makes it possible to identify the contract in case of a dispute or some form of auditing. + \item At the point where the merchant completes step three (submits the contract terms and its signature) to the customer, the customer is able to finish the transaction using the deposit protocol without interaction of the merchant. + This means that the merchant at this step must be able to fulfill the contract if the customer completes the payment process. +\end{itemize} + +\subsubsection{Deposit Protocol} +\label{sec:deposit-protocol} +As previously mentioned, both parties (customer and merchant) are able to run the deposit protocol. +In the following description, the term merchant will be used, but could be replaced by customer. +In cases where there are multiple deposit permissions (meaning that multiple coins are used to pay), the deposit protocol is run separately for each deposit permission. +\begin{enumerate} + \item The merchant submits the deposit permission and its signature to the exchange. + \item The exchange runs these checks: + \begin{itemize} + \item Is the denomination public key referenced in the deposit permission valid (issued by the exchange, lifetime between start and deposit/refresh expiration, not revoked)? + \item Is the deposit permission signature $ \sigma_{D} $ a correct signature of the deposit permission $ \rho_{D} $ with the Ed25519 coin public key $ C_p $ referenced in the deposit permission? + \item Is there a processed deposit recorded in the exchanges databases based on coin public key and contract terms hash (replay/double spending)? + If not, continue with the next check since this is correct and expected behavior. + \\If there is, does the recorded deposit permission equal the one we're currently checking? + If this is the case, further checks can be skipped and the deposit confirmation signature can be returned to the customer. + If not, the process should be terminated because there's something wrong with the transaction. + \item Is the signature of the coin valid? + \item Is $ f $ (the value to be spent) smaller or equal the residual value of the coin (check for overspending attempt)? + \end{itemize} + If all checks are successful, the exchange saves the deposit record containing the deposit permission and its signature in a database, subtracts the spent value from the residual value of the coin and schedules the money transfer to the merchant's account $ A_m $ (grouping payments is done to reduce payment fees). + \\The exchange calculates a deposit confirmation signature $ \sigma_{DC} $ for the deposit permission with the exchange signing private key and returns them to the merchant. + \\This signature is also used to prove that a merchant was the first to receive payment from a certain coin. + Without this, an evil exchange could later deny confirming a payment and claim double spending. + With the signature, the merchant can prove that the payment was confirmed by the exchange, thus delegating the responsibility (and potential financial loss) for double spending detection to the exchange. + \item The merchant checks the signatures of the deposit confirmations with the exchange signing public key. +\end{enumerate} + +It may happen that a payment gets stuck as partially complete, for example when a backup of a wallet is restored and one coin or more have already been spent (\cite{dold:the-gnu-taler-system} chapter 4.1.4). +In this case, the customer can retry the payment with a different coin. +If this isn't possible, the payment can be refunded (assuming refunds were enabled for this payment). +Other scenarios were described in Dold's thesis, but dismissed due to privacy concerns. +This means that disputes have to be settled aside from Taler when a customer isn't able to fully pay and refunds are disabled. + +\subsubsection{Web Payment Scenarios} +The following methods are Taler-native methods for paying and payment validation. +They are not identity-based, meaning that they do not require a login or similar techniques. +Note that other methods could be implemented depending on the scenario. + +\begin{itemize} + \item \textbf{Resource-based web payment} (\cite{dold:the-gnu-taler-system} chapter 4.1.5): + All Taler contract terms contain a fulfillment URL. + This can either be a direct link to a digital product (like a movie, a song or a document), or to a confirmation page. + When a browser opens a fulfillment URL for a resource that hasn't yet been paid for, the merchant requests payment. + The wallet then generates and submits a claim key pair, thus claiming the contract, which then can be paid (if the user accepts the contract). + The browser can then retry to navigate to the fulfillment URL, this time submitting the contract order ID as parameter, which the merchant can check if it has been paid (and deliver the content if this is the case). + This is known as the extended fulfillment URL + \\The wallet stores fulfillment URLs and their associated contracts. + Upon receiving a payment request, the wallet searches the stored fulfillment URLs and if it found one, automatically forwards the user to the extended fulfillment URL containing the contract. + \item \textbf{Session-bound payments and sharing} (\cite{dold:the-gnu-taler-system} chapter 4.1.6): + So far, validating payment is done using the extended fulfillment URL. + The problem with this approach is that this URL can be shared, which is a problem for digital content. + To make this more difficult, the seller's website assigns the user a session ID (for example using a session cookie) and extends the extended fulfillment URL with a session signature parameter. + This parameter can be used by the merchant to check if the user paid for the resource or replayed the payment in this session. + \item \textbf{Embedded content} (\cite{dold:the-gnu-taler-system} chapter 4.1.7): + When paying to access multiple resources behind a paywall (instead of just one resource), the previously described methods do not work. + Dold's thesis suggest two methods: + \begin{enumerate} + \item A session cookie can be set by accessing the fulfillment URL. + When the browser requests a subresource, the merchant can verify the session cookie. + \item In this scenario, the fulfillment URL would show the resources behind the paywall. + Upon opening the extended fulfillment URL, the merchant's website would add an authentication token to the URLs of the subresources. + When accessing a subresource, the merchant can check the authentication tokens validity. + \end{enumerate} +\end{itemize} + +\subsection{Refresh Protocol} +\label{sec:refresh-protocol} +This section provides a description of the refresh protocol. +The technical details can be found in 4.7.4 \cite{dold:the-gnu-taler-system}. +All relevant preliminaries needed to understand the technical details were already introduced in this work. + +\subsubsection{Introduction} +A protocol to refresh coins is needed for many reasons. +One important reason is giving change. +Similar to the real world, there are often situations where one does not have the exact amount of coins. +A change protocol therefore provides a lot of convenience for the users. +Without such a mechanism it would be quite hard to use. \\ +Giving change is not trivial, since \ac{AML} and \ac{CFT} compliance still needs to hold. +On the other side, the change still needs to provide privacy for the customer. +Thus, the change must be unlinkable to the previous (or any) transaction.\\ +Complying with \ac{AML} and \ac{CFT} while preserving the customer's anonymity may sound like a contradiction at first. +However, Taler has a clever way to solve this problem with the refresh protocol. + +The general idea is that the new coin can be derived from the private key of the old coin. + +\subsubsection{DH Lock} +\ac{DHKE} was introduced in section \ref{sec:preliminaries-DHKE}. +Taler uses \ac{ECDH} as a lock with two possible keys to unlock the shared key. +To create such a lock, one creates two key pairs $C = cG$ and $T = tG$. +To unlock now means calculating $k$. +Both private keys, $c$ and $t$ are now able to calculate $k = tC = t(cG) = c(tG) = cT$ and thus can unlock the lock. +This $k$ can then be used to derive the private key of the new coin and the corresponding blinding factor. + +\subsubsection{Customer Setup} + +The customer, which holds the old partially spend coin and knows \\$C_{old} = \text{Ed25519.GetPub}(c_{old})$. + A transfer key $T = \text{Ed25519.GetPub}(t)$ is then (randomly) generated by the customer. + \\The key pairs $T = \text{Ed25519.GetPub}(t)$ and $C_{old} = \text{Ed25519.GetPub}(c_{old})$ form the lock with two keys that was introduced before. + The customer then creates $x = c_{old}, T = tC_{old}$ and derives $c_{new}$, the private key of the new coin and $b_{new}$ the blinding factor of the new key. + As usual the customer calculates the coins public key $C_{new} = \text{Ed25519.GetPub}(c_{new})$, hashes the new coin with \gls{fdh} $f_{new} = \text{FDH}(C_{new})$ and blinds the hash $f'_{new} = f_{new}b_{new}^e$. + The $f'_{new}$ is then transmitted to the exchange. + \\Figure \ref{fig:refresh-derive} shows how the new coin is derived as explained above. + + \begin{figure}[htp] + \centering + \fbox{% + \procedure[codesize=\small]{$\text{RefreshDerive}(s, \langle e,N\rangle, C_p)$}{% + t := \text{HKDF}(256, s, \text{"t"}) \\ + T := \text{Curve25519.GetPub}(t) \\ + x := \textrm{ECDH-EC}(t, C_p) \\ + r := \text{SelectSeeded}(x,\mathbb{Z}^*_N)\\ + c'_s := \text{HKDF}(256,x,"c")\\ + C'_p := \text{Ed25519.GetPub}(c'_s)\\ + \overline{m} := r^e * C'_p \mod N\\ + \pcreturn \langle t, T, x, c_s', C_p', \overline{m}\rangle + } + } + \caption[RefreshDerive algorithm]{The RefreshDerive derives a new coin from a dirty coin with a seed. The DH-Lock is used to create the link used in the linking protocol} + \label{fig:refresh-derive} + \end{figure} + + Now with the DH Lock the person who is in possession of the old key can always recalculate and thus spend the new coin (as long as it knows the public transfer key $T$). + However, there is one last thing: How does the exchange know that the old key is linked to the new one? + To comply with \ac{AML} and \ac{CFT}, the exchange wants to ensure that the person who created the new coin is also in possession of the old coin. + A link needs to be created in a way that nobody can link the old coin to the new coin, except the person in possession of the old coin. + The person in possession of the old coin needs to proof to the exchange that this link was created without revealing the link. + This problem is solved with the cut and choose protocol in the next section. + + \begin{figure}[htp] + \centering + \includegraphics[height=0.5\textwidth]{taler_refresh_transfer_key.png} + \caption{Taler refresh protocol, transfer key setup (source: \cite{pic:refresh-prot})} + \label{fig:taler-refresh-transfer-key} + \end{figure} + \newpage + \subsubsection{Cut \& Choose} + Instead of doing the customer setup once, it is done $n$ times. + The customer generates $n$ different transfer keys $t_1, t_2 \dots t_n$. + For each key the whole calculations are done and all the blinded coins $f'_1, f'_2 \dots f'_n$ are sent to the exchange together with the old coins public key and signature. \\ + The exchange responds with a randomly picked number from $1$ to $n$. + The customer has to reveal all the transfer keys, \textbf{except the one picked by the exchange.} + The exchange makes the same calculations with the revealed private transfer keys (without knowing the private key $c_{old}$). + The exchange can now verify whether the customer was honest or not. + A evil customer could create a new coin which is not linked to the old coin (without the DH lock). + Such attacks will be detected with a high probability in this protocol. + Since the $t_x$ picked by the exchange is not checked, an evil customer can win this with a probability of $1/n$. + Already with $n=3$ an attack is not in the customers interest due to economic reasons. + In 2 out of 3 cases the exchange would detect the attack and would keep the money and the customer would have lost it. + The probability can be adjusted with $n$. + With increasing size of $n$ the attack becomes even less attractive. + When the cut and choose protocol ended successfully, the value of the old coin is set to zero. + + \begin{figure}[htp] + \centering + \includegraphics[height=0.5\textwidth]{taler_cut_and_choose.png} + \caption{Taler refresh protocol, cut and choose (source: \cite{pic:refresh-prot})} + \label{fig:taler-cut-and-choose} + \end{figure} + + \subsection{Commit Phase} + \label{sec:commit-phase-rsa} + The refresh protocol is implemented in two phases. + The commit phases creates $k$ derives and commits to this values by calculating a hash over the derives. + On the exchange's side various checks are done to validate the request. + Detailed steps of the commit phase are shown in figure \ref{fig:refresh-part1}. + + + \begin{figure} + \begin{equation*} + \resizebox{1.0\textwidth}{!}{$\displaystyle + \begin{array}{ l c l } + % preliminaries + \text{Customer} & & \text{Exchange} + \\ \text{knows:} & & \text{knows:} + \\ \text{denomination public key } D_{p(i)} & & \text{denomination keys } d_{s(i)}, D_{p(i)} + \\ \text{coin}_0 = \langle D_{p(0)}, c_s^{(0)}, C_p^{(0)}, \sigma_c^{(0)} \rangle & & + % refresh request + \\ \text{Select} \langle N_t, e_t\rangle := D_{p(t)} \in D_{p(i)} + \\ \textbf{for } i = 1, \dots, \kappa: % generate k derives + \\ s_i \rightarrow \{0,1\}^{256} % seed generation + \\ X_i := \text{RefreshDerive}(s_i, D_{p(t)}, C_p^{(0)}) + \\ (t_i, T_i, x_i, c_s^{(i)}, C_p^{(i)}, \overline{m}_i) := X_i + \\ \textbf{endfor} + \\ h_T := H(T_1, \dots, T_k) + \\ h_{\overline{m}} := H(\overline{m}_1, \dots, \overline{m}_k) + \\ h_C := H(h_t, h_{\overline{m}}) + \\ \rho_{RC} := \langle h_C, D_{p(t)}, D_{p(0)}, C_p^{(0)}, \sigma_C^{(0)} \rangle + \\ \sigma_{RC} := \text{Ed25519.Sign}(c_s^{(0), \rho_{RC}}) + \\ \text{Persist refresh-request} \langle \rho_{RC}, \sigma_{RC} \rangle + \\ & \xrightarrow[\rule{2.5cm}{0pt}]{\rho_{RC}, \sigma_{RC}} & + % Exchange checks refresh request + \\ & & (h_C, D_{p(t)}, D_{p(0)}, C_p^{(0)}, \sigma_C^{(0)} = \rho_{RC}) + \\ & & \textbf{check} \text{Ed25519.Verify}(C_p^{(0)}, \sigma_{RC}, \rho_{RC}) + \\ & & x \rightarrow \text{GetOldRefresh}(\rho_{RC}) + \\ & & \textbf{Comment: }\text{GetOldRefresh} \\(\rho_{RC} \mapsto \{\bot,\gamma\}) + \\ & & \pcif x = \bot + \\ & & v := D(D_{p(t)}) + \\ & & \langle e_0, N_0 \rangle := D_{p(0)} + \\ & & \textbf{check } \text{IsOverspending}(C_p^{(0)}, D_ {p(0)}, v) + \\ & & \textbf{check } D_{p(t)} \in \{D_{p(i)}\} + \\ & & \textbf{check } \text{FDH}(N_0, C_p^{(0)}) \equiv_{N_0} (\sigma_0^{(0)})^{e_0} + \\ & & \text{MarkFractionalSpend}(C_p^{(0)}, v) + \\ & & \gamma \leftarrow \{1, \dots, \kappa\} + \\ & & \text{Persist refresh-record } \langle \rho_{RC},\gamma \rangle + \\ & & \pcelse + \\ & & \gamma := x + \\ & & \textbf{endif} + \\ & \xleftarrow[\rule{2.5cm}{0pt}]{\gamma} & + \\ + \\ + \\ & \textit{Continued in figure \ref{fig:refresh-part2}} & + %\\ \pcintertext[dotted]{(Continued in Figure)} + \end{array}$ + } + \end{equation*} + \caption{Refresh protocol (commit phase)} + \label{fig:refresh-part1} + \end{figure} + + \subsection{Reveal Phase} + \label{sec:reveal-phase-rsa} + In the reveal phase the customer receives $\gamma$ and he reveals the all the seeds to the exchange, except for $s_\gamma$. + The exchange can then verify if the customer was honest with probability $1/k$. + On success the exchange will return the blinded signature of the new coin and the customer can then unblind and store the coin. + The reveal phase is described in figure \ref{fig:refresh-part2} + + \begin{figure} + \begin{equation*} + \resizebox{1.0\textwidth}{!}{$\displaystyle + \begin{array}{ l c l } + % preliminaries + \text{Customer} & & \text{Exchange} + \\ & \textit{Continuation of figure \ref{fig:refresh-part1}} & + \\ + \\ + % Check challenge and send challenge response (reveal not selected msgs) + \\ & \xleftarrow[\rule{2.5cm}{0pt}]{\gamma} & + \\ \textbf{check } \text{IsConsistentChallenge}(\rho_{RC}, \gamma) + \\ \textbf{Comment: } \text{IsConsistentChallenge}\\(\rho_{RC}, \gamma) \mapsto \{ \bot,\top \} + \\ + \\ \text{Persist refresh-challenge} \langle \rho_{RC}, \gamma \rangle + \\ S := \langle s_1, \dots, s_{\gamma-1}, s_{\gamma+1}, \dots,s_x \rangle % all seeds without the gamma seed + \\ \rho_L = \langle C_p^{(0)}, D_{p(t)}, T_{\gamma},\overline{m}_\gamma \rangle + \\ \rho_{RR} = \langle T_\gamma, \overline{m}_\gamma, S \rangle + \\ \sigma_{L} = \text{Ed25519.Sign}(c_s^{(0)}, \rho_{L}) + \\ & \xrightarrow[\rule{2.5cm}{0pt}]{\rho_{RR},\rho_L, \sigma_{L}} & + % check revealed msgs and sign coin + \\ & & \langle T'_\gamma, \overline{m}'_\gamma, S \rangle := \rho_{RR} + \\ & & \langle s_1,\dots,s_{\gamma-1},s_{\gamma+1},\dots,s_\kappa \rangle ) := S + \\ & & \textbf{check } \text{Ed25519.Verify}(C_p^{(0)}, \sigma_L, \rho_L) + \\ & & \pcfor i = 1,\dots, \gamma-1, \gamma+1,\dots, \kappa + \\ & & X_i := \text{RefreshDerive}(s_i, D_{p(t)}, C_p^{(0)}) + \\ & & \langle t_i, T_i, x_i, c_s^{(i)}, C_p^{(i)}, \overline{m}_i \rangle := X_i + \\ & & \textbf{endfor} + \\ & & h_T' = H(T_1,\dots,T_{\gamma-1},T'_{\gamma},T_{\gamma+1},\dots,T_\kappa) + \\ & & h_{\overline{m}}' = H(\overline{m}_1,\dots,\overline{m}_{\gamma-1},\overline{m}'_{\gamma},\overline{m}_{\gamma+1},\dots,\overline{m}_\kappa) + \\ & & h_C' = H(h_T', h_{\overline{m}}') + \\ & & \textbf{check } h_C = h_C' + \\ & & \overline{\sigma}_C^{(\gamma)} := \overline{m}^{d_{s(t)}} + \\ & \xleftarrow[\rule{2.5cm}{0pt}]{\overline{\sigma}_C^{(\gamma)}} & + % Check coin signature and persist coin + \\ \sigma_C^{(\gamma)} := r^{-1}\overline{\sigma}_C^{(\gamma)} + \\ \textbf{check } (\sigma_C^{(\gamma)})^{e_t} \equiv_{N_t} C_p^{(\gamma)} + \\ \text{Persist coin} \langle D_{p(t)}, c_s^{(\gamma)}, C_p^{(\gamma)}, \sigma_C^{(\gamma)} \rangle + \end{array}$ + } + \end{equation*} + \caption{Refresh protocol (reveal phase)} + \label{fig:refresh-part2} + \end{figure} + + \subsubsection{(Un)linkability} + \begin{figure}[htp] + \centering + \includegraphics[height=0.5\textwidth]{taler_refresh_link_threat.png} + \caption{Taler refresh protocol, linkability (source: \cite{pic:refresh-prot})} + \label{fig:taler-link-threat} + \end{figure} + The goal of the cut and choose protocol is to ensure with a high probability ($1/n$) that the customer honestly created the new coin. + It ensures that the old coin is linked to the new coin via the DH lock. + + With that, the following attack scenario is prevented (with probability $1/n$):\\ + An third party creates the new coin without the DH lock as described in section \ref{sec:blind-sign-schemes}. + The third party sends the blinded new coin to the customer (who possesses the old coin). + The customer then signs the new coin by the exchange and sends the blinded signature back to the third party. + The third party would then be in possession of a valid new coin, which is not linked to the old coin. + As mentioned, such an attack is detected with a high probability by the exchange with the cut and choose protocol described earlier. + + We will now consider the following attack scenario:\\ + Someone could give the private key of the old coin $c_{old}$ to another person. + This other person then can derive a new coin using the refresh protocol. + The original customer currently can not recreate the new coin with only the knowledge of the old coins private key $c_{old}$. + He would need to know the public key of the transfer key $T_x$ and also the blinded signature of the new coin $f'_{new}$. + For this reason the exchange exposes the public transfer key $T_x$ and the blinded new coin $f'_{new}$ for a given old coin $C_{old}$. + So anybody who knows the public key of the old coin could ask for the public transfer key and the blinded signature of the new coin. + Only a person in possession of the old coins private key $c_{old}$ can recreate the new coin's private key. \\ +This mechanism can not be abused for money laundering anymore, since the original customer could trick this third person and spend the coin faster. +The linking protocol is described in figure \ref{fig:refresh-link}. + +\begin{figure} + \begin{equation*} + \resizebox{1.0\textwidth}{!}{$\displaystyle + \begin{array}{ l c l } + % preliminaries + \text{Customer} & & \text{Exchange} + \\ \text{knows:} & & \text{knows:} + \\ \text{coin}_0 = \langle D_{p(0)}, c_s^{(0)}, C_p^{(0)}, \sigma_{C}^{(0)} \rangle + \\ & \xrightarrow[\rule{2.5cm}{0pt}]{C_{p(0)}} & + \\ & & L := \text{LookupLink}(C_{p(0)}) + \\ & & \textbf{Comment: } \text{LookupLink}(C_p) \mapsto \{\langle \rho_L^{(i)}, + \\ & & \sigma_L^{(i)}, \overline{\sigma}_C^{(i)} \rangle\} + \\ & \xleftarrow[\rule{2.5cm}{0pt}]{L} & + \\ \pcfor \langle \rho_{L}^{(i)}, \overline{\sigma}_L^{(i)}, \sigma_C^{(i)} \rangle \in L + \\ \langle \hat{C}_p^{(i)}, D_{p(t)}^{(i)}, T_\gamma^{(i)}, \overline{m}_\gamma^{(i)} \rangle := \rho_L^{(i)} + \\ \langle e_t^{(i)}, N_t^{(i)} \rangle := D_{p(t)}^{(i)} + \\ \textbf{check } \hat{C}_p^{(i)} \equiv C_p^{(0)} + \\ \textbf{check } \text{Ed25519.Verify}(C_p^{(0)}, \rho_{L}^{(i)}, \sigma_L^{(i)}) + \\ x_i := \text{ECDH}(c_s^{(0)}, T_{\gamma}^{(i)}) + \\ r_i := \text{SelectSeeded}(x_i,\mathbb{Z}^*_{N_t}) + \\ c_s^{(i)} := \text{HKDF}(256,x_i,"c") + \\ C_p^{(i)} := \text{Ed25519.GetPub}(c_s^{(i)}) + \\ \sigma_C^{(i)} := (r_i)^{-1} \cdot \overline{m}_\gamma^{(i)} + \\ \textbf{check } (\sigma_C^{(i)})^{e_t^{(i)}} \equiv_{N_t^{(i)}} C_p^{(i)} + \\ \text{(Re-)obtain coin} \langle D_{p(t)}^{(i)},c_s^{(i)}, C_p^{(i)}, \sigma_C^{(i)} \rangle + \end{array}$ + } + \end{equation*} + \caption{Linking protocol} + \label{fig:refresh-link} +\end{figure} + + +\subsection{Tipping Protocol} +\label{sec:tipping} +Source for this protocol was section 4.1.10 from \cite{dold:the-gnu-taler-system}.\\ +Merchants can give customers a small tip by using the withdraw loophole (described in section \ref{sec:withdraw-loophole}). +This can be for a variety of different reasons, for example for submitting a survey. +The merchant needs to create a reserve with the exchange. +The reserve keys is now used to sign blinded coins generated by the user. +\begin{enumerate} + \item The Merchant triggers the Payment required response with the Taler-Tip header set + \item The taler tip header contains information like amount, exchange to use, deadline and more. (details section 4.1.10 \cite{dold:the-gnu-taler-system}) + \item The customer creates planchets that sum up the amount and blinds the token with the denomination key of the specified exchange and sends the blinded planchets to the merchant. + \item The merchant creates withdrawal confirmations (by signing them with the reserver private key) for these planchets and responds with a list of signatures. + \item The customer then uses these signatures to create coins as in the withdrawal protocol +\end{enumerate} +The received coins are still anonymized and only spendable by the customer. + + +\subsection{Refund Protocol} +A merchant can undo a deposit on a coin by signing a refund permission. +The protocol details can be found in section 4.7.5 of \cite{dold:the-gnu-taler-system}. +Since a refund is mainly done by the merchant, to provide refunds a merchant need to support refunds. +A refund can be either fully or partially. +After a refund, the customer is able to spend the coin, but it should be refreshed first to prevent linking of transactions. +The refund deadline is specified in the contract header, after the deadline the exchange makes a wire transfer with the money to the merchants bank. +There is a refund fee, which is subtracted from the remaining coin value. +This also prevents denial of service attacks, or at least makes them economically uninteresting. +There exists automatic refunds when a payment only partially succeeds for many reasons. +Refunds are also an important business case for many merchants who want to provide a convenient experience. +A merchant can for example provide a refund when the customer is not happy with the product. +Such a refund can be made by the merchant with a signature without the customers consent. +Now should be clear what the purpose of a refund protocol is, the rest of this section will look at the refund protocol. + + +In the protocol the customer requests a refund from the merchant. +If the merchant accepts the request, it authorizes the exchange to apply the refund. +\begin{enumerate} + \item The customer asks for a refund for payment $p$ with reason $m$ + \item The merchant decides whether it accepts the refund or not according to the merchants business rules. + \item If accepted, the merchant signs the refund permission with the merchants Ed25519 key and sends it to exchange. + \item The exchange checks the signature and refunds the coin(s) and sends a signed confirmation to the merchant. + \item The merchant sends the signed confirmation from the exchange to the customer. +\end{enumerate} + +\section{Trust and PKI in Taler} +In this section Taler's \ac{PKI} is explained and how Taler handles trust. +This section is included due to the reason that we have to create Schnorr denomination keys to add the Clause Blind Schnorr Signature scheme to Taler. +Taler uses TLS, however it does not rely on TLS for authenticity or integrity. (More detailed in chapter 4.1.3 of \cite{dold:the-gnu-taler-system}) + +\subsubsection{Auditor} +In Taler the auditors serves as trust anchor, and they are identified by a single Ed25519 public key. +Similar to the list of trusted root \ac{CA} that come with web browsers and operating systems, a wallet comes with a list of trusted auditor certificates. +In the rest of this section, different parts of Taler and how they are integrated in Taler's \ac{PKI} are discussed. +The section ends with a discussion about security risks of Taler's trust model. +For details, refer to chapter 4.1.3 of \cite{dold:the-gnu-taler-system}. + +\begin{figure}[htp] + \includegraphics[height=0.5\textwidth]{taler-pki.png} + \centering + \caption{GNU Taler PKI entities (source: \cite{dold:the-gnu-taler-system})} + \label{fig:taler-pki} +\end{figure} + +\subsubsection{Exchange} +The exchange has to expose an API in order to enable customers (wallets), merchants and auditors to access keys and other information. +An exchange has a long term master key (Ed25519 key) and a base URL. +The URL and the long term \ac{MK} identifies an exchange. +The \ac{MK} is only used as an offline signing key and should be stored on an air-gapped machine. +Further, the exchange has online signing keys (Ed25519 key), which are signed by the exchanges \ac{MK}. +This \ac{MK} is on his side signed by one or possibly more auditors master key(s). +The exchange's (online) signing keys are used to sign API responses. +The denomination keys of an exchange are also signed by the exchanges offline \ac{MK} and the auditors \ac{MK}. +The bank accounts supported by the exchange for withdrawals and deposits are also signed by the exchanges offline \ac{MK}. + +API requests are made to the base URL appending the name of the endpoint (eg. <base-url>/keys) +The endpoint <base-url>/keys is used to get the exchanges signing keys and other information. +Similar to the \ac{CA} trust model, the client (customer or merchant) can validate the signature of the keys, with the list of trusted auditor certs. + +\subsubsection{Coins} +As seen in the withdrawal protocol blind signatures are done with RSA public keys (section \ref{sec:blind-rsa-sign}). +These keys are called denomination keys and they represent the coin value of the signed coins. +The following information concerning the denomination keys are signed by the exchanges master key (citation from \cite{dold:the-gnu-taler-system} chapter 4.1.3): +\begin{itemize} + \item The RSA public key + \item The start date, after which coins of this denomination can be withdrawn and deposited. + \item The withdraw expiration date, after which coins cannot be withdrawn anymore, must be after the start date. + \item The deposit expiration date, after which coins cannot be deposited anymore, must be after the withdraw expiration date. + \item The legal expiration date, after which the exchange can delete all records about operations with coins of this denominations, must be (typically quite a long time!) after the deposit expiration date. + \item The fees for a withdraw, deposit, refresh and refund operation with this coin, respectively. +\end{itemize} + +As mentioned, the denomination keys are signed by the exchanges \ac{MK} and also by the auditor. + +\subsubsection{Merchant} +The merchant has one Ed25519 public key. +With that key the merchant authenticates to the exchange and signs responses to the customer. +Depending on the jurisdiction, an exchange needs to comply to \ac{KYC} regulations. +A merchant which accepts payments from all exchanges (audited by a trusted auditor) therefore needs to fulfill \ac{KYC} registration for all accepted exchange separately. +This is needed to be legally compliant. \\ +Like the customer, also the merchant is configured with a set of trusted auditors and exchanges. +A merchant only accepts payments with coins of denominations from a trusted exchange which is audited by a trusted auditor. + +For this reason Taler separates this service into an isolated service, similar to on-premise or external payment gateways, which are used by most e-commerce shops nowadays. + +\subsubsection{Customer} +A customer has private keys of reserves that they own to authenticate with the exchange. +The public key was communicated to the exchange with the wire transfer. (A bank however is not part of Taler's \ac{PKI}.) +A customer is therefore not registered with an exchange. + +Further a customer possesses the private keys of his coins and stores them in a digital wallet. +\subsubsection{Security Discussion} +Taler's trust model is technically similar to the \ac{CA} trust model we know from TLS certificates. +The trust anchor lies with the auditors, whose certificates are pre-configured by the merchant or customer respectively. +However, trust is always somehow attackable. +That does not mean that there is a security issue in the trust model. +When the list of trusted auditor certs of a customer/merchant somehow can be manipulated, the trust model breaks for this entity. \\ +One attack scenario would be to attack customers/merchants with a supply-chain attack on the wallets or merchant backends' implementation. +With software supply-chain attacks on the rise in 2020/21 (although the concept is not new) such an attack could have a big impact. \\ +Since auditor certs are coupled with the wallet (or merchant) implementation, a bank, country, central bank or auditor will most likely publish a wallet and a merchant implementation for the corresponding Taler ecosystem. +%This would make it possible for the publisher to make changes on the Taler protocol for this specific implementation. diff --git a/doc/cs/content/4_1_design.tex b/doc/cs/content/4_1_design.tex new file mode 100644 index 000000000..b23e72050 --- /dev/null +++ b/doc/cs/content/4_1_design.tex @@ -0,0 +1,459 @@ +\chapter{Protocol Design} +\label{chap:design} +This chapter describes the necessary changes on the protocol level to implement a Blind Schnorr Signature Scheme to Taler. + + +\section{Analysis of Current Protocols} +The blind RSA signature scheme is only used for coin signatures. +Note that we omitted protocols (or parts of them) where the coin signature is transmitted, but no other actions using it is performed. +\\\\ +\label{abort-idempotency} +An important property to mention here is \textit{\gls{abort-idempotency}}. +\Gls{idempotence} in the context of computer science is a property to ensure that the state of a system will not change, no matter how many times the same request was made. +A more in-depth explanation is given within the cited source \cite{yuchen:idempotence}.\\ +\textit{\gls{abort-idempotency}} goes a bit further. +When the protocol is aborted at any stage, for example due to power cuts or network issues, the protocol still needs to ensure that the same response is sent for the same request. +This is especially challenging when dealing with random values as we will see in the redesigned protocols in the following sections. +For \gls{RSABS} it is inherently easier to provide \textit{\gls{abort-idempotency}} since signature creation only needs one round-trip and requires less random values. + +The following protocols currently use \gls{RSABS}: +\begin{itemize} + \item \textbf{Withdraw Protocol:} + The customer uses the blind signature scheme to blind the coins before transmitting them to the exchange, which blindly signs it (standard RSA signature) and the returns the signatures. + After the customer receives the signatures, he unblinds and stores them together with the coins. + \\ Components: + \begin{itemize} + \item Customer + \item Exchange + \end{itemize} + \item \textbf{Deposit Protocol:} + During the Deposit, the exchange verifies the coin signature derived using the blind RSA signature scheme. + \\ Components: + \begin{itemize} + \item Exchange + \end{itemize} + \item \textbf{Refresh Protocol:} + The refresh protocol is used to derive a new coin from an old one which was partially spent. + Parts of the protocol are similar to the withdraw protocol, but it is more complex due to the added DH lock and cut-and-choose. + \\ Components: + \begin{itemize} + \item Customer + \item Exchange + \end{itemize} + \item \textbf{Tipping:} + Tipping is a variation of the withdraw protocol where the message containing the blinded planchets is transmitted to the merchant, who signs them using his reserve private, key and returns the signatures back to the customer. + Here, the details from the withdraw protocol apply. + \\ Components: + \begin{itemize} + \item Customer + \item Exchange + \end{itemize} + \item \textbf{Recoup Protocol:} + The recoup protocol distinguishes three different cases, which either use the refresh protocol or disclose either the withdraw transcript or refresh protocol transcript to the exchange. + \\ Components: + \begin{itemize} + \item Customer + \item Exchange + \end{itemize} +\end{itemize} + + +\section{Protocol Changes} +The goal of the thesis is to add support for the Clause Blind Schnorr Signature scheme to Taler, besides the existing \gls{RSABS} implementation (see section \ref{sec:blind-rsa-sign}). +For the design of the \gls{CSBS} the existing protocols with \gls{RSABS} were redesigned. + +The goal of the blind signature is to keep the exchange from knowing which coin a user withdraws and thus preventing the exchange linking a coin to a user. +The biggest impact is on the withdrawal and refresh protocols, but all protocols that include some operation around denomination signatures are affected. + +During the thesis the protocols will be redesigned, implemented and the differences to the current version will be outlined. +These results will be delivered to the Taler team. +Feedback is very important when (re)designing protocols. +For that reason the redesigned protocols were discussed and reviewed with Christian Grothoff multiple times. + +As signature scheme the Clause Blind Schnorr Signature Scheme described in section \ref{sec:clause-blind-schnorr-sig} was chosen for multiple reasons. +First of all it is currently considered to be secure (see \cite{cryptoeprint:2019:877}). +Schnorr Signatures on \gls{25519} are much shorter than RSA signatures. +This should provide notable performance improvements in speed and storage, and therefore scales better. +The paper describes a security analysis of the Blind Schnorr Signature scheme and introduces a modification (the "clause" part in the name) that is resistant to Wagner's algorithm (which solves ROS problem). + +\Gls{25519} \cite{bern:curve25519} will be used for the implementation because it is a widely accepted curve (see \cite{bernlange:safecurves}, \cite{rfc7748}) and is already used by Taler (Taler uses Ed25519 which is built upon \gls{25519}). + + +\subsection{Withdraw Protocol} +\label{sec:withdraw-protocol-schnorr} +The modified protocol using the Clause Blind Schnorr Signature Scheme is described in figures \ref{fig:withdrawal-process-schnorr-1} and \ref{fig:withdrawal-process-schnorr-2}. + +The proposed change introduces an additional round trip. +It must be prevented that the exchange has to track sessions or persist values during the first stage \ref{fig:withdrawal-process-schnorr-1}, while still ensuring \gls{abort-idempotency}. +In order to ensure \textit{\gls{abort-idempotency}}, the exchange has to generate the same $R_0,R_1$ for the same withdrawal request, while $r_0,r_1$ still needs to be unpredictable for the customer. +For this reason a withdrawal-nonce combined with a \gls{hkdf} comes into play. +The redesigned protocol makes extensive use of \gls{hkdf}'s functionality as \ac{PRNG} and one-way function, thus random becomes \textit{unpredictable}. + +In the beginning of the protocol, the customer generates a coin key pair. +Its private key is used to generate the withdraw-nonce $n_w$ and the blinding factors $\alpha_0, \alpha_1, \beta_0, \beta_1$. +The exchange uses the withdraw nonce together with the reserve key and a long-term secret to generate $r_0, r_1$. +The coin and denomination private keys can be used as long-term secrets due to the one-way property of the \gls{hkdf}. + +Another question evolved around which key to use for the derivation of $ r_0, r_1 $. +Obvious options are the denomination key or the exchange's online signing key. +The denomination key was chosen because it has the recopu protocol in place that would handle coin recovery in case of a key compromise and subsequent revocation. + +\begin{figure}[htp] + \begin{equation*} + \resizebox{1.0\textwidth}{!}{$\displaystyle + \begin{array}{ l c l } + % preliminaries + \text{Customer} & & \text{Exchange} + \\ \text{knows:} & & \text{knows:} + \\ \text{reserve keys } w_s, W_p & & \text{reserve public key } W_p + \\ \text{denomination public key } D_p & & \text{denomination keys } d_s, D_p + \\ & & + \\\text{generate withdraw secret:} + \\ \omega := randombytes(32) + \\ \text{persist } \langle \omega, D_p \rangle + \\ n_w := \text{HKDF}(256, \omega, \text{"n"}) + \\ & \xrightarrow[\rule{2.5cm}{0pt}]{n_w, D_p} & + % generate R + \\ & & \text{verify if } D_p \text{ is valid} + \\ & & r_0 := \text{HKDF}(256,n_w || d_s, \text{"wr0"}) + \\ & & r_1 := \text{HKDF}(256,n_w || d_s, \text{"wr1"}) + \\ & & R_0 := r_0G + \\ & & R_1 := r_1G + \\ & \xleftarrow[\rule{2.5cm}{0pt}]{R_0, R_1} & + \\ \text{derive coin key pair}: + \\ c_s := \text{HKDF}(256, \omega || R_0 || R_1,\text{"cs"}) + \\ C_p := \text{Ed25519.GetPub}(c_s) + % blinding + \\ \text{blind:} & & + \\ b_s := \text{HKDF}(256, \omega || R_0 || R_1,\text{"b-seed"}) + \\ \alpha_0 := \text{HKDF}(256, b_s, \text{"a0"}) + \\ \alpha_1 := \text{HKDF}(256, b_s, \text{"a1"}) + \\ \beta_0 := \text{HKDF}(256, b_s, \text{"b0"}) + \\ \beta_1 := \text{HKDF}(256, b_s, \text{"b1"}) + \\ R'_0 := R_0 + \alpha_0 G + \beta_0 D_p & & + \\ R'_1 := R_1 + \alpha_1 G + \beta_1 D_p & & + \\ c'_0 := H(R'_0, C_p) & & + \\ c'_1 := H(R'_1, C_p) & & + \\ c_0 := c'_0 + \beta_0 \mod p & & + \\ c_1 := c'_1 + \beta_1 \mod p & & + \\ + \\ & \textit{Continued in figure \ref{fig:withdrawal-process-schnorr-2}} & + \end{array}$ + } + \end{equation*} + \caption{Withdrawal process using Clause Blind Schnorr Signatures part 1} + \label{fig:withdrawal-process-schnorr-1} +\end{figure} + +\begin{figure}[htp] + \begin{equation*} + \resizebox{1.0\textwidth}{!}{$\displaystyle + \begin{array}{ l c l } + % preliminaries + \text{Customer} & & \text{Exchange} + \\ \text{knows:} & & \text{knows:} + \\ \text{reserve keys } w_s, W_p & & \text{reserve public key } W_p + \\ \text{denomination public key } D_p & & \text{denomination keys } d_s, D_p + \\ + \\ & \textit{Continuation of figure \ref{fig:withdrawal-process-schnorr-1}} & + \\ + % sign with reserve sk + \\ \text{sign with reserve private key:} & & + \\ \rho_W := \langle n_w, D_p, c_0, c_1 \rangle & & + \\ \sigma_W := \text{Ed25519.Sign}(w_s, \rho_W) & & + \\ & \xrightarrow[\rule{2.5cm}{0pt}]{W_p, \sigma_W, \rho_W} & + \\ & & \langle n_w, D_p, c_0, c_1 \rangle := \rho_W + % checks done by the exchange + \\ & & \text{verify if } D_p \text{ is valid} + \\ & & \text{check } \text{Ed25519.Verify}(W_p, \rho_W, \sigma_W) + \\ & & b := \text{HKDF}(1,n_w || d_s, \text{"b"}) + \\ & & s \leftarrow \text{GetWithdraw}(n_w, D_p) + \\ & & \textbf{if } s = \bot + \\ & & \textbf{check !} \text{NonceReuse} (n_w, D_p, \rho_W) + \\ & & r_b := \text{HKDF}(256,n_w || d_s, \text{"r}b\text{"}) + % sign coin + \\ & & s := r_b + c_b d_s \mod p + % the following db operations are atomic + \\ & & \text{decrease balance if sufficient and} + \\ & & \text{persist NonceUse } \langle n_w, D_p, \rho_W \rangle + \\ & & \text{persist } \langle D_p, s \rangle + \\ & & \textbf{endif} + \\ & \xleftarrow[\rule{2.5cm}{0pt}]{b,s} & + % verify signature + \\ \text{verify signature:}& & + \\ \textbf{check if } sG = R_b + c_b D_p & & + % unblind signature + \\ \text{unblind:}& & + \\ s' := s + \alpha_b \mod p & & + \\ \text{verify signature:}& & + \\ \textbf{check if } s'G = R'_b + c'_b D_p & & + \\ \sigma_C := \langle R'_b, s' \rangle & & + \\ \text{resulting coin: } c_s, C_p, \sigma_C, D_p & & + \end{array}$ + } + \end{equation*} + \caption{Withdrawal process using Clause Blind Schnorr Signatures part 2} + \label{fig:withdrawal-process-schnorr-2} +\end{figure} + + +\subsection{Deposit Protocol} +The deposit protocol remains unchanged, except for the verification of the coin signature. +To verify the signature, the exchange has to check if the following equation holds: +\begin{align*} + s'G & = R' + c' D_p + \\ &= R' + H(R', C_p) D_p +\end{align*} +$ s', R' $ together form the signature, $ D_p $ is the denomination public key and $ C_p $ is the coin public key. + +Further details regarding the verification process can be found in section \ref{sec:blind-schnorr-sig}. + + +\subsection{Refresh Protocol} +The refresh protocol blindly signs the new derived coins. +The replacement of \gls{RSABS} with the Clause Blind Schnorr Signature Scheme (see \ref{sec:clause-blind-schnorr-sig}) makes the refresh protocol a bit more complex. + +\subsubsection{RefreshDerive Schnorr} +The RefreshDerive protocol is described in figure \ref{fig:refresh-derive-schnorr}. +For this protocol, the main change is that more values need to be derived somehow. +These blinding factors are also derived from $x$. +Then the challenges $\overline{c_0}$ and $\overline{c_1}$ are generated as in the Clause Blind Schnorr Signature Scheme. + +\begin{figure}[htp] + \centering + \fbox{% + \procedure[codesize=\small]{$\text{RefreshDerive}(t, D_{p(t)}, C_p, R_0, R_1)$}{% + T := \text{Curve25519.GetPub}(t) \\ + x := \textrm{ECDH-EC}(t, C_p) \\ + c'_s := \text{HKDF}(256, x, \text{"c"}) \\ + C_p' := \text{Ed25519.GetPub}(c'_s) \\ + b_s := \text{HKDF}(256, x || R_0 || R_1,\text{"b-seed"}) \\ + \alpha_0 := \text{HKDF}(256, b_s, \text{"a0"}) \\ + \alpha_1 := \text{HKDF}(256, b_s, \text{"a1"}) \\ + \beta_0 := \text{HKDF}(256, b_s, \text{"b0"}) \\ + \beta_1 := \text{HKDF}(256, b_s, \text{"b1"}) \\ + R'_0 = R_0 + \alpha_0 G + \beta_0 D_p \\ + R'_1 = R_1 + \alpha_1 G + \beta_1 D_p \\ + c'_0 = H(R'_0, C_p') \\ + c'_1 = H(R'_1, C_p') \\ + \overline{c_0} = c'_0 + \beta_0 \mod p \\ + \overline{c_1} = c'_1 + \beta_1 \mod p \\ + \pcreturn \langle T, c'_s, C_p', \overline{c_0}, \overline{c_1} \rangle + } + } + \caption[RefreshDerive algorithm]{The RefreshDerive replaced with Schnorr blind signature details. As before the uses the seed $s$ on the dirty coin for generating the new coin. + The new coin needs to be signed later on with the denomination key.} + \label{fig:refresh-derive-schnorr} +\end{figure} + +\subsubsection{Refresh Protocol} +\label{sec:refresh-protocol} +In the commit phase (see figure \ref{fig:refresh-commit-part1}) there needs to be requested an $R_0$ and $R_1$ before deriving the new coins. +There now needs to be calculated two different commit hashes, one for $\overline{c_0}$ and one for $\overline{c_1}$. +The exchange needs to additionally generate a random $b \leftarrow \{0,1\}$ to choose a $\overline{c_b}$. +The reveal phase (see figure \ref{fig:refresh-commit-part2}) now is continued only with the chosen $\overline{c_b}$. +In the reveal phase, the RSA signing and unblinding is exchanged with Schnorr's blind signature counterparts. + +\begin{figure}[htp] + \begin{equation*} + \resizebox{1.0\textwidth}{!}{$\displaystyle + \begin{array}{ l c l } + % preliminaries + \text{Customer} & & \text{Exchange} + \\ \text{knows:} & & \text{knows:} + \\ \text{denomination public key } D_p & & \text{old denomination keys } d_{s(0)} D_{p(0)} + \\ \text{coin}_0 = \langle D_{p(0)}, c_s^{(0)}, C_p^{(0)}, \sigma_c^{(0)} \rangle && \text{new denomination keys } d_s, D_P + % request r + \\ & & + \\ n_r := randombytes(32) + \\ \text{persist } \langle n_r, D_p \rangle + % sign with reserve sk + \\ & \xrightarrow[\rule{2.5cm}{0pt}]{n_r, D_p} & + % generate R + \\ & & \text{verify if } D_p \text{ is valid} + \\ & & r_0 := \text{HKDF}(256, n_r || d_s, \text{"mr0"}) + \\ & & r_1 := \text{HKDF}(256, n_r || d_s, \text{"mr1"}) + \\ & & R_0 := r_0G + \\ & & R_1 := r_1G + \\ & \xleftarrow[\rule{2cm}{0pt}]{R_0, R_1} & + % refresh request + \\ \textbf{for } i = 1, \dots, \kappa: % generate k derives + %\\ s_i \leftarrow \{0,1\}^{256} % seed generation + \\ t_i := \text{HKDF}(256, c_s^{(0)}, n_r || R_0 || R_1,\text{"t} i \text{"} ) % seed generation + \\ X_i := \text{RefreshDerive}(t_i, D_p, C_p^{(0)}, R_0, R_1) + \\ (T_i, c_s^{(i)}, C_p^{(i)}, \overline{c_0}, \overline{c_1}):= X_i + \\ \textbf{endfor} + \\ h_T := H(T_1, \dots, T_k) + \\ h_{\overline{c_0}} := H(\overline{c_{0_1}},\dots, \overline{c}_{0_k}) + \\ h_{\overline{c_1}} := H(\overline{c_{1_1}},\dots, \overline{c}_{1_k}) + \\ h_{\overline{c}} := H(h_{\overline{c_0}}, h_{\overline{c_1}}, n_r) + \\ h_C := H(h_T, h_{\overline{c}}) + \\ \rho_{RC} := \langle h_C, D_p, \text{ } D_{p(0)}, C_p^{(0)}, \sigma_C^{(0)} \rangle + \\ \sigma_{RC} := \text{Ed25519.Sign}(c_s^{(0)}, \rho_{RC}) + \\ \text{Persist refresh-request} + \\ \langle n_r, R_0, R_1, \rho_{RC}, \sigma_{RC} \rangle + \\ + \\ & \textit{Continued in figure \ref{fig:refresh-commit-part2}} & + \end{array}$ + } + \end{equation*} + \caption{Refresh protocol (commit phase part 1) using Clause Blind Schnorr Signatures} + \label{fig:refresh-commit-part1} +\end{figure} + + +\begin{figure}[htp] + \begin{equation*} + \resizebox{1.0\textwidth}{!}{$\displaystyle + \begin{array}{ l c l } + \text{Customer} & & \text{Exchange} + \\ & \textit{Continuation of} + \\ & \textit{figure \ref{fig:refresh-commit-part1}} + \\ + \\ & \xrightarrow[\rule{2cm}{0pt}]{\rho_{RC}, \sigma_{RC}, n_r} & + % Exchange checks refresh request + \\ & & \langle h_C, D_p, D_{p(0)}, C_p^{(0)}, \sigma_C^{(0)} \rangle := \rho_{RC} + \\ & & \textbf{check} \text{ Ed25519.Verify}(C_p^{(0)}, \sigma_{RC}, \rho_{RC}) + \\ + \\ & & \gamma \leftarrow \text{GetOldRefresh}(\rho_{RC}) + \\ & & \textbf{Comment: }\text{GetOldRefresh}(\rho_{RC} \mapsto + \\ & & \{\bot, \gamma \}) + \\ & & \pcif \gamma = \bot + \\ & & v := \text{Denomination}(D_p) + \\ & & \textbf{check } \text{IsOverspending}(C_p^{(0)}, D_ {p(0)}, v) + \\ & & \text{verify if } D_p \text{ is valid} + \\ & & \textbf{check !} \text{NonceReuse} (n_r, D_p, \rho_{RC}) + \\ & & \textbf{check } \text{Schnorr.Verify}(D_{p(0)}, C_p^{(0)}, \sigma_C^{(0)}) + \\ & & \text{MarkFractionalSpend}(C_p^{(0)}, v) + \\ & & \gamma \leftarrow \{1, \dots, \kappa\} + \\ & & \text{persist NonceUse } \langle n_r, D_p, \rho_{RC} \rangle + \\ & & \text{persist refresh-record } \langle \rho_{RC},\gamma \rangle + \\ & \xleftarrow[\rule{2cm}{0pt}]{\gamma} & + % Check challenge and send challenge response (reveal not selected msgs) + \\ \textbf{check } \text{IsConsistentChallenge}(\rho_{RC}, \gamma) + \\ \textbf{Comment: } \text{IsConsistentChallenge}\\(\rho_{RC}, \gamma) \mapsto \{ \bot,\top \} + \\ + \\ \text{Persist refresh-challenge} \langle \rho_{RC}, \gamma \rangle + \\ S := \langle t_1, \dots, t_{\gamma-1}, t_{\gamma+1}, \dots,t_\kappa \rangle % all seeds without the gamma seed + \\ \rho_L := \langle C_p^{(0)}, D_p, T_{\gamma}, \overline{c_0}_\gamma, \overline{c_1}_\gamma \rangle + \\ \rho_{RR} := \langle \rho_L, S \rangle + \\ \sigma_{L} := \text{Ed25519.Sign}(c_s^{(0)}, \rho_{L}) + \\ & \xrightarrow[\rule{2.5cm}{0pt}]{\rho_{RR},\rho_L, \sigma_{L}} & + \\ + \\ & \textit{Continued in} & + \\ & \textit{figure \ref{fig:refresh-reveal-part1}} & + \end{array}$ + } + \end{equation*} + \caption{Refresh protocol (commit phase part 2) using Clause Blind Schnorr Signatures} + \label{fig:refresh-commit-part2} +\end{figure} + +\begin{figure}[htp] + \begin{equation*} + \resizebox{1.0\textwidth}{!}{$\displaystyle + \begin{array}{ l c l } + % preliminaries + \text{Customer} & & \text{Exchange} + \\ & \textit{Continuation of} + \\ & \textit{figure \ref{fig:refresh-commit-part2}} + \\ + \\ & \xrightarrow[\rule{2.5cm}{0pt}]{\rho_{RR},\rho_L, \sigma_{L}} & + % check revealed msgs and sign coin + \\ & & \langle C_p^{(0)}, D_p, T_{\gamma}, \overline{c_0}_\gamma, \overline{c_1}_\gamma \rangle := \rho_L + \\ & & \langle T'_\gamma, \overline{c_0}_\gamma, \overline{c_1}_\gamma, S \rangle := \rho_{RR} + \\ & & \langle t_1,\dots,t_{\gamma-1},t_{\gamma+1},\dots,t_\kappa \rangle := S + \\ & & \textbf{check } \text{Ed25519.Verify}(C_p^{(0)}, \sigma_L, \rho_L) + \\ & & b := \text{HKDF}(1, n_r || d_{s(i)}, \text{"b"}) + \\ & & \textbf{for } i = 1,\dots, \gamma-1, \gamma+1,\dots, \kappa + \\ & & X_i := \text{RefreshDerive}(t_i, D_p, C_p^{(0)} \\ &&, R_0, R_1) + \\ & & \langle T_i, c_s^{(i)}, C_p^{(i)}, \overline{c_1}_i, \overline{c_2}_i \rangle := X_i + \\ & & \textbf{endfor} + \\ & & h_T' = H(T_1,\dots,T_{\gamma-1},T'_{\gamma},T_{\gamma+1},\dots,T_\kappa) + \\ & & h_{\overline{c_0}}' := H(\overline{c_{0_1}},\dots, \overline{c}_{0_k}) + \\ & & h_{\overline{c_1}}' := H(\overline{c_{1_1}},\dots, \overline{c}_{1_k}) + \\ & & h_{\overline{c}}' := H(h_{\overline{c_0}}, h_{\overline{c_1}}, n_r) + \\ & & h_C' = H(h_T', h_{\overline{c}}') + \\ & & \textbf{check } h_C = h_C' + \\ & & r_b := \text{HKDF}(256, n_r || d_s, \text{"mr}b\text{"}) + \\ & & \overline{s}_{C_p}^{(\gamma)} = r_b + \overline{c_{b_\gamma}} d_s \mod p + \\ & & \text{persist } \langle \rho_L, \sigma_L, S \rangle + \\ & \xleftarrow[\rule{2.5cm}{0pt}]{b, \overline{s}_C^{(\gamma)}} & + % Check coin signature and persist coin + % unblind signature + \\ \text{unblind:}& & + \\ s_C'^{(\gamma)} := \overline{s}_C^{(\gamma)} + \alpha_b \mod p & & + \\ \text{verify signature:}& & + \\ \textbf{check if } \overline{s'}_C^{(\gamma)}G \equiv R'_b + \overline{c'_0}_\gamma D_p & & + \\ \sigma_C^{(\gamma)} := \langle s_{C}'^{(\gamma)},R_b' \rangle + \\ \text{Persist coin} \langle D_p, c_s^{(\gamma)}, C_p^{(\gamma)}, \sigma_C^{(\gamma)} \rangle + \end{array}$ + } + \end{equation*} + \caption{Refresh protocol (reveal phase) using Clause Blind Schnorr Signatures} + \label{fig:refresh-reveal-part1} +\end{figure} +\newpage +\subsubsection{Linking Protocol} +\label{sec:refresh-link} +The beginning of the linking protocol (see figure \ref{fig:refresh-link}) is the same as in the current protocol. +After the customer received the answer $L$ the only difference is in obtaining the coin. +To re-obtain the derived coin, the same calculations as in \ref{fig:refresh-derive-schnorr} are made. +\begin{figure}[htp] + \begin{equation*} + \resizebox{1.0\textwidth}{!}{$\displaystyle + \begin{array}{ l c l } + % preliminaries + \text{Customer} & & \text{Exchange} + \\ \text{knows:} & & \text{knows:} + \\ \text{coin}_0 = \langle D_{p(0)}, c_s^{(0)}, C_p^{(0)}, \sigma_{C}^{(0)} \rangle + \\ & \xrightarrow[\rule{2.5cm}{0pt}]{C_{p(0)}} & + \\ & & L := \text{LookupLink}(C_{p(0)}) + \\ & & \textbf{Comment: } \text{LookupLink}(C_p^{(0)}) \mapsto + \\ & & \{\langle \rho_L^{(i)}, \sigma_L^{(i)}, \overline{\sigma}_C^{(i)}, b \rangle\} + %\\ & & \{\langle C_{p(0)}, D_{p(t)},\overline{\sigma}_C^{(i)}, b^{(i)}, R_b^{(i)}\rangle\} + \\ & \xleftarrow[\rule{2.5cm}{0pt}]{L} & + \\ \textbf{for } \langle \rho_L^{(i)}, \overline{\sigma}_L^{(i)}, \overline{\sigma}_C^{(i)}, b \rangle\ \in L + + %\\ & & \langle C_p^{(0)}, D_{p(t)}, T_{\gamma}, \overline{c_0}_\gamma, \overline{c_1}_\gamma, n_r \rangle := \rho_L + \\ \langle \hat{C}_p^{(i)}, D_p^{(i)}, T_\gamma^{(i)}, \overline{c_0}_\gamma^{(i)}, \overline{c_1}_\gamma^{(i)}, n_r \rangle := \rho_L^{(i)} + \\ \langle \overline{s}_C^{(i)}, R_b^{(i)} \rangle := \overline{\sigma}_C^{(i)} + \\ \textbf{check } \hat{C}_p^{(i)} \equiv C_p^{(0)} + \\ \textbf{check } \text{Ed25519.Verify}(C_p^{(0)}, \rho_{L}^{(i)}, \sigma_L^{(i)}) + \\ \langle \overline{s}_C^{(i)}, R_b^{(i)} \rangle := \sigma_C^{(i)} + \\ x_i := \text{ECDH}(c_s^{(0)}, T_{\gamma}^{(i)}) + \\ c_s^{(i)} := \text{HKDF}(256, x, \text{"c"}) + \\ C_p^{(i)} := \text{Ed25519.GetPub}(c_s^{(i)}) + \\ b_s^{(i)} := \text{HKDF}(256, x_i || R_0^{(i)} || R_1^{(i)},\text{"b-seed"}) + \\ \alpha_b := \text{HKDF}(256, b_s^{(i)}, \text{"a}b\text{"}) + \\ \beta_b := \text{HKDF}(256, b_s^{(i)}, \text{"b}b\text{"}) + \\ {R'}_b^{(i)} = R_b^{(i)} + \alpha_b G + \beta_b D_p^{(i)} + \\ c'_b = H(R'_b, C_p^{(i)}) + \\ c_b = c'_b + \beta_b \mod p + \\ s_C'^{(i)} := \overline{s}_C^{(i)} + \alpha_b \mod p + \\ \sigma_C^{(i)} := \langle s_C'^{(i)}, R_b' \rangle + \\ \textbf{check } s'{_C^{(i)}}G \equiv {R'}_b^{(i)} + c'_b D_p^{(i)} + \\ \text{(Re-)obtain coin} \langle D_p^{(i)},c_s^{(i)}, C_p^{(i)}, \sigma_C^{(i)} \rangle + \end{array}$ + } + \end{equation*} + \caption{Linking protocol using Clause Blind Schnorr Signatures} + \label{fig:refresh-link} +\end{figure} + + +\subsection{Tipping} +Tipping remains unchanged, except for the content of the message $ \rho_W = D_p, c_0, c_1 $ signed by the merchant using its reserve private key. + +\subsection{Recoup Protocol} +The recoup protocol distinguishes three different cases, which all depend on the state of a coin whose denomination key has been revoked. +The following listing outlines the necessary changes on the protocol, please refer to Dold's documentation section 2.2.1 \cite{dold:the-gnu-taler-system} for details regarding the different cases. +\begin{itemize} + \item \textbf{The revoked coin has never been seen by the exchange}: + \\The withdraw transcript (and verification) must be adjusted in order for the exchange to be able to retrace the blinding. + \item \textbf{The coin has been partially spent}: + \\In this case the refresh protocol will be invoked on the coin. + The necessary changes are outlined in \ref{sec:refresh-protocol}. + \item \textbf{The revoked coin has never been seen by the exchange and resulted from a refresh operation}: + \\The refresh protocol transcript and its blinding factors must be adjusted to consider the changes in the blind signature scheme. +\end{itemize} diff --git a/doc/cs/content/4_2_specification.tex b/doc/cs/content/4_2_specification.tex new file mode 100644 index 000000000..bfbe5edc7 --- /dev/null +++ b/doc/cs/content/4_2_specification.tex @@ -0,0 +1,790 @@ +\chapter{Protocol Specification} +\label{chap:spec} +The proposed Taler protocols using the Clause Blind Schnorr Signature Scheme will be implemented as an additional option besides the existing \gls{RSABS} variant of the protocol as suggested by Christian Grothoff. +A Taler Exchange operator should be able to configure whether he wants to use \gls{RSABS} or \gls{CSBS}. +\\This variant allows to choose the signature scheme globally or per denomination. +Furthermore, it allows a change of signature scheme in a non-breaking way by revoking (or letting expire) a denomination and offering new denominations with the other scheme. +\\ +The following key points are specified in this chapter: +\begin{itemize} + \item Architecture of the different components + \item Explain and specify needed changes + \item Data strucutures + \item Public \acp{API} + \item Persistence + \item Used libraries +\end{itemize} + +\section{Architecture} +Before specifying the implementation of the different protocols, a deeper understanding of the technical architecture of Talers components is needed. +this section introduces the architecture of the exchange and wallet components and explains where the needed changes need to be implemented on a high-level. + +\subsection{Exchange} +An introduction to the exchange can be found in section \ref{sec:exchange}. +An exchange operator needs to run and maintain some additional services besides Taler's exchange. +Although this is not directly relevant for the implementation, it helps to better understand the environment in which the exchange runs. +The perspective of an exchange operator can be seen in figure \ref{fig:taler:exchange-operator-architecture}. + +\begin{figure}[h!] + \begin{adjustbox}{max totalsize={.9\textwidth}{.7\textheight},center} + \begin{tikzpicture} + \tikzstyle{def} = [node distance= 5em and 6.5em, inner sep=1em, outer sep=.3em]; + \node (origin) at (0,0) {}; + \node (exchange) [def,above=of origin,draw]{Exchange}; + \node (nexus) [def, draw, below right=of exchange] {Nexus}; + \node (corebanking) [def, draw, below left=of nexus] {Core Banking}; + \node (nginx) [def, draw, above=of exchange]{Nginx}; + \node (postgres) [def, draw, below left=of exchange]{Postgres}; + \node (postgres-nexus) [def, draw, below right=of nexus]{Postgres}; + + \tikzstyle{C} = [color=black, line width=1pt] + + \draw [<-, C] (exchange) -- (nginx) node [midway, above, sloped] (TextNode) {REST API}; + \draw [<-, C] (postgres) -- (exchange) node [midway, above, sloped] (TextNode) {SQL}; + \draw [<-, C] (postgres-nexus) -- (nexus) node [midway, above, sloped] (TextNode) {SQL}; + \draw [<-, C] (nexus) -- (exchange) node [midway, above, sloped] (TextNode) {Internal REST API}; + \draw [<-, C] (corebanking) -- (nexus) node [midway, above, sloped] (TextNode) {EBICS/FinTS}; + + \end{tikzpicture} + \end{adjustbox} + \caption{Taler exchange operator architecture (source: \cite{taler-presentation})} + \label{fig:taler:exchange-operator-architecture} +\end{figure} + +The software architecture of the exchange can be seen in figure \ref{fig:taler:exchange-architecture}. +The API runs under the httpd service, where the API endpoints need to be adjusted/added to incorporate the changes of this thesis. +The httpd server has no access to the private keys of the denomination and online signing keys. +Only the corresponding security module can perform operations requiring the private key. +Further the keys are also managed by these security modules. +To support \gls{CSBS} a new security module, which performs signature operations, is added. +To persist the new data structures, the postgres helpers need to be adjusted to serialize/deserialize the new \gls{CSBS} data structures. +More details on what changes are needed in these places is discussed in the following sections. + +\begin{figure}[h!] + \begin{center} + \begin{tikzpicture} + \tikzstyle{def} = [node distance=2em and 2.5em, inner sep=1em, outer sep=.3em]; + \node (origin) at (0,0) {}; + \node [blue] (httpd) [def,above=of origin,draw]{httpd}; + \node (secmod-rsa) [def, draw, right=of httpd] {secmod-rsa}; + \node (secmod-eddsa) [def, draw, left=of httpd] {secmod-eddsa}; + \node [blue](postgres) [def, draw, below=of httpd]{Postgres}; + \node [mGreen] (secmod-cs) [def, draw, left=of postgres]{secmod-cs}; + \node (aggregator) [def, draw, right=of postgres]{aggregator}; + \node (transfer) [def, draw, below left=of postgres]{transfer}; + \node (wirewatch) [def, draw, below right=of postgres]{wirewatch}; + \node (nexus) [def, draw, below=of postgres]{Nexus}; + + \tikzstyle{C} = [color=black, line width=1pt] + + \draw [<->, C] (httpd) -- (postgres) node [midway, above, sloped] (TextNode) {}; + \draw [<->, C] (httpd) -- (secmod-rsa) node [midway, above, sloped] (TextNode) {}; + \draw [<->, C] (httpd) -- (secmod-eddsa) node [midway, above, sloped] (TextNode) {}; + \draw [<->, C] (httpd) -- (secmod-cs) node [midway, above, sloped] (TextNode) {}; + \draw [<->, C] (aggregator) -- (postgres) node [midway, above, sloped] (TextNode) {}; + \draw [<->, C] (wirewatch) -- (postgres) node [midway, above, sloped] (TextNode) {}; + \draw [<->, C] (transfer) -- (postgres) node [midway, above, sloped] (TextNode) {}; + \draw [->, C] (transfer) -- (nexus) node [midway, above, sloped] (TextNode) {}; + \draw [<-, C] (wirewatch) -- (nexus) node [midway, above, sloped] (TextNode) {}; + \end{tikzpicture} + \end{center} + \caption{Taler exchange architecture (source: \cite{taler-presentation})} + \label{fig:taler:exchange-architecture} +\end{figure} + +\subsection{Wallet} +The architecture of the wallet implementation (as seen in figure \ref{fig:taler:wallet-architecture}) is quite straightforward. +To add support for \gls{CSBS} in the wallet, the cryptographic routines need to be reimplemented in Typescript. +Taler uses tweetnacl \cite{bern:tweetnacl} which provides functionality for the group operations. +There are existing \gls{hkdf} and \gls{fdh} implementations, that can be reused.\\ +Furthermore, the Taler protocols need to be adjusted to support \gls{CSBS} in the wallet-core. + +\begin{figure}[h!] + \begin{center} + \begin{tikzpicture} + \tikzstyle{def} = [node distance= 5em and 4.5em, inner sep=1em, outer sep=.3em]; + \node (origin) at (0,0) {}; + \node (gui) [def,above=of origin,draw]{wallet-gui}; + \node [blue](core) [def,below=of gui,draw]{wallet-core}; + \node (sync) [def, draw, below left=of core] {Sync}; + \node (taler) [def, draw, below right=of core] {Taler}; + \node (anastasis) [def, draw, below=of core] {Anastasis}; + + \tikzstyle{C} = [color=black, line width=1pt] + \draw [<->, C] (gui) -- (core) node [midway, above, sloped] (TextNode) {}; + \draw [<->, C] (core) -- (sync) node [midway, above, sloped] (TextNode) {Backup}; + \draw [<->, C] (core) -- (taler) node [midway, above, sloped] (TextNode) {Payment}; + \draw [<->, C] (core) -- (anastasis) node [midway, above, sloped] (TextNode) {Key Escrow}; + \end{tikzpicture} + \end{center} + \caption{Taler wallet architecture (source: \cite{taler-presentation})} + \label{fig:taler:wallet-architecture} +\end{figure} + +\section{Persistence} +The Clause Blind Schnorr Signature scheme is quite different to \gls{RSABS}. +Despite the differences, the database model does not need to be changed. +The only change needed an additional type field, specifying whether RSA or CS is used as signature algorithm. +To persist the new structs introduced with the support for \gls{CSBS}, only the postgres helpers need to support serialization and deserialization of the new structs. + +\section{Testing} +We will partially use test-driven development, meaning that we will write tests (at least for the known good case) before implementing functions, and extend them during and after development. +This allows us to check the functionality (code section, function(s)) during development, while being able to extend testing whenever we identify new test cases during development. + +Test cases can be used to verify different aspects of a functionality. +These are the ones we will focus on. +\begin{itemize} + \item \textbf{Known good}: + Known good cases test whether a functionality works as expected. + They are the most useful during development, because they indicate whether the code is working as expected. + \item \textbf{Known Bad}: + Known bad cases test whether functionality that is known not to work behaves as expected. + \item \textbf{Determinism}: + This case type checks whether the same input leads to the same output. + It is important for code that must work deterministic (same output), non-deterministic (e.g. random output) or based on a state that impacts the functionality. + \item \textbf{Performance testing}: + Performance testing is used to gather timing information that can be used to identify functionality with long duration, or to compare performance between different implementations or major changes. + We will restrict performance testing to the comparison of the Blind RSA Signature Scheme and the Clause Blind Schnorr Signature Scheme. +\end{itemize} + + +\section{Signature Scheme Operations in GNUnet} +\label{sec:specification-signature-scheme} + +The signature scheme operations implemented are needed in all other parts of the implementation. +Taler's cryptographic primitives (e.g. \gls{RSABS}, \gls{hkdf}, hash functions) are mostly implemented in GNUnet utils, therefore the Clause Blind Schnorr Signature routines will be implemented in GNUnet too. +It is important to provide a clear API for the cryptographic routines and to test them thoroughly. +Libsodium will be used for finite field arithmetic (\cite{libsodium:finite-field-arithmetic}) and for other functionality when available (e.g. for key generation). +Thus, a widely used and well tested cryptographic library is used for group operations. + +For \acl{FDH} and \gls{hkdf} existing implementations provided by GNUnet are used. +The \gls{hkdf} is used with SHA-512 for the extraction phase and SHA-256 for the expansion phase. + +\subsection{Data Structures} +Libsodium represents Ed25519 points and scalars as 32-byte char arrays. +To provide a more user-friendly \ac{API}, structs were created to represent each type. +For example \texttt{struct GNUNET\_CRYPTO\_CsPrivateKey} or \texttt{struct GNUNET\_CRYPTO\_RSecret} +The main reason is to increase readability and to prevent misusage of the \ac{API}. +Unlike RSA, our \gls{CSBS} on Ed25519 data structures have a fixed sizes. +The different data structures can be found in table \ref{tab:datastruct-crypto}. + +\begin{table}[ht] + \centering + \resizebox{0.95\textwidth}{!}{\begin{minipage}{\textwidth} + \colorlet{BFH-table}{BFH-MediumBlue!10} + \colorlet{BFH-tablehead}{BFH-MediumBlue!50} + \setupBfhTabular + \begin{tabular}{lll} + \rowcolor{BFH-tablehead} + \textbf{Values} & \textbf{Data Structure} & \textbf{Data Type} \\\hline + Curve25519 Scalar & {\small GNUNET\_CRYPTO\_Cs25519Scalar} & 32 byte char array\\\hline + Curve25519 Point & {\small GNUNET\_CRYPTO\_Cs25519Point} & 32 byte char array\\\hline + Private Key & {\small GNUNET\_CRYPTO\_CsPrivateKey} & {\small GNUNET\_CRYPTO\_Cs25519Scalar}\\\hline + Public Key & {\small GNUNET\_CRYPTO\_CsPublicKey} & {\small GNUNET\_CRYPTO\_Cs25519Point}\\\hline + $\alpha, \beta$ & {\small GNUNET\_CRYPTO\_CsBlindingSecret} & {\footnotesize 2x GNUNET\_CRYPTO\_Cs25519Scalar}\\\hline + $r$ & {\small GNUNET\_CRYPTO\_CsRSecret} & {\small GNUNET\_CRYPTO\_Cs25519Scalar}\\\hline + $R$ & {\small GNUNET\_CRYPTO\_CsRPublic} & {\small GNUNET\_CRYPTO\_Cs25519Point}\\\hline + $c$ & {\small GNUNET\_CRYPTO\_CsC} & {\small GNUNET\_CRYPTO\_Cs25519Scalar}\\\hline + $s$ & {\small GNUNET\_CRYPTO\_CsBlindS} & {\small GNUNET\_CRYPTO\_Cs25519Scalar}\\\hline + $s'$ & {\small GNUNET\_CRYPTO\_CsS} & {\small GNUNET\_CRYPTO\_Cs25519Scalar}\\\hline + $\sigma := \langle s',R' \rangle$ & {\small GNUNET\_CRYPTO\_CsSignature} & {\small GNUNET\_CRYPTO\_Cs25519Scalar}\\ + & & {\small GNUNET\_CRYPTO\_Cs25519Point}\\\hline + Nonce & {\small GNUNET\_CRYPTO\_CsNonce} & 32 byte char array\\\hline + \end{tabular} + \caption{Data structures for cryptographic routines} + \label{tab:datastruct-crypto} +\end{minipage}} +\end{table} + + + +\subsection{Library API} +The public \ac{API} and related data structures are specified in the C header file \url{src/include/gnunet_crypto_lib.h} in the GNUnet repository \cite{gnunet-git}. +It was developed in multiple iterations based on feedback from Christian Grothoff. +The complete C header \ac{API} can be found in the repository. +This section provides an overview of the implemented crypto API. + +Some design decisions need to be explained further: +\begin{itemize} + \item In order to prevent misusage of our implementation and increase readability, the functions that represent different stages in the signature scheme takes different data types as in- and output. + Internally most variables are either scalars or curve points (except for nonces, secrets and messages). + \item Operations that are performed twice in the Clause Blind Schnorr Signature Scheme (e.g. derivation of $ r $) do not have to be called twice. + Instead, the API returns an array of two instead of a single value.\\ + For these functions, we also optimized the \gls{hkdf} (as proposed by Christian Grothoff). + Instead of calling \gls{hkdf} twice (with different salts, e.g. "r0" and "r1"), we call it one time (e.g. with salt "r") and double the output length. + \item The cryptographic hash function used to derive $ c' $ (hash of $ R' $ and message) must map the results into the main subgroup for scalars, meaning that it has to be a \gls{fdh} (see \ref{sec:rsa-fdh}). +\end{itemize} + +The following API examples should provide an overview on how the API works and how to use it. + +First of all the API must provide functionality to create a \gls{25519} keypair as in listing \ref{lst:crypto-keypair-api} + +\begin{lstlisting}[style=bfh-c,language=C, caption={GNUnet create keypair API}, label={lst:crypto-keypair-api}] +/** + * Create a new random private key. + * + * @param[out] priv where to write the fresh private key + */ +void +GNUNET_CRYPTO_cs_private_key_generate ( + struct GNUNET_CRYPTO_CsPrivateKey *priv); + + +/** + * Extract the public key of the given private key. + * + * @param priv the private key + * @param[out] pub where to write the public key + */ +void +GNUNET_CRYPTO_cs_private_key_get_public ( + const struct GNUNET_CRYPTO_CsPrivateKey *priv, + struct GNUNET_CRYPTO_CsPublicKey *pub); +\end{lstlisting} + +The signer needs an API to generate his secret $r$ and calculate his public point $R$. +As specified in the redesign of the protocols, the r must not be chosen randomly because we need to provide \textit{\gls{abort-idempotency}}. However, the secret $r$ still needs to be \textit{unpredictable} and look random to the client. +The r\_derive API derives such a secret $r$ from a nonce and a long-term secret with \gls{hkdf}. +Further, the API ensures that a caller must generate two secret $r$ as in the Clause Blind Schnorr Signature scheme. This should discourage people from using the unsecure Blind Schnorr Signature scheme. See \ref{lst:crypto-rderive-api}. + + +\begin{lstlisting}[style=bfh-c,language=C, caption={GNUnet r derive API}, label={lst:crypto-rderive-api}] + /** + * Derive a new secret r pair r0 and r1. + * In original papers r is generated randomly + * To provide abort-idempotency, r needs to be derived but still needs to be UNPREDICTABLE + * To ensure unpredictability a new nonce should be used when a new r needs to be derived. + * Uses HKDF internally. + * Comment: Can be done in one HKDF shot and split output. + * + * @param nonce is a random nonce + * @param lts is a long-term-secret in form of a private key + * @param[out] r array containing derived secrets r0 and r1 + */ + void + GNUNET_CRYPTO_cs_r_derive (const struct GNUNET_CRYPTO_CsNonce *nonce, + const struct GNUNET_CRYPTO_CsPrivateKey *lts, + struct GNUNET_CRYPTO_CsRSecret r[2]); + + +/** + * Extract the public R of the given secret r. + * + * @param r_priv the private key + * @param[out] r_pub where to write the public key + */ + void + GNUNET_CRYPTO_cs_r_get_public (const struct GNUNET_CRYPTO_CsRSecret *r_priv, + struct GNUNET_CRYPTO_CsRPublic *r_pub); +\end{lstlisting} + + +Same as the r\_derive, the blinding secrets are also derived and not generated randomly. +The blinding secrets are generated by a client who provides a secret as seed to derive the secrets from as in listing \ref{lst:crypto-blinding-secrets-api}. + +\begin{lstlisting}[style=bfh-c,language=C, caption={GNUnet blinding secrets derive API}, label={lst:crypto-blinding-secrets-api}] +/** + * Derives new random blinding factors. + * In original papers blinding factors are generated randomly + * To provide abort-idempotency, blinding factors need to be derived but still need to be UNPREDICTABLE + * To ensure unpredictability a new nonce has to be used. + * Uses HKDF internally + * + * @param secret is secret to derive blinding factors + * @param secret_len secret length + * @param[out] bs array containing the two derivedGNUNET_CRYPTO_CsBlindingSecret + */ +void +GNUNET_CRYPTO_cs_blinding_secrets_derive ( + const struct GNUNET_CRYPTO_CsNonce *blind_seed, + struct GNUNET_CRYPTO_CsBlindingSecret bs[2]); +\end{lstlisting} + +Further the Clause Blind Schnorr API provides an API to calculate the two blinded c of the message with the two public $R$, the blinding factors and the public key as in listing \ref{lst:crypto-calc-c-api}. + +\begin{lstlisting}[style=bfh-c,language=C, caption={GNUnet calculate blinded c API}, label={lst:crypto-calc-c-api}] +/** + * Calculate two blinded c's + * Comment: One would be insecure due to Wagner's algorithm solving ROS + * + * @param bs array of the two blinding factor structs each containing alpha and beta + * @param r_pub array of the two signer's nonce R + * @param pub the public key of the signer + * @param msg the message to blind in preparation for signing + * @param msg_len length of message msg + * @param[out] blinded_c array of the two blinded c's + */ +void +GNUNET_CRYPTO_cs_calc_blinded_c ( + const struct GNUNET_CRYPTO_CsBlindingSecret bs[2], + const struct GNUNET_CRYPTO_CsRPublic r_pub[2], + const struct GNUNET_CRYPTO_CsPublicKey *pub, + const void *msg, + size_t msg_len, + struct GNUNET_CRYPTO_CsC blinded_c[2]); +\end{lstlisting} + +The sign function in our API is called sign\_derive, since we derive $b \in \{0,1\}$ from the long-term secret and then calculate the signature scalar of $c_b$. +See listing \ref{lst:crypto-sign-api}. + +\begin{lstlisting}[style=bfh-c,language=C, caption={GNUnet sign API}, label={lst:crypto-sign-api}] +/** + * Sign a blinded c + * This function derives b from a nonce and a longterm secret + * In original papers b is generated randomly + * To provide abort-idempotency, b needs to be derived but still need to be UNPREDICTABLE. + * To ensure unpredictability a new nonce has to be used for every signature + * HKDF is used internally for derivation + * r0 and r1 can be derived prior by using GNUNET_CRYPTO_cs_r_derive + * + * @param priv private key to use for the signing and as LTS in HKDF + * @param r array of the two secret nonce from the signer + * @param c array of the two blinded c to sign c_b + * @param nonce is a random nonce + * @param[out] blinded_signature_scalar where to write the signature + * @return 0 or 1 for b (see Clause Blind Signature Scheme) + */ +int +GNUNET_CRYPTO_cs_sign_derive( + const struct GNUNET_CRYPTO_CsPrivateKey *priv, + const struct GNUNET_CRYPTO_CsRSecret r[2], + const struct GNUNET_CRYPTO_CsC c[2], + const struct GNUNET_CRYPTO_CsNonce *nonce, + struct GNUNET_CRYPTO_CsBlindS *blinded_signature_scalar); +\end{lstlisting} + +The API for the unblind operation can be called with the blinding secrets and the signature scalar received from the signer as in listing \ref{lst:crypto-unblind-api}. + +\begin{lstlisting}[style=bfh-c,language=C, caption={GNUnet unblind API}, label={lst:crypto-unblind-api}] + /** + * Unblind a blind-signed signature using a c that was blinded + * + * @param blinded_signature_scalar the signature made on the blinded c + * @param bs the blinding factors used in the blinding + * @param[out] signature_scalar where to write the unblinded signature + */ +void +GNUNET_CRYPTO_cs_unblind ( + const struct GNUNET_CRYPTO_CsBlindS *blinded_signature_scalar, + const struct GNUNET_CRYPTO_CsBlindingSecret *bs, + struct GNUNET_CRYPTO_CsS *signature_scalar); +\end{lstlisting} + +The verify API takes the message and its signature with the public key and returns GNUNET\_OK for a valid signature and GNUNET\_SYSERR otherwise. +See listing \ref{lst:crypto-verify-api}. + +\begin{lstlisting}[style=bfh-c,language=C,, caption={GNUnet verify API}, label={lst:crypto-verify-api}] + /** + * Verify whether the given message corresponds to the given signature and the + * signature is valid with respect to the given public key. + * + * @param sig signature that is being validated + * @param pub public key of the signer + * @param msg is the message that should be signed by @a sig (message is used to calculate c) + * @param msg_len is the message length + * @returns #GNUNET_YES on success, #GNUNET_SYSERR if signature invalid + */ + enum GNUNET_GenericReturnValue + GNUNET_CRYPTO_cs_verify (const struct GNUNET_CRYPTO_CsSignature *sig, + const struct GNUNET_CRYPTO_CsPublicKey *pub, + const void *msg, + size_t msg_len); +\end{lstlisting} + +\subsection{Testing} +For digital signature schemes, the most important test case is the \textit{known good} case where a signature is created and successfully validated. +This test case already tests very much in a digital signature scheme. +When the signature creation or verification has a bug, a test will not succeed, because the mathematic operations need to be correct to be validated correctly. + +The cryptographic operations are further tested for deterministicy (where it applies), meaning that multiple function calls with the same input must lead to the same output. + +Since libsodium is used for the finite field arithmetic operations and is a well tested library, many cryptographic tests are already done in libsodium. + +The performance is measured in a benchmark to see how performant \gls{CSBS} are in comparison to the RSA Blind Signature Scheme. + +\section{Taler Cryptographic Utilities} +Taler provides utility functions to support cryptographic operations.\\ +This chapter provides an overview of these utility functions and about the functionality they provide. + +\subsection{Planchet Creation} +In crypto.c many utility functions are provided to create planchets (for planchet details see \ref{fig:coin:states}), blinding secrets and much more. +One difference between \gls{RSABS} and \gls{CSBS} is, that the coin private key and RSA blinding secret can be created at the same point in time, since the RSA blinding secret is created randomly. +However, for Clause Blind Schnorr secrets an additional step is needed, the public $R_0$ and $R_1$ are required to calculate the blinding seed to derive the secrets. + +A planchet in the Clause Blind Schnorr Signature Scheme can be created as followed (implementation details omitted). + +\begin{enumerate} + \item Create planchet with new \ac{EdDSA} private key + \item Derive withdraw nonce + \item Request public $R_0, R_1$ from signer + \item Derive blinding seed + \item Prepare (blind) the planchet +\end{enumerate} + +After the planchet is created, it is sent to the exchange to be signed. + +\subsection{Taler CS Security Module} +The exchange segregates access to the private keys with separate security module processes. +The security module has sole access to the private keys of the online signing keys and thus, only a security module can create signatures. +The different \textit{taler-exchange-secmod} processes (separated by signature scheme) are managing the exchanges online signing keys. The RSA denomination keys for example are managed with \textit{taler-exchange-secmod-rsa}. + +Now a new \textit{taler-exchange-secmod-cs} needs to be created for managing the \gls{CSBS} denomination keys. +These security modules run on the same machine as the httpd process and they use UNIX Domain Sockets as method for \acl{IPC}. +A short introduction about UNIX Domain Sockets can be found in the blog post \cite{matt:unix-domain-sockets}. +Furthermore, the security modules are used to protect the online signing keys by performing the actual signing operations in the dedicated taler-secmod-cs process. +This abstraction makes it harder for an attacker who has already compromised the http daemon to gain access to the private keys. +However, such an attacker would still be able to sign arbitrary messages (see \cite{taler-documentation:exchange-operator-manual}). +A crypto helper exists for each security module, these functions can be called inside the exchange for operations requiring the private online signing keys. +The new Clause Schnorr security module and corresponding crypto helper provides the following functionality: +\begin{itemize} + \item Private Key Management and creation + \item Request public $R_0, R_1$ + \item Request a signature of a $c_0,c_1$ pair + \item Revoke an online signing key +\end{itemize} + +\subsection{Testing} +All of the operations have tests and are included in unit tests. +As a template for testing, the existing RSA tests were used and adjusted for \gls{CSBS}. + + +\section{Denomination Key Management} +Since we introduce a type of denomination keys, related operations like connection to the \gls{CSBS} security module, making the denominations available for customers, persisting them in the database and offline signing using the exchange's offline signature key have to be extended to incorporate the \acl{CS}. + +The exchange offline signer requests the future, not yet signed keys by calling GET \url{/management/keys} as described in table \ref{tab:management-keys-get}. \\\\ +\framebox[1.1\width]{\color{blue}\texttt{GET /management/keys}} +\begin{table}[ht] + \centering + \resizebox{0.9\textwidth}{!}{\begin{minipage}{\textwidth} + \colorlet{BFH-table}{BFH-MediumBlue!10} + \colorlet{BFH-tablehead}{BFH-MediumBlue!50} + \setupBfhTabular + \begin{tabular}{ll} + \rowcolor{BFH-tablehead} + \textbf{Field} & \textbf{Value} \\ + future\_denoms & Information about denomination keys \\ + future\_signkeys & Information about exchange online signing keys \\ + master\_pub & Exchange's master public key \\ + denom\_secmod\_public\_key & RSA security module public key \\ + denom\_secmod\_cs\_public\_key & \gls{CSBS} security module public key \\ + signkey\_secmod\_public\_key & Online signing security module public key \\ + \end{tabular} + \caption{GET \url{/management/keys} response data} + \label{tab:management-keys-get} +\end{minipage}} +\end{table} + +It then signs the keys and returns them using POST on the same \ac{URL} with the data described in table \ref{tab:management-keys-post}. \\\\ +\framebox[1.1\width]{\color{blue}\texttt{POST /management/keys}} +\begin{table}[ht] + \centering + \colorlet{BFH-table}{BFH-MediumBlue!10} + \colorlet{BFH-tablehead}{BFH-MediumBlue!50} + \setupBfhTabular + \begin{tabular}{ll} + \rowcolor{BFH-tablehead} + \textbf{Field} & \textbf{Value} \\ + denom\_sigs & Denomination key signatures \\ + signkey\_sigs & Online signing key signatures \\ + \end{tabular} + \caption{POST \url{/management/keys} response data} + \label{tab:management-keys-post} +\end{table} + +Wallets can then call GET \url{/keys} to obtain the current denominations and other information, the response is described in table \ref{tab:keys-get}. \\\\ +\framebox[1.1\width]{\color{blue}\texttt{GET /keys}} +\begin{table}[ht] + \centering + \colorlet{BFH-table}{BFH-MediumBlue!10} + \colorlet{BFH-tablehead}{BFH-MediumBlue!50} + \setupBfhTabular + \begin{tabular}{ll} + \rowcolor{BFH-tablehead} + \textbf{Field} & \textbf{Value} \\ + version & Exchange's protocol version \\ + currency & Currency \\ + master\_public\_key & Exchange's master public key \\ + reserve\_closing\_delay & Delay before reserves are closed \\ + signkeys & Exchange's online signing public keys \\ + recoup & Revoked keys \\ + denoms & List of denominations \\ + auditors & Auditors for this exchange \\ + list\_issue\_date & Timestamp \\ + eddsa\_pub & Exchange's online signing public key \\ + eddsa\_sig & Signature (use "eddsa\_pub" for verification) \\ + \end{tabular} + \caption{GET \url{/keys} response data} + \label{tab:keys-get} +\end{table} + + +\section{New Endpoint for $R$} +The withdraw and refresh protocols using the Claude Blind Schnorr Signature Scheme introduce an additional round trip. +In this round trip, the customer requests two $ R $ from the exchange. +The exchange uses a secret $ r $ to calculate $ R := rG $. +\\ +In contrast to the plain Clause Blind Schnorr Signature Scheme (see \ref{sec:clause-blind-schnorr-sig}), $ r $ isn't generated randomly but instead derived using a \gls{hkdf} with a nonce from the customer and a denomination private key (secret only known by the exchange). +This still ensures that the private $ r $ can't be anticipated, but has multiple advantages regarding \gls{abort-idempotency}. +\Gls{abort-idempotency} means that a withdraw or refresh operation can be aborted in any step and later tried again (using the same values) without yielding a different result. +The challenge for $ r, R $ regarding \gls{abort-idempotency} is to ensure that the same $ r $ is used during the complete signature creation process. + +The only drawback of this process is that we have to ensure that the same nonce and secret aren't used for different withdraw- or refresh-operations. +This is done during signature creation and will be described in the withdraw protocol section \ref{sec:specification-withdraw}. + + +\subsection{Public APIs and Data Structures} +This is a new functionality, meaning a new endpoint accessible to customers has to be introduced. +It will be made available in the exchange HTTP server under \framebox[1.1\width]{\color{blue}\texttt{POST /csr}} and will take the input parameters described in table \ref{tab:csr-request-data} (as \ac{JSON}). +\begin{table}[ht] + \centering + \resizebox{0.9\textwidth}{!}{\begin{minipage}{\textwidth} + \colorlet{BFH-table}{BFH-MediumBlue!10} + \colorlet{BFH-tablehead}{BFH-MediumBlue!50} + \setupBfhTabular + \begin{tabular}{lll} + \rowcolor{BFH-tablehead} + \textbf{Field} & \textbf{Type} & \textbf{Value} \\ + nonce & String & 32 Bytes encoded in Crockford base32 Hex \\ + denom\_pub\_hash & String & Denomination Public Key encoded in Crockford base32 Hex \\ + \end{tabular} + \caption{POST \url{/csr} request data} + \label{tab:csr-request-data} +\end{minipage}} +\end{table} + +The exchange will then check the denomination and return one of these HTTP status codes: +\begin{itemize} + \item \textbf{200 (HTTP\_OK)}: Request Successful + \item \textbf{400 (BAD\_REQUEST)}: Invalid input parameters + \item \textbf{404 (NOT\_FOUND)}: Denomination unknown or not Clause Schnorr + \item \textbf{410 (GONE)}: Denomination revoked/expired + \item \textbf{412 (PRECONDITION\_FAILED)}: Denomination not yet valid +\end{itemize} + +When the request was successful, the exchange returns the data described in table \ref{tab:csr-response-data} (as \ac{JSON}). +\begin{table}[ht] + \centering + \colorlet{BFH-table}{BFH-MediumBlue!10} + \colorlet{BFH-tablehead}{BFH-MediumBlue!50} + \setupBfhTabular + \begin{tabular}{lll} + \rowcolor{BFH-tablehead} + \textbf{Field} & \textbf{Type} & \textbf{Value} \\ + r\_pub\_0 & String & 32 Bytes encoded in Crockford base32 Hex \\ + r\_pub\_1 & String & 32 Bytes encoded in Crockford base32 Hex \\ + \end{tabular} + \caption{POST \url{/csr} response data} + \label{tab:csr-response-data} +\end{table} + + +\subsection{Persistence} +This API does not persist anything. +This is because the resulting $R_0, R_1$ are derived and can be derived in a later step. + + +\section{Withdraw Protocol} +\label{sec:specification-withdraw} +The withdraw protocol has been introduced in section \ref{sec:withdrawal}. +For the \acl{CS} necessary adjustments are described in section \ref{sec:withdraw-protocol-schnorr}. + + +\subsection{Public APIs and Data Structures} +\label{sec:specification-withdraw-public-api} +The existing endpoint is available under \texttt{POST /reserves/[reserve]/withdraw} where "reserve" is the reserve public key encoded as Crockford base32. +It takes the following input parameters described in table \ref{tab:withdraw-request-data} as JSON.\\\\ +\framebox[1.1\width]{\color{blue}\texttt{POST /reserves/[reserve]/withdraw}} +\begin{table}[ht] + \centering + \colorlet{BFH-table}{BFH-MediumBlue!10} + \colorlet{BFH-tablehead}{BFH-MediumBlue!50} + \setupBfhTabular + \begin{tabular}{ll} + \rowcolor{BFH-tablehead} + \textbf{Field} & \textbf{Value} \\ + denom\_pub\_hash & Denomination Public Key \\ + coin\_ev & RSA blinded coin public key \\ + reserve\_sig & Signature over the request using the reserve's private key \\ + \end{tabular} + \caption{Withdraw request data} + \label{tab:withdraw-request-data} +\end{table} + +In order to facilitate parsing, Christian Grothoff suggested to include the cipher type in the "coin\_ev" field, thus creating a nested \ac{JSON} (as described in table \ref{tab:withdraw-coin-ev-rsa}). +\begin{table}[ht] + \centering + \colorlet{BFH-table}{BFH-MediumBlue!10} + \colorlet{BFH-tablehead}{BFH-MediumBlue!50} + \setupBfhTabular + \begin{tabular}{lll} + \rowcolor{BFH-tablehead} + \textbf{Field} & \textbf{Type} & \textbf{Value} \\ + cipher & Integer & Denomination cipher: 1 stands for RSA \\ + rsa\_blinded\_planchet & String & RSA blinded coin public key \\ + \end{tabular} + \caption{Withdraw "coin\_ev" field (RSA)} + \label{tab:withdraw-coin-ev-rsa} +\end{table} + +For the Clause Schnorr implementation, the field "rsa\_blinded\_planchet" will be replaced with the necessary values as described in table \ref{tab:withdraw-coin-ev-cs}. +\begin{table}[ht] + \centering + \resizebox{0.85\textwidth}{!}{\begin{minipage}{\textwidth} + \colorlet{BFH-table}{BFH-MediumBlue!10} + \colorlet{BFH-tablehead}{BFH-MediumBlue!50} + \setupBfhTabular + \begin{tabular}{lll} + \rowcolor{BFH-tablehead} + \textbf{Field} & \textbf{Type} & \textbf{Value} \\ + cipher & Integer & Denomination cipher: 2 stands for \gls{CSBS} \\ + cs\_nonce & String & 32 Bytes encoded in Crockford base32 Hex \\ + cs\_blinded\_c0 & String & 32 Bytes encoded in Crockford base32 Hex \\ + cs\_blinded\_c1 & String & 32 Bytes encoded in Crockford base32 Hex \\ + \end{tabular} + \caption{Withdraw "coin\_ev" field (\gls{CSBS})} + \label{tab:withdraw-coin-ev-cs} +\end{minipage}} +\end{table} + +The exchange will then process the withdraw request and return one of these HTTP status codes: +\begin{itemize} + \item \textbf{200 (HTTP\_OK)}: Request Successful + \item \textbf{400 (BAD\_REQUEST)}: Invalid input parameters (can also happen if denomination cipher doesn't match with cipher in "coin\_ev") + \item \textbf{403 (FORBIDDEN)}: Signature contained in "reserve\_sig" invalid + \item \textbf{404 (NOT\_FOUND)}: Denomination unknown + \item \textbf{410 (GONE)}: Denomination revoked/expired + \item \textbf{412 (PRECONDITION\_FAILED)}: Denomination not yet valid +\end{itemize} + +When the request was successful, the exchange returns the RSA signature as JSON (described in table \ref{tab:withdraw-response-rsa}). +\begin{table}[ht] + \centering + \colorlet{BFH-table}{BFH-MediumBlue!10} + \colorlet{BFH-tablehead}{BFH-MediumBlue!50} + \setupBfhTabular + \begin{tabular}{lll} + \rowcolor{BFH-tablehead} + \textbf{Field} & \textbf{Type} & \textbf{Value} \\ + cipher & Integer & Denomination cipher: 1 stands for RSA \\ + blinded\_rsa\_signature & String & RSA signature \\ + \end{tabular} + \caption{Withdraw response (RSA)} + \label{tab:withdraw-response-rsa} +\end{table} + +Table \ref{tab:withdraw-response-cs} describes the response for \gls{CSBS}. +\begin{table}[ht] + \centering + \resizebox{0.85\textwidth}{!}{\begin{minipage}{\textwidth} + \colorlet{BFH-table}{BFH-MediumBlue!10} + \colorlet{BFH-tablehead}{BFH-MediumBlue!50} + \setupBfhTabular + \begin{tabular}{lll} + \rowcolor{BFH-tablehead} + \textbf{Field} & \textbf{Type} & \textbf{Value} \\ + cipher & Integer & Denomination cipher: 2 stands for \gls{CSBS} \\ + b & Integer & \gls{CSBS} signature session identifier (either 0 or 1) \\ + s & String & signature scalar (32 Bytes encoded in Crockford base32 Hex) \\ + \end{tabular} + \caption{Withdraw response (\gls{CSBS})} + \label{tab:withdraw-response-cs} +\end{minipage}} +\end{table} + + +\subsection{Persistence} +Persistence for withdrawing is implemented in the function \texttt{postgres\_do\_withdraw} in \texttt{src/exchangedb/plugin\_exchangedb\_postgres.c} +For \gls{CSBS}, persisting the blinded signature must be implemented. + + +\section{Deposit Protocol} +For the deposit protocol (described in section \ref{sec:deposit-protocol}) only the handling and verification of \gls{CSBS} signatures has to be added. + +\subsection{Public APIs and Data Structures} +Deposit is an existing endpoint available under \texttt{POST /coins/[coin public key]/deposit} where "coin public key" is encoded as Crockford base32. +Additional parameters are passed as JSON (as described in table \ref{tab:spend-request}).\\\\ +\framebox[1.1\width]{\color{blue}\texttt{POST /coins/[coin public key]/deposit}} +\begin{table}[ht] + \centering + \colorlet{BFH-table}{BFH-MediumBlue!10} + \colorlet{BFH-tablehead}{BFH-MediumBlue!50} + \setupBfhTabular + \begin{tabular}{ll} + \rowcolor{BFH-tablehead} + \textbf{Field} & \textbf{Value} \\ + % cipher & Denomination cipher: 2 stands for \gls{CSBS} \\ + % b & \gls{CSBS} signature session identifier (either 0 or 1) \\ + % s & signature scalar (32 Bytes encoded in Crockford base32 Hex) \\ + merchant\_payto\_uri & Account that is credited \\ + wire\_salt & Salt used by the merchant \\ + contribution & Amount to use for payment (for one specific coin) \\ + denom\_pub\_hash & Denomination public key hash \\ + ub\_sig & (unblinded) denomination signature of coin \\ + merchant\_pub & Merchant public key \\ + h\_contract\_terms & Contract terms hash \\ + coin\_sig & Deposit permission signature \\ + timestamp & Timestamp of generation \\ + refund\_deadline (optional) & Refund deadline \\ + wire\_transfer\_deadline (optional) & Wire transfer deadline \\ + \end{tabular} + \caption{Spend request} + \label{tab:spend-request} +\end{table} + +Relevant field for the \gls{CSBS} implementation is the field "ub\_sig" containing the unblinded denomination signature of the coin. +For RSA, the (nested) \ac{JSON} is described in table \ref{tab:spend-request-ubsig-rsa}. +\begin{table}[ht] + \centering + \colorlet{BFH-table}{BFH-MediumBlue!10} + \colorlet{BFH-tablehead}{BFH-MediumBlue!50} + \setupBfhTabular + \begin{tabular}{lll} + \rowcolor{BFH-tablehead} + \textbf{Field} & \textbf{Type} & \textbf{Value} \\ + cipher & Integer & Denomination cipher: 1 stands for RSA \\ + rsa\_signature & String & Unblinded RSA signature \\ + \end{tabular} + \caption{ub\_sig (RSA)} + \label{tab:spend-request-ubsig-rsa} +\end{table} + +Table \ref{tab:spend-request-ubsig-cs} describes the values in "ub\_sig" required for \gls{CSBS}. +\begin{table}[ht] + \centering + \resizebox{0.85\textwidth}{!}{\begin{minipage}{\textwidth} + \colorlet{BFH-table}{BFH-MediumBlue!10} + \colorlet{BFH-tablehead}{BFH-MediumBlue!50} + \setupBfhTabular + \begin{tabular}{lll} + \rowcolor{BFH-tablehead} + \textbf{Field} & \textbf{Type} & \textbf{Value} \\ + cipher & Integer & Denomination cipher: 2 stands for \gls{CSBS} \\ + cs\_signature\_r & String & Curve point $ R' $ (32 Bytes encoded in Crockford base32 Hex) \\ + cs\_signature\_s & String & Signature scalar (32 Bytes encoded in Crockford base32 Hex) \\ + \end{tabular} + \caption{ub\_sig (\gls{CSBS})} + \label{tab:spend-request-ubsig-cs} +\end{minipage}} +\end{table} + + +\subsection{Persistence} +Persistence is handled in the functions \texttt{postgres\_insert\_deposit} and\\ \texttt{postgres\_have\_deposit} located in \url{src/exchangedb/plugin_exchangedb_postgres.c}. +However, these functions are not containing \gls{CSBS}-specific persistence. +\\What needs to be adjusted however, is the function \texttt{postgres\_ensure\_coin\_known} called by the function \texttt{TEH\_make\_coin\_known} (located in \url{src/exchange/taler-exchange-httpd_db.c}). + + +% \section{Tipping} +% \subsection{Public APIs and Data Structures} +% \subsection{Code Location} +% \subsection{Persistence} +% \subsection{Used Libraries} + +% \section{Payback Protocol} +% \subsection{Public APIs and Data Structures} +% \subsection{Code Location} +% \subsection{Persistence} +% \subsection{Used Libraries} + + +% sollte ein Product Backlog das Ziel dieser Phase sein? diff --git a/doc/cs/content/4_3_implementation.tex b/doc/cs/content/4_3_implementation.tex new file mode 100644 index 000000000..879e69e8f --- /dev/null +++ b/doc/cs/content/4_3_implementation.tex @@ -0,0 +1,333 @@ +\chapter{Implementation} +\label{chap:implement} +This chapter gives an overview on the implementation challenges and discusses special parts in the implementation. + + +\section{Signature Scheme Operations} +The signature scheme operations are implemented in the GNUnet core repository \cite{gnunet-git} (and have been merged into the master branch). +This would allow other GNUnet projects to use our implementation of the Clause Blind Schnorr Signature Scheme. + +The implementation is done in multiple locations: +\begin{itemize} + \item \texttt{src/include/gnunet\_crypto\_lib.h}: + This header file is included when using GNUnet's cryptography implementation. + \item \texttt{src/util/crypto\_cs.c}: + The functions specified in \texttt{gnunet\_crypto\_lib.h} will be implemented here. + \item \texttt{src/util/test\_crypto\_cs.c}: + The test cases for the signature scheme will be implemented here. + \item \texttt{src/util/perf\_crypto\_cs.c}: + This file houses the implementation of a small program that will be used to compare the performance against the blind RSA Signature Scheme. +\end{itemize} + +The specification explaining the \ac{API} can be found in section \ref{sec:specification-signature-scheme}. There are two internal functions that have to be explained further in this section. + +The \texttt{map\_to\_scalar\_subgroup} function clamps scalars, which is necessary for values that are derived using a \gls{hkdf}. +It sets the three least significant bits to zero (making the scalar a multiple of 8), sets the most significant bit to zero and the second-most significant bit to one. +This process is further described in \cite{rfc7748} and \cite{madden:curve25519-clamping}. + +\begin{lstlisting}[style=bfh-c, language=C, caption={Function map\_to\_scalar\_subgroup - Crypto API}, label={lst:map-to-scalar}] +static void +map_to_scalar_subgroup (struct GNUNET_CRYPTO_Cs25519Scalar *scalar) +{ + scalar->d[0] &= 248; + scalar->d[31] &= 127; + scalar->d[31] |= 64; +} +\end{lstlisting} + +Another important function is the \gls{fdh} (see \ref{sec:schnorr-sig}) used to map the message to a scalar. +GNUnet provides a \gls{fdh} function, which expects libgcrypt's multi precision format. +A conversion function is provided by GNUnet, which requires the data to be in big endian format. +Since libsodium uses a little endian representation, the conversion process must include endianness conversion. +The complete \gls{fdh} including the required conversions is implemented in the function described in listing \ref{lst:cs-fdh}. +\begin{lstlisting}[style=bfh-c, language=C, caption={Function cs\_full\_domain\_hash - Crypto API}, label={lst:cs-fdh}] +static void +cs_full_domain_hash (const struct GNUNET_CRYPTO_CsRPublic *r_dash, + const void *msg, + size_t msg_len, + const struct GNUNET_CRYPTO_CsPublicKey *pub, + struct GNUNET_CRYPTO_CsC *c) +{ + ... +\end{lstlisting} + +Last but not least, the implementation has one notable performance improvement not mentioned in the redesigned protocols. +In various steps \gls{hkdf} is used multiple times in a row. +For example to derive the four blinding secrets $\alpha_0, \alpha_1, \beta_0, \beta_1$. +The derivation can be done in one \gls{hkdf} call with bigger output size, 128 bit in this case. +The output then can be split in four parts and then mapped to the ed25519 subgroup. +This can be done secure, because as explained in \autoref{sec:kdf} a \gls{hkdf} output is truly random. + + +\section{Taler Cryptographic Utilities} +\begin{bfhNoteBox} + Implementation is done in Taler's exchange. + From here on the implementation can be found in the exchange git repository \cite{taler-git:exchange}. +\end{bfhNoteBox} +The cryptographic utilities of Taler can be found in \texttt{src/util}. + + +The implementation is done in various locations: +\begin{itemize} + \item \texttt{src/include/taler\_crypto\_lib.h}: This header file is included when using Taler's cryptography implementation. + The different data structures and functionality are defined here. + \item \texttt{src/util/denom.c}: Implement denomination utility functions for \gls{CSBS} cases + \item \texttt{src/util/crypto.c}: Adjust all utility functions to support \gls{CSBS}. + crypto.c contains many cryptographic utility functions, for example to create planchets or blinding factors. + \item \texttt{src/util/test\_crypto.c}: Functionality tests for crypto.c and denom.c + \item \texttt{src/include/taler\_signatures.h}: In this header file message formats and signature constants are defined (not modified) + \item \texttt{src/util/secmod\_signatures.c}: Utility functions for Taler security module signatures +\end{itemize} + +The security module \texttt{taler-secmod-cs} is implemented here: +\begin{itemize} + \item \texttt{src/util/taler-exchange-secmod-cs.c}: Standalone process to perform private key Clause Blind Schnorr signature operations. + \item \texttt{src/util/taler-exchange-secmod-cs.h}: Specification of \ac{IPC} messages for the CS secmod process + \item \texttt{src/util/taler-exchange-secmod-cs.conf}: Configuration file for the secmod process + \item \texttt{src/util/secmod\_common.c} and \texttt{src/util/secmod\_common.h}: Common functions for the exchange's security modules (not modified) +\end{itemize} + +The corresponding crypto helper, that talks with the security module, and its tests \& benchmarks are implemented here: +\begin{itemize} + \item \texttt{src/util/crypto\_helper\_cs.c}: Utility functions to communicate with the security module + \item \texttt{src/util/crypto\_helper\_common.c}: and \texttt{crypto\_helper\_common.h}: Common functions for the exchange security modules (not modified) + \item \texttt{src/util/test\_helper\_cs.c}: Tests and benchmarks for the \gls{CSBS} crypto helper +\end{itemize} +% Crypto API offene Punkte: +%Input-validation of points and scalars: +% describe clamping: https://neilmadden.blog/2020/05/28/whats-the-curve25519-clamping-all-about/ +% Testing: inverse operations, blinded signature test + + +\section{Denomination Key Management} +For the implementation, the \gls{CSBS} security module had to be connected to the key handling and the \gls{CSBS} denominations had to be integrated: +\begin{itemize} + \item \url{src/exchange/taler-exchange-httpd_keys.h} and \\ + \url{src/exchange/taler-exchange-httpd_keys.c}: Integrate \gls{CSBS} secmod and denomination key management + \item \url{src/exchange-tools/taler-exchange-offline.c}: Implement \gls{CSBS} case for offline signing of denomination keys + \item \url{src/include/taler_exchange_service.h}: \\ + Add \gls{CSBS} secmod public key to struct\\TALER\_EXCHANGE\_FutureKeys + \item \url{src/json/json_helper.c}: Implement CS case in function parse\_denom\_pub (used in taler-exchange-offline.c) + \item \url{src/json/json_pack.c}: Implement \gls{CSBS} case in function TALER\_JSON\_pack\_denom\_pub (used in taler-exchange-httpd\_keys.c) + \item \url{src/pq/pq_query_helper.c}: Implement \gls{CSBS} case in function qconv\_denom\_pub + \item \url{src/pq/pq_result_helper.c}: Implement \gls{CSBS} case in function extract\_denom\_pub +\end{itemize} + +In order for the tests to pass, the following changes had to be implemented: +\begin{itemize} + \item \url{src/lib/exchange_api_management_get_keys.c}: Add denom\_secmod\_cs\_public\_key JSON parsing, implement \gls{CSBS} case \\in function TALER\_EXCHANGE\_ManagementGetKeysHandle + \item \url{src/testing/.gitignore}: Add paths where \gls{CSBS} keys are stored (secmod-helper) + \item \url{src/testing/test_auditor_api.conf}: Add section taler-exchange-secmod-cs + \item \url{src/testing/test_exchange_api_keys_cherry_picking.conf}: Add section taler-exchange-secmod-cs + \item \url{src/testing/testing_api_helpers_exchange.c}: Add \gls{CSBS} secmod start and stop logic +\end{itemize} + + +\section{New Endpoint for $R$} +The new endpoint is available in the exchange's HTTP server under \url{/csr}. +It parses and checks the input, passes the request for derivation of the two $ R $'s down to the \gls{CSBS} security module and returns them to the requestor. +The implementation can be found in: +\begin{itemize} + \item \url{src/exchange/taler-exchange-httpd.c}: + Definition for the new endpoint, calls the function that handles \url{/csr} requests + \item \url{src/exchange/taler-exchange-httpd_responses.h} and \\ + \url{src/exchange/taler-exchange-httpd_responses.c}: \\ + Added function TEH\_RESPONSE\_reply\_invalid\_denom\_cipher\_for\_operation that indicates a failure when the endpoint is called for a non-\gls{CSBS} denomination + \item \url{src/exchange/taler-exchange-httpd_csr.h} and \\ + \url{src/exchange/taler-exchange-httpd_csr.c}: \\ + Implementation of the request handler for the new endpoint + \item \url{src/exchange/taler-exchange-httpd_keys.h} and \\ + \url{src/exchange/taler-exchange-httpd_keys.c}: \\ + Additional function TEH\_keys\_denomination\_cs\_r\_pub that passes down the request to derive the $ R $ to the taler-exchange-secmod-cs helper +\end{itemize} + +The tests that check the functionality of the procotols are defined in \url{src/testing/} and use code that calls the \ac{API} (located in \url{src/lib/}). +Since the new endpoint is used during withdrawing coins, testing for the \url{/csr} endpoint is integrated in these protocol tests. +Therefore, a call to the endpoint was implemented and later integrated into the calls to the withdraw-\ac{API}. +Code for calling the endpoint is located in these files: +\begin{itemize} + \item \url{src/include/taler_exchange_service.h}: \\ + Header describing functions and data structures used in withdraw and refresh testing: + \begin{itemize} + \item struct TALER\_EXCHANGE\_CsRHandle: Handle containing request information + \item struct TALER\_EXCHANGE\_CsRResponse: Response details + \item function TALER\_EXCHANGE\_CsRCallback: Callback function to deliver the results (used in withdraw and refresh) + \item function TALER\_EXCHANGE\_csr: Used to call endpoint + \item function TALER\_EXCHANGE\_csr\_cancel: Used to free dynamically allocated resources + \end{itemize} + \item \url{src/lib/exchange_api_csr.c}: Implementation of \url{/csr} request +\end{itemize} + + +\section{Withdraw Protocol} +\label{sec:withdraw-protocol-impl} +Since this is an existing endpoint, it was adjusted to support \gls{CSBS}. +Mainly, the in- and output-handling had to be adjusted as described in section \ref{sec:specification-withdraw-public-api}, additional cipher checks for the denomination were added and the \gls{CSBS} for persisting the request in the database was implemented. +\\\\ +An interesting part of the implementation is the check whether a nonce was already used for this denomination or not (step: $s \leftarrow \text{GetWithdraw}(n_w, D_p)$). +This step ensures that the same signature will always be returned for a certain nonce. +Using the same nonce for the same denomination twice without this check would lead to the same random value $r$. +This is due to derivation of $r := \text{HKDF}(256,n_w || d_s, \text{"r"})$. +An attacker could then immediately recover the secret key by the following equation: $(h' - h) * x \mod q = s -s' \mod q$ \cite{tibouchi:attacks-schnorr-nonce}. +There are popular examples of this vulnerability in Sony Playstation 3's or Bitcoins ECDSA implementation \cite{buchanan:ps3-ecdsa-vuln} \cite{wang:bitcoin-ecdsa-vuln}. +More details on how such a vulnerability can be exploited can be found in one of the author's blog posts \cite{gian:nonce-sense}.\\ +The designed Taler protocols using \gls{CSBS} are preventing this attack by checking the nonce and return the previously generated signature. +Additionally the denomination's public key is included in this check to prevent another issue explained in section \ref{sec:taler-vuln}.\\ +The check is implemented by persisting a hash value over $n_w$ and $D_p$. +On every withdrawal \texttt{check\_request\_idempotent()} is called, which checks whether the persisted hash matches with the current $n_w, D_p$ pair. + + +\begin{itemize} + \item \url{src/exchange/taler-exchange-httpd_withdraw.c}: Implementation of \gls{CSBS} case for withdraw endpoint + \item \url{src/exchange/taler-exchange-httpd_keys.c}: Implement \gls{CSBS} case in function \\ + TEH\_keys\_denomination\_sign (passes the signature creation down to the crypto helpers) + \item \url{src/include/taler_json_lib.h} and \url{src/json/json_helper.c}: \\ + Add function TALER\_JSON\_spec\_blinded\_planchet + \item \url{src/json/json_pack.c}: \\ + Implement \gls{CSBS} case in function\\ TALER\_JSON\_pack\_blinded\_denom\_sig + \item \url{src/pq/pq_query_helper.c}: implement \gls{CSBS} case in functions qconv\_denom\_sig and qconv\_blinded\_denom\_sig + \item \url{src/pq/pq_result_helper.c}: Implement \gls{CSBS} case in function extract\_blinded\_denom\_sig +\end{itemize} + +For testing, the \gls{CSBS}-related data structures and procedures as well as the request to the additional endpoint \url{/csr} (before performing the actual withdrawal) were integrated: +\begin{itemize} + \item \url{src/testing/test_exchange_api.c}: Add additional tests for \gls{CSBS} withdraw + \item \url{src/include/taler_testing_lib.h}: Specification for functions \\ + TALER\_TESTING\_cmd\_withdraw\_cs\_amount and \\ + TALER\_TESTING\_cmd\_withdraw\_cs\_amount\_reuse\_key, add denomination cipher parameter to function TALER\_TESTING\_find\_pk + \item \url{src/testing/testing_api_cmd_withdraw.c}: add functions \\ + TALER\_TESTING\_cmd\_withdraw\_cs\_amount and \\ + TALER\_TESTING\_cmd\_withdraw\_cs\_amount\_reuse\_key, implement \gls{CSBS}-specific logic for withdraw + \item \url{src/testing/testing_api_helpers_exchange.c}: + add cipher parameter to function TALER\_TESTING\_find\_pk + \item \url{src/lib/exchange_api_withdraw.c}: Implement \gls{CSBS}-specific withdraw logic, integrate \url{/csr} request + \item \url{src/lib/exchange_api_withdraw2.c}: implement \gls{CSBS} case + \item \url{src/include/taler_json_lib.h} and \url{src/json/json_pack.c}: \\ + Add function TALER\_JSON\_pack\_blinded\_planchet + \item \url{src/json/json_helper.c} implement \gls{CSBS} case in function parse\_blinded\_denom\_sig +\end{itemize} + +\section{Deposit Protocol} +For deposit, only few changes were necessary because some of the required functionality has already been added for the previously implemented protocols, and only the coin signature verification is \gls{CSBS}-specific in this protocol. +\begin{itemize} + \item \url{/src/exchange/taler-exchange-httpd_deposit.c}: Add check whether denomination cipher and denomination signature cipher are equal + \item \url{/src/json/json_helper.c}: Implement \gls{CSBS} case in function parse\_denom\_sig + \item \url{/src/pq/pq_result_helper.c}: Implement \gls{CSBS} case in function extract\_denom\_sig +\end{itemize} + +Tests for deposit are implemented here: +\begin{itemize} + \item \url{/src/testing/test_exchange_api.c}: Add tests (see "struct TALER\_TESTING\_Command\ spend\_cs[]") that spend \gls{CSBS} coins withdrawn in tests added for withdrawal + \item \url{/src/json/json_pack.c}: Implement \gls{CSBS} case in function TALER\_JSON\_pack\_denom\_sig +\end{itemize} + +\section{Fixing a Minor Security Issue in Taler's RSA Blind Signature Protocols} +\label{sec:taler-vuln} +While implementing the nonce check in the \gls{CSBS} protocol (see section \ref{sec:withdraw-protocol-impl}), a minor security issue in Taler's current RSA Blind Signature implementation was detected and fixed. +The issue was only in the implementation of the current RSA Blind Signature protocols, the fix for this scenario was already implemented in \gls{CSBS} since the beginning. + +\subsection{Security Issue} +\label{sec:taler-vuln-desc} + +The redesigned \gls{CSBS} protocols already include the denomination key in the nonce check, which fixes this issue (see \ref{sec:withdraw-protocol-schnorr}). +In the case of \gls{RSABS}, the current protocol includes an \gls{idempotence} check by persisting the hash value of the blinded coin $m'$. +On a withdrawal/refresh the \gls{idempotence} check compares if the hash value of $m'$ was seen in the past and returns the 'old' signature on a match. +This could lead to the following scenario: + +\begin{enumerate} + \item A broken wallet withdraws a coin with denomination $D_{p_{(1)}}$. + \item The wallet sends a request to withdraw the same coin for denomination $D_{p_{(2)}}$. + \item The exchange returns the signature for the denomination $D_{p_{(1)}}$ due to the \gls{idempotence} check. + \item Since the exchange returned an invalid signature, the customer can file a complaint at the auditor. + \item The auditor then has to investigate why the exchange returned invalid signatures. + \item The auditor can disprove the complaint by querying the persisted hash used for the \gls{idempotence} check. + With the associated denomination public key that is also persisted, the auditor can successfully verify the signature and thus prove that the exchange operated honestly. +\end{enumerate} + +Including the denomination public key into the persisted hash for the \gls{idempotence} check solves this issue. +If a broken wallet now sends the same coin for more than one denomination, the exchange returns valid signatures in both cases.\\ +While this is still an issue, this case is already handled nicely in Taler since this situation could also occur if a broken value tries to withdraw the same coin with two different blinding factors. + +\subsection{Impact} +The impact of this security vulnerability is considered as very low. +An auditor investigating such an issue can simply retrace what happened by checking the persisted hash and associated denomination. +The impact of the issue is, that an auditor needs to investigate an issue, which can be prevented inside the protocol. +\\ +In the previous section the client was considered a broken wallet. +While this could be done on purpose by malicious a customer, there is no real motivation for abusing this issue due the easy detection of an auditor. + + +\subsection{Fix} +Listing \ref{lst:rsa-idempotence} shows the code of calculating the hash for the idempotency check in the RSA case before it was fixed. +By trying to implement the \gls{CSBS} case, the question came up why the RSA case has not included the denomination key into the check. +After discussing this issue with Christian Grothoff, the conclusion was to include the denomination public key to prevent the discussed issue. + +\begin{lstlisting}[style=bfh-c,language=C, caption={Idempotency check on RSA}, label={lst:rsa-idempotence}] + enum GNUNET_GenericReturnValue + TALER_coin_ev_hash (const struct TALER_BlindedPlanchet *blinded_planchet, + struct TALER_BlindedCoinHash *bch) + { + switch (blinded_planchet->cipher) + { + case TALER_DENOMINATION_RSA: + GNUNET_CRYPTO_hash ( + blinded_planchet->details.rsa_blinded_planchet.blinded_msg, + blinded_planchet->details.rsa_blinded_planchet.blinded_msg_size, + &bch->hash); + return GNUNET_OK; + case TALER_DENOMINATION_CS: + ... + +\end{lstlisting} + +The issue is fixed by adding a hash of the current denomination key into the calculation of the hash used in the \gls{idempotence} check. +The applied fix can be seen in listing \ref{lst:fixed-idempotence}. + +\begin{lstlisting}[style=bfh-c,language=C, caption={Fixed idempotency check}, label={lst:fixed-idempotence}] + enum GNUNET_GenericReturnValue + TALER_coin_ev_hash (const struct TALER_BlindedPlanchet *blinded_planchet, + const struct TALER_DenominationHash *denom_hash, + struct TALER_BlindedCoinHash *bch) + { + switch (blinded_planchet->cipher) + { + case TALER_DENOMINATION_RSA: + { + struct GNUNET_HashContext *hash_context; + hash_context = GNUNET_CRYPTO_hash_context_start (); + + GNUNET_CRYPTO_hash_context_read (hash_context, + &denom_hash->hash, + sizeof(denom_hash->hash)); + GNUNET_CRYPTO_hash_context_read (hash_context, + blinded_planchet->details. + rsa_blinded_planchet.blinded_msg, + blinded_planchet->details. + rsa_blinded_planchet.blinded_msg_size); + GNUNET_CRYPTO_hash_context_finish (hash_context, + &bch->hash); + return GNUNET_OK; + } + case TALER_DENOMINATION_CS: + { + struct GNUNET_HashContext *hash_context; + hash_context = GNUNET_CRYPTO_hash_context_start (); + + GNUNET_CRYPTO_hash_context_read (hash_context, + &denom_hash->hash, + sizeof(denom_hash->hash)); + GNUNET_CRYPTO_hash_context_read (hash_context, + &blinded_planchet->details. + cs_blinded_planchet.nonce, + sizeof (blinded_planchet->details. + cs_blinded_planchet.nonce)); + GNUNET_CRYPTO_hash_context_finish (hash_context, + &bch->hash); + return GNUNET_OK; + } + default: + GNUNET_break (0); + return GNUNET_SYSERR; + } + } +\end{lstlisting} diff --git a/doc/cs/content/4_execution.tex b/doc/cs/content/4_execution.tex new file mode 100644 index 000000000..675a33439 --- /dev/null +++ b/doc/cs/content/4_execution.tex @@ -0,0 +1,5 @@ +\input{content/4_1_design.tex} + +\input{content/4_2_specification.tex} + +\input{content/4_3_implementation.tex} diff --git a/doc/cs/content/5_discussion.tex b/doc/cs/content/5_discussion.tex new file mode 100644 index 000000000..8381273c1 --- /dev/null +++ b/doc/cs/content/5_discussion.tex @@ -0,0 +1,317 @@ +\chapter{Discussion} +\label{chap:disc} +This chapter analyses the \acl{CS} implementation and compares it to the existing implementation with \gls{RSABS}. +The comparison will include the schemes itself, performance comparisons and a discussion on the security assumptions. +For the performance comparison CPU usage, latency, bandwidth and storage space are compared. + +\section{Cipher Agility} +One of the benefits of having another blind signature scheme in Taler is \textit{cipher agility}. +Cipher agility means that one scheme can substitute another, for example if one scheme gets compromised in the future. + +Cipher agility is considered harmful in certain situations. +TLS 1.2 \cite{rfc5246} and IPSEC/IKEv2 \cite{rfc6071} are good examples on how dangerous cipher agility inside protocols can be. +There are many ways these protocols can be set up insecure. +\\\\ +Taler's protocols are built around blind signature schemes. +Therefore it is crucial to have an additional secure blind signature scheme that works with all Taler protocols. +As described in section \ref{sec:blind-sign-schemes}, blind signature schemes can vary and may be complex to substitute. +The \gls{CSBS} implementation provides such an alternative and thus \textit{cipher agility}. + +\section{Scheme Comparison} +\label{chap:disc-scheme-comp} +Both schemes are explained in the preliminaries chapter (\gls{RSABS} in section \ref{fig:rsa-fdh-blind-sign} and \gls{CSBS} in \ref{fig:clause-blind-schnorr-sign-scheme}). +\\ +There are multiple differences worth mentioning. +The first difference is that Schnorr signatures are inherently randomized. +This is also where the additional step in Schnorr signatures comes from. +A random number is chosen by the signer for every signature. \\ +In \gls{CSBS} two blinding secrets are used instead of one in \gls{RSABS}. +On top of that, \gls{CSBS} needs to do most computations for signature creation twice, due to the \ac{ROS} problem (see \ref{par:ros-problem}). +\\\\ +\textit{\Gls{abort-idempotency}} is a very important property for Taler. +Ensuring \gls{abort-idempotency} with the \gls{CSBS} scheme is harder than it was with RSA, due to the many random elements in the scheme ($r_0, r_1, \alpha_0, \alpha_1, \beta_0, \beta_1, b$). +The reason that these values are chosen randomly is the need for \textit{unpredictability}.\\ +In the protocols (see chapter \ref{chap:design}) \gls{hkdf} is extensively used to derive these values instead of randomly generating them. +That way, the values are still \textit{unpredictable} (due to \gls{hkdf} properties), but now the protocols also ensure \textit{\gls{abort-idempotency}}. +In comparison to the RSA Blind Signature scheme, this is a clever and elegant solution, but the protocol complexity is increased. +\\\\ +One could now think that RSA would be much simpler to implement, since the scheme looks easier and more accessible for many. +This can go horribly wrong and many developers still underestimate implementing RSA. +There are a lot of attacks on RSA, some examples are listed on the famous tool RsaCtfTool \cite{ganapati:rsactftool}. +Ben Perez made a popular talk and blog post, about why one should stop using RSA and should preferably use libsodium and \ac{ECC} \cite{perez:stoprsa}. +Using \gls{RSABS} in Taler is still a reasonable and fine choice. +Taler uses libgcrypt, a well-known and tested library. +\\ +To conclude, the \gls{CSBS} protocols might be more complex to understand than the RSA Blind Signature protocols. +One has to keep in mind that implementing RSA correctly is hard. +\\ +Another difference worth mentioning is, that the \gls{CSBS} scheme does not need scheme specific configurations, whereas RSA needs a key size specified. +This is because the implemented \gls{CSBS} version only supports \gls{25519}. +\\\\ +Furthermore, both schemes provide \textit{perfect blindness}, see paragraph \ref{par:prop-blindness-rsa} for RSA and paragraph \ref{par:prop-blindness-cs} for \gls{CSBS}. + + +\section{Performance Comparison} +\label{sec:disc-perf-comp} +This section compares how the two schemes perform regarding CPU usage, latency, bandwidth and space. +Clause Schnorr has fixed key sizes with 256 bits (32 bytes), which we compare against different RSA key sizes (1024, 2048, 3072 and 4096 bits). +In terms of security, \gls{CSBS} 256 bit keys could be compared to 3072 bit RSA keys (see \url{https://www.keylength.com/} for more information). + +\subsection{CPU Usage} +Various benchmarks were made on different CPU architectures. +This section discusses the main results, detailed information about the performance comparison can be found in appendix \ref{chap:app-perf}. +We thank the Taler team for providing measurements from additional systems and architectures. + +Table \ref{tab:comp-cs-vs-rsa-3072} shows how \gls{CSBS} compares to RSA 3072. +RSA 3072 was chosen for comparison, since they both provide a comparable level of security. +Both provide about 128 bits of security, which means that roughly $2^{128}$ attempts in average are needed for a successful brute-force attack.\\ +The table shows that \gls{CSBS} has better performance compared to RSA 3072 in all operations. +The biggest difference can be seen in the key generation. +In RSA, two random primes are needed, whereas \ac{DLP} algorithms like \gls{CSBS} only need to generate a random value. +Since key generation is done rarely compared to the other operations, the time needed for key generation does not matter that much.\\ +Furthermore, the blinding in \gls{CSBS} is still faster than blinding in RSA, although in the \gls{CSBS} case the calculation is done twice. Also the derivation of $r_0,r_1$, the generation of $R_0,R_1$ and the derivation of $\alpha_0, \beta_0, \alpha_1, \beta_1$ is included in the measurement for the blinding operation of \gls{CSBS}. +Signing and blinding operations are much faster in \gls{CSBS}, also \gls{CSBS} signature verification is faster than RSA 3072. + +\begin{bfhBox}[BFH-MediumBlue]{Setup} + CPU: 8-core AMD Ryzen 7 PRO 5850U \\ + OS: Ubuntu 21.10 Linux 5.13.0-25-generic \#26-Ubuntu SMP Fri Jan 7 15:48:31 UTC 2022 x86\_64 x86\_64 x86\_64 GNU/Linux \\ + libsodium version: 1.0.18-1build1 \\ + libgcrypt version: 1.8.7-5ubuntu2 \\\\ + Benchmarks with other hardware setups can be found in appendix \ref{chap:app-perf}. +\end{bfhBox} + +\begin{table}[h] + \centering + \colorlet{BFH-table}{BFH-MediumBlue!10} + \colorlet{BFH-tablehead}{BFH-MediumBlue!50} + \setupBfhTabular + \begin{tabular}{llr} + \rowcolor{BFH-tablehead} + \textbf{Signature Scheme} & \textbf{Operation} & \textbf{Speed} \\\hline + CS & 10x key generation & 0.204 ms \\\hline + RSA 3072 bit & 10x key generation & 2684 ms \\\hline + \hline + CS & 10x derive $R_0, R_1$ \& blinding & 3.870 ms \\\hline + RSA 3072 bit & 10x blinding & 5 ms \\\hline + \hline + CS & 10x signing & 0.077 ms \\\hline + RSA 3072 bit & 10x signing & 86 ms \\\hline + \hline + CS & 10x unblinding & 0.001 ms \\\hline + RSA 3072 bit & 10x unblinding & 24 ms \\\hline + \hline + CS & 10x verifying & 1.358 ms \\\hline + RSA 3072 bit & 10x verifying & 3.075 ms \\\hline + \end{tabular} + \caption{Comparison on CS vs. RSA 3072} + \label{tab:comp-cs-vs-rsa-3072} +\end{table} + +Table \ref{tab:comp-cs-vs-rsa-1024} shows a comparison between \gls{CSBS} and RSA 1024 bit. +RSA 1024 is in some situations faster than the \gls{CSBS} implementation. +Note that 1024 bit keys are not recommended for many use cases, but the highest currently known RSA factorization done is 829 bits \cite{enwiki:1055393696}. +The following section \ref{sec:disc-risk} explains the risk running RSA 1024 or \gls{CSBS} denominations further.\\ +The blind and unblind operations are running in a wallet implementation, therefore the comparison with RSA 1024 is very interesting for devices with less CPU power. +Comparison of such hardware can be found in appendix \ref{chap:app-perf}, these comparison results come to the same conclusion.\\ +Although RSA 1024 bit is much faster in the blinding operation, \gls{CSBS} still perform better when calculating the blinding and unblinding operations together. +\gls{CSBS} unblinding computes only an addition of two scalars $s + \alpha \mod p$, while RSA computes $s * r^{-1}$. +To conclude, \gls{CSBS} are faster than RSA 1024 bit and provide a better level of security. +This can be especially useful for wallets running on devices with less CPU power. +The verification on RSA 1024 is faster than \gls{CSBS}. +Therefore, it has to be further investigated which algorithm would overall perform better for the exchange or merchants. +While RSA 1024 bit can compete in certain operations, \gls{CSBS} provide a better level of security and are still faster in most operations. + +\begin{table}[h] + \centering + \colorlet{BFH-table}{BFH-MediumBlue!10} + \colorlet{BFH-tablehead}{BFH-MediumBlue!50} + \setupBfhTabular + \begin{tabular}{llr} + \rowcolor{BFH-tablehead} + \textbf{Signature Scheme} & \textbf{Operation} & \textbf{Speed} \\\hline + CS & 10x key generation & 0.204 ms \\\hline + RSA 1024 bit & 10x key generation & 126 ms \\\hline + \hline + CS & 10x derive $R_0, R_1$ \& blinding & 3.870 ms \\\hline + RSA 1024 bit & 10x blinding & 1.282 ms \\\hline + \hline + CS & 10x signing & 0.077 ms \\\hline + RSA 1024 bit & 10x signing & 7 ms \\\hline + \hline + CS & 10x unblinding & 0.001 ms \\\hline + RSA 1024 bit & 10x unblinding & 2.991 ms \\\hline + \hline + CS & 10x verifying & 1.358 ms \\\hline + RSA 1024 bit & 10x verifying & 0.876 ms \\\hline + \end{tabular} + \caption{Comparison on CS vs RSA 1024} + \label{tab:comp-cs-vs-rsa-1024} +\end{table} +\subsection{Disk Space} +\begin{bfhWarnBox} + These are theoretical calculations, implementations may choose to persist additional values. + \end{bfhWarnBox} +\gls{CSBS} save disk space due to the much smaller key sizes. +Even more disk space is saved by deriving values with the \gls{hkdf}, these values do not have to be stored. +\\ +Table \ref{tab:comp-sign-space} shows the disk space comparison of signatures, the private keys alone need even less space with 256 bits per key. +\\ +The wallet saves a lot of disk space by deriving most of the values. +In the \gls{CSBS} case a wallet must at least persist the private key $c_s$, $R_0, R_1, s', D_p$, each being 256 bits (32 bytes). +A wallet needs to persist 150 bytes per coin in total. +In the RSA Blind Signature case the wallet persists $c_s$, $b$, $\sigma_c$, $D_p$. +\\Note: for refreshed coins an additional 32 byte value is persisted as seed.\\ +$c_s$ is still a 32 byte value in the RSA case, the other values depend on the RSA key size. (32 byte + 3 * \textit{rsa\_keysize}). +The disk space comparison for a wallet can be found in \ref{tab:comp-wallet-space}. + +\begin{table}[ht] + \centering + \colorlet{BFH-table}{BFH-MediumBlue!10} + \colorlet{BFH-tablehead}{BFH-MediumBlue!50} + \setupBfhTabular + \begin{tabular}{lccr} + \rowcolor{BFH-tablehead} + \textbf{Signature Scheme} & \textbf{Disk Space} & \textbf{Factor} & \textbf{Disk Space 1M signatures}\\\hline + CS & 512 bits & 1x & 64 MB\\\hline + RSA 1024 bit & 1024 bits & 2x & 128 MB \\\hline + RSA 2048 bit & 2048 bits & 4x & 256 MB\\\hline + RSA 3072 bit & 3072 bits & 6x & 384 MB\\\hline + RSA 4096 bit & 4096 bits & 8x & 512 MB\\\hline + \end{tabular} + \caption{Comparison disk space signatures} + \label{tab:comp-sign-space} +\end{table} + +\begin{table}[ht] + \centering + \colorlet{BFH-table}{BFH-MediumBlue!10} + \colorlet{BFH-tablehead}{BFH-MediumBlue!50} + \setupBfhTabular + \begin{tabular}{lccr} + \rowcolor{BFH-tablehead} + \textbf{Signature Scheme} & \textbf{Disk Space} & \textbf{Factor} & \textbf{Disk Space 1M coins}\\\hline + CS 256 bits & 150 bytes & 1x & 150 MB\\\hline + RSA 1024 bit & 416 bytes & 2.7x & 416 MB \\\hline + RSA 2048 bit & 800 bytes & 5.3x & 800 MB\\\hline + RSA 3072 bit & 1184 bytes & 7.9x & 1184 MB\\\hline + RSA 4096 bit & 1568 bytes & 10.4x & 1568 MB\\\hline + \end{tabular} + \caption{Comparison disk space wallet} + \label{tab:comp-wallet-space} +\end{table} + +\subsection{Bandwidth} +\begin{bfhWarnBox} + These are theoretical calculations, implementations may choose to persist additional values. +\end{bfhWarnBox} +The reasons that \gls{CSBS} use less bandwidth is mostly because the signature/key sizes are much smaller. +The bandwidth improvements for the \texttt{/keys} API is the same as specified in the table with disk space comparison \ref{tab:comp-sign-space}. +For \gls{CSBS} many calculations are performed twice, therefore also two values are submitted. +Table \ref{tab:comp-band-withd} compares the bandwidth used in a withdrawal. +The 32 byte values $2 * n_w, 2 * D_p, R_0, R_1, s,W_p, c_0, c_1, \sigma_W$ as well as an integer $b$ are transmitted for \gls{CSBS}.\\ +For RSA, the values $D_p, m', \sigma'_c$ have the same size as the key size. +Additionally, the 32 byte values $W_p, \sigma_W$ are transmitted. +\\\\ +In the refresh protocol the only difference is an additional hash ($h_{C_0}, h_{C_1}$ instead of only $h_C$) sent in the commit phase. +Depending on the hash size another 32 byte (or 64 byte) value is transmitted. + +\begin{table}[ht] + \centering + \colorlet{BFH-table}{BFH-MediumBlue!10} + \colorlet{BFH-tablehead}{BFH-MediumBlue!50} + \setupBfhTabular + \begin{tabular}{lccr} + \rowcolor{BFH-tablehead} + \textbf{Signature Scheme} & \textbf{Bandwidth used} & \textbf{Factor} & \textbf{1M coins}\\\hline + CS 256 bits & 356 bytes & 1x & 324 MB\\\hline + RSA 1024 bit & 448 bytes & 1.3x & 448 MB \\\hline + RSA 2048 bit & 832 bytes & 2.5x & 832 MB\\\hline + RSA 3072 bit & 1216 bytes & 3.75x & 1216 MB\\\hline + RSA 4096 bit & 1600 bytes & 4.9x & 1600 MB\\\hline + \end{tabular} + \caption{Bandwidth comparison withdrawal} + \label{tab:comp-band-withd} +\end{table} + +\subsection{Latency} +This section the notion of \acl{RTT} (see \cite{geeks:rtt}) is used. +There are many factors that influence the measurement of a \acl{RTT}. +Following factors can bring huge changes in the value of \ac{RTT}s. +\begin{itemize} + \item Distance + \item Transmission medium + \item Network hops + \item Traffic levels + \item Server response time +\end{itemize} +All of these factors will vary in reality and are independent of the scheme.\\ +The important comparison here is the number of \ac{RT}s as in table \ref{tab:comp-rtt}. +\begin{table}[ht] + \centering + \colorlet{BFH-table}{BFH-MediumBlue!10} + \colorlet{BFH-tablehead}{BFH-MediumBlue!50} + \setupBfhTabular + \begin{tabular}{lc} + \rowcolor{BFH-tablehead} + \textbf{Signature Scheme} & \textbf{Number of RTs} \\\hline + RSA Blind Signatures & 1\\\hline + Clause Blind Schnorr Signatures & 2\\\hline + \end{tabular} + \caption{Comparison of Round-Trips} + \label{tab:comp-rtt} +\end{table} + +While creating \gls{RSABS} have one \ac{RT}, \gls{CSBS} need an additional \ac{RT} for requesting the public $R_0, R_1$. +This means that the time spend for withdrawing is almost \textbf{doubled} (the $ R $ request doesn't have any persistence and therefore requires less time) in comparison to RSA. + +A coin should not be spent immediately after withdrawal or refresh. +Otherwise, an adversary could deanonymize a customer by correlating the timestamps. +The additional \ac{RT} is a drawback of \gls{CSBS} compared to RSA, but negligible due to the fact that a coin must not be spent immediately. + +\section{Security Assumptions} +\label{sec:disc-sec-assumptions} +This section discusses the differences regarding the security assumptions of the schemes. +This section should not explain nor analyze the security assumptions, instead the section focuses on explaining what these assumptions mean and what should be kept in mind about them. +Read section \ref{sec:sign-schemes} and it's references for more information on the assumptions. + +RSA's security assumptions are well known since quite a long time and a lot of research is done. +Despite being a lot of attacks \cite{ganapati:rsactftool} \cite{perez:stoprsa}, RSA is still considered a secure scheme after decades.\\ +For Schnorr Signatures the \acl{DLP} (see \autoref{sec:dlp}) needs to be hard. +Also the \ac{DLP} is well-known and is being researched since decades.\\ +However, with Blind Schorr Signatures an additional assumption needs to hold; the \ac{ROS} problem. +Compared to the other assumptions, \ac{ROS} is relatively new and still a recent research topic. +A recent paper from 2020 on the (in)security of ROS \cite{cryptoeprint:2020:945} broke many schemes relying on ROS being hard, including Schnorr Blind signatures. +The paper on which we rely on (updated in 2021) with the Clause Blind Schnorr Signature Scheme \cite{cryptoeprint:2019:877} is considered secure at the time of writing.\\ + +\section{Risk} +\label{sec:disc-risk} +As introduced in \autoref{sec:disc-sec-assumptions}, \gls{CSBS} rely on an additional assumption currently being researched. +Compared to other schemes, the chosen \gls{CSBS} are very new (published in 2019, updated in 2021). +While every scheme could potentially be broken, older ones already went through a lot of research and their assumptions are well-known. +Therefore, the risk that a vulnerability in \gls{CSBS} will be discovered is probably higher than a newly discovered vulnerability breaking RSA. + +Unpredictability of $ r $ is a key aspect of the signature creation process of \gls{CSBS}. +The redesigned Taler protocols solve this by persisting the nonce and denomination key (described in \autoref{sec:withdraw-protocol-impl}) and checking for reuse of this combination before signature creation. +If this process is malfunctioning (broken implementation, faulty database) or can be circumvented in any way, recovery of a denomination private key is possible. + +An exchange operator can still consider using \gls{CSBS} as denomination scheme, as there are multiple benefits (see \autoref{sec:disc-perf-comp}). +The financial loss in the worst case can be calculated and capped by the validity of a denomination key. +If a vulnerability in the \gls{CSBS} would be detected, an exchange operator could revoke the corresponding denomination keys and change the scheme to \gls{RSABS}. +The wallets can then follow the refund protocol to get the money back. + +\section{Comparison Conclusion} +\label{sec:disc-comp-conclusion} +A detailed comparison of the two blind signature schemes was made. +This last section interprets the results and concludes the comparison. + +\gls{CSBS} on \gls{25519} provide the same security level as \gls{RSABS} with 3072 bit key sizes. +The implementation of \gls{CSBS} is the clear winner in all performance comparisons with RSA 3072 bits. + +1024 bit RSA is faster than the \gls{CSBS} implementation in certain operations. +The \gls{CSBS} implementation still offers better performance for wallets with less CPU power and provides a much higher level of security (comparable to RSA 3072). +As further comparisons show, RSA scales very bad the larger the keys get and \gls{CSBS} performs much better overall. + +As discussed in the risk section \ref{sec:disc-risk}, \gls{CSBS} have an additional security assumption, which is still a recent research topic. +\gls{CSBS} provide various benefits and the risk can be calculated and capped. +An exchange operator who is aware of the discussed risk can use \gls{CSBS} safely. +\gls{CSBS} are best suited for denominations with low value, where many coins are being withdrawn/refreshed. diff --git a/doc/cs/content/6_conclusion.tex b/doc/cs/content/6_conclusion.tex new file mode 100644 index 000000000..8ee12fa5e --- /dev/null +++ b/doc/cs/content/6_conclusion.tex @@ -0,0 +1,70 @@ +\chapter{Conclusion} +This section provides a summary of this work, presents the results and gives an outlook on future work. + +\section{Summary} +In the beginning of the project good knowledge on the current state in research about Blind Schnorr signatures was needed. +Therefore, various papers were read and then the paper "Blind Schnorr Signatures and Signed ElGamal Encryption in the Algebraic Group Model" \cite{cryptoeprint:2019:877} was chosen as basis for the redesign of the Taler protocols.\\ +The next step was to analyze the current Taler protocols and understand the required properties including \textit{\gls{abort-idempotency}}.\\ +With the gathered knowledge (see chapter \ref{chap:preliminaries}) the Taler protocols were redesigned to support \gls{CSBS} (see chapter \ref{chap:design}). +These redesigned protocols were then further specified (chapter \ref{chap:spec}) and then implemented (chapter \ref{chap:implement}). +The implementation includes the main protocols, key management, cryptographic utilities in Taler and the \gls{CSBS} cryptographic routines.\\ +The \gls{CSBS} scheme was analyzed and compared in detail to the RSA Blind Signature scheme (see \ref{chap:disc}). + + +\section{Results} +The thesis provides several results to add support for Schnorr's blind signature in Taler, including: +\begin{itemize} + \item Redesigned Taler protocols to support \gls{CSBS} + \item Implementation of cryptographic routines + \item Implementation of Taler protocols in Exchange + \begin{itemize} + \item Key Management and security module + \item Cryptographic utilities + \item Withdraw protocol + \item Deposit protocol + \end{itemize} + \item Comparison and Analysis + \begin{itemize} + \item Performance (speed, space, latency \& bandwidth) + \item Security + \item Scheme Comparison + \end{itemize} + \item Fixing a minor security issue in Taler's current protocols +\end{itemize} +The code is tested, and those tests are integrated in the existing testing framework. +Benchmarks are added for the cryptographic routines and the security module. + +\section{Future Work} +Like in any other project, there is always more that could be done. +This section provides an outlook on what can be done in future work. + +\begin{itemize} + \item Implement wallet + \item Implementing remaining \gls{CSBS} protocols (refresh, tipping protocol, refund etc.) + \item Implementing merchant + \item Security audit of CS implementation + \item Find a solution for withdraw loophole + \item Evaluating \& implementing \gls{CSBS} on other curves +\end{itemize} + +There are some remaining protocols to implement, which were out of scope for this thesis. +To run \gls{CSBS} in production, these protocols have to be implemented too. +Further, the merchant needs to support \gls{CSBS} too. +The merchant implementation can be done fast, as the merchant only verifies denomination signatures in most cases. \\ +Currently, the exchange runs both security modules, the \gls{CSBS} and the RSA security modules. +To reduce unnecessary overhead, this should be changed so that only one security has to be running. +To run \gls{CSBS} in production a security audit from an external company is recommended (as done for other parts in the exchange, see \cite{codeblau:taler-audit}). +A security audit should always be made when implementing big changes like these.\\ +As mentioned in the scope section, the optional goal to find and implement a good solution for the withdraw loophole was dropped. +This was due to the scope shift and because the analysis of the problem showed that finding a good solution needs more research and is a whole project in itself (see \ref{sec:scope} for more information).\\ +Furthermore, \gls{CSBS} could be implemented on other curves. +For example Curve448 \cite{cryptoeprint:2015:625} could be used, as it provides 224 bits of security, whereas \gls{25519} \cite{bern:curve25519} provides about 128 bits of security. +Curve secp256k1 could further improve \gls{CSBS} performance. +While providing support for Curve448 should not be problematic, a potential implementation for secp256k1 needs further analysis (see \cite{bernlange:safecurves} and \cite{bip:schnorr-bitc} for more information). + +\section{Personal Conclusion} +This thesis includes understanding, analyzing, integrating and implementing a recent academic paper \cite{cryptoeprint:2019:877} containing a modern cryptographic scheme. +Furthermore, the implementation is done in Taler, an intuitive and modern solution for a social responsible payment system with high ethical standards. +Although there was a lot of work, we enjoyed working on such a modern and very interesting topic. +Especially the first successful signature verification and the signature scheme performance benchmarks motivated us to push the implementation and integration into Taler forward.\\ +We are happy to provide an implementation of a modern scheme and making it available as free software. diff --git a/doc/cs/content/appendix.tex b/doc/cs/content/appendix.tex new file mode 100644 index 000000000..137a29ba7 --- /dev/null +++ b/doc/cs/content/appendix.tex @@ -0,0 +1,677 @@ +\appendix + +\chapter{Installation} +These installation instructions are meant to run the code developed within this thesis for development- and review-purposes. +For a comprehensive installation instruction follow the Taler documentation +\cite{taler-documentation}. + +\begin{bfhNoteBox} + These instructions are used and tested on Ubuntu 21.10. +\end{bfhNoteBox} + +\section{Dependencies and Setup} +The following dependencies need to be installed for GNUnet and Taler Exchange: +\setupLinuxPrompt{student} +\begin{ubuntu} +sudo apt update +sudo apt install git curl build-essential gcc automake make \ texinfo autoconf uncrustify libtool pkgconf gettext gnutls-bin \ libcurl4-gnutls-dev libgcrypt20-dev libidn2-dev libjansson-dev \ libnss3-dev sqlite pipenv libltdl-dev libsodium-dev libpq-dev \ autopoint libunistring-dev libextractor-dev libpng-dev \ libpulse-dev libsqlite3-dev recutils python3-jinja2 sqlite yapf3 \ postgresql libpq-dev wget libmicrohttpd-dev +export LD\_LIBRARY\_PATH=/usr/local/lib +\end{ubuntu} + +\begin{bfhBox}[BFH-MediumBlue]{Install in a container} +The installation can also be done in a docker or podman container with the ubuntu:21.10 image: +\setupLinuxPrompt{student} +\begin{ubuntu} +podman run -it --name talertest ubuntu:21.10 +\end{ubuntu} +\end{bfhBox} + +\section{Install GNUnet Core} +GNUnet core is both a dependency of the Taler exchange and where we implemented the Clause Blind Schnorr Signature Scheme. +\setupLinuxPrompt{student} +\begin{ubuntu} +git clone https://git.gnunet.org/gnunet.git +cd gnunet +./bootstrap +./configure --enable-benchmarks --prefix=/usr/local +make +make install +make check # Run optionally to verify installation and run tests +\end{ubuntu} + +To run benchmarks run: +\setupLinuxPrompt{student} +\begin{ubuntu} +./src/util/perf_crypto_cs +./src/util/perf_crypto_rsa +\end{ubuntu} + +\section{Install Taler Exchange} +\begin{bfhWarnBox} +Ensure that the current user has privileges in postgresql. +One possible way to do this is:\\ +(where [user] has to be replaced with the name of the system user running the tests) +\setupLinuxPrompt{student} +\begin{ubuntu} +service postgresql start +sudo su +su - postgres +psql +CREATE ROLE [user] LOGIN SUPERUSER; +CREATE DATABASE [user] OWNER [user]; +exit +\end{ubuntu} +\end{bfhWarnBox} + +The Taler exchange can be installed as followed: +\setupLinuxPrompt{student} +\begin{ubuntu} +service postgresql start +createdb talercheck +git clone https://git.taler.net/exchange.git +cd exchange +./bootstrap +./configure --with-gnunet=/usr/local --prefix=/usr/local +./make +./make install +./make check # Run optionally to verify installation and run tests +\end{ubuntu} + +To execute the security module benchmarks run: +\setupLinuxPrompt{student} +\begin{ubuntu} +cd src/util +./test_helper_cs +./test_helper_rsa +\end{ubuntu} + +\chapter{Performance Measurements} +\label{chap:app-perf} + +\section{AMD Ryzen 7 PRO 5850U (Notebook)} +Detailed comparison of each operation can be found in table \ref{tab:comp-sign-amd-ryzen-7}. +\begin{bfhBox}[BFH-MediumBlue]{Setup} + CPU: 8-core AMD Ryzen 7 PRO 5850U \\ + Architecture: amd64 \\ + OS: Ubuntu 21.10 Linux 5.13.0-25-generic \#26-Ubuntu SMP Fri Jan 7 15:48:31 UTC 2022 x86\_64 x86\_64 x86\_64 GNU/Linux \\ + libsodium:amd64 version: 1.0.18-1build1 \\ + libgcrypt:amd64 version: 1.8.7-5ubuntu2 +\end{bfhBox} + +\begin{table}[h] + \centering + \colorlet{BFH-table}{BFH-MediumBlue!10} + \colorlet{BFH-tablehead}{BFH-MediumBlue!50} + \setupBfhTabular + \begin{tabular}{llr} + \rowcolor{BFH-tablehead} + \textbf{Signature Scheme} & \textbf{Operation} & \textbf{Speed} \\\hline + CS & 10x key generation & 0.204 ms \\\hline + RSA 1024 bit & 10x key generation & 126 ms \\\hline + RSA 2048 bit & 10x key generation & 903 ms \\\hline + RSA 3072 bit & 10x key generation & 2684 ms \\\hline + RSA 4096 bit & 10x key generation & 10 000 ms \\\hline + \hline + CS & 10x r0, r1 derive and R1,R2 calculation & 0.444 ms \\\hline + CS & 10x derivation of blinding secrets & 0.094 ms \\\hline + CS & 10x blinding & 3.332 ms \\\hline + RSA 1024 bit & 10x blinding & 1.282 ms \\\hline + RSA 2048 bit & 10x blinding & 3.012 ms \\\hline + RSA 3072 bit & 10x blinding & 5 ms \\\hline + RSA 4096 bit & 10x blinding & 9 ms \\\hline + \hline + CS & 10x signing & 0.077 ms \\\hline + RSA 1024 bit & 10x signing & 7 ms \\\hline + RSA 2048 bit & 10x signing & 34 ms \\\hline + RSA 3072 bit & 10x signing & 86 ms \\\hline + RSA 4096 bit & 10x signing & 183 ms \\\hline + \hline + CS & 10x unblinding & 0.001 ms \\\hline + RSA 1024 bit & 10x unblinding & 2.991 ms \\\hline + RSA 2048 bit & 10x unblinding & 10 ms \\\hline + RSA 3072 bit & 10x unblinding & 24 ms \\\hline + RSA 4096 bit & 10x unblinding & 44 ms \\\hline + \hline + CS & 10x verifying & 1.358 ms \\\hline + RSA 1024 bit & 10x verifying & 0.876 ms \\\hline + RSA 2048 bit & 10x verifying & 1.836 ms \\\hline + RSA 3072 bit & 10x verifying & 3.075 ms \\\hline + RSA 4096 bit & 10x verifying & 5 ms \\\hline + \end{tabular} + \caption{Comparison on AMD Ryzen 7} + \label{tab:comp-sign-amd-ryzen-7} +\end{table} + +\section{Intel(R) Core(TM) i7-8565U} +Detailed comparison of each operation can be found in table \ref{tab:comp-sign-intel-i7}. +\begin{bfhBox}[BFH-MediumBlue]{Setup} + CPU: 8-core Intel(R) Core(TM) i7-8565U CPU @ 1.80GHz \\ + Architecture: amd64 \\ + OS: Ubuntu 21.10 Linux 5.13.0-25-generic \#26-Ubuntu SMP Fri Jan 7 15:48:31 UTC 2022 x86\_64 x86\_64 x86\_64 GNU/Linux \\ + libsodium:amd64 version: 1.0.18-1build1 \\ + libgcrypt:amd64 version: 1.8.7-5ubuntu2 +\end{bfhBox} + +\begin{table}[ht] + \centering + \colorlet{BFH-table}{BFH-MediumBlue!10} + \colorlet{BFH-tablehead}{BFH-MediumBlue!50} + \setupBfhTabular + \begin{tabular}{llr} + \rowcolor{BFH-tablehead} + \textbf{Signature Scheme} & \textbf{Operation} & \textbf{Speed} \\\hline + CS & 10x key generation & 1.05 ms \\\hline + RSA 1024 bit & 10x key generation & 189 ms \\\hline + RSA 2048 bit & 10x key generation & 1555 ms \\\hline + RSA 3072 bit & 10x key generation & 5000 ms \\\hline + RSA 4096 bit & 10x key generation & 11 000 ms \\\hline + \hline + CS & 10x r0, r1 derive and R1,R2 calculation & 2.261 ms \\\hline + CS & 10x derivation of blinding secrets & 0.521 ms \\\hline + CS & 10x blinding & 13 ms \\\hline + RSA 1024 bit & 10x blinding & 2.6 ms \\\hline + RSA 2048 bit & 10x blinding & 4.12 ms \\\hline + RSA 3072 bit & 10x blinding & 7 ms \\\hline + RSA 4096 bit & 10x blinding & 11 ms \\\hline + \hline + CS & 10x signing & 0.405 ms \\\hline + RSA 1024 bit & 10x signing & 9 ms \\\hline + RSA 2048 bit & 10x signing & 44 ms \\\hline + RSA 3072 bit & 10x signing & 108 ms \\\hline + RSA 4096 bit & 10x signing & 216 ms \\\hline + \hline + CS & 10x unblinding & 0.005 ms \\\hline + RSA 1024 bit & 10x unblinding & 3.353 ms \\\hline + RSA 2048 bit & 10x unblinding & 12 ms \\\hline + RSA 3072 bit & 10x unblinding & 27 ms \\\hline + RSA 4096 bit & 10x unblinding & 47 ms \\\hline + \hline + CS & 10x verifying & 4.413 ms \\\hline + RSA 1024 bit & 10x verifying & 1.202 ms \\\hline + RSA 2048 bit & 10x verifying & 2.304 ms \\\hline + RSA 3072 bit & 10x verifying & 4.094 ms \\\hline + RSA 4096 bit & 10x verifying & 6 ms \\\hline + \end{tabular} + \caption{Comparison on Intel(R) Core(TM) i7-8565U} + \label{tab:comp-sign-intel-i7} +\end{table} + +\section{AMD Ryzen Threadripper 1950X 16-Core Processor} +Detailed comparison of each operation can be found in table \ref{tab:comp-sign-amd-threadripper}. +\begin{bfhBox}[BFH-MediumBlue]{Setup} + CPU: AMD Ryzen Threadripper 1950X 16-Core Processor \\ + Architecture: amd64 \\ + OS: Linux 5.13.0-trunk-amd64 \#1 SMP Debian 5.13.12-1~exp1 + (2021-08-20) x86\_64 GNU/Linux \\ + libsodium:amd64 version: 1.9.4-5 \\ + libgcrypt:amd64 version: 1.0.18-1 +\end{bfhBox} + +\begin{table}[ht] + \centering + \colorlet{BFH-table}{BFH-MediumBlue!10} + \colorlet{BFH-tablehead}{BFH-MediumBlue!50} + \setupBfhTabular + \begin{tabular}{llr} + \rowcolor{BFH-tablehead} + \textbf{Signature Scheme} & \textbf{Operation} & \textbf{Speed} \\\hline + CS & 10x key generation & 0.442 ms \\\hline + RSA 1024 bit & 10x key generation & 145 ms \\\hline + RSA 2048 bit & 10x key generation & 1167 ms \\\hline + RSA 3072 bit & 10x key generation & 6000 ms \\\hline + RSA 4096 bit & 10x key generation & 11 000 ms \\\hline + \hline + CS & 10x r0, r1 derive and R1,R2 calculation & 1.043 ms \\\hline + CS & 10x derivation of blinding secrets & 0.242 ms \\\hline + CS & 10x blinding & 7 ms \\\hline + RSA 1024 bit & 10x blinding & 2.258 ms \\\hline + RSA 2048 bit & 10x blinding & 4.744 ms \\\hline + RSA 3072 bit & 10x blinding & 9 ms \\\hline + RSA 4096 bit & 10x blinding & 14 ms \\\hline + \hline + CS & 10x signing & 0.270 ms \\\hline + RSA 1024 bit & 10x signing & 10 ms \\\hline + RSA 2048 bit & 10x signing & 47 ms \\\hline + RSA 3072 bit & 10x signing & 119 ms \\\hline + RSA 4096 bit & 10x signing & 248 ms \\\hline + \hline + CS & 10x unblinding & 0.003 ms \\\hline + RSA 1024 bit & 10x unblinding & 4.086 ms \\\hline + RSA 2048 bit & 10x unblinding & 14 ms \\\hline + RSA 3072 bit & 10x unblinding & 34 ms \\\hline + RSA 4096 bit & 10x unblinding & 60 ms \\\hline + \hline + CS & 10x verifying & 2.392 ms \\\hline + RSA 1024 bit & 10x verifying & 1.137 ms \\\hline + RSA 2048 bit & 10x verifying & 2.797 ms \\\hline + RSA 3072 bit & 10x verifying & 5 ms \\\hline + RSA 4096 bit & 10x verifying & 7 ms \\\hline + \end{tabular} + \caption{Comparison on AMD Ryzen Threadripper 1950X} + \label{tab:comp-sign-amd-threadripper} +\end{table} + +\section{Intel(R) Xeon(R) CPU E5-2630} +Detailed comparison of each operation can be found in table \ref{tab:comp-sign-intel-xeon}. +\begin{bfhBox}[BFH-MediumBlue]{Setup} + CPU: Intel(R) Xeon(R) CPU E5-2630 0 @ 2.30GHz \\ + Architecture: amd64 \\ + OS: Linux 5.10.0-8-amd64 \#1 SMP Debian 5.10.46-4 (2021-08-03) x86\_64\\ + libsodium:amd64 version: 1.0.18-1\\ + libgcrypt:amd64 version: 1.8.7-6 +\end{bfhBox} + +\begin{table}[ht] + \centering + \colorlet{BFH-table}{BFH-MediumBlue!10} + \colorlet{BFH-tablehead}{BFH-MediumBlue!50} + \setupBfhTabular + \begin{tabular}{llr} + \rowcolor{BFH-tablehead} + \textbf{Signature Scheme} & \textbf{Operation} & \textbf{Speed} \\\hline + CS & 10x key generation & 0.606 ms \\\hline + RSA 1024 bit & 10x key generation & 329 ms \\\hline + RSA 2048 bit & 10x key generation & 3210 ms \\\hline + RSA 3072 bit & 10x key generation & 12 000 ms \\\hline + RSA 4096 bit & 10x key generation & 40 000 ms \\\hline + \hline + CS & 10x r0, r1 derive and R1,R2 calculation & 1.527 ms \\\hline + CS & 10x derivation of blinding secrets & 0.329 ms \\\hline + CS & 10x blinding & 9 ms \\\hline + RSA 1024 bit & 10x blinding & 4.026 ms \\\hline + RSA 2048 bit & 10x blinding & 9 ms \\\hline + RSA 3072 bit & 10x blinding & 18 ms \\\hline + RSA 4096 bit & 10x blinding & 27 ms \\\hline + \hline + CS & 10x signing & 0.274 ms \\\hline + RSA 1024 bit & 10x signing & 21 ms \\\hline + RSA 2048 bit & 10x signing & 96 ms \\\hline + RSA 3072 bit & 10x signing & 237 ms \\\hline + RSA 4096 bit & 10x signing & 482 ms \\\hline + \hline + CS & 10x unblinding & 0.004 ms \\\hline + RSA 1024 bit & 10x unblinding & 7 ms \\\hline + RSA 2048 bit & 10x unblinding & 25 ms \\\hline + RSA 3072 bit & 10x unblinding & 58 ms \\\hline + RSA 4096 bit & 10x unblinding & 99 ms \\\hline + \hline + CS & 10x verifying & 4.334 ms \\\hline + RSA 1024 bit & 10x verifying & 2.190 ms \\\hline + RSA 2048 bit & 10x verifying & 5 ms \\\hline + RSA 3072 bit & 10x verifying & 11 ms \\\hline + RSA 4096 bit & 10x verifying & 14 ms \\\hline + \end{tabular} + \caption{Comparison on Intel(R) Xeon(R) CPU E5-2630} + \label{tab:comp-sign-intel-xeon} +\end{table} + +\section{Intel(R) Pentium(R) 3558U} +Detailed comparison of each operation can be found in table \ref{tab:comp-sign-intel-pentium}. +\begin{bfhBox}[BFH-MediumBlue]{Setup} + CPU: Intel(R) Pentium(R) 3558U @ 1.70GHz \\ + Architecture: amd64 \\ + OS: Linux 5.10.0-8-amd64 \#1 SMP Debian 5.10.46-3 (2021-07-28) x86\_64\\ + libsodium:amd64 version: 1.0.18-1\\ + libgcrypt:amd64 version: 1.8.7-6 +\end{bfhBox} + +\begin{table}[ht] + \centering + \colorlet{BFH-table}{BFH-MediumBlue!10} + \colorlet{BFH-tablehead}{BFH-MediumBlue!50} + \setupBfhTabular + \begin{tabular}{llr} + \rowcolor{BFH-tablehead} + \textbf{Signature Scheme} & \textbf{Operation} & \textbf{Speed} \\\hline + CS & 10x key generation & 0.53 ms \\\hline + RSA 1024 bit & 10x key generation & 524 ms \\\hline + RSA 2048 bit & 10x key generation & 3357 ms \\\hline + RSA 3072 bit & 10x key generation & 15 000 ms \\\hline + RSA 4096 bit & 10x key generation & 37 000 ms \\\hline + \hline + CS & 10x r0, r1 derive and R1,R2 calculation & 1.375 ms \\\hline + CS & 10x derivation of blinding secrets & 0.349 ms \\\hline + CS & 10x blinding & 8 ms \\\hline + RSA 1024 bit & 10x blinding & 4.86 ms \\\hline + RSA 2048 bit & 10x blinding & 11 ms \\\hline + RSA 3072 bit & 10x blinding & 19 ms \\\hline + RSA 4096 bit & 10x blinding & 31 ms \\\hline + \hline + CS & 10x signing & 0.283 ms \\\hline + RSA 1024 bit & 10x signing & 26 ms \\\hline + RSA 2048 bit & 10x signing & 117 ms \\\hline + RSA 3072 bit & 10x signing & 292 ms \\\hline + RSA 4096 bit & 10x signing & 571 ms \\\hline + \hline + CS & 10x unblinding & 0.003 ms \\\hline + RSA 1024 bit & 10x unblinding & 8 ms \\\hline + RSA 2048 bit & 10x unblinding & 30 ms \\\hline + RSA 3072 bit & 10x unblinding & 67 ms \\\hline + RSA 4096 bit & 10x unblinding & 111 ms \\\hline + \hline + CS & 10x verifying & 3.769 ms \\\hline + RSA 1024 bit & 10x verifying & 2.616 ms \\\hline + RSA 2048 bit & 10x verifying & 6 ms \\\hline + RSA 3072 bit & 10x verifying & 11 ms \\\hline + RSA 4096 bit & 10x verifying & 17 ms \\\hline + \end{tabular} + \caption{Comparison on Intel(R) Pentium(R) 3558U} + \label{tab:comp-sign-intel-pentium} +\end{table} + + +\section{arm64} +Detailed comparison of each operation can be found in table \ref{tab:comp-sign-arm64}. +\begin{bfhBox}[BFH-MediumBlue]{Setup} + CPU: 8-core arm64\\ + Architecture: ARM64 \\ + OS: Linux ten64 5.11.0-31-generic \#33+testsfp1 SMP Mon Aug 23 16:07:41 UTC 2021 aarch64 aarch64 aarch64 GNU/Linux \\ + libsodium:arm64 version: 1.8.7-2ubuntu2.1 \\ + libgcrypt:arm64 version: 1.0.18-1 +\end{bfhBox} + +\begin{table}[ht] + \centering + \colorlet{BFH-table}{BFH-MediumBlue!10} + \colorlet{BFH-tablehead}{BFH-MediumBlue!50} + \setupBfhTabular + \begin{tabular}{llr} + \rowcolor{BFH-tablehead} + \textbf{Signature Scheme} & \textbf{Operation} & \textbf{Speed} \\\hline + CS & 10x key generation & 2.896 ms \\\hline + RSA 1024 bit & 10x key generation & 839 ms \\\hline + RSA 2048 bit & 10x key generation & 8000 ms \\\hline + RSA 3072 bit & 10x key generation & 17 000 ms \\\hline + RSA 4096 bit & 10x key generation & 82 000 ms \\\hline + \hline + CS & 10x r0, r1 derive and R1,R2 calculation & 6 ms \\\hline + CS & 10x derivation of blinding secrets & 0.713 ms \\\hline + CS & 10x blinding & 23 ms \\\hline + RSA 1024 bit & 10x blinding & 11 ms \\\hline + RSA 2048 bit & 10x blinding & 28 ms \\\hline + RSA 3072 bit & 10x blinding & 51 ms \\\hline + RSA 4096 bit & 10x blinding & 81 ms \\\hline + \hline + CS & 10x signing & 0.321 ms \\\hline + RSA 1024 bit & 10x signing & 57 ms \\\hline + RSA 2048 bit & 10x signing & 263 ms \\\hline + RSA 3072 bit & 10x signing & 685 ms \\\hline + RSA 4096 bit & 10x signing & 1385 ms \\\hline + \hline + CS & 10x unblinding & 0.006 ms \\\hline + RSA 1024 bit & 10x unblinding & 23 ms \\\hline + RSA 2048 bit & 10x unblinding & 79 ms \\\hline + RSA 3072 bit & 10x unblinding & 171 ms \\\hline + RSA 4096 bit & 10x unblinding & 296 ms \\\hline + \hline + CS & 10x verifying & 11ms \\\hline + RSA 1024 bit & 10x verifying & 5 ms \\\hline + RSA 2048 bit & 10x verifying & 15 ms \\\hline + RSA 3072 bit & 10x verifying & 27 ms \\\hline + RSA 4096 bit & 10x verifying & 45 ms \\\hline + \end{tabular} + \caption{Comparison on arm64} + \label{tab:comp-sign-arm64} +\end{table} + +\section{AMD Ryzen Embedded R1606G} +Detailed comparison of each operation can be found in table \ref{tab:comp-sign-amd-embedded}. +\begin{bfhBox}[BFH-MediumBlue]{Setup} + CPU: 4-core AMD Ryzen Embedded R1606G with Radeon Vega Gfx\\ + Architecture: amd64 \\ + OS: Linux computer 5.13.0-25-generic \#26-Ubuntu SMP Fri Jan 7 15:48:31 UTC 2022 x86\_64 x86\_64 x86\_64 GNU/Linux\\ + libsodium:amd64 version: 1.8.7-5ubuntu2 \\ + libgcrypt:amd64 version: 1.0.18-1build1 +\end{bfhBox} + +\begin{table}[ht] + \centering + \colorlet{BFH-table}{BFH-MediumBlue!10} + \colorlet{BFH-tablehead}{BFH-MediumBlue!50} + \setupBfhTabular + \begin{tabular}{llr} + \rowcolor{BFH-tablehead} + \textbf{Signature Scheme} & \textbf{Operation} & \textbf{Speed} \\\hline + CS & 10x key generation & 2.373 ms \\\hline + RSA 1024 bit & 10x key generation & 184 ms \\\hline + RSA 2048 bit & 10x key generation & 2132 ms \\\hline + RSA 3072 bit & 10x key generation & 8000 ms \\\hline + RSA 4096 bit & 10x key generation & 21 000 ms \\\hline + \hline + CS & 10x r0, r1 derive and R1,R2 calculation & 1.09 ms \\\hline + CS & 10x derivation of blinding secrets & 0.43 ms \\\hline + CS & 10x blinding & 6 ms \\\hline + RSA 1024 bit & 10x blinding & 3.886 ms \\\hline + RSA 2048 bit & 10x blinding & 7 ms \\\hline + RSA 3072 bit & 10x blinding & 14 ms \\\hline + RSA 4096 bit & 10x blinding & 23 ms \\\hline + \hline + CS & 10x signing & 0.379 ms \\\hline + RSA 1024 bit & 10x signing & 15 ms \\\hline + RSA 2048 bit & 10x signing & 71 ms \\\hline + RSA 3072 bit & 10x signing & 177 ms \\\hline + RSA 4096 bit & 10x signing & 357 ms \\\hline + \hline + CS & 10x unblinding & 0.001 ms \\\hline + RSA 1024 bit & 10x unblinding & 6 ms \\\hline + RSA 2048 bit & 10x unblinding & 24 ms \\\hline + RSA 3072 bit & 10x unblinding & 53 ms \\\hline + RSA 4096 bit & 10x unblinding & 93 ms \\\hline + \hline + CS & 10x verifying & 2.610 ms \\\hline + RSA 1024 bit & 10x verifying & 2.303 ms \\\hline + RSA 2048 bit & 10x verifying & 4.386 ms \\\hline + RSA 3072 bit & 10x verifying & 7 ms \\\hline + RSA 4096 bit & 10x verifying & 11 ms \\\hline + \end{tabular} + \caption{Comparison on AMD Ryzen Embedded R1606G} + \label{tab:comp-sign-amd-embedded} +\end{table} + +\section{risc64} +Detailed comparison of each operation can be found in table \ref{tab:comp-sign-risc64}. +\begin{bfhBox}[BFH-MediumBlue]{Setup} + CPU: 4-core risc64 processor\\ + OS: Linux risc-v-unleashed-000 5.11.0-1022-generic \#23~20.04.1-Ubuntu SMP Thu Oct 21 10:16:27 UTC 2021 riscv64 riscv64 riscv64 GNU/Linux\\ + libsodium:riscv64 version: 1.8.7-5ubuntu2 \\ + libgcrypt:riscv64 version: 1.0.18-1build1 +\end{bfhBox} + +\begin{table}[ht] + \centering + \colorlet{BFH-table}{BFH-MediumBlue!10} + \colorlet{BFH-tablehead}{BFH-MediumBlue!50} + \setupBfhTabular + \begin{tabular}{llr} + \rowcolor{BFH-tablehead} + \textbf{Signature Scheme} & \textbf{Operation} & \textbf{Speed} \\\hline + CS & 10x key generation & 4.144 ms \\\hline + RSA 1024 bit & 10x key generation & 2923 ms \\\hline + RSA 2048 bit & 10x key generation & 28 000 ms \\\hline + RSA 3072 bit & 10x key generation & 174 000 ms \\\hline + RSA 4096 bit & 10x key generation & 600 000 ms \\\hline + \hline + CS & 10x r0, r1 derive and R1,R2 calculation & 10 ms \\\hline + CS & 10x derivation of blinding secrets & 2.514 ms \\\hline + CS & 10x blinding & 72 ms \\\hline + RSA 1024 bit & 10x blinding & 37 ms \\\hline + RSA 2048 bit & 10x blinding & 93 ms \\\hline + RSA 3072 bit & 10x blinding & 170 ms \\\hline + RSA 4096 bit & 10x blinding & 277 ms \\\hline + \hline + CS & 10x signing & 1.697 ms \\\hline + RSA 1024 bit & 10x signing & 215 ms \\\hline + RSA 2048 bit & 10x signing & 1040 ms \\\hline + RSA 3072 bit & 10x signing & 2883 ms \\\hline + RSA 4096 bit & 10x signing & 5000 ms \\\hline + \hline + CS & 10x unblinding & 0.022 ms \\\hline + RSA 1024 bit & 10x unblinding & 62 ms \\\hline + RSA 2048 bit & 10x unblinding & 150 ms \\\hline + RSA 3072 bit & 10x unblinding & 275 ms \\\hline + RSA 4096 bit & 10x unblinding & 431 ms \\\hline + \hline + CS & 10x verifying & 29 ms \\\hline + RSA 1024 bit & 10x verifying & 22 ms \\\hline + RSA 2048 bit & 10x verifying & 54 ms \\\hline + RSA 3072 bit & 10x verifying & 99 ms \\\hline + RSA 4096 bit & 10x verifying & 166 ms \\\hline + \end{tabular} + \caption{Comparison on risc64} + \label{tab:comp-sign-risc64} +\end{table} + +\section{POWER9} +Detailed comparison of each operation can be found in table \ref{tab:comp-sign-POWER9}. +\begin{bfhBox}[BFH-MediumBlue]{Setup} + CPU: 176-core power9\\ + architecture: pp64le \\ + OS: Linux power9 5.11.0-34-generic \#36-Ubuntu SMP Thu Aug 26 19:19:54 UTC 2021 ppc64le ppc64le ppc64le GNU/Linux \\ + libsodium:a::ppc64el version: 1.8.7-2ubuntu2.1 \\ + libgcrypt::ppc64el version: 1.0.18-1 +\end{bfhBox} + +\begin{table}[ht] + \centering + \colorlet{BFH-table}{BFH-MediumBlue!10} + \colorlet{BFH-tablehead}{BFH-MediumBlue!50} + \setupBfhTabular + \begin{tabular}{llr} + \rowcolor{BFH-tablehead} + \textbf{Signature Scheme} & \textbf{Operation} & \textbf{Speed} \\\hline + CS & 10x key generation & 0.275 ms \\\hline + RSA 1024 bit & 10x key generation & 290 ms \\\hline + RSA 2048 bit & 10x key generation & 3743 ms \\\hline + RSA 3072 bit & 10x key generation & 15 000 ms \\\hline + RSA 4096 bit & 10x key generation & 45 000 ms \\\hline + \hline + CS & 10x r0, r1 derive and R1,R2 calculation & 0.749 ms \\\hline + CS & 10x derivation of blinding secrets & 0.267 ms \\\hline + CS & 10x blinding & 4.996 ms \\\hline + RSA 1024 bit & 10x blinding & 3.952 ms \\\hline + RSA 2048 bit & 10x blinding & 10 ms \\\hline + RSA 3072 bit & 10x blinding & 17 ms \\\hline + RSA 4096 bit & 10x blinding & 27 ms \\\hline + \hline + CS & 10x signing & 0.221 ms \\\hline + RSA 1024 bit & 10x signing & 25 ms \\\hline + RSA 2048 bit & 10x signing & 135 ms \\\hline + RSA 3072 bit & 10x signing & 381 ms \\\hline + RSA 4096 bit & 10x signing & 762 ms \\\hline + \hline + CS & 10x unblinding & 0.002 ms \\\hline + RSA 1024 bit & 10x unblinding & 9 ms \\\hline + RSA 2048 bit & 10x unblinding & 34 ms \\\hline + RSA 3072 bit & 10x unblinding & 80 ms \\\hline + RSA 4096 bit & 10x unblinding & 141 ms \\\hline + \hline + CS & 10x verifying & 2.458 ms \\\hline + RSA 1024 bit & 10x verifying & 2.365 ms \\\hline + RSA 2048 bit & 10x verifying & 6 ms \\\hline + RSA 3072 bit & 10x verifying & 10 ms \\\hline + RSA 4096 bit & 10x verifying & 16 ms \\\hline + \end{tabular} + \caption{Comparison on POWER9} + \label{tab:comp-sign-POWER9} +\end{table} + +\section{ARMv7 Processor} +Detailed comparison of each operation can be found in table \ref{tab:comp-sign-armv7}. +\begin{bfhBox}[BFH-MediumBlue]{Setup} + CPU: 8-core ARMv7 Processor rev 3 (v7l) + Architecture: armv7 \\ + OS: Linux odroidxu4 4.14.150-odroidxu4 \#2 SMP PREEMPT Mon Oct 28 08:07:45 CET 2019 armv7l GNU/Linux\\ + libsodium:armhf version: 1.9.4-5 \\ + libgcrypt:armhf version: 1.0.18-1 +\end{bfhBox} + +\begin{table}[ht] + \centering + \colorlet{BFH-table}{BFH-MediumBlue!10} + \colorlet{BFH-tablehead}{BFH-MediumBlue!50} + \setupBfhTabular + \begin{tabular}{llr} + \rowcolor{BFH-tablehead} + \textbf{Signature Scheme} & \textbf{Operation} & \textbf{Speed} \\\hline + CS & 10x key generation & 1.719 ms \\\hline + RSA 1024 bit & 10x key generation & 1050 ms \\\hline + RSA 2048 bit & 10x key generation & 8000 ms \\\hline + RSA 3072 bit & 10x key generation & 53 000 ms \\\hline + RSA 4096 bit & 10x key generation & 159 000 ms \\\hline + \hline + CS & 10x r0, r1 derive and R1,R2 calculation & 3.621 ms \\\hline + CS & 10x derivation of blinding secrets & 0.514 ms \\\hline + CS & 10x blinding & 24 ms \\\hline + RSA 1024 bit & 10x blinding & 10 ms \\\hline + RSA 2048 bit & 10x blinding & 26 ms \\\hline + RSA 3072 bit & 10x blinding & 45 ms \\\hline + RSA 4096 bit & 10x blinding & 78 ms \\\hline + \hline + CS & 10x signing & 0.481 ms \\\hline + RSA 1024 bit & 10x signing & 87 ms \\\hline + RSA 2048 bit & 10x signing & 385 ms \\\hline + RSA 3072 bit & 10x signing & 1038 ms \\\hline + RSA 4096 bit & 10x signing & 2073 ms \\\hline + \hline + CS & 10x unblinding & 0.008 ms \\\hline + RSA 1024 bit & 10x unblinding & 26 ms \\\hline + RSA 2048 bit & 10x unblinding & 90 ms \\\hline + RSA 3072 bit & 10x unblinding & 195 ms \\\hline + RSA 4096 bit & 10x unblinding & 344 ms \\\hline + \hline + CS & 10x verifying & 11 ms \\\hline + RSA 1024 bit & 10x verifying & 5 ms \\\hline + RSA 2048 bit & 10x verifying & 15 ms \\\hline + RSA 3072 bit & 10x verifying & 28 ms \\\hline + RSA 4096 bit & 10x verifying & 42 ms \\\hline + \end{tabular} + \caption{Comparison on ARMv7} + \label{tab:comp-sign-armv7} +\end{table} + + +\section{Performance of the Security Module} +These performance measurements are only done on one hardware setup. +The performance tests of the cryptographic routines are more meaningful, the architecture of the Taler exchange could change a lot. +Furthermore, there could be made performance improvements at costs of security by doing the operations requiring the private keys directly in the httpd process. +Because of security reasons, the current design with the security module makes a lot of sense. +It has to be kept in mind that the following performance benchmarks are interesting to see, but could vary a lot with changes inside the codebase. +The performance of the signatures with the security module can be found in table \ref{tab:comp-sign-full} +\begin{bfhBox}[BFH-MediumBlue]{Setup} + CPU: 8-core AMD Ryzen 7 PRO 5850U \\ + OS: Ubuntu 21.10 Linux 5.13.0-25-generic \#26-Ubuntu SMP Fri Jan 7 15:48:31 UTC 2022 x86\_64 x86\_64 x86\_64 GNU/Linux \\ + libsodium version: 1.0.18-1build1 \\ + libgcrypt version: 1.8.7-5ubuntu2 +\end{bfhBox} + +\begin{table}[ht] + \centering + \colorlet{BFH-table}{BFH-MediumBlue!10} + \colorlet{BFH-tablehead}{BFH-MediumBlue!50} + \setupBfhTabular + \begin{tabular}{lll} + \rowcolor{BFH-tablehead} + \textbf{Signature Scheme} & \textbf{Test} & \textbf{Speed} \\\hline + CS & 100 sequential signature operations & 2.591 ms \\\hline + RSA 1024 bit & 100 sequential signature operations & 79 ms \\\hline + RSA 2048 bit & 100 sequential signature operations & 350 ms \\\hline + RSA 3072 bit & 100 sequential signature operations & 893 ms \\\hline + RSA 4092 & 100 sequential signature operations & 1811 ms \\\hline + \hline + CS & 100 parallel signature operations & 14 ms \\\hline + RSA 1024 bit & 100 parallel signature operations & 125 ms \\\hline + RSA 2048 bit & 100 parallel signature operations & 573ms \\\hline + RSA 3072 bit & 100 parallel signature operations & 1420 ms \\\hline + RSA 4092 & 100 parallel signature operations & 3279 ms \\\hline + \hline + CS & 800 parallel signature operations & 19 ms \\\hline + RSA 1024 bit & 800 parallel signature operations & 137 ms \\\hline + RSA 2048 bit & 800 parallel signature operations & 653 ms \\\hline + RSA 3072 bit & 800 parallel signature operations & 1451 ms \\\hline + RSA 4092 & 800 parallel signature operations & 3388 ms \\\hline + \end{tabular} + \caption{Performance comparison of the security module} + \label{tab:comp-sign-full} +\end{table} + +\input{content/appendix/rsa-redesign.tex} diff --git a/doc/cs/content/appendix/crypto_implementation.tex b/doc/cs/content/appendix/crypto_implementation.tex new file mode 100644 index 000000000..9ae9b5865 --- /dev/null +++ b/doc/cs/content/appendix/crypto_implementation.tex @@ -0,0 +1,279 @@ +\begin{lstlisting}[style=bfh-c,language=C,, caption={Crypto Implementation API}, label={lst:cryptoapi}] + #include <sodium.h> + + /** + * IMPLEMENTATION NOTICE: + * + * This is an implementation of the Schnorr, Blind Schnorr and + * Clause Blind Schnorr Signature Scheme using Curve25519. + * We use libsodium wherever possible. + * + * Blind Schnorr: The Blind Schnorr Signature Scheme is BROKEN! + * Use the Clause Blind Schnorr Signature Scheme instead. + * + * Clause Blind Schnorr Signature Scheme: + * This is a variation of the Blind Schnorr Signature Scheme where all operations + * before the signature creation are performed twice. + * The signer randomly chooses one of the two sessions and only creates the signature for this session. + * Note that the Clause part needs to be implemented by whoever uses this API. + * Further details about the Clause Blind Schnorr Signature Scheme can be found here: + * https://eprint.iacr.org/2019/877.pdf + */ + + + /** + * Curve25519 Scalar + */ + struct GNUNET_CRYPTO_Cs25519Scalar + { + /** + * 32 byte scalar + */ + unsigned char d[crypto_core_ed25519_SCALARBYTES]; + }; + + + /** + * Curve25519 point + */ + struct GNUNET_CRYPTO_Cs25519Point + { + /** + * This is a point on the Curve25519. + * The x coordinate can be restored using the y coordinate + */ + unsigned char y[crypto_core_ed25519_BYTES]; + }; + + + /** + * The private information of an Schnorr key pair. + */ + struct GNUNET_CRYPTO_CsPrivateKey + { + struct GNUNET_CRYPTO_Cs25519Scalar scalar; + }; + + + /** + * The public information of an Schnorr key pair. + */ + struct GNUNET_CRYPTO_CsPublicKey + { + struct GNUNET_CRYPTO_Cs25519Point point; + }; + + + /** + * Secret used for blinding (alpha and beta). + */ + struct GNUNET_CRYPTO_CsBlindingSecret + { + struct GNUNET_CRYPTO_Cs25519Scalar alpha; + struct GNUNET_CRYPTO_Cs25519Scalar beta; + }; + + + /** + * the private r used in the signature + */ + struct GNUNET_CRYPTO_CsRSecret + { + struct GNUNET_CRYPTO_Cs25519Scalar scalar; + }; + + + /** + * the public R (derived from r) used in c + */ + struct GNUNET_CRYPTO_CsRPublic + { + struct GNUNET_CRYPTO_Cs25519Point point; + }; + + /** + * Schnorr c to be signed + */ + struct GNUNET_CRYPTO_CsC + { + struct GNUNET_CRYPTO_Cs25519Scalar scalar; + }; + + /** + * s in the signature + */ + struct GNUNET_CRYPTO_CsS + { + struct GNUNET_CRYPTO_Cs25519Scalar scalar; + }; + + /** + * blinded s in the signature + */ + struct GNUNET_CRYPTO_CsBlindS + { + struct GNUNET_CRYPTO_Cs25519Scalar scalar; + }; + + /** + * CS Signtature containing scalar s and point R + */ + struct GNUNET_CRYPTO_CsSignature + { + /** + * Schnorr signatures are composed of a scalar s and a curve point + */ + struct GNUNET_CRYPTO_CsS s_scalar; + struct GNUNET_CRYPTO_Cs25519Point r_point; + }; + + /** + * Nonce + */ + struct GNUNET_CRYPTO_CsNonce + { + /*a nonce*/ + unsigned char nonce[256 / 8]; + }; + + + /** + * Create a new random private key. + * + * @param[out] priv where to write the fresh private key + */ + void + GNUNET_CRYPTO_cs_private_key_generate (struct GNUNET_CRYPTO_CsPrivateKey *priv); + + + /** + * Extract the public key of the given private key. + * + * @param priv the private key + * @param[out] pub where to write the public key + */ + void + GNUNET_CRYPTO_cs_private_key_get_public (const struct GNUNET_CRYPTO_CsPrivateKey *priv, + struct GNUNET_CRYPTO_CsPublicKey *pub); + + + /** + * Derive a new secret r pair r0 and r1. + * In original papers r is generated randomly + * To provide abort-idempotency, r needs to be derived but still needs to be UNPREDICTABLE + * To ensure unpredictability a new nonce should be used when a new r needs to be derived. + * Uses HKDF internally. + * Comment: Can be done in one HKDF shot and split output. + * + * @param nonce is a random nonce + * @param lts is a long-term-secret in form of a private key + * @param[out] r array containing derived secrets r0 and r1 + */ + void + GNUNET_CRYPTO_cs_r_derive (const struct GNUNET_CRYPTO_CsNonce *nonce, + const struct GNUNET_CRYPTO_CsPrivateKey *lts, + struct GNUNET_CRYPTO_CsRSecret r[2]); + + + /** + * Extract the public R of the given secret r. + * + * @param r_priv the private key + * @param[out] r_pub where to write the public key + */ + void + GNUNET_CRYPTO_cs_r_get_public (const struct GNUNET_CRYPTO_CsRSecret *r_priv, + struct GNUNET_CRYPTO_CsRPublic *r_pub); + + + /** + * Derives new random blinding factors. + * In original papers blinding factors are generated randomly + * To provide abort-idempotency, blinding factors need to be derived but still need to be UNPREDICTABLE + * To ensure unpredictability a new nonce has to be used. + * Uses HKDF internally + * + * @param secret is secret to derive blinding factors + * @param secret_len secret length + * @param[out] bs array containing the two derivedGNUNET_CRYPTO_CsBlindingSecret + */ + void + GNUNET_CRYPTO_cs_blinding_secrets_derive (const struct GNUNET_CRYPTO_CsNonce *blind_seed, + struct GNUNET_CRYPTO_CsBlindingSecret bs[2]); + + + /** + * Calculate two blinded c's + * Comment: One would be insecure due to Wagner's algorithm solving ROS + * + * @param bs array of the two blinding factor structs each containing alpha and beta + * @param r_pub array of the two signer's nonce R + * @param pub the public key of the signer + * @param msg the message to blind in preparation for signing + * @param msg_len length of message msg + * @param[out] blinded_c array of the two blinded c's + */ + void + GNUNET_CRYPTO_cs_calc_blinded_c (const struct GNUNET_CRYPTO_CsBlindingSecret bs[2], + const struct GNUNET_CRYPTO_CsRPublic r_pub[2], + const struct GNUNET_CRYPTO_CsPublicKey *pub, + const void *msg, + size_t msg_len, + struct GNUNET_CRYPTO_CsC blinded_c[2]); + + + /** + * Sign a blinded c + * This function derives b from a nonce and a longterm secret + * In original papers b is generated randomly + * To provide abort-idempotency, b needs to be derived but still need to be UNPREDICTABLE. + * To ensure unpredictability a new nonce has to be used for every signature + * HKDF is used internally for derivation + * r0 and r1 can be derived prior by using GNUNET_CRYPTO_cs_r_derive + * + * @param priv private key to use for the signing and as LTS in HKDF + * @param r array of the two secret nonce from the signer + * @param c array of the two blinded c to sign c_b + * @param nonce is a random nonce + * @param[out] blinded_signature_scalar where to write the signature + * @return 0 or 1 for b (see Clause Blind Signature Scheme) + */ + int + GNUNET_CRYPTO_cs_sign_derive(const struct GNUNET_CRYPTO_CsPrivateKey *priv, + const struct GNUNET_CRYPTO_CsRSecret r[2], + const struct GNUNET_CRYPTO_CsC c[2], + const struct GNUNET_CRYPTO_CsNonce *nonce, + struct GNUNET_CRYPTO_CsBlindS *blinded_signature_scalar + ); + + + /** + * Unblind a blind-signed signature using a c that was blinded + * + * @param blinded_signature_scalar the signature made on the blinded c + * @param bs the blinding factors used in the blinding + * @param[out] signature_scalar where to write the unblinded signature + */ + void + GNUNET_CRYPTO_cs_unblind (const struct GNUNET_CRYPTO_CsBlindS *blinded_signature_scalar, + const struct GNUNET_CRYPTO_CsBlindingSecret *bs, + struct GNUNET_CRYPTO_CsS *signature_scalar); + + + /** + * Verify whether the given message corresponds to the given signature and the + * signature is valid with respect to the given public key. + * + * @param sig signature that is being validated + * @param pub public key of the signer + * @param msg is the message that should be signed by @a sig (message is used to calculate c) + * @param msg_len is the message length + * @returns #GNUNET_YES on success, #GNUNET_SYSERR if key parameter(s) invalid #GNUNET_NO if signature invalid + */ + enum GNUNET_GenericReturnValue + GNUNET_CRYPTO_cs_verify (const struct GNUNET_CRYPTO_CsSignature *sig, + const struct GNUNET_CRYPTO_CsPublicKey *pub, + const void *msg, + size_t msg_len); + +\end{lstlisting}
\ No newline at end of file diff --git a/doc/cs/content/appendix/rsa-redesign.tex b/doc/cs/content/appendix/rsa-redesign.tex new file mode 100644 index 000000000..4f66d907e --- /dev/null +++ b/doc/cs/content/appendix/rsa-redesign.tex @@ -0,0 +1,209 @@ +\chapter{Redesigned RSA Protocols} +In order to bring the RSA and \gls{CSBS} protocols closer, this chapter describes a variant of the RSA protocols with the same changes as in the \gls{CSBS} versions (where they can be applied). + + +\section{Withdraw Protocol} +\begin{figure}[htp] + \begin{equation*} + \resizebox{1.0\textwidth}{!}{$\displaystyle + \begin{array}{ l c l } + \text{Customer} & & \text{Exchange} + \\ \text{knows:} & & \text{knows:} + \\ \text{reserve keys } w_s, W_p & & \text{reserve public key } W_p + \\ \text{denomination public key } D_p = e, N & & \text{denomination keys } d_s, D_p + \\ & & + \\\text{generate withdraw secret:} + \\ \omega := randombytes(32) + \\ \text{persist } \langle \omega, D_p \rangle + \\\text{derive coin key pair:} & & + \\ c_s := \text{HKDF}(256, \omega, \text{"cs"}) + \\ C_p := \text{Ed25519.GetPub}(c_s) + \\ \text{blind:} & & + \\ b_s := \text{HKDF}(256, \omega, \text{"b-seed"}) + \\ r := \text{FDH}(b_s) + \\ m' := \text{FDH}(N, C_p)*r^{e} \mod N & & + \\ \text{sign with reserve private key:} & & + \\ \rho_W := \langle D_p, m' \rangle & & + \\ \sigma_W := \text{Ed25519.Sign}(w_s, \rho_W) & & + \\ & \xrightarrow[\rule{2.5cm}{0pt}]{\rho = W_p, \sigma_W, \rho_W} & + \\ & & \langle D_p, m' \rangle := \rho_W + \\ & & \text{verify if } D_p \text{ is valid} + \\ & & \text{check } \text{Ed25519.Verify}(W_p, \rho_W, \sigma_W) + \\ & & \sigma'_c = (m')^{d_s} \mod N + \\ & & \text{decrease balance if sufficient and} + \\ & & \text{persist } \langle D_p, s \rangle + \\ & \xleftarrow[\rule{2.5cm}{0pt}]{\sigma'_c} & + \\ \text{unblind:}& & + \\ \sigma_c = \sigma'_c*r^{-1} & & + \\ \text{verify signature:}& & + \\ \textbf{check if } \sigma_c^{e} = \text{FDH}(N, C_p) & & + \\ & & + \\ \text{resulting coin: } c_s, C_p, \sigma_c, D_p & & + \\ & & + \\ \text{implementation note: minimum of} + \\ \text{persisted values is } \langle \omega, \sigma_c \rangle + \end{array}$ + } + \end{equation*} + \caption{Redesigned RSA withdrawal process} + \label{fig:withdrawal-process-rsa-redesign} +\end{figure} + +The changes to the RSA witdhdraw protocol (see \autoref{fig:withdrawal-process-rsa-redesign}) are limited to the derivation of the coin and blinding factor. + + +\section{Refresh Protocol} +The changes to the refresh protocol are related to the derivation of transfer secrets and subsequent operations, see \autoref{fig:refresh-derive-rsa-redesign}, \autoref{fig:refresh-part1-rsa-redesign} and \autoref{fig:refresh-part2-rsa-redesign}. +\begin{figure}[htp] + \centering + \fbox{% + \procedure[codesize=\small]{$\text{RefreshDerive}(t, \langle e, N \rangle, C_p)$}{% + T := \text{Curve25519.GetPub}(t) \\ + x := \textrm{ECDH-EC}(t, C_p) \\ + b_s := \text{HKDF}(256, x, \text{"b-seed"}) \\ + r := \text{FDH}(b_s) \\ + c'_s := \text{HKDF}(256,x,"c") \\ + C'_p := \text{Ed25519.GetPub}(c'_s) \\ + \overline{m} := r^e * C'_p \mod N \\ + \pcreturn \langle T, c_s', C_p', \overline{m} \rangle + } + } + \caption{Redesigned RSA RefreshDerive algorithm} + \label{fig:refresh-derive-rsa-redesign} +\end{figure} + +\begin{figure}[htp] + \begin{equation*} + \resizebox{1.0\textwidth}{!}{$\displaystyle + \begin{array}{ l c l } + % preliminaries + \text{Customer} & & \text{Exchange} + \\ \text{knows:} & & \text{knows:} + \\ \text{denomination public key } D_{p(i)} & & \text{denomination keys } d_{s(i)}, D_{p(i)} + \\ \text{coin}_0 = \langle D_{p(0)}, c_s^{(0)}, C_p^{(0)}, \sigma_c^{(0)} \rangle & & + % refresh request + \\ \text{Select} \langle N_t, e_t\rangle := D_{p(t)} \in D_{p(i)} + \\ \omega := randombytes(32) + \\ \text{persist } \langle \omega, D_{p(t)} \rangle + \\ \textbf{for } i = 1, \dots, \kappa: % generate k derives + \\ t_i := \text{HKDF}(256, \omega,\text{"t} i \text{"} ) % seed generation + \\ X_i := \text{RefreshDerive}(t_i, D_{p(t)}, C_p^{(0)}) + \\ (T_i, c_s^{(i)}, C_p^{(i)}, \overline{m}_i) := X_i + \\ \textbf{endfor} + \\ h_T := H(T_1, \dots, T_k) + \\ h_{\overline{m}} := H(\overline{m}_1, \dots, \overline{m}_k) + \\ h_C := H(h_t, h_{\overline{m}}) + \\ \rho_{RC} := \langle h_C, D_{p(t)}, D_{p(0)}, C_p^{(0)}, \sigma_C^{(0)} \rangle + \\ \sigma_{RC} := \text{Ed25519.Sign}(c_s^{(0)}, \rho_{RC}) + \\ \text{Persist refresh-request} \langle \omega, \rho_{RC}, \sigma_{RC} \rangle + \\ & \xrightarrow[\rule{2.5cm}{0pt}]{\rho_{RC}, \sigma_{RC}} & + % Exchange checks refresh request + \\ & & (h_C, D_{p(t)}, D_{p(0)}, C_p^{(0)}, \sigma_C^{(0)} = \rho_{RC}) + \\ & & \textbf{check} \text{Ed25519.Verify}(C_p^{(0)}, \sigma_{RC}, \rho_{RC}) + \\ & & x \rightarrow \text{GetOldRefresh}(\rho_{RC}) + \\ & & \textbf{Comment: }\text{GetOldRefresh} (\rho_{RC} \mapsto \{\bot,\gamma\}) + \\ & & \pcif x = \bot + \\ & & v := \text{Denomination}(D_{p(t)}) + \\ & & \langle e_0, N_0 \rangle := D_{p(0)} + \\ & & \textbf{check } \text{IsOverspending}(C_p^{(0)}, D_ {p(0)}, v) + \\ & & \textbf{check } D_{p(t)} \in \{D_{p(i)}\} + \\ & & \textbf{check } \text{FDH}(N_0, C_p^{(0)}) \equiv_{N_0} (\sigma_0^{(0)})^{e_0} + \\ & & \text{MarkFractionalSpend}(C_p^{(0)}, v) + \\ & & \gamma \leftarrow \{1, \dots, \kappa\} + \\ & & \text{Persist refresh-record } \langle \rho_{RC},\gamma \rangle + \\ & & \pcelse + \\ & & \gamma := x + \\ & & \textbf{endif} + \\ & \xleftarrow[\rule{2.5cm}{0pt}]{\gamma} & + \\ + \\ + \\ & \textit{Continued in figure \ref{fig:refresh-part2}} & + %\\ \pcintertext[dotted]{(Continued in Figure)} + \end{array}$ + } + \end{equation*} + \caption{Redesigned RSA refresh protocol (commit phase)} + \label{fig:refresh-part1-rsa-redesign} +\end{figure} + +\begin{figure}[htp] + \begin{equation*} + \resizebox{1.0\textwidth}{!}{$\displaystyle + \begin{array}{ l c l } + % preliminaries + \text{Customer} & & \text{Exchange} + \\ & \textit{Continuation of figure \ref{fig:refresh-part1}} & + \\ + \\ + % Check challenge and send challenge response (reveal not selected msgs) + \\ & \xleftarrow[\rule{2.5cm}{0pt}]{\gamma} & + \\ \textbf{check } \text{IsConsistentChallenge}(\rho_{RC}, \gamma) + \\ \textbf{Comment: } \text{IsConsistentChallenge}\\(\rho_{RC}, \gamma) \mapsto \{ \bot,\top \} + \\ + \\ \text{Persist refresh-challenge} \langle \rho_{RC}, \gamma \rangle + \\ S := \langle t_1, \dots, t_{\gamma-1}, t_{\gamma+1}, \dots, t_\kappa \rangle % all seeds without the gamma seed + \\ \rho_L = \langle C_p^{(0)}, D_{p(t)}, T_{\gamma},\overline{m}_\gamma \rangle + \\ \rho_{RR} = \langle T_\gamma, \overline{m}_\gamma, S \rangle + \\ \sigma_{L} = \text{Ed25519.Sign}(c_s^{(0)}, \rho_{L}) + \\ & \xrightarrow[\rule{2.5cm}{0pt}]{\rho_{RR},\rho_L, \sigma_{L}} & + % check revealed msgs and sign coin + \\ & & \langle T'_\gamma, \overline{m}'_\gamma, S \rangle := \rho_{RR} + \\ & & \langle t_1, \dots, t_{\gamma-1}, t_{\gamma+1}, \dots, t_\kappa \rangle ) := S + \\ & & \textbf{check } \text{Ed25519.Verify}(C_p^{(0)}, \sigma_L, \rho_L) + \\ & & \textbf{for} i = 1,\dots, \gamma-1, \gamma+1,\dots, \kappa + \\ & & X_i := \text{RefreshDerive}(t_i, D_{p(t)}, C_p^{(0)}) + \\ & & \langle T_i, c_s^{(i)}, C_p^{(i)}, \overline{m}_i \rangle := X_i + \\ & & \textbf{endfor} + \\ & & h_T' = H(T_1,\dots,T_{\gamma-1},T'_{\gamma},T_{\gamma+1},\dots,T_\kappa) + \\ & & h_{\overline{m}}' = H(\overline{m}_1,\dots,\overline{m}_{\gamma-1},\overline{m}'_{\gamma},\overline{m}_{\gamma+1},\dots,\overline{m}_\kappa) + \\ & & h_C' = H(h_T', h_{\overline{m}}') + \\ & & \textbf{check } h_C = h_C' + \\ & & \overline{\sigma}_C^{(\gamma)} := \overline{m}^{d_{s(t)}} + \\ & & \text{persist } \langle \rho_L, \sigma_L, S \rangle + \\ & \xleftarrow[\rule{2.5cm}{0pt}]{\overline{\sigma}_C^{(\gamma)}} & + % Check coin signature and persist coin + \\ \sigma_C^{(\gamma)} := r^{-1}\overline{\sigma}_C^{(\gamma)} + \\ \textbf{check if } (\sigma_C^{(\gamma)})^{e_t} \equiv_{N_t} C_p^{(\gamma)} + \\ \text{Persist coin} \langle D_{p(t)}, c_s^{(\gamma)}, C_p^{(\gamma)}, \sigma_C^{(\gamma)} \rangle + \end{array}$ + } + \end{equation*} + \caption{Redesigned RSA refresh protocol (reveal phase)} + \label{fig:refresh-part2-rsa-redesign} +\end{figure} + + +\section{Linking Protocol} +The changes are described in \autoref{fig:refresh-link-rsa-redesign}. +\begin{figure}[htp] + \begin{equation*} + \resizebox{1.0\textwidth}{!}{$\displaystyle + \begin{array}{ l c l } + % preliminaries + \text{Customer} & & \text{Exchange} + \\ \text{knows:} & & \text{knows:} + \\ \text{coin}_0 = \langle D_{p(0)}, c_s^{(0)}, C_p^{(0)}, \sigma_{C}^{(0)} \rangle + \\ & \xrightarrow[\rule{2.5cm}{0pt}]{C_{p(0)}} & + \\ & & L := \text{LookupLink}(C_{p(0)}) + \\ & & \textbf{Comment: } \text{LookupLink}(C_p) \mapsto \{\langle \rho_L^{(i)}, + \\ & & \sigma_L^{(i)}, \overline{\sigma}_C^{(i)} \rangle\} + \\ & \xleftarrow[\rule{2.5cm}{0pt}]{L} & + \\ \pcfor \langle \rho_{L}^{(i)}, \overline{\sigma}_L^{(i)}, \sigma_C^{(i)} \rangle \in L + \\ \langle \hat{C}_p^{(i)}, D_{p(t)}^{(i)}, T_\gamma^{(i)}, \overline{m}_\gamma^{(i)} \rangle := \rho_L^{(i)} + \\ \langle e_t^{(i)}, N_t^{(i)} \rangle := D_{p(t)}^{(i)} + \\ \textbf{check } \hat{C}_p^{(i)} \equiv C_p^{(0)} + \\ \textbf{check } \text{Ed25519.Verify}(C_p^{(0)}, \rho_{L}^{(i)}, \sigma_L^{(i)}) + \\ x_i := \text{ECDH}(c_s^{(0)}, T_{\gamma}^{(i)}) + \\ c_s^{(i)} := \text{HKDF}(256,x_i,"c") + \\ C_p^{(i)} := \text{Ed25519.GetPub}(c_s^{(i)}) + \\ b_s^{(i)} := \text{HKDF}(256, x_i, \text{"b-seed"}) + \\ r_i := \text{FDH}(b_s^{(i)}) + \\ \sigma_C^{(i)} := (r_i)^{-1} \cdot \overline{m}_\gamma^{(i)} + \\ \textbf{check } (\sigma_C^{(i)})^{e_t^{(i)}} \equiv_{N_t^{(i)}} C_p^{(i)} + \\ \text{(Re-)obtain coin} \langle D_{p(t)}^{(i)},c_s^{(i)}, C_p^{(i)}, \sigma_C^{(i)} \rangle + \end{array}$ + } + \end{equation*} + \caption{Redesigned RSA linking protocol} + \label{fig:refresh-link-rsa-redesign} +\end{figure} diff --git a/doc/cs/content/x_taler.tex b/doc/cs/content/x_taler.tex new file mode 100644 index 000000000..d04fe84cf --- /dev/null +++ b/doc/cs/content/x_taler.tex @@ -0,0 +1,373 @@ +\chapter{Taler} + +\section{Taler Architecture} + +\subsection{Auditor} +The following text is cited from section 4.4 in \cite{dold:the-gnu-taler-system} +\begin{center} + \textit{ + "The auditor consists of two processes that are regularly run and generate auditing reports. + Both processes access the exchange’s database, either directly (for exchange-internal auditing as part if its operational security) or over a replica (in the case of external auditors). + The taler-wire-auditor process checks that the incoming and outgoing transfers recorded in the exchange’s database match wire transfers of the underlying bank account. + To access the transaction history (typically recorded by the bank), the wire auditor uses a wire plugin, with the same interface and implementation as the exchange’s wire plugins. + The taler-auditor process generates a report with the following information: + } +\end{center} + +\begin{itemize} + \item \textit{Do the operations stored in a reserve’s history match the reserve’s balance?} + \item \textit{Did the exchange record outgoing transactions to the right merchant for deposits after the deadline for the payment was reached?} + \item \textit{Do operations recorded on coins (deposit, refresh, refund) match the remaining value on the coin?} + \item \textit{Do operations respect the expiration of denominations?} + \item \textit{For a denomination, is the number of pairwise different coin public keys recorded in deposit/refresh operations smaller or equal to the number of blind signatures recorded in withdraw/refresh operations? If this invariant is violated, the corresponding denomination must be revoked.} + \item \textit{What is the income if the exchange from different fees?} +\end{itemize} + +\begin{center} + \textit{ + \dots + The auditor exposes a web server with the taler-auditor-httpd process. + Currently, it only shows a website that allows the customer to add the auditor to the list of trusted auditors in their wallet. + In future versions, the auditor will also have HTTP endpoints that allow merchants to submit samples of deposit confirmations, which will be checked against the deposit permissions in the exchange’s database to detect compromised signing keys or missing writes. + Furthermore, in deployments that require the merchant to register with the exchange beforehand, the auditor also offers a list of exchanges it audits, so that the merchant backend can automatically register with all exchanges it transitively trusts." + } +\end{center} +Some details were left out (see at the dots) and can be read in section 4.4 in \cite{dold:the-gnu-taler-system} + +\subsubsection{Technical Details} +Documentation: \cite{taler-documentation:auditor-operator-manual} \\ +Git Repositories: +\begin{itemize} + \item Main repository: \cite{taler-git:exchange} (Part of exchange repository, inside ./src/auditor and ./src/auditordb) + \item Auditor's public website: \cite{taler-git:auditor} +\end{itemize} +Language: C \\ +Dependencies: +\begin{itemize} + \item GNUnet >= 0.14.0 + \item GNU libmicrohttpd >= 0.9.71 + \item Postgres >= 9.6, including libpq + \item libjansson >= 2.7 + \item libargon2 >= 20171227 + \item libsodium >= 1.0 + \item libgcrypt >= 1.6 + \item libqrencode >= 4.0.0 + \item libcurl >= 7.26 (or libgnurl >= 7.26) + \item GNU libunistring >= 0.9.3 + \item libsqlite3 >= 3.16.2 +\end{itemize} +The auditor API is implemented as REST API and uses \ac{JSON} as message format. +The auditor does not implement HTTPS (TLS), instead it recommends using a HTTP reverse Proxy that offers TLS termination. +By delegating the responsibility for TLS termination, the auditor implementation becomes lighter. + +There are a lot more technical details written in the documentation linked above and in the README files. +Since Taler is actively developed and technical details could change, we refer to this documentation. + +\subsection{Exchange} +The following text is cited from section 4.3 in \cite{dold:the-gnu-taler-system} +\begin{center} + \textit{ + "The exchange consists of three independent processes: + } +\end{center} +\begin{itemize} + \item \textit{The taler-exchange-httpd process handles HTTP requests from clients, mainly merchants and wallets.} + \item \textit{The taler-exchange-wirewatch process watches for wire transfers to the exchange’s bank account and updates reserves based on that.} + \item \textit{The taler-exchange-aggregator process aggregates outgoing transactions to merchants.} +\end{itemize} + +\begin{center} + \textit{ + All three processes exchange data via the same database. + Only taler-exchange-httpd needs access to the exchanges online signing keys and denomination keys. + The database is accessed via a Taler-specific database abstraction layer. + Different databases can be supported via plugins; at the time of writing this, only a PostgreSQL plugin has been implemented. + Wire plugins are used as an abstraction to access the account layer that Taler runs on. + Specifically, the wirewatch process uses the plugin to monitor incoming transfers, and the aggregator process uses the wire plugin to make wire transfers to merchants. + The following APIs are offered by the exchange: + } + + \textbf{\textit{Announcing keys, bank accounts and other public information}}\\ + \textit{ + The exchange offers the list of denomination keys, signing keys, auditors, supported bank accounts, revoked keys and other general information needed to use the exchange’s services via the /keys and /wire APIs. + } + + \textbf{\textit{Reserve status and withdrawal}}\\ + \textit{ + After having wired money to the exchange, the status of the reserve can be checked via the /reserve/status API. Since the wire transfer usually takes some time to arrive at the exchange, wallets should periodically poll this API, and initiate a withdrawal with /reserve/withdraw once the exchange received the funds. + } + + \textbf{\textit{Deposits and tracking}}\\ + \textit{ + Merchants transmit deposit permissions they have received from customers to the exchange via the/deposit API. Since multiple deposits are aggregated into one wire transfer, the merchant additionally can use the exchange’s /track/transfer API that returns the list of deposits for an identifier included in the wire transfer to the merchant, as well as the /track/transaction API to look up which wire transfer included the payment for a given deposit. + } + + \textbf{\textit{Refunds}}\\ + \textit{ + The refund API (/refund) can “undo” a deposit if the merchant gave their signature, and the aggregation deadline for the payment has not occurred yet. + } + + \textbf{\textit{Emergency payback}}\\ + \textit{ + The emergency payback API (/payback) allows customers to be compensated for coins whose denomination key has been revoked. + Customers must send either a full withdrawal transcript that includes their private blinding factor, or a refresh transcript (of a refresh that had the revoked denominations as one of the targets) that includes blinding factors. + In the former case, the reserve is credited, in the latter case, the source coin of the refresh is refunded and can be refreshed again." + } +\end{center} + +Additional information for how the exchange generates new denomination and signing keys can be found in the end of section 4.3 of \cite{dold:the-gnu-taler-system}. + +\begin{figure}[h!] + \centering + \includegraphics[height=0.5\textwidth]{taler-exchange.png} + \caption{Architecture of the Taler Exchange reference implementation. Source: \cite{dold:the-gnu-taler-system}} + \label{fig:taler-arch-exchange} +\end{figure} + +\subsubsection{Technical Details} + +Documentation: \cite{taler-documentation:exchange-operator-manual} \\ +Git Repository: Main repository: \cite{taler-git:exchange} \\ +Language: C \\ +Dependencies: +\begin{itemize} + \item GNUnet >= 0.14.0 + \item GNU libmicrohttpd >= 0.9.71 + \item Postgres >= 9.6, including libpq + \item libjansson >= 2.7 + \item libargon2 >= 20171227 + \item libsodium >= 1.0 + \item libgcrypt >= 1.6 + \item libqrencode >= 4.0.0 + \item libcurl >= 7.26 (or libgnurl >= 7.26) + \item GNU libunistring >= 0.9.3 + \item libsqlite3 >= 3.16.2 +\end{itemize} +The exchange’s API is implemented as REST API and uses \ac{JSON} as message format. + +There are a lot more technical details written in the documentation linked above and in the README files. +Since Taler is actively developed and technical details could change, we refer to this documentation. + +\subsection{Merchant} +The following text is cited from section 4.5 in \cite{dold:the-gnu-taler-system} +\begin{center} + \textit{ + "The Taler merchant backend is a component that abstracts away the details of processing Taler payments and provides a simple HTTP API. + The merchant backend handles cryptographic operations (signature verification, signing), secret management and communication with the exchange. + The backend API (see \url{https://docs.taler.net/api/}) is divided into two types of HTTP endpoints: + } +\end{center} + +\begin{enumerate} + \item \textit{Functionality that is accessed internally by the merchant. + These API stypically require authentication and/or are only accessible from within the private network of the merchant.} + \item \textit{Functionality that is exposed publicly on the Internet and accessed by the customer’s wallet and browser.} +\end{enumerate} + +\begin{center} + \textit{ + A typical merchant has a storefront component that customers visit with their browser, as well as a back office component that allows the merchant to view information about payments that customers made and that integrates with other components such as order processing and shipping." + } +\end{center} + +\subsubsection{Processing Payments} +\begin{center} + \textit{ + "To process a payment, the storefront first instructs the backend to create an order. + The order contains information relevant to the purchase, and is in fact a subset of the information contained in the contract terms. + The backend automatically adds missing information to the order details provided by the storefront. + The full contract terms can only be signed once the customer provides the claim public key for the contract.\\ + Each order is uniquely identified by an order ID, which can be chosen by the storefront or automatically generated by the backend. + The order ID can be used to query the status of the payment. + If the customer did not pay for an order ID yet, the response from the backend includes a payment redirect URL. + The storefront can redirect the customer to this payment redirect URL; visiting the URL will trigger the customer’s browser/wallet to prompt for a payment.\\ + To simplify the implementation of the storefront, the merchant backend can serve a page to the customer’s browser that triggers the payment via the HTTP402 status code and the corresponding headers, and provides a fallback (in the form of a taler:pay link) for loosely integrated browsers. + When checking the status of a payment that is not settled yet, the response from the merchant backend will contains a payment redirect URL. + The storefront redirects the browser to this URL, which is served by the merchant backend and triggers the payment. + \dots " + } +\end{center} + +\subsubsection{Back Office APIs} +\begin{center} + \textit{ + "The back office API allows the merchant to query information about the history and status of payments, as well as correlate wire transfers to the merchant’s bank account with the respective GNU Taler payment. + This API is necessary to allow integration with other parts of the merchant’s e-commerce infrastructure." + } +\end{center} + +% Nachfolgende Section nicht notwendig. +% \subsubsection{Example Merchant Frontends} +% This section is included to provide an overview of the reference implementation for the merchant. +% This helps to get a better understanding of how a merchant could potentially look like. +% Note that the actual code could differ from the cited part. +% The actual code can be found in \url{git.taler.net} +% \begin{center} +% \textit{ +% We implemented the following applications using the merchant backend API. +% } + +% \textit{\textbf{Blog Merchant}}\\ +% \textit{ +% The blog merchant’s landing page has a list of article titles with a teaser. +% When following the link to the article, the customer is asked to pay to view the article. +% } + +% \textit{\textbf{Donations}}\\ +% \textit{ +% The donations frontend allows the customer to select a project to donate to. +% The fulfillment page shows a donation receipt. +% } + +% \textit{\textbf{Codeless Payments}}\\ +% \textit{ +% The codeless payment frontend is a prototype for a user interface that allows merchants to sell products on their website without having to write code to integrate with the merchant backend. +% Instead, the merchant uses a web interface to manage products and their available stock. +% The codeless payment frontend then creates an HTML snippet with a payment button that the merchant can copy-and-paste integrate into their storefront. +% } + +% \textit{\textbf{Survey}}\\ +% \textit{ +% The survey frontend showcases the tipping functionality of GNU Taler. +% The user fills out a survey and receives a tip for completing it. +% } + +% \textit{\textbf{Back Office}}\\ +% \textit{ +% The example back-office application shows the history and status of payments processed by the merchant. +% } +% \end{center} + +\begin{figure}[h!] + \centering + \includegraphics[height=0.5\textwidth]{taler-merchant.png} + \caption{Architecture Taler Merchant reference implementation. Source: \cite{dold:the-gnu-taler-system}} + \label{fig:taler-arch-merchant} +\end{figure} + +\subsubsection{Technical Details} + +Documentation: \cite{taler-documentation:merchant-backend-operator-manual} \\ +API Documentation: \cite{taler-documentation:merchant-api} \\ +Back-office Documentation: \cite{taler-documentation:back-office} \\ +Point-of-Sales Documentation: \cite{taler-documentation:pos-manual} \\ +Git Repositories: +\begin{itemize} +\item Backend: \cite{taler-git:merchant} +\item Backoffice: \cite{taler-git:backoffice} +\item Point-of-Sales App: \cite{taler-git:android} (part of android repo) +\end{itemize} +Language: C (Backend), Kotlin (\ac{PoS}), [Python, Javascript] (Backoffice)\\ +Dependencies: +\begin{itemize} + \item GNUnet >= 0.14.0 + \item GNU libmicrohttpd >= 0.9.71 + \item Postgres >= 9.6, including libpq + \item libjansson >= 2.7 + \item libargon2 >= 20171227 + \item libsodium >= 1.0 + \item libgcrypt >= 1.6 + \item libqrencode >= 4.0.0 + \item libcurl >= 7.26 (or libgnurl >= 7.26) + \item GNU libunistring >= 0.9.3 + \item libsqlite3 >= 3.16.2 + \item Flask (Backoffice) +\end{itemize} +Frontend Repositories: +\begin{itemize} + \item Payments with Django: \cite{taler-git:django-payments} + \item Wordpress woocommerce plugin: \cite{taler-git:woocommerce} + \item Saleor Frontend: \cite{taler-git:saleor} + \item Demo Frontends: \cite{taler-git:merchant-demos} +\end{itemize} +The merchant’s API is implemented as REST API and uses \ac{JSON} as message format. +The \ac{PoS} app is for the merchant to process customer's orders by adding or removing products, calculating the amount owed by the customer or letting the customer make a Taler payment via QR code or NFC. +The back office Web service allows a merchant to check status of their Taler transactions. +There are already a lot of demo pages and integrations for different e-commerce solutions. + +There are a lot more technical details written in the documentation linked above and in the README files. +Since Taler is actively developed and technical details could change, we refer to this documentation. + +\subsection{Wallet} +The following text is cited from section 4.6 in \cite{dold:the-gnu-taler-system} +\begin{center} + \textit{ + "The wallet manages the customer’s reserves and coins, lets the customer view and pay for contracts from merchants. \dots + The reference implementation of the GNU Taler wallet is written in the Type-Script language against the WebExtension API, a cross-browser mechanism for browser extensions. + The reference wallet is a “tightly integrated” wallet, as it directly hooks into the browser to process responses with the HTTP status code“402 Payment Required”.\\ + Many cryptographic operations needed to implement the wallet are not commonly available in a browser environment. + We cross-compile the GNU Taler utility library written in C as well as its dependencies (such as libgcrypt) to asm.js (and WebAssembly on supported platforms) using the LLVM-based emscripten toolchain. + Cryptographic operations run in an isolated process implemented as a WebWorker. + This design allows the relatively slow cryptographic operations to run concurrently in the background in multiple threads. + Since the crypto WebWorkers are started on-demand, the wallet only uses minimal resources when not actively used." + } +\end{center} + +\subsubsection{Optimizations} +\begin{center} + \textit{ + "To improve the perceived performance of cryptographic operations, the wallet optimistically creates signatures in the background while the user is looking at the “confirm payment” dialog. + If the user does not accept the contract, these signatures are thrown away instead of being sent to the merchant. + This effectively hides the latency of the most expensive cryptographic operations, as they are done while the user consciously needs to make a decision on whether to proceed with a payment." + } +\end{center} + +\subsubsection{Wallet Detection} +\begin{center} + \textit{ + " \dots + Browser fingerprinting is a concern with any additional APIs made available to websites, either by the browser itself or by browser extensions. + Since a website can simply try to trigger a payment to determine whether a tightly integrated Taler wallet is installed, one bit of additional fingerprinting information is already available through the usage of Taler. + The dynamic detection methods do not, however, expose any information that is not already available to websites by signaling the wallet through HTTP headers." + } +\end{center} + +\subsubsection{Further Wallet Features} +More information about other Wallet Features like coin selection, wallet liquidation and wallet signaling can be found in sections 4.6.2, 4.6.5 and 4.6.6 of \cite{dold:the-gnu-taler-system}. + +\begin{figure}[h!] + \centering + \includegraphics[height=0.5\textwidth]{taler-wallet.png} + \caption{Architecture of the Taler Wallet reference implementation. Source: \cite{dold:the-gnu-taler-system}} + \label{fig:taler-wallet-reference-impl} +\end{figure} + +\subsubsection{Technical Details} + +Documentation: \cite{taler-documentation:wallet-developer-manual} \\ +Wallet-CLI documentation: \cite{taler-documentation:wallet-cli-manual} \\ +Git Repository: +\begin{itemize} + \item Main repository: \cite{taler-git:wallet-core} \\ + This Repository includes the wallet-core and the implementations for the web extension and CLI. + \item Android app: \cite{taler-git:android} + \item iOS app: \cite{taler-git:ios} +\end{itemize} +Language: Typescript, Javascript (wallet-core, web extension), Kotlin (Android app), Swift (iOS app)\\ +Dependencies: +\begin{itemize} + \item prettier + \item rimraf + \item rollup + \item typescript + \item ava + \item esbuild + \item axios + \item tslib + \item cancellationtoken + \item minimatch + \item source-map-support + \item big-integer + \item fflate + \item esm + \item jed + \item nyc + \item po2json + \item typedoc + \item api-extractor +\end{itemize} + +There are a lot more technical details written in the documentation linked above and in the README files. +Since Taler is actively developed and technical details could change, we refer to this documentation. + + diff --git a/doc/cs/images/bfh_logo.png b/doc/cs/images/bfh_logo.png Binary files differnew file mode 100644 index 000000000..e3aba1175 --- /dev/null +++ b/doc/cs/images/bfh_logo.png diff --git a/doc/cs/images/diagram-simple.png b/doc/cs/images/diagram-simple.png Binary files differnew file mode 100644 index 000000000..d6ad2921e --- /dev/null +++ b/doc/cs/images/diagram-simple.png diff --git a/doc/cs/images/logo-2021.png b/doc/cs/images/logo-2021.png Binary files differnew file mode 100644 index 000000000..ea599bdab --- /dev/null +++ b/doc/cs/images/logo-2021.png diff --git a/doc/cs/images/projectplan.png b/doc/cs/images/projectplan.png Binary files differnew file mode 100644 index 000000000..edad872b2 --- /dev/null +++ b/doc/cs/images/projectplan.png diff --git a/doc/cs/images/taler-exchange.png b/doc/cs/images/taler-exchange.png Binary files differnew file mode 100644 index 000000000..2e898b0ac --- /dev/null +++ b/doc/cs/images/taler-exchange.png diff --git a/doc/cs/images/taler-merchant.png b/doc/cs/images/taler-merchant.png Binary files differnew file mode 100644 index 000000000..15b746129 --- /dev/null +++ b/doc/cs/images/taler-merchant.png diff --git a/doc/cs/images/taler-pki.png b/doc/cs/images/taler-pki.png Binary files differnew file mode 100644 index 000000000..f72d42315 --- /dev/null +++ b/doc/cs/images/taler-pki.png diff --git a/doc/cs/images/taler-wallet.png b/doc/cs/images/taler-wallet.png Binary files differnew file mode 100644 index 000000000..234d8a0e7 --- /dev/null +++ b/doc/cs/images/taler-wallet.png diff --git a/doc/cs/images/taler_bigger.png b/doc/cs/images/taler_bigger.png Binary files differnew file mode 100644 index 000000000..cd55fa643 --- /dev/null +++ b/doc/cs/images/taler_bigger.png diff --git a/doc/cs/images/taler_cut_and_choose.png b/doc/cs/images/taler_cut_and_choose.png Binary files differnew file mode 100644 index 000000000..47ad4d0d0 --- /dev/null +++ b/doc/cs/images/taler_cut_and_choose.png diff --git a/doc/cs/images/taler_refresh_link_threat.png b/doc/cs/images/taler_refresh_link_threat.png Binary files differnew file mode 100644 index 000000000..03d0804fb --- /dev/null +++ b/doc/cs/images/taler_refresh_link_threat.png diff --git a/doc/cs/images/taler_refresh_transfer_key.png b/doc/cs/images/taler_refresh_transfer_key.png Binary files differnew file mode 100644 index 000000000..d75360f28 --- /dev/null +++ b/doc/cs/images/taler_refresh_transfer_key.png diff --git a/doc/cs/thesis.tex b/doc/cs/thesis.tex new file mode 100644 index 000000000..b6abb0d74 --- /dev/null +++ b/doc/cs/thesis.tex @@ -0,0 +1,93 @@ +%============================ MAIN DOCUMENT ================================ +% define document class +\documentclass[ + a4paper % paper format +% ,10.5pt % fontsize +% ,BCOR=18mm % Binding correction +% ,twoside +% ,headings=openright + ,bibliography=totoc % If enabled add bibliography to TOC + ,class=scrreprt % If removed, makes book format (1 side left, 1 right) + ,listof=totoc % If enabled add lists to TOC +% ,bilingual + ,monolingual +% ,invert-title % Invert the BFH colors +]{bfhthesis} % KOMA-script report + +\input{ads/header.tex} + +\begin{document} + +\frontmatter + + +\input{variable.sty} + +%---------------- BFH tile page ----------------------------------------- +\maketitle + +% Abstract +\input{ads/abstract} + +%------------ TABLEOFCONTENTS ---------------- +\tableofcontents + +%------------ START MAIN PART ---------------- +\mainmatter + +%------------ Introduction +\input{content/1_introduction.tex} + +%------------ Project management +% \input{content/2_project_management.tex} + +%------------ Preliminaries +\input{content/3_preliminaries.tex} + +%------------ Execution +\input{content/4_execution.tex} + +%------------ Discussion +\input{content/5_discussion.tex} + +%------------ Conclusion +\input{content/6_conclusion.tex} + + + +%------------ Eidesstattliche Erklärung +% \includepdf[pages=1]{ads/Erklaerung} +%------------ History +% \input{ads/history} + +%------------ Abbildungsverzeichnis +%\cleardoublepage +\listoffigures + +%------------ Tabellenverzeichnis +%\cleardoublepage +\listoftables + +% TODO +%------------ Quellcodeverzeichnis +% \cleardoublepage + \phantomsection \label{listoflist} + \addcontentsline{toc}{chapter}{List of listings} + \lstlistoflistings + +%------------ Literaturverzeichnis +%\cleardoublepage +\printbibliography + +%------------ Abkürzungsverzeichnis +%\cleardoublepage +\phantomsection \label{listofacs} +\addcontentsline{toc}{chapter}{Abbreviations} +\input{ads/abbreviation} + +%------------ Glossar +\printglossary[style=altlist,title=Glossary] + +%------------ Anhang +\input{content/appendix.tex} +\end{document} diff --git a/doc/cs/variable.sty b/doc/cs/variable.sty new file mode 100644 index 000000000..18ae77a7c --- /dev/null +++ b/doc/cs/variable.sty @@ -0,0 +1,15 @@ +\title{Adding Schnorr's Blind Signature in Taler} +\subtitle{An improved Taler Blind Signature System} +\author{{Gian Demarmels}, {Lucien Heuzeveldt}} +\institution{Bern University of Applied Science} +\department{Engineering and Computer Sciences} +\institute{Institute for Cybersecurity and Engineering ICE} +\version{1.0} +\titlegraphic{\includegraphics[width=\width]{logo-2021.png}} +\advisor{Prof. Dr. Emmanuel Benoist} +\expert{Elektronikingenieur HTL Daniel Voisard} +\degreeprogram{Bachelor of Science in Computer Science} +\setupSignature{ + G. Demarmels={\includegraphics[width=\linewidth]{logo-2021.png}}, + L. Heuzeveldt={\includegraphics[width=\linewidth]{bfh_logo.png}\vskip-\baselineskip} +} diff --git a/doc/doxygen/taler.doxy b/doc/doxygen/taler.doxy index dafe78fa5..1516811c5 100644 --- a/doc/doxygen/taler.doxy +++ b/doc/doxygen/taler.doxy @@ -1,17 +1,144 @@ -# Doxyfile 1.5.6 +# Doxyfile 1.9.4 + +# This file describes the settings to be used by the documentation system +# doxygen (www.doxygen.org) for a project. +# +# All text after a double hash (##) is considered a comment and is placed in +# front of the TAG it is preceding. +# +# All text after a single hash (#) is considered a comment and will be ignored. +# The format is: +# TAG = value [value, ...] +# For lists, items can also be appended using: +# TAG += value [value, ...] +# Values that contain spaces should be placed between quotes (\" \"). +# +# Note: +# +# Use doxygen to compare the used configuration file with the template +# configuration file: +# doxygen -x [configFile] +# Use doxygen to compare the used configuration file with the template +# configuration file without replacing the environment variables: +# doxygen -x_noenv [configFile] #--------------------------------------------------------------------------- # Project related configuration options #--------------------------------------------------------------------------- + +# This tag specifies the encoding used for all characters in the configuration +# file that follow. The default is UTF-8 which is also the encoding used for all +# text before the first occurrence of this tag. Doxygen uses libiconv (or the +# iconv built into libc) for the transcoding. See +# https://www.gnu.org/software/libiconv/ for the list of possible encodings. +# The default value is: UTF-8. + DOXYFILE_ENCODING = UTF-8 + +# The PROJECT_NAME tag is a single word (or a sequence of words surrounded by +# double-quotes, unless you are using Doxywizard) that should identify the +# project for which the documentation is generated. This name is used in the +# title of most generated pages and in a few other places. +# The default value is: My Project. + PROJECT_NAME = "GNU Taler: Exchange" -PROJECT_NUMBER = 0.8.3 + +# The PROJECT_NUMBER tag can be used to enter a project or revision number. This +# could be handy for archiving the generated documentation or if some version +# control system is used. + +PROJECT_NUMBER = 0.10.2 + +# Using the PROJECT_BRIEF tag one can provide an optional one line description +# for a project that appears at the top of each page and should give viewer a +# quick idea about the purpose of the project. Keep the description short. + +PROJECT_BRIEF = + +# With the PROJECT_LOGO tag one can specify a logo or an icon that is included +# in the documentation. The maximum height of the logo should not exceed 55 +# pixels and the maximum width should not exceed 200 pixels. Doxygen will copy +# the logo to the output directory. + PROJECT_LOGO = logo.svg + +# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path +# into which the generated documentation will be written. If a relative path is +# entered, it will be relative to the location where doxygen was started. If +# left blank the current directory will be used. + OUTPUT_DIRECTORY = . + +# If the CREATE_SUBDIRS tag is set to YES then doxygen will create up to 4096 +# sub-directories (in 2 levels) under the output directory of each output format +# and will distribute the generated files over these directories. Enabling this +# option can be useful when feeding doxygen a huge amount of source files, where +# putting all generated files in the same directory would otherwise causes +# performance problems for the file system. Adapt CREATE_SUBDIRS_LEVEL to +# control the number of sub-directories. +# The default value is: NO. + CREATE_SUBDIRS = YES + +# Controls the number of sub-directories that will be created when +# CREATE_SUBDIRS tag is set to YES. Level 0 represents 16 directories, and every +# level increment doubles the number of directories, resulting in 4096 +# directories at level 8 which is the default and also the maximum value. The +# sub-directories are organized in 2 levels, the first level always has a fixed +# number of 16 directories. +# Minimum value: 0, maximum value: 8, default value: 8. +# This tag requires that the tag CREATE_SUBDIRS is set to YES. + +# CREATE_SUBDIRS_LEVEL = 8 + +# If the ALLOW_UNICODE_NAMES tag is set to YES, doxygen will allow non-ASCII +# characters to appear in the names of generated files. If set to NO, non-ASCII +# characters will be escaped, for example _xE3_x81_x84 will be used for Unicode +# U+3044. +# The default value is: NO. + +ALLOW_UNICODE_NAMES = NO + +# The OUTPUT_LANGUAGE tag is used to specify the language in which all +# documentation generated by doxygen is written. Doxygen will use this +# information to generate all constant output in the proper language. +# Possible values are: Afrikaans, Arabic, Armenian, Brazilian, Bulgarian, +# Catalan, Chinese, Chinese-Traditional, Croatian, Czech, Danish, Dutch, English +# (United States), Esperanto, Farsi (Persian), Finnish, French, German, Greek, +# Hindi, Hungarian, Indonesian, Italian, Japanese, Japanese-en (Japanese with +# English messages), Korean, Korean-en (Korean with English messages), Latvian, +# Lithuanian, Macedonian, Norwegian, Persian (Farsi), Polish, Portuguese, +# Romanian, Russian, Serbian, Serbian-Cyrillic, Slovak, Slovene, Spanish, +# Swedish, Turkish, Ukrainian and Vietnamese. +# The default value is: English. + OUTPUT_LANGUAGE = English + +# If the BRIEF_MEMBER_DESC tag is set to YES, doxygen will include brief member +# descriptions after the members that are listed in the file and class +# documentation (similar to Javadoc). Set to NO to disable this. +# The default value is: YES. + BRIEF_MEMBER_DESC = YES + +# If the REPEAT_BRIEF tag is set to YES, doxygen will prepend the brief +# description of a member or function before the detailed description +# +# Note: If both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the +# brief descriptions will be completely suppressed. +# The default value is: YES. + REPEAT_BRIEF = YES + +# This tag implements a quasi-intelligent brief description abbreviator that is +# used to form the text in various listings. Each string in this list, if found +# as the leading text of the brief description, will be stripped from the text +# and the result, after processing the whole list, is used as the annotated +# text. Otherwise, the brief description is used as-is. If left blank, the +# following values are used ($name is automatically replaced with the name of +# the entity):The $name class, The $name widget, The $name file, is, provides, +# specifies, contains, represents, a, an and the. + ABBREVIATE_BRIEF = "The $name class" \ "The $name widget" \ "The $name file" \ @@ -23,282 +150,2550 @@ ABBREVIATE_BRIEF = "The $name class" \ a \ an \ the + +# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then +# doxygen will generate a detailed section even if there is only a brief +# description. +# The default value is: NO. + ALWAYS_DETAILED_SEC = NO + +# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all +# inherited members of a class in the documentation of that class as if those +# members were ordinary class members. Constructors, destructors and assignment +# operators of the base classes will not be shown. +# The default value is: NO. + INLINE_INHERITED_MEMB = NO + +# If the FULL_PATH_NAMES tag is set to YES, doxygen will prepend the full path +# before files name in the file list and in the header files. If set to NO the +# shortest path that makes the file name unique will be used +# The default value is: YES. + FULL_PATH_NAMES = YES + +# The STRIP_FROM_PATH tag can be used to strip a user-defined part of the path. +# Stripping is only done if one of the specified strings matches the left-hand +# part of the path. The tag can be used to show relative paths in the file list. +# If left blank the directory from which doxygen is run is used as the path to +# strip. +# +# Note that you can specify absolute paths here, but also relative paths, which +# will be relative from the directory where doxygen is started. +# This tag requires that the tag FULL_PATH_NAMES is set to YES. + STRIP_FROM_PATH = ../.. + +# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the +# path mentioned in the documentation of a class, which tells the reader which +# header file to include in order to use a class. If left blank only the name of +# the header file containing the class definition is used. Otherwise one should +# specify the list of include paths that are normally passed to the compiler +# using the -I flag. + STRIP_FROM_INC_PATH = ../../src/include \ src/include \ include + +# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter (but +# less readable) file names. This can be useful is your file systems doesn't +# support long names like on DOS, Mac, or CD-ROM. +# The default value is: NO. + SHORT_NAMES = NO + +# If the JAVADOC_AUTOBRIEF tag is set to YES then doxygen will interpret the +# first line (until the first dot) of a Javadoc-style comment as the brief +# description. If set to NO, the Javadoc-style will behave just like regular Qt- +# style comments (thus requiring an explicit @brief command for a brief +# description.) +# The default value is: NO. + JAVADOC_AUTOBRIEF = YES + +# If the JAVADOC_BANNER tag is set to YES then doxygen will interpret a line +# such as +# /*************** +# as being the beginning of a Javadoc-style comment "banner". If set to NO, the +# Javadoc-style will behave just like regular comments and it will not be +# interpreted by doxygen. +# The default value is: NO. + +JAVADOC_BANNER = NO + +# If the QT_AUTOBRIEF tag is set to YES then doxygen will interpret the first +# line (until the first dot) of a Qt-style comment as the brief description. If +# set to NO, the Qt-style will behave just like regular Qt-style comments (thus +# requiring an explicit \brief command for a brief description.) +# The default value is: NO. + QT_AUTOBRIEF = NO + +# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make doxygen treat a +# multi-line C++ special comment block (i.e. a block of //! or /// comments) as +# a brief description. This used to be the default behavior. The new default is +# to treat a multi-line C++ comment block as a detailed description. Set this +# tag to YES if you prefer the old behavior instead. +# +# Note that setting this tag to YES also means that rational rose comments are +# not recognized any more. +# The default value is: NO. + MULTILINE_CPP_IS_BRIEF = NO + +# By default Python docstrings are displayed as preformatted text and doxygen's +# special commands cannot be used. By setting PYTHON_DOCSTRING to NO the +# doxygen's special commands can be used and the contents of the docstring +# documentation blocks is shown as doxygen documentation. +# The default value is: YES. + +PYTHON_DOCSTRING = YES + +# If the INHERIT_DOCS tag is set to YES then an undocumented member inherits the +# documentation from any documented member that it re-implements. +# The default value is: YES. + INHERIT_DOCS = YES + +# If the SEPARATE_MEMBER_PAGES tag is set to YES then doxygen will produce a new +# page for each member. If set to NO, the documentation of a member will be part +# of the file/class/namespace that contains it. +# The default value is: NO. + SEPARATE_MEMBER_PAGES = NO + +# The TAB_SIZE tag can be used to set the number of spaces in a tab. Doxygen +# uses this value to replace tabs by spaces in code fragments. +# Minimum value: 1, maximum value: 16, default value: 4. + TAB_SIZE = 8 + +# This tag can be used to specify a number of aliases that act as commands in +# the documentation. An alias has the form: +# name=value +# For example adding +# "sideeffect=@par Side Effects:^^" +# will allow you to put the command \sideeffect (or @sideeffect) in the +# documentation, which will result in a user-defined paragraph with heading +# "Side Effects:". Note that you cannot put \n's in the value part of an alias +# to insert newlines (in the resulting output). You can put ^^ in the value part +# of an alias to insert a newline as if a physical newline was in the original +# file. When you need a literal { or } or , in the value part of an alias you +# have to escape them by means of a backslash (\), this can lead to conflicts +# with the commands \{ and \} for these it is advised to use the version @{ and +# @} or use a double escape (\\{ and \\}) + ALIASES = + +# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources +# only. Doxygen will then generate output that is more tailored for C. For +# instance, some of the names that are used will be different. The list of all +# members will be omitted, etc. +# The default value is: NO. + OPTIMIZE_OUTPUT_FOR_C = YES + +# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java or +# Python sources only. Doxygen will then generate output that is more tailored +# for that language. For instance, namespaces will be presented as packages, +# qualified scopes will look different, etc. +# The default value is: NO. + OPTIMIZE_OUTPUT_JAVA = NO + +# Set the OPTIMIZE_FOR_FORTRAN tag to YES if your project consists of Fortran +# sources. Doxygen will then generate output that is tailored for Fortran. +# The default value is: NO. + OPTIMIZE_FOR_FORTRAN = NO + +# Set the OPTIMIZE_OUTPUT_VHDL tag to YES if your project consists of VHDL +# sources. Doxygen will then generate output that is tailored for VHDL. +# The default value is: NO. + OPTIMIZE_OUTPUT_VHDL = NO + +# Set the OPTIMIZE_OUTPUT_SLICE tag to YES if your project consists of Slice +# sources only. Doxygen will then generate output that is more tailored for that +# language. For instance, namespaces will be presented as modules, types will be +# separated into more groups, etc. +# The default value is: NO. + +OPTIMIZE_OUTPUT_SLICE = NO + +# Doxygen selects the parser to use depending on the extension of the files it +# parses. With this tag you can assign which parser to use for a given +# extension. Doxygen has a built-in mapping, but you can override or extend it +# using this tag. The format is ext=language, where ext is a file extension, and +# language is one of the parsers supported by doxygen: IDL, Java, JavaScript, +# Csharp (C#), C, C++, Lex, D, PHP, md (Markdown), Objective-C, Python, Slice, +# VHDL, Fortran (fixed format Fortran: FortranFixed, free formatted Fortran: +# FortranFree, unknown formatted Fortran: Fortran. In the later case the parser +# tries to guess whether the code is fixed or free formatted code, this is the +# default for Fortran type files). For instance to make doxygen treat .inc files +# as Fortran files (default is PHP), and .f files as C (default is Fortran), +# use: inc=Fortran f=C. +# +# Note: For files without extension you can use no_extension as a placeholder. +# +# Note that for custom extensions you also need to set FILE_PATTERNS otherwise +# the files are not read by doxygen. When specifying no_extension you should add +# * to the FILE_PATTERNS. +# +# Note see also the list of default file extension mappings. + +EXTENSION_MAPPING = + +# If the MARKDOWN_SUPPORT tag is enabled then doxygen pre-processes all comments +# according to the Markdown format, which allows for more readable +# documentation. See https://daringfireball.net/projects/markdown/ for details. +# The output of markdown processing is further processed by doxygen, so you can +# mix doxygen, HTML, and XML commands with Markdown formatting. Disable only in +# case of backward compatibilities issues. +# The default value is: YES. + +MARKDOWN_SUPPORT = YES + +# When the TOC_INCLUDE_HEADINGS tag is set to a non-zero value, all headings up +# to that level are automatically included in the table of contents, even if +# they do not have an id attribute. +# Note: This feature currently applies only to Markdown headings. +# Minimum value: 0, maximum value: 99, default value: 5. +# This tag requires that the tag MARKDOWN_SUPPORT is set to YES. + +TOC_INCLUDE_HEADINGS = 5 + +# When enabled doxygen tries to link words that correspond to documented +# classes, or namespaces to their corresponding documentation. Such a link can +# be prevented in individual cases by putting a % sign in front of the word or +# globally by setting AUTOLINK_SUPPORT to NO. +# The default value is: YES. + +AUTOLINK_SUPPORT = YES + +# If you use STL classes (i.e. std::string, std::vector, etc.) but do not want +# to include (a tag file for) the STL sources as input, then you should set this +# tag to YES in order to let doxygen match functions declarations and +# definitions whose arguments contain STL classes (e.g. func(std::string); +# versus func(std::string) {}). This also make the inheritance and collaboration +# diagrams that involve STL classes more complete and accurate. +# The default value is: NO. + BUILTIN_STL_SUPPORT = NO + +# If you use Microsoft's C++/CLI language, you should set this option to YES to +# enable parsing support. +# The default value is: NO. + CPP_CLI_SUPPORT = NO + +# Set the SIP_SUPPORT tag to YES if your project consists of sip (see: +# https://www.riverbankcomputing.com/software/sip/intro) sources only. Doxygen +# will parse them like normal C++ but will assume all classes use public instead +# of private inheritance when no explicit protection keyword is present. +# The default value is: NO. + SIP_SUPPORT = NO + +# For Microsoft's IDL there are propget and propput attributes to indicate +# getter and setter methods for a property. Setting this option to YES will make +# doxygen to replace the get and set methods by a property in the documentation. +# This will only work if the methods are indeed getting or setting a simple +# type. If this is not the case, or you want to show the methods anyway, you +# should set this option to NO. +# The default value is: YES. + IDL_PROPERTY_SUPPORT = YES + +# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC +# tag is set to YES then doxygen will reuse the documentation of the first +# member in the group (if any) for the other members of the group. By default +# all members of a group must be documented explicitly. +# The default value is: NO. + DISTRIBUTE_GROUP_DOC = NO + +# If one adds a struct or class to a group and this option is enabled, then also +# any nested class or struct is added to the same group. By default this option +# is disabled and one has to add nested compounds explicitly via \ingroup. +# The default value is: NO. + +GROUP_NESTED_COMPOUNDS = NO + +# Set the SUBGROUPING tag to YES to allow class member groups of the same type +# (for instance a group of public functions) to be put as a subgroup of that +# type (e.g. under the Public Functions section). Set it to NO to prevent +# subgrouping. Alternatively, this can be done per class using the +# \nosubgrouping command. +# The default value is: YES. + SUBGROUPING = YES + +# When the INLINE_GROUPED_CLASSES tag is set to YES, classes, structs and unions +# are shown inside the group in which they are included (e.g. using \ingroup) +# instead of on a separate page (for HTML and Man pages) or section (for LaTeX +# and RTF). +# +# Note that this feature does not work in combination with +# SEPARATE_MEMBER_PAGES. +# The default value is: NO. + +INLINE_GROUPED_CLASSES = NO + +# When the INLINE_SIMPLE_STRUCTS tag is set to YES, structs, classes, and unions +# with only public data fields or simple typedef fields will be shown inline in +# the documentation of the scope in which they are defined (i.e. file, +# namespace, or group documentation), provided this scope is documented. If set +# to NO, structs, classes, and unions are shown on a separate page (for HTML and +# Man pages) or section (for LaTeX and RTF). +# The default value is: NO. + +INLINE_SIMPLE_STRUCTS = NO + +# When TYPEDEF_HIDES_STRUCT tag is enabled, a typedef of a struct, union, or +# enum is documented as struct, union, or enum with the name of the typedef. So +# typedef struct TypeS {} TypeT, will appear in the documentation as a struct +# with name TypeT. When disabled the typedef will appear as a member of a file, +# namespace, or class. And the struct will be named TypeS. This can typically be +# useful for C code in case the coding convention dictates that all compound +# types are typedef'ed and only the typedef is referenced, never the tag name. +# The default value is: NO. + TYPEDEF_HIDES_STRUCT = NO + +# The size of the symbol lookup cache can be set using LOOKUP_CACHE_SIZE. This +# cache is used to resolve symbols given their name and scope. Since this can be +# an expensive process and often the same symbol appears multiple times in the +# code, doxygen keeps a cache of pre-resolved symbols. If the cache is too small +# doxygen will become slower. If the cache is too large, memory is wasted. The +# cache size is given by this formula: 2^(16+LOOKUP_CACHE_SIZE). The valid range +# is 0..9, the default is 0, corresponding to a cache size of 2^16=65536 +# symbols. At the end of a run doxygen will report the cache usage and suggest +# the optimal cache size from a speed point of view. +# Minimum value: 0, maximum value: 9, default value: 0. + +LOOKUP_CACHE_SIZE = 0 + +# The NUM_PROC_THREADS specifies the number of threads doxygen is allowed to use +# during processing. When set to 0 doxygen will based this on the number of +# cores available in the system. You can set it explicitly to a value larger +# than 0 to get more control over the balance between CPU load and processing +# speed. At this moment only the input processing can be done using multiple +# threads. Since this is still an experimental feature the default is set to 1, +# which effectively disables parallel processing. Please report any issues you +# encounter. Generating dot graphs in parallel is controlled by the +# DOT_NUM_THREADS setting. +# Minimum value: 0, maximum value: 32, default value: 1. + +NUM_PROC_THREADS = 1 + #--------------------------------------------------------------------------- # Build related configuration options #--------------------------------------------------------------------------- + +# If the EXTRACT_ALL tag is set to YES, doxygen will assume all entities in +# documentation are documented, even if no documentation was available. Private +# class members and static file members will be hidden unless the +# EXTRACT_PRIVATE respectively EXTRACT_STATIC tags are set to YES. +# Note: This will also disable the warnings about undocumented members that are +# normally produced when WARNINGS is set to YES. +# The default value is: NO. + EXTRACT_ALL = YES + +# If the EXTRACT_PRIVATE tag is set to YES, all private members of a class will +# be included in the documentation. +# The default value is: NO. + EXTRACT_PRIVATE = NO + +# If the EXTRACT_PRIV_VIRTUAL tag is set to YES, documented private virtual +# methods of a class will be included in the documentation. +# The default value is: NO. + +EXTRACT_PRIV_VIRTUAL = NO + +# If the EXTRACT_PACKAGE tag is set to YES, all members with package or internal +# scope will be included in the documentation. +# The default value is: NO. + +EXTRACT_PACKAGE = NO + +# If the EXTRACT_STATIC tag is set to YES, all static members of a file will be +# included in the documentation. +# The default value is: NO. + EXTRACT_STATIC = YES + +# If the EXTRACT_LOCAL_CLASSES tag is set to YES, classes (and structs) defined +# locally in source files will be included in the documentation. If set to NO, +# only classes defined in header files are included. Does not have any effect +# for Java sources. +# The default value is: YES. + EXTRACT_LOCAL_CLASSES = NO + +# This flag is only useful for Objective-C code. If set to YES, local methods, +# which are defined in the implementation section but not in the interface are +# included in the documentation. If set to NO, only methods in the interface are +# included. +# The default value is: NO. + EXTRACT_LOCAL_METHODS = NO + +# If this flag is set to YES, the members of anonymous namespaces will be +# extracted and appear in the documentation as a namespace called +# 'anonymous_namespace{file}', where file will be replaced with the base name of +# the file that contains the anonymous namespace. By default anonymous namespace +# are hidden. +# The default value is: NO. + EXTRACT_ANON_NSPACES = YES + +# If this flag is set to YES, the name of an unnamed parameter in a declaration +# will be determined by the corresponding definition. By default unnamed +# parameters remain unnamed in the output. +# The default value is: YES. + +RESOLVE_UNNAMED_PARAMS = YES + +# If the HIDE_UNDOC_MEMBERS tag is set to YES, doxygen will hide all +# undocumented members inside documented classes or files. If set to NO these +# members will be included in the various overviews, but no documentation +# section is generated. This option has no effect if EXTRACT_ALL is enabled. +# The default value is: NO. + HIDE_UNDOC_MEMBERS = NO + +# If the HIDE_UNDOC_CLASSES tag is set to YES, doxygen will hide all +# undocumented classes that are normally visible in the class hierarchy. If set +# to NO, these classes will be included in the various overviews. This option +# has no effect if EXTRACT_ALL is enabled. +# The default value is: NO. + HIDE_UNDOC_CLASSES = NO + +# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, doxygen will hide all friend +# declarations. If set to NO, these declarations will be included in the +# documentation. +# The default value is: NO. + HIDE_FRIEND_COMPOUNDS = NO + +# If the HIDE_IN_BODY_DOCS tag is set to YES, doxygen will hide any +# documentation blocks found inside the body of a function. If set to NO, these +# blocks will be appended to the function's detailed documentation block. +# The default value is: NO. + HIDE_IN_BODY_DOCS = NO + +# The INTERNAL_DOCS tag determines if documentation that is typed after a +# \internal command is included. If the tag is set to NO then the documentation +# will be excluded. Set it to YES to include the internal documentation. +# The default value is: NO. + INTERNAL_DOCS = YES + +# With the correct setting of option CASE_SENSE_NAMES doxygen will better be +# able to match the capabilities of the underlying filesystem. In case the +# filesystem is case sensitive (i.e. it supports files in the same directory +# whose names only differ in casing), the option must be set to YES to properly +# deal with such files in case they appear in the input. For filesystems that +# are not case sensitive the option should be set to NO to properly deal with +# output files written for symbols that only differ in casing, such as for two +# classes, one named CLASS and the other named Class, and to also support +# references to files without having to specify the exact matching casing. On +# Windows (including Cygwin) and MacOS, users should typically set this option +# to NO, whereas on Linux or other Unix flavors it should typically be set to +# YES. +# The default value is: system dependent. + CASE_SENSE_NAMES = YES + +# If the HIDE_SCOPE_NAMES tag is set to NO then doxygen will show members with +# their full class and namespace scopes in the documentation. If set to YES, the +# scope will be hidden. +# The default value is: NO. + HIDE_SCOPE_NAMES = NO + +# If the HIDE_COMPOUND_REFERENCE tag is set to NO (default) then doxygen will +# append additional text to a page's title, such as Class Reference. If set to +# YES the compound reference will be hidden. +# The default value is: NO. + +HIDE_COMPOUND_REFERENCE= NO + +# If the SHOW_HEADERFILE tag is set to YES then the documentation for a class +# will show which file needs to be included to use the class. +# The default value is: YES. + +# SHOW_HEADERFILE = YES + +# If the SHOW_INCLUDE_FILES tag is set to YES then doxygen will put a list of +# the files that are included by a file in the documentation of that file. +# The default value is: YES. + SHOW_INCLUDE_FILES = YES + +# If the SHOW_GROUPED_MEMB_INC tag is set to YES then Doxygen will add for each +# grouped member an include statement to the documentation, telling the reader +# which file to include in order to use the member. +# The default value is: NO. + +SHOW_GROUPED_MEMB_INC = NO + +# If the FORCE_LOCAL_INCLUDES tag is set to YES then doxygen will list include +# files with double quotes in the documentation rather than with sharp brackets. +# The default value is: NO. + +FORCE_LOCAL_INCLUDES = NO + +# If the INLINE_INFO tag is set to YES then a tag [inline] is inserted in the +# documentation for inline members. +# The default value is: YES. + INLINE_INFO = YES + +# If the SORT_MEMBER_DOCS tag is set to YES then doxygen will sort the +# (detailed) documentation of file and class members alphabetically by member +# name. If set to NO, the members will appear in declaration order. +# The default value is: YES. + SORT_MEMBER_DOCS = NO + +# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the brief +# descriptions of file, namespace and class members alphabetically by member +# name. If set to NO, the members will appear in declaration order. Note that +# this will also influence the order of the classes in the class list. +# The default value is: NO. + SORT_BRIEF_DOCS = NO + +# If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen will sort the +# (brief and detailed) documentation of class members so that constructors and +# destructors are listed first. If set to NO the constructors will appear in the +# respective orders defined by SORT_BRIEF_DOCS and SORT_MEMBER_DOCS. +# Note: If SORT_BRIEF_DOCS is set to NO this option is ignored for sorting brief +# member documentation. +# Note: If SORT_MEMBER_DOCS is set to NO this option is ignored for sorting +# detailed member documentation. +# The default value is: NO. + +SORT_MEMBERS_CTORS_1ST = NO + +# If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the hierarchy +# of group names into alphabetical order. If set to NO the group names will +# appear in their defined order. +# The default value is: NO. + SORT_GROUP_NAMES = YES + +# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be sorted by +# fully-qualified names, including namespaces. If set to NO, the class list will +# be sorted only by class name, not including the namespace part. +# Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES. +# Note: This option applies only to the class list, not to the alphabetical +# list. +# The default value is: NO. + SORT_BY_SCOPE_NAME = NO + +# If the STRICT_PROTO_MATCHING option is enabled and doxygen fails to do proper +# type resolution of all parameters of a function it will reject a match between +# the prototype and the implementation of a member function even if there is +# only one candidate or it is obvious which candidate to choose by doing a +# simple string match. By disabling STRICT_PROTO_MATCHING doxygen will still +# accept a match between prototype and implementation in such cases. +# The default value is: NO. + +STRICT_PROTO_MATCHING = NO + +# The GENERATE_TODOLIST tag can be used to enable (YES) or disable (NO) the todo +# list. This list is created by putting \todo commands in the documentation. +# The default value is: YES. + GENERATE_TODOLIST = YES + +# The GENERATE_TESTLIST tag can be used to enable (YES) or disable (NO) the test +# list. This list is created by putting \test commands in the documentation. +# The default value is: YES. + GENERATE_TESTLIST = YES + +# The GENERATE_BUGLIST tag can be used to enable (YES) or disable (NO) the bug +# list. This list is created by putting \bug commands in the documentation. +# The default value is: YES. + GENERATE_BUGLIST = YES + +# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or disable (NO) +# the deprecated list. This list is created by putting \deprecated commands in +# the documentation. +# The default value is: YES. + GENERATE_DEPRECATEDLIST= YES + +# The ENABLED_SECTIONS tag can be used to enable conditional documentation +# sections, marked by \if <section_label> ... \endif and \cond <section_label> +# ... \endcond blocks. + ENABLED_SECTIONS = + +# The MAX_INITIALIZER_LINES tag determines the maximum number of lines that the +# initial value of a variable or macro / define can have for it to appear in the +# documentation. If the initializer consists of more lines than specified here +# it will be hidden. Use a value of 0 to hide initializers completely. The +# appearance of the value of individual variables and macros / defines can be +# controlled using \showinitializer or \hideinitializer command in the +# documentation regardless of this setting. +# Minimum value: 0, maximum value: 10000, default value: 30. + MAX_INITIALIZER_LINES = 30 + +# Set the SHOW_USED_FILES tag to NO to disable the list of files generated at +# the bottom of the documentation of classes and structs. If set to YES, the +# list will mention the files that were used to generate the documentation. +# The default value is: YES. + SHOW_USED_FILES = YES + +# Set the SHOW_FILES tag to NO to disable the generation of the Files page. This +# will remove the Files entry from the Quick Index and from the Folder Tree View +# (if specified). +# The default value is: YES. + SHOW_FILES = YES + +# Set the SHOW_NAMESPACES tag to NO to disable the generation of the Namespaces +# page. This will remove the Namespaces entry from the Quick Index and from the +# Folder Tree View (if specified). +# The default value is: YES. + SHOW_NAMESPACES = YES + +# The FILE_VERSION_FILTER tag can be used to specify a program or script that +# doxygen should invoke to get the current version for each file (typically from +# the version control system). Doxygen will invoke the program by executing (via +# popen()) the command command input-file, where command is the value of the +# FILE_VERSION_FILTER tag, and input-file is the name of an input file provided +# by doxygen. Whatever the program writes to standard output is used as the file +# version. For an example see the documentation. + FILE_VERSION_FILTER = + +# The LAYOUT_FILE tag can be used to specify a layout file which will be parsed +# by doxygen. The layout file controls the global structure of the generated +# output files in an output format independent way. To create the layout file +# that represents doxygen's defaults, run doxygen with the -l option. You can +# optionally specify a file name after the option, if omitted DoxygenLayout.xml +# will be used as the name of the layout file. See also section "Changing the +# layout of pages" for information. +# +# Note that if you run doxygen from a directory containing a file called +# DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE +# tag is left empty. + +LAYOUT_FILE = + +# The CITE_BIB_FILES tag can be used to specify one or more bib files containing +# the reference definitions. This must be a list of .bib files. The .bib +# extension is automatically appended if omitted. This requires the bibtex tool +# to be installed. See also https://en.wikipedia.org/wiki/BibTeX for more info. +# For LaTeX the style of the bibliography can be controlled using +# LATEX_BIB_STYLE. To use this feature you need bibtex and perl available in the +# search path. See also \cite for info how to create references. + +CITE_BIB_FILES = + #--------------------------------------------------------------------------- -# configuration options related to warning and progress messages +# Configuration options related to warning and progress messages #--------------------------------------------------------------------------- + +# The QUIET tag can be used to turn on/off the messages that are generated to +# standard output by doxygen. If QUIET is set to YES this implies that the +# messages are off. +# The default value is: NO. + QUIET = YES + +# The WARNINGS tag can be used to turn on/off the warning messages that are +# generated to standard error (stderr) by doxygen. If WARNINGS is set to YES +# this implies that the warnings are on. +# +# Tip: Turn warnings on while writing the documentation. +# The default value is: YES. + WARNINGS = YES + +# If the WARN_IF_UNDOCUMENTED tag is set to YES then doxygen will generate +# warnings for undocumented members. If EXTRACT_ALL is set to YES then this flag +# will automatically be disabled. +# The default value is: YES. + WARN_IF_UNDOCUMENTED = YES + +# If the WARN_IF_DOC_ERROR tag is set to YES, doxygen will generate warnings for +# potential errors in the documentation, such as documenting some parameters in +# a documented function twice, or documenting parameters that don't exist or +# using markup commands wrongly. +# The default value is: YES. + WARN_IF_DOC_ERROR = YES + +# If WARN_IF_INCOMPLETE_DOC is set to YES, doxygen will warn about incomplete +# function parameter documentation. If set to NO, doxygen will accept that some +# parameters have no documentation without warning. +# The default value is: YES. + +# WARN_IF_INCOMPLETE_DOC = YES + +# This WARN_NO_PARAMDOC option can be enabled to get warnings for functions that +# are documented, but have no documentation for their parameters or return +# value. If set to NO, doxygen will only warn about wrong parameter +# documentation, but not about the absence of documentation. If EXTRACT_ALL is +# set to YES then this flag will automatically be disabled. See also +# WARN_IF_INCOMPLETE_DOC +# The default value is: NO. + WARN_NO_PARAMDOC = YES -WARN_FORMAT = "$file:$line: $text" + +# If the WARN_AS_ERROR tag is set to YES then doxygen will immediately stop when +# a warning is encountered. If the WARN_AS_ERROR tag is set to FAIL_ON_WARNINGS +# then doxygen will continue running as if WARN_AS_ERROR tag is set to NO, but +# at the end of the doxygen process doxygen will return with a non-zero status. +# Possible values are: NO, YES and FAIL_ON_WARNINGS. +# The default value is: NO. + +WARN_AS_ERROR = FAIL_ON_WARNINGS + +# The WARN_FORMAT tag determines the format of the warning messages that doxygen +# can produce. The string should contain the $file, $line, and $text tags, which +# will be replaced by the file and line number from which the warning originated +# and the warning text. Optionally the format may contain $version, which will +# be replaced by the version of the file (if it could be obtained via +# FILE_VERSION_FILTER) +# See also: WARN_LINE_FORMAT +# The default value is: $file:$line: $text. + +# WARN_FORMAT = "$file:$line: $text" + +# In the $text part of the WARN_FORMAT command it is possible that a reference +# to a more specific place is given. To make it easier to jump to this place +# (outside of doxygen) the user can define a custom "cut" / "paste" string. +# Example: +# WARN_LINE_FORMAT = "'vi $file +$line'" +# See also: WARN_FORMAT +# The default value is: at line $line of file $file. + +WARN_LINE_FORMAT = "at line $line of file $file" + +# The WARN_LOGFILE tag can be used to specify a file to which warning and error +# messages should be written. If left blank the output is written to standard +# error (stderr). In case the file specified cannot be opened for writing the +# warning and error messages are written to standard error. When as file - is +# specified the warning and error messages are written to standard output +# (stdout). + WARN_LOGFILE = + #--------------------------------------------------------------------------- -# configuration options related to the input files +# Configuration options related to the input files #--------------------------------------------------------------------------- + +# The INPUT tag is used to specify the files and/or directories that contain +# documented source files. You may enter file names like myfile.cpp or +# directories like /usr/src/myproject. Separate the files or directories with +# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING +# Note: If this tag is empty the current directory is searched. + INPUT = ../../src + +# This tag can be used to specify the character encoding of the source files +# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses +# libiconv (or the iconv built into libc) for the transcoding. See the libiconv +# documentation (see: +# https://www.gnu.org/software/libiconv/) for the list of possible encodings. +# The default value is: UTF-8. + INPUT_ENCODING = UTF-8 + +# If the value of the INPUT tag contains directories, you can use the +# FILE_PATTERNS tag to specify one or more wildcard patterns (like *.cpp and +# *.h) to filter out the source-files in the directories. +# +# Note that for custom extensions or not directly supported extensions you also +# need to set EXTENSION_MAPPING for the extension otherwise the files are not +# read by doxygen. +# +# Note the list of default checked file patterns might differ from the list of +# default file extension mappings. +# +# If left blank the following patterns are tested:*.c, *.cc, *.cxx, *.cpp, +# *.c++, *.java, *.ii, *.ixx, *.ipp, *.i++, *.inl, *.idl, *.ddl, *.odl, *.h, +# *.hh, *.hxx, *.hpp, *.h++, *.l, *.cs, *.d, *.php, *.php4, *.php5, *.phtml, +# *.inc, *.m, *.markdown, *.md, *.mm, *.dox (to be provided as doxygen C +# comment), *.py, *.pyw, *.f90, *.f95, *.f03, *.f08, *.f18, *.f, *.for, *.vhd, +# *.vhdl, *.ucf, *.qsf and *.ice. + FILE_PATTERNS = *.c \ - *.cc \ - *.cxx \ - *.cpp \ - *.c++ \ - *.d \ - *.java \ - *.ii \ - *.ixx \ - *.ipp \ - *.i++ \ - *.inl \ - *.h \ - *.hh \ - *.hxx \ - *.hpp \ - *.h++ \ - *.idl \ - *.odl \ - *.cs \ - *.php \ - *.php3 \ - *.inc \ - *.m \ - *.mm \ - *.dox \ - *.py \ - *.f90 \ - *.f \ - *.vhd \ - *.vhdl \ - *.C \ - *.CC \ - *.C++ \ - *.II \ - *.I++ \ - *.H \ - *.HH \ - *.H++ \ - *.CS \ - *.PHP \ - *.PHP3 \ - *.M \ - *.MM \ - *.PY \ - *.F90 \ - *.F \ - *.VHD \ - *.VHDL + *.h + +# The RECURSIVE tag can be used to specify whether or not subdirectories should +# be searched for input files as well. +# The default value is: NO. + RECURSIVE = YES + +# The EXCLUDE tag can be used to specify files and/or directories that should be +# excluded from the INPUT source files. This way you can easily exclude a +# subdirectory from a directory tree whose root is specified with the INPUT tag. +# +# Note that relative paths are relative to the directory from which doxygen is +# run. + EXCLUDE = + +# The EXCLUDE_SYMLINKS tag can be used to select whether or not files or +# directories that are symbolic links (a Unix file system feature) are excluded +# from the input. +# The default value is: NO. + EXCLUDE_SYMLINKS = NO + +# If the value of the INPUT tag contains directories, you can use the +# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude +# certain files from those directories. +# +# Note that the wildcards are matched against the file with absolute path, so to +# exclude all test directories for example use the pattern */test/* + EXCLUDE_PATTERNS = */test_* \ - */.svn/* \ */.git/* \ - */perf_* .* \ + */perf_* \ .* \ - */gnu-taler-error-codes/* + .* \ + */gnu-taler-error-codes/* \ + */src/templating/mustach* + +# The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names +# (namespaces, classes, functions, etc.) that should be excluded from the +# output. The symbol name can be a fully qualified name, a word, or if the +# wildcard * is used, a substring. Examples: ANamespace, AClass, +# ANamespace::AClass, ANamespace::*Test +# +# Note that the wildcards are matched against the file with absolute path, so to +# exclude all test directories use the pattern */test/* + EXCLUDE_SYMBOLS = + +# The EXAMPLE_PATH tag can be used to specify one or more files or directories +# that contain example code fragments that are included (see the \include +# command). + EXAMPLE_PATH = + +# If the value of the EXAMPLE_PATH tag contains directories, you can use the +# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and +# *.h) to filter out the source-files in the directories. If left blank all +# files are included. + EXAMPLE_PATTERNS = * + +# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be +# searched for input files to be used with the \include or \dontinclude commands +# irrespective of the value of the RECURSIVE tag. +# The default value is: NO. + EXAMPLE_RECURSIVE = NO + +# The IMAGE_PATH tag can be used to specify one or more files or directories +# that contain images that are to be included in the documentation (see the +# \image command). + IMAGE_PATH = + +# The INPUT_FILTER tag can be used to specify a program that doxygen should +# invoke to filter for each input file. Doxygen will invoke the filter program +# by executing (via popen()) the command: +# +# <filter> <input-file> +# +# where <filter> is the value of the INPUT_FILTER tag, and <input-file> is the +# name of an input file. Doxygen will then use the output that the filter +# program writes to standard output. If FILTER_PATTERNS is specified, this tag +# will be ignored. +# +# Note that the filter must not add or remove lines; it is applied before the +# code is scanned, but not when the output code is generated. If lines are added +# or removed, the anchors will not be placed correctly. +# +# Note that for custom extensions or not directly supported extensions you also +# need to set EXTENSION_MAPPING for the extension otherwise the files are not +# properly processed by doxygen. + INPUT_FILTER = + +# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern +# basis. Doxygen will compare the file name with each pattern and apply the +# filter if there is a match. The filters are a list of the form: pattern=filter +# (like *.cpp=my_cpp_filter). See INPUT_FILTER for further information on how +# filters are used. If the FILTER_PATTERNS tag is empty or if none of the +# patterns match the file name, INPUT_FILTER is applied. +# +# Note that for custom extensions or not directly supported extensions you also +# need to set EXTENSION_MAPPING for the extension otherwise the files are not +# properly processed by doxygen. + FILTER_PATTERNS = + +# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using +# INPUT_FILTER) will also be used to filter the input files that are used for +# producing the source files to browse (i.e. when SOURCE_BROWSER is set to YES). +# The default value is: NO. + FILTER_SOURCE_FILES = NO + +# The FILTER_SOURCE_PATTERNS tag can be used to specify source filters per file +# pattern. A pattern will override the setting for FILTER_PATTERN (if any) and +# it is also possible to disable source filtering for a specific pattern using +# *.ext= (so without naming a filter). +# This tag requires that the tag FILTER_SOURCE_FILES is set to YES. + +FILTER_SOURCE_PATTERNS = + +# If the USE_MDFILE_AS_MAINPAGE tag refers to the name of a markdown file that +# is part of the input, its contents will be placed on the main page +# (index.html). This can be useful if you have a project on for instance GitHub +# and want to reuse the introduction page also for the doxygen output. + +USE_MDFILE_AS_MAINPAGE = + #--------------------------------------------------------------------------- -# configuration options related to source browsing +# Configuration options related to source browsing #--------------------------------------------------------------------------- + +# If the SOURCE_BROWSER tag is set to YES then a list of source files will be +# generated. Documented entities will be cross-referenced with these sources. +# +# Note: To get rid of all source code in the generated output, make sure that +# also VERBATIM_HEADERS is set to NO. +# The default value is: NO. + SOURCE_BROWSER = YES + +# Setting the INLINE_SOURCES tag to YES will include the body of functions, +# classes and enums directly into the documentation. +# The default value is: NO. + INLINE_SOURCES = YES + +# Setting the STRIP_CODE_COMMENTS tag to YES will instruct doxygen to hide any +# special comment blocks from generated source code fragments. Normal C, C++ and +# Fortran comments will always remain visible. +# The default value is: YES. + STRIP_CODE_COMMENTS = YES + +# If the REFERENCED_BY_RELATION tag is set to YES then for each documented +# entity all documented functions referencing it will be listed. +# The default value is: NO. + REFERENCED_BY_RELATION = YES + +# If the REFERENCES_RELATION tag is set to YES then for each documented function +# all documented entities called/used by that function will be listed. +# The default value is: NO. + REFERENCES_RELATION = YES + +# If the REFERENCES_LINK_SOURCE tag is set to YES and SOURCE_BROWSER tag is set +# to YES then the hyperlinks from functions in REFERENCES_RELATION and +# REFERENCED_BY_RELATION lists will link to the source code. Otherwise they will +# link to the documentation. +# The default value is: YES. + REFERENCES_LINK_SOURCE = YES + +# If SOURCE_TOOLTIPS is enabled (the default) then hovering a hyperlink in the +# source code will show a tooltip with additional information such as prototype, +# brief description and links to the definition and documentation. Since this +# will make the HTML file larger and loading of large files a bit slower, you +# can opt to disable this feature. +# The default value is: YES. +# This tag requires that the tag SOURCE_BROWSER is set to YES. + +SOURCE_TOOLTIPS = YES + +# If the USE_HTAGS tag is set to YES then the references to source code will +# point to the HTML generated by the htags(1) tool instead of doxygen built-in +# source browser. The htags tool is part of GNU's global source tagging system +# (see https://www.gnu.org/software/global/global.html). You will need version +# 4.8.6 or higher. +# +# To use it do the following: +# - Install the latest version of global +# - Enable SOURCE_BROWSER and USE_HTAGS in the configuration file +# - Make sure the INPUT points to the root of the source tree +# - Run doxygen as normal +# +# Doxygen will invoke htags (and that will in turn invoke gtags), so these +# tools must be available from the command line (i.e. in the search path). +# +# The result: instead of the source browser generated by doxygen, the links to +# source code will now point to the output of htags. +# The default value is: NO. +# This tag requires that the tag SOURCE_BROWSER is set to YES. + USE_HTAGS = NO + +# If the VERBATIM_HEADERS tag is set the YES then doxygen will generate a +# verbatim copy of the header file for each class for which an include is +# specified. Set to NO to disable this. +# See also: Section \class. +# The default value is: YES. + VERBATIM_HEADERS = YES + +# If the CLANG_ASSISTED_PARSING tag is set to YES then doxygen will use the +# clang parser (see: +# http://clang.llvm.org/) for more accurate parsing at the cost of reduced +# performance. This can be particularly helpful with template rich C++ code for +# which doxygen's built-in parser lacks the necessary type information. +# Note: The availability of this option depends on whether or not doxygen was +# generated with the -Duse_libclang=ON option for CMake. +# The default value is: NO. + +CLANG_ASSISTED_PARSING = NO + +# If the CLANG_ASSISTED_PARSING tag is set to YES and the CLANG_ADD_INC_PATHS +# tag is set to YES then doxygen will add the directory of each input to the +# include path. +# The default value is: YES. +# This tag requires that the tag CLANG_ASSISTED_PARSING is set to YES. + +CLANG_ADD_INC_PATHS = YES + +# If clang assisted parsing is enabled you can provide the compiler with command +# line options that you would normally use when invoking the compiler. Note that +# the include paths will already be set by doxygen for the files and directories +# specified with INPUT and INCLUDE_PATH. +# This tag requires that the tag CLANG_ASSISTED_PARSING is set to YES. + +CLANG_OPTIONS = + +# If clang assisted parsing is enabled you can provide the clang parser with the +# path to the directory containing a file called compile_commands.json. This +# file is the compilation database (see: +# http://clang.llvm.org/docs/HowToSetupToolingForLLVM.html) containing the +# options used when the source files were built. This is equivalent to +# specifying the -p option to a clang tool, such as clang-check. These options +# will then be passed to the parser. Any options specified with CLANG_OPTIONS +# will be added as well. +# Note: The availability of this option depends on whether or not doxygen was +# generated with the -Duse_libclang=ON option for CMake. + +CLANG_DATABASE_PATH = + #--------------------------------------------------------------------------- -# configuration options related to the alphabetical class index +# Configuration options related to the alphabetical class index #--------------------------------------------------------------------------- + +# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index of all +# compounds will be generated. Enable this if the project contains a lot of +# classes, structs, unions or interfaces. +# The default value is: YES. + ALPHABETICAL_INDEX = YES + +# In case all classes in a project start with a common prefix, all classes will +# be put under the same header in the alphabetical index. The IGNORE_PREFIX tag +# can be used to specify a prefix (or a list of prefixes) that should be ignored +# while generating the index headers. +# This tag requires that the tag ALPHABETICAL_INDEX is set to YES. + IGNORE_PREFIX = TALER_ + #--------------------------------------------------------------------------- -# configuration options related to the HTML output +# Configuration options related to the HTML output #--------------------------------------------------------------------------- + +# If the GENERATE_HTML tag is set to YES, doxygen will generate HTML output +# The default value is: YES. + GENERATE_HTML = YES + +# The HTML_OUTPUT tag is used to specify where the HTML docs will be put. If a +# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of +# it. +# The default directory is: html. +# This tag requires that the tag GENERATE_HTML is set to YES. + HTML_OUTPUT = html + +# The HTML_FILE_EXTENSION tag can be used to specify the file extension for each +# generated HTML page (for example: .htm, .php, .asp). +# The default value is: .html. +# This tag requires that the tag GENERATE_HTML is set to YES. + HTML_FILE_EXTENSION = .html + +# The HTML_HEADER tag can be used to specify a user-defined HTML header file for +# each generated HTML page. If the tag is left blank doxygen will generate a +# standard header. +# +# To get valid HTML the header file that includes any scripts and style sheets +# that doxygen needs, which is dependent on the configuration options used (e.g. +# the setting GENERATE_TREEVIEW). It is highly recommended to start with a +# default header using +# doxygen -w html new_header.html new_footer.html new_stylesheet.css +# YourConfigFile +# and then modify the file new_header.html. See also section "Doxygen usage" +# for information on how to generate the default header that doxygen normally +# uses. +# Note: The header is subject to change so you typically have to regenerate the +# default header when upgrading to a newer version of doxygen. For a description +# of the possible markers and block names see the documentation. +# This tag requires that the tag GENERATE_HTML is set to YES. + HTML_HEADER = + +# The HTML_FOOTER tag can be used to specify a user-defined HTML footer for each +# generated HTML page. If the tag is left blank doxygen will generate a standard +# footer. See HTML_HEADER for more information on how to generate a default +# footer and what special commands can be used inside the footer. See also +# section "Doxygen usage" for information on how to generate the default footer +# that doxygen normally uses. +# This tag requires that the tag GENERATE_HTML is set to YES. + HTML_FOOTER = + +# The HTML_STYLESHEET tag can be used to specify a user-defined cascading style +# sheet that is used by each HTML page. It can be used to fine-tune the look of +# the HTML output. If left blank doxygen will generate a default style sheet. +# See also section "Doxygen usage" for information on how to generate the style +# sheet that doxygen normally uses. +# Note: It is recommended to use HTML_EXTRA_STYLESHEET instead of this tag, as +# it is more robust and this tag (HTML_STYLESHEET) will in the future become +# obsolete. +# This tag requires that the tag GENERATE_HTML is set to YES. + HTML_STYLESHEET = -GENERATE_HTMLHELP = NO + +# The HTML_EXTRA_STYLESHEET tag can be used to specify additional user-defined +# cascading style sheets that are included after the standard style sheets +# created by doxygen. Using this option one can overrule certain style aspects. +# This is preferred over using HTML_STYLESHEET since it does not replace the +# standard style sheet and is therefore more robust against future updates. +# Doxygen will copy the style sheet files to the output directory. +# Note: The order of the extra style sheet files is of importance (e.g. the last +# style sheet in the list overrules the setting of the previous ones in the +# list). For an example see the documentation. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_EXTRA_STYLESHEET = + +# The HTML_EXTRA_FILES tag can be used to specify one or more extra images or +# other source files which should be copied to the HTML output directory. Note +# that these files will be copied to the base HTML output directory. Use the +# $relpath^ marker in the HTML_HEADER and/or HTML_FOOTER files to load these +# files. In the HTML_STYLESHEET file, use the file name only. Also note that the +# files will be copied as-is; there are no commands or markers available. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_EXTRA_FILES = + +# The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen +# will adjust the colors in the style sheet and background images according to +# this color. Hue is specified as an angle on a color-wheel, see +# https://en.wikipedia.org/wiki/Hue for more information. For instance the value +# 0 represents red, 60 is yellow, 120 is green, 180 is cyan, 240 is blue, 300 +# purple, and 360 is red again. +# Minimum value: 0, maximum value: 359, default value: 220. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_COLORSTYLE_HUE = 220 + +# The HTML_COLORSTYLE_SAT tag controls the purity (or saturation) of the colors +# in the HTML output. For a value of 0 the output will use gray-scales only. A +# value of 255 will produce the most vivid colors. +# Minimum value: 0, maximum value: 255, default value: 100. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_COLORSTYLE_SAT = 100 + +# The HTML_COLORSTYLE_GAMMA tag controls the gamma correction applied to the +# luminance component of the colors in the HTML output. Values below 100 +# gradually make the output lighter, whereas values above 100 make the output +# darker. The value divided by 100 is the actual gamma applied, so 80 represents +# a gamma of 0.8, The value 220 represents a gamma of 2.2, and 100 does not +# change the gamma. +# Minimum value: 40, maximum value: 240, default value: 80. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_COLORSTYLE_GAMMA = 80 + +# If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML +# page will contain the date and time when the page was generated. Setting this +# to YES can help to show when doxygen was last run and thus if the +# documentation is up to date. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_TIMESTAMP = NO + +# If the HTML_DYNAMIC_MENUS tag is set to YES then the generated HTML +# documentation will contain a main index with vertical navigation menus that +# are dynamically created via JavaScript. If disabled, the navigation index will +# consists of multiple levels of tabs that are statically embedded in every HTML +# page. Disable this option to support browsers that do not have JavaScript, +# like the Qt help browser. +# The default value is: YES. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_DYNAMIC_MENUS = YES + +# If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML +# documentation will contain sections that can be hidden and shown after the +# page has loaded. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_DYNAMIC_SECTIONS = NO + +# With HTML_INDEX_NUM_ENTRIES one can control the preferred number of entries +# shown in the various tree structured indices initially; the user can expand +# and collapse entries dynamically later on. Doxygen will expand the tree to +# such a level that at most the specified number of entries are visible (unless +# a fully collapsed tree already exceeds this amount). So setting the number of +# entries 1 will produce a full collapsed tree by default. 0 is a special value +# representing an infinite number of entries and will result in a full expanded +# tree by default. +# Minimum value: 0, maximum value: 9999, default value: 100. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_INDEX_NUM_ENTRIES = 100 + +# If the GENERATE_DOCSET tag is set to YES, additional index files will be +# generated that can be used as input for Apple's Xcode 3 integrated development +# environment (see: +# https://developer.apple.com/xcode/), introduced with OSX 10.5 (Leopard). To +# create a documentation set, doxygen will generate a Makefile in the HTML +# output directory. Running make will produce the docset in that directory and +# running make install will install the docset in +# ~/Library/Developer/Shared/Documentation/DocSets so that Xcode will find it at +# startup. See https://developer.apple.com/library/archive/featuredarticles/Doxy +# genXcode/_index.html for more information. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + GENERATE_DOCSET = NO + +# This tag determines the name of the docset feed. A documentation feed provides +# an umbrella under which multiple documentation sets from a single provider +# (such as a company or product suite) can be grouped. +# The default value is: Doxygen generated docs. +# This tag requires that the tag GENERATE_DOCSET is set to YES. + DOCSET_FEEDNAME = "GNU Taler Source Documentation" -DOCSET_BUNDLE_ID = net.taler -HTML_DYNAMIC_SECTIONS = NO + +# This tag determines the URL of the docset feed. A documentation feed provides +# an umbrella under which multiple documentation sets from a single provider +# (such as a company or product suite) can be grouped. +# This tag requires that the tag GENERATE_DOCSET is set to YES. + +# DOCSET_FEEDURL = + +# This tag specifies a string that should uniquely identify the documentation +# set bundle. This should be a reverse domain-name style string, e.g. +# com.mycompany.MyDocSet. Doxygen will append .docset to the name. +# The default value is: org.doxygen.Project. +# This tag requires that the tag GENERATE_DOCSET is set to YES. + +DOCSET_BUNDLE_ID = net.taler.exchange + +# The DOCSET_PUBLISHER_ID tag specifies a string that should uniquely identify +# the documentation publisher. This should be a reverse domain-name style +# string, e.g. com.mycompany.MyDocSet.documentation. +# The default value is: org.doxygen.Publisher. +# This tag requires that the tag GENERATE_DOCSET is set to YES. + +DOCSET_PUBLISHER_ID = net.taler + +# The DOCSET_PUBLISHER_NAME tag identifies the documentation publisher. +# The default value is: Publisher. +# This tag requires that the tag GENERATE_DOCSET is set to YES. + +DOCSET_PUBLISHER_NAME = "Taler Systems SA" + +# If the GENERATE_HTMLHELP tag is set to YES then doxygen generates three +# additional HTML index files: index.hhp, index.hhc, and index.hhk. The +# index.hhp is a project file that can be read by Microsoft's HTML Help Workshop +# on Windows. In the beginning of 2021 Microsoft took the original page, with +# a.o. the download links, offline the HTML help workshop was already many years +# in maintenance mode). You can download the HTML help workshop from the web +# archives at Installation executable (see: +# http://web.archive.org/web/20160201063255/http://download.microsoft.com/downlo +# ad/0/A/9/0A939EF6-E31C-430F-A3DF-DFAE7960D564/htmlhelp.exe). +# +# The HTML Help Workshop contains a compiler that can convert all HTML output +# generated by doxygen into a single compiled HTML file (.chm). Compiled HTML +# files are now used as the Windows 98 help format, and will replace the old +# Windows help format (.hlp) on all Windows platforms in the future. Compressed +# HTML files also contain an index, a table of contents, and you can search for +# words in the documentation. The HTML workshop also contains a viewer for +# compressed HTML files. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +GENERATE_HTMLHELP = NO + +# The CHM_FILE tag can be used to specify the file name of the resulting .chm +# file. You can add a path in front of the file if the result should not be +# written to the html output directory. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. + CHM_FILE = + +# The HHC_LOCATION tag can be used to specify the location (absolute path +# including file name) of the HTML help compiler (hhc.exe). If non-empty, +# doxygen will try to run the HTML help compiler on the generated index.hhp. +# The file has to be specified with full path. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. + HHC_LOCATION = + +# The GENERATE_CHI flag controls if a separate .chi index file is generated +# (YES) or that it should be included in the main .chm file (NO). +# The default value is: NO. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. + GENERATE_CHI = NO + +# The CHM_INDEX_ENCODING is used to encode HtmlHelp index (hhk), content (hhc) +# and project file content. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. + CHM_INDEX_ENCODING = + +# The BINARY_TOC flag controls whether a binary table of contents is generated +# (YES) or a normal table of contents (NO) in the .chm file. Furthermore it +# enables the Previous and Next buttons. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. + BINARY_TOC = NO + +# The TOC_EXPAND flag can be set to YES to add extra items for group members to +# the table of contents of the HTML help documentation and to the tree view. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. + TOC_EXPAND = NO + +# If the GENERATE_QHP tag is set to YES and both QHP_NAMESPACE and +# QHP_VIRTUAL_FOLDER are set, an additional index file will be generated that +# can be used as input for Qt's qhelpgenerator to generate a Qt Compressed Help +# (.qch) of the generated HTML documentation. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +GENERATE_QHP = NO + +# If the QHG_LOCATION tag is specified, the QCH_FILE tag can be used to specify +# the file name of the resulting .qch file. The path specified is relative to +# the HTML output folder. +# This tag requires that the tag GENERATE_QHP is set to YES. + +QCH_FILE = + +# The QHP_NAMESPACE tag specifies the namespace to use when generating Qt Help +# Project output. For more information please see Qt Help Project / Namespace +# (see: +# https://doc.qt.io/archives/qt-4.8/qthelpproject.html#namespace). +# The default value is: org.doxygen.Project. +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHP_NAMESPACE = org.doxygen.Project + +# The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating Qt +# Help Project output. For more information please see Qt Help Project / Virtual +# Folders (see: +# https://doc.qt.io/archives/qt-4.8/qthelpproject.html#virtual-folders). +# The default value is: doc. +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHP_VIRTUAL_FOLDER = doc + +# If the QHP_CUST_FILTER_NAME tag is set, it specifies the name of a custom +# filter to add. For more information please see Qt Help Project / Custom +# Filters (see: +# https://doc.qt.io/archives/qt-4.8/qthelpproject.html#custom-filters). +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHP_CUST_FILTER_NAME = + +# The QHP_CUST_FILTER_ATTRS tag specifies the list of the attributes of the +# custom filter to add. For more information please see Qt Help Project / Custom +# Filters (see: +# https://doc.qt.io/archives/qt-4.8/qthelpproject.html#custom-filters). +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHP_CUST_FILTER_ATTRS = + +# The QHP_SECT_FILTER_ATTRS tag specifies the list of the attributes this +# project's filter section matches. Qt Help Project / Filter Attributes (see: +# https://doc.qt.io/archives/qt-4.8/qthelpproject.html#filter-attributes). +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHP_SECT_FILTER_ATTRS = + +# The QHG_LOCATION tag can be used to specify the location (absolute path +# including file name) of Qt's qhelpgenerator. If non-empty doxygen will try to +# run qhelpgenerator on the generated .qhp file. +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHG_LOCATION = + +# If the GENERATE_ECLIPSEHELP tag is set to YES, additional index files will be +# generated, together with the HTML files, they form an Eclipse help plugin. To +# install this plugin and make it available under the help contents menu in +# Eclipse, the contents of the directory containing the HTML and XML files needs +# to be copied into the plugins directory of eclipse. The name of the directory +# within the plugins directory should be the same as the ECLIPSE_DOC_ID value. +# After copying Eclipse needs to be restarted before the help appears. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +GENERATE_ECLIPSEHELP = NO + +# A unique identifier for the Eclipse help plugin. When installing the plugin +# the directory name containing the HTML and XML files should also have this +# name. Each documentation set should have its own identifier. +# The default value is: org.doxygen.Project. +# This tag requires that the tag GENERATE_ECLIPSEHELP is set to YES. + +ECLIPSE_DOC_ID = org.doxygen.Project + +# If you want full control over the layout of the generated HTML pages it might +# be necessary to disable the index and replace it with your own. The +# DISABLE_INDEX tag can be used to turn on/off the condensed index (tabs) at top +# of each HTML page. A value of NO enables the index and the value YES disables +# it. Since the tabs in the index contain the same information as the navigation +# tree, you can set this option to YES if you also set GENERATE_TREEVIEW to YES. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + DISABLE_INDEX = NO -ENUM_VALUES_PER_LINE = 4 + +# The GENERATE_TREEVIEW tag is used to specify whether a tree-like index +# structure should be generated to display hierarchical information. If the tag +# value is set to YES, a side panel will be generated containing a tree-like +# index structure (just like the one that is generated for HTML Help). For this +# to work a browser that supports JavaScript, DHTML, CSS and frames is required +# (i.e. any modern browser). Windows users are probably better off using the +# HTML help feature. Via custom style sheets (see HTML_EXTRA_STYLESHEET) one can +# further fine tune the look of the index (see "Fine-tuning the output"). As an +# example, the default style sheet generated by doxygen has an example that +# shows how to put an image at the root of the tree instead of the PROJECT_NAME. +# Since the tree basically has the same information as the tab index, you could +# consider setting DISABLE_INDEX to YES when enabling this option. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + GENERATE_TREEVIEW = NONE + +# When both GENERATE_TREEVIEW and DISABLE_INDEX are set to YES, then the +# FULL_SIDEBAR option determines if the side bar is limited to only the treeview +# area (value NO) or if it should extend to the full height of the window (value +# YES). Setting this to YES gives a layout similar to +# https://docs.readthedocs.io with more room for contents, but less room for the +# project logo, title, and description. If either GENERATE_TREEVIEW or +# DISABLE_INDEX is set to NO, this option has no effect. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +# FULL_SIDEBAR = NO + +# The ENUM_VALUES_PER_LINE tag can be used to set the number of enum values that +# doxygen will group on one line in the generated HTML documentation. +# +# Note that a value of 0 will completely suppress the enum values from appearing +# in the overview section. +# Minimum value: 0, maximum value: 20, default value: 4. +# This tag requires that the tag GENERATE_HTML is set to YES. + +ENUM_VALUES_PER_LINE = 4 + +# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be used +# to set the initial width (in pixels) of the frame in which the tree is shown. +# Minimum value: 0, maximum value: 1500, default value: 250. +# This tag requires that the tag GENERATE_HTML is set to YES. + TREEVIEW_WIDTH = 250 + +# If the EXT_LINKS_IN_WINDOW option is set to YES, doxygen will open links to +# external symbols imported via tag files in a separate window. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +EXT_LINKS_IN_WINDOW = NO + +# If the OBFUSCATE_EMAILS tag is set to YES, doxygen will obfuscate email +# addresses. +# The default value is: YES. +# This tag requires that the tag GENERATE_HTML is set to YES. + +# OBFUSCATE_EMAILS = YES + +# If the HTML_FORMULA_FORMAT option is set to svg, doxygen will use the pdf2svg +# tool (see https://github.com/dawbarton/pdf2svg) or inkscape (see +# https://inkscape.org) to generate formulas as SVG images instead of PNGs for +# the HTML output. These images will generally look nicer at scaled resolutions. +# Possible values are: png (the default) and svg (looks nicer but requires the +# pdf2svg or inkscape tool). +# The default value is: png. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_FORMULA_FORMAT = png + +# Use this tag to change the font size of LaTeX formulas included as images in +# the HTML documentation. When you change the font size after a successful +# doxygen run you need to manually remove any form_*.png images from the HTML +# output directory to force them to be regenerated. +# Minimum value: 8, maximum value: 50, default value: 10. +# This tag requires that the tag GENERATE_HTML is set to YES. + FORMULA_FONTSIZE = 10 + +# Use the FORMULA_TRANSPARENT tag to determine whether or not the images +# generated for formulas are transparent PNGs. Transparent PNGs are not +# supported properly for IE 6.0, but are supported on all modern browsers. +# +# Note that when changing this option you need to delete any form_*.png files in +# the HTML output directory before the changes have effect. +# The default value is: YES. +# This tag requires that the tag GENERATE_HTML is set to YES. + +FORMULA_TRANSPARENT = YES + +# The FORMULA_MACROFILE can contain LaTeX \newcommand and \renewcommand commands +# to create new LaTeX commands to be used in formulas as building blocks. See +# the section "Including formulas" for details. + +FORMULA_MACROFILE = + +# Enable the USE_MATHJAX option to render LaTeX formulas using MathJax (see +# https://www.mathjax.org) which uses client side JavaScript for the rendering +# instead of using pre-rendered bitmaps. Use this if you do not have LaTeX +# installed or if you want to formulas look prettier in the HTML output. When +# enabled you may also need to install MathJax separately and configure the path +# to it using the MATHJAX_RELPATH option. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +# USE_MATHJAX = NO + +# With MATHJAX_VERSION it is possible to specify the MathJax version to be used. +# Note that the different versions of MathJax have different requirements with +# regards to the different settings, so it is possible that also other MathJax +# settings have to be changed when switching between the different MathJax +# versions. +# Possible values are: MathJax_2 and MathJax_3. +# The default value is: MathJax_2. +# This tag requires that the tag USE_MATHJAX is set to YES. + +MATHJAX_VERSION = MathJax_2 + +# When MathJax is enabled you can set the default output format to be used for +# the MathJax output. For more details about the output format see MathJax +# version 2 (see: +# http://docs.mathjax.org/en/v2.7-latest/output.html) and MathJax version 3 +# (see: +# http://docs.mathjax.org/en/latest/web/components/output.html). +# Possible values are: HTML-CSS (which is slower, but has the best +# compatibility. This is the name for Mathjax version 2, for MathJax version 3 +# this will be translated into chtml), NativeMML (i.e. MathML. Only supported +# for NathJax 2. For MathJax version 3 chtml will be used instead.), chtml (This +# is the name for Mathjax version 3, for MathJax version 2 this will be +# translated into HTML-CSS) and SVG. +# The default value is: HTML-CSS. +# This tag requires that the tag USE_MATHJAX is set to YES. + +MATHJAX_FORMAT = HTML-CSS + +# When MathJax is enabled you need to specify the location relative to the HTML +# output directory using the MATHJAX_RELPATH option. The destination directory +# should contain the MathJax.js script. For instance, if the mathjax directory +# is located at the same level as the HTML output directory, then +# MATHJAX_RELPATH should be ../mathjax. The default value points to the MathJax +# Content Delivery Network so you can quickly see the result without installing +# MathJax. However, it is strongly recommended to install a local copy of +# MathJax from https://www.mathjax.org before deployment. The default value is: +# - in case of MathJax version 2: https://cdn.jsdelivr.net/npm/mathjax@2 +# - in case of MathJax version 3: https://cdn.jsdelivr.net/npm/mathjax@3 +# This tag requires that the tag USE_MATHJAX is set to YES. + +MATHJAX_RELPATH = + +# The MATHJAX_EXTENSIONS tag can be used to specify one or more MathJax +# extension names that should be enabled during MathJax rendering. For example +# for MathJax version 2 (see +# https://docs.mathjax.org/en/v2.7-latest/tex.html#tex-and-latex-extensions): +# MATHJAX_EXTENSIONS = TeX/AMSmath TeX/AMSsymbols +# For example for MathJax version 3 (see +# http://docs.mathjax.org/en/latest/input/tex/extensions/index.html): +# MATHJAX_EXTENSIONS = ams +# This tag requires that the tag USE_MATHJAX is set to YES. + +MATHJAX_EXTENSIONS = + +# The MATHJAX_CODEFILE tag can be used to specify a file with javascript pieces +# of code that will be used on startup of the MathJax code. See the MathJax site +# (see: +# http://docs.mathjax.org/en/v2.7-latest/output.html) for more details. For an +# example see the documentation. +# This tag requires that the tag USE_MATHJAX is set to YES. + +MATHJAX_CODEFILE = + +# When the SEARCHENGINE tag is enabled doxygen will generate a search box for +# the HTML output. The underlying search engine uses javascript and DHTML and +# should work on any modern browser. Note that when using HTML help +# (GENERATE_HTMLHELP), Qt help (GENERATE_QHP), or docsets (GENERATE_DOCSET) +# there is already a search function so this one should typically be disabled. +# For large projects the javascript based search engine can be slow, then +# enabling SERVER_BASED_SEARCH may provide a better solution. It is possible to +# search using the keyboard; to jump to the search box use <access key> + S +# (what the <access key> is depends on the OS and browser, but it is typically +# <CTRL>, <ALT>/<option>, or both). Inside the search box use the <cursor down +# key> to jump into the search results window, the results can be navigated +# using the <cursor keys>. Press <Enter> to select an item or <escape> to cancel +# the search. The filter options can be selected when the cursor is inside the +# search box by pressing <Shift>+<cursor down>. Also here use the <cursor keys> +# to select a filter and <Enter> or <escape> to activate or cancel the filter +# option. +# The default value is: YES. +# This tag requires that the tag GENERATE_HTML is set to YES. + +SEARCHENGINE = YES + +# When the SERVER_BASED_SEARCH tag is enabled the search engine will be +# implemented using a web server instead of a web client using JavaScript. There +# are two flavors of web server based searching depending on the EXTERNAL_SEARCH +# setting. When disabled, doxygen will generate a PHP script for searching and +# an index file used by the script. When EXTERNAL_SEARCH is enabled the indexing +# and searching needs to be provided by external tools. See the section +# "External Indexing and Searching" for details. +# The default value is: NO. +# This tag requires that the tag SEARCHENGINE is set to YES. + +SERVER_BASED_SEARCH = NO + +# When EXTERNAL_SEARCH tag is enabled doxygen will no longer generate the PHP +# script for searching. Instead the search results are written to an XML file +# which needs to be processed by an external indexer. Doxygen will invoke an +# external search engine pointed to by the SEARCHENGINE_URL option to obtain the +# search results. +# +# Doxygen ships with an example indexer (doxyindexer) and search engine +# (doxysearch.cgi) which are based on the open source search engine library +# Xapian (see: +# https://xapian.org/). +# +# See the section "External Indexing and Searching" for details. +# The default value is: NO. +# This tag requires that the tag SEARCHENGINE is set to YES. + +EXTERNAL_SEARCH = NO + +# The SEARCHENGINE_URL should point to a search engine hosted by a web server +# which will return the search results when EXTERNAL_SEARCH is enabled. +# +# Doxygen ships with an example indexer (doxyindexer) and search engine +# (doxysearch.cgi) which are based on the open source search engine library +# Xapian (see: +# https://xapian.org/). See the section "External Indexing and Searching" for +# details. +# This tag requires that the tag SEARCHENGINE is set to YES. + +SEARCHENGINE_URL = + +# When SERVER_BASED_SEARCH and EXTERNAL_SEARCH are both enabled the unindexed +# search data is written to a file for indexing by an external tool. With the +# SEARCHDATA_FILE tag the name of this file can be specified. +# The default file is: searchdata.xml. +# This tag requires that the tag SEARCHENGINE is set to YES. + +SEARCHDATA_FILE = searchdata.xml + +# When SERVER_BASED_SEARCH and EXTERNAL_SEARCH are both enabled the +# EXTERNAL_SEARCH_ID tag can be used as an identifier for the project. This is +# useful in combination with EXTRA_SEARCH_MAPPINGS to search through multiple +# projects and redirect the results back to the right project. +# This tag requires that the tag SEARCHENGINE is set to YES. + +EXTERNAL_SEARCH_ID = + +# The EXTRA_SEARCH_MAPPINGS tag can be used to enable searching through doxygen +# projects other than the one defined by this configuration file, but that are +# all added to the same external search index. Each project needs to have a +# unique id set via EXTERNAL_SEARCH_ID. The search mapping then maps the id of +# to a relative location where the documentation can be found. The format is: +# EXTRA_SEARCH_MAPPINGS = tagname1=loc1 tagname2=loc2 ... +# This tag requires that the tag SEARCHENGINE is set to YES. + +EXTRA_SEARCH_MAPPINGS = + #--------------------------------------------------------------------------- -# configuration options related to the LaTeX output +# Configuration options related to the LaTeX output #--------------------------------------------------------------------------- + +# If the GENERATE_LATEX tag is set to YES, doxygen will generate LaTeX output. +# The default value is: YES. + GENERATE_LATEX = NO + +# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. If a +# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of +# it. +# The default directory is: latex. +# This tag requires that the tag GENERATE_LATEX is set to YES. + LATEX_OUTPUT = latex + +# The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be +# invoked. +# +# Note that when not enabling USE_PDFLATEX the default is latex when enabling +# USE_PDFLATEX the default is pdflatex and when in the later case latex is +# chosen this is overwritten by pdflatex. For specific output languages the +# default can have been set differently, this depends on the implementation of +# the output language. +# This tag requires that the tag GENERATE_LATEX is set to YES. + LATEX_CMD_NAME = latex + +# The MAKEINDEX_CMD_NAME tag can be used to specify the command name to generate +# index for LaTeX. +# Note: This tag is used in the Makefile / make.bat. +# See also: LATEX_MAKEINDEX_CMD for the part in the generated output file +# (.tex). +# The default file is: makeindex. +# This tag requires that the tag GENERATE_LATEX is set to YES. + MAKEINDEX_CMD_NAME = makeindex + +# The LATEX_MAKEINDEX_CMD tag can be used to specify the command name to +# generate index for LaTeX. In case there is no backslash (\) as first character +# it will be automatically added in the LaTeX code. +# Note: This tag is used in the generated output file (.tex). +# See also: MAKEINDEX_CMD_NAME for the part in the Makefile / make.bat. +# The default value is: makeindex. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_MAKEINDEX_CMD = makeindex + +# If the COMPACT_LATEX tag is set to YES, doxygen generates more compact LaTeX +# documents. This may be useful for small projects and may help to save some +# trees in general. +# The default value is: NO. +# This tag requires that the tag GENERATE_LATEX is set to YES. + COMPACT_LATEX = YES + +# The PAPER_TYPE tag can be used to set the paper type that is used by the +# printer. +# Possible values are: a4 (210 x 297 mm), letter (8.5 x 11 inches), legal (8.5 x +# 14 inches) and executive (7.25 x 10.5 inches). +# The default value is: a4. +# This tag requires that the tag GENERATE_LATEX is set to YES. + PAPER_TYPE = a4 + +# The EXTRA_PACKAGES tag can be used to specify one or more LaTeX package names +# that should be included in the LaTeX output. The package can be specified just +# by its name or with the correct syntax as to be used with the LaTeX +# \usepackage command. To get the times font for instance you can specify : +# EXTRA_PACKAGES=times or EXTRA_PACKAGES={times} +# To use the option intlimits with the amsmath package you can specify: +# EXTRA_PACKAGES=[intlimits]{amsmath} +# If left blank no extra packages will be included. +# This tag requires that the tag GENERATE_LATEX is set to YES. + EXTRA_PACKAGES = + +# The LATEX_HEADER tag can be used to specify a user-defined LaTeX header for +# the generated LaTeX document. The header should contain everything until the +# first chapter. If it is left blank doxygen will generate a standard header. It +# is highly recommended to start with a default header using +# doxygen -w latex new_header.tex new_footer.tex new_stylesheet.sty +# and then modify the file new_header.tex. See also section "Doxygen usage" for +# information on how to generate the default header that doxygen normally uses. +# +# Note: Only use a user-defined header if you know what you are doing! +# Note: The header is subject to change so you typically have to regenerate the +# default header when upgrading to a newer version of doxygen. The following +# commands have a special meaning inside the header (and footer): For a +# description of the possible markers and block names see the documentation. +# This tag requires that the tag GENERATE_LATEX is set to YES. + LATEX_HEADER = + +# The LATEX_FOOTER tag can be used to specify a user-defined LaTeX footer for +# the generated LaTeX document. The footer should contain everything after the +# last chapter. If it is left blank doxygen will generate a standard footer. See +# LATEX_HEADER for more information on how to generate a default footer and what +# special commands can be used inside the footer. See also section "Doxygen +# usage" for information on how to generate the default footer that doxygen +# normally uses. Note: Only use a user-defined footer if you know what you are +# doing! +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_FOOTER = + +# The LATEX_EXTRA_STYLESHEET tag can be used to specify additional user-defined +# LaTeX style sheets that are included after the standard style sheets created +# by doxygen. Using this option one can overrule certain style aspects. Doxygen +# will copy the style sheet files to the output directory. +# Note: The order of the extra style sheet files is of importance (e.g. the last +# style sheet in the list overrules the setting of the previous ones in the +# list). +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_EXTRA_STYLESHEET = + +# The LATEX_EXTRA_FILES tag can be used to specify one or more extra images or +# other source files which should be copied to the LATEX_OUTPUT output +# directory. Note that the files will be copied as-is; there are no commands or +# markers available. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_EXTRA_FILES = + +# If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated is +# prepared for conversion to PDF (using ps2pdf or pdflatex). The PDF file will +# contain links (just like the HTML output) instead of page references. This +# makes the output suitable for online browsing using a PDF viewer. +# The default value is: YES. +# This tag requires that the tag GENERATE_LATEX is set to YES. + PDF_HYPERLINKS = YES + +# If the USE_PDFLATEX tag is set to YES, doxygen will use the engine as +# specified with LATEX_CMD_NAME to generate the PDF file directly from the LaTeX +# files. Set this option to YES, to get a higher quality PDF documentation. +# +# See also section LATEX_CMD_NAME for selecting the engine. +# The default value is: YES. +# This tag requires that the tag GENERATE_LATEX is set to YES. + USE_PDFLATEX = YES + +# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \batchmode +# command to the generated LaTeX files. This will instruct LaTeX to keep running +# if errors occur, instead of asking the user for help. +# The default value is: NO. +# This tag requires that the tag GENERATE_LATEX is set to YES. + LATEX_BATCHMODE = NO + +# If the LATEX_HIDE_INDICES tag is set to YES then doxygen will not include the +# index chapters (such as File Index, Compound Index, etc.) in the output. +# The default value is: NO. +# This tag requires that the tag GENERATE_LATEX is set to YES. + LATEX_HIDE_INDICES = NO + +# The LATEX_BIB_STYLE tag can be used to specify the style to use for the +# bibliography, e.g. plainnat, or ieeetr. See +# https://en.wikipedia.org/wiki/BibTeX and \cite for more info. +# The default value is: plain. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_BIB_STYLE = plain + +# If the LATEX_TIMESTAMP tag is set to YES then the footer of each generated +# page will contain the date and time when the page was generated. Setting this +# to NO can help when comparing the output of multiple runs. +# The default value is: NO. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_TIMESTAMP = NO + +# The LATEX_EMOJI_DIRECTORY tag is used to specify the (relative or absolute) +# path from which the emoji images will be read. If a relative path is entered, +# it will be relative to the LATEX_OUTPUT directory. If left blank the +# LATEX_OUTPUT directory will be used. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_EMOJI_DIRECTORY = + #--------------------------------------------------------------------------- -# configuration options related to the RTF output +# Configuration options related to the RTF output #--------------------------------------------------------------------------- + +# If the GENERATE_RTF tag is set to YES, doxygen will generate RTF output. The +# RTF output is optimized for Word 97 and may not look too pretty with other RTF +# readers/editors. +# The default value is: NO. + GENERATE_RTF = NO + +# The RTF_OUTPUT tag is used to specify where the RTF docs will be put. If a +# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of +# it. +# The default directory is: rtf. +# This tag requires that the tag GENERATE_RTF is set to YES. + RTF_OUTPUT = rtf + +# If the COMPACT_RTF tag is set to YES, doxygen generates more compact RTF +# documents. This may be useful for small projects and may help to save some +# trees in general. +# The default value is: NO. +# This tag requires that the tag GENERATE_RTF is set to YES. + COMPACT_RTF = NO + +# If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated will +# contain hyperlink fields. The RTF file will contain links (just like the HTML +# output) instead of page references. This makes the output suitable for online +# browsing using Word or some other Word compatible readers that support those +# fields. +# +# Note: WordPad (write) and others do not support links. +# The default value is: NO. +# This tag requires that the tag GENERATE_RTF is set to YES. + RTF_HYPERLINKS = NO + +# Load stylesheet definitions from file. Syntax is similar to doxygen's +# configuration file, i.e. a series of assignments. You only have to provide +# replacements, missing definitions are set to their default value. +# +# See also section "Doxygen usage" for information on how to generate the +# default style sheet that doxygen normally uses. +# This tag requires that the tag GENERATE_RTF is set to YES. + RTF_STYLESHEET_FILE = + +# Set optional variables used in the generation of an RTF document. Syntax is +# similar to doxygen's configuration file. A template extensions file can be +# generated using doxygen -e rtf extensionFile. +# This tag requires that the tag GENERATE_RTF is set to YES. + RTF_EXTENSIONS_FILE = + #--------------------------------------------------------------------------- -# configuration options related to the man page output +# Configuration options related to the man page output #--------------------------------------------------------------------------- + +# If the GENERATE_MAN tag is set to YES, doxygen will generate man pages for +# classes and files. +# The default value is: NO. + GENERATE_MAN = NO + +# The MAN_OUTPUT tag is used to specify where the man pages will be put. If a +# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of +# it. A directory man3 will be created inside the directory specified by +# MAN_OUTPUT. +# The default directory is: man. +# This tag requires that the tag GENERATE_MAN is set to YES. + MAN_OUTPUT = man + +# The MAN_EXTENSION tag determines the extension that is added to the generated +# man pages. In case the manual section does not start with a number, the number +# 3 is prepended. The dot (.) at the beginning of the MAN_EXTENSION tag is +# optional. +# The default value is: .3. +# This tag requires that the tag GENERATE_MAN is set to YES. + MAN_EXTENSION = .3 + +# The MAN_SUBDIR tag determines the name of the directory created within +# MAN_OUTPUT in which the man pages are placed. If defaults to man followed by +# MAN_EXTENSION with the initial . removed. +# This tag requires that the tag GENERATE_MAN is set to YES. + +MAN_SUBDIR = + +# If the MAN_LINKS tag is set to YES and doxygen generates man output, then it +# will generate one additional man file for each entity documented in the real +# man page(s). These additional files only source the real man page, but without +# them the man command would be unable to find the correct page. +# The default value is: NO. +# This tag requires that the tag GENERATE_MAN is set to YES. + MAN_LINKS = NO + #--------------------------------------------------------------------------- -# configuration options related to the XML output +# Configuration options related to the XML output #--------------------------------------------------------------------------- + +# If the GENERATE_XML tag is set to YES, doxygen will generate an XML file that +# captures the structure of the code including all documentation. +# The default value is: NO. + GENERATE_XML = NO + +# The XML_OUTPUT tag is used to specify where the XML pages will be put. If a +# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of +# it. +# The default directory is: xml. +# This tag requires that the tag GENERATE_XML is set to YES. + XML_OUTPUT = xml + +# If the XML_PROGRAMLISTING tag is set to YES, doxygen will dump the program +# listings (including syntax highlighting and cross-referencing information) to +# the XML output. Note that enabling this will significantly increase the size +# of the XML output. +# The default value is: YES. +# This tag requires that the tag GENERATE_XML is set to YES. + XML_PROGRAMLISTING = YES + +# If the XML_NS_MEMB_FILE_SCOPE tag is set to YES, doxygen will include +# namespace members in file scope as well, matching the HTML output. +# The default value is: NO. +# This tag requires that the tag GENERATE_XML is set to YES. + +XML_NS_MEMB_FILE_SCOPE = NO + #--------------------------------------------------------------------------- -# configuration options for the AutoGen Definitions output +# Configuration options related to the DOCBOOK output #--------------------------------------------------------------------------- + +# If the GENERATE_DOCBOOK tag is set to YES, doxygen will generate Docbook files +# that can be used to generate PDF. +# The default value is: NO. + +GENERATE_DOCBOOK = NO + +# The DOCBOOK_OUTPUT tag is used to specify where the Docbook pages will be put. +# If a relative path is entered the value of OUTPUT_DIRECTORY will be put in +# front of it. +# The default directory is: docbook. +# This tag requires that the tag GENERATE_DOCBOOK is set to YES. + +DOCBOOK_OUTPUT = docbook + +#--------------------------------------------------------------------------- +# Configuration options for the AutoGen Definitions output +#--------------------------------------------------------------------------- + +# If the GENERATE_AUTOGEN_DEF tag is set to YES, doxygen will generate an +# AutoGen Definitions (see http://autogen.sourceforge.net/) file that captures +# the structure of the code including all documentation. Note that this feature +# is still experimental and incomplete at the moment. +# The default value is: NO. + GENERATE_AUTOGEN_DEF = NO + #--------------------------------------------------------------------------- -# configuration options related to the Perl module output +# Configuration options related to the Perl module output #--------------------------------------------------------------------------- + +# If the GENERATE_PERLMOD tag is set to YES, doxygen will generate a Perl module +# file that captures the structure of the code including all documentation. +# +# Note that this feature is still experimental and incomplete at the moment. +# The default value is: NO. + GENERATE_PERLMOD = NO + +# If the PERLMOD_LATEX tag is set to YES, doxygen will generate the necessary +# Makefile rules, Perl scripts and LaTeX code to be able to generate PDF and DVI +# output from the Perl module output. +# The default value is: NO. +# This tag requires that the tag GENERATE_PERLMOD is set to YES. + PERLMOD_LATEX = NO + +# If the PERLMOD_PRETTY tag is set to YES, the Perl module output will be nicely +# formatted so it can be parsed by a human reader. This is useful if you want to +# understand what is going on. On the other hand, if this tag is set to NO, the +# size of the Perl module output will be much smaller and Perl will parse it +# just the same. +# The default value is: YES. +# This tag requires that the tag GENERATE_PERLMOD is set to YES. + PERLMOD_PRETTY = YES + +# The names of the make variables in the generated doxyrules.make file are +# prefixed with the string contained in PERLMOD_MAKEVAR_PREFIX. This is useful +# so different doxyrules.make files included by the same Makefile don't +# overwrite each other's variables. +# This tag requires that the tag GENERATE_PERLMOD is set to YES. + PERLMOD_MAKEVAR_PREFIX = + #--------------------------------------------------------------------------- # Configuration options related to the preprocessor #--------------------------------------------------------------------------- + +# If the ENABLE_PREPROCESSING tag is set to YES, doxygen will evaluate all +# C-preprocessor directives found in the sources and include files. +# The default value is: YES. + ENABLE_PREPROCESSING = YES + +# If the MACRO_EXPANSION tag is set to YES, doxygen will expand all macro names +# in the source code. If set to NO, only conditional compilation will be +# performed. Macro expansion can be done in a controlled way by setting +# EXPAND_ONLY_PREDEF to YES. +# The default value is: NO. +# This tag requires that the tag ENABLE_PREPROCESSING is set to YES. + MACRO_EXPANSION = YES + +# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then +# the macro expansion is limited to the macros specified with the PREDEFINED and +# EXPAND_AS_DEFINED tags. +# The default value is: NO. +# This tag requires that the tag ENABLE_PREPROCESSING is set to YES. + EXPAND_ONLY_PREDEF = NO + +# If the SEARCH_INCLUDES tag is set to YES, the include files in the +# INCLUDE_PATH will be searched if a #include is found. +# The default value is: YES. +# This tag requires that the tag ENABLE_PREPROCESSING is set to YES. + SEARCH_INCLUDES = YES + +# The INCLUDE_PATH tag can be used to specify one or more directories that +# contain include files that are not input files but should be processed by the +# preprocessor. Note that the INCLUDE_PATH is not recursive, so the setting of +# RECURSIVE has no effect here. +# This tag requires that the tag SEARCH_INCLUDES is set to YES. + INCLUDE_PATH = + +# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard +# patterns (like *.h and *.hpp) to filter out the header-files in the +# directories. If left blank, the patterns specified with FILE_PATTERNS will be +# used. +# This tag requires that the tag ENABLE_PREPROCESSING is set to YES. + INCLUDE_FILE_PATTERNS = -PREDEFINED = GNUNET_UNUSED="" GNUNET_PACKED="" + +# The PREDEFINED tag can be used to specify one or more macro names that are +# defined before the preprocessor is started (similar to the -D option of e.g. +# gcc). The argument of the tag is a list of macros of the form: name or +# name=definition (no spaces). If the definition and the "=" are omitted, "=1" +# is assumed. To prevent a macro definition from being undefined via #undef or +# recursively expanded use the := operator instead of the = operator. +# This tag requires that the tag ENABLE_PREPROCESSING is set to YES. + +PREDEFINED = GNUNET_UNUSED= \ + GNUNET_PACKED= + +# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this +# tag can be used to specify a list of macro names that should be expanded. The +# macro definition that is found in the sources will be used. Use the PREDEFINED +# tag if you want to use a different macro definition that overrules the +# definition found in the source code. +# This tag requires that the tag ENABLE_PREPROCESSING is set to YES. + EXPAND_AS_DEFINED = + +# If the SKIP_FUNCTION_MACROS tag is set to YES then doxygen's preprocessor will +# remove all references to function-like macros that are alone on a line, have +# an all uppercase name, and do not end with a semicolon. Such function macros +# are typically used for boiler-plate code, and will confuse the parser if not +# removed. +# The default value is: YES. +# This tag requires that the tag ENABLE_PREPROCESSING is set to YES. + SKIP_FUNCTION_MACROS = YES + #--------------------------------------------------------------------------- -# Configuration::additions related to external references +# Configuration options related to external references #--------------------------------------------------------------------------- -TAGFILES = ../../contrib/gnunet.tag ../../contrib/microhttpd.tag + +# The TAGFILES tag can be used to specify one or more tag files. For each tag +# file the location of the external documentation should be added. The format of +# a tag file without this location is as follows: +# TAGFILES = file1 file2 ... +# Adding location for the tag files is done as follows: +# TAGFILES = file1=loc1 "file2 = loc2" ... +# where loc1 and loc2 can be relative or absolute paths or URLs. See the +# section "Linking to external documentation" for more information about the use +# of tag files. +# Note: Each tag file must have a unique name (where the name does NOT include +# the path). If a tag file is not located in the directory in which doxygen is +# run, you must also specify the path to the tagfile here. + +TAGFILES = ../../contrib/gnunet.tag \ + ../../contrib/microhttpd.tag + +# When a file name is specified after GENERATE_TAGFILE, doxygen will create a +# tag file that is based on the input files it reads. See section "Linking to +# external documentation" for more information about the usage of tag files. + GENERATE_TAGFILE = taler-exchange.tag + +# If the ALLEXTERNALS tag is set to YES, all external class will be listed in +# the class index. If set to NO, only the inherited external classes will be +# listed. +# The default value is: NO. + ALLEXTERNALS = NO + +# If the EXTERNAL_GROUPS tag is set to YES, all external groups will be listed +# in the modules index. If set to NO, only the current project's groups will be +# listed. +# The default value is: YES. + EXTERNAL_GROUPS = YES +# If the EXTERNAL_PAGES tag is set to YES, all external pages will be listed in +# the related pages index. If set to NO, only the current project's pages will +# be listed. +# The default value is: YES. + +EXTERNAL_PAGES = YES + #--------------------------------------------------------------------------- # Configuration options related to the dot tool #--------------------------------------------------------------------------- -CLASS_DIAGRAMS = YES + +# You can include diagrams made with dia in doxygen documentation. Doxygen will +# then run dia to produce the diagram and insert it in the documentation. The +# DIA_PATH tag allows you to specify the directory where the dia binary resides. +# If left empty dia is assumed to be found in the default search path. + +DIA_PATH = + +# If set to YES the inheritance and collaboration graphs will hide inheritance +# and usage relations if the target is undocumented or is not a class. +# The default value is: YES. + HIDE_UNDOC_RELATIONS = YES + +# If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is +# available from the path. This tool is part of Graphviz (see: +# http://www.graphviz.org/), a graph visualization toolkit from AT&T and Lucent +# Bell Labs. The other options in this section have no effect if this option is +# set to NO +# The default value is: YES. + HAVE_DOT = YES + +# The DOT_NUM_THREADS specifies the number of dot invocations doxygen is allowed +# to run in parallel. When set to 0 doxygen will base this on the number of +# processors available in the system. You can set it explicitly to a value +# larger than 0 to get control over the balance between CPU load and processing +# speed. +# Minimum value: 0, maximum value: 32, default value: 0. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_NUM_THREADS = 0 + +# When you want a differently looking font in the dot files that doxygen +# generates you can specify the font name using DOT_FONTNAME. You need to make +# sure dot is able to find the font, which can be done by putting it in a +# standard location or by setting the DOTFONTPATH environment variable or by +# setting DOT_FONTPATH to the directory containing the font. +# The default value is: Helvetica. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_FONTNAME = Helvetica + +# The DOT_FONTSIZE tag can be used to set the size (in points) of the font of +# dot graphs. +# Minimum value: 4, maximum value: 24, default value: 10. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_FONTSIZE = 10 + +# By default doxygen will tell dot to use the default font as specified with +# DOT_FONTNAME. If you specify a different font using DOT_FONTNAME you can set +# the path where dot can find it using this tag. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_FONTPATH = + +# If the CLASS_GRAPH tag is set to YES (or GRAPH) then doxygen will generate a +# graph for each documented class showing the direct and indirect inheritance +# relations. In case HAVE_DOT is set as well dot will be used to draw the graph, +# otherwise the built-in generator will be used. If the CLASS_GRAPH tag is set +# to TEXT the direct and indirect inheritance relations will be shown as texts / +# links. +# Possible values are: NO, YES, TEXT and GRAPH. +# The default value is: YES. + CLASS_GRAPH = NO + +# If the COLLABORATION_GRAPH tag is set to YES then doxygen will generate a +# graph for each documented class showing the direct and indirect implementation +# dependencies (inheritance, containment, and class references variables) of the +# class with other documented classes. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. + COLLABORATION_GRAPH = NO + +# If the GROUP_GRAPHS tag is set to YES then doxygen will generate a graph for +# groups, showing the direct groups dependencies. See also the chapter Grouping +# in the manual. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. + GROUP_GRAPHS = NO + +# If the UML_LOOK tag is set to YES, doxygen will generate inheritance and +# collaboration diagrams in a style similar to the OMG's Unified Modeling +# Language. +# The default value is: NO. +# This tag requires that the tag HAVE_DOT is set to YES. + UML_LOOK = NO + +# If the UML_LOOK tag is enabled, the fields and methods are shown inside the +# class node. If there are many fields or methods and many nodes the graph may +# become too big to be useful. The UML_LIMIT_NUM_FIELDS threshold limits the +# number of items for each type to make the size more manageable. Set this to 0 +# for no limit. Note that the threshold may be exceeded by 50% before the limit +# is enforced. So when you set the threshold to 10, up to 15 fields may appear, +# but if the number exceeds 15, the total amount of fields shown is limited to +# 10. +# Minimum value: 0, maximum value: 100, default value: 10. +# This tag requires that the tag UML_LOOK is set to YES. + +UML_LIMIT_NUM_FIELDS = 10 + +# If the DOT_UML_DETAILS tag is set to NO, doxygen will show attributes and +# methods without types and arguments in the UML graphs. If the DOT_UML_DETAILS +# tag is set to YES, doxygen will add type and arguments for attributes and +# methods in the UML graphs. If the DOT_UML_DETAILS tag is set to NONE, doxygen +# will not generate fields with class member information in the UML graphs. The +# class diagrams will look similar to the default class diagrams but using UML +# notation for the relationships. +# Possible values are: NO, YES and NONE. +# The default value is: NO. +# This tag requires that the tag UML_LOOK is set to YES. + +DOT_UML_DETAILS = NO + +# The DOT_WRAP_THRESHOLD tag can be used to set the maximum number of characters +# to display on a single line. If the actual line length exceeds this threshold +# significantly it will wrapped across multiple lines. Some heuristics are apply +# to avoid ugly line breaks. +# Minimum value: 0, maximum value: 1000, default value: 17. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_WRAP_THRESHOLD = 17 + +# If the TEMPLATE_RELATIONS tag is set to YES then the inheritance and +# collaboration graphs will show the relations between templates and their +# instances. +# The default value is: NO. +# This tag requires that the tag HAVE_DOT is set to YES. + TEMPLATE_RELATIONS = NO + +# If the INCLUDE_GRAPH, ENABLE_PREPROCESSING and SEARCH_INCLUDES tags are set to +# YES then doxygen will generate a graph for each documented file showing the +# direct and indirect include dependencies of the file with other documented +# files. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. + INCLUDE_GRAPH = YES + +# If the INCLUDED_BY_GRAPH, ENABLE_PREPROCESSING and SEARCH_INCLUDES tags are +# set to YES then doxygen will generate a graph for each documented file showing +# the direct and indirect include dependencies of the file with other documented +# files. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. + INCLUDED_BY_GRAPH = YES + +# If the CALL_GRAPH tag is set to YES then doxygen will generate a call +# dependency graph for every global function or class method. +# +# Note that enabling this option will significantly increase the time of a run. +# So in most cases it will be better to enable call graphs for selected +# functions only using the \callgraph command. Disabling a call graph can be +# accomplished by means of the command \hidecallgraph. +# The default value is: NO. +# This tag requires that the tag HAVE_DOT is set to YES. + CALL_GRAPH = YES + +# If the CALLER_GRAPH tag is set to YES then doxygen will generate a caller +# dependency graph for every global function or class method. +# +# Note that enabling this option will significantly increase the time of a run. +# So in most cases it will be better to enable caller graphs for selected +# functions only using the \callergraph command. Disabling a caller graph can be +# accomplished by means of the command \hidecallergraph. +# The default value is: NO. +# This tag requires that the tag HAVE_DOT is set to YES. + CALLER_GRAPH = YES + +# If the GRAPHICAL_HIERARCHY tag is set to YES then doxygen will graphical +# hierarchy of all classes instead of a textual one. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. + GRAPHICAL_HIERARCHY = NO + +# If the DIRECTORY_GRAPH tag is set to YES then doxygen will show the +# dependencies a directory has on other directories in a graphical way. The +# dependency relations are determined by the #include relations between the +# files in the directories. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. + DIRECTORY_GRAPH = YES + +# The DIR_GRAPH_MAX_DEPTH tag can be used to limit the maximum number of levels +# of child directories generated in directory dependency graphs by dot. +# Minimum value: 1, maximum value: 25, default value: 1. +# This tag requires that the tag DIRECTORY_GRAPH is set to YES. + +# DIR_GRAPH_MAX_DEPTH = 1 + +# The DOT_IMAGE_FORMAT tag can be used to set the image format of the images +# generated by dot. For an explanation of the image formats see the section +# output formats in the documentation of the dot tool (Graphviz (see: +# http://www.graphviz.org/)). +# Note: If you choose svg you need to set HTML_FILE_EXTENSION to xhtml in order +# to make the SVG files visible in IE 9+ (other browsers do not have this +# requirement). +# Possible values are: png, jpg, jpg:cairo, jpg:cairo:gd, jpg:gd, jpg:gd:gd, +# gif, gif:cairo, gif:cairo:gd, gif:gd, gif:gd:gd, svg, png:gd, png:gd:gd, +# png:cairo, png:cairo:gd, png:cairo:cairo, png:cairo:gdiplus, png:gdiplus and +# png:gdiplus:gdiplus. +# The default value is: png. +# This tag requires that the tag HAVE_DOT is set to YES. + DOT_IMAGE_FORMAT = svg + +# If DOT_IMAGE_FORMAT is set to svg, then this option can be set to YES to +# enable generation of interactive SVG images that allow zooming and panning. +# +# Note that this requires a modern browser other than Internet Explorer. Tested +# and working are Firefox, Chrome, Safari, and Opera. +# Note: For IE 9+ you need to set HTML_FILE_EXTENSION to xhtml in order to make +# the SVG files visible. Older versions of IE do not have SVG support. +# The default value is: NO. +# This tag requires that the tag HAVE_DOT is set to YES. + INTERACTIVE_SVG = NO + +# The DOT_PATH tag can be used to specify the path where the dot tool can be +# found. If left blank, it is assumed the dot tool can be found in the path. +# This tag requires that the tag HAVE_DOT is set to YES. + DOT_PATH = + +# The DOTFILE_DIRS tag can be used to specify one or more directories that +# contain dot files that are included in the documentation (see the \dotfile +# command). +# This tag requires that the tag HAVE_DOT is set to YES. + DOTFILE_DIRS = -DOT_GRAPH_MAX_NODES = 100 + +# The MSCFILE_DIRS tag can be used to specify one or more directories that +# contain msc files that are included in the documentation (see the \mscfile +# command). + +MSCFILE_DIRS = + +# The DIAFILE_DIRS tag can be used to specify one or more directories that +# contain dia files that are included in the documentation (see the \diafile +# command). + +DIAFILE_DIRS = + +# When using plantuml, the PLANTUML_JAR_PATH tag should be used to specify the +# path where java can find the plantuml.jar file or to the filename of jar file +# to be used. If left blank, it is assumed PlantUML is not used or called during +# a preprocessing step. Doxygen will generate a warning when it encounters a +# \startuml command in this case and will not generate output for the diagram. + +PLANTUML_JAR_PATH = + +# When using plantuml, the PLANTUML_CFG_FILE tag can be used to specify a +# configuration file for plantuml. + +PLANTUML_CFG_FILE = + +# When using plantuml, the specified paths are searched for files specified by +# the !include statement in a plantuml block. + +PLANTUML_INCLUDE_PATH = + +# The DOT_GRAPH_MAX_NODES tag can be used to set the maximum number of nodes +# that will be shown in the graph. If the number of nodes in a graph becomes +# larger than this value, doxygen will truncate the graph, which is visualized +# by representing a node as a red box. Note that doxygen if the number of direct +# children of the root node in a graph is already larger than +# DOT_GRAPH_MAX_NODES then the graph will not be shown at all. Also note that +# the size of a graph can be further restricted by MAX_DOT_GRAPH_DEPTH. +# Minimum value: 0, maximum value: 10000, default value: 50. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_GRAPH_MAX_NODES = 1000 + +# The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the graphs +# generated by dot. A depth value of 3 means that only nodes reachable from the +# root by following a path via at most 3 edges will be shown. Nodes that lay +# further from the root node will be omitted. Note that setting this option to 1 +# or 2 may greatly reduce the computation time needed for large code bases. Also +# note that the size of a graph can be further restricted by +# DOT_GRAPH_MAX_NODES. Using a depth of 0 means no depth restriction. +# Minimum value: 0, maximum value: 1000, default value: 0. +# This tag requires that the tag HAVE_DOT is set to YES. + MAX_DOT_GRAPH_DEPTH = 2 + +# Set the DOT_TRANSPARENT tag to YES to generate images with a transparent +# background. This is disabled by default, because dot on Windows does not seem +# to support this out of the box. +# +# Warning: Depending on the platform used, enabling this option may lead to +# badly anti-aliased labels on the edges of a graph (i.e. they become hard to +# read). +# The default value is: NO. +# This tag requires that the tag HAVE_DOT is set to YES. + DOT_TRANSPARENT = YES + +# Set the DOT_MULTI_TARGETS tag to YES to allow dot to generate multiple output +# files in one run (i.e. multiple -o and -T options on the command line). This +# makes dot run faster, but since only newer versions of dot (>1.8.10) support +# this, this feature is disabled by default. +# The default value is: NO. +# This tag requires that the tag HAVE_DOT is set to YES. + DOT_MULTI_TARGETS = NO + +# If the GENERATE_LEGEND tag is set to YES doxygen will generate a legend page +# explaining the meaning of the various boxes and arrows in the dot generated +# graphs. +# Note: This tag requires that UML_LOOK isn't set, i.e. the doxygen internal +# graphical representation for inheritance and collaboration diagrams is used. +# The default value is: YES. +# This tag requires that the tag HAVE_DOT is set to YES. + GENERATE_LEGEND = YES + +# If the DOT_CLEANUP tag is set to YES, doxygen will remove the intermediate +# files that are used to generate the various graphs. +# +# Note: This setting is not only used for dot files but also for msc temporary +# files. +# The default value is: YES. + DOT_CLEANUP = YES -#--------------------------------------------------------------------------- -# Configuration::additions related to the search engine -#--------------------------------------------------------------------------- -SEARCHENGINE = YES diff --git a/doc/flows/.gitignore b/doc/flows/.gitignore new file mode 100644 index 000000000..f0de8a3d5 --- /dev/null +++ b/doc/flows/.gitignore @@ -0,0 +1 @@ +main.pdf diff --git a/doc/flows/Makefile b/doc/flows/Makefile new file mode 100644 index 000000000..e6af0897c --- /dev/null +++ b/doc/flows/Makefile @@ -0,0 +1,3 @@ +all: + pdflatex main.tex + pdflatex main.tex diff --git a/doc/flows/fees-coins.tex b/doc/flows/fees-coins.tex new file mode 100644 index 000000000..c24f19a28 --- /dev/null +++ b/doc/flows/fees-coins.tex @@ -0,0 +1,39 @@ +\section{Fees per coin} \label{sec:fees:coin} + +Payments with Taler are always made using coins. Each coin has a specific +denomination, and an exchange will issue coins in different denominations (in +the same currency). The fees per coin depend on the operation and the +denomination. + +The primary fee to be paid is a {\bf deposit} fee that is +charged whenever a coin is fully or partially deposited +into a bank account or another wallet. + +A secondary fee to be paid is a {\bf change} fee that is +charged whenever a coin partially spent and change must +be rendered. + +Coins also have an {\bf expiration} date of approximately {\bf one year}. +After the expiration date, coins become worthless. Wallets that are online +{\bf three months} {\em before} a coin expires will automatically trade any +such coins for one or more fresh coins with a later expiration date. This +process is also subject to the {\bf change} fee. + + +\begin{table}[h!] + \caption{Fees per coin. Coin denomination values are given in units of CHF 0.01.} + \label{table:fees:coins} + \begin{center} + \begin{tabular}{l|c|r} + {\bf Denomination} & {\bf Fee type} & {\bf Amount} \\ \hline \hline + $2^{-4}-2^{ 0}$ & deposit & {\em CHF 0.00125} \\ + $2^{-4}-2^{ 0}$ & change & {\em CHF 0.00125} \\ + $2^{ 0}-2^{ 3}$ & deposit & {\em CHF 0.00250} \\ + $2^{ 0}-2^{ 3}$ & change & {\em CHF 0.00125} \\ + $2^{ 4}-2^{ 8}$ & deposit & {\em CHF 0.005} \\ + $2^{ 4}-2^{ 8}$ & change & {\em CHF 0.00125} \\ + $2^{ 8}-2^{12}$ & deposit & {\em CHF 0.01} \\ + $2^{ 8}-2^{12}$ & change & {\em CHF 0.00125} \\ + \end{tabular} + \end{center} +\end{table} diff --git a/doc/flows/fees-wire.tex b/doc/flows/fees-wire.tex new file mode 100644 index 000000000..214a69021 --- /dev/null +++ b/doc/flows/fees-wire.tex @@ -0,0 +1,30 @@ +\section{Fees per wire} \label{sec:fees:wire} + +Wire fees apply whenever an exchange needs to initiate a wire transfer to +another bank account. Wire fees do not apply to every individual payment to a +merchant, as merchants can choose to {\em aggregate} multiple micropayments +into one large payment on the wire. Wire fees also do not apply to +wallet-to-wallet payments within the Taler system. + +A {\bf wire} fee is applied when a merchant receives +an aggregated payment into their bank account. + +A {\bf closing} fee is applied when a wallet fails to +withdraw coins and money has to be sent back to the +originating bank account. + +\begin{table}[h!] + \caption{Table with wire fees. Wire fees are set annually.} + \label{table:fees:wire} + \begin{center} + \begin{tabular}{l|c|r} + {\bf Year} & {\bf Fee type} & {\bf Amount} \\ \hline \hline + 2023 & wire & {\em CHF 0.05} \\ + 2023 & closing & {\em CHF 0.10} \\ + 2024 & wire & {\em CHF 0.05} \\ + 2024 & closing & {\em CHF 0.10} \\ + 2025 & wire & {\em CHF 0.05} \\ + 2025 & closing & {\em CHF 0.10} \\ + \end{tabular} + \end{center} +\end{table} diff --git a/doc/flows/int-deposit.tex b/doc/flows/int-deposit.tex new file mode 100644 index 000000000..661f4dccb --- /dev/null +++ b/doc/flows/int-deposit.tex @@ -0,0 +1,52 @@ +\section{Deposit} \label{sec:deposit} + +\begin{figure}[h!] + \begin{sequencediagram} + \newinst{wallet}{\shortstack{Customer wallet \\ + \\ \begin{tikzpicture} + \node [fill=gray!20,draw=black,thick,align=center] { Unique \\ Wallet ID}; + \end{tikzpicture} + }} + \newinst[2]{exchange}{\shortstack{Taler (exchange) \\ + \\ \begin{tikzpicture}[shape aspect=.5] + \tikzset{every node/.style={cylinder,shape border rotate=90, draw,fill=gray!25}} + \node at (1.5,0) {\shortstack{{{\tiny Database}}}}; + \end{tikzpicture} + }} + \newinst[2]{bank}{\shortstack{Retail bank \\ + \\ \begin{tikzpicture} + \node [fill=gray!20,draw=black,thick,align=center] {Checking \\ Accounts}; + \end{tikzpicture} + }} + \postlevel + \begin{callself}{wallet}{Review deposit fees}{} + \end{callself} + \mess[0]{wallet}{Deposit {(Coins)}}{exchange} + \begin{sdblock}{Acceptable account?}{} + \mess[0]{exchange}{{Refuse deposit}}{wallet} + \end{sdblock} + \begin{sdblock}{KYC/AML required?}{} + \begin{callself}{exchange}{Figures~\ref{fig:proc:kyc}, \ref{fig:proc:aml}}{} + \end{callself} + \end{sdblock} +% \prelevel +% \prelevel +% \begin{sdblock}{User abort?}{} +% \mess[0]{wallet}{{Request abort}}{exchange} +% \mess[0]{exchange}{{Abort confirmation}}{wallet} +% \end{sdblock} + \mess[0]{exchange}{{Initiate transfer}}{bank} + +\end{sequencediagram} + \caption{A customer deposits the coins issued by a Taler exchange (payment + service provider) into a bank account. Even if the + bank account is owned by the same customer, the + KYC checks from Section~\ref{sec:kyc:deposit} apply.} + \label{fig:int:deposit} +\end{figure} + +We do {\bf not} permit the customer to regain control over their funds {\em + unless} they pass the KYC/AML checks. The technical reason is simply that +the KYC/AML checks happen {\em after} the aggregation logic and at this point +refunds are no longer permitted. From a compliance perspective, this also +prevents malicious customers from risk-free probing of the system. diff --git a/doc/flows/int-pay.tex b/doc/flows/int-pay.tex new file mode 100644 index 000000000..2968c4c2e --- /dev/null +++ b/doc/flows/int-pay.tex @@ -0,0 +1,60 @@ +\section{Pay} \label{sec:pay} + +\begin{figure}[h!] + \begin{sequencediagram} + \newinst{wallet}{\shortstack{Customer wallet \\ + \\ \begin{tikzpicture} + \node [fill=gray!20,draw=black,thick,align=center] { Unique \\ Wallet ID}; + \end{tikzpicture} + }} + \newinst[1]{merchant}{\shortstack{Merchant \\ + \\ \begin{tikzpicture}[shape aspect=.5] + \tikzset{every node/.style={cylinder,shape border rotate=90, draw,fill=gray!25}} + \node at (1.5,0) {\shortstack{{{\tiny Database}}}}; + \end{tikzpicture} + }} + \newinst[1]{exchange}{\shortstack{Taler (exchange) \\ + \\ \begin{tikzpicture}[shape aspect=.5] + \tikzset{every node/.style={cylinder,shape border rotate=90, draw,fill=gray!25}} + \node at (1.5,0) {\shortstack{{{\tiny Database}}}}; + \end{tikzpicture} + }} + \newinst[1]{bank}{\shortstack{Merchant bank \\ + \\ \begin{tikzpicture} + \node [fill=gray!20,draw=black,thick,align=center] {Commercial \\ Accounts}; + \end{tikzpicture} + }} + \postlevel + \mess[0]{wallet}{Browse catalog}{merchant} + \mess[0]{merchant}{Commercial offer}{wallet} + \begin{callself}{wallet}{Review offer}{} + \end{callself} + \mess[0]{wallet}{Pay {(Coins)}}{merchant} + \mess[0]{merchant}{Deposit {(Coins)}}{exchange} + \begin{sdblock}{Acceptable account?}{} + \mess[0]{exchange}{{Refuse deposit}}{merchant} + \mess[0]{merchant}{{Refund purchase}}{wallet} + \end{sdblock} + \mess[0]{exchange}{{Confirm deposit}}{merchant} + \mess[0]{merchant}{Fulfill order}{wallet} + \begin{callself}{exchange}{Aggregate transactions}{} + \end{callself} + \begin{sdblock}{KYC/AML required?}{} + \begin{callself}{exchange}{Figures~\ref{fig:proc:kyc}, \ref{fig:proc:aml}}{} + \end{callself} + \end{sdblock} + \mess[0]{exchange}{{Initiate transfer}}{bank} + \end{sequencediagram} + \caption{Payments from a customer to merchant result in + depositing coins at the Taler exchange (payment service provider) + which then credits the merchant's bank account. + The KYC/AML checks are described in Section~\ref{sec:kyc:deposit}} + \label{fig:int:pay} +\end{figure} + +{\bf Internal note:} The exchange refusing a deposit immediately based on +unaccaptable merchant accounts may not be fully implemented (this is a very +recent feature, after all); especially the merchant then automatically +refunding the purchase to the customer is certainly missing. However, +the entire situation only arises when a merchant is incorrectly configured +and in violation of the terms of service. diff --git a/doc/flows/int-pull.tex b/doc/flows/int-pull.tex new file mode 100644 index 000000000..38caef6c8 --- /dev/null +++ b/doc/flows/int-pull.tex @@ -0,0 +1,56 @@ +\section{Pull payment (aka invoicing)} \label{sec:pull} + +\begin{figure}[h!] + \begin{sequencediagram} + \newinst{payer}{\shortstack{Payer \\ + \\ \begin{tikzpicture} + \node [fill=gray!20,draw=black,thick,align=center] {Pre-funded \\ Wallet}; + \end{tikzpicture} + }} + \newinst[2]{exchange}{\shortstack{Taler (exchange) \\ + \\ \begin{tikzpicture}[shape aspect=.5] + \tikzset{every node/.style={cylinder,shape border rotate=90, draw,fill=gray!25}} + \node at (1.5,0) {\shortstack{{{\tiny Database}}}}; + \end{tikzpicture} + }} + \newinst[2]{payee}{\shortstack{Payee \\ + \\ \begin{tikzpicture} + \node [fill=gray!20,draw=black,thick,align=center] { Unique \\ Wallet ID}; + \end{tikzpicture} + }} + \postlevel + \begin{callself}{payee}{Review pull payment fees}{} + \end{callself} + \mess[0]{payee}{{Create invoice (Wallet ID)}}{exchange} + + \mess[0]{exchange}{{Invoice ready}}{payee} + \mess[0]{payee}{{Send invoice (e.g. via QR code)}}{payer} + + \begin{callself}{payer}{Review invoice}{} + \end{callself} + \mess[0]{payer}{{Make payment (Coins)}}{exchange} + + \begin{sdblock}{Domestic wallet?}{} + \begin{callself}{exchange}{Figure~\ref{fig:proc:domestic}}{} + \end{callself} + \end{sdblock} + \begin{sdblock}{KYC/AML required?}{} + \begin{callself}{exchange}{Figures~\ref{fig:proc:kyc}, \ref{fig:proc:aml}}{} + \end{callself} + \end{sdblock} + + \mess[0]{exchange}{{Distribute digital cash}}{payee} + +\end{sequencediagram} + \caption{Interactions between wallets and Taler exchange + in a pull payment. KYC/AML checks are described in + Section~\ref{sec:kyc:pull}.} + \label{fig:int:pull} +\end{figure} + +We do {\bf not} permit the payer to regain control over their funds, once the +payment was made they are locked {\em until} the payee passes the KYC/AML +checks. We only do the AML/KYC process once the funds are locked at the +exchange. This ensures we know the actual transacted amounts (which may be +lower than the total amounts requested) and prevents risk-free probing +attacks. diff --git a/doc/flows/int-push.tex b/doc/flows/int-push.tex new file mode 100644 index 000000000..faea50f72 --- /dev/null +++ b/doc/flows/int-push.tex @@ -0,0 +1,48 @@ +\section{Push payment} \label{sec:push} + +\begin{figure}[h!] + \begin{sequencediagram} + \newinst{payer}{\shortstack{Payer \\ + \\ \begin{tikzpicture} + \node [fill=gray!20,draw=black,thick,align=center] {Pre-funded \\ Wallet}; + \end{tikzpicture} + }} + \newinst[2]{exchange}{\shortstack{Taler (exchange) \\ + \\ \begin{tikzpicture}[shape aspect=.5] + \tikzset{every node/.style={cylinder,shape border rotate=90, draw,fill=gray!25}} + \node at (1.5,0) {\shortstack{{{\tiny Database}}}}; + \end{tikzpicture} + }} + \newinst[2]{payee}{\shortstack{Payee \\ + \\ \begin{tikzpicture} + \node [fill=gray!20,draw=black,thick,align=center] { Unique \\ Wallet ID}; + \end{tikzpicture} + }} + \postlevel + \begin{callself}{payer}{Review push payment fees}{} + \end{callself} + \mess[0]{payer}{{Push funds (Coins)}}{exchange} + \mess[0]{payer}{{Offer payment (e.g. via QR code)}}{payee} + \begin{callself}{payee}{Review payment offer}{} + \end{callself} + \mess[0]{payee}{{Request funds (Wallet ID)}}{exchange} + \begin{sdblock}{Domestic wallet?}{} + \begin{callself}{exchange}{Figure~\ref{fig:proc:domestic}}{} + \end{callself} + \end{sdblock} + \begin{sdblock}{KYC/AML required?}{} + \begin{callself}{exchange}{Figures~\ref{fig:proc:kyc}, \ref{fig:proc:aml}}{} + \end{callself} + \end{sdblock} + \mess[0]{exchange}{{Distribute digital cash}}{payee} +% \postlevel + \begin{sdblock}{Payment offer expired?}{} + \mess[0]{exchange}{{Return funds}}{payer} + \end{sdblock} + +\end{sequencediagram} + \caption{Interactions between wallets and Taler exchange + in a push payment. KYC/AML checks are described + in Section~\ref{sec:kyc:push}.} + \label{fig:int:push} +\end{figure} diff --git a/doc/flows/int-refund.tex b/doc/flows/int-refund.tex new file mode 100644 index 000000000..3f11e5600 --- /dev/null +++ b/doc/flows/int-refund.tex @@ -0,0 +1,39 @@ +\section{Refund} + +\begin{figure}[h!] + \begin{sequencediagram} + \newinst{wallet}{\shortstack{Customer wallet \\ + \\ \begin{tikzpicture} + \node [fill=gray!20,draw=black,thick,align=center] { Unique \\ Wallet ID}; + \end{tikzpicture} + }} + \newinst[2]{merchant}{\shortstack{Merchant \\ + \\ \begin{tikzpicture}[shape aspect=.5] + \tikzset{every node/.style={cylinder,shape border rotate=90, draw,fill=gray!25}} + \node at (1.5,0) {\shortstack{{{\tiny Database}}}}; + \end{tikzpicture} + }} + \newinst[2]{exchange}{\shortstack{Taler (exchange) \\ + \\ \begin{tikzpicture}[shape aspect=.5] + \tikzset{every node/.style={cylinder,shape border rotate=90, draw,fill=gray!25}} + \node at (1.5,0) {\shortstack{{{\tiny Database}}}}; + \end{tikzpicture} + }} + \postlevel + \begin{callself}{merchant}{Initiate refund}{} + \end{callself} + \mess[0]{merchant}{{Refund offer (QR code)}}{wallet} + \mess[0]{wallet}{Download refund}{merchant} + \mess[0]{merchant}{Approve refund}{exchange} + \mess[0]{exchange}{Confirm refund}{merchant} + \mess[0]{merchant}{Return refund confirmation}{wallet} + \end{sequencediagram} + \caption{Refund processing when a merchant is unable to fulfill + a contract. Refunds must happen {\em before} the + exchange has aggregated the original transaction for + a bank transfer to the merchant. Furthermore, refunds + can only go to the customer who made the original payment + and the refund cannot exceed the amount of the original + payment.} + \label{fig:int:refund} +\end{figure} diff --git a/doc/flows/int-shutdown.tex b/doc/flows/int-shutdown.tex new file mode 100644 index 000000000..e8ee6feed --- /dev/null +++ b/doc/flows/int-shutdown.tex @@ -0,0 +1,48 @@ +\section{Shutdown} + +\begin{figure}[h!] + \begin{sequencediagram} + \newinst{wallet}{\shortstack{Customer wallet \\ + \\ \begin{tikzpicture} + \node [fill=gray!20,draw=black,thick,align=center] { Unique \\ Wallet ID}; + \end{tikzpicture} + }} + \newinst[2]{exchange}{\shortstack{Taler (exchange) \\ + \\ \begin{tikzpicture}[shape aspect=.5] + \tikzset{every node/.style={cylinder,shape border rotate=90, draw,fill=gray!25}} + \node at (1.5,0) {\shortstack{{{\tiny Database}}}}; + \end{tikzpicture} + }} + \newinst[2]{bank}{\shortstack{Customer bank \\ + \\ \begin{tikzpicture} + \node [fill=gray!20,draw=black,thick,align=center] {Checking \\ Accounts}; + \end{tikzpicture} + }} + \postlevel + + \begin{callself}{exchange}{Operator initiates shutdown}{} + \end{callself} + \mess[0]{exchange}{{Shutdown alert}}{wallet} + \begin{sdblock}{Bank account known?}{} + \begin{callself}{wallet}{Designate bank account}{} + \end{callself} + \end{sdblock} + \mess[0]{wallet}{{Deposit (Coins)}}{exchange} + \begin{sdblock}{Acceptable account?}{} + \mess[0]{exchange}{{Refuse deposit}}{wallet} + \end{sdblock} + \begin{sdblock}{KYC/AML required?}{} + \begin{callself}{exchange}{Figures~\ref{fig:proc:kyc}, \ref{fig:proc:aml}}{} + \end{callself} + \end{sdblock} + \mess[0]{exchange}{{Initiate transfer}}{bank} +\end{sequencediagram} + \caption{Shutdown interactions between customer, Taler exchange (payment + service provider) and bank.} + \label{fig:int:shutdown} +\end{figure} + +KYC/AML requirements are relaxed in cases where the customer is able to +cryptographically demonstrate that they previously withdrew these coins from +the designated checking account. Thus, KYC/AML checks here primarily still +apply if the customer received the funds via P2P transfers from other wallets. diff --git a/doc/flows/int-withdraw.tex b/doc/flows/int-withdraw.tex new file mode 100644 index 000000000..11ae25de9 --- /dev/null +++ b/doc/flows/int-withdraw.tex @@ -0,0 +1,49 @@ +\section{Withdraw} + +\begin{figure}[h!] + \begin{sequencediagram} + \newinst{wallet}{\shortstack{Customer wallet \\ + \\ \begin{tikzpicture} + \node [fill=gray!20,draw=black,thick,align=center] { Unique \\ Wallet ID}; + \end{tikzpicture} + }} + \newinst[2]{exchange}{\shortstack{Taler (exchange) \\ + \\ \begin{tikzpicture}[shape aspect=.5] + \tikzset{every node/.style={cylinder,shape border rotate=90, draw,fill=gray!25}} + \node at (1.5,0) {\shortstack{{{\tiny Database}}}}; + \end{tikzpicture} + }} + \newinst[2]{bank}{\shortstack{Customer bank \\ + \\ \begin{tikzpicture} + \node [fill=gray!20,draw=black,thick,align=center] {Checking \\ Accounts}; + \end{tikzpicture} + }} + \postlevel + \mess[0]{wallet}{Withdraw {(Amount)}}{exchange} + \mess[0]{exchange}{{Configuration (ToS, Fees)}}{wallet} + \begin{sdblock}{once}{} + \begin{callself}{wallet}{Accept ToS}{} + \end{callself} + \end{sdblock} + \begin{callself}{wallet}{Review withdraw fees}{} + \end{callself} + \mess[0]{wallet}{{Initiate transfer (Amount, Credit account, Wallet ID)}}{bank} + \mess[0]{bank}{{Credit (Wallet ID)}}{exchange} + + \begin{sdblock}{Acceptable transfer?}{} + \mess[0]{exchange}{{Bounce funds}}{bank} + \end{sdblock} + \postlevel + \mess[0]{exchange}{Confirm wire transfer}{wallet} + \mess[0]{wallet}{Request digital cash}{exchange} + \mess[0]{exchange}{Distribute digital cash}{wallet} + \postlevel + \begin{sdblock}{Withdraw period expired?}{} + \mess[0]{exchange}{{Return remaining funds}}{bank} + \end{sdblock} +\end{sequencediagram} + \caption{Withdraw interactions between customer, Taler exchange (payment + service provider) and bank. The amount of digital cash distributed is + subject to limits per origin account (see Section~\ref{sec:kyc:withdraw}).} + \label{fig:int:withdraw} +\end{figure} diff --git a/doc/flows/kyc-balance.tex b/doc/flows/kyc-balance.tex new file mode 100644 index 000000000..de8953665 --- /dev/null +++ b/doc/flows/kyc-balance.tex @@ -0,0 +1,58 @@ +\section{KYC: Balance} + +Note: this process is not implemented and would require non-trivial extra work +if required. + +\begin{figure}[h!] + \begin{center} +\begin{tikzpicture}[node distance=1cm,font=\sffamily, + start/.style={rectangle, rounded corners, minimum width=3cm, minimum height=1cm,text centered, draw=black, fill=yellow!30}, + end/.style={rectangle, rounded corners, minimum width=3cm, minimum height=1cm,text centered, draw=black, fill=red!30}, + process/.style={rectangle, minimum width=3cm, minimum height=1cm, text centered, draw=black, fill=orange!30}, + failed/.style={rectangle, rounded corners, minimum width=3cm, minimum height=1cm, text centered, draw=black, fill=red!30}, + io/.style={trapezium, trapezium left angle=70, trapezium right angle=110, minimum width=3cm, minimum height=1cm, text centered, draw=black, fill=blue!30}, + decision/.style={diamond, minimum width=3cm, minimum height=1cm, text centered, draw=black, fill=green!30}, + arr/.style={very thick,-latex}, + every edge quotes/.style = {auto, font=\footnotesize, sloped} + ] + \node (start) [start] {Start}; + \node (balance) [decision,below=of start,text width=3cm] {Transaction leaves wallet balance below AML threshold?}; + \node (registered) [decision,below=of balance,text width=3cm] {Wallet has been subject to KYC?}; + \node (kyc) [process, below=of registered] {KYC process}; + \node (aml) [process, left=of kyc] {AML process}; + \node (allow) [end, right=of balance] {Allow}; + \node (deny) [failed, right=of registered] {Deny}; + \draw[arr] (start) -> (balance) {}; + \draw[arr] (balance) -> (registered); + \draw (balance) edge["No"] (registered); + \draw[arr] (balance) -> (allow); + \draw (balance) edge["Yes"] (allow); + + \draw[arr] (registered) -> (kyc); + \draw (registered) edge["No"] (kyc); + \draw[arr] (registered) -> (deny); + \draw (registered) edge["Yes"] (deny); + + \draw[arr] (kyc) -> (deny); + \draw (kyc) edge["Failed"] (deny); + \draw[arr] (kyc) -> (aml); + \draw (kyc) edge["Ok"] (aml); + + \draw[arr] (aml) -> (balance.west); + \draw (aml) edge["New threshold"] (balance.west); +\end{tikzpicture} + \end{center} + \caption{Regulatory process when a wallet exceeds its AML threshold. + When the transfer is denied the transaction (withdraw, P2P transfer) + is refused by the wallet.} +\end{figure} + + +\begin{table}[h!] + \caption{Settings for the balance trigger.} + \begin{tabular}{l|l|r} + {\bf Setting} & {\bf Type} & {\bf Value} \\ \hline \hline + KYC threshold & Amount & {\em 5000 CHF} \\ + Default AML threshold & Amount & {\em 5000 CHF} \\ + \end{tabular} +\end{table} diff --git a/doc/flows/kyc-deposit.tex b/doc/flows/kyc-deposit.tex new file mode 100644 index 000000000..0132cebf6 --- /dev/null +++ b/doc/flows/kyc-deposit.tex @@ -0,0 +1,85 @@ +\section{KYC: Deposit} \label{sec:kyc:deposit} + +\begin{figure}[h!] + \begin{center} +\begin{tikzpicture}[node distance=1cm,font=\sffamily, + start/.style={rectangle, rounded corners, minimum width=3cm, minimum height=1cm,text centered, draw=black, fill=yellow!30}, + end/.style={rectangle, rounded corners, minimum width=3cm, minimum height=1cm,text centered, draw=black, fill=red!30}, + process/.style={rectangle, minimum width=3cm, minimum height=1cm, text centered, draw=black, fill=orange!30}, + failed/.style={rectangle, rounded corners, minimum width=3cm, minimum height=1cm, text centered, draw=black, fill=red!30}, + io/.style={trapezium, trapezium left angle=70, trapezium right angle=110, minimum width=3cm, minimum height=1cm, text centered, draw=black, fill=blue!30}, + decision/.style={diamond, minimum width=3cm, minimum height=1cm, text centered, draw=black, fill=green!30}, + arr/.style={very thick,-latex}, + every edge quotes/.style = {auto, font=\footnotesize, sloped} + ] + \node (start) [start] {Start}; + \node (country) [decision,below=of start,text width=2.5cm] {Target account in allowed country?}; + \node (amount) [decision, below=of country,text width=2.5cm] {Target account received less than KYB threshold?}; + \node (kyc) [process, right=of amount] {KYB process}; + \node (high) [decision, below=of amount,text width=2.5cm] {Target account received more than its AML threshold?}; + \node (aml) [process, right=of high] {AML process}; + \node (dummy) [below right=of aml] {}; + \node (allow) [end, below right=of dummy] {Allow}; + \node (deny) [failed, right=of kyc] {Deny}; + \draw[arr] (start) -> (country) {}; + + \draw[arr] (country) -> (amount); + \draw (country) edge["Yes"] (amount); + + \draw[arr] (country.east) -> (deny); + \draw (country.east) edge["No"] (deny); + + \draw[arr] (amount) -> (high); + \draw (amount) edge["Yes"] (high); + + \draw[arr] (amount.east) -> (kyc); + \draw (amount.east) edge["No"] (kyc); + + \draw[arr] (kyc) -> (deny); + \draw (kyc) edge["Failed"] (deny); + + \draw[arr] (kyc) -> (high); + \draw (kyc) edge["Succeeded"] (high); + + \draw[arr] (high.south) -> (allow); + \draw (high.south) edge["Yes"] (allow); + + \draw[arr] (high.east) -> (aml); + \draw (high.east) edge["No"] (aml); + + \draw[arr] (aml) -> (deny); + \draw (aml) edge["Violation"] (deny); + + \draw[arr] (aml) -> (allow); + \draw (aml) edge["Ok"] (allow); +\end{tikzpicture} + \end{center} + \caption{Regulatory process when depositing digital cash into a bank + account. When the transfer is denied, the money is held in escrow + until authorities authorize the transfer.} +\end{figure} + + +\begin{table}[h!] + \caption{Settings for the deposit trigger. Note that the operation + must satisfy all of the given rules.} + \begin{tabular}{l|l|r} + {\bf Setting} & {\bf Type} & {\bf Value} \\ \hline \hline + Allowed bank accounts & RFC 8905 RegEx & {\em CH*} \\ \hline + KYB deposit threshold & Amount/month & {\em 5000 CHF} \\ + KYB deposit threshold & Amount/year & {\em 15000 CHF} \\ + Default AML deposit threshold & Amount/month & {\em 5000 CHF} \\ + \end{tabular} +\end{table} + +%The KYB deposit threshold of 5'000 \CURRENCY{} per month and than 15'000 +%\CURRENCY{} per year ensure compliance. % with article 48-1b. + +Additionally, our terms of service will prohibit businesses to receive +amounts exceeding 1'000 \CURRENCY{} per transaction. +%(well below the 15'000 \CURRENCY{} threshold defined in article 24-1c). + +SMS-Identification is done by in-house software. KYB data is initially +obtained and vetted by one of several external KYB providers before +being passed for manual validation by our own staff who can then +determine appropriate AML thresholds and set review criteria. diff --git a/doc/flows/kyc-pull.tex b/doc/flows/kyc-pull.tex new file mode 100644 index 000000000..4d4f2c852 --- /dev/null +++ b/doc/flows/kyc-pull.tex @@ -0,0 +1,92 @@ +\section{KYC/AML: Pull Payment} \label{sec:kyc:pull} + +\begin{figure}[h!] + \begin{center} +\begin{tikzpicture}[node distance=0.9cm,font=\sffamily, + start/.style={rectangle, rounded corners, minimum width=3cm, minimum height=1cm,text centered, draw=black, fill=yellow!30}, + end/.style={rectangle, rounded corners, minimum width=3cm, minimum height=1cm,text centered, draw=black, fill=red!30}, + process/.style={rectangle, minimum width=3cm, minimum height=1cm, text centered, draw=black, fill=orange!30}, + failed/.style={rectangle, rounded corners, minimum width=3cm, minimum height=1cm, text centered, draw=black, fill=red!30}, + io/.style={trapezium, trapezium left angle=70, trapezium right angle=110, minimum width=3cm, minimum height=1cm, text centered, draw=black, fill=blue!30}, + decision/.style={diamond, minimum width=3cm, minimum height=1cm, text centered, draw=black, fill=green!30}, + arr/.style={very thick,-latex}, + every edge quotes/.style = {auto, font=\footnotesize, sloped} + ] + \node (start) [start] {Start}; + \node (wallet) [decision,below=of start,text width=2.5cm] {Wallet linked to (domestic) phone number?}; + \node (domestic) [process, right=of wallet] {Validate phone number}; + \node (amount) [decision, below=of wallet,text width=2.5cm] {Wallet received less than KYC threshold from other wallets?}; + \node (kyc) [process, right=of amount] {KYC process}; + \node (high) [decision, below=of amount,text width=2.5cm] {Wallet received more than its AML threshold?}; + \node (aml) [process, right=of high] {AML process}; + \node (dummy) [below right=of aml] {}; + \node (allow) [end, below right=of dummy] {Allow invoicing}; + \node (deny) [failed, right=of kyc] {Deny}; + \draw[arr] (start) -> (wallet) {}; + + \draw[arr] (wallet) -> (amount); + \draw (wallet) edge["Yes"] (amount); + + \draw[arr] (wallet.east) -> (domestic); + \draw (wallet.east) edge["No"] (domestic); + + \draw[arr] (domestic) -> (amount); + \draw (domestic) edge["Confirmed"] (amount); + + \draw[arr] (domestic) -> (deny); + \draw (domestic) edge["Failed"] (deny); + + \draw[arr] (amount) -> (high); + \draw (amount) edge["Yes"] (high); + + \draw[arr] (amount.east) -> (kyc); + \draw (amount.east) edge["No"] (kyc); + + \draw[arr] (kyc) -> (deny); + \draw (kyc) edge["Failed"] (deny); + + \draw[arr] (kyc) -> (high); + \draw (kyc) edge["Succeeded"] (high); + + \draw[arr] (high.south) -> (allow); + \draw (high.south) edge["Yes"] (allow); + + \draw[arr] (high.east) -> (aml); + \draw (high.east) edge["No"] (aml); + + \draw[arr] (aml) -> (deny); + \draw (aml) edge["Violation"] (deny); + + \draw[arr] (aml) -> (allow); + \draw (aml) edge["Ok"] (allow); +\end{tikzpicture} + \end{center} + \caption{Regulatory process when receiving payments from another wallet. + The threshold depends on the risk profile from the KYC process. + When KYC thresholds would be passed, the receiving wallet cannot + generate a valid invoice until it has provided the KYC data. + When a transfer is denied by AML staff, the money is held in escrow + until authorities authorize the transfer.} +\end{figure} + + +\begin{table}[h!] + \caption{Settings for the pull payment trigger. Note that the operation + must satisfy all of the given rules.} + \begin{tabular}{l|l|r} + {\bf Setting} & {\bf Type} & {\bf Value} \\ \hline \hline + Permitted phone numbers & Dialing prefix & {\em +41} \\ + SMS-Identification & Amount/month & {\em 0 CHF} \\ + P2P KYC threshold & Amount/month & {\em 5000 CHF} \\ + P2P KYC threshold & Amount/year & {\em 15000 CHF} \\ + Default P2P AML threshold & Amount/month & {\em 5000 CHF} \\ + \end{tabular} +\end{table} + +%The P2P KYC thresholds of 5'000 \CURRENCY{} per month and than 15'000 +%\CURRENCY{} per year ensure compliance with article 49-2c. + +SMS-Identification is done by in-house software. KYC data is initially +obtained and vetted by one of several external KYC providers before +being passed for manual validation by our own staff who can then +determine appropriate AML thresholds and set review criteria. diff --git a/doc/flows/kyc-push.tex b/doc/flows/kyc-push.tex new file mode 100644 index 000000000..c74b3ce16 --- /dev/null +++ b/doc/flows/kyc-push.tex @@ -0,0 +1,90 @@ +\section{KYC/AML: Push Payment} \label{sec:kyc:push} + +\begin{figure}[h!] + \begin{center} +\begin{tikzpicture}[node distance=0.9cm,font=\sffamily, + start/.style={rectangle, rounded corners, minimum width=3cm, minimum height=1cm,text centered, draw=black, fill=yellow!30}, + end/.style={rectangle, rounded corners, minimum width=3cm, minimum height=1cm,text centered, draw=black, fill=red!30}, + process/.style={rectangle, minimum width=3cm, minimum height=1cm, text centered, draw=black, fill=orange!30}, + failed/.style={rectangle, rounded corners, minimum width=3cm, minimum height=1cm, text centered, draw=black, fill=red!30}, + io/.style={trapezium, trapezium left angle=70, trapezium right angle=110, minimum width=3cm, minimum height=1cm, text centered, draw=black, fill=blue!30}, + decision/.style={diamond, minimum width=3cm, minimum height=1cm, text centered, draw=black, fill=green!30}, + arr/.style={very thick,-latex}, + every edge quotes/.style = {auto, font=\footnotesize, sloped} + ] + \node (start) [start] {Start}; + \node (wallet) [decision,below=of start,text width=2.5cm] {Wallet linked to (domestic) phone number?}; + \node (domestic) [process, right=of wallet] {Validate phone number}; + \node (amount) [decision, below=of wallet,text width=2.5cm] {Wallet received less than KYC threshold from other wallets?}; + \node (kyc) [process, right=of amount] {KYC process}; + \node (high) [decision, below=of amount,text width=2.5cm] {Wallet received more than its AML threshold?}; + \node (aml) [process, right=of high] {AML process}; + \node (dummy) [below right=of aml] {}; + \node (allow) [end, below right=of dummy] {Allow}; + \node (deny) [failed, right=of kyc] {Deny}; + \draw[arr] (start) -> (wallet) {}; + + \draw[arr] (wallet) -> (amount); + \draw (wallet) edge["Yes"] (amount); + + \draw[arr] (wallet.east) -> (domestic); + \draw (wallet.east) edge["No"] (domestic); + + \draw[arr] (domestic) -> (amount); + \draw (domestic) edge["Confirmed"] (amount); + + \draw[arr] (domestic) -> (deny); + \draw (domestic) edge["Failed"] (deny); + + \draw[arr] (amount) -> (high); + \draw (amount) edge["Yes"] (high); + + \draw[arr] (amount.east) -> (kyc); + \draw (amount.east) edge["No"] (kyc); + + \draw[arr] (kyc) -> (deny); + \draw (kyc) edge["Failed"] (deny); + + \draw[arr] (kyc) -> (high); + \draw (kyc) edge["Succeeded"] (high); + + \draw[arr] (high.south) -> (allow); + \draw (high.south) edge["Yes"] (allow); + + \draw[arr] (high.east) -> (aml); + \draw (high.east) edge["No"] (aml); + + \draw[arr] (aml) -> (deny); + \draw (aml) edge["Violation"] (deny); + + \draw[arr] (aml) -> (allow); + \draw (aml) edge["Ok"] (allow); +\end{tikzpicture} + \end{center} + \caption{Regulatory process when receiving payments from another wallet. + The threshold depends on the risk profile from the KYC process. + When the transfer is denied, the money is held in escrow + until authorities authorize the transfer.} +\end{figure} + + +\begin{table}[h!] + \caption{Settings for the push payment trigger. Note that the operation + must satisfy all of the given rules.} + \begin{tabular}{l|l|r} + {\bf Setting} & {\bf Type} & {\bf Value} \\ \hline \hline + Permitted phone numbers & Dialing prefix & {\em +41} \\ + SMS-Identification & Amount/month & {\em 0 CHF} \\ + P2P KYC threshold & Amount/month & {\em 5000 CHF} \\ + P2P KYC threshold & Amount/year & {\em 15000 CHF} \\ + Default P2P AML threshold & Amount/month & {\em 5000 CHF} \\ + \end{tabular} +\end{table} + +%The P2P KYC thresholds of 5'000 \CURRENCY{} per month and than 15'000 +%\CURRENCY{} per year ensure compliance. % with article 49-2c. + +SMS-Identification is done by in-house software. KYC data is initially +obtained and vetted by one of several external KYC providers before +being passed for manual validation by our own staff who can then +determine appropriate AML thresholds and set review criteria. diff --git a/doc/flows/kyc-withdraw.tex b/doc/flows/kyc-withdraw.tex new file mode 100644 index 000000000..b5605618e --- /dev/null +++ b/doc/flows/kyc-withdraw.tex @@ -0,0 +1,58 @@ +\section{KYC: Withdraw} \label{sec:kyc:withdraw} + +\begin{figure}[h!] + \begin{center} +\begin{tikzpicture}[node distance=1cm,font=\sffamily, + start/.style={rectangle, rounded corners, minimum width=3cm, minimum height=1cm,text centered, draw=black, fill=yellow!30}, + end/.style={rectangle, rounded corners, minimum width=3cm, minimum height=1cm,text centered, draw=black, fill=red!30}, + process/.style={rectangle, minimum width=3cm, minimum height=1cm, text centered, draw=black, fill=orange!30}, + failed/.style={rectangle, rounded corners, minimum width=3cm, minimum height=1cm, text centered, draw=black, fill=red!30}, + io/.style={trapezium, trapezium left angle=70, trapezium right angle=110, minimum width=3cm, minimum height=1cm, text centered, draw=black, fill=blue!30}, + decision/.style={diamond, minimum width=3cm, minimum height=1cm, text centered, draw=black, fill=green!30}, + arr/.style={very thick,-latex}, + every edge quotes/.style = {auto, font=\footnotesize, sloped} + ] + \node (start) [start] {Start}; + \node (country) [decision,below=of start,text width=3cm] {Wire transfer originates from allowed country?}; + \node (amount) [decision, below=of country,text width=3cm] {Transferred less than maximum amount from origin account over last month?}; + \node (allow) [end, below=of amount] {Allow}; + \node (deny) [failed, right=of allow] {Deny}; + \draw[arr] (start) -> (country) {}; + \draw[arr] (country) -> (amount); + \draw (country) edge["Yes"] (amount); + \draw[arr] (country.east) -> (deny); + \draw (country.east) edge["No"] (deny); + \draw[arr] (amount) -> (allow); + \draw (amount) edge["Yes"] (allow); + \draw[arr] (amount.east) -> (deny); + \draw (amount.east) edge["No"] (deny); +\end{tikzpicture} + \end{center} + \caption{Regulatory process when withdrawing digital cash from a + bank account. + If the transfer is denied or the user fails to withdraw the + funds for any other reason, the money is automatically returned + after the bounce period (see Table~\ref{table:kyc:withdraw:settings}) to + the originating bank account.} + \label{fig:kyc:withdraw} +\end{figure} + +\begin{table}[h!] + \caption{Settings for the withdraw trigger. Note that the operation + must satisfy all of the given rules.} \label{table:kyc:withdraw:settings} + \begin{tabular}{l|l|r} + {\bf Setting} & {\bf Type} & {\bf Value} \\ \hline \hline + Allowed bank accounts & RFC 8905 RegEx & {\em CH*} \\ \hline + SMS-Identification & Amount/month & {\em 200 CHF} \\ + Withdraw limit & Amount/month & {\em 5000 CHF} \\ + Withdraw limit & Amount/year & {\em 15000 CHF} \\ + Bounce period & Delay & 1 month \\ + \end{tabular} +\end{table} + +%The limit of 200 \CURRENCY{} results from article 48-2. Strictly limiting +%withdrawals to less than 5'000 \CURRENCY{} per month and less than 15'000 +%\CURRENCY{} per year assures compliance with article 48-1c. + +SMS-Identification is done by in-house software. Withdraw limits are +hard and cannot be raised even if the customer is known. diff --git a/doc/flows/main.de.tex b/doc/flows/main.de.tex new file mode 100644 index 000000000..5f224007d --- /dev/null +++ b/doc/flows/main.de.tex @@ -0,0 +1,239 @@ +% This is a (partial) translation of main.tex into +% German. Please keep the structure as parallel as +% possible when improving / expanding the translation! +\documentclass[10pt,a4paper,oneside]{book} +\usepackage[utf8]{inputenc} +\usepackage{url} +\usepackage{enumitem} +\usepackage{graphicx} +\usepackage{hyperref} +\usepackage{qrcode} +\usepackage{pgf-umlsd} +\usepackage{tikz} +\usetikzlibrary{shapes,arrows} +\usetikzlibrary{positioning} +\usetikzlibrary{calc} +\usetikzlibrary{quotes} +\author{Christian Grothoff} +\title{Flows in the GNU Taler System} + +\begin{document} + +\tableofcontents + +\newcommand\TALER{TALER OPERATIONS AG} +\newcommand\CURRENCY{CHF} +\newcommand\LAND{der Schweiz} + +\section{Transaktionen im Taler-Bezahlsystem}\label{sec:Transaktionen} + +Dieser Abschnitt stellt die Transaktionen im Taler-Bezahlsystem +vor. Die Grafiken geben wieder, in welcher Reihenfolge die beteiligten +Parteien interagieren. \\ +F\"ur jede einzelne Transaktion ist die automatische Ausl\"osung von +Compliance-Prozessen durch den Taler-Exchange einstellbar. +Die im Rahmen des jeweiligen Compliance-Prozesses erzwungenen +Pr\"ufschritte beschreibt Abschnitt~\ref{sec:triggers}. + +Folgende Transaktionen kommen als Ausl\"oser f\"ur AML- und KYC-Prozesse +in Betracht: +\begin{description}[noitemsep] + \item[withdraw] Ein Nutzer hebt digitales Bargeld (e-money) in Form von + Taler-Coins in ein Taler-Wallet ab + \item[reimburse] Ein Nutzer l\"asst den Gegenwert von Taler-Coins vom + Taler-Exchange an das urspr\"ungliche IBAN-Bankkonto zur\"uck\"uberweisen + \item[pay] Ein Nutzer zahlt zugunsten eines IBAN-Bankkontos des Empf\"angers + \item[refund] Ein Verk\"aufer erteilt einem Zahlenden die R\"uckerstattung + eines Zahlbetrags + \item[push] Ein Nutzer sendet einen Zahlbetrag an ein anderes Taler-Wallet + \item[pull] Ein Nutzer stellt einem anderen Taler-Wallet eine Rechnung aus + und fordert eine Zahlung von diesem Wallet + \item[shutdown] Der Betreiber des Taler-Exchange informiert die Inhaber von + Coins, die diese von jenem Exchange abgehoben hatten, dass der Exchange + geplant eingestellt und die Gegenwerte der Coins restituiert werden +\end{description} + +Die Nutzer beginnen ein gesch\"aftliches Nutzungsverh\"altnis mit +\TALER{}, wenn sie ihre Taler-Wallets anweisen, eine Abhebung durchzuf\"uhren. +Das Taler-Bezahlsystem verwendet jedoch keine Konten, sondern wert-basierte +Token und explizit keine konten-basierten Geld-\"Aquivalente. +Taler soll digitales Bargeld sein und erlaubt technisch bedingt +kein Nachvollziehen der Transaktionen seiner Nutzer, wie es Konten mit +Eing\"angen und Ausg\"angen von Zahlungen erm\"oglichen w\"urden. +Es gibt daher kein ``Er\"offnen'' oder ``Schliessen'' von Konten der Nutzer. +Die Begriffe ``opening'' und ``closing'' lassen sich deshalb auch nicht auf +das System anwenden oder \"ubertragen. \\ + +Die Nutzer k\"onnen +\begin{enumerate}[noitemsep] +\item die treuh\"andisch verwalteten Einlagen gezielt auf ein bestimmtes +Bankkonto auszahlen lassen, +%(siehe Abschnitt~\ref{sec:deposit}) +\item an einen Verk\"aufer zahlen, +%(siehe Abschnitt~\ref{sec:deposit}) +\item einem anderen Empf\"anger mittels peer-to-peer-Verfahren Coins zukommen +lassen +%(siehe Abschnitte~\ref{sec:push} und~\ref{sec:pull}) +\item die Coins in ihrem Wallet, das verloren ging oder zerst\"ort wurde, +durch Ablauf der G\"ultigkeit entwerten lassen (dies w\"are ebenso der Fall +bei einer langen Zeit ohne Internet-Anbindung oder ohne Installation), +\item den Wert der Coins im Wallet durch Zahlung von Geb\"uhren f\"ur +die Verl\"angerung ihrer G\"ultigkeit langsam verringern lassen. +%(siehe Abschnitt~\ref{sec:fees:coin}) +\end{enumerate} + +Das Taler-Bezahlsystem verwehrt den Nutzern kategorisch die Abhebung +von h\"oheren Betr\"agen als 5.000 \CURRENCY{} pro Monat bzw. von +mehr als 15.000 \CURRENCY{} pro Jahr. Damit wird gew\"ahrleistet, +dass die Nutzer stets unterhalb der Grenzwerte bleiben, ab denen die +meisten Pr\"ufschritte aufgrund regulatorischer Bestimmungen erforderlich +werden. \TALER{} stellt dar\"uber hinaus sicher, dass die Nutzer +ausschliesslich in \LAND{} ans\"assig sind +(siehe Abschnitt~\ref{sec:proc:domestic}), da auf ihrer Seite ein Bankkonto +in \LAND{} f\"ur die \"Uberweisungen an den Taler-Exchange und/oder +eine Telefonnummer mit entsprechender Vorwahl (++41) ben\"otigt werden. +Zus\"atzlich setzt das Taler-Wallet zu jeder Zeit eine Obergrenze +von 5.000 \CURRENCY{} auf die Coin-Betr\"age in Summe fest, so dass es +keine weitere Abhebung \"uber diesen Grenzwert hinaus bewirken kann. + +F\"ur {\bf Verk\"aufer} beginnt ein gesch\"aftliches Nutzungsverh\"altnis +mit \TALER{}, sobald sie Geldeing\"ange auf ihren IBAN-Bankkonten erhalten, +die als Zahlungen von Nutzern des Taler-Bezahlsystems ausgel\"ost wurden +(siehe Abschnitt~\ref{sec:deposit}). Sollten die Summen der Eing\"ange +5.000 \CURRENCY{} pro Monat bzw. 15.000 \CURRENCY{} pro Jahr \"ubersteigen, +kommt es zu einer KYB-Pr\"ufung, die dem Begriff ``Er\"offnen'' eines +Kontos entspricht und die eine aktualisierte KYB-Information sowie +die Pr\"ufung von Sanktionslisten erfordert, sofern der Verk\"aufer +innerhalb von 24 Monaten wenigstens einen Geldeingang erhielt. + +Im Gegensatz zu normalen Nutzern k\"onnen Verk\"aufer im Prinzip +Zahlungen ohne Limit empfangen. Allerdings m\"ussen diese Transaktionen +auch wirklich als Eing\"ange auf dem Bankkonto des Unternehmens verzeichnet +werden (im Kontoauszug). In Abh\"angigkeit von den an das Gesch\"aftskonto +\"uberwiesenen Betr\"agen wird der Verk\"aufer einer KYB-Pr\"ufung unterzogen +(siehe Abschnitt~\ref{sec:KYB}). Dies gilt ebenso f\"ur +Geldw\"asche-\"Uberpr\"ufungen (AML checks). + +Das Taler-Bezahlsystem transferiert lediglich Gelder auf die bestehenden +Bankkonten der Verk\"aufer, die f\"ur ihre G\"uterleistungen Zahlungen +der Nutzer erhalten, f\"ur die bereits bei der \"Uberweisung von deren +Kundenkonten eine KYC-Pr\"ufung erfolgte. Daher wird unseres Erachtens +der Betreiber eines Taler-Exchange keine Mittelherkunft verlangen bzw. +nachweisen m\"ussen +\footnote{Wenn Unternehmen das Taler-Bezahlsystem ihrerseits f\"ur +Zahlungen nutzen wollen, m\"ussen sie genauso wie alle anderen Nutzer +zuerst Geld von ihrem Bankkonto an einen Taler-Exchange \"uberweisen, +eine KYC-Pr\"ufung absolvieren und dann ihr Wallet Coins abheben lassen. +F\"ur die gesch\"aftlichen K\"aufer gelten ebenfalls die Limits wie +f\"ur alle anderen Nutzer.}. + + +\include{int-withdraw} +\include{int-deposit} +\include{int-pay} +\include{int-refund} +\include{int-push} +\include{int-pull} +\include{int-shutdown} + + + +\chapter{Regulatory Triggers} \label{chap:triggers} + +In this chapter we show decision diagrams for regulatory processes of the +various core operations of the GNU Taler payment system. In each case, the +{\bf start} state refers to one of the interactions described in the previous +chapter. The payment system will then use the process to arrive at an {\bf + allow} decision which permits the transaction to go through, or at a {\bf + deny} decision which ensures that the funds are not moved. + +The specific {\em decisions} (in green) depend on the risk profile and the +regulatory environment. The tables in each section list the specific values +that are to be configured. + +There are five types if interactions that can trigger regulatory processes: + +\begin{description} + \item[withdraw] a customer withdraws digital cash from their {\bf bank account} + \item[deposit] a merchant's {\bf bank account} is designated to receive a payment in digital cash + \item[push] a {\bf wallet} accepts a payment from another wallet + \item[pull] a {\bf wallet} requests a payment from another wallet + \item[balance] a withdraw or P2P payment causes the balance of a {\bf wallet} to exceed a given threshold +\end{description} + +We note in bold the {\bf anchor} for the regulator process. The anchor is used +to link the interaction to an identity. Once an identity has been established +for a particular anchor, that link is considered established for all types of +activities involving that anchor. A wallet is uniquely identified in the +system by its unique cryptographic key. A bank account is uniquely identified +in the system by its (RFC 8905) bank routing data (usually including BIC, IBAN +and account owner name). + +The KYC and AML processes themselves are described in +Chapter~\ref{chap:regproc}. + +\include{kyc-withdraw} +\include{kyc-deposit} +\include{kyc-push} +\include{kyc-pull} +\include{kyc-balance} + +\chapter{Regulatory Processes} \label{chap:regproc} + +This chapter describes the interactions between the customer, exchange and +organizations or staff assisting with regulatory processes designed to ensure +that customers are residents in the area of operation of the payment service +provider, are properly identified, and do not engage in money laundering. + +The three main regulatory processes are: + +\begin{description} +\item[domestic check] This process establishes that a user is generally + eligible to use the payment system. The process checks that the user has an + eligible address, but stops short of establishing the user's identity. +\item[kyc] This process establishes a user's legal identity, possibly + using external providers to review documents and check against blacklists. +\item[aml] The AML process reviews suspicious payment activities for + money laundering. Here AML staff reviews all collected information. +\end{description} + +\include{proc-domestic} +%\include{proc-kyc} +\include{proc-kyb} +\include{proc-aml} + +\chapter{Fees} \label{chap:fees} + +The business model for operating a Taler exchange is to charge transaction +fees. Fees are charged on certain operations by the exchange. There are two +types of fees, {\bf wire fees} and {\bf coin fees}. This chapter describes +the fee structure. + +Fixed, amount-independent {\bf wire fees} are charged on wire transfers using +the core banking system. Details on wire fees are described in +Section~\ref{sec:fees:wire}. + +Coin fees are more complex, as they do not exactly follow neither the usual +percentage of volume model of other payment systems. Instead, coin fees are +applied per coin, resulting in a {\em logarithmic} fee structure. As a +result, the effective fee {\em percentage} for tiny transactions is high (for +example 50\% for transactions of 0.0025 CHF) while the effective fee +percentage for large transactions is nominal (for example $\approx$ 0.05\% for +transactions of $\approx$ 40 CHF). Details on coin fees are described in +Section~\ref{sec:fees:coin}. + +Fees are configurable (and that fee types beyond those described here are +supported by the software). Thus, the specific fees may be adjusted in the +future based on business decisions. However, changes to the fees are never +retroactively applied to coins already in circulation. Wire fees that have +been publicly announced for a particular time period also cannot be changed. +Finally, any change to the terms of service must also be explicitly accepted +by the users before they withdraw additional funds. + + +\include{fees-wire} +\include{fees-coins} +%\include{fees-other} + + +\end{document} diff --git a/doc/flows/main.tex b/doc/flows/main.tex new file mode 100644 index 000000000..d46d93251 --- /dev/null +++ b/doc/flows/main.tex @@ -0,0 +1,206 @@ +\documentclass[10pt,a4paper,oneside]{book} +\usepackage[utf8]{inputenc} +\usepackage{url} +\usepackage{graphicx} +\usepackage{hyperref} +\usepackage{qrcode} +\usepackage{pgf-umlsd} +\usepackage{tikz} +\usetikzlibrary{shapes,arrows} +\usetikzlibrary{positioning} +\usetikzlibrary{calc} +\usetikzlibrary{quotes} +\author{Christian Grothoff} +\title{Flows in the GNU Taler System} + +\newcommand\CURRENCY{CHF} + +\begin{document} + +\maketitle +\tableofcontents + +\chapter{Interactions} \label{chap:interactions} + +This chapter introduces the main payment interactions in the GNU Taler payment +system. For each interaction, we introduce the parties involved and in which +order they interact and how. In each interaction it is possible that the +Taler exchange needs to trigger a compliance process. These regulatory +riggers are described in more detail in Chapter~\ref{chap:triggers}. + +The main interactions of the system are: + +\begin{description} + \item[withdraw] a customer withdraws digital cash to their wallet + \item[deposit] a customer returns digital cash into their bank account + \item[pay] a customer pays into bank account of a merchant + \item[refund] a merchant decides to return funds to a customer + \item[push] a customer sends a payment to another wallet + \item[pull] a customer requests a payment from another wallet (effectively sending an invoice) + \item[shutdown] the Taler payment system operator informs the customers that the system is being shut down for good +\end{description} + +In the analysis of the legal requirements, it is important to differentiate +between transactions between wallets (customer-to-customer) and transactions +where money flows from a wallet into a bank account (customer-to-merchant) as +these have different limits: When digital coins are used to pay at a business in +Taler, the business never actually receives usable digital coins but instead +the amount is always directly credited to their bank account. Depending on +the transacted amounts, the business will nevertheless be subject to KYB +(Section~\ref{sec:proc:kyb}) and AML checks. + +{\bf Customers} begin their business relationship with us when they withdraw +digital cash. Taler has no accounts (this is digital cash) and thus there is +no ``opening'' or ``closing'' of accounts for consumers. Given digital cash, +the customers can either (1) deposit the funds explicitly into a bank account +(see Section~\ref{sec:deposit}), (2) pay a merchant (see +Section~\ref{sec:pay}), (3) pay another customer using a peer-to-peer +transfer (see Sections~\ref{sec:push} and~\ref{sec:pull}), or (4) the coins +will expire if the wallet was lost (including offline for a long time or +uninstalled). Finally, if a wallet remains (occasionally) online but a user +does simply not spend the coins will (5) diminish in value from the change +fees (see Section~\ref{sec:fees:coin}) that apply to prevent the coins from +expiring outright. + +For customers, we will categorically limit of digital cash withdrawn per month +to less than CHF 5'000 per month and less than CHF 15'000 per year, thus +ensuring that consumers remain below the thresholds where most regulatory +processes become applicable. Payments between users will be limited +to receiving less than CHF 2'500 per month and less than CHF 15'000 per year. +We will ensure that customers are Swiss +(see Section~\ref{sec:proc:domestic}) by requiring them to have a Swiss bank +account and/or a Swiss phone number (+41-prefix). +%Furthermore, the wallet will +%impose an upper limit of CHF 5000 on its balance at any point in time. + +For {\bf merchants}, the Taler equivalent of ``opening'' an account and thus +establishing an ongoing business relationship is for a business to receive +payments (see Section~\ref{sec:pay}) exceeding CHF 5'000/month or CHF +15'000/year. We will consider the account ``open'' (and require up-to-date KYB +information and check sanction lists) as long as the business has made any +transactions within the last 24 months. + +As we will only transfer money into the existing bank accounts of the +merchants to compensate them for sales made using the Taler payment system, we +do not need to check the origin of funds for those merchants as they will only +receive funds from us.\footnote{Should businesses want to use Taler for +expenditures, they will need to withdraw digital coins from their bank account +just like customers, and the limits for customers will continue to apply.} + +For individual {\bf transactions}, we will impose a limit of CHF +1'000/transaction (even though our reading of the regulations would permit +individual transactions up to CHF 15'000). + +The following sections describe the respective processes for each of these +interactions. + +\include{int-withdraw} +\include{int-deposit} +\include{int-pay} +\include{int-refund} +\include{int-push} +\include{int-pull} +\include{int-shutdown} + + +\chapter{Regulatory Triggers} \label{chap:triggers} + +In this chapter we show decision diagrams for regulatory processes of the +various core operations of the GNU Taler payment system. In each case, the +{\bf start} state refers to one of the interactions described in the previous +chapter. The payment system will then use the process to arrive at an {\bf + allow} decision which permits the transaction to go through, or at a {\bf + deny} decision which ensures that the funds are not moved. + +The specific {\em decisions} (in green) depend on the risk profile and the +regulatory environment. The tables in each section list the specific values +that are to be configured. + +There are five types if interactions that can trigger regulatory processes: + +\begin{description} + \item[withdraw] a customer withdraws digital cash from their {\bf bank account} + \item[deposit] a customer or merchant's {\bf bank account} is + designated to receive a payment due someone paying with or + depositing digital cash + \item[push] a {\bf wallet} accepts a payment from another wallet + \item[pull] a {\bf wallet} requests a payment from another wallet +% \item[balance] a withdraw or P2P payment causes the balance of a {\bf wallet} to exceed a given threshold +\end{description} + +We note in bold the {\bf anchor} for the regulator process. The anchor is used +to link the interaction to an identity. Once an identity has been established +for a particular anchor, that link is considered established for all types of +activities involving that anchor. A wallet is uniquely identified in the +system by its unique cryptographic key. A bank account is uniquely identified +in the system by its (RFC 8905) bank routing data (usually including BIC, IBAN +and account owner name). + +The KYC and AML processes themselves are described in +Chapter~\ref{chap:regproc}. + +\include{kyc-withdraw} +\include{kyc-deposit} +\include{kyc-push} +\include{kyc-pull} +%\include{kyc-balance} + +\chapter{Regulatory Processes} \label{chap:regproc} + +This chapter describes the interactions between the customer, exchange and +organizations or staff assisting with regulatory processes designed to ensure +that customers are residents in the area of operation of the payment service +provider, are properly identified, and do not engage in money laundering. + +The three main regulatory processes are: + +\begin{description} +\item[domestic check] This process establishes that a user is generally + eligible to use the payment system. The process checks that the user has an + eligible address, but stops short of establishing the user's identity. +\item[kyc] This process establishes a user's legal identity, possibly + using external providers to review documents and check against blacklists. +\item[aml] The AML process reviews suspicious payment activities for + money laundering. Here AML staff reviews all collected information. +\end{description} + +\include{proc-domestic} +\include{proc-kyc} +\include{proc-kyb} +\include{proc-aml} + +\chapter{Fees} \label{chap:fees} + +The business model for operating a Taler exchange is to charge transaction +fees. Fees are charged on certain operations by the exchange. There are two +types of fees, {\bf wire fees} and {\bf coin fees}. This chapter describes +the fee structure. + +Fixed, amount-independent {\bf wire fees} are charged on wire transfers using +the core banking system. Details on wire fees are described in +Section~\ref{sec:fees:wire}. + +Coin fees are more complex, as they do not exactly follow neither the usual +percentage of volume model of other payment systems. Instead, coin fees are +applied per coin, resulting in a {\em logarithmic} fee structure. As a +result, the effective fee {\em percentage} for tiny transactions is high (for +example 50\% for transactions of 0.0025 CHF) while the effective fee +percentage for large transactions is nominal (for example $\approx$ 0.05\% for +transactions of $\approx$ 40 CHF). Details on coin fees are described in +Section~\ref{sec:fees:coin}. + +Fees are configurable (and that fee types beyond those described here are +supported by the software). Thus, the specific fees may be adjusted in the +future based on business decisions. However, changes to the fees are never +retroactively applied to coins already in circulation. Wire fees that have +been publicly announced for a particular time period also cannot be changed. +Finally, any change to the terms of service must also be explicitly accepted +by the users before they withdraw additional funds. + + +\include{fees-wire} +\include{fees-coins} +%\include{fees-other} + + +\end{document} diff --git a/doc/flows/proc-aml.tex b/doc/flows/proc-aml.tex new file mode 100644 index 000000000..04700faf8 --- /dev/null +++ b/doc/flows/proc-aml.tex @@ -0,0 +1,47 @@ +\section{AML process} + +\begin{figure}[h!] + \begin{sequencediagram} + \newinst{wallet}{\shortstack{Customer \\ + \\ \begin{tikzpicture} + \node [fill=gray!20,draw=black,thick,align=center] { Unique \\ Action}; + \end{tikzpicture} + }} + \newinst[2]{exchange}{\shortstack{Taler (exchange) \\ + \\ \begin{tikzpicture}[shape aspect=.5] + \tikzset{every node/.style={cylinder,shape border rotate=90, draw,fill=gray!25}} + \node at (1.5,0) {\shortstack{{{\tiny Database}}}}; + \end{tikzpicture} + }} + \newinst[2]{staff}{\shortstack{AML staff \\ + \\ \begin{tikzpicture} + \node [fill=gray!20,draw=black,thick,align=center] { Access \\ Token}; + \end{tikzpicture} + }} + \postlevel + \mess[0]{wallet}{{Initial action}}{exchange} + \begin{callself}{exchange}{Establish AML requirement}{} + \end{callself} + \begin{callself}{exchange}{Queue AML task}{} + \end{callself} + \mess[0]{exchange}{Wait for AML}{wallet} + \mess[0]{staff}{Request AML work}{exchange} + \mess[0]{exchange}{{Open AML task(s)}}{staff} + \mess[0]{staff}{Request details}{exchange} + \mess[0]{exchange}{KYC/AML data}{staff} + \begin{callself}{staff}{Review and decide}{} + \end{callself} + \mess[0]{staff}{{Decision documentation}}{exchange} + \mess[0]{exchange}{AML decision}{wallet} + \mess[0]{wallet}{{Retry action}}{exchange} +\end{sequencediagram} + \caption{Deposit interactions between customer, Taler exchange (payment + service provider) and the AML staff. The process can be + triggered by various {\em actions} described in Chapter~\ref{chap:triggers}. + AML staff interactions are cryptographically secured and + decisions and the provided reasoning are archived by the exchange. + AML staff may interact with the customer (out-of-band) + in its decision process. + } + \label{fig:proc:aml} +\end{figure} diff --git a/doc/flows/proc-domestic.tex b/doc/flows/proc-domestic.tex new file mode 100644 index 000000000..f3a1b7b18 --- /dev/null +++ b/doc/flows/proc-domestic.tex @@ -0,0 +1,66 @@ +\section{Domestic wallet check} \label{sec:proc:domestic} + +\begin{figure}[h!] + \begin{sequencediagram} + \newinst{wallet}{\shortstack{Customer wallet \\ + \\ \begin{tikzpicture} + \node [fill=gray!20,draw=black,thick,align=center] { Unique \\ Wallet ID}; + \end{tikzpicture} + }} + \newinst[2]{exchange}{\shortstack{Taler (exchange) \\ + \\ \begin{tikzpicture}[shape aspect=.5] + \tikzset{every node/.style={cylinder,shape border rotate=90, draw,fill=gray!25}} + \node at (1.5,0) {\shortstack{{{\tiny Database}}}}; + \end{tikzpicture} + }} + \newinst[2]{sms}{\shortstack{Address validator}} + + \postlevel + \mess[0]{wallet}{{P2P payment (Wallet ID)}}{exchange} + \begin{callself}{exchange}{New wallet?}{} + \end{callself} + \mess[0]{exchange}{Request address validation}{sms} + \mess[0]{sms}{Validation process ID}{exchange} + \mess[0]{exchange}{Request address validation}{wallet} + \mess[0]{wallet}{Send address}{sms} + \mess[0]{sms}{{Send confirmation code (to address)}}{wallet} + \mess[0]{wallet}{Supply confirmation code}{sms} + \mess[0]{sms}{{Confirmed customer address}}{exchange} + \mess[0]{exchange}{{Confirm completion}}{wallet} + \mess[0]{wallet}{{Retry action}}{exchange} +\end{sequencediagram} + \caption{Deposit interactions between customer, Taler exchange (payment + service provider) and external address validation service. The process can be + triggered by wallet-to-wallet (P2P) payments described in Chapter~\ref{chap:triggers}.} + \label{fig:proc:domestic} +\end{figure} + +Our users have to accept the terms of service which restrict the use of the +service to domestic customers. For interactions with the core banking system, +this simply means that we only accept payments from or to domestic bank +accounts. For P2P payments between wallets, we require that the wallets are +controlled by a domestic entity. We define domestic entities as those that +are able to receive messages at a domestic address. Two types of addresses are +supported: + +\begin{itemize} +\item Control over a domestic {\bf mobile phone number} is established + by sending an SMS message with a confirmation code to the MSIN. +\item Control over a domestic {\bf postal address} is established by + sending a letter with a confirmation code to the address. +\end{itemize} + +Depending on the type of address, a validation has a limited validity period, +as shown in Table~\ref{table:proc:domestic}. When the validity period is +over, a wallet has to re-do the address validation before they can receive any +further funds through the service. + +\begin{table}[h!] + \caption{Restrictions on address validations} + \label{table:proc:domestic} + \begin{tabular}{l|l|r} + {\bf Type} & {\bf Validity period} & {\bf Restricted to} \\ \hline \hline + Mobile phone number & 12 months & {\em +41} \\ + Postal address & 36 months & {\em Switzerland} \\ + \end{tabular} +\end{table} diff --git a/doc/flows/proc-kyb.tex b/doc/flows/proc-kyb.tex new file mode 100644 index 000000000..6c84f414c --- /dev/null +++ b/doc/flows/proc-kyb.tex @@ -0,0 +1,98 @@ +\section{KYB process} \label{sec:proc:kyb} + +\begin{figure}[h!] + \begin{sequencediagram} + \newinst{merchant}{\shortstack{Merchant \\ + \\ \begin{tikzpicture} + \node [fill=gray!20,draw=black,thick,align=center] { Unique \\ Action}; + \end{tikzpicture} + }} + \newinst[2]{exchange}{\shortstack{Taler (exchange) \\ + \\ \begin{tikzpicture}[shape aspect=.5] + \tikzset{every node/.style={cylinder,shape border rotate=90, draw,fill=gray!25}} + \node at (1.5,0) {\shortstack{{{\tiny Database}}}}; + \end{tikzpicture} + }} + \newinst[2]{kyb}{\shortstack{KYB provider \\ + \\ \begin{tikzpicture}[shape aspect=.5] + \tikzset{every node/.style={cylinder,shape border rotate=90, draw,fill=gray!25}} + \node at (1.5,0) {\shortstack{{{\tiny Database}}}}; + \end{tikzpicture} + }} + + \postlevel + \mess[0]{merchant}{{Initial action}}{exchange} + \begin{callself}{exchange}{Establish KYB requirement}{} + \end{callself} + \mess[0]{exchange}{Request new KYB process}{kyb} + \mess[0]{kyb}{{Process identifier (PI)}}{exchange} + \mess[0]{exchange}{{KYB required (PI)}}{merchant} + \mess[0]{merchant}{{KYB start (PI)}}{kyb} + \mess[0]{kyb}{{Request identity documentation}}{merchant} + \mess[0]{merchant}{{Upload identity documentation}}{kyb} + \begin{callself}{kyb}{Validate documentation}{} + \end{callself} + \mess[0]{kyb}{{Share documentation (PI)}}{exchange} + \mess[0]{kyb}{{Confirm completion}}{merchant} + \mess[0]{merchant}{{Retry action}}{exchange} +\end{sequencediagram} + \caption{Deposit interactions between customer, Taler exchange (payment + service provider) and external KYB provider. The process can be + triggered by various {\em actions} described in Chapter~\ref{chap:triggers}.} + \label{fig:proc:kyb} +\end{figure} + +At the beginning of the KYB process, the user needs to specify whether they +are an {\bf individual} (not incorporated) or a {\bf business}.\footnote{In +practice, we expect most owners of bank accounts crossing the KYB threshold to +be businesses, but in principle such a bank account could be owned by an +individual operating a business without a separate legal entity.} This then +determines which types of attributes are collected in the KYB process +(Table~\ref{table:proc:kyb:individual} +vs. Table~\ref{table:proc:kyb:business}). + +\begin{table} + \caption{Information collected for unincorporated individuals} + \label{table:proc:kyb:individual} + \begin{center} + \begin{tabular}{l|c|r} + {\bf Type} & {\bf Required} & {\bf Example} \\ \hline \hline + Surname & yes & Mustermann \\ + First name(s) & yes & Max \\ + Date of birth & yes & 1.1.1980 \\ + Nationality & yes & Swiss \\ + Actual address of domicile & yes & Seestrasse 3, 8008 Zuerich \\ + Phone number & no & +41-123456789 \\ + E-mail & no & me@example.com \\ + Identification document & yes & JPG image \\ + Taxpayer identification & yes & ZPV Nr. 253'123'456 \\ + \end{tabular} + \end{center} +\end{table} + + +\begin{table} + \caption{Information collected for businesses. Information on individals is + collected for owners with more than 25\% ownership and for those with + signature authority for the business.} + \label{table:proc:kyb:business} + \begin{center} + \begin{tabular}{l|c|r} + {\bf Type} & {\bf Required} & {\bf Example} \\ \hline \hline + Company name & yes & Mega AG \\ + Registered office & yes & Seestrasse 4, 8008 Zuerich \\ + Company identification document & yes & PDF file \\ + Power of attorney arrangement & yes & PDF file \\ + Business registration number & yes & \\ + Business registration document & yes & PDF file \\ + Registration authority & yes & \\ \hline + Authorized person name & yes & Max Mustermann \\ + Share/authorization certification & yes & PDF file \\ + Identification document & yes & JPG image \\ + Date of birth & yes & 1.1.1980 \\ + Nationality & yes & Swiss \\ + E-mail & yes & me@example.com \\ + Phone number & no & +41-123456789 \\ + \end{tabular} + \end{center} +\end{table} diff --git a/doc/flows/proc-kyc.tex b/doc/flows/proc-kyc.tex new file mode 100644 index 000000000..87465f44c --- /dev/null +++ b/doc/flows/proc-kyc.tex @@ -0,0 +1,88 @@ +\section{KYC process} + +\begin{figure}[h!] + \begin{sequencediagram} + \newinst{wallet}{\shortstack{Customer \\ + \\ \begin{tikzpicture} + \node [fill=gray!20,draw=black,thick,align=center] { Unique \\ Action}; + \end{tikzpicture} + }} + \newinst[2]{exchange}{\shortstack{Taler (exchange) \\ + \\ \begin{tikzpicture}[shape aspect=.5] + \tikzset{every node/.style={cylinder,shape border rotate=90, draw,fill=gray!25}} + \node at (1.5,0) {\shortstack{{{\tiny Database}}}}; + \end{tikzpicture} + }} + \newinst[2]{kyc}{\shortstack{KYC provider \\ + \\ \begin{tikzpicture}[shape aspect=.5] + \tikzset{every node/.style={cylinder,shape border rotate=90, draw,fill=gray!25}} + \node at (1.5,0) {\shortstack{{{\tiny Database}}}}; + \end{tikzpicture} + }} + + \postlevel + \mess[0]{wallet}{{Initial action}}{exchange} + \begin{callself}{exchange}{Establish KYC requirement}{} + \end{callself} + \mess[0]{exchange}{Request new KYC process}{kyc} + \mess[0]{kyc}{{Process identifier (PI)}}{exchange} + \mess[0]{exchange}{{KYC required (PI)}}{wallet} + \mess[0]{wallet}{{KYC start (PI)}}{kyc} + \mess[0]{kyc}{{Request identity documentation}}{wallet} + \mess[0]{wallet}{{Upload identity documentation}}{kyc} + \begin{callself}{kyc}{Validate documentation}{} + \end{callself} + \mess[0]{kyc}{{Share documentation (PI)}}{exchange} + \mess[0]{kyc}{{Confirm completion}}{wallet} + \mess[0]{wallet}{{Retry action}}{exchange} +\end{sequencediagram} + \caption{Deposit interactions between customer, Taler exchange (payment + service provider) and external KYC provider. The process can be + triggered by various {\em actions} described in Chapter~\ref{chap:triggers}.} + \label{fig:proc:kyc} +\end{figure} + +At the beginning of the KYC process, the user needs to specify whether they +are an {\bf individual} or a {\bf business}.\footnote{ In practice, we expect +most wallet-users to be individuals, but in principle a wallet could be owned +by a business.} This then determines which types of attributes are collected +in the KYC process (Table~\ref{table:proc:kyc:individual} vs. +Table~\ref{table:proc:kyc:business}). + +\begin{table} + \caption{Information collected for individuals} + \label{table:proc:kyc:individual} + \begin{center} + \begin{tabular}{l|c|r} + {\bf Type} & {\bf Required} & {\bf Example} \\ \hline \hline + Surname & yes & Mustermann \\ + First name(s) & yes & Max \\ + Date of birth & yes & 1.1.1980 \\ + Nationality & yes & Swiss \\ + Actual address of domicile & yes & Seestrasse 3, 8008 Zuerich \\ + Phone number & no & +41-123456789 \\ + E-mail & no & me@example.com \\ + Identification document & yes & JPG image \\ + \end{tabular} + \end{center} +\end{table} + +\begin{table} + \caption{Information collected for businesses} + \label{table:proc:kyc:business} + \begin{center} + \begin{tabular}{l|c|r} + {\bf Type} & {\bf Required} & {\bf Example} \\ \hline \hline + Company name & yes & Mega AG \\ + Registered office & yes & Seestrasse 4, 8008 Zuerich \\ + Company identification document & yes & PDF file \\ \hline + Contact person name & yes & Max Mustermann \\ + Phone number & no & +41-123456789 \\ + E-mail & yes & me@example.com \\ + Identification document & yes & JPG image \\ + Date of birth & yes & 1.1.1980 \\ + Nationality & yes & Swiss \\ \hline + Power of attorney arrangement & yes & PDF file \\ + \end{tabular} + \end{center} +\end{table} diff --git a/doc/prebuilt b/doc/prebuilt -Subproject 74d9c44ebc257a3d8b9c2c0a806508bd0cc5269 +Subproject b8d2d2fa2ed2a771880f451725176f256583cb2 diff --git a/doc/system/.gitignore b/doc/system/.gitignore index 3156fa055..368efd05f 100644 --- a/doc/system/.gitignore +++ b/doc/system/.gitignore @@ -1,5 +1,7 @@ thesis.pdf thesis-*.pdf +system.pdf +system-*.pdf thesis.out summary/summary-english.pdf *-converted-to.pdf diff --git a/doc/system/plots/cpu.pdf b/doc/system/plots/cpu.pdf Binary files differnew file mode 100644 index 000000000..6ac08a2b5 --- /dev/null +++ b/doc/system/plots/cpu.pdf diff --git a/doc/system/plots/latencies.pdf b/doc/system/plots/latencies.pdf Binary files differnew file mode 100644 index 000000000..f85609606 --- /dev/null +++ b/doc/system/plots/latencies.pdf diff --git a/doc/system/plots/latency-summary-0.data b/doc/system/plots/latency-summary-0.data new file mode 100644 index 000000000..8ba510704 --- /dev/null +++ b/doc/system/plots/latency-summary-0.data @@ -0,0 +1,7 @@ +http://192.168.42.1:8081/deposit 22.3593 +http://192.168.42.1:8081/keys 1.139 +http://192.168.42.1:8081/reserve/withdraw 22.675 +http://192.168.42.1:8081/refresh/link 7.12287 +http://192.168.42.1:8081/refresh/reveal 63.6377 +http://192.168.42.1:8081/refresh/melt 20.7065 +http://192.168.42.2:8081/admin/add/incoming 0.501 diff --git a/doc/system/plots/latency-summary-100.data b/doc/system/plots/latency-summary-100.data new file mode 100644 index 000000000..4b282e66a --- /dev/null +++ b/doc/system/plots/latency-summary-100.data @@ -0,0 +1,7 @@ +http://192.168.42.1:8081/deposit 223.217 +http://192.168.42.1:8081/keys 201.251 +http://192.168.42.1:8081/reserve/withdraw 222.458 +http://192.168.42.1:8081/refresh/link 205.331 +http://192.168.42.1:8081/refresh/reveal 466.303 +http://192.168.42.1:8081/refresh/melt 223.9 +http://192.168.42.2:8081/admin/add/incoming 0.485 diff --git a/doc/system/plots/req-received.data b/doc/system/plots/req-received.data new file mode 100644 index 000000000..d26da40f1 --- /dev/null +++ b/doc/system/plots/req-received.data @@ -0,0 +1,7 @@ +http://192.168.42.1:8081/deposit 0.339055 +http://192.168.42.1:8081/keys 3.748 +http://192.168.42.1:8081/reserve/withdraw 0.722583 +http://192.168.42.1:8081/refresh/link 3.15716 +http://192.168.42.1:8081/refresh/reveal 2.10851 +http://192.168.42.1:8081/refresh/melt 0.35252 +http://192.168.42.2:8081/admin/add/incoming 0.177 diff --git a/doc/system/plots/req-sent.data b/doc/system/plots/req-sent.data new file mode 100644 index 000000000..40f524d30 --- /dev/null +++ b/doc/system/plots/req-sent.data @@ -0,0 +1,7 @@ +http://192.168.42.1:8081/deposit 1.36432 +http://192.168.42.1:8081/keys 0.145 +http://192.168.42.1:8081/reserve/withdraw 0.711581 +http://192.168.42.1:8081/refresh/link 0.215 +http://192.168.42.1:8081/refresh/reveal 1.42 +http://192.168.42.1:8081/refresh/melt 1.06365 +http://192.168.42.2:8081/admin/add/incoming 0.386 diff --git a/doc/system/plots/speed.pdf b/doc/system/plots/speed.pdf Binary files differnew file mode 100644 index 000000000..b809c1d21 --- /dev/null +++ b/doc/system/plots/speed.pdf diff --git a/doc/system/system.tex b/doc/system/system.tex index b5be63564..16782212a 100644 --- a/doc/system/system.tex +++ b/doc/system/system.tex @@ -66,7 +66,7 @@ \usepackage{pdfpages} -\author{Florian Dold \and the GNU Taler Developers} +\author{Florian Dold \and The GNU Taler Developers} \title{The GNU Taler System} \begin{document} @@ -79,6 +79,7 @@ \let\thefootnote=\oldthefootnote% } +\maketitle \frontmatter \include{abstract} \include{acknowledgements} diff --git a/doc/system/taler-arch-full.pdf b/doc/system/taler-arch-full.pdf Binary files differnew file mode 100644 index 000000000..9c3d8f2c4 --- /dev/null +++ b/doc/system/taler-arch-full.pdf diff --git a/doc/system/taler/implementation.tex b/doc/system/taler/implementation.tex index 9d7cb9a9e..e7d8b9dc7 100644 --- a/doc/system/taler/implementation.tex +++ b/doc/system/taler/implementation.tex @@ -1179,7 +1179,7 @@ Section~\ref{sec:compromised-signing-key-detection}. In the future, we plan for the auditor to expose additional endpoints where wallets and merchant backends can submit (cryptographic) proofs of -missbehavior from an exchange. The goal would be to automatically verify the +misbehavior from an exchange. The goal would be to automatically verify the proofs, take corrective action by including the information in the audit report and possibly even compensating the victim. |
