1 /* 2 * Copyright (C) 2021 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 // This file can be autogenerated by the following command, but the generated file 18 // may not pass clang-format check. 19 // cbindgen --config cbindgen.toml doh/doh.rs -o doh.h 20 21 #pragma once 22 23 #include <stdint.h> 24 #include <sys/types.h> 25 26 /// The return code of doh_query means that there is no answer. 27 static const ssize_t DOH_RESULT_INTERNAL_ERROR = -1; 28 29 /// The return code of doh_query means that query can't be sent. 30 static const ssize_t DOH_RESULT_CAN_NOT_SEND = -2; 31 32 /// The return code of doh_query to indicate that the query timed out. 33 static const ssize_t DOH_RESULT_TIMEOUT = -255; 34 35 /// The error log level. 36 static const uint32_t DOH_LOG_LEVEL_ERROR = 0; 37 38 /// The warning log level. 39 static const uint32_t DOH_LOG_LEVEL_WARN = 1; 40 41 /// The info log level. 42 static const uint32_t DOH_LOG_LEVEL_INFO = 2; 43 44 /// The debug log level. 45 static const uint32_t DOH_LOG_LEVEL_DEBUG = 3; 46 47 /// The trace log level. 48 static const uint32_t DOH_LOG_LEVEL_TRACE = 4; 49 50 /// Context for a running DoH engine. 51 struct DohDispatcher; 52 53 struct FeatureFlags { 54 uint64_t probe_timeout_ms; 55 uint64_t idle_timeout_ms; 56 bool use_session_resumption; 57 bool enable_early_data; 58 }; 59 60 using ValidationCallback = void (*)(uint32_t net_id, bool success, const char* ip_addr, 61 const char* host); 62 63 using TagSocketCallback = void (*)(int32_t sock); 64 65 extern "C" { 66 67 /// Performs static initialization for android logger. 68 /// If an invalid level is passed, defaults to logging errors only. 69 /// If called more than once, it will have no effect on subsequent calls. 70 void doh_init_logger(uint32_t level); 71 72 /// Set the log level. 73 /// If an invalid level is passed, defaults to logging errors only. 74 void doh_set_log_level(uint32_t level); 75 76 /// Performs the initialization for the DoH engine. 77 /// Creates and returns a DoH engine instance. 78 DohDispatcher* doh_dispatcher_new(ValidationCallback validation_fn, 79 TagSocketCallback tag_socket_fn); 80 81 /// Deletes a DoH engine created by doh_dispatcher_new(). 82 /// # Safety 83 /// `doh` must be a non-null pointer previously created by `doh_dispatcher_new()` 84 /// and not yet deleted by `doh_dispatcher_delete()`. 85 void doh_dispatcher_delete(DohDispatcher* doh); 86 87 /// Probes and stores the DoH server with the given configurations. 88 /// Use the negative errno-style codes as the return value to represent the result. 89 /// # Safety 90 /// `doh` must be a non-null pointer previously created by `doh_dispatcher_new()` 91 /// and not yet deleted by `doh_dispatcher_delete()`. 92 /// `url`, `domain`, `ip_addr`, `cert_path` are null terminated strings. 93 int32_t doh_net_new(DohDispatcher* doh, uint32_t net_id, const char* url, const char* domain, 94 const char* ip_addr, uint32_t sk_mark, const char* cert_path, 95 const FeatureFlags* flags, uint32_t network_type, uint32_t private_dns_mode); 96 97 /// Sends a DNS query via the network associated to the given |net_id| and waits for the response. 98 /// The return code should be either one of the public constant RESULT_* to indicate the error or 99 /// the size of the answer. 100 /// # Safety 101 /// `doh` must be a non-null pointer previously created by `doh_dispatcher_new()` 102 /// and not yet deleted by `doh_dispatcher_delete()`. 103 /// `dns_query` must point to a buffer at least `dns_query_len` in size. 104 /// `response` must point to a buffer at least `response_len` in size. 105 ssize_t doh_query(DohDispatcher* doh, uint32_t net_id, uint8_t* dns_query, size_t dns_query_len, 106 uint8_t* response, size_t response_len, uint64_t timeout_ms); 107 108 /// Clears the DoH servers associated with the given |netid|. 109 /// # Safety 110 /// `doh` must be a non-null pointer previously created by `doh_dispatcher_new()` 111 /// and not yet deleted by `doh_dispatcher_delete()`. 112 void doh_net_delete(DohDispatcher* doh, uint32_t net_id); 113 114 } // extern "C" 115