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 }; 58 59 using ValidationCallback = void (*)(uint32_t net_id, bool success, const char* ip_addr, 60 const char* host); 61 62 using TagSocketCallback = void (*)(int32_t sock); 63 64 extern "C" { 65 66 /// Performs static initialization for android logger. 67 /// If an invalid level is passed, defaults to logging errors only. 68 /// If called more than once, it will have no effect on subsequent calls. 69 void doh_init_logger(uint32_t level); 70 71 /// Set the log level. 72 /// If an invalid level is passed, defaults to logging errors only. 73 void doh_set_log_level(uint32_t level); 74 75 /// Performs the initialization for the DoH engine. 76 /// Creates and returns a DoH engine instance. 77 DohDispatcher* doh_dispatcher_new(ValidationCallback validation_fn, 78 TagSocketCallback tag_socket_fn); 79 80 /// Deletes a DoH engine created by doh_dispatcher_new(). 81 /// # Safety 82 /// `doh` must be a non-null pointer previously created by `doh_dispatcher_new()` 83 /// and not yet deleted by `doh_dispatcher_delete()`. 84 void doh_dispatcher_delete(DohDispatcher* doh); 85 86 /// Probes and stores the DoH server with the given configurations. 87 /// Use the negative errno-style codes as the return value to represent the result. 88 /// # Safety 89 /// `doh` must be a non-null pointer previously created by `doh_dispatcher_new()` 90 /// and not yet deleted by `doh_dispatcher_delete()`. 91 /// `url`, `domain`, `ip_addr`, `cert_path` are null terminated strings. 92 int32_t doh_net_new(DohDispatcher* doh, uint32_t net_id, const char* url, const char* domain, 93 const char* ip_addr, uint32_t sk_mark, const char* cert_path, 94 const FeatureFlags* flags); 95 96 /// Sends a DNS query via the network associated to the given |net_id| and waits for the response. 97 /// The return code should be either one of the public constant RESULT_* to indicate the error or 98 /// the size of the answer. 99 /// # Safety 100 /// `doh` must be a non-null pointer previously created by `doh_dispatcher_new()` 101 /// and not yet deleted by `doh_dispatcher_delete()`. 102 /// `dns_query` must point to a buffer at least `dns_query_len` in size. 103 /// `response` must point to a buffer at least `response_len` in size. 104 ssize_t doh_query(DohDispatcher* doh, uint32_t net_id, uint8_t* dns_query, size_t dns_query_len, 105 uint8_t* response, size_t response_len, uint64_t timeout_ms); 106 107 /// Clears the DoH servers associated with the given |netid|. 108 /// # Safety 109 /// `doh` must be a non-null pointer previously created by `doh_dispatcher_new()` 110 /// and not yet deleted by `doh_dispatcher_delete()`. 111 void doh_net_delete(DohDispatcher* doh, uint32_t net_id); 112 113 } // extern "C" 114