Bitcoin’s APIs in Open-Source Projects: Security Usability Evaluation ^†

Abstract

Given the current state of software development, it does not seem that we are nowhere near vulnerability-free software applications, due to many reasons, and software developers are one of them. Insecure coding practices, the complexity of the task in hand, and usability issues, amongst other reasons, make it hard on software developers to maintain secure code. When it comes to cryptographic currencies, the need for assuring security is inevitable. For example, Bitcoin is a peer-to-peer software system that is primarily used as digital money. There exist many software libraries supporting various programming languages that allow access to the Bitcoin system via an Application Programming Interface (API). APIs that are inappropriately used would lead to security vulnerabilities, which are hard to discover, resulting in many zero-day exploits. Making APIs usable is, therefore, an essential aspect related to the quality and robustness of the software. This paper surveys the general academic literature concerning API usability and usable security. Furthermore, it evaluates the API usability of Libbitcoin, a well-known C++ implementation of the Bitcoin system, and assesses how the findings of this evaluation could affect the applications that use Libbitcoin. For that purpose, the paper proposes two static analysis tools to further investigate the use of Libbitcoin APIs in open-source projects from a security usability perspective. The findings of this research have improved Libbitcoin in many places, as will be shown in this paper.

1. Introduction

The success of Bitcoin as an alternative way of paying money online sparked considerable interest and research in the area of Blockchain, with more interest in Bitcoin’s most prominent technologies, such as the proof-of-work scheme. Most of the existing Bitcoin research revolves around the areas of security, privacy and resource usage, as depicted in Figure 1. While some research has been done on the usability of Bitcoin’s applications from an end-user’s point of view, as far as the authors of this paper know, there is no research yet that addresses usability aspects from a developer’s point of view. From a developer’s point of view, Bitcoin is a software system that implements digital money. A software system’s functionality can be made available to other software systems using Application Programming Interfaces (APIs). Thus, software developers want to create an application that integrates or utilises Bitcoin and can use a software library that provides Bitcoin functionality via such an API. Bitcoin Applications comprehensively deal with monetary assets. A malfunctioned Bitcoin application consequently puts its users at risk of losing money. It is, therefore, critical that such APIs are easy and safe to use. An essential aspect of APIs’ safety is their usability, which is the main focus of this research paper. It is worth emphasising that security verification of the Bitcoin technology or the question regarding the safety of the implementation of Bitcoin’s APIs is outside the scope of this research.

Usability is defined by the ISO 9241-11 standard as “the extent to which a product can be used by specified users to achieve specified goals with effectiveness, efficiency and satisfaction in a specified context of use” [1]. This paper focuses on the usability of security in the context of Bitcoin’s APIs. The users of APIs are software developers. Consequently, from a software developer’s perspective, APIs, for which security is of a major concern, should be designed in such a way that makes it difficult, if not impossible, for client code to introduce security vulnerabilities by misusing an API. Unfortunately, this is not the general case, as discussed by Acar et al. (2017) in [2]. The incorrect use of APIs may result in critical security vulnerabilities, as demonstrated by Myers et al. (2016) in [3]. In the software industry, it is not surprising to find APIs that are poorly documented, hard to learn, inconsistent, or facilitating bugs in the code, which diminishes the benefits gained from using such APIs, as discussed by Zibran et al. (2011) in [4]. Acar et al. (2016) in [5] highlighted that usable security still seems to be a secondary concern for developers. Aspects such as functionality, time-to-market, economics and compliance with corporate policies all seem to have greater importance than making software or APIs secure to use.

What differentiates Bitcoin libraries from general-purpose libraries is that for Bitcoin libraries, security is paramount. Typically, misusing a general-purpose library results in program misbehaviour. While such misbehaviour can sometimes be severe, often it is just annoying. With security APIs, however, misuse can result in misbehaviour that is critical or costly. With Bitcoin libraries, in particular, applications that use such libraries put their users at risk of losing money. The importance of the secure use of Bitcoin APIs, and security APIs in general, shifts the focus of API usability evaluation to some specific first-level attributes of the API usability taxonomy. The first-level usability attribute, knowability, is relevant for any type of API. However, operability, efficiency and subjective satisfaction are evidently less critical for security-related APIs. Instead, robustness and safety become the most crucial aspect of the API usability attributes.

Given the aforementioned challenges, this paper surveys the general academic literature concerning API usability and usable security. It evaluates the API usability of Libbitcoin, a well-known C++ implementation of the Bitcoin system, and assesses how the findings of this evaluation could affect the applications that use Libbitcoin. For such a purpose, the paper proposes two static analysis tools. Besides, this paper studies the use of Bitcoin APIs in open-source projects from a security usability perspective. The findings of this research have improved Libbitcoin in many places, as will be shown in the paper. The organisation of this paper is as follows. Section 2 discusses the research methodology of the paper, demonstrating the data sources, search strategy and how data is extracted along with the inclusion and exclusion criteria. Section 3 surveys the related work. Section 4 introduces the two static analysis tools, including the design objective and the building blocks. Section 5 evaluates the results and lists our observations. Finally, Section 6 concludes the paper and draws the future direction of the work. The novel contribution of this paper focuses on being the first, as to the knowledge of the researchers, work that focuses on the usability of security of the Bitcoin’s libraries and their application in open-source projects. It, also, systematically surveys the existing literature regarding usable security from a software developer’s point of view. It serves as a road-map of the research efforts in the field of usable security from a software developer’s point of view while introducing the key lessons learned from those research proposals.

2. Research Methodology

In this paper, those individual study papers concerning usable security from the developer’s point of view are studied. The main sources of data here are ACM DL (https://www.springer.com/gp) accessed 03.03.2020, IEEE Xplore (https://ieeexplore.ieee.org/Xplore/home.jsp) accessed 03.03.2020, and Springer (https://www.springer.com/ accessed 03.03.2020). The Google Scholar (https://scholar.google.com accessed 03.03.2020) service is also used for some aggregated searches. Given those data sources, the searches are narrowed down to the following areas: Security and Privacy, Software Engineering, and Programming Languages. Conferences such as ICSE, FSE/ESEC, ASE, ISTTA, ICSME, POPL, PLDI, OOPSLA, ICFP, IEEE Security & Privacy, ACM CHI, SOUP, and USENIX are comprehensively researched. The set of surveyed papers (i.e., the individual study papers, as defined by Kitchenham in [6]) are believed to offer a sound body of literature for usable security.

This paper follows the same criteria of Merino et al. (2019) in [7] that only reviews the proceedings of the venues with full papers and excludes other types of papers such as tool posters, keynotes and so forth. The criteria we used to include/exclude papers is the date, peer-review status, the type of publication, and the number of citations. For individual study papers, the abstract was firstly read, and then the conclusion was read. In some cases that required further study, the full paper was read. Most of the papers listed in this research were identified/categorised without reading the full paper. To extract the data from those individual study papers, a mix of manual and automated keyword extraction was utilised. Manually, the words found in the keywords section of those papers were collected, if any. When the keyword section was missing, the free online service from FiveFilters organisation (http://termextract.fivefilters.org/extract.php accessed 03.03.2020) was used with $Maxitems=30$ and $Maxwordsperterm=3$. Then, the list of the resulting keywords was manually inspected against the following terms: “Usability”, “Usable Security”, “Static analysis tool”, “IDE tools”, “Secure Programming”, “secure programming language”, “security learning”, “security learning resources”, “security perception”, “APIs usability”, “Secure coding”, “Secure software development” and “Software developer”.

3. Related Work

According to Rama and Kak (2015, p. 76), “an API can be thought of as a focused expression of the overall functionality of a software module in terms of method declarations that can be called by others wishing to utilise the services offered by the module” [8]. More specifically, an API is a means for a software system to provide some of its functionality to other software systems. APIs are typically a set of function declarations that describe the functionality or services offered by a software system. Assurance is needed to assure those APIs are sound from a security perspective. Software security assurance techniques have been around for some time. To assure safety, the developers’ use of such techniques differs. The developers’ practices to ensure the security of their code range from the use of peer code review to static analysis to penetration testing. Wagner et al. (2015) reported the overhead of such techniques could be too time-consuming, and that is why many developers are not willing to tolerate that in production [9]. Other studies report integration problems, untrustworthiness, overwhelming non-actionable warnings and being too expensive to fix amongst the reasons why developers do not largely use static analysis tools [10]. Generally, the large number of alarms is a major concern with the static analysis tools, as reported by Muske and Serebrenik (2016) in [11]. This is a serious usability problem. Early studies and surveys on API usability, such as McLellan et al. (1998) in [12], Stylos et al. (2008) in [13] and Robillard (2009) in [14] mainly focused on the increased productivity aspect of API usability. Their common finding was that complementary resources, such as documentation and code examples, were instrumental for software developers to grasp and master new APIs quickly. However, considering the grave consequences that security exploits can have, the focus on productivity must be put into context. While producing secure APIs may take a considerable time, this investment will pay off in the long run. The API usability issues can lower code quality and ruin the productivity gains achieved, for example, through reuse. This was argued by Zibran et. al (2011) in [4], where they found that 562 of 1513 bug-posts across five different bug repositories were related to API usability. They tagged all the 562 API usability-related bug-posts with the appropriate usability factors taken from a selection of 22 usability factors that were earlier published by Zibran (2008) in  [15]. Finally, they used the study’s findings to list factors that affect usability and to determine their significance. A study by Piccioni, Furia and Meyer (2013) in [16], focusing on API documentation and tool support, highlighted the importance of naming to convey the semantics of API functions. They further pointed out the importance of accurate documentation and that it may be more difficult for programmers unfamiliar with the conventions of a particular programming language to intuitively understand the APIs targeting that programming language. Finally, they found that the appreciation of choice (i.e., the flexibility offered by a particular API) differs between novice and experienced software developers. ‘Flexibility’ and ‘appreciation of choice’ are, sometimes, the cause of mistakes. For example, password usability does not only affect end-users but also software developers. While end-users are more concerned with the password complexity and how hard it is to break, software developers are more into making sure their applications store passwords securely. Many developers are still storing plain passwords, not the salted-hash value of the passwords.Thus, should the password storage be compromised, the whole system falls apart. Alena et al. (2017) in [17] studied how developers (20 student participants) deal with password storage. The main result, as reported by the study, is that most of the participants claim they have little understanding of the topic of secure password storage. An observation in similar studies that utilise students to reflect the software developers community, raises a concern regarding students instead of professional developers being recruited to investigate a specific industrial practice. How accurate such a practice is, has been investigated by Acar et al. (2016) highlighted in [18]). An information resource such as Stack Overflow (https://stackoverflow.com/ accessed 03.03.2020) is claimed to be one of the reasons for insecure code by inexperienced developers. Research questions such as “What is the best resource to learn security?” and “What does make an information resource a good one for learning security?” have been around for some time now. Acar et al. (2016) in [18] investigated how information resources impact code security. In other words, how programmers learn security. The findings are interesting when the resulting code is evaluated against functionality and security. The developers using Stack Overflow created significantly better functional code and significantly less secure code compared to those using the Android official documentation, for example. On the same line of work, Fischer et al. (2017) in [19] studied the impact of code ’copy and paste’ from Stack Overflow on the code security, which has been studied further by Acar et al. (2017) in [20]. The simple finding in this work is that there exists excessive copying for insecure code snippets from Stack Overflow in current Android applications. About 15.4% copied&pasted code from Stack Overflow with about 97.9% of that containing at least one insecure code snippet. The shocking thing here is that the code snippets copied in those 15.4% applications are security-related code, not just for functional requirements! The work of Imai and Kanaoka (2018) in [21] confirmed that, by studying the actual vulnerable code that is used widely from Stack Overflow. Motivating developers to learn security is a rather challenging task. Weir et al. (2016) call for ‘fun security learning’ in their work in [22], which shares the same opinion of Boopathi et al. (2015)  [23] that fun security learning is an effective method for cyber-security education. The work in  [22] suggests the use of techniques from other domains to motivate app developers to learn security. Techniques include games that teach and story-telling. The idea of using games to teach security is interesting. Tillmann et al. (2014) were the first to call for gamifying programming learning in their work in [24]. They proposed Code-Hunt (https://www.microsoft.com/en-us/research/project/code-hunt/ accessed 03.03.2020); a game that teaches general programming skills. Denning et al. (2013), in their work in [25], designed and implemented a card game to teach developers security. Although there were no developer’s interviews, the application is distributed to 150 educators who used the app with their students. How much computer science students reflect genuinely the state of professional developers is a question that has been indeed discussed by Acar et al. (2016) in [5]. For those interested in reading about gamifying security training, the suggestion is to read the M.Sc. thesis of Rieff (2018) in [26].

While most of API usability studies focus on a qualitative analysis approach based on some defined guidelines and usability attributes, Rama and Kak (2015) in [8] take a quantitative approach, proposing eight novel metrics of analysing API usability based on nine structural measures. These nine structural measures represent issues with practical relevance and cover topics such as inconsistencies in function definitions, unmanageable function argument lists, failure to correctly group and name functions, problems related to concurrency and exception handling and poor documentation. Green and Smith (2016) in [27] suggest ten principles for designing usable security APIs. Although their focus is on cryptographic APIs, most of their suggested principles apply equally well to other security APIs. Lo Iacono and Gorski (2017) in [28] note that most of the research investigating the APIs’ usability of security is related to cryptography. They point out that security APIs include more than cryptographic APIs. Consequently, they suggest a classification scheme to structure the field of security APIs and use that classification scheme in two other studies. The conclusion of this work is that further research is needed for the various types of security APIs. Mosqueira-Rey et al. (2018) in [29] propose a new set of usability heuristics and guidelines, some of which they synthesised and refined from existing literature. The presented heuristics and guidelines form a conclusive classification scheme that can be used to analyse the usability of APIs. After they conducted a study to evaluate their usability taxonomy, Mosqueira-Rey et al. (2018) concluded that the existing literature on API usability, while somewhat complementary, is not entirely complete. They pointed out that quantitative analysis of API usability must be complemented with qualitative analysis, as usability is not entirely objective. That is why Cognitive Walkthrough is, sometimes, used to evaluate certain usability attributes [30].

There exists only little developer-centric literature about Bitcoin, and most of it is not academic. Antonopoulos (2017) in [31] describes how to build Bitcoin Core, discusses the reference Bitcoin implementation, provides some information about how to use the JSON-RPC API and presents most of Bitcoin’s core technical aspects from a developer’s point of view. A comprehensive resource about Bitcoin Core development with a detailed description of its technical internals is Bitcoin official website (https://Bitcoin.org/en/ accessed 03.03.2020). Some information about how to use Libbitcoin can also be found in [31]. Additionally, Libbitcoin’s GitHub project Wiki provides code examples and other developer’s documentation (https://github.com/Libbitcoin/Libbitcoin/wiki accessed 03.03.2020).

According to Yli-Huumo et al. (2016) in [32], there did not exist any research on the usability of Bitcoin from a developer’s perspective by 2016, although the unfriendly nature of Bitcoin’s API has been noted by Meva (2016) in [33]. Unfortunately, the difficulty of using Bitcoin APIs had not yet been addressed academically. This situation does not seem to have changed since Yli-Huumo et al. (2016) published their study. However, there exists a growing body of research unrelated to Bitcoin that covers aspects related to this paper. Table 1 summarises the major academic pieces of work that are related to the API usability, APIs usable security, API usability heuristics and guidelines, API misuse detection and so forth. As far as the researchers of this paper know, and based on Table 1, there has been no previous work to investigate the security usability of Bitcoin’s APIs. We have also categorised those workpieces in Table 2. It is worth noting that Table 2 categorises those related workpieces to the general security usability from a developer’s perspective, not just the APIs. The categories are:

• Behavioural, which studies the behavioural practices of the software developers in developing secure code. This includes the following subcategories:

  (a)

  Security Learning, which covers the research done investigating the existing security learning methods and resources available.  

  (b)

  Perception that studies what the developers think about secure coding and security in general. 

  (c)

  Development Processes, which investigate the available techniques to help developers improve code security.

• Programming, which studies the programming practices of the software developers concerning secure coding. This includes the following subcategories:

  (a)

  Languages that either surveys existing literature or proposing new secure programming languages. 

  (b)

  Tools that are used in security assurance mainly to help the software developers writing secure code. 

  (c)

  Implementation Choices, which investigates the reasons for software developer’s bad coding behaviour and the bad design decisions developers take that affect the security of their applications.

As this research is focused more on the tools category, other categories are outside the scope of this work. Professional software developers usually select a programming language to use on the basis of its fitness for the task at hand. Furthermore, software developers often have certain programming language preferences. Some software developers, for example, prefer to use a language with which they are familiar. Others prefer to use new or hip languages. This project looks at Bitcoin APIs. Unlike other security APIs, such as cryptography APIs, for example (i.e., the workstream of Yasemin Acar, such as the one in [2]), there are not many programming languages with more than one well-maintained Bitcoin implementation. Instead, there are typically only one or two maintained Bitcoin libraries per programming language. This paper evaluates the API usability of Libbitcoin (https://github.com/Libbitcoin accessed 03.03.2020), an actively maintained open-source Bitcoin implementation that is written in the C++ programming language. Unlike Bitcoin Core (https://github.com/Bitcoin/Bitcoin accessed 03.03.2020), Libbitcoin is intended to be used as a software library.

It is worth noting that the academic literature reports a couple of tools such as SmartCheck [34], Slither [35] and the work of Ye et al. (2020) in [36] that support the verification of smart contracts (i.e., based on Ethereum). However, it fails to show or provide software developers with static analysis tools to verify Bitcoin API’s security usability. We suggest the reader go through the work of Grishchenko et al. (2018) in [37] and the work of Liu and Liu (2019) in [38] for more information about the security verification of Blockchain smart contracts, which is beyond the scope of this paper.

Table 1. Related work comparison.

Work	Aim	Related to API Usability	Related to Security APIs	Usability Heuristics and Guidelines	Detect API Misuse	Tools to Detect Misuse
[39]	programmers perception on app security responsibility	∘	•	∘	∘	∘
[40]	how developers use the static code analysis tools	∘	∘	∘	∘	•
[41]	automatic detection of API usability Problems	•	∘	∘	•	•
[42]	API new usage rules fixing security problems	•	•	∘	•	•
[43]	Relation between developer experience and personality traits and API misuse	•	•	∘	∘	∘
[44]	Identify API usability issues of SCrypt implementation	•	•	∘	•	∘
[45]	platform providing examples on the correct use of crypto APIs	•	•	∘	∘	∘
[46]	Usability evaluation of Rust cryptographic libraries	•	•	∘	•	∘
[29]	Categorisation of API usability heuristics	•	∘	•	•	∘
[47]	Tool to help developers correctly use crypto API	∘	•	∘	∘	•
[2]	Usability evaluation of Python cryptographic libraries	•	•	∘	∘	∘
[48]	How to conduct developer security usability studies?	•	∘	∘	∘	∘
[49]	Security and usability impact of using immutability	•	∘	∘	∘	∘
[17]	How does API usability relate to software developers handling passwords securely?	•	•	∘	∘	∘
[28]	Classification of security APIs	•	•	∘	∘	∘
[50]	What obstacles do developers face when using Java crypto APIs?	•	•	∘	∘	⊙
[51]	Is it possible to create security libraries that are easy to use?	•	•	∘	∘	∘
[52]	A static code analysis tool to detect security vulnerabilities in PHP applications	∘	∘	∘	∘	•
[53]	A tool to detect and repair cryptographic misuse on bytecode level	⊙	•	∘	•	•
[27]	developer-friendly security by increasing usability	•	•	⊙	∘	∘
[54]	Suggestion for semantic crypto API offering better usability	•	•	∘	∘	∘
[3]	Why API usability is important, especially for security	•	•	∘	∘	∘
[55]	Suggestion for semantic crypto API offering better usability	•	•	∘	∘	∘
[18]	Suggestions for improving usable security for developers research	•	•	∘	∘	∘
[56]	Detailed analysis of the current state of API usability	•	•	⊙	∘	∘
[8]	Definition of metric for the quantitative analysis of API usability	•	∘	∘	⊙	∘
[57]	Development of a code completion tool to improve API usability	•	∘	∘	∘	•
[58]	cryptographic libraries usability and a new tool to identify misuses	•	•	∘	•	•
[16]	Design of an empirical study for assessing API usability	•	∘	∘	∘	∘
[59]	Analysis and detection of crypto API misuse in Android apps	•	•	∘	•	•

•: Covered by the work; ∘: Not covered by the work; ⊙: Partially covered by the work.

Table 1. Related work comparison.

Work	Aim	Related to API Usability	Related to Security APIs	Usability Heuristics and Guidelines	Detect API Misuse	Tools to Detect Misuse
[39]	programmers perception on app security responsibility	∘	•	∘	∘	∘
[40]	how developers use the static code analysis tools	∘	∘	∘	∘	•
[41]	automatic detection of API usability Problems	•	∘	∘	•	•
[42]	API new usage rules fixing security problems	•	•	∘	•	•
[43]	Relation between developer experience and personality traits and API misuse	•	•	∘	∘	∘
[44]	Identify API usability issues of SCrypt implementation	•	•	∘	•	∘
[45]	platform providing examples on the correct use of crypto APIs	•	•	∘	∘	∘
[46]	Usability evaluation of Rust cryptographic libraries	•	•	∘	•	∘
[29]	Categorisation of API usability heuristics	•	∘	•	•	∘
[47]	Tool to help developers correctly use crypto API	∘	•	∘	∘	•
[2]	Usability evaluation of Python cryptographic libraries	•	•	∘	∘	∘
[48]	How to conduct developer security usability studies?	•	∘	∘	∘	∘
[49]	Security and usability impact of using immutability	•	∘	∘	∘	∘
[17]	How does API usability relate to software developers handling passwords securely?	•	•	∘	∘	∘
[28]	Classification of security APIs	•	•	∘	∘	∘
[50]	What obstacles do developers face when using Java crypto APIs?	•	•	∘	∘	⊙
[51]	Is it possible to create security libraries that are easy to use?	•	•	∘	∘	∘
[52]	A static code analysis tool to detect security vulnerabilities in PHP applications	∘	∘	∘	∘	•
[53]	A tool to detect and repair cryptographic misuse on bytecode level	⊙	•	∘	•	•
[27]	developer-friendly security by increasing usability	•	•	⊙	∘	∘
[54]	Suggestion for semantic crypto API offering better usability	•	•	∘	∘	∘
[3]	Why API usability is important, especially for security	•	•	∘	∘	∘
[55]	Suggestion for semantic crypto API offering better usability	•	•	∘	∘	∘
[18]	Suggestions for improving usable security for developers research	•	•	∘	∘	∘
[56]	Detailed analysis of the current state of API usability	•	•	⊙	∘	∘
[8]	Definition of metric for the quantitative analysis of API usability	•	∘	∘	⊙	∘
[57]	Development of a code completion tool to improve API usability	•	∘	∘	∘	•
[58]	cryptographic libraries usability and a new tool to identify misuses	•	•	∘	•	•
[16]	Design of an empirical study for assessing API usability	•	∘	∘	∘	∘
[59]	Analysis and detection of crypto API misuse in Android apps	•	•	∘	•	•

•: Covered by the work; ∘: Not covered by the work; ⊙: Partially covered by the work.

Table 2. Individual study categories.

Usable Security Research Spectrum
Class	Category	Concept	Proposals
Behavioural	Learning	Information Source Impact	[18,19,20,21,45,60,61,62,63,64,65]
		Gaming	[22,24,25,66]
	Perception	Carelessness	[17,22,65]
		Organisational Support	[67,68,69,70,71]
		Complexity	[17,43,48,65,71,72,73,74,75,76]
	Development Processes	Secure SDLC	[76,77,78,79,80,81,82,83,84]
		Dialectic & Comm.	[22,62,85]
		Code Auto-generation	[46,66,86]
Programming	Libraries& APIs	Cryptography	[2,27,42,46,50,87,88,89,90,90]
		Semantic APIs	[42,54,55]
		Improving Usability	[3,18,27,44,91,92,93]
	Languages	Secure Programming Language	[94,95,96,97,98,99,100,101]
		Language Extensions	[102]
		Comparative Analysis	[2,103,104,105,106,107]
	Tools	Security Assurance	[9,10,40,41,52,63,74,108,109,110,111,112,113,114,115]
		IDE Integration	[47,66,73,86,91,109,116,117,118,119,120,121,122,123,124]
		Adoption Factors	[11,43,49,109,124,125,126,127,128,129,130,131,132,133,134,135]
	Implementation Choices	Code Smell	[136,137]
		Security Errors Reasons	[17,44,73,75,87,88,138,139,140,141,142]

Table 2. Individual study categories.

Usable Security Research Spectrum
Class	Category	Concept	Proposals
Behavioural	Learning	Information Source Impact	[18,19,20,21,45,60,61,62,63,64,65]
		Gaming	[22,24,25,66]
	Perception	Carelessness	[17,22,65]
		Organisational Support	[67,68,69,70,71]
		Complexity	[17,43,48,65,71,72,73,74,75,76]
	Development Processes	Secure SDLC	[76,77,78,79,80,81,82,83,84]
		Dialectic & Comm.	[22,62,85]
		Code Auto-generation	[46,66,86]
Programming	Libraries& APIs	Cryptography	[2,27,42,46,50,87,88,89,90,90]
		Semantic APIs	[42,54,55]
		Improving Usability	[3,18,27,44,91,92,93]
	Languages	Secure Programming Language	[94,95,96,97,98,99,100,101]
		Language Extensions	[102]
		Comparative Analysis	[2,103,104,105,106,107]
	Tools	Security Assurance	[9,10,40,41,52,63,74,108,109,110,111,112,113,114,115]
		IDE Integration	[47,66,73,86,91,109,116,117,118,119,120,121,122,123,124]
		Adoption Factors	[11,43,49,109,124,125,126,127,128,129,130,131,132,133,134,135]
	Implementation Choices	Code Smell	[136,137]
		Security Errors Reasons	[17,44,73,75,87,88,138,139,140,141,142]

4. The Proposal: The Two Static Analysis Tools

For an initial evaluation of the API usability of the selected Bitcoin libraries and implementations, the process suggested by Mosqueira-Rey et al. (2018) in [29] is followed, which falls under knowability, robustness and safety. The reason to adopt Mosquera-Rey’s work is the inclusiveness of the proposed heuristics and the ability to be used for Bitcoin’s APIs to evaluate its security usability. Unlike, for example, the generic methodology of Wijayarathna and Arachchilage (2018) in [143] and that of Grill’s et al. (2012) in [144], the latter work represents a mature stream of research in Human–Computer Interaction that dates back to the ’90s (i.e., Nielsen’s “heuristic evaluation” guidelines in [145]). The work of Zibran (2008) in [15] has also proposed 22 API usability factors solely on the basis of surveying the literature and “there is no indication of [the] relative significance of one factor over another” [4]. Tools such as StopMotion [41] have a limited scope of identifying general API usability problems by contrasting committed code at file-level for successive changes. It is worth emphasising that a comprehensive list of low-level API security usability heuristics are still missing.

In this research, the various Libbitcoin’s APIs are compared against the heuristics defined in that work, then each API function is categorised according to one of the following classifications. Yes (•): The heuristic is fulfilled, Partially (⊙): The heuristic is partially fulfilled (e.g., some of the guidelines were followed while others are missing), and No (∘): The heuristic is not fulfilled. This API comparative analysis is done through the proposed static analysis tools as well as the Cognitive Walkthrough method mentioned earlier. Reliable source code analysis, done independently from the chosen programming language, relies on a language parser that recognises the language’s syntax. The parser’s input is a source code file, and its output is some form of intermediate representation, typically an Abstract Syntax Tree (AST). Tools can then either analyse the AST to generate diagnostic output or change the AST and feed it to a pretty-printer as a way to automate code refactoring [146]). In this research, we used a Clang-based C++ tool. Clang provides three methods for building tools that make use of Clang’s parsing functionality. First, there is LibClang, a C interface library that can be used from other tools and programming languages other than C++. A second option is Clang Plugins, which allow integrating additional functionality into the C++ build process. Finally, there is LibTooling. LibTooling allows building standalone tools that have full access to the parsed AST. Having said that, two C++ static code analysis tools are implemented in this research using the Clang’s LibTooling library for parsing and analysing the ASTs of C++ programs and could be found on Github (https://github.com/phitsc/check-cpp-api accessed 03.03.2020 https://github.com/phitsc/find-api-usage accessed 03.03.2020). The tools are:

• $check-cpp-api$, which checks C++ applications for violations of the API heuristics and guidelines we highlighted before. The tool could be used on a single.cpp file as follows [147]:
      ./check-cpp-api -p ./build ./main.cpp
  Or, it can process all files in a directory by calling:
      find ./Libbitcoin/src/
          -name *.cpp
          -exec ./check-cpp-api
              -kc-1-1-case-type=snake
              -p ./Libbitcoin/build {} +
• $find-api-usage$, which supports finding the best usage of those identified problematic APIs issues by $check-cpp-api$. It could be used as follows:
      ./find-api-usage
          -p Libbitcoin/build
          -fc script::is_valid
          Libbitcoin/src/chain/input.cpp

It is worth noting that while all development and testing were done on a Linux environment, no platform-specific functionality was used. Thus, building and running both tools on other platforms for which Clang is available should, therefore, be straightforward. However, the availability of a compilation database is required. To facilitate the development of these tools and help to automate the build process, a Docker (https://www.docker.com/ accessed 03.03.2020) environment, paired with some Bash and Python scripts, were developed.

$check-cpp-api$ currently provides checks for the following Mosqueira-Rey et al. (2018) guidelines [29]:

• $KCE-1-1$ Avoid cryptographic names and abbreviations. The current implementation checks for the use of abbreviations in function names by checking whether the function being processed ends with a fixed number of often-used abbreviations in a custom dictionary.
• $KCE-2-2$ Use enumerations instead of booleans for options. The current implementation checks whether the function being processed has any arguments of boolean type.
• $KC-1-1$ Use consistent naming. The current implementation verifies whether every function name adheres to the specified naming convention, which can be either of Hungarian (i.e., nSomeNumber), Camel Case (i.e., thisIsCamelCase), Pascal Case (i.e., ThisIsPascalCase) or Snake Case (i.e., this_is_snake_case).
• $KC-1-2$ Use consistent parameter ordering. The current implementation verifies that in- and out-parameters are not intermixed, i.e., that all in-parameters come before all out-parameters or vice verse.
• $KM-1-1$ Prefer short function names. The current implementation checks that the lengths of all function names are below a specified or a predefined number of characters. The default length used is 40 characters.
• $KM-1-2$ Avoid functions with many parameters. The current implementation checks that the number of parameters of each function is below a specified or predefined value. The default value used is six parameters.
• $KM-1-3$ Avoid functions with many consecutive parameters of the same type. The current implementation, for each function, counts the number of consecutive parameters with the same type and reports occurrences where that number is larger than a specified or predefined value (i.e., threshold). The default value used is three consecutive parameters with the same type.
• $RU-2-1$ Prefer standard over exceptional processing by using optional return values. The current implementation reports all functions that have both a boolean return type and one or more out-parameters.

The Specifications and Design Objectives

Based on our research, as demonstrated in

Table 3. Static analysis tools: design objectives.

Objective	Proposals
Reducing No. of Alarms	[11,109,124,130,131,132,133]
Code Auto-generation	[47,66,86,91,148]
Focusing on limited vulnerabilities	[116,123,149,150,151]
IDE Integration	[66,73,86,91,117,118,119,120,121,122]

, the current static analysis tools’ design objectives are:

• Improving the alarm system by, for example, reducing false-positives or narrowing down the scope to only those actionable warnings.
• Auto-generation of secure code. Some tools are going the extra mile to correct the existing code or to auto-generate secure code for specific tasks.
• Some tools are focusing on a specific set of code vulnerabilities to make sure that the list of warnings is actionable. Since the scope of this research is centred around the security usability of current Bitcoin’s APIs, our work (i.e., the tools we propose here) falls under this category of design objectives.
• IDE Integration. Those tools are fully integrated into IDEs facilitating, on the spot, the identification of possible security usability problems.

Our proposal (i.e., $check-cpp-api$ and $find-api-usage$), although targeting a special set of API vulnerabilities related to Bitcoin, has the vision of supporting IDE integration and auto code generation. However, those two functions have not been fully implemented yet and are considered part of this paper’s future work.

An essential architectural characteristic of static code analysis tools is extensibility, where it should be straightforward to add additional checks or remove deprecated ones. This flexibility can be achieved with a generic object model that allows executing checks seamlessly. The class diagram depicted in Figure 2 presents the proposed static analysis tools’ classes and their relationships to provide such extensibility. It is worth noting that both tools are based on LibTooling’s ClangTool class. On the execution of the ClangTool::run method, the tools start analysing the source files passed as program arguments. Once the instantiated MatchFinder object finds a match, it executes the run method on the registered MatchFinder::MatchCallback object, passing the matched AST subtree as an argument. In our case, this is the HeuristicCheckAction::run method, which then executes the Heuristic::check method on all registered heuristics. The Heuristic::check methods, in turn, execute all Guideline::check methods of the Guideline objects registered on their related Heuristic object. Finally, the HeuristicCheckAction::run method prints all failed checks to the console or exports them to a file in a structured file format for further processing. Since all checks may require access to certain specified command-line options, an Options object is passed through the whole call-chain.

5. Evaluation of the Results

In this subsection, we evaluate two overly important points; firstly, as

Table 4. Libbitcoin API usability.

	Guidelines
Covered by this work	KCE-1, KCS-2, KCF-2, KC-1, KC-2, KM-1, KM-2, RU-2, SUC-1
Partially covered by this work	KCE-2, KHS-1, KHS-3, KHS-5, RU-1, RU-3
Not covered by this work	KHS-4, SUA-1

shows, how Libbitcoin complies with the API usability heuristics defined before by Mosqueira-Rey et al. (2018). This is simply accomplished by investigating the source code of Libbitcoin, using a hybrid of automated and Cognitive Walkthrough methodologies. A detailed assessment of Libbitcoin APIs’ usability follows in the following subsections. These assessments are based on the source code, in-code API documentation (if any) and any additional official API documentation. Only those API methods and functions with public accessibility were considered for this evaluation. The tools used for the evaluation include the standard Linux tools such as $find$ and $grep$, the code searching tool $ag$ (i.e., The Silver Searcher (https://github.com/ggreer/the_silver_searcher accessed 03.03.2020)) and the $check-cpp-api$ tool developed in this paper. Secondly, we assess the API utilisation in existing open-source projects to investigate how software developers utilise those APIs in their code.

5.1. Libbitcoin APIs: Evaluation

The Libbitcoin libraries are available on GitHub (https://github.com/Libbitcoin/ accessed 03.03.2020). The developer’s documentation can be found on Libbitcoin’s Wiki page. This evaluation is based on those Libbitcoin Git repositories. Running Tokei (https://github.com/Aaronepower/tokei accessed 03.03.2020) on those repositories results in a total of 1393 C++ source and header files and 169689 physical lines of C++ source code. The 88679 of these physical C++ lines of source code belong to the foundation Libbitcoin library, which was renamed to Libbitcoin-system shortly after this evaluation had been concluded. It is worth mentioning that some of the below evaluation uses the Cognitive Walkthrough methodology of Callaghan (2010) in [30], where the authors of the paper “walk through” the Libbitcoin’s code line by line to gain an understanding of the library concerning the heuristic under investigation.

KCE-1 Names should be self-explanatory

Using the Cognitive Walkthrough methodology shows that Libbitcoin’s API uses expressive function names that, mostly, avoid the use of abbreviations. While the use of abbreviations such as multisig (i.e., Multisignature) is domain terminology and, therefore, is sensible to use, the use of min_version and max_version in $message/alert\_payload.hpp$ or maxmoney in $Bitcoin/settings.hpp$ is slightly inconsistent compared to the ‘minimum’ and ‘maximum’ used in other parts of the API.

KCE-2 Data types should be as specific as possible to make the code more readable

The choice of data types is exemplary in Libbitcoin. The object model is well defined, with dedicated types for each entity. The numeric data types used have a predefined bit width. The standard C++ data types and classes are used appropriately. However, the boolean flags are used plentifully throughout the API (see Listing 1). The meanings of the boolean flags are difficult to remember, making it necessary to regularly look up their purpose in the documentation. This is a usability problem.

Listing 1.check-cpp-api output for KCE-2 heuristic (truncated).

> find Libbitcoin-all -name ’*.hpp’   -exec check-cpp-api   -kc-1-1-case-type=snake {} +   | grep KCE-2 .../Bitcoin/chain/block.hpp:93:   KCE-2-2: boolean parameter .../Bitcoin/chain/header.hpp:109:   KCE-2-2: boolean parameter .../Bitcoin/chain/input.hpp:90:   KCE-2-2: boolean parameter ...

To investigate this usability problem further, Listing 2 shows one of the Libbitcoin’s functions that uses a boolean flag. As one can see in Listing 3, the same function could be made more expressive using an enumeration. Finally, Listing 4 contrasts the usage of these two functions illustrating the usability advantage of using enumerations for flags, compared to boolean values, as suggested by our tools.

Listing 2. Boolean flag used in parse_signature in math/elliptic_curve.hpp.

BC_API bool parse_signature(   ec_signature& out,   const der_signature& der_signature,   bool strict);

Listing 3. Hypothetical parse_signature using an enumeration.

enum class der_enforcement {   lax,   strict };   BC_API bool parse_signature(   ec_signature& out,   const der_signature& der_signature,   der_enforcement der_enforcement);

Listing 4. Using boolean vs. enumeration for flags.

// true: lax or strict? parse_signature(ec_sig, der_sig, true);   parse_signature(ec_sig, der_sig,   der_enforcement::strict);

KCS-2 When reading code that uses the API, it should be easy to understand what that code does

We observe that although Libbitcoin does not support the chaining of methods, this does not adversely affect the readability of Libbitcoin’s code. Libbitcoin code is easy to read because its types, methods and functions are meaningfully and consistently named. In Libbitcoin’s codebase, there is a slight majority of positive over negative conditionals. Furthermore, Libbitcoin seems to adhere to C++ standard conventions as much as possible, which makes its code easy to read for anyone who is familiar with modern C++ code.

KCF-2 Functions should perform only the tasks described in their names

One of the guidelines in KCF-2 suggests that methods should not have side effects. One instance of side effects in C++ is methods that change the parameterised object(s) [152]. C++ offers the const qualifier to tell both the compiler and the users of an API that particular methods are free of side effects (i.e., that their execution will not change the observable state of their related objects). Libbitcoin uses const meticulously in method declarations. All property accessors and predicate methods (i.e., methods starting with is_ and has_) are const-qualified. The same is true for other methods whose names indicate that they should not influence an object’s state.

KC-1 The API should be consistent with itself

Libbitcoin’s naming is mostly consistent. The snake case naming convention is consistently used. Parameters seem to be consistently ordered. Out-parameters typically appear before in-parameters in function declarations throughout Libbitcoin. In the rare instances where this is not the case, such as with some of the network_address methods in $message/network\_address.hpp$, the deviation is consistent. However, a few API inconsistencies do exist. Errors, for example, are not handled consistently throughout the whole codebase. Some functions use a boolean return value to indicate success/failure of a function, as shown in Listing 5, while others return a failure code, as seen in Listing 6, and yet others might throw an exception, as seen in Listing 7.

Listing 5.decode_base58 in f ormats/base_58.hpp.

BC_API bool decode_base58(   data_chunk& out,   const std::string& in);

Listing 6. Some of block’s methods return an error code in chain/block.hpp.

code accept_transactions(   const chain_state& state) const; code connect() const; code connect(   const chain_state& state) const; code connect_transactions(   const chain_state& state) const;

Listing 7.to_utf8 throws an exception in unicode/unicode.cpp.

size_t to_utf8(char out[], size_t out_bytes,   const wchar_t in[], size_t in_chars) {   ...   if (bytes > out_bytes)     throw std::ios_base::failure(       ‘‘utf8 buffer is too small’’);     return bytes; }

Additionally, some objects can be in an invalid state. While most of these objects provide an is_valid method (e.g., chain::header in $chain/header.hpp$), others overload operator bool (e.g., wallet::stealthaddress in $wallet/stealth\_address.hpp$).

KC-2 The API should be consistent with standard conventions

The standard C++ language does not prescribe any standard for formatting code or naming entities. However, some naming and formatting standards have been established. In any case, a good recommendation is to be consistent within a codebase with a specific standard that has been chosen [153]. Libbitcoin mostly adheres to this recommendation. Property accessors mostly use the property/set_property naming convention. In-parameters are passed by value for simple types, constant reference for complex types, or rvalue-reference for consumed parameters. The out-parameters are passed by reference. Non-static property accessors for querying property values (i.e., getters) and predicates (i.e., is_) are properly qualified with the const keyword in most cases. While a few minor inconsistencies do exist, they look like oversights rather than deliberate deviations. The BC_PROPERTY_GET_REF macro defined in $config/printer.hpp$ results in property getters with a get_ prefix (instead of no prefix) and without the const qualifier. The BC_PROPERTY macro defined in $config/parameter.hpp$ also results in property getters with a get_ prefix. However, this macro does apply the const qualifier to the resulting property accessors. Further examples are the use of pass by constant value in the header_organizer constructor in $organizers/header\_organizer.hpp$ or the pass by value instead of pass by constant reference of data_slice in most of the APIs.

KM-1 The API should be easy to remember

Mosqueira-Rey et al. (2018) in [29] suggest that methods should not have long names. However, neither Mosqueira-Rey et al. (2018) nor the sources they reference for that guideline provide a concrete value of a sensible maximum length for method names. The work of Scheller and Kühn in [153] on page 15, which Mosqueira-Rey et al. (2018) reference for that guideline, suggests that “the length of names does not have a significant impact on usability”. The example name that was given by Mosqueira-Rey et al. (2018) for that guideline seems difficult, long and does not make much sense. The longest methods in Libbitcoin’s public API are is_pay_witness_script_hash_pattern in $chain/script.hpp$, transaction_pool_fetch_transaction, transaction_pool_fetch_transaction2, blockchain_fetch_transaction_index, and block-chain_fetch_unspent_outputs in $client/obelisk\_client.hpp$. The names of those functions are expressive and consistent with the names of other, similar functions, and should, therefore, be easy to remember despite their length.

It should be easier to remember how to use functions with fewer parameters compared to ones that have many parameters. The suggestion is to aim for four parameters or fewer, which seems a reasonable number to aim for but not a real hard limit [29]. This study assumes at most six parameters to be a good compromise between usability and practicability. The method with the most parameters in Libbitcoin is the version constructor in $message/version.hpp$, which requires nine arguments. There are two functions in Libbitcoin’s public API. with eight parameters each, namely check_signature and create_endorsement in $chain/script.hpp$, both of which have eight parameters but require only six (i.e., the last two are optional parameters with default arguments). Three functions take seven arguments, including get_map in $chain/chain\_state.hpp$, the program constructor in $machine/program.hpp$, create_key_pair in $wallet/encrypted\_keys.hpp$. The program constructor accepts one optional argument and create_key_pair is commented to be deprecated.

Confusing arguments of the same data type can be particularly unsafe. Normally, compilers cannot detect such mistakes. Preconditions could be used as a countermeasure provided that the values of the concerned parameters do not overlap. What is more likely, however, is that arguments that are passed in the wrong order manifest as run-time errors. In the worst case, mixed up arguments having the same data type exhibit no errors. Instead, they make the application behave in a correct but undesired way. This study, therefore, investigates whether Libbitcoin had any APIs accepting more than three consecutive arguments with the same data type. Libbitcoin has only a single such function in its public API, namely the block_database constructor in $databases/block\_database.hpp$, which has four consecutive parameters of type path, followed by two parameters of type size_t. Listing 8 shows the output of check-cpp-api that was used for the above analysis.

Listing 8.check-cpp-api output for the KM-1 heuristic (truncated).

> find Libbitcoin-all -name ’*.hpp’   -exec check-cpp-api   -kc-1-1-case-type=snake {} +   | grep KM-1 .../Bitcoin/chain/chain_state.hpp:130:   KM-1-2: too many parameters .../Bitcoin/chain/chain_state.hpp:223:   KM-1-3: too many cons. params of same type .../Bitcoin/chain/script.hpp:136: KM-1-2:   too many parameters .../Bitcoin/chain/script.hpp:176: KM-1-1:   long function name ...

KM-2 The API should follow the terminology of the field

Although Libbitcoin mostly adheres to domain terminology, a few deviations do exist. The header class in $chain/header.hpp$ exhibits the Merkle property. However, the related domain terminology is Merkle Root, as can be seen in Figure 1. Naming the property merkle_root would, therefore, be more in line with Bitcoin terminology. Indeed, the block class in $chain/block.hpp$ does exhibit the two-member functions generate_merkle_root and is_valid_merkle_root, which highlights the inconsistency.

KHS-1 Every element of the API should be documented

The Libbitcoin’s source code does contain some documentation. However, that documentation cannot be considered usable API reference documentation. While some documenting comments describe the purpose of the API method, most such comments are merely brief. Furthermore, some documenting comments seem contradictory, such as the one in Listing 9. If the terminology “is set” is appropriate, then why not call the function is_set or is_fork_set?

Listing 9.chain_state::is_enabled in chain/chain_state.hpp.

// Check if the block’s fork is set bool is_enabled(     machine::rule_fork fork) const;

Although most of Libbitcoin’s source code does not use structured comment blocks usable for generating reference documentation, some of it does. It is, however, neither complete nor up-to-date. An example is shown in Listing 10. Only one of the function’s three parameters is documented. Furthermore, the parameter name in the documentation does not match the function’s actual parameter name. Additionally, although the signature is an out-parameter, it is marked ’in’ in the structured documentation comment.

Listing 10.sign_message in wallet/message.hpp.

/**  * Signs a message using deterministic  * signature.  * @param[in] out_signature The  * elements of in Bitcoin’s own  * format. This should be base64  * encoded for presentation to the user.  * @return true if wif is valid and  * signature encoding is successful.  */ BC_API bool sign_message(   message_signature& signature,   data_slice message,   const ec_private& secret);

Some API documentation has misleading parameter annotations. The @param[in] annotation in Listing 11 implies that the list parameter is an input parameter into the function (http://www.doxygen.nl/manual/commands.html accessed 03.03.2020). However, the fact that it is passed by reference, instead of by constant reference, indicates that the function might serve as both an input and an output parameter.

Listing 11.distinct in utility/collection.hpp.

/**  * Obtain the sorted distinct  * elements of the list.  * @param <Element> The list element type.  * @param[in] list The list.  * @return The sorted list reduced to  * its distinct elements.  */ template <typename Element> std::vector<Element>& distinct(     std::vector<Element>& list);

Similarly, the key parameter of find_pair_position function declared in $collection.hpp$ is annotated as an input parameter, as seen in Listing 12, but passed by reference in the function declaration. However, the function’s implementation in $collection.ipp$ accepts the key parameter by constant reference, as Listing 13 shows. The reason why this works is that the function in Listing 13, whose definition is included in $collection.hpp$ using an include statement, overloads the function with the same name in Listing 12.

Listing 12.find_pair_position declaration in utility/collection.hpp.

/**  * Find the position of a pair in an  * ordered list.  * @param  <Pair> The type of list  * member elements  * @param[in] list The list to search.  * @param[in] key The key to the element  * to find.  * @return The position or -1 if not found.  */ template <typename Pair, typename Key> int find_pair_position(   const std::vector<const Pair>& list,   Key& key);

Listing 13.find_pair_position definition in utility/collection.hpp.

template <typename Pair, typename Key> int find_pair_position(   const std::vector<Pair>& list,   const Key& key) {     const auto predicate =       [&] (const Pair& pair) {         return pair.first == key;       };     auto it = std::find_if(       list.begin(), list.end(), predicate);     if (it == list.end())       return -1;     // Unsafe for use with lists greater     // than max_int32 in size.     Bitcoin_ASSERT(list.size() <= max_int32);     return static_cast<int>(       distance(list.begin(), it)); }

We conclude that without meaningful documentation that makes it easy on developers to use the APIs, it is hard to maintain the security of the code. It is worth noting that the learning resources of security have been studied in recent years by the academic community of usable security.

KHS-3 The API should properly identify deprecated classes and methods

Libbitcoin does identify some API functions in $utility/pseudo\_random.hpp$ and some methods of the transaction class in $chain/transaction.hpp$ as deprecated. Although Libbitcoin defines the BC_DEPRECATED macro in $Bitcoin/define.hpp$ that would produce a compiler warning when a deprecated function is used, that macro is not used anywhere.

KHS-4 The API should supply helpful error information and, if possible, suggest a solution

Errors can be handled using various strategies in C++. Returning an error code and throwing exceptions are two such strategies. The Libbitcoin Wiki provides no treatment of how errors are handled within the library or how to deal with them when using the library. However, inspection of Libbitcoin’s APIs and implementation shows that Libbitcoin handles errors in three different ways. Some functions throw exceptions, some return a boolean value to indicate success or error and some return an error code. An advantage of exceptions over boolean or integer return values is that exception types already provide some information about the causes of errors/exceptions. Exceptions also make it more difficult to ignore erroneous events. However, Libbitcoin makes only little use of exceptions. Instead, it primarily relies on the returning of error codes and boolean error indications.

KHS-5 The API documentation should include code samples for the most common scenarios

Although some of Libbitcoin’s libraries contain an example directory, these directories contain only a few short examples. Libbitcoin’s Wiki provides 14 web pages with developer documentation on various topics. Additionally, 11 web pages with code examples related to the developer documentation topics are available on the Wiki. However, some of these examples use API functions that have been marked deprecated. One such example is the use of pseudo_random_fill in the $SerializedData$ example.

RU-1 The API should allow detecting and managing errors without breaking the execution or leaving the error undetected

Until C++ gets proper support for contract programming [154], the verification of pre-conditions, post-conditions and invariants are sometimes checked using the assert macro. Software developers also often use assertions to verify assumptions [155]. Libbitcoin seems to be using assertions for all these cases in various parts of the library. However, it does not do that consistently. Furthermore, in some places, assertions seem to be used inappropriately. Because assertions are not in effect in production builds, assertions should not be used to test conditions that may just as well happen in production. Listing 14 shows an assert that halts a non-production version of an application using Libbitcoin in case transaction store corruption is detected. However, the assumption is that the same condition might occur in production builds, which would lead to inconsistent results being returned.

Listing 14. Testing store corruption but only in non-production builds in inter f ace/block_chain.cpp.

block_const_ptr block_chain::get_block(   size_t height, bool witness,   bool candidate) const {   ...   const auto result =     database_.blocks().get(       height, candidate);   ...   transaction::list txs;   ...     // False implies store corruption.   DEBUG_ONLY(const auto value =)     get_transactions(       txs, result, witness);   Bitcoin_ASSERT(value);     // Use non-const header copy to   // obtain move construction for txs.     auto header = result.header();   return std::make_shared<const block>   (std::move(header),std::move(txs)); }

A questionable use of assert is to check pointer variables before they are dereferenced, as can be found in Libbitcoin in a small number of cases. Listing 15 shows one such example.

Listing 15. Dereferencing a pointer variable that might be a nullptr in pools/header_entry.cpp.

// Not callable if the entry is // a search key const hash_digest& header_entry::                    parent() const {     Bitcoin_ASSERT(header_);     return header_->previous_block_hash(); }

Because Libbitcoin libraries are programmed in C++, the use of most data types will be checked at compilation time rather than at run-time. Libbitcoin also uses enum class in many but not all cases. enum class was introduced in C++ 11 (http://www.stroustrup.com/C++11FAQ.html#enum accessed 03.03.2020) to improve the type safety of enumerated types.

RU-2 The API should facilitate managing non-common but correct situations without generating exceptions or forcing users to catch them

Although Listing 16 might suggest that there is potential for using optional return values in Libbitcoin, most of them would not be particularly beneficial. There are only a few cases in the Libbitcoin APIs where an optional value could be used instead of using the combination of an out-parameter and a boolean return value indicating success or failure. However, all of them are used to handle exceptional situations where continuing on the standard program path makes no sense. While the use of std::optional may offer some slight advantage over a combination of the boolean return value and out-parameter, such as, for example, the possibility to make the returned value constant, it does not simplify the client code significantly.

Listing 16.check-cpp-api output for the RU-2 heuristic (truncated).

> find Libbitcoin-all -name ’*.hpp’   -exec check-cpp-api   -kc-1-1-case-type=snake {} +   | grep RU-2 .../Bitcoin/chain/block.hpp:98:   RU-2: omission to use optional? .../Bitcoin/chain/block.hpp:99:   RU-2: omission to use optional? .../Bitcoin/chain/compact.hpp:51:   RU-2: omission to use optional? .../Bitcoin/chain/header.hpp:113:   RU-2: omission to use optional? ...

RU-3 The API should not expose vulnerabilities that would allow users to make errors

While Libbitcoin seems to handle element accessibility purposefully, there are some class members whose accessibility could be further restricted. Various classes have protected methods, e.g., operation in $machine/operation.hpp$ or chain_state in $chain/chain\_state.hpp$, although they do not seem to be intended to serve as base classes. Sometimes compiler bugs mandate certain members to be protected although they could be private from a language point of view. However, such cases should visibly be documented in the code. Another case where accessibility should be further restricted is the BC_PROPERTY_GET_REF macro shown in Listing 17. The macro generates property accessors that return non-const references to private member variables, defeating the purpose of making these member variables private in the first place. The BC_PROPERTY_GET_REF macro, however, is only used in a single non-critical class of Libbitcoin.

Listing 17.BC_PROPERTY_GET_REF exposing private member by non-const reference in config/printer.hpp.

#define BC_PROPERTY_GET_REF(type, name)   public: virtual type& get_##name() {     return name##_;   }   private: type name##_

Immutability is addressed nicely in Libbitcoin’s API. For example, those methods that do not need to change their related object, such as property getters, are properly qualified with the const keyword. However, immutability could be further promoted in client code by using optional return values instead of out-parameters and boolean return values. With a boolean return value and an out-parameter, a mutable temporary variable must be created and passed into the function as Listing 18 shows. Listing 19 demonstrates how the temporary variable could be made immutable with the help of an optional return value. By doing this, an added benefit would be allowing the use of type inference which further enhances the usability of the API.

Listing 18.create_ephemeral_key returning boolean success or failure value in math/stealth.hpp.

BC_API bool create_ephemeral_key(   ec_secret& out_secret,   const data_chunk& seed); ... ec_secret ephemeral_private; if (create_ephemeral_key(       ephemeral_private, seed))   initialize(ephemeral_private,     address, seed, filter);

Listing 19. Hypothetical create_ephemeral_key alternative returning an optional value in math/stealth.hpp.

BC_API std::optional<ec_secret>   create_ephemeral_key(     const data_chunk& seed); ... if (const auto ephemeral_private =       create_ephemeral_key(seed))   initialize(*ephemeral_private,     address, seed, filter);

There are no obvious threading issues in Libbitcoin from a API usability point of view. There are also no APIs in Libbitcoin returning allocated memory that must be manually freed by a user of the API. Furthermore, neither cppcheck (http://cppcheck.sourceforge.net/ accessed 03.03.2020) nor Clang Static Analyzer (https://clang-analyzer.llvm.org/ accessed 03.03.2020) reported any memory-related issues.

SUC-1 The API should not compromise the confidentiality of the users’ personal information

Libbitcoin does not seem to acquire, store or process any personal information beyond what is necessary to fulfil its intended purpose. The sole information that could be considered personal is the one related to the wallet functionality which makes sense to use. All other data is related to the public blockchain.

SUA-1 The API should not compromise the security of the users’ assets

Not compromising the security of user assets should be a primary goal of any Bitcoin library. However, assessing whether an API constitutes a risk to user assets seems challenging when evaluating the API alone, not along with its implementation. For security-critical algorithms, including the ones related to AES, ECDSA, RIPEMD, SHA and scrypt, Libbitcoin uses external implementations. Libbitcoin provides unit tests for a lot of its code. However, the test coverage should be increased to include more error and corner cases.

5.2. Open-Source Projects: Libbitcoin APIs Evaluation

It is worth emphasising that the versification of how secure Libbitcoin’s APIs are is outside the scope of this research. Having evaluated Libbitcoin’s APIs in the previous sections, it is now time to investigate how such APIs are used in production. This subsection demonstrates the results of investigating the utilisation of Libbitcoin in the following open-source projects concerning the findings described in the previous subsections:

• https://github.com/Libbitcoin/Libbitcoin-explorer.git with Commit ID of f4dd566fbce806f3e622
• https://github.com/Libbitcoin/Libbitcoin-node.git with Commit ID of 791f5ab5ab5eb5f01b09
• https://github.com/Libbitcoin/Libbitcoin-server.git with Commit ID of 3118b3b4495cc8a94894
• https://github.com/mvs-org/metaverse.git with Commit ID of 8dec1d81fe243f6a27e1
• https://github.com/joinparty/joinparty.git with Commit ID of 258c7419dec7ee193452.

KCE-2: Boolean Flags

As pointed out before, the boolean parameters appear plentifully in the Libbitcoin library APIs. The reason why boolean flags in APIs are problematic has been already discussed.

Table 5. Usage of methods with boolean flags.

API	Libbitcoin Explorer	Libbitcoin Node	Libbitcoin Server	Metaverse	Joinparty
authenticator::apply	∘	∘	•	•	∘
block_chain::fetch_block	∘	∘	•	∘	∘
block_chain::fetch_transaction	∘	∘	•	∘	∘
block_chain::get_top	∘	•	∘	∘	∘
create_key_pair	•	∘	∘	∘	∘
decode_base10	•	∘	∘	•	∘
deserialize	•	∘	∘	•	∘
ec_private::ec_private	•	∘	∘	∘	∘
ec_public::ec_public	•	∘	∘	•	∘
initialize	•	•	•	∘	∘
parse_signature	•	∘	∘	•	•
payment_record::to_data	∘	∘	•	∘	∘
property_tree	•	∘	∘	∘	∘
script::from_data	∘	∘	∘	•	•
split	•	∘	∘	•	∘
transaction::serialized_size	∘	∘	∘	∘	•
wallet::sign_message	∘	∘	∘	∘	•

•: Used; ∘: Not Used.

lists the Libbitcoin functions that violate guideline KCE-2-2 and are used in one of the evaluated projects. This subsection describes how the evaluated projects pass boolean arguments to those functions. While using an enumeration, as described before, would often be preferable, using a meaningful named variable is the best case in the given situation. The worse, but tolerable, case is a comment at the call site indicating the meaning of the parameter. The worst cases are situations where the code surrounding the call site needs to be analysed to understand why true or false was passed to a function. The ultimate worst case is where a boolean literal is passed and software developers working on the code must look up the API documentation or an APIs implementation to understand what a boolean flag is used for.

authenticator::apply is used in heartbeat_service::bind, query_service::bind, block_service::bind and transaction_service::bind, both in Libbitcoin server (see Listing 20) and Metaverse. Each of these services is instantiated twice in server_node, once for each value of the boolean flag. While the flag’s name might make the flag’s meaning obvious enough, its apparent security-relevance suggests making it more obvious with the help of an enumeration. However, the examined usages were non-critical.

block_chain::get_top is used in full_node::handle_running in the Libbitcoin node (see Listing 21). In the evaluated code, the flag’s meaning is made obvious through the naming of the additional parameter passed to block_chain::get_top. block_chain::fetch_block is used in blockchain::fetch_block_by_hash and blockchain::fetch_block_by_height in Libbitcoin server, as well as in protocol_block_out::send_next_data of Libbitcoin node. The fetch_block method of the safe_chain class, which block_chain derives from, is used both in the Libbitcoin server and the Libbitcoin node. In the Libbitcoin server, the flag’s meaning is made obvious with the help of an appropriately named local variable whose value is calculated right before block_chain::fetch_block is executed. In the Libbitcoin node, boolean literals are passed whose purpose can merely be derived from the case label related to the blocks the methods are called in.

Listing 20. Usages of authenticator::apply in the Libbitcoin server (truncated).

> find Libbitcoin-server -name ’*.cpp’   -exec find-api-usage   -function-call=’authenticator::apply’   {} + .../src/services/query_service.cpp:88:   this->authenticator_.apply(router,     domain, this->secure_) .../src/services/block_service.cpp:96:   this->authenticator_.apply(xpub,     domain, this->secure_) ...

Listing 21. Usages of block_chain::get_top in Libbitcoin node.

> find Libbitcoin-node -name ’*.cpp’   -exec find-api-usage   -function-call=’block_chain::get_top’   {} + .../src/full_node.cpp:117:   this->chain_.get_top(top_confirmed,     false) .../src/full_node.cpp:130:   this->chain_.get_top(top_candidate,     true)

block_chain::fetch_transaction requires two flags to be passed and is used in blockchain::fetch_transaction, blockchain::fetch_transaction1, transaction_pool::fetch_transaction and transaction_pool::fetch_transaction2 in Libbitcoin server. The meaning of the flags is merely described in the examined code through some comments above the method invocation (see Listing 22). Without consulting the method’s declaration, it is not obvious that the comment above the method invocation is related to these two boolean flags. Furthermore, comments always pose the risk of diverging with the code they describe. In the Libbitcoin node, block_chain::fetch_transaction is used in protocol_transaction_out::send_next_data with boolean literals. Again, the purpose of the boolean flags passed can merely be derived from the case label related to the blocks the methods are called in.

Listing 22. Use of boolean flags in block_chain::fetch_transaction.

/* * The response is restricted to the * confirmed transactions. * * This response excludes witness data * so as not to break old the parsers. */ node.chain().fetch_transaction(   hash, true, false,   std::bind(     &blockchain::transaction_fetched,     _1, _2, _3, _4, request, handler));

parse_signature is used in input_validate::invoke in Libbitcoin explorer, in sort_multi_sigs and signmultisigtx::invoke in Metaverse and in get_ec_signature in Joinparty. In input_validate::invoke, the flag is passed using a local variable that is initialised with a boolean literal and whose name gives a hint about its use. In both sort_multi_sigs and signmultisigtx::invoke, local variables are used that are initialised right before the function call. In get_ec_signature, a boolean literal is passed without further comment about the argument’s purpose.

In both the Libbitcoin explorer and Metaverse, the boolean flag to decode_base10 is not passed explicitly but its default value is used. In the  Libbitcoin explorer, ec_public::ec_public is used in ec_add::invoke, ec_decompress::invoke, ec_multiply::invoke, ec_to_public::invoke and ek_public_to_ec::invoke. In three cases, locally initialised and appropriately named variables are used to pass the flag. In ec_multiply::invoke, the flag is passed by calling a function that indicates the flag’s purpose. In ec_decompress::invoke, a boolean literal is passed and the class name ec_decompress is the only indication of what the flag’s purpose might be. In Metaverse, ec_public::ec_public is used in getnewaddress::invoke, which just passes a boolean literal. While there is a code comment right before the constructor call, it is not obvious that it relates to the boolean flag.

wallet::sign_message is used in get_encoded_signed_message in Joinparty. A boolean literal is passed to wallet::sign_message without any indication about the argument’s purpose. create_key_pair is used in ek_address::invoke, ek_new::invoke and commands::ek_public::invoke in Libbitcoin explorer (see Listing 23). In all three cases, a locally initialised and appropriately named variable is used to pass the flag.

Listing 23. Usages of create_key_pair in Libbitcoin explorer (truncated).

> find Libbitcoin-explorer -name ’*.cpp’   -exec find-api-usage   -function-call=’create_key_pair’   {} + .../src/commands/ek-new.cpp:49:   create_key_pair(secret, unused, ...) .../src/commands/ek-public.cpp:52:   create_key_pair(unused1, key, ...) .../src/commands/ek-address.cpp:50:   create_key_pair(unused, point, ...)

ec_private::ec_private is used in ec_to_wif::invoke in Libbitcoin explorer. A locally initialised and appropriately named variable is used to pass the flag.

Both the Libbitcoin explorer and Metaverse use deserialize in operator>> related to the byte class. In both cases, the flag is passed as a boolean literal without any further hint of what the flag’s meaning might be. In the  Libbitcoin explorer, split is only used without its flag parameter, which is initialised from its default value. Metaverse, as well, uses split with the flag’s default value into many places. However, in Metaverse, there are also multiple cases where boolean literals are explicitly passed to split. While the flag’s purpose is further commented in one case, in all other cases its meaning is not apparent.

property_tree is used in fetch_block::invoke, fetch_tx::invoke, fetch_utxo::invoke and tx_decode::invoke in Libbitcoin explorer. In all cases, a local variable is used to pass the flag, which is initialised close to the function invocation. In each case, an enumeration is used to initialise this local variable, albeit one with three possible values.

transaction::serialized_size is called in Wallet::create_and_broadcast_transaction and Wallet::create_coin_join_transaction in Joinparty. In both cases, no arguments are explicitly passed to transaction::serialized_size and the method’s default arguments are used instead. In all places where script::from_data is used in Metaverse and Joinparty, its flag option is passed as a boolean literal without any further hints about its purpose.

payment_record::to_data is used in blockchain::history_fetched and blockchain::stealth_fetched in Libbitcoin server. In both cases, the flag is passed as a boolean literal without any further hints about its purpose.

initialize, a free function related to Libbitcoin’s logging functionality. While its flag option is passed as a named local variable in both Libbitcoin node and Libbitcoin server, it is passed as a boolean literal without any further comment about its function in Libbitcoin explorer.

KC-1: Unhandled Error Results

In contrast to exceptions, boolean error results and error result codes are easier to ignore, be it on purpose or by accident. This study, therefore, examined the usage of functions and methods flagging success or failure by returning a boolean value or error code of type std::error_code (used as code in Libbitcoin with the help of a typedef).

Table 6. Functions with a boolean error result.

API	Libbitcoin Explorer	Libbitcoin Node	Libbitcoin Server	Metaverse	Joinparty
Bitcoin_uri::set_address(const std::string&)	•	∘	∘	•	∘
create_key_pair	•	∘	∘	∘	∘
create_stealth_data	∘	∘	∘	•	∘
create_token	•	∘	∘	∘	∘
decode_base10	•	∘	∘	•	∘
decode_base16	∘	∘	∘	•	•
decode_base58	•	∘	∘	•	∘
decode_base64	•	∘	∘	•	•
decrypt	•	∘	∘	∘	∘
ec_add	•	∘	∘	•	•
ec_multiply	•	∘	∘	•	•
encode_signature	∘	∘	∘	∘	•
encrypt	•	∘	∘	∘	∘
extract_ephemeral_key	∘	∘	∘	•	∘
parse_signature	∘	∘	∘	•	•
parser::get_option	•	•	•	•	∘
png::write_png	•	∘	∘	∘	∘
point::from_data	∘	∘	•	•	∘
property_tree	•	∘	∘	∘	∘
script::check_signature	•	∘	∘	•	∘
script::create_endorsement	•	∘	∘	•	•
script::from_data	∘	∘	∘	∘	•
script::verify	∘	∘	∘	∘	•
secret_to_public	•	∘	∘	•	•
sign_message	•	∘	∘	∘	•
sign	∘	∘	∘	∘	•
to_stealth_prefix	∘	∘	•	•	∘
uncover_stealth	∘	∘	∘	•	∘
verify_message	•	∘	∘	∘	∘
verify_signature	∘	∘	∘	∘	•

•: Used; ∘: Not Used.

lists some of those functions (The full set of functions is available upon request should the corresponding author is contacted) and methods of Libbitcoin’s public API that fall into this category and are used in one of the evaluated projects.

In multiple cases in the Libbitcoin explorer and Metaverse, the return value for secret_to_public is not checked. In Joinparty, the results of secret_to_public calls are always ignored. secret_to_public internally calls secp256k1_ec_pubkey_create and serialize, both of which can fail. Of the three overloads of Bitcoin_uri::set_address, only one can fail, namely, the one which is called with a std::string argument. This overload is used in the Libbitcoin explorer without checking its return value (see Listing 24).

Listing 24. Usage of Bitcoin_uri::set_address in Libbitcoin explorer.

> find Libbitcoin-explorer -name ’*.cpp’   -exec find-api-usage   -function-call=’Bitcoin_uri::set_address’   {} + .../src/commands/uri-encode.cpp:43:   uri.set_address(address)

create_key_pair, create_token, encrypt and sign_message are used in the lib-Bitcoin explorer without their return values being checked in any of the calls. sign_message is also called in Joinparty, where its return value is properly evaluated.

point::from_data is called in one instance as a call to output_point::from_data (output_point derives from point) in the Libbitcoin server and Metaverse without its return value is checked. While the result of calling decode_base160 is checked in one case in Joinparty, it is ignored in three other cases. Furthermore, none of the calls to decode_base64 in Joinparty is checked for a failed result.

parse_signature, encode_signature, ec_add, and ec_mulitply are all used in Joinparty without their return values ever being evaluated.

In the examined client applications, the return values are checked for invocations of all other functions listed in Table 6. The invocation of any API functions and methods within Libbitcoin’s libraries themselves have not been further investigated. However, doing so would be advisable, as ignored error result flags are a potential source of security-critical bugs.

KC-2/RU-3: BC_PROPERTY_GET_REF

As demonstrated before, the use of the BC_PROPERTY_GET_REF macro results in property accessors that provide write access to private member variables. However, none of the evaluated applications makes use of the property accessors defined through the BC_PROPERTY_GET_REF macro. Instead, these property accessors seem to be only used by other public API methods of Libbitcoin’s printer class. Consequently, the BC_PROPERTY_GET_REF macro should not only be changed to return a constant reference but the property accessors could even be implemented with private accessibility.

KHS-3: Deprecated Functions

Table 7. Deprecated functions.

API	Libbitcoin Explorer	Libbitcoin Node	Libbitcoin Server	Metaverse	Joinparty
transaction :: inputs() (non-const version)	•	∘	∘	∘	•
transaction :: outputs() (non-const version)	•	∘	∘	∘	•
pseudo_random()	∘	∘	∘	•	∘
ine pseudo_random(uint64_t, uint64_t)	∘	∘	•	∘	∘
pseudo_random_fill(data_chunk&)	•	∘	∘	•	•
pseudo_randomize(const asio:duration&, uint8_t)	∘	∘	∘	∘	∘
create_key_pair(encrypted_private&,encrypted_public&, ec_compressed&,...)	•	∘	∘	∘	∘
decrypt(ec_compressed&, uint8_t&, bool&, const encrypted_public&, ...)	•	∘	∘	∘	∘

•: Used; ∘: Not Used.

lists all of Libbitcoin’s functions and methods that are labelled deprecated using a comment, and which are used by some of the examined client applications. The BC_DEPRECATED macro defined in $Bitcoin/define.hpp$, which should be preferred for tagging deprecated functions, is not used anywhere in Libbitcoin. Furthermore, Mosqueira-Rey et al. (2018) suggest that deprecated API elements should have accompanying documentation explaining the reasons for the deprecation and proposing viable alternatives [29]. None of the functions listed in Table 7 has such accompanying documentation.

6. Conclusions and Future Work

This paper attempts to understand the usability issues in Bitcoin’s APIs, namely in the Libbitcoin implementation and how software developers misuse the Bitcoin APIs in their code. Libbitcoin is a well-known C++ implementation of the Bitcoin system, which has been used in this project. This paper evaluates those APIs from a security usability perspective. As far as the authors of this paper know, it is the first attempt to understand how Bitcoin’s APIs are used in open-source projects and how to avoid certain coding practices that could leave the application vulnerable to attacks. It is worth emphasising that while some research has been done on the usability of Bitcoin’s applications from an end-user’s point of view, as far as the authors of this paper know, there is no research yet that addresses usability aspects from a developer’s point of view. This work proposed two static analysis tools to identify security usability concerns and suggests resolutions for such concerns. This paper comprehensively surveyed the general academic literature concerning API usability and usable security. The findings of this research has improved Libbitcoin in many places. The paper answers questions such as “How usable are Bitcoin’s API libraries from a security preservative?”, “How would a static analysis tool help in minimising code volubility using those identified Bitcoin API libraries?” and so forth. To be able to do that, the paper attempted to study the usability issues with identified Bitcoin’s APIs, investigate the static analysis tools and how they could help to raise the awareness of Bitcoin’s software developers to avoid such usable security issues and so forth.

The future direction of this paper includes fully integrating the tool in moderns IDEs, such as Eclipse, to make it easier for the developers to identify concerns on the run and get online suggestions on how to resolve those usability/security issues. A qualitative analysis of the tools needs to be carried out by surveys and questionnaires, which requires the tools to gain some popularity in the Blockchain development community before a statistically significant response is received. One of the limitations of this study is that it focuses only on Libbitcoin’s C++ API implementation and the rest of available libraries are considered future work.