From f4e9cee189f080a8e28d2e30a0ab00c0b3ff13c9 Mon Sep 17 00:00:00 2001 From: Raul Metsma Date: Thu, 26 Feb 2026 13:36:43 +0200 Subject: [PATCH] Update documentation IB-8847 Signed-off-by: Raul Metsma --- etc/Doxyfile.in | 239 +++++++++++++++++++++++++++++---------- src/Conf.cpp | 23 +++- src/Container.cpp | 12 +- src/Exception.cpp | 9 +- src/Signature.cpp | 64 ++++++++++- src/XmlConf.cpp | 105 ++++++++++++++++- src/crypto/Signer.cpp | 5 + src/crypto/WinSigner.cpp | 1 + src/crypto/X509Cert.cpp | 175 ++++++++++++++++++++-------- 9 files changed, 509 insertions(+), 124 deletions(-) diff --git a/etc/Doxyfile.in b/etc/Doxyfile.in index 73c5a949d..c68de5942 100644 --- a/etc/Doxyfile.in +++ b/etc/Doxyfile.in @@ -1,4 +1,4 @@ -# Doxyfile 1.12.0 +# Doxyfile 1.16.1 # This file describes the settings to be used by the documentation system # Doxygen (www.doxygen.org) for a project. @@ -51,7 +51,7 @@ PROJECT_NAME = libdigidocpp PROJECT_NUMBER = @PROJECT_VERSION@ # 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 +# for a project that appears at the top of each page and should give viewers a # quick idea about the purpose of the project. Keep the description short. PROJECT_BRIEF = @@ -80,7 +80,7 @@ OUTPUT_DIRECTORY = @PROJECT_BINARY_DIR@/doc/ # 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 +# putting all generated files in the same directory would otherwise cause # performance problems for the file system. Adapt CREATE_SUBDIRS_LEVEL to # control the number of sub-directories. # The default value is: NO. @@ -202,17 +202,17 @@ STRIP_FROM_PATH = STRIP_FROM_INC_PATH = # 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 +# less readable) file names. This can be useful if your file system 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.) +# first line (until the first dot, question mark or exclamation mark) 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 = NO @@ -228,9 +228,10 @@ JAVADOC_AUTOBRIEF = 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.) +# line (until the first dot, question mark or exclamation mark) 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 @@ -360,6 +361,20 @@ EXTENSION_MAPPING = MARKDOWN_SUPPORT = YES +# If the MARKDOWN_STRICT tag is enabled then Doxygen treats text in comments as +# Markdown formatted also in cases where Doxygen's native markup format +# conflicts with that of Markdown. This is only relevant in cases where +# backticks are used. Doxygen's native markup style allows a single quote to end +# a text fragment started with a backtick and then treat it as a piece of quoted +# text, whereas in Markdown such text fragment is treated as verbatim and only +# ends when a second matching backtick is found. Also, Doxygen's native markup +# format requires double quotes to be escaped when they appear in a backtick +# section, whereas this is not needed for Markdown. +# The default value is: YES. +# This tag requires that the tag MARKDOWN_SUPPORT is set to YES. + +MARKDOWN_STRICT = 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. @@ -383,11 +398,20 @@ MARKDOWN_ID_STYLE = DOXYGEN # 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. +# globally by setting AUTOLINK_SUPPORT to NO. Words listed in the +# AUTOLINK_IGNORE_WORDS tag are excluded from automatic linking. # The default value is: YES. AUTOLINK_SUPPORT = YES +# This tag specifies a list of words that, when matching the start of a word in +# the documentation, will suppress auto links generation, if it is enabled via +# AUTOLINK_SUPPORT. This list does not affect links explicitly created using # +# or the \link or \ref commands. +# This tag requires that the tag AUTOLINK_SUPPORT is set to YES. + +AUTOLINK_IGNORE_WORDS = + # 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 @@ -500,7 +524,7 @@ LOOKUP_CACHE_SIZE = 0 # 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. +# Minimum value: 0, maximum value: 512, default value: 1. NUM_PROC_THREADS = 1 @@ -599,6 +623,14 @@ HIDE_UNDOC_MEMBERS = NO HIDE_UNDOC_CLASSES = NO +# If the HIDE_UNDOC_NAMESPACES tag is set to YES, Doxygen will hide all +# undocumented namespaces that are normally visible in the namespace hierarchy. +# If set to NO, these namespaces will be included in the various overviews. This +# option has no effect if EXTRACT_ALL is enabled. +# The default value is: YES. + +HIDE_UNDOC_NAMESPACES = YES + # 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. @@ -761,6 +793,27 @@ GENERATE_BUGLIST = YES GENERATE_DEPRECATEDLIST= YES +# The GENERATE_REQUIREMENTS tag can be used to enable (YES) or disable (NO) the +# requirements page. When enabled, this page is automatically created when at +# least one comment block with a \requirement command appears in the input. +# The default value is: YES. + +GENERATE_REQUIREMENTS = YES + +# The REQ_TRACEABILITY_INFO tag controls if traceability information is shown on +# the requirements page (only relevant when using \requirement comment blocks). +# The setting NO will disable the traceablility information altogether. The +# setting UNSATISFIED_ONLY will show a list of requirements that are missing a +# satisfies relation (through the command: \satisfies). Similarly the setting +# UNVERIFIED_ONLY will show a list of requirements that are missing a verifies +# relation (through the command: \verifies). Setting the tag to YES (the +# default) will show both lists if applicable. +# Possible values are: YES, NO, UNSATISFIED_ONLY and UNVERIFIED_ONLY. +# The default value is: YES. +# This tag requires that the tag GENERATE_REQUIREMENTS is set to YES. + +REQ_TRACEABILITY_INFO = YES + # The ENABLED_SECTIONS tag can be used to enable conditional documentation # sections, marked by \if ... \endif and \cond # ... \endcond blocks. @@ -909,6 +962,14 @@ WARN_NO_PARAMDOC = NO WARN_IF_UNDOC_ENUM_VAL = NO +# If WARN_LAYOUT_FILE option is set to YES, Doxygen will warn about issues found +# while parsing the user defined layout file, such as missing or wrong elements. +# See also LAYOUT_FILE for details. If set to NO, problems with the layout file +# will be suppressed. +# The default value is: YES. + +WARN_LAYOUT_FILE = YES + # 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 @@ -979,10 +1040,10 @@ INPUT = @PROJECT_SOURCE_DIR@/src \ INPUT_ENCODING = UTF-8 # This tag can be used to specify the character encoding of the source files -# that Doxygen parses The INPUT_FILE_ENCODING tag can be used to specify +# that Doxygen parses. The INPUT_FILE_ENCODING tag can be used to specify # character encoding on a per file pattern basis. Doxygen will compare the file # name with each pattern and apply the encoding instead of the default -# INPUT_ENCODING) if there is a match. The character encodings are a list of the +# INPUT_ENCODING if there is a match. The character encodings are a list of the # form: pattern=encoding (like *.php=ISO-8859-1). # See also: INPUT_ENCODING for further information on supported encodings. @@ -1001,9 +1062,9 @@ INPUT_FILE_ENCODING = # # If left blank the following patterns are tested:*.c, *.cc, *.cxx, *.cxxm, # *.cpp, *.cppm, *.ccm, *.c++, *.c++m, *.java, *.ii, *.ixx, *.ipp, *.i++, *.inl, -# *.idl, *.ddl, *.odl, *.h, *.hh, *.hxx, *.hpp, *.h++, *.ixx, *.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, +# *.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 \ @@ -1060,7 +1121,8 @@ EXCLUDE_PATTERNS = */crypto/Connect.* \ */SiVa*.* \ */PDF.* \ */libdigidocpp.i.h \ - */XMLDocument.h + */XMLDocument.h \ + */*_p.h # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names # (namespaces, classes, functions, etc.) that should be excluded from the @@ -1070,7 +1132,9 @@ EXCLUDE_PATTERNS = */crypto/Connect.* \ EXCLUDE_SYMBOLS = digidoc::*Private \ *m_* \ - *tslcert* + *tslcert* \ + MAX_MEM_FILE \ + initXmlSecCallback # 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 @@ -1160,6 +1224,15 @@ FILTER_SOURCE_PATTERNS = USE_MDFILE_AS_MAINPAGE = +# If the IMPLICIT_DIR_DOCS tag is set to YES, any README.md file found in sub- +# directories of the project's root, is used as the documentation for that sub- +# directory, except when the README.md starts with a \dir, \page or \mainpage +# command. If set to NO, the README.md file needs to start with an explicit \dir +# command in order to be used as directory documentation. +# The default value is: YES. + +IMPLICIT_DIR_DOCS = YES + # The Fortran standard specifies that for fixed formatted Fortran code all # characters from position 72 are to be considered as comment. A common # extension is to allow longer lines before the automatic comment starts. The @@ -1528,9 +1601,9 @@ DOCSET_PUBLISHER_NAME = Publisher # 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: +# 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). # @@ -1704,20 +1777,29 @@ DISABLE_INDEX = NO # 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. +# Since the tree basically has more details information than the tab index, you +# could consider setting DISABLE_INDEX to YES when enabling this option. +# The default value is: YES. # This tag requires that the tag GENERATE_HTML is set to YES. GENERATE_TREEVIEW = YES -# 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. +# When GENERATE_TREEVIEW is set to YES, the PAGE_OUTLINE_PANEL option determines +# if an additional navigation panel is shown at the right hand side of the +# screen, displaying an outline of the contents of the main page, similar to +# e.g. https://developer.android.com/reference If GENERATE_TREEVIEW is set to +# NO, this option has no effect. +# The default value is: YES. +# This tag requires that the tag GENERATE_HTML is set to YES. + +PAGE_OUTLINE_PANEL = YES + +# When GENERATE_TREEVIEW is set to YES, 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 e.g. https://docs.readthedocs.io with more room for +# contents, but less room for the project logo, title, and description. If +# GENERATE_TREEVIEW 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. @@ -1802,7 +1884,7 @@ USE_MATHJAX = NO # 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. +# Possible values are: MathJax_2, MathJax_3 and MathJax_4. # The default value is: MathJax_2. # This tag requires that the tag USE_MATHJAX is set to YES. @@ -1811,9 +1893,10 @@ 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 +# https://docs.mathjax.org/en/v2.7/output.html), MathJax version 3 (see: +# https://docs.mathjax.org/en/v3.2/output/index.html) and MathJax version 4 # (see: -# http://docs.mathjax.org/en/latest/web/components/output.html). +# https://docs.mathjax.org/en/v4.0/output/index.htm). # 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 @@ -1826,36 +1909,50 @@ MATHJAX_VERSION = MathJax_2 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: +# output directory using the MATHJAX_RELPATH option. For Mathjax version 2 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.s For Mathjax versions 3 +# and 4 the destination directory should contain the tex-.js script +# (where is either chtml or svg). 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 +# - in case of MathJax version 4: https://cdn.jsdelivr.net/npm/mathjax@4 # This tag requires that the tag USE_MATHJAX is set to YES. MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest # 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): +# for MathJax version 2 (see https://docs.mathjax.org/en/v2.7/tex.html): # MATHJAX_EXTENSIONS = TeX/AMSmath TeX/AMSsymbols # For example for MathJax version 3 (see -# http://docs.mathjax.org/en/latest/input/tex/extensions/index.html): +# https://docs.mathjax.org/en/v3.2/input/tex/extensions/): # MATHJAX_EXTENSIONS = ams +# For example for MathJax version 4 (see +# https://docs.mathjax.org/en/v4.0/input/tex/extensions/): +# MATHJAX_EXTENSIONS = units +# Note that for Mathjax version 4 quite a few extensions are already +# automatically loaded. To disable a package in Mathjax version 4 one can use +# the package name prepended with a minus sign (- like MATHJAX_EXTENSIONS += +# -textmacros) # 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. +# of code that will be used on startup of the MathJax code. See the Mathjax site +# for more details: +# - MathJax version 2 (see: +# https://docs.mathjax.org/en/v2.7/) +# - MathJax version 3 (see: +# https://docs.mathjax.org/en/v3.2/) +# - MathJax version 4 (see: +# https://docs.mathjax.org/en/v4.0/) For an example see the documentation. # This tag requires that the tag USE_MATHJAX is set to YES. MATHJAX_CODEFILE = @@ -2118,7 +2215,7 @@ 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. +# The default value is: plainnat. # This tag requires that the tag GENERATE_LATEX is set to YES. LATEX_BIB_STYLE = plain @@ -2516,7 +2613,7 @@ HAVE_DOT = NO # 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. +# Minimum value: 0, maximum value: 512, default value: 0. # This tag requires that the tag HAVE_DOT is set to YES. DOT_NUM_THREADS = 0 @@ -2618,6 +2715,15 @@ UML_LOOK = NO UML_LIMIT_NUM_FIELDS = 10 +# If the UML_LOOK tag is enabled, field labels are shown along the edge between +# two class nodes. If there are many fields and many nodes the graph may become +# too cluttered. The UML_MAX_EDGE_LABELS threshold limits the number of items to +# make the size more manageable. Set this to 0 for no limit. +# Minimum value: 0, maximum value: 100, default value: 10. +# This tag requires that the tag UML_LOOK is set to YES. + +UML_MAX_EDGE_LABELS = 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 @@ -2725,24 +2831,29 @@ DIR_GRAPH_MAX_DEPTH = 1 # generated by dot. For an explanation of the image formats see the section # output formats in the documentation of the dot tool (Graphviz (see: # https://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). +# +# Note the formats svg:cairo and svg:cairo:cairo cannot be used in combination +# with INTERACTIVE_SVG (the INTERACTIVE_SVG will be set to NO). # Possible values are: png, jpg, gif, svg, png:gd, png:gd:gd, png:cairo, -# png:cairo:gd, png:cairo:cairo, png:cairo:gdiplus, png:gdiplus and -# png:gdiplus:gdiplus. +# png:cairo:gd, png:cairo:cairo, png:cairo:gdiplus, png:gdiplus, +# png:gdiplus:gdiplus, svg:cairo, svg:cairo:cairo, svg:svg, svg:svg:core, +# gif:cairo, gif:cairo:gd, gif:cairo:gdiplus, gif:gdiplus, gif:gdiplus:gdiplus, +# gif:gd, gif:gd:gd, jpg:cairo, jpg:cairo:gd, jpg:cairo:gdiplus, jpg:gd, +# jpg:gd:gd, jpg:gdiplus and jpg:gdiplus:gdiplus. # The default value is: png. # This tag requires that the tag HAVE_DOT is set to YES. DOT_IMAGE_FORMAT = png -# 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. +# If DOT_IMAGE_FORMAT is set to svg or svg:svg or svg:svg:core, 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. +# +# Note This option will be automatically disabled when DOT_IMAGE_FORMAT is set +# to svg:cairo or svg:cairo:cairo. # The default value is: NO. # This tag requires that the tag HAVE_DOT is set to YES. @@ -2792,6 +2903,12 @@ PLANTUML_CFG_FILE = PLANTUML_INCLUDE_PATH = +# The PLANTUMLFILE_DIRS tag can be used to specify one or more directories that +# contain PlantUml files that are included in the documentation (see the +# \plantumlfile command). + +PLANTUMLFILE_DIRS = + # 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 diff --git a/src/Conf.cpp b/src/Conf.cpp index 9401cf4df..594249e7b 100644 --- a/src/Conf.cpp +++ b/src/Conf.cpp @@ -42,7 +42,7 @@ Conf* Conf::INSTANCE = nullptr; * @class digidoc::Conf * @brief Configuration class which can reimplemented and virtual methods overloaded. * - * @deprecated Use digidoc::ConfV5 + * @deprecated Since 3.12.2, use digidoc::ConfV5 * @see @ref parameters */ /** @@ -68,7 +68,7 @@ void Conf::init(Conf *conf) /** * Returns libdigidoc library configuration file's (digidoc.ini) file location - * @deprecated Unused + * @deprecated Since 3.12.0, Unused */ string Conf::libdigidocConf() const { return {}; } @@ -118,7 +118,7 @@ string Conf::ocsp(const string &/*issuer*/) const /** * Gets Certificate store location. - * @deprecated Unused + * @deprecated Since 3.10.0, Unused */ string Conf::certsPath() const { return {}; } @@ -146,17 +146,20 @@ string Conf::proxyPass() const { return {}; } * Gets PKCS12 certificate file location. * * Used for signing OCSP request + * @deprecated Since 3.16.0 */ string Conf::PKCS12Cert() const { return {}; } /** * Gets PKCS12 password. + * @deprecated Since 3.16.0 * @see digidoc::Conf::PKCS12Cert */ string Conf::PKCS12Pass() const { return {}; } /** * Gets PKCS12 usage. + * @deprecated Since 3.16.0 * @see digidoc::Conf::PKCS12Cert */ bool Conf::PKCS12Disable() const { return false; } @@ -235,8 +238,9 @@ string Conf::verifyServiceUri() const { return SIVA_URL; } * Conf contains virtual members and is not leaf class we need create * subclasses to keep binary compatibility * https://techbase.kde.org/Policies/Binary_Compatibility_Issues_With_C++#Adding_new_virtual_functions_to_leaf_classes + * @since 3.12.2 * @see digidoc::Conf - * @deprecated Use digidoc::ConfV5 + * @deprecated Since 3.13.8, use digidoc::ConfV5 * @see @ref parameters */ /** @@ -253,6 +257,7 @@ ConfV2* ConfV2::instance() { return dynamic_cast(Conf::instance()); } /** * Gets verify service Cert + * @since 3.12.2 */ X509Cert ConfV2::verifyServiceCert() const { return X509Cert(); } @@ -265,8 +270,9 @@ X509Cert ConfV2::verifyServiceCert() const { return X509Cert(); } * Conf contains virtual members and is not leaf class we need create * subclasses to keep binary compatibility * https://techbase.kde.org/Policies/Binary_Compatibility_Issues_With_C++#Adding_new_virtual_functions_to_leaf_classes + * @since 3.13.8 * @see digidoc::ConfV2 - * @deprecated Use digidoc::ConfV5 + * @deprecated Since 3.14.7, use digidoc::ConfV5 * @see @ref parameters */ /** @@ -285,6 +291,7 @@ ConfV3* ConfV3::instance() { return dynamic_cast(Conf::instance()); } * Gets OCSP TM Profile OID-s * * OCSP responder certificate policies that are used to identify if OCSP response is given with TM profile + * @since 3.13.8 */ set ConfV3::OCSPTMProfiles() const { return { "1.3.6.1.4.1.10015.4.1.2" }; } @@ -297,8 +304,9 @@ set ConfV3::OCSPTMProfiles() const { return { "1.3.6.1.4.1.10015.4.1.2" * Conf contains virtual members and is not leaf class we need create * subclasses to keep binary compatibility * https://techbase.kde.org/Policies/Binary_Compatibility_Issues_With_C++#Adding_new_virtual_functions_to_leaf_classes + * @since 3.14.7 * @see digidoc::ConfV3 - * @deprecated Use digidoc::ConfV5 + * @deprecated Since 3.15.0, use digidoc::ConfV5 * @see @ref parameters */ /** @@ -315,6 +323,7 @@ ConfV4* ConfV4::instance() { return dynamic_cast(Conf::instance()); } /** * Gets verify service Certs + * @since 3.14.7 */ vector ConfV4::verifyServiceCerts() const { @@ -330,6 +339,7 @@ vector ConfV4::verifyServiceCerts() const * Conf contains virtual members and is not leaf class we need create * subclasses to keep binary compatibility * https://techbase.kde.org/Policies/Binary_Compatibility_Issues_With_C++#Adding_new_virtual_functions_to_leaf_classes + * @since 3.15.0 * @see digidoc::ConfV4 * @see @ref parameters */ @@ -347,6 +357,7 @@ ConfV5* ConfV5::instance() { return dynamic_cast(Conf::instance()); } /** * Gets verify service Certs + * @since 3.15.0 */ vector ConfV5::TSCerts() const { diff --git a/src/Container.cpp b/src/Container.cpp index b3c01df1f..d150d6bae 100644 --- a/src/Container.cpp +++ b/src/Container.cpp @@ -66,6 +66,7 @@ string digidoc::appInfo() { return m_appName; } /** * Returns user-agent info + * @since 3.14.3 */ string digidoc::userAgent() { return m_userAgent; } @@ -94,6 +95,7 @@ void digidoc::initialize(const string &appInfo, initCallBack callBack) * loads configuration settings from default configuration files (see \ref conf) and initializes * certificate store using TSL lists * + * @since 3.14.3 * @param appInfo Application name for container comments * @param userAgent Application info for user agent string * @param callBack Callback when background thread TSL loading is completed @@ -231,7 +233,7 @@ Container::~Container() = default; * Adds the data from an input stream (i.e. the data file contents can be read from internal memory buffer). * * Takes ownership std::istream *is object. - * @deprecated Use digidoc::Container::addDataFile(std::unique_ptr is, const std::string &fileName, const std::string &mediaType) + * @deprecated Since 3.14.4, use digidoc::Container::addDataFile(std::unique_ptr is, const std::string &fileName, const std::string &mediaType) * @param is input stream from where data is read * @param fileName data file name in the container * @param mediaType MIME type of the data file, for example “text/plain” or “application/msword” @@ -248,6 +250,7 @@ void Container::addDataFile(istream *is, const string &fileName, const string &m /** * Adds the data from an input stream (i.e. the data file contents can be read from internal memory buffer). * + * @since 3.14.4 * @param is input stream from where data is read * @param fileName data file name in the container * @param mediaType MIME type of the data file, for example “text/plain” or “application/msword” @@ -284,7 +287,7 @@ void Container::addAdESSignature(const std::vector &signature) /** * Create a new container object and specify the DigiDoc container type * - * @deprecated Use Container::createPtr + * @deprecated Since 3.14.4, use Container::createPtr * This method gives ownership of object to caller */ Container* Container::create(const std::string &path) @@ -294,6 +297,7 @@ Container* Container::create(const std::string &path) /** * Create a new container object and specify the DigiDoc container type + * @since 3.14.4 */ unique_ptr Container::createPtr(const std::string &path) { @@ -334,7 +338,7 @@ unsigned int Container::newSignatureId() const * * This method gives ownership of object to caller * - * @deprecated Use Container::openPtr + * @deprecated Since 3.14.4, use Container::openPtr * @param path * @throws Exception */ @@ -346,6 +350,7 @@ Container* Container::open(const string &path) /** * Opens container from a file * + * @since 3.14.4 * @param path * @throws Exception */ @@ -357,6 +362,7 @@ unique_ptr Container::openPtr(const string &path) /** * Opens container from a file * + * @since 3.17.0 * @param path * @param cb Callback called when additional info is requested (digidoc::ContainerOpenCB::validateOnline) * @throws Exception diff --git a/src/Exception.cpp b/src/Exception.cpp index b4aa948b0..6f29f3152 100644 --- a/src/Exception.cpp +++ b/src/Exception.cpp @@ -44,10 +44,13 @@ std::vector Exception::ignores {}; * General error, no specific code * @var digidoc::Exception::NetworkError * Network error, network connection errors + * @since 3.14.3 * @var digidoc::Exception::HostNotFound * Network error, host not found + * @since 3.14.8 * @var digidoc::Exception::InvalidUrl * Network error, invalid URL + * @since 3.14.8 * * @var digidoc::Exception::CertificateIssuerMissing * Signer's certificate's issuer certificate is missing @@ -57,6 +60,7 @@ std::vector Exception::ignores {}; * Certificate status is unknown in OCSP response * @var digidoc::Exception::OCSPBeforeTimeStamp * OCSP producedAt time is before TimeStamp time + * @since 3.14.2 * @var digidoc::Exception::OCSPResponderMissing * OCSP Responder is missing * @var digidoc::Exception::OCSPCertMissing @@ -67,8 +71,10 @@ std::vector Exception::ignores {}; * OCSP Responder requires the OCSP request to be signed * @var digidoc::Exception::TSForbidden * TSA service responds forbidden + * @since 3.14.4 * @var digidoc::Exception::TSTooManyRequests * TSA service requests have reached limit + * @since 3.13.8 * * @var digidoc::Exception::PINCanceled * PIN cancelled exception @@ -91,10 +97,11 @@ std::vector Exception::ignores {}; * TimeStamp and OCSP time difference is more than 15 minutes * @var digidoc::Exception::MimeTypeWarning * Mime type is not conformant mime-type strings + * @since 3.13.2 * * @var digidoc::Exception::DDocError * DDoc libdigidoc error codes bit masked - * @deprecated Unused + * @deprecated Since 3.14.7, libdigidoc support removed */ /** diff --git a/src/Signature.cpp b/src/Signature.cpp index 7314c00f6..3c1cc8c66 100644 --- a/src/Signature.cpp +++ b/src/Signature.cpp @@ -28,6 +28,17 @@ using namespace digidoc; using namespace std; +/** + * @struct digidoc::TSAInfo + * @brief Time-stamp information. + * @since 4.3.0 + * + * @var digidoc::TSAInfo::cert + * Time-stamp token certificate. + * @var digidoc::TSAInfo::time + * Time-stamp token time. + */ + /** * @class digidoc::Signature * @@ -37,6 +48,7 @@ using namespace std; /** * http://open-eid.github.io/SiVa/siva/appendix/validation_policy/#POLv1 * + * @since 3.13.0 * @see validate(const std::string &policy) const */ const string Signature::POLv1 = "POLv1"; @@ -44,6 +56,7 @@ const string Signature::POLv1 = "POLv1"; /** * http://open-eid.github.io/SiVa/siva/appendix/validation_policy/#POLv2 * + * @since 3.13.0 * @see validate(const std::string &policy) const */ const string Signature::POLv2 = "POLv2"; @@ -76,6 +89,7 @@ string Signature::countryName() const { return {}; } /** * Returns signed signature hash message imprint value (TM - OCSP Nonce, TS - TimeStamp value) + * @since 3.13.7 */ vector Signature::messageImprint() const { return {}; } @@ -91,6 +105,7 @@ string Signature::stateOrProvince() const { return {}; } /** * Returns signature production street address. + * @since 3.13.0 */ string Signature::streetAddress() const { return {}; } @@ -101,6 +116,7 @@ vector Signature::signerRoles() const { return {}; } /** * Return signer's certificate common name + * @since 3.13.0 */ string Signature::signedBy() const { return signingCertificate().subjectName("CN"); } @@ -144,6 +160,7 @@ string Signature::signedBy() const { return signingCertificate().subjectName("CN /** * Validates signature + * @since 3.13.0 * @see POLv1 * @see POLv2 */ @@ -165,6 +182,7 @@ void Signature::validate(const std::string & /*policy*/) const { validate(); } /** * Extends signature to selected profile * + * @deprecated Since 4.1.0, use extendSignatureProfile(Signer *signer) * @param profile Target profile */ void Signature::extendSignatureProfile(const string &profile) { @@ -180,6 +198,7 @@ void Signature::extendSignatureProfile(const string &profile) { /** * Extends signature to selected profile * + * @since 4.1.0 * @param signer Signer parameters */ void Signature::extendSignatureProfile(Signer * /*signer*/) {} @@ -206,7 +225,7 @@ X509Cert Signature::OCSPCertificate() const { return X509Cert(); } /** * Returns signed signature message imprint in OCSP response nonce. - * @deprecated Use messageImprint() + * @deprecated Since 3.13.7, use messageImprint() */ vector Signature::OCSPNonce() const { return messageImprint(); } @@ -222,6 +241,7 @@ string Signature::TimeStampTime() const { return {}; } /** * Returns signature Archive TimeStampToken certificate. + * @deprecated Since 4.3.0, use ArchiveTimeStamps() */ X509Cert Signature::ArchiveTimeStampCertificate() const { @@ -232,6 +252,7 @@ X509Cert Signature::ArchiveTimeStampCertificate() const /** * Returns signature Archive TimeStampToken time. + * @deprecated Since 4.3.0, use ArchiveTimeStamps() */ string Signature::ArchiveTimeStampTime() const { @@ -242,6 +263,7 @@ string Signature::ArchiveTimeStampTime() const /** * Returns signature Archive TimeStampTokens. + * @since 4.3.0 */ vector Signature::ArchiveTimeStamps() const { if(auto cert = ArchiveTimeStampCertificate()) @@ -256,6 +278,34 @@ struct Signature::Validator::Private std::vector warnings; }; +/** + * @class digidoc::Signature::Validator + * @since 3.13.8 + * @brief Signature validation helper class. + */ + +/** + * @enum digidoc::Signature::Validator::Status + * @brief Signature validation status. + * + * @var digidoc::Signature::Validator::Valid + * Signature is valid and uses qualified certificates. + * @var digidoc::Signature::Validator::Warning + * Signature is valid but has some warnings. + * @var digidoc::Signature::Validator::NonQSCD + * Signature is valid but does not use qualified certificates. + * @var digidoc::Signature::Validator::Test + * @deprecated Since 3.14.7, Unused + * @var digidoc::Signature::Validator::Invalid + * Signature is invalid. + * @var digidoc::Signature::Validator::Unknown + * Signature validity is unknown (e.g. missing certificates). + */ + +/** + * Validates signature and initializes Validator object. + * @param s Signature to validate. + */ Signature::Validator::Validator(const Signature *s) : d(new Private) { @@ -281,11 +331,17 @@ Signature::Validator::Validator(const Signature *s) } } +/** + * Releases resources. + */ Signature::Validator::~Validator() { delete d; } +/** + * Returns validation diagnostics. + */ std::string Signature::Validator::diagnostics() const { return d->diagnostics; @@ -320,11 +376,17 @@ void Signature::Validator::parseException(const Exception &e) } } +/** + * Returns validation status. + */ Signature::Validator::Status Signature::Validator::status() const { return d->result; } +/** + * Returns validation warnings. + */ std::vector Signature::Validator::warnings() const { return d->warnings; diff --git a/src/XmlConf.cpp b/src/XmlConf.cpp index c9bb802a7..c3c31fcff 100644 --- a/src/XmlConf.cpp +++ b/src/XmlConf.cpp @@ -261,7 +261,7 @@ void XmlConf::Private::setUserConf(XmlConfParam ¶m, A value) /** * @class digidoc::XmlConf * @brief XML Configuration class - * @deprecated Use digidoc::XmlConfV5 + * @deprecated Since 3.12.2, use digidoc::XmlConfV5 * @see digidoc::Conf */ XmlConf::XmlConf(const string &path, const string &schema) @@ -277,7 +277,8 @@ XmlConf* XmlConf::instance() { return dynamic_cast(Conf::instance()); /** * @class digidoc::XmlConfV2 * @brief Version 2 of XML Configuration class - * @deprecated Use digidoc::XmlConfV5 + * @since 3.12.2 + * @deprecated Since 3.13.8, use digidoc::XmlConfV5 * @see digidoc::ConfV2 */ XmlConfV2::XmlConfV2(const string &path, const string &schema) @@ -293,7 +294,8 @@ XmlConfV2* XmlConfV2::instance() { return dynamic_cast(Conf::instanc /** * @class digidoc::XmlConfV3 * @brief Version 3 of XML Configuration class - * @deprecated Use digidoc::XmlConfV5 + * @since 3.13.8 + * @deprecated Since 3.14.7, use digidoc::XmlConfV5 * @see digidoc::ConfV3 */ XmlConfV3::XmlConfV3(const string &path, const string &schema) @@ -309,7 +311,8 @@ XmlConfV3* XmlConfV3::instance() { return dynamic_cast(Conf::instanc /** * @class digidoc::XmlConfV4 * @brief Version 4 of XML Configuration class - * @deprecated Use digidoc::XmlConfV5 + * @since 3.14.7 + * @deprecated Since 3.15.0, use digidoc::XmlConfV5 * @see digidoc::ConfV4 */ /** @@ -328,6 +331,7 @@ XmlConfV4* XmlConfV4::instance() { return dynamic_cast(Conf::instanc /** * @class digidoc::XmlConfV5 * @brief Version 5 of XML Configuration class + * @since 3.15.0 * @see digidoc::ConfV5 */ /** @@ -405,24 +409,36 @@ string XmlConf::ocsp(const string &issuer) const return i != d->ocsp.end() ? i->second : Conf::ocsp(issuer); } +/** + * @since 3.12.2 + */ string XmlConfV2::ocsp(const string &issuer) const { auto i = d->ocsp.find(issuer); return i != d->ocsp.end() ? i->second : Conf::ocsp(issuer); } +/** + * @since 3.13.8 + */ string XmlConfV3::ocsp(const string &issuer) const { auto i = d->ocsp.find(issuer); return i != d->ocsp.end() ? i->second : Conf::ocsp(issuer); } +/** + * @since 3.14.7 + */ string XmlConfV4::ocsp(const string &issuer) const { auto i = d->ocsp.find(issuer); return i != d->ocsp.end() ? i->second : Conf::ocsp(issuer); } +/** + * @since 3.15.0 + */ string XmlConfV5::ocsp(const string &issuer) const { auto i = d->ocsp.find(issuer); @@ -437,18 +453,22 @@ string XmlConfV5::ocsp(const string &issuer) const /** * @fn void digidoc::XmlConfV2::setTSLOnlineDigest(bool enable) * @copydoc digidoc::XmlConf::setTSLOnlineDigest(bool enable) + * @since 3.12.2 */ /** * @fn void digidoc::XmlConfV3::setTSLOnlineDigest(bool enable) * @copydoc digidoc::XmlConf::setTSLOnlineDigest(bool enable) + * @since 3.13.8 */ /** * @fn void digidoc::XmlConfV4::setTSLOnlineDigest(bool enable) * @copydoc digidoc::XmlConf::setTSLOnlineDigest(bool enable) + * @since 3.14.7 */ /** * @fn void digidoc::XmlConfV5::setTSLOnlineDigest(bool enable) * @copydoc digidoc::XmlConf::setTSLOnlineDigest(bool enable) + * @since 3.15.0 */ SET1(bool, setTSLOnlineDigest, TSLOnlineDigest) @@ -461,18 +481,22 @@ SET1(bool, setTSLOnlineDigest, TSLOnlineDigest) /** * @fn void digidoc::XmlConfV2::setTSLTimeOut(int timeOut) * @copydoc digidoc::XmlConf::setTSLTimeOut(int timeOut) + * @since 3.12.2 */ /** * @fn void digidoc::XmlConfV3::setTSLTimeOut(int timeOut) * @copydoc digidoc::XmlConf::setTSLTimeOut(int timeOut) + * @since 3.13.8 */ /** * @fn void digidoc::XmlConfV4::setTSLTimeOut(int timeOut) * @copydoc digidoc::XmlConf::setTSLTimeOut(int timeOut) + * @since 3.14.7 */ /** * @fn void digidoc::XmlConfV5::setTSLTimeOut(int timeOut) * @copydoc digidoc::XmlConf::setTSLTimeOut(int timeOut) + * @since 3.15.0 */ SET1(int, setTSLTimeOut, TSLTimeOut) @@ -486,18 +510,22 @@ SET1(int, setTSLTimeOut, TSLTimeOut) /** * @fn void digidoc::XmlConfV2::setProxyHost(const std::string &host) * @copydoc digidoc::XmlConf::setProxyHost(const std::string &host) + * @since 3.12.2 */ /** * @fn void digidoc::XmlConfV3::setProxyHost(const std::string &host) * @copydoc digidoc::XmlConf::setProxyHost(const std::string &host) + * @since 3.13.8 */ /** * @fn void digidoc::XmlConfV4::setProxyHost(const std::string &host) * @copydoc digidoc::XmlConf::setProxyHost(const std::string &host) + * @since 3.14.7 */ /** * @fn void digidoc::XmlConfV5::setProxyHost(const std::string &host) * @copydoc digidoc::XmlConf::setProxyHost(const std::string &host) + * @since 3.15.0 */ SET1CONST(string, setProxyHost, proxyHost) @@ -511,18 +539,22 @@ SET1CONST(string, setProxyHost, proxyHost) /** * @fn void digidoc::XmlConfV2::setProxyPort(const std::string &port) * @copydoc digidoc::XmlConf::setProxyPort(const std::string &port) + * @since 3.12.2 */ /** * @fn void digidoc::XmlConfV3::setProxyPort(const std::string &port) * @copydoc digidoc::XmlConf::setProxyPort(const std::string &port) + * @since 3.13.8 */ /** * @fn void digidoc::XmlConfV4::setProxyPort(const std::string &port) * @copydoc digidoc::XmlConf::setProxyPort(const std::string &port) + * @since 3.14.7 */ /** * @fn void digidoc::XmlConfV5::setProxyPort(const std::string &port) * @copydoc digidoc::XmlConf::setProxyPort(const std::string &port) + * @since 3.15.0 */ SET1CONST(string, setProxyPort, proxyPort) @@ -536,18 +568,22 @@ SET1CONST(string, setProxyPort, proxyPort) /** * @fn void digidoc::XmlConfV2::setProxyUser(const std::string &user) * @copydoc digidoc::XmlConf::setProxyUser(const std::string &user) + * @since 3.12.2 */ /** * @fn void digidoc::XmlConfV3::setProxyUser(const std::string &user) * @copydoc digidoc::XmlConf::setProxyUser(const std::string &user) + * @since 3.13.8 */ /** * @fn void digidoc::XmlConfV4::setProxyUser(const std::string &user) * @copydoc digidoc::XmlConf::setProxyUser(const std::string &user) + * @since 3.14.7 */ /** * @fn void digidoc::XmlConfV5::setProxyUser(const std::string &user) * @copydoc digidoc::XmlConf::setProxyUser(const std::string &user) + * @since 3.15.0 */ SET1CONST(string, setProxyUser, proxyUser) @@ -561,18 +597,22 @@ SET1CONST(string, setProxyUser, proxyUser) /** * @fn void digidoc::XmlConfV2::setProxyPass(const std::string &pass) * @copydoc digidoc::XmlConf::setProxyPass(const std::string &pass) + * @since 3.12.2 */ /** * @fn void digidoc::XmlConfV3::setProxyPass(const std::string &pass) * @copydoc digidoc::XmlConf::setProxyPass(const std::string &pass) + * @since 3.13.8 */ /** * @fn void digidoc::XmlConfV4::setProxyPass(const std::string &pass) * @copydoc digidoc::XmlConf::setProxyPass(const std::string &pass) + * @since 3.14.7 */ /** * @fn void digidoc::XmlConfV5::setProxyPass(const std::string &pass) * @copydoc digidoc::XmlConf::setProxyPass(const std::string &pass) + * @since 3.15.0 */ SET1CONST(string, setProxyPass, proxyPass) @@ -581,24 +621,29 @@ SET1CONST(string, setProxyPass, proxyPass) * Sets a PKCS#12 certficate path. Also adds or replaces PKCS#12 certificate path in the user configuration file. * By default the PKCS#12 certificate file should be located at default path, given by getUserConfDir() function. * + * @deprecated Since 3.16.0 * @param cert PKCS#12 certificate location path. * @throws Exception exception is thrown if saving a PKCS#12 certificate path into a user configuration file fails. */ /** * @fn void digidoc::XmlConfV2::setPKCS12Cert(const std::string &cert) * @copydoc digidoc::XmlConf::setPKCS12Cert(const std::string &cert) + * @since 3.12.2 */ /** * @fn void digidoc::XmlConfV3::setPKCS12Cert(const std::string &cert) * @copydoc digidoc::XmlConf::setPKCS12Cert(const std::string &cert) + * @since 3.13.8 */ /** * @fn void digidoc::XmlConfV4::setPKCS12Cert(const std::string &cert) * @copydoc digidoc::XmlConf::setPKCS12Cert(const std::string &cert) + * @since 3.14.7 */ /** * @fn void digidoc::XmlConfV5::setPKCS12Cert(const std::string &cert) * @copydoc digidoc::XmlConf::setPKCS12Cert(const std::string &cert) + * @since 3.15.0 */ SET1CONSTEX(string, setPKCS12Cert, (void)value) @@ -606,24 +651,29 @@ SET1CONSTEX(string, setPKCS12Cert, (void)value) * @fn void digidoc::XmlConf::setPKCS12Pass(const std::string &pass) * Sets a PKCS#12 certificate password. Also adds or replaces PKCS#12 certificate password in the user configuration file. * + * @deprecated Since 3.16.0 * @param pass PKCS#12 certificate password. * @throws Exception exception is thrown if saving a PKCS#12 certificate password into a user configuration file fails. */ /** * @fn void digidoc::XmlConfV2::setPKCS12Pass(const std::string &pass) * @copydoc digidoc::XmlConf::setPKCS12Pass(const std::string &pass) + * @since 3.12.2 */ /** * @fn void digidoc::XmlConfV3::setPKCS12Pass(const std::string &pass) * @copydoc digidoc::XmlConf::setPKCS12Pass(const std::string &pass) + * @since 3.13.8 */ /** * @fn void digidoc::XmlConfV4::setPKCS12Pass(const std::string &pass) * @copydoc digidoc::XmlConf::setPKCS12Pass(const std::string &pass) + * @since 3.14.7 */ /** * @fn void digidoc::XmlConfV5::setPKCS12Pass(const std::string &pass) * @copydoc digidoc::XmlConf::setPKCS12Pass(const std::string &pass) + * @since 3.15.0 */ SET1CONSTEX(string, setPKCS12Pass, (void)value) @@ -637,18 +687,22 @@ SET1CONSTEX(string, setPKCS12Pass, (void)value) /** * @fn void digidoc::XmlConfV2::setTSUrl(const std::string &url) * @copydoc digidoc::XmlConf::setTSUrl(const std::string &url) + * @since 3.12.2 */ /** * @fn void digidoc::XmlConfV3::setTSUrl(const std::string &url) * @copydoc digidoc::XmlConf::setTSUrl(const std::string &url) + * @since 3.13.8 */ /** * @fn void digidoc::XmlConfV4::setTSUrl(const std::string &url) * @copydoc digidoc::XmlConf::setTSUrl(const std::string &url) + * @since 3.14.7 */ /** * @fn void digidoc::XmlConfV5::setTSUrl(const std::string &url) * @copydoc digidoc::XmlConf::setTSUrl(const std::string &url) + * @since 3.15.0 */ SET1CONST(string, setTSUrl, TSUrl) @@ -662,18 +716,22 @@ SET1CONST(string, setTSUrl, TSUrl) /** * @fn void digidoc::XmlConfV2::setVerifyServiceUri(const std::string &url) * @copydoc digidoc::XmlConf::setVerifyServiceUri(const std::string &url) + * @since 3.12.2 */ /** * @fn void digidoc::XmlConfV3::setVerifyServiceUri(const std::string &url) * @copydoc digidoc::XmlConf::setVerifyServiceUri(const std::string &url) + * @since 3.13.8 */ /** * @fn void digidoc::XmlConfV4::setVerifyServiceUri(const std::string &url) * @copydoc digidoc::XmlConf::setVerifyServiceUri(const std::string &url) + * @since 3.14.7 */ /** * @fn void digidoc::XmlConfV5::setVerifyServiceUri(const std::string &url) * @copydoc digidoc::XmlConf::setVerifyServiceUri(const std::string &url) + * @since 3.15.0 */ SET1CONST(string, setVerifyServiceUri, verifyServiceUri) @@ -681,24 +739,29 @@ SET1CONST(string, setVerifyServiceUri, verifyServiceUri) * @fn void digidoc::XmlConf::setPKCS12Disable(bool disable) * Sets a PKCS#12 certificate usage. Also adds or replaces PKCS#12 certificate usage in the user configuration file. * + * @deprecated Since 3.16.0 * @param disable PKCS#12 certificate usage. * @throws Exception exception is thrown if saving a PKCS#12 certificate usage into a user configuration file fails. */ /** * @fn void digidoc::XmlConfV2::setPKCS12Disable(bool disable) * @copydoc digidoc::XmlConf::setPKCS12Disable(bool disable) + * @since 3.12.2 */ /** * @fn void digidoc::XmlConfV3::setPKCS12Disable(bool disable) * @copydoc digidoc::XmlConf::setPKCS12Disable(bool disable) + * @since 3.13.8 */ /** * @fn void digidoc::XmlConfV4::setPKCS12Disable(bool disable) * @copydoc digidoc::XmlConf::setPKCS12Disable(bool disable) + * @since 3.14.7 */ /** * @fn void digidoc::XmlConfV5::setPKCS12Disable(bool disable) * @copydoc digidoc::XmlConf::setPKCS12Disable(bool disable) + * @since 3.15.0 */ SET1EX([[maybe_unused]] bool, setPKCS12Disable, {}) @@ -711,67 +774,101 @@ SET1EX([[maybe_unused]] bool, setPKCS12Disable, {}) /** * @fn void digidoc::XmlConfV2::setProxyTunnelSSL(bool enable) * @copydoc digidoc::XmlConf::setProxyTunnelSSL(bool enable) + * @since 3.12.2 */ /** * @fn void digidoc::XmlConfV3::setProxyTunnelSSL(bool enable) * @copydoc digidoc::XmlConf::setProxyTunnelSSL(bool enable) + * @since 3.13.8 */ /** * @fn void digidoc::XmlConfV4::setProxyTunnelSSL(bool enable) * @copydoc digidoc::XmlConf::setProxyTunnelSSL(bool enable) + * @since 3.14.7 */ /** * @fn void digidoc::XmlConfV5::setProxyTunnelSSL(bool enable) * @copydoc digidoc::XmlConf::setProxyTunnelSSL(bool enable) + * @since 3.15.0 */ SET1(bool, setProxyTunnelSSL, proxyTunnelSSL) +/** + * @since 3.12.2 + */ X509Cert XmlConfV2::verifyServiceCert() const { return ConfV2::verifyServiceCert(); } +/** + * @since 3.13.8 + */ X509Cert XmlConfV3::verifyServiceCert() const { return ConfV3::verifyServiceCert(); } +/** + * @since 3.14.7 + */ X509Cert XmlConfV4::verifyServiceCert() const { return ConfV4::verifyServiceCert(); } +/** + * @since 3.15.0 + */ X509Cert XmlConfV5::verifyServiceCert() const { return ConfV5::verifyServiceCert(); } +/** + * @since 3.13.8 + */ set XmlConfV3::OCSPTMProfiles() const { return d->ocspTMProfiles.empty() ? ConfV3::OCSPTMProfiles() : d->ocspTMProfiles; } +/** + * @since 3.14.7 + */ set XmlConfV4::OCSPTMProfiles() const { return d->ocspTMProfiles.empty() ? ConfV3::OCSPTMProfiles() : d->ocspTMProfiles; } +/** + * @since 3.15.0 + */ set XmlConfV5::OCSPTMProfiles() const { return d->ocspTMProfiles.empty() ? ConfV3::OCSPTMProfiles() : d->ocspTMProfiles; } +/** + * @since 3.14.7 + */ vector XmlConfV4::verifyServiceCerts() const { return ConfV4::verifyServiceCerts(); } +/** + * @since 3.15.0 + */ vector XmlConfV5::verifyServiceCerts() const { return ConfV5::verifyServiceCerts(); } +/** + * @since 3.15.0 + */ vector XmlConfV5::TSCerts() const { return ConfV5::TSCerts(); diff --git a/src/crypto/Signer.cpp b/src/crypto/Signer.cpp index b36a0e4c5..ea40f8f7c 100644 --- a/src/crypto/Signer.cpp +++ b/src/crypto/Signer.cpp @@ -85,6 +85,7 @@ void Signer::setSignatureProductionPlace(const string &city, /** * Sets signature production place according XAdES EN standard. Note that setting the signature production place is optional. + * @since 3.13.0 * @param city * @param streetAddress * @param stateOrProvince @@ -105,6 +106,7 @@ void Signer::setSignatureProductionPlaceV2(const string &city, const string &str /** * Sets additional User-Agent info that is sent to TSA or OCSP service + * @since 4.1.0 * @param userAgent */ void Signer::setUserAgent(const string &userAgent) @@ -128,6 +130,7 @@ string Signer::city() const /** * Returns streetAddress from signature production place + * @since 3.13.0 */ string Signer::streetAddress() const { @@ -231,6 +234,7 @@ void Signer::setMethod(const string &method) /** * Toggle XAdES EN profile usage on signing + * @since 3.13.0 */ void Signer::setENProfile(bool enable) { @@ -266,6 +270,7 @@ string Signer::userAgent() const /** * Use XAdES EN profile + * @since 3.13.0 */ bool Signer::usingENProfile() const { diff --git a/src/crypto/WinSigner.cpp b/src/crypto/WinSigner.cpp index a0d7eda0c..64d365515 100644 --- a/src/crypto/WinSigner.cpp +++ b/src/crypto/WinSigner.cpp @@ -233,6 +233,7 @@ void WinSigner::setSelectFirst(bool first) /** * Sets property select certificate with specified thumbprint + * @since 3.13.9 * @see WinSigner::WinSigner */ void WinSigner::setThumbprint(const vector &thumbprint) diff --git a/src/crypto/X509Cert.cpp b/src/crypto/X509Cert.cpp index 23c8b6290..f8c47b45d 100644 --- a/src/crypto/X509Cert.cpp +++ b/src/crypto/X509Cert.cpp @@ -82,6 +82,23 @@ DEFINE_STACK_OF(QCStatement) #endif DECLARE_ASN1_FUNCTIONS(QCStatements) +/** + * @class digidoc::X509Cert + * + * @brief Wrapper for OpenSSL X509 certificate structure. + */ + +/** + * @enum digidoc::X509Cert::Format + * Binary encoding format + * + * @var digidoc::X509Cert::Der + * ASN.1 syntax + * + * @var digidoc::X509Cert::Pem + * Base64 encoded ASN.1 syntax + */ + /** * @class digidoc::X509Cert * @@ -104,95 +121,121 @@ DECLARE_ASN1_FUNCTIONS(QCStatements) * Key usage bits defined in certificate * * @var digidoc::X509Cert::DigitalSignature + * Key used for verifying digital signatures, other than signatures on certificates and CRLs. * @var digidoc::X509Cert::NonRepudiation - * Used for signing certificate selection in the current library - * + * Key used to provide a non-repudiation service which protects against the signing entity falsely denying some action. + * Used for signing certificate selection in the current library. * @var digidoc::X509Cert::KeyEncipherment + * Key used for enciphering private or shortcut keys. * @var digidoc::X509Cert::DataEncipherment + * Key used for directly enciphering raw user data without the use of an intermediate symmetric cipher. * @var digidoc::X509Cert::KeyAgreement + * Key used for key agreement. * @var digidoc::X509Cert::KeyCertificateSign + * Key used for verifying signatures on public key certificates. * @var digidoc::X509Cert::CRLSign + * Key used for verifying signatures on certificate revocation lists (e.g., CRLs). * @var digidoc::X509Cert::EncipherOnly + * In conjunction with KeyAgreement, key used only for enciphering data while performing key agreement. * @var digidoc::X509Cert::DecipherOnly + * In conjunction with KeyAgreement, key used only for deciphering data while performing key agreement. */ /** * https://www.ietf.org/rfc/rfc3739.txt - id-etsi-qcs-QcCompliance + * @since 3.13.0 */ const string X509Cert::QC_COMPLIANT = "0.4.0.1862.1.1"; /** * https://www.ietf.org/rfc/rfc3739.txt - id-etsi-qcs-QcSSCD + * @since 3.13.0 */ const string X509Cert::QC_SSCD = "0.4.0.1862.1.4"; /** * https://www.ietf.org/rfc/rfc3739.txt - id-etsi-qcs-QcPDS + * @since 3.13.0 */ const string X509Cert::QC_QCP = "0.4.0.1862.1.5"; /** * https://www.ietf.org/rfc/rfc3739.txt - id-etsi-qcs-QcType + * @since 3.13.0 */ const string X509Cert::QC_QCT = "0.4.0.1862.1.6"; /** * https://www.ietf.org/rfc/rfc3739.txt - id-qcs-pkixQCSyntax-v1 + * @since 3.13.0 */ const string X509Cert::QC_SYNTAX1 = "1.3.6.1.5.5.7.11.1"; /** * https://www.ietf.org/rfc/rfc3739.txt - id-qcs-pkixQCSyntax-v2 + * @since 3.13.0 */ const string X509Cert::QC_SYNTAX2 = "1.3.6.1.5.5.7.11.2"; /** * http://www.etsi.org/deliver/etsi_en/319400_319499/31941201/01.01.01_60/en_31941201v010101p.pdf - id-etsi-qcs-semanticsId-natural + * @since 3.13.0 */ const string X509Cert::QCS_NATURAL = "0.4.0.194121.1.1"; /** * http://www.etsi.org/deliver/etsi_en/319400_319499/31941201/01.01.01_60/en_31941201v010101p.pdf - id-etsi-qcs-semanticsId-legal + * @since 3.13.0 */ const string X509Cert::QCS_LEGAL = "0.4.0.194121.1.2"; /** * http://www.etsi.org/deliver/etsi_en/319400_319499/31941205/02.01.01_60/en_31941205v020101p.pdf - id-etsi-qct-esign + * @since 3.13.0 */ const string X509Cert::QCT_ESIGN = "0.4.0.1862.1.6.1"; /** * http://www.etsi.org/deliver/etsi_en/319400_319499/31941205/02.01.01_60/en_31941205v020101p.pdf - id-etsi-qct-eseal + * @since 3.13.0 */ const string X509Cert::QCT_ESEAL = "0.4.0.1862.1.6.2"; /** * http://www.etsi.org/deliver/etsi_en/319400_319499/31941205/02.01.01_60/en_31941205v020101p.pdf - id-etsi-qct-web + * @since 3.13.0 */ const string X509Cert::QCT_WEB = "0.4.0.1862.1.6.3"; /** * http://www.etsi.org/deliver/etsi_ts/101400_101499/101456/01.04.03_60/ts_101456v010403p.pdf + * @since 3.13.0 */ const string X509Cert::QCP_PUBLIC_WITH_SSCD = "0.4.0.1456.1.1"; /** * http://www.etsi.org/deliver/etsi_ts/101400_101499/101456/01.04.03_60/ts_101456v010403p.pdf + * @since 3.13.0 */ const string X509Cert::QCP_PUBLIC = "0.4.0.1456.1.2"; /** * http://www.etsi.org/deliver/etsi_en/319400_319499/31941102/02.01.01_60/en_31941102v020101p.pdf + * @since 3.13.0 */ const string X509Cert::QCP_NATURAL = "0.4.0.194112.1.0"; /** * http://www.etsi.org/deliver/etsi_en/319400_319499/31941102/02.01.01_60/en_31941102v020101p.pdf + * @since 3.13.0 */ const string X509Cert::QCP_LEGAL = "0.4.0.194112.1.1"; /** * http://www.etsi.org/deliver/etsi_en/319400_319499/31941102/02.01.01_60/en_31941102v020101p.pdf + * @since 3.13.0 */ const string X509Cert::QCP_NATURAL_QSCD = "0.4.0.194112.1.2"; /** * http://www.etsi.org/deliver/etsi_en/319400_319499/31941102/02.01.01_60/en_31941102v020101p.pdf + * @since 3.13.0 */ const string X509Cert::QCP_LEGAL_QSCD = "0.4.0.194112.1.3"; /** * http://www.etsi.org/deliver/etsi_en/319400_319499/31941102/02.01.01_60/en_31941102v020101p.pdf + * @since 3.13.0 */ const string X509Cert::QCP_WEB = "0.4.0.194112.1.4"; /** * Creates copy of the OpenSSL X509 certificate. * - * @param cert X509 certificate structure to be wrapped. + * @param cert OpenSSL X509 certificate structure to be wrapped. */ X509Cert::X509Cert(X509* cert) : cert(X509_dup(cert), X509_free) @@ -200,11 +243,11 @@ X509Cert::X509Cert(X509* cert) } /** - * Creates X509 certificate from bytes. + * Creates X509 certificate from a vector of bytes. * - * @param bytes X509 certificate in bytes. - * @param format Format input bytes format - * @throws Exception throws exception if X509 certificate parsing failed. + * @param bytes X509 certificate data. + * @param format Format input bytes format (Der or Pem). + * @throws Exception if X509 certificate parsing failed. */ X509Cert::X509Cert(const vector &bytes, Format format) : X509Cert(bytes.data(), bytes.size(), format) @@ -212,12 +255,12 @@ X509Cert::X509Cert(const vector &bytes, Format format) } /** - * Creates X509 certificate from bytes. + * Creates X509 certificate from raw bytes. * - * @param bytes X509 certificate in bytes. - * @param size of X509 certificate in bytes. - * @param format Format input bytes format - * @throws Exception throws exception if X509 certificate parsing failed. + * @param bytes Pointer to X509 certificate data. + * @param size Size of the data in bytes. + * @param format Format input bytes format (Der or Pem). + * @throws Exception if X509 certificate parsing failed. */ X509Cert::X509Cert(const unsigned char *bytes, size_t size, Format format) { @@ -238,11 +281,11 @@ X509Cert::X509Cert(const unsigned char *bytes, size_t size, Format format) } /** - * Creates X509 certificate from path. + * Creates X509 certificate from a file. * - * @param path X509 certificate path. - * @param format Format input bytes format - * @throws Exception throws exception if X509 certificate parsing failed. + * @param path Path to the X509 certificate file. + * @param format Format input file format (Der or Pem). + * @throws Exception if the file cannot be opened or parsing failed. */ X509Cert::X509Cert(const string &path, Format format) { @@ -270,12 +313,14 @@ X509Cert::X509Cert(const X509Cert &other) = default; X509Cert::X509Cert(X509Cert &&other) noexcept = default; /** - * Clean up underlying X509 data. + * Clean up underlying OpenSSL X509 data. */ X509Cert::~X509Cert() = default; /** * Encodes the X509 certificate using DER encoding. + * + * @return DER encoded certificate bytes. */ X509Cert::operator std::vector() const { @@ -283,7 +328,9 @@ X509Cert::operator std::vector() const } /** - * Returns true if handle is valid + * Checks if the certificate object holds a valid OpenSSL handle. + * + * @return true if handle is valid. */ X509Cert::operator bool() const { @@ -291,9 +338,10 @@ X509Cert::operator bool() const } /** - * Returns X.509 certificate serial number. + * Returns X.509 certificate serial number in decimal string format. * - * @throws Exception exception is thrown if the serial is incorrect. + * @return Decimal serial number string. + * @throws Exception if the serial number cannot be retrieved. */ string X509Cert::serial() const { @@ -308,11 +356,12 @@ string X509Cert::serial() const } /** - * Returns issuer name as string. + * Returns issuer name as an RFC 2253 string. * - * @param obj if set to empty string then returns whole issuer name. Otherwise, for example, if set to - * CN then returns Common name part from issuer name. - * @throws Exception exception is throws if the conversion failed. + * @param obj If empty, returns the full issuer DN. If a short name (e.g., "CN", "O", "C") is provided, + * returns only that component of the issuer name. + * @return Issuer name string. + * @throws Exception if the conversion failed. */ string X509Cert::issuerName(const string &obj) const { @@ -326,7 +375,9 @@ constexpr auto X509Cert::extension(int nid) const noexcept } /** - * Returns current certificate key usage bits + * Returns the certificate's key usage bits. + * + * @return Vector of KeyUsage enums. */ vector X509Cert::keyUsage() const { @@ -344,7 +395,9 @@ vector X509Cert::keyUsage() const } /** - * Returns current certificate policies + * Returns the certificate's policy OIDs. + * + * @return Vector of policy OID strings. */ vector X509Cert::certificatePolicies() const { @@ -358,7 +411,10 @@ vector X509Cert::certificatePolicies() const } /** - * Return QCStatements info https://www.ietf.org/rfc/rfc3739.txt + * Returns Qualified Certificate (QC) statements as defined in RFC 3739 and ETSI EN 319 412-5. + * + * @since 3.13.0 + * @return Vector of OID strings representing QC statements. */ vector X509Cert::qcStatements() const { @@ -404,11 +460,12 @@ vector X509Cert::qcStatements() const } /** - * Return subject name as string. + * Returns subject name as an RFC 2253 string. * - * @param obj empty string then returns whole issuer name. Otherwise, for example, if set to - * CN then returns Common name part from issuer name. - * @throws Exception exception is throws if the conversion failed. + * @param obj If empty, returns the full subject DN. If a short name (e.g., "CN", "SN", "GN") is provided, + * returns only that component of the subject name. + * @return Subject name string. + * @throws Exception if the conversion failed. */ string X509Cert::subjectName(const string &obj) const { @@ -423,11 +480,11 @@ string X509Cert::toOID(ASN1_OBJECT *obj) }; /** - * Converts X509_NAME struct to string. + * Converts OpenSSL X509_NAME struct to string. * - * @param obj Optional parameter to get from X509_NAME (default CN). - * @return converted value of X509_NAME. - * @throws Exception throws exception if conversion failed. + * @param obj Optional parameter to extract a specific component (e.g., "CN"). + * @return String representation of the name. + * @throws Exception if conversion failed. */ template string X509Cert::toString(const string &obj) const @@ -437,7 +494,7 @@ string X509Cert::toString(const string &obj) const return str; X509_NAME* name = Func(cert.get()); if(!name) - THROW_OPENSSLEXCEPTION("Failed to convert X.509 certificate subject"); + THROW_OPENSSLEXCEPTION("Failed to convert X.509 certificate name"); if(!obj.empty()) { @@ -472,7 +529,9 @@ string X509Cert::toString(const string &obj) const } /** - * Returns certificate internal handle (OpenSSL X509 struct) + * Returns the internal OpenSSL X509 structure handle. + * + * @return Pointer to OpenSSL X509 structure. */ X509* X509Cert::handle() const { @@ -480,7 +539,9 @@ X509* X509Cert::handle() const } /** - * Rerturns true if certificate is CA + * Checks if the certificate is a Certificate Authority (CA). + * + * @return true if the certificate is a CA. */ bool X509Cert::isCA() const { @@ -489,9 +550,11 @@ bool X509Cert::isCA() const } /** - * Validates if certificate is in valid time slot + * Validates if the certificate is within its valid time period. * - * @param t If param is 0 then current time is used, else defined time + * @param t Pointer to time_t. If nullptr, the current system time is used. + * @return true if the certificate is valid at time t. + * @throws Exception if validation fails. */ bool X509Cert::isValid(time_t *t) const { @@ -505,8 +568,13 @@ bool X509Cert::isValid(time_t *t) const } /** - * Returns true if certificate is signed by trusted issuer - * @throws Exception if error + * Verifies if the certificate is signed by a trusted issuer. + * + * @since 4.4.0 + * @param noqscd If true, QSCD (Qualified Signature Creation Device) requirements are not checked. + * @param validation_time Time at which the validation is performed. + * @return true if the certificate is verified as trusted. + * @throws Exception if verification error occurs. */ bool X509Cert::verify(bool noqscd, tm validation_time) const { @@ -514,7 +582,9 @@ bool X509Cert::verify(bool noqscd, tm validation_time) const } /** - * Negative operator to check if object is valid + * Checks if the certificate object is invalid (holds no handle). + * + * @return true if the certificate is invalid. */ bool X509Cert::operator !() const { @@ -522,17 +592,20 @@ bool X509Cert::operator !() const } /** - * Assign operator + * Assignment operator. */ X509Cert& X509Cert::operator =(const X509Cert &other) = default; /** - * Move operator + * Move assignment operator. */ X509Cert& X509Cert::operator =(X509Cert &&other) noexcept = default; /** - * Equal operator to compare two objects + * Compares the certificate with an OpenSSL X509 pointer. + * + * @param other Pointer to OpenSSL X509 structure. + * @return true if both refer to the same certificate. */ bool X509Cert::operator ==(X509 *other) const { @@ -544,7 +617,10 @@ bool X509Cert::operator ==(X509 *other) const } /** - * Equal operator to compare two objects + * Compares two X509Cert objects. + * + * @param other Another X509Cert object. + * @return true if both refer to the same certificate. */ bool X509Cert::operator ==(const X509Cert &other) const { @@ -552,7 +628,10 @@ bool X509Cert::operator ==(const X509Cert &other) const } /** - * Not equal operator to compare two objects + * Compares two X509Cert objects for inequality. + * + * @param other Another X509Cert object. + * @return true if the certificates are different. */ bool X509Cert::operator !=(const X509Cert &other) const {