Merge branch 'master' into hardening

* master:
  Implement TR31_USE_SSCANF_DATETIME
  Update to latest libargp
  Fix various typos
  Fix ISO 8601 parsing using sscanf() when strptime() is unavailable
  Fix ASCII decimal to binary integer conversion
  Fix and improve parsing of IBM proprietary optional blocks
  Update Gentoo ebuild
  Update tr31-tool to use GPLv3
  Update to latest libargp
  Improve readability of optional block PB export
  Fix ISO 8601 delimiter validation

This merge is to confirm that the master branch resolves the remaining
CodeQL items in the hardening branch.

Author: leonlynch

.github/workflows/ubuntu-build.yaml

@@ -42,6 +42,34 @@ jobs:
     - name: Test
       run: ctest --test-dir build --output-on-failure -j 4
 
+  build-ubuntu-sscanf:
+    name: Ubuntu (sscanf)
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Install dependencies
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y libmbedtls-dev
+
+    - name: Checkout
+      uses: actions/checkout@v4
+      with:
+        submodules: recursive
+    - run: git describe --always --dirty
+
+    - name: Configure CMake with sscanf() for date/time
+      run: |
+        cmake -B build \
+          -DCMAKE_BUILD_TYPE="Debug" \
+          -DTR31_USE_SSCANF_DATETIME=ON
+
+    - name: Build
+      run: cmake --build build -j 4
+
+    - name: Test
+      run: ctest --test-dir build --output-on-failure -j 4
+
   build-ubuntu-sanitizers:
     strategy:
       fail-fast: false

README.md

@@ -11,7 +11,7 @@ This project began as an implementation of the ASC X9 TR-31 standard and has
 since grown to include the ANSI X9.143 standard which supersedes it, and the
 ISO 20038 standard which extends it. However, this project continues to refer
 to the library as TR-31 and prefixes the API, data types and command line tool
-with `tr31`, while mostly avoiding that naming when refering to key blocks and
+with `tr31`, while mostly avoiding that naming when referring to key blocks and
 data associated with key blocks. Given that most uses of these standards
 involve dedicated security hardware, this implementation is mostly for
 validation and debugging purposes.
@@ -55,9 +55,10 @@ Dependencies
 * TR-31 library requires [MbedTLS](https://github.com/Mbed-TLS/mbedtls)
   (preferred), or [OpenSSL](https://www.openssl.org/)
 * `tr31-tool` will be built by default and requires `argp` (either via Glibc, a
-  system-provided standalone or a downloaded implementation; see
+  system-provided standalone, or downloaded during the build from
+  [libargp](https://github.com/leonlynch/libargp); see
   [MacOS / Windows](#macos--windows)). Use the `BUILD_TR31_TOOL` option to
-  prevent TR-31 tool from being built and avoid the dependency on `argp`.
+  prevent `tr31-tool` from being built and avoid the dependency on `argp`.
 * [Doxygen](https://github.com/doxygen/doxygen) can _optionally_ be used to
   generate API documentation if it is available; see
   [Documentation](#documentation)
@@ -216,5 +217,15 @@ License
 
 Copyright 2020-2025 [Leon Lynch](https://github.com/leonlynch).
 
-This project is licensed under the terms of the LGPL v2.1 license. See
-[LICENSE](https://github.com/openemv/tr31/blob/master/LICENSE) file.
+This project is licensed under the terms of the LGPL v2.1 license with the
+exception of `tr31-tool` which is licensed under the terms of the GPL v3
+license.
+See [LICENSE](https://github.com/openemv/tr31/blob/master/LICENSE) file.
+
+This project includes [crypto](https://github.com/openemv/crypto) as a git
+submodule and it is licensed under the terms of the MIT license. See
+[LICENSE](https://github.com/openemv/crypto/blob/master/LICENSE) file.
+
+This project may download [libargp](https://github.com/leonlynch/libargp)
+during the build and it is licensed under the terms of the LGPL v3 license. See
+[LICENSE](https://github.com/leonlynch/libargp/blob/master/LICENSE) file.

cmake/Modules/FetchLibArgp.cmake

@@ -1,5 +1,5 @@
 ##############################################################################
-# Copyright 2022-2023 Leon Lynch
+# Copyright 2022-2023, 2025 Leon Lynch
 #
 # This file is licensed under the terms of the LGPL v2.1 license.
 # See LICENSE file.
@@ -24,7 +24,7 @@ message(CHECK_START "Downloading libargp...")
 FetchContent_Declare(
 	libargp
 	GIT_REPOSITORY https://github.com/leonlynch/libargp.git
-	GIT_TAG 987d87b98e4cd03abb1107b77ef5d43ad0552e13
+	GIT_TAG 0a0c4df3431d4f268076d5784080b5c5b6434b8f
 )
 FetchContent_MakeAvailable(libargp)
 message(CHECK_PASS "done")

gentoo/dev-libs/tr31/metadata.xml

@@ -12,5 +12,6 @@
 	<use>
 		<flag name="mbedtls">Use MbedTLS as the crypto library</flag>
 		<flag name="openssl">Use OpenSSL as the crypto library</flag>
+		<flag name="tools">Build command-line tool (tr31-tool)</flag>
 	</use>
 </pkgmetadata>

gentoo/dev-libs/tr31/tr31-9999.ebuild

@@ -1,4 +1,4 @@
-# Copyright 1999-2024 Gentoo Authors
+# Copyright 1999-2025 Gentoo Authors
 # Distributed under the terms of the GNU General Public License v2
 
 EAPI=8
@@ -15,10 +15,10 @@ else
 	SRC_URI="https://github.com/openemv/tr31/releases/download/${PV}/${P}-src.tar.gz -> ${P}.tar.gz"
 fi
 
-LICENSE="LGPL-2.1"
+LICENSE="LGPL-2.1+ tools? ( GPL-3+ )"
 SLOT="0"
 KEYWORDS="~amd64 ~x86"
-IUSE="+mbedtls openssl doc test"
+IUSE="+mbedtls openssl +tools doc test"
 REQUIRED_USE="|| ( mbedtls openssl )"
 RESTRICT="!test? ( test )"
 
@@ -45,6 +45,7 @@ src_configure() {
 	local mycmakeargs=(
 		$(cmake_use_find_package mbedtls MbedTLS)
 		$(cmake_use_find_package openssl OpenSSL)
+		-DBUILD_TR31_TOOL=$(usex tools)
 		-DBUILD_DOCS=$(usex doc)
 		-DBUILD_TESTING=$(usex test)
 	)

src/CMakeLists.txt

@@ -116,6 +116,14 @@ else()
 	# set as cache entry to persist across multiple builds
 	set(TR31_ENABLE_DATETIME_CONVERSION OFF CACHE INTERNAL "Date/time conversion availability")
 endif()
+# option to use sscanf() for date/time parsing even when strptime() is
+# available
+option(TR31_USE_SSCANF_DATETIME "Use sscanf() for date/time parsing")
+if(HAVE_STRPTIME AND NOT TR31_USE_SSCANF_DATETIME)
+	message(STATUS "Using strptime() for date/time parsing")
+else()
+	message(STATUS "Using sscanf() for date/time parsing")
+endif()
 
 include(GNUInstallDirs) # provides CMAKE_INSTALL_* variables and good defaults for install()
 
@@ -905,7 +913,7 @@ if(TARGET tr31-tool AND BUILD_TESTING)
 	)
 
 	# test IBM proprietary key block
-	# NOTE: the input was hand crafted based on https://www.ibm.com/docs/en/zos/3.1.0?topic=ktf-x9143-tr-31-key-block-header-optional-block-data and https://www.ibm.com/docs/en/linux-on-systems?topic=data-tr-31-optional-block
+	# NOTE: the input was hand crafted based on https://www.ibm.com/docs/en/zos/3.2.0?topic=ktf-x9143-tr-31-key-block-header-optional-block-data and https://www.ibm.com/docs/en/linux-on-systems?topic=data-tr-31-optional-block
 	add_test(NAME tr31_tool_test53
 		COMMAND tr31-tool --import D014410A100N0200101CIBMC01140123456789ABCDEFPB04000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 --import-no-strict-validation
 	)

src/tr31-tool.c

@@ -3,19 +3,18 @@
  *
  * Copyright 2020-2025 Leon Lynch
  *
- * This program is free software; you can redistribute it and/or
- * modify it under the terms of the GNU Lesser General Public
- * License as published by the Free Software Foundation; either
- * version 2.1 of the License, or (at your option) any later version.
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
  *
  * This program is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
- * Lesser General Public License for more details.
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
  *
- * You should have received a copy of the GNU Lesser General Public
- * License along with this program. If not, see
- * <https://www.gnu.org/licenses/>.
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
 #include "tr31.h"
@@ -162,7 +161,7 @@ static struct argp_option argp_options[] = {
 	{ "export-opt-block-KC", TR31_TOOL_OPTION_EXPORT_OPT_BLOCK_KC, NULL, 0, "Add optional block KC (KCV of wrapped key) during key block export. May be used with either --export-template or --export-header." },
 	{ "export-opt-block-KP", TR31_TOOL_OPTION_EXPORT_OPT_BLOCK_KP, NULL, 0, "Add optional block KP (KCV of KBPK) during key block export. May be used with either --export-template or --export-header." },
 	{ "export-opt-block-KS", TR31_TOOL_OPTION_EXPORT_OPT_BLOCK_KS, "IKSN", 0, "Add optional block KS (Initial Key Serial Number) during key block export. May be used with either --export-template or --export-header." },
-	{ "export-opt-block-LB", TR31_TOOL_OPTION_EXPORT_OPT_BLOCK_LB, "ASCII", 0, "Add optinal block LB (Label) during key block export. May be used with either --export-template or --export-header." },
+	{ "export-opt-block-LB", TR31_TOOL_OPTION_EXPORT_OPT_BLOCK_LB, "ASCII", 0, "Add optional block LB (Label) during key block export. May be used with either --export-template or --export-header." },
 	{ "export-opt-block-PK", TR31_TOOL_OPTION_EXPORT_OPT_BLOCK_PK, "KCV", 0, "Add optional block PK (Protection Key Check Value) during key block export. May be used with either --export-template or --export-header." },
 	{ "export-opt-block-TC", TR31_TOOL_OPTION_EXPORT_OPT_BLOCK_TC, "ISO8601", 0, "Add optional block TC (Time of Creation in ISO 8601 UTC format) during key block export. May be used with either --export-template or --export-header. Specify \"now\" for current date/time." },
 	{ "export-opt-block-TS", TR31_TOOL_OPTION_EXPORT_OPT_BLOCK_TS, "ISO8601", 0, "Add optional block TS (Time Stamp in ISO 8601 UTC format) during key block export. May be used with either --export-template or --export-header. Specify \"now\" for current date/time." },
@@ -454,7 +453,7 @@ static error_t argp_parser_helper(int key, char* arg, struct argp_state* state)
 			}
 			for (size_t i = 0; i < strlen(arg); ++i) {
 				if (!isalnum(arg[i])) {
-					argp_error(state, "Export optional block DA consist of alphanumeric characters (invalid character '%c' is not allowed)", arg[i]);
+					argp_error(state, "Export optional block DA must consist of alphanumeric characters (invalid character '%c' is not allowed)", arg[i]);
 				}
 			}
 			options->export_opt_block_DA = arg;

src/tr31.c

@@ -153,7 +153,7 @@ static int dec_to_int(const char* str, size_t str_len)
 
 	value = 0;
 	for (size_t i = 0; i < str_len; ++i) {
-		if (str[i] < '0' && str[i] > '9') {
+		if (str[i] < '0' || str[i] > '9') {
 			return -1;
 		}
 
@@ -855,7 +855,7 @@ int tr31_init_from_header(
 		ptr += opt_blk_len;
 	}
 
-	// NOTE: the total optional block length is intentially ignored and not
+	// NOTE: the total optional block length is intentionally ignored and not
 	// validated against the encryption block length
 
 	// success
@@ -2559,11 +2559,13 @@ int tr31_export(
 	// So we'll use the encryption block size which is determined by the key
 	// block format version.
 	if (opt_blk_len_total & (state.enc_block_size-1)) {
-		unsigned int pb_len = 4; // Minimum length of optional block PB
+		// minimum length of optional block PB
+		const unsigned int pb_min_len = sizeof(struct tr31_opt_blk_hdr_t);
+		unsigned int pb_len = pb_min_len;
 
 		// compute required padding length
-		if ((opt_blk_len_total + pb_len) & (state.enc_block_size-1)) { // if further padding is required
-			pb_len = ((opt_blk_len_total + 4 + state.enc_block_size) & ~(state.enc_block_size-1)) - opt_blk_len_total;
+		if ((opt_blk_len_total + pb_min_len) & (state.enc_block_size-1)) { // if further padding is required
+			pb_len = ((opt_blk_len_total + pb_min_len + state.enc_block_size) & ~(state.enc_block_size-1)) - opt_blk_len_total;
 		}
 
 		if (ptr + pb_len - (void*)header > key_block_buf_len) {
@@ -2890,6 +2892,9 @@ static int tr31_opt_block_parse(
 
 static int tr31_opt_block_validate_iso8601(const char* str, size_t str_len)
 {
+	// length of optional block header used for ISO 8601 values
+	const unsigned int opt_blk_hdr_len = sizeof(struct tr31_opt_blk_hdr_t);
+
 	if (!str) {
 		return -1;
 	}
@@ -2901,10 +2906,10 @@ static int tr31_opt_block_validate_iso8601(const char* str, size_t str_len)
 	// validate ISO 8601 string length
 	// see ANSI X9.143:2021, 6.3.6.13, table 21
 	// see ANSI X9.143:2021, 6.3.6.14, table 22
-	if (str_len != 0x13 - 4 && // no delimiters, ss precision
-		str_len != 0x15 - 4 && // no delimiters, ssss precision
-		str_len != 0x18 - 4 && // delimiters, ss precision
-		str_len != 0x1B - 4 // delimiters, ss.ss precision
+	if (str_len != 0x13 - opt_blk_hdr_len && // no delimiters, ss precision
+		str_len != 0x15 - opt_blk_hdr_len && // no delimiters, ssss precision
+		str_len != 0x18 - opt_blk_hdr_len && // delimiters, ss precision
+		str_len != 0x1B - opt_blk_hdr_len // delimiters, ss.ss precision
 	) {
 		return TR31_ERROR_INVALID_OPTIONAL_BLOCK_DATA;
 	}
@@ -2917,7 +2922,8 @@ static int tr31_opt_block_validate_iso8601(const char* str, size_t str_len)
 	}
 
 	// validate ISO 8601 delimiters (YYYY-MM-DDThh:mm:ss[.ss])
-	if (str_len == 0x18 || str_len == 0x1B) {
+	if (str_len == 0x18 - opt_blk_hdr_len ||
+		str_len == 0x1B - opt_blk_hdr_len) {
 		if (str[4] != '-' ||
 			str[7] != '-' ||
 			str[10] != 'T' ||
@@ -2927,7 +2933,7 @@ static int tr31_opt_block_validate_iso8601(const char* str, size_t str_len)
 			return TR31_ERROR_INVALID_OPTIONAL_BLOCK_DATA;
 		}
 	}
-	if (str_len == 0x1B) {
+	if (str_len == 0x1B - opt_blk_hdr_len) {
 		if (str[19] != '.') {
 			return TR31_ERROR_INVALID_OPTIONAL_BLOCK_DATA;
 		}
@@ -3015,18 +3021,24 @@ static int tr31_opt_block_export_PB(
 	struct tr31_opt_blk_t* opt_blk
 )
 {
+	if (pb_len < sizeof(*opt_blk)) {
+		// this should never happen
+		return -1;
+	}
+	const size_t pb_data_len = pb_len - sizeof(*opt_blk);
+
 	opt_blk->id = htons(TR31_OPT_BLOCK_PB);
 	int_to_hex(pb_len, opt_blk->length, sizeof(opt_blk->length));
 
 	if ((state->flags & TR31_EXPORT_ZERO_OPT_BLOCK_PB) == 0) {
 		// populate with random data and then transpose to the required range
-		crypto_rand(opt_blk->data, pb_len - 4);
+		crypto_rand(opt_blk->data, pb_data_len);
 	} else {
 		// populate with zeros instead of random data
-		memset(opt_blk->data, 0, pb_len - 4);
+		memset(opt_blk->data, 0, pb_data_len);
 	}
 
-	for (size_t i = 0; i < pb_len - 4; ++i) {
+	for (size_t i = 0; i < pb_data_len; ++i) {
 		// although optional block PB may contain printable ASCII characters in
 		// the range 0x20 to 0x7E, characters outside the ranges of '0'-'9',
 		// 'A'-'Z' and 'a'-'z' are problematic when using HSM protocols that
@@ -3047,8 +3059,8 @@ static int tr31_opt_block_export_PB(
 		} else if (tmp < 62) {
 			opt_blk->data[i] = tmp - 36 + 'a'; // 'a'-'z'
 		} else {
-			// This should never happen
-			return -1;
+			// this should never happen
+			return -2;
 		}
 	}
 

src/tr31.h

@@ -2,7 +2,7 @@
  * @file tr31.h
  * @brief High level TR-31 library interface
  *
- * Copyright 2020-2023 Leon Lynch
+ * Copyright 2020-2023, 2025 Leon Lynch
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public
@@ -378,7 +378,7 @@ struct tr31_opt_blk_kcv_data_t {
  * @see @ref optional-block-wp-values "Wrapping Pedigree (WP) optional block values"
  */
 struct tr31_opt_blk_wp_data_t {
-	uint8_t version; ///<Wrapping Pedigree (WP) format version
+	uint8_t version; ///< Wrapping Pedigree (WP) format version
 	/// Wrapping Pedigree (WP) version 0
 	struct v0_t {
 		uint8_t wrapping_pedigree; ///< Wrapping Pedigree value
@@ -778,7 +778,7 @@ int tr31_opt_block_decode_HM(
  *
  * @param ctx Key block context object
  * @param ikid Initial Key Identifier (IKID) for Initial AES DUKPT Key
- * @param ikid_len of @p ikid in bytes. Must be 8 bytes.
+ * @param ikid_len Length of @p ikid in bytes. Must be 8 bytes.
  * @return Zero for success. Less than zero for internal error. Greater than zero for data error. See @ref tr31_error_t
  */
 int tr31_opt_block_add_IK(
@@ -796,7 +796,7 @@ int tr31_opt_block_add_IK(
  *
  * @param opt_ctx Optional block context object
  * @param ikid Initial Key Identifier (IKID) output
- * @param ikid_len of @p ikid in bytes. Must be 8 bytes.
+ * @param ikid_len Length of @p ikid in bytes. Must be 8 bytes.
  * @return Zero for success. Less than zero for internal error. Greater than zero for data error. See @ref tr31_error_t
  */
 int tr31_opt_block_decode_IK(
@@ -935,7 +935,7 @@ int tr31_opt_block_add_LB(
  *
  * @param ctx Key block context object
  * @param kcv_algorithm KCV algorithm. Either @ref TR31_OPT_BLOCK_KCV_LEGACY or @ref TR31_OPT_BLOCK_KCV_CMAC.
- * @param kcv Key Check Value (KCV) according to algoritm specified by @p kcv_algorithm
+ * @param kcv Key Check Value (KCV) according to algorithm specified by @p kcv_algorithm
  * @param kcv_len Length of @p kcv in bytes. Must comply with ANSI X9.24-1 Annex A.
  * @return Zero for success. Less than zero for internal error. Greater than zero for data error. See @ref tr31_error_t
  */

src/tr31_config.h.in

@@ -35,5 +35,6 @@
 #cmakedefine HAVE_LOCALTIME_R
 #cmakedefine HAVE_GMTIME_R
 #cmakedefine TR31_ENABLE_DATETIME_CONVERSION
+#cmakedefine TR31_USE_SSCANF_DATETIME
 
 #endif