1 /*
2  *  Copyright (c) 2020, The OpenThread Authors.
3  *  All rights reserved.
4  *
5  *  Redistribution and use in source and binary forms, with or without
6  *  modification, are permitted provided that the following conditions are met:
7  *  1. Redistributions of source code must retain the above copyright
8  *     notice, this list of conditions and the following disclaimer.
9  *  2. Redistributions in binary form must reproduce the above copyright
10  *     notice, this list of conditions and the following disclaimer in the
11  *     documentation and/or other materials provided with the distribution.
12  *  3. Neither the name of the copyright holder nor the
13  *     names of its contributors may be used to endorse or promote products
14  *     derived from this software without specific prior written permission.
15  *
16  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17  *  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18  *  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19  *  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
20  *  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21  *  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22  *  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23  *  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24  *  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25  *  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26  *  POSSIBILITY OF SUCH DAMAGE.
27  */
28 
29 /**
30  * @file
31  * @brief
32  *  This file defines the API for server of the Service Registration Protocol (SRP).
33  */
34 
35 #ifndef OPENTHREAD_SRP_SERVER_H_
36 #define OPENTHREAD_SRP_SERVER_H_
37 
38 #include <stdint.h>
39 
40 #include <openthread/dns.h>
41 #include <openthread/instance.h>
42 #include <openthread/ip6.h>
43 
44 #ifdef __cplusplus
45 extern "C" {
46 #endif
47 
48 /**
49  * @addtogroup api-srp
50  *
51  * @brief
52  *  This module includes functions of the Service Registration Protocol.
53  *
54  * @{
55  *
56  */
57 
58 /**
59  * This opaque type represents a SRP service host.
60  *
61  */
62 typedef void otSrpServerHost;
63 
64 /**
65  * This opaque type represents a SRP service.
66  *
67  */
68 typedef void otSrpServerService;
69 
70 /**
71  * The ID of a SRP service update transaction on the SRP Server.
72  *
73  */
74 typedef uint32_t otSrpServerServiceUpdateId;
75 
76 /**
77  * The service flag type to indicate which services to include or exclude when searching in (or iterating over) the
78  * list of SRP services.
79  *
80  * This is a combination of bit-flags. The specific bit-flags are defined in the enumeration `OT_SRP_SERVER_FLAG_*`.
81  *
82  */
83 typedef uint8_t otSrpServerServiceFlags;
84 
85 enum
86 {
87     OT_SRP_SERVER_SERVICE_FLAG_BASE_TYPE = 1 << 0, ///< Include base services (not a sub-type).
88     OT_SRP_SERVER_SERVICE_FLAG_SUB_TYPE  = 1 << 1, ///< Include sub-type services.
89     OT_SRP_SERVER_SERVICE_FLAG_ACTIVE    = 1 << 2, ///< Include active (not deleted) services.
90     OT_SRP_SERVER_SERVICE_FLAG_DELETED   = 1 << 3, ///< Include deleted services.
91 };
92 
93 enum
94 {
95     /**
96      * This constant defines an `otSrpServerServiceFlags` combination accepting any service (base/sub-type,
97      * active/deleted).
98      *
99      */
100     OT_SRP_SERVER_FLAGS_ANY_SERVICE = (OT_SRP_SERVER_SERVICE_FLAG_BASE_TYPE | OT_SRP_SERVER_SERVICE_FLAG_SUB_TYPE |
101                                        OT_SRP_SERVER_SERVICE_FLAG_ACTIVE | OT_SRP_SERVER_SERVICE_FLAG_DELETED),
102 
103     /**
104      * This constant defines an `otSrpServerServiceFlags` combination accepting base service only.
105      *
106      */
107     OT_SRP_SERVER_FLAGS_BASE_TYPE_SERVICE_ONLY =
108         (OT_SRP_SERVER_SERVICE_FLAG_BASE_TYPE | OT_SRP_SERVER_SERVICE_FLAG_ACTIVE | OT_SRP_SERVER_SERVICE_FLAG_DELETED),
109 
110     /**
111      * This constant defines an `otSrpServerServiceFlags` combination accepting sub-type service only.
112      *
113      */
114     OT_SRP_SERVER_FLAGS_SUB_TYPE_SERVICE_ONLY =
115         (OT_SRP_SERVER_SERVICE_FLAG_SUB_TYPE | OT_SRP_SERVER_SERVICE_FLAG_ACTIVE | OT_SRP_SERVER_SERVICE_FLAG_DELETED),
116 
117     /**
118      * This constant defines an `otSrpServerServiceFlags` combination accepting any active service (not deleted).
119      *
120      */
121     OT_SRP_SERVER_FLAGS_ANY_TYPE_ACTIVE_SERVICE =
122         (OT_SRP_SERVER_SERVICE_FLAG_BASE_TYPE | OT_SRP_SERVER_SERVICE_FLAG_SUB_TYPE |
123          OT_SRP_SERVER_SERVICE_FLAG_ACTIVE),
124 
125     /**
126      * This constant defines an `otSrpServerServiceFlags` combination accepting any deleted service.
127      *
128      */
129     OT_SRP_SERVER_FLAGS_ANY_TYPE_DELETED_SERVICE =
130         (OT_SRP_SERVER_SERVICE_FLAG_BASE_TYPE | OT_SRP_SERVER_SERVICE_FLAG_SUB_TYPE |
131          OT_SRP_SERVER_SERVICE_FLAG_ACTIVE),
132 };
133 
134 /**
135  * Represents the state of an SRP server
136  *
137  */
138 typedef enum
139 {
140     OT_SRP_SERVER_STATE_DISABLED = 0, ///< The SRP server is disabled.
141     OT_SRP_SERVER_STATE_RUNNING  = 1, ///< The SRP server is running.
142     OT_SRP_SERVER_STATE_STOPPED  = 2, ///< The SRP server is stopped.
143 } otSrpServerState;
144 
145 /**
146  * This structure includes SRP server LEASE and KEY-LEASE configurations.
147  *
148  */
149 typedef struct otSrpServerLeaseConfig
150 {
151     uint32_t mMinLease;    ///< The minimum LEASE interval in seconds.
152     uint32_t mMaxLease;    ///< The maximum LEASE interval in seconds.
153     uint32_t mMinKeyLease; ///< The minimum KEY-LEASE interval in seconds.
154     uint32_t mMaxKeyLease; ///< The maximum KEY-LEASE interval in seconds.
155 } otSrpServerLeaseConfig;
156 
157 /**
158  * This function returns the domain authorized to the SRP server.
159  *
160  * If the domain if not set by SetDomain, "default.service.arpa." will be returned.
161  * A trailing dot is always appended even if the domain is set without it.
162  *
163  * @param[in]  aInstance  A pointer to an OpenThread instance.
164  *
165  * @returns A pointer to the dot-joined domain string.
166  *
167  */
168 const char *otSrpServerGetDomain(otInstance *aInstance);
169 
170 /**
171  * This function sets the domain on the SRP server.
172  *
173  * A trailing dot will be appended to @p aDomain if it is not already there.
174  * This function should only be called before the SRP server is enabled.
175  *
176  * @param[in]  aInstance  A pointer to an OpenThread instance.
177  * @param[in]  aDomain    The domain to be set. MUST NOT be NULL.
178  *
179  * @retval  OT_ERROR_NONE           Successfully set the domain to @p aDomain.
180  * @retval  OT_ERROR_INVALID_STATE  The SRP server is already enabled and the Domain cannot be changed.
181  * @retval  OT_ERROR_INVALID_ARGS   The argument @p aDomain is not a valid DNS domain name.
182  * @retval  OT_ERROR_NO_BUFS        There is no memory to store content of @p aDomain.
183  *
184  */
185 otError otSrpServerSetDomain(otInstance *aInstance, const char *aDomain);
186 
187 /**
188  * This function returns the state of the SRP server.
189  *
190  * @param[in]  aInstance  A pointer to an OpenThread instance.
191  *
192  * @returns The current state of the SRP server.
193  *
194  */
195 otSrpServerState otSrpServerGetState(otInstance *aInstance);
196 
197 /**
198  * This function enables/disables the SRP server.
199  *
200  * @param[in]  aInstance  A pointer to an OpenThread instance.
201  * @param[in]  aEnabled   A boolean to enable/disable the SRP server.
202  *
203  */
204 void otSrpServerSetEnabled(otInstance *aInstance, bool aEnabled);
205 
206 /**
207  * This function returns SRP server LEASE and KEY-LEASE configurations.
208  *
209  * @param[in]   aInstance     A pointer to an OpenThread instance.
210  * @param[out]  aLeaseConfig  A pointer to an `otSrpServerLeaseConfig` instance.
211  *
212  */
213 void otSrpServerGetLeaseConfig(otInstance *aInstance, otSrpServerLeaseConfig *aLeaseConfig);
214 
215 /**
216  * This function sets SRP server LEASE and KEY-LEASE configurations.
217  *
218  * When a non-zero LEASE time is requested from a client, the granted value will be
219  * limited in range [aMinLease, aMaxLease]; and a non-zero KEY-LEASE will be granted
220  * in range [aMinKeyLease, aMaxKeyLease]. For zero LEASE or KEY-LEASE time, zero will
221  * be granted.
222  *
223  * @param[in]  aInstance     A pointer to an OpenThread instance.
224  * @param[in]  aLeaseConfig  A pointer to an `otSrpServerLeaseConfig` instance.
225  *
226  * @retval  OT_ERROR_NONE          Successfully set the LEASE and KEY-LEASE ranges.
227  * @retval  OT_ERROR_INVALID_ARGS  The LEASE or KEY-LEASE range is not valid.
228  *
229  */
230 otError otSrpServerSetLeaseConfig(otInstance *aInstance, const otSrpServerLeaseConfig *aLeaseConfig);
231 
232 /**
233  * This function handles SRP service updates.
234  *
235  * This function is called by the SRP server to notify that a SRP host and possibly SRP services
236  * are being updated. It is important that the SRP updates are not committed until the handler
237  * returns the result by calling otSrpServerHandleServiceUpdateResult or times out after @p aTimeout.
238  *
239  * A SRP service observer should always call otSrpServerHandleServiceUpdateResult with error code
240  * OT_ERROR_NONE immediately after receiving the update events.
241  *
242  * A more generic handler may perform validations on the SRP host/services and rejects the SRP updates
243  * if any validation fails. For example, an Advertising Proxy should advertise (or remove) the host and
244  * services on a multicast-capable link and returns specific error code if any failure occurs.
245  *
246  * @param[in]  aId       The service update transaction ID. This ID must be passed back with
247  *                       `otSrpServerHandleServiceUpdateResult`.
248  * @param[in]  aHost     A pointer to the otSrpServerHost object which contains the SRP updates. The
249  *                       handler should publish/un-publish the host and each service points to this
250  *                       host with below rules:
251  *                         1. If the host is not deleted (indicated by `otSrpServerHostIsDeleted`),
252  *                            then it should be published or updated with mDNS. Otherwise, the host
253  *                            should be un-published (remove AAAA RRs).
254  *                         2. For each service points to this host, it must be un-published if the host
255  *                            is to be un-published. Otherwise, the handler should publish or update the
256  *                            service when it is not deleted (indicated by `otSrpServerServiceIsDeleted`)
257  *                            and un-publish it when deleted.
258  * @param[in]  aTimeout  The maximum time in milliseconds for the handler to process the service event.
259  * @param[in]  aContext  A pointer to application-specific context.
260  *
261  * @sa otSrpServerSetServiceUpdateHandler
262  * @sa otSrpServerHandleServiceUpdateResult
263  *
264  */
265 typedef void (*otSrpServerServiceUpdateHandler)(otSrpServerServiceUpdateId aId,
266                                                 const otSrpServerHost *    aHost,
267                                                 uint32_t                   aTimeout,
268                                                 void *                     aContext);
269 
270 /**
271  * This function sets the SRP service updates handler on SRP server.
272  *
273  * @param[in]  aInstance        A pointer to an OpenThread instance.
274  * @param[in]  aServiceHandler  A pointer to a service handler. Use NULL to remove the handler.
275  * @param[in]  aContext         A pointer to arbitrary context information.
276  *                              May be NULL if not used.
277  *
278  */
279 void otSrpServerSetServiceUpdateHandler(otInstance *                    aInstance,
280                                         otSrpServerServiceUpdateHandler aServiceHandler,
281                                         void *                          aContext);
282 
283 /**
284  * This function reports the result of processing a SRP update to the SRP server.
285  *
286  * The Service Update Handler should call this function to return the result of its
287  * processing of a SRP update.
288  *
289  * @param[in]  aInstance  A pointer to an OpenThread instance.
290  * @param[in]  aId        The service update transaction ID. This should be the same ID
291  *                        provided via `otSrpServerServiceUpdateHandler`.
292  * @param[in]  aError     An error to be returned to the SRP server. Use OT_ERROR_DUPLICATED
293  *                        to represent DNS name conflicts.
294  *
295  */
296 void otSrpServerHandleServiceUpdateResult(otInstance *aInstance, otSrpServerServiceUpdateId aId, otError aError);
297 
298 /**
299  * This function returns the next registered host on the SRP server.
300  *
301  * @param[in]  aInstance  A pointer to an OpenThread instance.
302  * @param[in]  aHost      A pointer to current host; use NULL to get the first host.
303  *
304  * @returns  A pointer to the registered host. NULL, if no more hosts can be found.
305  *
306  */
307 const otSrpServerHost *otSrpServerGetNextHost(otInstance *aInstance, const otSrpServerHost *aHost);
308 
309 /**
310  * This function tells if the SRP service host has been deleted.
311  *
312  * A SRP service host can be deleted but retains its name for future uses.
313  * In this case, the host instance is not removed from the SRP server/registry.
314  *
315  * @param[in]  aHost  A pointer to the SRP service host.
316  *
317  * @returns  TRUE if the host has been deleted, FALSE if not.
318  *
319  */
320 bool otSrpServerHostIsDeleted(const otSrpServerHost *aHost);
321 
322 /**
323  * This function returns the full name of the host.
324  *
325  * @param[in]  aHost  A pointer to the SRP service host.
326  *
327  * @returns  A pointer to the null-terminated host name string.
328  *
329  */
330 const char *otSrpServerHostGetFullName(const otSrpServerHost *aHost);
331 
332 /**
333  * This function returns the addresses of given host.
334  *
335  * @param[in]   aHost          A pointer to the SRP service host.
336  * @param[out]  aAddressesNum  A pointer to where we should output the number of the addresses to.
337  *
338  * @returns  A pointer to the array of IPv6 Address.
339  *
340  */
341 const otIp6Address *otSrpServerHostGetAddresses(const otSrpServerHost *aHost, uint8_t *aAddressesNum);
342 
343 /**
344  * This function returns the next service (excluding any sub-type services) of given host.
345  *
346  * @note This function is being deprecated and will be removed. `otSrpServerHostFindNextService()` can be used
347  *       instead.
348  *
349  * @param[in]  aHost     A pointer to the SRP service host.
350  * @param[in]  aService  A pointer to current SRP service instance; use NULL to get the first service.
351  *
352  * @returns  A pointer to the next service or NULL if there is no more services.
353  *
354  */
355 const otSrpServerService *otSrpServerHostGetNextService(const otSrpServerHost *   aHost,
356                                                         const otSrpServerService *aService);
357 
358 /**
359  * This function finds the next matching service on the host.
360  *
361  * The combination of flags and service and instance names enables iterating over the full list of services and/or a
362  * subset of them matching certain conditions, or finding a specific service.
363  *
364  * To iterate over all services of a host:
365  *   service = otSrpServerHostFindNextService(host, service, OT_SRP_SERVER_FLAGS_ANY_SERVICE, NULL, NULL);
366  *
367  * To iterate over base services only (exclude sub-types):
368  *   service = otSrpServerHostFindNextService(host, service, OT_SRP_SERVER_FLAGS_BASE_TYPE_SERVICE_ONLY, NULL, NULL);
369  *
370  * To iterate over sub-types of a specific instance name `instanceName`:
371  *   service = otSrpServerHostFindNextService(host, service, OT_SRP_SERVER_FLAGS_SUB_TYPE_SERVICE_ONLY, NULL,
372  *                                            insatnceName);
373  *
374  * To find a specific service with service name `serviceName` and service instance name `instanceName`:
375  *   service = otSrpServerHostFindNextService(host, NULL, OT_SRP_SERVER_FLAGS_ANY_SERVICE, serviceName, instanceName);
376  *
377  * To find the base type service with a given service instance name `instanceName`:
378  *   service = otSrpServerHostFindNextService(host, NULL, OT_SRP_SERVER_FLAGS_BASE_TYPE_SERVICE_ONLY, NULL,
379  *                                            instanceName);
380  *
381  * @param[in] aHost          A pointer to the SRP service host (MUST NOT be NULL).
382  * @param[in] aPrevService   A pointer to the previous service or NULL to start from the beginning of the list.
383  * @param[in] aFlags         Flags indicating which services to include (base/sub-type, active/deleted).
384  * @param[in] aServiceName   The service name to match. Set to NULL to accept any name.
385  * @param[in] aInstanceName  The service instance name to match. Set to NULL to accept any name.
386  *
387  * @returns  A pointer to the next matching service or NULL if no matching service could be found.
388  *
389  */
390 const otSrpServerService *otSrpServerHostFindNextService(const otSrpServerHost *   aHost,
391                                                          const otSrpServerService *aPrevService,
392                                                          otSrpServerServiceFlags   aFlags,
393                                                          const char *              aServiceName,
394                                                          const char *              aInstanceName);
395 
396 /**
397  * This function indicates whether or not the SRP service has been deleted.
398  *
399  * A SRP service can be deleted but retains its name for future uses.
400  * In this case, the service instance is not removed from the SRP server/registry.
401  * It is guaranteed that all services are deleted if the host is deleted.
402  *
403  * @param[in]  aService  A pointer to the SRP service.
404  *
405  * @returns  TRUE if the service has been deleted, FALSE if not.
406  *
407  */
408 bool otSrpServerServiceIsDeleted(const otSrpServerService *aService);
409 
410 /**
411  * This function indicates whether or not the SRP service is sub-type.
412  *
413  * @param[in]  aService  A pointer to the SRP service.
414  *
415  * @returns  TRUE if the service is a sub-type, FALSE if not.
416  *
417  */
418 bool otSrpServerServiceIsSubType(const otSrpServerService *aService);
419 
420 /**
421  * This function returns the full service instance name of the service.
422  *
423  * @note This function is being deprecated and will be removed. `otSrpServerServiceGetInstanceName()` can be used
424  *       instead.
425  *
426  * @param[in]  aService  A pointer to the SRP service.
427  *
428  * @returns  A pointer to the null-terminated service instance name string.
429  *
430  */
431 const char *otSrpServerServiceGetFullName(const otSrpServerService *aService);
432 
433 /**
434  * This function returns the full service instance name of the service.
435  *
436  * @param[in]  aService  A pointer to the SRP service.
437  *
438  * @returns  A pointer to the null-terminated service instance name string.
439  *
440  */
441 const char *otSrpServerServiceGetInstanceName(const otSrpServerService *aService);
442 
443 /**
444  * This function returns the full service name of the service.
445  *
446  * @param[in]  aService  A pointer to the SRP service.
447  *
448  * @returns  A pointer to the null-terminated service name string.
449  *
450  */
451 const char *otSrpServerServiceGetServiceName(const otSrpServerService *aService);
452 
453 /**
454  * This function gets the sub-type label from service name.
455  *
456  * This function is intended to be used when the @p aService is a sub-type, i.e., `otSrpServerServiceIsSubType()` for
457  * the service returns TRUE. If it is not a sub-type this function returns `OT_ERROR_INVALID_ARGS`.
458  *
459  * The full service name for a sub-type service follows "<sub-label>._sub.<service-labels>.<domain>.". This function
460  * copies the `<sub-label>` into the @p aLabel buffer.
461  *
462  * The @p aLabel is ensured to always be null-terminated after returning even in case of failure.
463  *
464  * @param[in]  aService           A pointer to the SRP service.
465  * @param[out] aLabel             A pointer to a buffer to copy the sub-type label name into.
466  * @param[in]  aMaxSize           Maximum size of @p aLabel buffer.
467  *
468  * @retval OT_ERROR_NONE          @p aLabel was updated successfully.
469  * @retval OT_ERROR_NO_BUFS       The sub-type label could not fit in @p aLabel buffer (number of chars from label
470  *                                that could fit are copied in @p aLabel ensuring it is null-terminated).
471  * @retval OT_ERROR_INVALID_ARGS  SRP service is not a sub-type.
472  *
473  */
474 otError otSrpServerServiceGetServiceSubTypeLabel(const otSrpServerService *aService, char *aLabel, uint8_t aMaxSize);
475 
476 /**
477  * This function returns the port of the service instance.
478  *
479  * @param[in]  aService  A pointer to the SRP service.
480  *
481  * @returns  The port of the service.
482  *
483  */
484 uint16_t otSrpServerServiceGetPort(const otSrpServerService *aService);
485 
486 /**
487  * This function returns the weight of the service instance.
488  *
489  * @param[in]  aService  A pointer to the SRP service.
490  *
491  * @returns  The weight of the service.
492  *
493  */
494 uint16_t otSrpServerServiceGetWeight(const otSrpServerService *aService);
495 
496 /**
497  * This function returns the priority of the service instance.
498  *
499  * @param[in]  aService  A pointer to the SRP service.
500  *
501  * @returns  The priority of the service.
502  *
503  */
504 uint16_t otSrpServerServiceGetPriority(const otSrpServerService *aService);
505 
506 /**
507  * This function returns the TXT record data of the service instance.
508  *
509  * @param[in]  aService        A pointer to the SRP service.
510  * @param[out] aDataLength     A pointer to return the TXT record data length. MUST NOT be NULL.
511  *
512  * @returns A pointer to the buffer containing the TXT record data (the TXT data length is returned in @p aDataLength).
513  *
514  */
515 const uint8_t *otSrpServerServiceGetTxtData(const otSrpServerService *aService, uint16_t *aDataLength);
516 
517 /**
518  * This function returns the host which the service instance reside on.
519  *
520  * @param[in]  aService  A pointer to the SRP service.
521  *
522  * @returns  A pointer to the host instance.
523  *
524  */
525 const otSrpServerHost *otSrpServerServiceGetHost(const otSrpServerService *aService);
526 
527 /**
528  * @}
529  *
530  */
531 
532 #ifdef __cplusplus
533 } // extern "C"
534 #endif
535 
536 #endif // OPENTHREAD_SRP_SERVER_H_
537