/bitcoin/src/rpc/request.cpp

Source
// Copyright (c) 2010 Satoshi Nakamoto
// Copyright (c) 2009-2022 The Bitcoin Core developers
// Distributed under the MIT software license, see the accompanying
// file COPYING or http://www.opensource.org/licenses/mit-license.php.

#include <rpc/request.h>

#include <common/args.h>
#include <logging.h>
#include <random.h>
#include <rpc/protocol.h>
#include <util/fs.h>
#include <util/fs_helpers.h>
#include <util/strencodings.h>

#include <fstream>
#include <stdexcept>
#include <string>
#include <vector>

/**
 * JSON-RPC protocol.  Bitcoin speaks version 1.0 for maximum compatibility,
 * but uses JSON-RPC 1.1/2.0 standards for parts of the 1.0 standard that were
 * unspecified (HTTP errors and contents of 'error').
 *
 * 1.0 spec: http://json-rpc.org/wiki/specification
 * 1.2 spec: http://jsonrpc.org/historical/json-rpc-over-http.html
 *
 * If the server receives a request with the JSON-RPC 2.0 marker `{"jsonrpc": "2.0"}`
 * then Bitcoin will respond with a strictly specified response.
 * It will only return an HTTP error code if an actual HTTP error is encountered
 * such as the endpoint is not found (404) or the request is not formatted correctly (500).
 * Otherwise the HTTP code is always OK (200) and RPC errors will be included in the
 * response body.
 *
 * 2.0 spec: https://www.jsonrpc.org/specification
 *
 * Also see http://www.simple-is-better.org/rpc/#differences-between-1-0-and-2-0
 */

UniValue JSONRPCRequestObj(const std::string& strMethod, const UniValue& params, const UniValue& id)
{
    UniValue request(UniValue::VOBJ);
    request.pushKV("method", strMethod);
    request.pushKV("params", params);
    request.pushKV("id", id);
    request.pushKV("jsonrpc", "2.0");
    return request;
}

UniValue JSONRPCReplyObj(UniValue result, UniValue error, std::optional<UniValue> id, JSONRPCVersion jsonrpc_version)
{
    UniValue reply(UniValue::VOBJ);
    // Add JSON-RPC version number field in v2 only.
    if (jsonrpc_version == JSONRPCVersion::V2) reply.pushKV("jsonrpc", "2.0");

    // Add both result and error fields in v1, even though one will be null.
    // Omit the null field in v2.
    if (error.isNull()) {
        reply.pushKV("result", std::move(result));
        if (jsonrpc_version == JSONRPCVersion::V1_LEGACY) reply.pushKV("error", NullUniValue);
    } else {
        if (jsonrpc_version == JSONRPCVersion::V1_LEGACY) reply.pushKV("result", NullUniValue);
        reply.pushKV("error", std::move(error));
    }
    if (id.has_value()) reply.pushKV("id", std::move(id.value()));
    return reply;
}

UniValue JSONRPCError(int code, const std::string& message)
{
    UniValue error(UniValue::VOBJ);
    error.pushKV("code", code);
    error.pushKV("message", message);
    return error;
}

/** Username used when cookie authentication is in use (arbitrary, only for
 * recognizability in debugging/logging purposes)
 */
static const std::string COOKIEAUTH_USER = "__cookie__";
/** Default name for auth cookie file */
static const char* const COOKIEAUTH_FILE = ".cookie";

/** Get name of RPC authentication cookie file */
static fs::path GetAuthCookieFile(bool temp=false)
{
    fs::path arg = gArgs.GetPathArg("-rpccookiefile", COOKIEAUTH_FILE);
    if (arg.empty()) {
        return {}; // -norpccookiefile was specified
    }
    if (temp) {
        arg += ".tmp";
    }
    return AbsPathForConfigVal(gArgs, arg);
}

static bool g_generated_cookie = false;

GenerateAuthCookieResult GenerateAuthCookie(const std::optional<fs::perms>& cookie_perms,
                                            std::string& user,
                                            std::string& pass)
{
    const size_t COOKIE_SIZE = 32;
    unsigned char rand_pwd[COOKIE_SIZE];
    GetRandBytes(rand_pwd);
    const std::string rand_pwd_hex{HexStr(rand_pwd)};

    /** the umask determines what permissions are used to create this file -
     * these are set to 0077 in common/system.cpp.
     */
    std::ofstream file;
    fs::path filepath_tmp = GetAuthCookieFile(true);
    if (filepath_tmp.empty()) {
        return GenerateAuthCookieResult::DISABLED; // -norpccookiefile
    }
    file.open(filepath_tmp);
    if (!file.is_open()) {
        LogWarning("Unable to open cookie authentication file %s for writing", fs::PathToString(filepath_tmp));
        return GenerateAuthCookieResult::ERR;
    }
    file << COOKIEAUTH_USER << ":" << rand_pwd_hex;
    file.close();

    fs::path filepath = GetAuthCookieFile(false);
    if (!RenameOver(filepath_tmp, filepath)) {
        LogWarning("Unable to rename cookie authentication file %s to %s", fs::PathToString(filepath_tmp), fs::PathToString(filepath));
        return GenerateAuthCookieResult::ERR;
    }
    if (cookie_perms) {
        std::error_code code;
        fs::permissions(filepath, cookie_perms.value(), fs::perm_options::replace, code);
        if (code) {
            LogWarning("Unable to set permissions on cookie authentication file %s", fs::PathToString(filepath));
            return GenerateAuthCookieResult::ERR;
        }
    }

    g_generated_cookie = true;
    LogInfo("Generated RPC authentication cookie %s\n", fs::PathToString(filepath));
    LogInfo("Permissions used for cookie: %s\n", PermsToSymbolicString(fs::status(filepath).permissions()));

    user = COOKIEAUTH_USER;
    pass = rand_pwd_hex;
    return GenerateAuthCookieResult::OK;
}

bool GetAuthCookie(std::string *cookie_out)
{
    std::ifstream file;
    std::string cookie;
    fs::path filepath = GetAuthCookieFile();
    if (filepath.empty()) {
        return true; // -norpccookiefile
    }
    file.open(filepath);
    if (!file.is_open())
        return false;
    std::getline(file, cookie);
    file.close();

    if (cookie_out)
        *cookie_out = cookie;
    return true;
}

void DeleteAuthCookie()
{
    try {
        if (g_generated_cookie) {
            // Delete the cookie file if it was generated by this process
            fs::remove(GetAuthCookieFile());
        }
    } catch (const fs::filesystem_error& e) {
        LogWarning("Unable to remove random auth cookie file %s: %s\n", fs::PathToString(e.path1()), e.code().message());
    }
}

std::vector<UniValue> JSONRPCProcessBatchReply(const UniValue& in)
{
    if (!in.isArray()) {
        throw std::runtime_error("Batch must be an array");
    }
    const size_t num {in.size()};
    std::vector<UniValue> batch(num);
    for (const UniValue& rec : in.getValues()) {
        if (!rec.isObject()) {
            throw std::runtime_error("Batch member must be an object");
        }
        size_t id = rec["id"].getInt<int>();
        if (id >= num) {
            throw std::runtime_error("Batch member id is larger than batch size");
        }
        batch[id] = rec;
    }
    return batch;
}

void JSONRPCRequest::parse(const UniValue& valRequest)
{
    // Parse request
    if (!valRequest.isObject())
        throw JSONRPCError(RPC_INVALID_REQUEST, "Invalid Request object");
    const UniValue& request = valRequest.get_obj();

    // Parse id now so errors from here on will have the id
    if (request.exists("id")) {
        id = request.find_value("id");
    } else {
        id = std::nullopt;
    }

    // Check for JSON-RPC 2.0 (default 1.1)
    m_json_version = JSONRPCVersion::V1_LEGACY;
    const UniValue& jsonrpc_version = request.find_value("jsonrpc");
    if (!jsonrpc_version.isNull()) {
        if (!jsonrpc_version.isStr()) {
            throw JSONRPCError(RPC_INVALID_REQUEST, "jsonrpc field must be a string");
        }
        // The "jsonrpc" key was added in the 2.0 spec, but some older documentation
        // incorrectly included {"jsonrpc":"1.0"} in a request object, so we
        // maintain that for backwards compatibility.
        if (jsonrpc_version.get_str() == "1.0") {
            m_json_version = JSONRPCVersion::V1_LEGACY;
        } else if (jsonrpc_version.get_str() == "2.0") {
            m_json_version = JSONRPCVersion::V2;
        } else {
            throw JSONRPCError(RPC_INVALID_REQUEST, "JSON-RPC version not supported");
        }
    }

    // Parse method
    const UniValue& valMethod{request.find_value("method")};
    if (valMethod.isNull())
        throw JSONRPCError(RPC_INVALID_REQUEST, "Missing method");
    if (!valMethod.isStr())
        throw JSONRPCError(RPC_INVALID_REQUEST, "Method must be a string");
    strMethod = valMethod.get_str();
    if (fLogIPs)
        LogDebug(BCLog::RPC, "ThreadRPCServer method=%s user=%s peeraddr=%s\n", SanitizeString(strMethod),
            this->authUser, this->peerAddr);
    else
        LogDebug(BCLog::RPC, "ThreadRPCServer method=%s user=%s\n", SanitizeString(strMethod), this->authUser);

    // Parse params
    const UniValue& valParams{request.find_value("params")};
    if (valParams.isArray() || valParams.isObject())
        params = valParams;
    else if (valParams.isNull())
        params = UniValue(UniValue::VARR);
    else
        throw JSONRPCError(RPC_INVALID_REQUEST, "Params must be an array or object");
}

Coverage Report

Created: 2025-06-10 13:21

Line	Count	Source
1		// Copyright (c) 2010 Satoshi Nakamoto
2		// Copyright (c) 2009-2022 The Bitcoin Core developers
3		// Distributed under the MIT software license, see the accompanying
4		// file COPYING or http://www.opensource.org/licenses/mit-license.php.
5
6		#include <rpc/request.h>
7
8		#include <common/args.h>
9		#include <logging.h>
10		#include <random.h>
11		#include <rpc/protocol.h>
12		#include <util/fs.h>
13		#include <util/fs_helpers.h>
14		#include <util/strencodings.h>
15
16		#include <fstream>
17		#include <stdexcept>
18		#include <string>
19		#include <vector>
20
21		/**
22		* JSON-RPC protocol. Bitcoin speaks version 1.0 for maximum compatibility,
23		* but uses JSON-RPC 1.1/2.0 standards for parts of the 1.0 standard that were
24		* unspecified (HTTP errors and contents of 'error').
25		*
26		* 1.0 spec: http://json-rpc.org/wiki/specification
27		* 1.2 spec: http://jsonrpc.org/historical/json-rpc-over-http.html
28		*
29		* If the server receives a request with the JSON-RPC 2.0 marker `{"jsonrpc": "2.0"}`
30		* then Bitcoin will respond with a strictly specified response.
31		* It will only return an HTTP error code if an actual HTTP error is encountered
32		* such as the endpoint is not found (404) or the request is not formatted correctly (500).
33		* Otherwise the HTTP code is always OK (200) and RPC errors will be included in the
34		* response body.
35		*
36		* 2.0 spec: https://www.jsonrpc.org/specification
37		*
38		* Also see http://www.simple-is-better.org/rpc/#differences-between-1-0-and-2-0
39		*/
40
41		UniValue JSONRPCRequestObj(const std::string& strMethod, const UniValue& params, const UniValue& id)
42	0	{
43	0	UniValue request(UniValue::VOBJ);
44	0	request.pushKV("method", strMethod);
45	0	request.pushKV("params", params);
46	0	request.pushKV("id", id);
47	0	request.pushKV("jsonrpc", "2.0");
48	0	return request;
49	0	}
50
51		UniValue JSONRPCReplyObj(UniValue result, UniValue error, std::optional<UniValue> id, JSONRPCVersion jsonrpc_version)
52	2.35M	{
53	2.35M	UniValue reply(UniValue::VOBJ);
54		// Add JSON-RPC version number field in v2 only.
55	2.35M	if (jsonrpc_version == JSONRPCVersion::V2) reply.pushKV("jsonrpc", "2.0"); Branch (55:9): [True: 2.35M, False: 0]
56
57		// Add both result and error fields in v1, even though one will be null.
58		// Omit the null field in v2.
59	2.35M	if (error.isNull()) { Branch (59:9): [True: 2.35M, False: 4.78k]
60	2.35M	reply.pushKV("result", std::move(result));
61	2.35M	if (jsonrpc_version == JSONRPCVersion::V1_LEGACY) reply.pushKV("error", NullUniValue); Branch (61:13): [True: 0, False: 2.35M]
62	2.35M	} else {
63	4.78k	if (jsonrpc_version == JSONRPCVersion::V1_LEGACY) reply.pushKV("result", NullUniValue); Branch (63:13): [True: 0, False: 4.78k]
64	4.78k	reply.pushKV("error", std::move(error));
65	4.78k	}
66	2.35M	if (id.has_value()) reply.pushKV("id", std::move(id.value())); Branch (66:9): [True: 2.35M, False: 0]
67	2.35M	return reply;
68	2.35M	}
69
70		UniValue JSONRPCError(int code, const std::string& message)
71	4.78k	{
72	4.78k	UniValue error(UniValue::VOBJ);
73	4.78k	error.pushKV("code", code);
74	4.78k	error.pushKV("message", message);
75	4.78k	return error;
76	4.78k	}
77
78		/** Username used when cookie authentication is in use (arbitrary, only for
79		* recognizability in debugging/logging purposes)
80		*/
81		static const std::string COOKIEAUTH_USER = "__cookie__";
82		/** Default name for auth cookie file */
83		static const char* const COOKIEAUTH_FILE = ".cookie";
84
85		/** Get name of RPC authentication cookie file */
86		static fs::path GetAuthCookieFile(bool temp=false)
87	33.2k	{
88	33.2k	fs::path arg = gArgs.GetPathArg("-rpccookiefile", COOKIEAUTH_FILE);
89	33.2k	if (arg.empty()) { Branch (89:9): [True: 0, False: 33.2k]
90	0	return {}; // -norpccookiefile was specified
91	0	}
92	33.2k	if (temp) { Branch (92:9): [True: 11.0k, False: 22.1k]
93	11.0k	arg += ".tmp";
94	11.0k	}
95	33.2k	return AbsPathForConfigVal(gArgs, arg);
96	33.2k	}
97
98		static bool g_generated_cookie = false;
99
100		GenerateAuthCookieResult GenerateAuthCookie(const std::optional<fs::perms>& cookie_perms,
101		std::string& user,
102		std::string& pass)
103	11.0k	{
104	11.0k	const size_t COOKIE_SIZE = 32;
105	11.0k	unsigned char rand_pwd[COOKIE_SIZE];
106	11.0k	GetRandBytes(rand_pwd);
107	11.0k	const std::string rand_pwd_hex{HexStr(rand_pwd)};
108
109		/** the umask determines what permissions are used to create this file -
110		* these are set to 0077 in common/system.cpp.
111		*/
112	11.0k	std::ofstream file;
113	11.0k	fs::path filepath_tmp = GetAuthCookieFile(true);
114	11.0k	if (filepath_tmp.empty()) { Branch (114:9): [True: 0, False: 11.0k]
115	0	return GenerateAuthCookieResult::DISABLED; // -norpccookiefile
116	0	}
117	11.0k	file.open(filepath_tmp);
118	11.0k	if (!file.is_open()) { Branch (118:9): [True: 0, False: 11.0k]
119	0	LogWarning("Unable to open cookie authentication file %s for writing", fs::PathToString(filepath_tmp));
120	0	return GenerateAuthCookieResult::ERR;
121	0	}
122	11.0k	file << COOKIEAUTH_USER << ":" << rand_pwd_hex;
123	11.0k	file.close();
124
125	11.0k	fs::path filepath = GetAuthCookieFile(false);
126	11.0k	if (!RenameOver(filepath_tmp, filepath)) { Branch (126:9): [True: 0, False: 11.0k]
127	0	LogWarning("Unable to rename cookie authentication file %s to %s", fs::PathToString(filepath_tmp), fs::PathToString(filepath));
128	0	return GenerateAuthCookieResult::ERR;
129	0	}
130	11.0k	if (cookie_perms) { Branch (130:9): [True: 0, False: 11.0k]
131	0	std::error_code code;
132	0	fs::permissions(filepath, cookie_perms.value(), fs::perm_options::replace, code);
133	0	if (code) { Branch (133:13): [True: 0, False: 0]
134	0	LogWarning("Unable to set permissions on cookie authentication file %s", fs::PathToString(filepath));
135	0	return GenerateAuthCookieResult::ERR;
136	0	}
137	0	}
138
139	11.0k	g_generated_cookie = true;
140	11.0k	LogInfo("Generated RPC authentication cookie %s\n", fs::PathToString(filepath));
141	11.0k	LogInfo("Permissions used for cookie: %s\n", PermsToSymbolicString(fs::status(filepath).permissions()));
142
143	11.0k	user = COOKIEAUTH_USER;
144	11.0k	pass = rand_pwd_hex;
145	11.0k	return GenerateAuthCookieResult::OK;
146	11.0k	}
147
148		bool GetAuthCookie(std::string *cookie_out)
149	0	{
150	0	std::ifstream file;
151	0	std::string cookie;
152	0	fs::path filepath = GetAuthCookieFile();
153	0	if (filepath.empty()) { Branch (153:9): [True: 0, False: 0]
154	0	return true; // -norpccookiefile
155	0	}
156	0	file.open(filepath);
157	0	if (!file.is_open()) Branch (157:9): [True: 0, False: 0]
158	0	return false;
159	0	std::getline(file, cookie);
160	0	file.close();
161
162	0	if (cookie_out) Branch (162:9): [True: 0, False: 0]
163	0	*cookie_out = cookie;
164	0	return true;
165	0	}
166
167		void DeleteAuthCookie()
168	11.0k	{
169	11.0k	try {
170	11.0k	if (g_generated_cookie) { Branch (170:13): [True: 11.0k, False: 0]
171		// Delete the cookie file if it was generated by this process
172	11.0k	fs::remove(GetAuthCookieFile());
173	11.0k	}
174	11.0k	} catch (const fs::filesystem_error& e) {
175	0	LogWarning("Unable to remove random auth cookie file %s: %s\n", fs::PathToString(e.path1()), e.code().message());
176	0	}
177	11.0k	}
178
179		std::vector<UniValue> JSONRPCProcessBatchReply(const UniValue& in)
180	0	{
181	0	if (!in.isArray()) { Branch (181:9): [True: 0, False: 0]
182	0	throw std::runtime_error("Batch must be an array");
183	0	}
184	0	const size_t num {in.size()};
185	0	std::vector<UniValue> batch(num);
186	0	for (const UniValue& rec : in.getValues()) { Branch (186:30): [True: 0, False: 0]
187	0	if (!rec.isObject()) { Branch (187:13): [True: 0, False: 0]
188	0	throw std::runtime_error("Batch member must be an object");
189	0	}
190	0	size_t id = rec["id"].getInt<int>();
191	0	if (id >= num) { Branch (191:13): [True: 0, False: 0]
192	0	throw std::runtime_error("Batch member id is larger than batch size");
193	0	}
194	0	batch[id] = rec;
195	0	}
196	0	return batch;
197	0	}
198
199		void JSONRPCRequest::parse(const UniValue& valRequest)
200	2.35M	{
201		// Parse request
202	2.35M	if (!valRequest.isObject()) Branch (202:9): [True: 0, False: 2.35M]
203	0	throw JSONRPCError(RPC_INVALID_REQUEST, "Invalid Request object");
204	2.35M	const UniValue& request = valRequest.get_obj();
205
206		// Parse id now so errors from here on will have the id
207	2.35M	if (request.exists("id")) { Branch (207:9): [True: 2.35M, False: 0]
208	2.35M	id = request.find_value("id");
209	2.35M	} else {
210	0	id = std::nullopt;
211	0	}
212
213		// Check for JSON-RPC 2.0 (default 1.1)
214	2.35M	m_json_version = JSONRPCVersion::V1_LEGACY;
215	2.35M	const UniValue& jsonrpc_version = request.find_value("jsonrpc");
216	2.35M	if (!jsonrpc_version.isNull()) { Branch (216:9): [True: 2.35M, False: 0]
217	2.35M	if (!jsonrpc_version.isStr()) { Branch (217:13): [True: 0, False: 2.35M]
218	0	throw JSONRPCError(RPC_INVALID_REQUEST, "jsonrpc field must be a string");
219	0	}
220		// The "jsonrpc" key was added in the 2.0 spec, but some older documentation
221		// incorrectly included {"jsonrpc":"1.0"} in a request object, so we
222		// maintain that for backwards compatibility.
223	2.35M	if (jsonrpc_version.get_str() == "1.0") { Branch (223:13): [True: 0, False: 2.35M]
224	0	m_json_version = JSONRPCVersion::V1_LEGACY;
225	2.35M	} else if (jsonrpc_version.get_str() == "2.0") { Branch (225:20): [True: 2.35M, False: 0]
226	2.35M	m_json_version = JSONRPCVersion::V2;
227	2.35M	} else {
228	0	throw JSONRPCError(RPC_INVALID_REQUEST, "JSON-RPC version not supported");
229	0	}
230	2.35M	}
231
232		// Parse method
233	2.35M	const UniValue& valMethod{request.find_value("method")};
234	2.35M	if (valMethod.isNull()) Branch (234:9): [True: 0, False: 2.35M]
235	0	throw JSONRPCError(RPC_INVALID_REQUEST, "Missing method");
236	2.35M	if (!valMethod.isStr()) Branch (236:9): [True: 0, False: 2.35M]
237	0	throw JSONRPCError(RPC_INVALID_REQUEST, "Method must be a string");
238	2.35M	strMethod = valMethod.get_str();
239	2.35M	if (fLogIPs) Branch (239:9): [True: 0, False: 2.35M]
240	2.35M	LogDebug(BCLog::RPC, "ThreadRPCServer method=%s user=%s peeraddr=%s\n", SanitizeString(strMethod),
241	2.35M	this->authUser, this->peerAddr);
242	2.35M	else
243	2.35M	LogDebug(BCLog::RPC, "ThreadRPCServer method=%s user=%s\n", SanitizeString(strMethod), this->authUser);
244
245		// Parse params
246	2.35M	const UniValue& valParams{request.find_value("params")};
247	2.35M	if (valParams.isArray() \|\| valParams.isObject()) Branch (247:9): [True: 2.35M, False: 0] Branch (247:32): [True: 0, False: 0]
248	2.35M	params = valParams;
249	0	else if (valParams.isNull()) Branch (249:14): [True: 0, False: 0]
250	0	params = UniValue(UniValue::VARR);
251	0	else
252	0	throw JSONRPCError(RPC_INVALID_REQUEST, "Params must be an array or object");
253	2.35M	}