1 /* 2 * Copyright (c) 2019-2020 Apple Inc. All rights reserved. 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 * https://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 #ifndef __DNSSD_XPC_H__ 18 #define __DNSSD_XPC_H__ 19 20 #include <CoreUtils/CommonServices.h> 21 #include <dns_sd.h> 22 #include <xpc/xpc.h> 23 24 #define DNSSD_MACH_SERVICE_NAME "com.apple.dnssd.service" 25 26 #define DNSSD_COMMAND_GETADDRINFO "getaddrinfo" 27 #define DNSSD_COMMAND_STOP "stop" 28 29 CU_ASSUME_NONNULL_BEGIN 30 31 __BEGIN_DECLS 32 33 /*! 34 * @brief 35 * Gets command as a C string from XPC message. 36 * 37 * @param msg 38 * XPC message. 39 * 40 * @result 41 * Command, if present. Otherwise, NULL. 42 */ 43 const char * _Nullable 44 dnssd_xpc_message_get_command(xpc_object_t msg); 45 46 /*! 47 * @brief 48 * Gets error code from XPC message. 49 * 50 * @param msg 51 * XPC message. 52 * 53 * @param out_valid 54 * If non-NULL, set to true if value is present and of correct type, otherwise, set to false. 55 * 56 * @result 57 * Error code, if present. Otherwise, 0. 58 */ 59 DNSServiceErrorType 60 dnssd_xpc_message_get_error(xpc_object_t msg, bool * _Nullable out_valid); 61 62 /*! 63 * @brief 64 * Gets command instance ID from XPC message. 65 * 66 * @param msg 67 * XPC message. 68 * 69 * @param out_valid 70 * If non-NULL, set to true if value is present and of correct type, otherwise, set to false. 71 * 72 * @result 73 * ID, if present. Otherwise, 0. 74 */ 75 uint64_t 76 dnssd_xpc_message_get_id(xpc_object_t msg, bool * _Nullable out_valid); 77 78 /*! 79 * @brief 80 * Gets command parameter dictionary from XPC message. 81 * 82 * @param msg 83 * XPC message. 84 * 85 * @result 86 * Command parameter dictionary, if present. Otherwise, NULL. 87 */ 88 xpc_object_t _Nullable 89 dnssd_xpc_message_get_parameters(xpc_object_t msg); 90 91 /*! 92 * @brief 93 * Gets result array from XPC message. 94 * 95 * @param msg 96 * XPC message. 97 * 98 * @result 99 * Result array, if present. Otherwise, NULL. 100 */ 101 xpc_object_t _Nullable 102 dnssd_xpc_message_get_results(xpc_object_t msg); 103 104 /*! 105 * @brief 106 * Sets command in XPC message. 107 * 108 * @param msg 109 * XPC message. 110 * 111 * @param command 112 * Command as a C string. 113 */ 114 void 115 dnssd_xpc_message_set_command(xpc_object_t msg, const char *command); 116 117 /*! 118 * @brief 119 * Sets error code in XPC message. 120 * 121 * @param msg 122 * XPC message. 123 * 124 * @param error 125 * Error code. 126 */ 127 void 128 dnssd_xpc_message_set_error(xpc_object_t msg, DNSServiceErrorType error); 129 130 /*! 131 * @brief 132 * Sets command instance ID in XPC message. 133 * 134 * @param msg 135 * XPC message. 136 * 137 * @param ident 138 * Command instance ID. 139 */ 140 void 141 dnssd_xpc_message_set_id(xpc_object_t msg, uint64_t ident); 142 143 /*! 144 * @brief 145 * Sets command parameters dictionary in XPC message. 146 * 147 * @param msg 148 * XPC message. 149 * 150 * @param params 151 * Command parameters dictionary. 152 */ 153 void 154 dnssd_xpc_message_set_parameters(xpc_object_t msg, xpc_object_t params); 155 156 /*! 157 * @brief 158 * Sets command result array in XPC message. 159 * 160 * @param msg 161 * XPC message. 162 * 163 * @param results 164 * Command result array. 165 */ 166 void 167 dnssd_xpc_message_set_results(xpc_object_t msg, xpc_object_t results); 168 169 /*! 170 * @brief 171 * Gets delegate ID as a PID from a command parameters dictionary. 172 * 173 * @param params 174 * Command parameters dictionary. 175 * 176 * @param out_valid 177 * If non-NULL, set to true if value is present and of correct type, otherwise, set to false. 178 * 179 * @result 180 * Delegate ID as PID, if present. Otherwise, 0. 181 */ 182 pid_t 183 dnssd_xpc_parameters_get_delegate_pid(xpc_object_t params, bool * _Nullable out_valid); 184 185 /*! 186 * @brief 187 * Gets delegate ID as a UUID from a command parameters dictionary. 188 * 189 * @param params 190 * Command parameters dictionary. 191 * 192 * @result 193 * Delegate ID as UUID, if present. Otherwise, NULL. 194 */ 195 const uint8_t * _Nullable 196 dnssd_xpc_parameters_get_delegate_uuid(xpc_object_t params); 197 198 /*! 199 * @brief 200 * Gets a delegate audit token from a command parameters dictionary. 201 * 202 * @param params 203 * Command parameters dictionary. 204 * 205 * @param audit_token_storage 206 * Pointer to an audit token to overwrite with parameters dictionary's delegate audit token data. 207 * 208 * @result 209 * If the parameters dictionary contains a delegate audit token, this function copies it to 210 * audit_token_storage and returns audit_token_storage. Otherwise, it returns NULL. 211 */ 212 audit_token_t * _Nullable 213 dnssd_xpc_parameters_get_delegate_audit_token(xpc_object_t params, audit_token_t *audit_token_storage); 214 215 /*! 216 * @brief 217 * Gets flags from a command parameters dictionary. 218 * 219 * @param params 220 * Command parameters dictionary. 221 * 222 * @param out_valid 223 * If non-NULL, set to true if value is present and of correct type, otherwise, set to false. 224 * 225 * @result 226 * Flags, if present. Otherwise, 0. 227 */ 228 DNSServiceFlags 229 dnssd_xpc_parameters_get_flags(xpc_object_t params, bool * _Nullable out_valid); 230 231 /*! 232 * @brief 233 * Gets account id from a command parameters dictionary. 234 * 235 * @param params 236 * Command parameters dictionary. 237 * 238 * @result 239 * Account, if present, as a const char *. Otherwise, NULL. 240 */ 241 const char * _Nullable 242 dnssd_xpc_parameters_get_account_id(xpc_object_t params); 243 244 /*! 245 * @brief 246 * Gets hostname from a command parameters dictionary. 247 * 248 * @param params 249 * Command parameters dictionary. 250 * 251 * @result 252 * Hostname, if present, as an XPC string object. Otherwise, NULL. 253 */ 254 xpc_object_t _Nullable 255 dnssd_xpc_parameters_get_hostname_object(xpc_object_t params); 256 257 /*! 258 * @brief 259 * Gets interface index from a command parameters dictionary. 260 * 261 * @param params 262 * Command parameters dictionary. 263 * 264 * @para out_valid 265 * If non-NULL, set to true if value is present and of correct type, otherwise, set to false. 266 * 267 * @result 268 * Interface index, if present. Otherwise, 0. 269 */ 270 uint32_t 271 dnssd_xpc_parameters_get_interface_index(xpc_object_t params, bool * _Nullable out_valid); 272 273 /*! 274 * @brief 275 * Gets need_auth_tags boolean value from a command parameters dictionary. 276 * 277 * @param params 278 * Command parameters dictionary. 279 * 280 * @result 281 * A boolean value. 282 */ 283 bool 284 dnssd_xpc_parameters_get_need_authentication_tags(xpc_object_t params); 285 286 /*! 287 * @brief 288 * Gets need encryption boolean value from a command parameters dictionary. 289 * 290 * @param params 291 * Command parameters dictionary. 292 * 293 * @result 294 * A boolean value. 295 */ 296 bool 297 dnssd_xpc_parameters_get_need_encrypted_query(xpc_object_t params); 298 299 /*! 300 * @brief 301 * Gets fallback resolver configuration dictionary from a command parameters dictionary. 302 * 303 * @param params 304 * Command parameters dictionary. 305 * 306 * @result 307 * A dictionary containing resolver configuration to use in the absence of encrypted resolvers, or NULL. 308 */ 309 xpc_object_t _Nullable 310 dnssd_xpc_parameters_get_fallback_config(xpc_object_t params); 311 312 /*! 313 * @brief 314 * Gets resolver UUID array from a command parameters dictionary. 315 * 316 * @param params 317 * Command parameters dictionary. 318 * 319 * @result 320 * An array of UUIDs, or NULL. 321 */ 322 xpc_object_t _Nullable 323 dnssd_xpc_parameters_get_resolver_uuid_array(xpc_object_t params); 324 325 /*! 326 * @brief 327 * Gets protocols from a command parameters dictionary. 328 * 329 * @param params 330 * Command parameters dictionary. 331 * 332 * @param out_valid 333 * If non-NULL, set to true if value is present and of correct type, otherwise, set to false. 334 * 335 * @result 336 * Protocols, if present. Otherwise, 0. 337 */ 338 DNSServiceProtocol 339 dnssd_xpc_parameters_get_protocols(xpc_object_t params, bool * _Nullable out_valid); 340 341 /*! 342 * @brief 343 * Gets the service scheme from a command parameters dictionary. 344 * 345 * @param params 346 * Command parameters dictionary. 347 * 348 * @result 349 * A string containing service scheme for the query, or NULL. 350 */ 351 const char * _Nullable 352 dnssd_xpc_parameters_get_service_scheme(xpc_object_t params); 353 354 /*! 355 * @brief 356 * Sets delegate ID as a PID in a command parameters dictionary. 357 * 358 * @param params 359 * Command parameters dictionary. 360 * 361 * @param pid 362 * PID. 363 */ 364 void 365 dnssd_xpc_parameters_set_delegate_pid(xpc_object_t params, pid_t pid); 366 367 /*! 368 * @brief 369 * Sets delegate ID as a UUID in a command parameters dictionary. 370 * 371 * @param params 372 * Command parameters dictionary. 373 * 374 * @param uuid 375 * UUID. 376 */ 377 void 378 dnssd_xpc_parameters_set_delegate_uuid(xpc_object_t params, uuid_t _Nonnull uuid); 379 380 /*! 381 * @brief 382 * Sets the delegate audit token in a command parameters dictionary. 383 * 384 * @param params 385 * Command parameters dictionary. 386 * 387 * @param audit_token 388 * The delegate audit token. 389 */ 390 void 391 dnssd_xpc_parameters_set_delegate_audit_token(xpc_object_t params, const audit_token_t *audit_token); 392 393 /*! 394 * @brief 395 * Sets flags in a command parameters dictionary. 396 * 397 * @param params 398 * Command parameters dictionary. 399 * 400 * @param flags 401 * Flags. 402 */ 403 void 404 dnssd_xpc_parameters_set_flags(xpc_object_t params, DNSServiceFlags flags); 405 406 /*! 407 * @brief 408 * Sets account id in a command parameters dictionary. 409 * 410 * @param params 411 * Command parameters dictionary. 412 * 413 * @param account_id 414 * Account id. 415 */ 416 void 417 dnssd_xpc_parameters_set_account_id(xpc_object_t params, const char *account_id); 418 419 /*! 420 * @brief 421 * Sets hostname in a command parameters dictionary. 422 * 423 * @param params 424 * Command parameters dictionary. 425 * 426 * @param hostname 427 * Hostname. 428 */ 429 void 430 dnssd_xpc_parameters_set_hostname(xpc_object_t params, const char *hostname); 431 432 /*! 433 * @brief 434 * Sets interface index in a command parameters dictionary. 435 * 436 * @param params 437 * Command parameters dictionary. 438 * 439 * @param interface_index 440 * Interface index. 441 */ 442 void 443 dnssd_xpc_parameters_set_interface_index(xpc_object_t params, uint32_t interface_index); 444 445 /*! 446 * @brief 447 * Sets whether mDNSResponder should include an authentication tag for each hostname resolution. 448 * 449 * @param params 450 * Command parameters dictionary. 451 * 452 * @param need 453 * Pass <code>true</code> to enable this behavior. Pass <code>false</code> to disable it. 454 */ 455 void 456 dnssd_xpc_parameters_set_need_authentication_tags(xpc_object_t params, bool need); 457 458 /*! 459 * @brief 460 * Specifies whether or not queries must use encrypted transports to the next DNS server. 461 * 462 * @param params 463 * Command parameters dictionary. 464 * 465 * @param need 466 * Pass <code>true</code> if encrypted queries are required, otherwise, pass <code>false</code>. 467 * 468 * @param fallback_config 469 * If not NULL, specify a custom resolver configuration to use if no encrypted resolver configuation is otherwise 470 * available. 471 */ 472 void 473 dnssd_xpc_parameters_set_need_encrypted_query(xpc_object_t params, bool need, _Nullable xpc_object_t fallback_config); 474 475 /*! 476 * @brief 477 * Add a resolver UUID that represents a resolver configuration registered with the system that should 478 * be applied to this resolution. Multiple UUIDs can be set. 479 * 480 * @param params 481 * Command parameters dictionary. 482 * 483 * @param uuid 484 * UUID of a resolver configuration registered with the system. 485 */ 486 void 487 dnssd_xpc_parameters_add_resolver_uuid(xpc_object_t params, uuid_t _Nonnull uuid); 488 489 /*! 490 * @brief 491 * Sets a service scheme in a command parameters dictionary. 492 * 493 * @param params 494 * Command parameters dictionary. 495 * 496 * @param service_scheme 497 * Service scheme. 498 */ 499 void 500 dnssd_xpc_parameters_set_service_scheme(xpc_object_t params, const char *service_scheme); 501 502 /*! 503 * @brief 504 * Sets protocols in a command parameters dictionary. 505 * 506 * @param params 507 * Command parameters dictionary. 508 * 509 * @param protocols 510 * Protocols. 511 */ 512 void 513 dnssd_xpc_parameters_set_protocols(xpc_object_t params, DNSServiceProtocol protocols); 514 515 /*! 516 * @brief 517 * Gets authentication tag from a command result dictionary. 518 * 519 * @param result 520 * The command result dictionary. 521 * 522 * @result 523 * Authentication tag, if present, as an XPC data object. Otherwise, NULL. 524 */ 525 xpc_object_t _Nullable 526 dnssd_xpc_result_get_authentication_tag_object(xpc_object_t result); 527 528 /*! 529 * @brief 530 * Gets error code from a command result dictionary. 531 * 532 * @param result 533 * The command result dictionary. 534 * 535 * @param out_valid 536 * If non-NULL, set to true if value is present and of correct type, otherwise, set to false. 537 * 538 * @result 539 * Error code, if present. Otherwise, 0. 540 */ 541 DNSServiceErrorType 542 dnssd_xpc_result_get_error(xpc_object_t result, bool * _Nullable out_valid); 543 544 /*! 545 * @brief 546 * Gets flags from a command result dictionary. 547 * 548 * @param result 549 * The command result dictionary. 550 * 551 * @param out_valid 552 * If non-NULL, set to true if value is present and of correct type, otherwise, set to false. 553 * 554 * @result 555 * Flags, if present. Otherwise, 0. 556 */ 557 DNSServiceFlags 558 dnssd_xpc_result_get_flags(xpc_object_t result, bool * _Nullable out_valid); 559 560 /*! 561 * @brief 562 * Gets interface index from a command result dictionary. 563 * 564 * @param result 565 * The command result dictionary. 566 * 567 * @param out_valid 568 * If non-NULL, set to true if value is present and of correct type, otherwise, set to false. 569 * 570 * @result 571 * Interface index, if present. Otherwise, 0. 572 */ 573 uint32_t 574 dnssd_xpc_result_get_interface_index(xpc_object_t result, bool * _Nullable out_valid); 575 576 /*! 577 * @brief 578 * Gets record class from a command result dictionary. 579 * 580 * @param result 581 * The command result dictionary. 582 * 583 * @param out_valid 584 * If non-NULL, set to true if value is present and of correct type, otherwise, set to false. 585 * 586 * @result 587 * Record class, if present. Otherwise, 0. 588 */ 589 uint16_t 590 dnssd_xpc_result_get_record_class(xpc_object_t result, bool * _Nullable out_valid); 591 592 /*! 593 * @brief 594 * Gets record data from a command result dictionary. 595 * 596 * @param result 597 * The command result dictionary. 598 * 599 * @result 600 * Record data, if present, as an XPC data object. Otherwise, NULL. 601 */ 602 xpc_object_t _Nullable 603 dnssd_xpc_result_get_record_data_object(xpc_object_t result); 604 605 /*! 606 * @brief 607 * Gets record name from a command result dictionary. 608 * 609 * @param result 610 * The command result dictionary. 611 * 612 * @result 613 * Record name, if present, as an XPC string object. Otherwise, NULL. 614 */ 615 xpc_object_t _Nullable 616 dnssd_xpc_result_get_record_name_object(xpc_object_t result); 617 618 /*! 619 * @brief 620 * Gets record canonical name from a command result dictionary. 621 * 622 * @param result 623 * The command result dictionary. 624 * 625 * @result 626 * Record canonical name, if present, as an XPC string object. Otherwise, NULL. 627 */ 628 xpc_object_t _Nullable 629 dnssd_xpc_result_get_record_cname_object(xpc_object_t result); 630 631 /*! 632 * @brief 633 * Gets record type from a command result dictionary. 634 * 635 * @param result 636 * The command result dictionary. 637 * 638 * @param out_valid 639 * If non-NULL, set to true if value is present and of correct type, otherwise, set to false. 640 * 641 * @result 642 * Record type, if present. Otherwise, 0. 643 */ 644 uint16_t 645 dnssd_xpc_result_get_record_type(xpc_object_t result, bool * _Nullable out_valid); 646 647 /*! 648 * @brief 649 * Gets used record protocol from a command result dictionary. 650 * 651 * @param result 652 * The command result dictionary. 653 * 654 * @param out_valid 655 * If non-NULL, set to true if value is present and of correct type, otherwise, set to false. 656 * 657 * @result 658 * Used record protocol, if present. Otherwise, 0. 659 */ 660 uint16_t 661 dnssd_xpc_result_get_record_protocol(xpc_object_t result, bool * _Nullable out_valid); 662 663 /*! 664 * @brief 665 * Gets provider name from a command result dictionary. 666 * 667 * @param result 668 * The command result dictionary. 669 * 670 * @result 671 * Provider name, if present, as an XPC string object. Otherwise, NULL. 672 */ 673 xpc_object_t _Nullable 674 dnssd_xpc_result_get_provider_name_object(xpc_object_t result); 675 676 /*! 677 * @brief 678 * Gets canonical name updates from a command result dictionary. 679 * 680 * @param result 681 * The command result dictionary. 682 * 683 * @result 684 * The canonical name update, if present, as an XPC array object. Otherwise, NULL. 685 */ 686 xpc_object_t _Nullable 687 dnssd_xpc_result_get_cname_update(xpc_object_t result); 688 689 /*! 690 * @brief 691 * Sets the authentication tag in a command result dictionary. 692 * 693 * @param result 694 * The command result dictionary. 695 * 696 * @param auth_tag_ptr 697 * Pointer to the authentication tag. 698 * 699 * @param auth_tag_len 700 * Length of the authentication tag. 701 */ 702 void 703 dnssd_xpc_result_set_authentication_tag(xpc_object_t result, const void *auth_tag_ptr, size_t auth_tag_len); 704 705 /*! 706 * @brief 707 * Sets the error code in a command result dictionary. 708 * 709 * @param result 710 * The command result dictionary. 711 * 712 * @param error 713 * Error code. 714 */ 715 void 716 dnssd_xpc_result_set_error(xpc_object_t result, DNSServiceErrorType error); 717 718 /*! 719 * @brief 720 * Sets flags in a command result dictionary. 721 * 722 * @param result 723 * The command result dictionary. 724 * 725 * @param flags 726 * Flags. 727 */ 728 void 729 dnssd_xpc_result_set_flags(xpc_object_t result, DNSServiceFlags flags); 730 731 /*! 732 * @brief 733 * Sets interface index in a command result dictionary. 734 * 735 * @param result 736 * The command result dictionary. 737 * 738 * @param interface_index 739 * Interface index. 740 */ 741 void 742 dnssd_xpc_result_set_interface_index(xpc_object_t result, uint32_t interface_index); 743 744 /*! 745 * @brief 746 * Sets record class in a command result dictionary. 747 * 748 * @param result 749 * The command result dictionary. 750 * 751 * @param class 752 * Record class. 753 */ 754 void 755 dnssd_xpc_result_set_record_class(xpc_object_t result, uint16_t class); 756 757 /*! 758 * @brief 759 * Sets the record data in a command result dictionary. 760 * 761 * @param result 762 * The command result dictionary. 763 * 764 * @param data_ptr 765 * Pointer to the record data. 766 * 767 * @param data_len 768 * Length of the record data. 769 */ 770 void 771 dnssd_xpc_result_set_record_data(xpc_object_t result, const void * _Nullable data_ptr, size_t data_len); 772 773 /*! 774 * @brief 775 * Sets record name in a command result dictionary. 776 * 777 * @param result 778 * The command result dictionary. 779 * 780 * @param name 781 * Record name. 782 */ 783 void 784 dnssd_xpc_result_set_record_name(xpc_object_t result, const char *name); 785 786 /*! 787 * @brief 788 * Sets record canonical name in a command result dictionary. 789 * 790 * @param result 791 * The command result dictionary. 792 * 793 * @param cname 794 * Record canonical name. 795 */ 796 void 797 dnssd_xpc_result_set_record_cname(xpc_object_t result, const char *cname); 798 799 /*! 800 * @brief 801 * Sets record type in a command result dictionary. 802 * 803 * @param result 804 * The command result dictionary. 805 * 806 * @param type 807 * Record type. 808 */ 809 void 810 dnssd_xpc_result_set_record_type(xpc_object_t result, uint16_t type); 811 812 /*! 813 * @brief 814 * Sets record protocol in a command result dictionary. 815 * 816 * @param result 817 * The command result dictionary. 818 * 819 * @param protocol 820 * Record protocol. 821 */ 822 void 823 dnssd_xpc_result_set_record_protocol(xpc_object_t result, uint16_t protocol); 824 825 /*! 826 * @brief 827 * Sets the DNS provider name in a command result dictionary. 828 * 829 * @param result 830 * The command result dictionary. 831 * 832 * @param provider_name 833 * DNS provider name. 834 */ 835 void 836 dnssd_xpc_result_set_provider_name(xpc_object_t result, const char *provider_name); 837 838 /*! 839 * @brief 840 * Sets a canonical name update in a command result dictionary. 841 * 842 * @param result 843 * The command result dictionary. 844 * 845 * @param cname_update 846 * The canonical name update as an array of canonical names as strings. 847 */ 848 void 849 dnssd_xpc_result_set_cname_update(xpc_object_t result, xpc_object_t cname_update); 850 851 __END_DECLS 852 853 CU_ASSUME_NONNULL_END 854 855 #endif // __DNSSD_XPC_H__ 856