Improve processing of EMV format 'a', 'an' and 'ans'

* Fix emv_format_ans_to_alnum_space_str() to allow space character
* Move AID-to-ASCII conversion to emv_format_b_to_str() function
* Implement emv_format_a_get_string() to stringify format 'a'
* Implement emv_format_an_get_string() to stringify format 'an'
* Implement emv_format_ans_only_space_get_string() to stringify
  Application Label (field 50)
* Implement emv_format_ans_ccs_get_string() to stringify format 'ans'
  using only the ISO/IEC 8859 common character set
* Update various comments to clarify whether the output is ISO/IEC 8859
  or UTF-8

Also update emv-tool regarding fields that use these formats:
* Add Acquirer Identifier (field 9F01) to terminal configuration to
  illustrate format 'n'
* Add Merchant Identifier (field 9F16) to terminal configuration to
  illustrate format 'ans' of fixed length with padding
* Add Merchant Name and Location (field 9F4E) to terminal configuration
  to illustrate format 'ans' of variable length with no padding
* Fix Terminal Identification (field 9F1C) to be format 'an'

Author: leonlynch

src/emv_app.c

@@ -31,7 +31,6 @@
 #include <assert.h>
 
 // Helper functions
-static int emv_aid_get_string(const uint8_t* aid, size_t aid_len, char* str, size_t str_len);
 static int emv_app_extract_display_name(struct emv_app_t* app, struct emv_tlv_list_t* pse_tlv_list);
 static int emv_app_extract_priority_indicator(struct emv_app_t* app);
 static inline bool emv_app_list_is_valid(const struct emv_app_list_t* list);
@@ -144,35 +143,6 @@ struct emv_app_t* emv_app_create_from_fci(const void* fci, size_t fci_len)
 	return NULL;
 }
 
-static int emv_aid_get_string(const uint8_t* aid, size_t aid_len, char* str, size_t str_len)
-{
-	if (str_len < aid_len * 2 + 1) {
-		return -1;
-	}
-
-	for (size_t i = 0; i < str_len && i < aid_len * 2; ++i) {
-		uint8_t nibble;
-
-		if ((i & 0x01) == 0) {
-			// Most significant nibble
-			nibble = aid[i >> 1] >> 4;
-		} else {
-			// Least significant nibble
-			nibble = aid[i >> 1] & 0x0F;
-		}
-
-		// Convert to ASCII digit
-		if (nibble < 0xA) {
-			str[i] = '0' + nibble;
-		} else {
-			str[i] = 'A' + (nibble - 0xA);
-		}
-	}
-	str[aid_len * 2] = 0; // NULL terminate
-
-	return 0;
-}
-
 static int emv_app_extract_display_name(struct emv_app_t* app, struct emv_tlv_list_t* pse_tlv_list)
 {
 	int r;
@@ -259,7 +229,7 @@ static int emv_app_extract_display_name(struct emv_app_t* app, struct emv_tlv_li
 
 	// Use Application Identifier (AID) as display name
 	if (app->aid) {
-		return emv_aid_get_string(
+		return emv_format_b_to_str(
 			app->aid->value,
 			app->aid->length,
 			app->display_name,

src/emv_strings.c

@@ -2,7 +2,7 @@
  * @file emv_strings.c
  * @brief EMV string helper functions
  *
- * Copyright (c) 2021, 2022, 2023 Leon Lynch
+ * Copyright (c) 2021-2024 Leon Lynch
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public
@@ -1071,18 +1071,43 @@ static int emv_tlv_value_get_string(const struct emv_tlv_t* tlv, enum emv_format
 
 	switch (format) {
 		case EMV_FORMAT_A:
+			r = emv_format_a_get_string(tlv->value, tlv->length, value_str, value_str_len);
+			if (r) {
+				// Ignore parse error
+				value_str[0] = 0;
+				return 0;
+			}
+
+			return 0;
+
 		case EMV_FORMAT_AN:
+			r = emv_format_an_get_string(tlv->value, tlv->length, value_str, value_str_len);
+			if (r) {
+				// Ignore parse error
+				value_str[0] = 0;
+				return 0;
+			}
+
+			return 0;
+
 		case EMV_FORMAT_ANS:
-			// TODO: validate format 'a' characters
-			// TODO: validate format 'an' characters
-			// TODO: validate format 'ans' characters in accordance with ISO/IEC 8859 common character, EMV 4.3 Book 4, Annex B
-			// TODO: validate EMV_TAG_50_APPLICATION_LABEL in accordance with EMV 4.3 Book 3, 4.3
-			// TODO: convert EMV_TAG_9F12_APPLICATION_PREFERRED_NAME from the appropriate ISO/IEC 8859 code page to UTF-8
-
-			// For now assume that the field bytes are valid ASCII and are
-			// only the allowed characters specified in EMV 4.3 Book 3, 4.3
-			memcpy(value_str, tlv->value, tlv->length);
-			value_str[tlv->length] = 0; // NULL terminate
+			if (tlv->tag == EMV_TAG_50_APPLICATION_LABEL) {
+				r = emv_format_ans_only_space_get_string(tlv->value, tlv->length, value_str, value_str_len);
+			}
+			else if (tlv->tag == EMV_TAG_9F12_APPLICATION_PREFERRED_NAME) {
+				// TODO: Convert EMV_TAG_9F12_APPLICATION_PREFERRED_NAME from the appropriate ISO/IEC 8859 code page to UTF-8
+				memcpy(value_str, tlv->value, tlv->length);
+				value_str[tlv->length] = 0; // NULL terminate
+				return 0;
+			} else {
+				r = emv_format_ans_ccs_get_string(tlv->value, tlv->length, value_str, value_str_len);
+			}
+			if (r) {
+				// Ignore parse error
+				value_str[0] = 0;
+				return 0;
+			}
+
 			return 0;
 
 		case EMV_FORMAT_CN: {
@@ -1113,6 +1138,155 @@ static int emv_tlv_value_get_string(const struct emv_tlv_t* tlv, enum emv_format
 	}
 }
 
+int emv_format_a_get_string(const uint8_t* buf, size_t buf_len, char* str, size_t str_len)
+{
+	if (!buf || !buf_len || !str || !str_len) {
+		return -1;
+	}
+
+	// Minimum string length
+	if (str_len < buf_len + 1) {
+		return -2;
+	}
+
+	while (buf_len) {
+		// Validate format "a"
+		if (
+			(*buf >= 0x41 && *buf <= 0x5A) || // A-Z
+			(*buf >= 0x61 && *buf <= 0x7A)    // a-z
+		) {
+			*str = *buf;
+
+			// Advance output
+			++str;
+			--str_len;
+		} else {
+			// Invalid digit
+			return 1;
+		}
+
+		++buf;
+		--buf_len;
+	}
+
+	*str = 0; // NULL terminate
+
+	return 0;
+}
+
+int emv_format_an_get_string(const uint8_t* buf, size_t buf_len, char* str, size_t str_len)
+{
+	if (!buf || !buf_len || !str || !str_len) {
+		return -1;
+	}
+
+	// Minimum string length
+	if (str_len < buf_len + 1) {
+		return -2;
+	}
+
+	while (buf_len) {
+		// Validate format "an"
+		if (
+			(*buf >= 0x30 && *buf <= 0x39) || // 0-9
+			(*buf >= 0x41 && *buf <= 0x5A) || // A-Z
+			(*buf >= 0x61 && *buf <= 0x7A)    // a-z
+		) {
+			*str = *buf;
+
+			// Advance output
+			++str;
+			--str_len;
+		} else {
+			// Invalid digit
+			return 1;
+		}
+
+		++buf;
+		--buf_len;
+	}
+
+	*str = 0; // NULL terminate
+
+	return 0;
+}
+
+int emv_format_ans_only_space_get_string(const uint8_t* buf, size_t buf_len, char* str, size_t str_len)
+{
+	if (!buf || !buf_len || !str || !str_len) {
+		return -1;
+	}
+
+	// Minimum string length
+	if (str_len < buf_len + 1) {
+		return -2;
+	}
+
+	while (buf_len) {
+		// Validate format "ans" with special characters limited to space
+		// character, which is effectively format "an" plus space character
+		if (
+			(*buf >= 0x30 && *buf <= 0x39) || // 0-9
+			(*buf >= 0x41 && *buf <= 0x5A) || // A-Z
+			(*buf >= 0x61 && *buf <= 0x7A) || // a-z
+			(*buf == 0x20)                    // Space
+		) {
+			*str = *buf;
+
+			// Advance output
+			++str;
+			--str_len;
+		} else {
+			// Invalid digit
+			return 1;
+		}
+
+		++buf;
+		--buf_len;
+	}
+
+	*str = 0; // NULL terminate
+
+	return 0;
+}
+
+int emv_format_ans_ccs_get_string(const uint8_t* buf, size_t buf_len, char* str, size_t str_len)
+{
+	if (!buf || !buf_len || !str || !str_len) {
+		return -1;
+	}
+
+	// Minimum string length
+	if (str_len < buf_len + 1) {
+		return -2;
+	}
+
+	while (buf_len) {
+		// Validate format "ans" (ISO/IEC 8859 common character set)
+		// See EMV 4.4 Book 4, Annex B
+		if (*buf >= 0x20 && *buf <= 0x7F) {
+			// ISO/IEC 8859 common character set is identical to the first
+			// Unicode block and each character is encoded as a single byte
+			// UTF-8 character
+			*str = *buf;
+
+			// Advance output
+			++str;
+			--str_len;
+		} else {
+			// Invalid digit
+			return 1;
+		}
+
+		++buf;
+		--buf_len;
+	}
+
+	*str = 0; // NULL terminate
+
+	return 0;
+}
+
 int emv_format_cn_get_string(const uint8_t* buf, size_t buf_len, char* str, size_t str_len)
 {
 	if (!buf || !buf_len || !str || !str_len) {

src/emv_strings.h

@@ -2,7 +2,7 @@
  * @file emv_strings.h
  * @brief EMV string helper functions
  *
- * Copyright (c) 2021, 2022, 2023 Leon Lynch
+ * Copyright (c) 2021-2024 Leon Lynch
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public
@@ -33,7 +33,7 @@ __BEGIN_DECLS
 
 /**
  * EMV data element formats
- * @remark See EMV 4.3 Book 1, 4.3
+ * @remark See EMV 4.4 Book 1, 4.3
  */
 enum emv_format_t {
 	/**
@@ -96,7 +96,7 @@ enum emv_format_t {
 
 	/**
 	 * Data Object List (DOL).
-	 * Encoded according to EMV Book 3, 5.4
+	 * Encoded according to EMV 4.4 Book 3, 5.4
 	 */
 	EMV_FORMAT_DOL,
 
@@ -108,8 +108,8 @@ enum emv_format_t {
 
 /**
  * EMV TLV information as human readable strings
- * @remark See EMV 4.3 Book 1, Annex B
- * @remark See EMV 4.3 Book 3, Annex A
+ * @remark See EMV 4.4 Book 1, Annex B
+ * @remark See EMV 4.4 Book 3, Annex A
  * @remark See ISO 7816-4:2005, 5.2.4
  */
 struct emv_tlv_info_t {
@@ -132,7 +132,7 @@ int emv_strings_init(const char* isocodes_path, const char* mcc_path);
 
 /**
  * Retrieve EMV TLV information, if available, and convert value to human
- * readable string(s), if possible.
+ * readable UTF-8 string(s), if possible.
  * @note @c value_str output will be empty if human readable string is not available
  *
  * @param tlv Decoded EMV TLV structure
@@ -149,7 +149,59 @@ int emv_tlv_get_info(
 );
 
 /**
- * Stringify EMV format "cn" (trailing 'F's will be omitted)
+ * Stringify EMV format "a".
+ * See @ref EMV_FORMAT_A
+ *
+ * @param buf Buffer containing EMV format "a" data
+ * @param buf_len Length of buffer in bytes
+ * @param str String buffer output
+ * @param str_len Length of string buffer in bytes
+ * @return Zero for success. Less than zero for internal error. Greater than zero for parse error.
+ */
+int emv_format_a_get_string(const uint8_t* buf, size_t buf_len, char* str, size_t str_len);
+
+/**
+ * Stringify EMV format "an".
+ * See @ref EMV_FORMAT_AN
+ *
+ * @param buf Buffer containing EMV format "an" data
+ * @param buf_len Length of buffer in bytes
+ * @param str String buffer output
+ * @param str_len Length of string buffer in bytes
+ * @return Zero for success. Less than zero for internal error. Greater than zero for parse error.
+ */
+int emv_format_an_get_string(const uint8_t* buf, size_t buf_len, char* str, size_t str_len);
+
+/**
+ * Stringify EMV format "ans", with special characters limited to space
+ * character, to UTF-8.
+ * See @ref EMV_FORMAT_ANS regarding @ref EMV_TAG_50_APPLICATION_LABEL
+ * @remark See ISO/IEC 8859
+ *
+ * @param buf Buffer containing EMV format "ans" data
+ * @param buf_len Length of buffer in bytes
+ * @param str String buffer output
+ * @param str_len Length of string buffer in bytes
+ * @return Zero for success. Less than zero for internal error. Greater than zero for parse error.
+ */
+int emv_format_ans_only_space_get_string(const uint8_t* buf, size_t buf_len, char* str, size_t str_len);
+
+/**
+ * Stringify EMV format "ans" (using ISO/IEC 8859 common character set) to
+ * UTF-8.
+ * See @ref EMV_FORMAT_ANS
+ * @remark See ISO/IEC 8859
+ *
+ * @param buf Buffer containing EMV format "ans" data
+ * @param buf_len Length of buffer in bytes
+ * @param str String buffer output
+ * @param str_len Length of string buffer in bytes
+ * @return Zero for success. Less than zero for internal error. Greater than zero for parse error.
+ */
+int emv_format_ans_ccs_get_string(const uint8_t* buf, size_t buf_len, char* str, size_t str_len);
+
+/**
+ * Stringify EMV format "cn" (trailing 'F's will be omitted).
  * See @ref EMV_FORMAT_CN
  *
  * @param buf Buffer containing EMV format "cn" data
@@ -161,7 +213,7 @@ int emv_tlv_get_info(
 int emv_format_cn_get_string(const uint8_t* buf, size_t buf_len, char* str, size_t str_len);
 
 /**
- * Stringify EMV format "n" (leading zeros will be omitted)
+ * Stringify EMV format "n" (leading zeros will be omitted).
  * See @ref EMV_FORMAT_N
  *
  * @param buf Buffer containing EMV format "n" data