lib audit_logging: re-factor and add functions.
[samba.git] / lib / audit_logging / audit_logging.c
1 /*
2    common routines for audit logging
3
4    Copyright (C) Andrew Bartlett <abartlet@samba.org> 2018
5
6    This program is free software; you can redistribute it and/or modify
7    it under the terms of the GNU General Public License as published by
8    the Free Software Foundation; either version 3 of the License, or
9    (at your option) any later version.
10
11    This program is distributed in the hope that it will be useful,
12    but WITHOUT ANY WARRANTY; without even the implied warranty of
13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14    GNU General Public License for more details.
15
16    You should have received a copy of the GNU General Public License
17    along with this program.  If not, see <http://www.gnu.org/licenses/>.
18 */
19
20 /*
21  * Error handling:
22  *
23  * The json_object structure contains a boolean 'error'.  This is set whenever
24  * an error is detected. All the library functions check this flag and return
25  * immediately if it is set.
26  *
27  *      if (object->error) {
28  *              return;
29  *      }
30  *
31  * This allows the operations to be sequenced naturally with out the clutter
32  * of error status checks.
33  *
34  *      audit = json_new_object();
35  *      json_add_version(&audit, OPERATION_MAJOR, OPERATION_MINOR);
36  *      json_add_int(&audit, "statusCode", ret);
37  *      json_add_string(&audit, "status", ldb_strerror(ret));
38  *      json_add_string(&audit, "operation", operation);
39  *      json_add_address(&audit, "remoteAddress", remote);
40  *      json_add_sid(&audit, "userSid", sid);
41  *      json_add_string(&audit, "dn", dn);
42  *      json_add_guid(&audit, "transactionId", &ac->transaction_guid);
43  *      json_add_guid(&audit, "sessionId", unique_session_token);
44  *
45  * The assumptions are that errors will be rare, and that the audit logging
46  * code should not cause failures. So errors are logged but processing
47  * continues on a best effort basis.
48  */
49
50 #include "includes.h"
51
52 #include "librpc/ndr/libndr.h"
53 #include "lib/tsocket/tsocket.h"
54 #include "libcli/security/dom_sid.h"
55 #include "lib/messaging/messaging.h"
56 #include "auth/common_auth.h"
57 #include "audit_logging.h"
58
59 /*
60  * @brief Get a human readable timestamp.
61  *
62  * Returns the current time formatted as
63  *  "Tue, 14 Mar 2017 08:38:42.209028 NZDT"
64  *
65  * The returned string is allocated by talloc in the supplied context.
66  * It is the callers responsibility to free it.
67  *
68  * @param mem_ctx talloc memory context that owns the returned string.
69  *
70  * @return a human readable time stamp.
71  *
72  */
73 char* audit_get_timestamp(TALLOC_CTX *frame)
74 {
75         char buffer[40];        /* formatted time less usec and timezone */
76         char tz[10];            /* formatted time zone                   */
77         struct tm* tm_info;     /* current local time                    */
78         struct timeval tv;      /* current system time                   */
79         int r;                  /* response code from gettimeofday       */
80         char * ts;              /* formatted time stamp                  */
81
82         r = gettimeofday(&tv, NULL);
83         if (r) {
84                 DBG_ERR("Unable to get time of day: (%d) %s\n",
85                         errno,
86                         strerror(errno));
87                 return NULL;
88         }
89
90         tm_info = localtime(&tv.tv_sec);
91         if (tm_info == NULL) {
92                 DBG_ERR("Unable to determine local time\n");
93                 return NULL;
94         }
95
96         strftime(buffer, sizeof(buffer)-1, "%a, %d %b %Y %H:%M:%S", tm_info);
97         strftime(tz, sizeof(tz)-1, "%Z", tm_info);
98         ts = talloc_asprintf(frame, "%s.%06ld %s", buffer, tv.tv_usec, tz);
99         if (ts == NULL) {
100                 DBG_ERR("Out of memory formatting time stamp\n");
101         }
102         return ts;
103 }
104
105 /*
106  * @brief write an audit message to the audit logs.
107  *
108  * Write a human readable text audit message to the samba logs.
109  *
110  * @param prefix Text to be printed at the start of the log line
111  * @param message The content of the log line.
112  * @param debub_class The debug class to log the message with.
113  * @param debug_level The debug level to log the message with.
114  */
115 void audit_log_human_text(const char* prefix,
116                           const char* message,
117                           int debug_class,
118                           int debug_level)
119 {
120         DEBUGC(debug_class, debug_level, ("%s %s\n", prefix, message));
121 }
122
123 #ifdef HAVE_JANSSON
124 /*
125  * @brief write a json object to the samba audit logs.
126  *
127  * Write the json object to the audit logs as a formatted string
128  *
129  * @param prefix Text to be printed at the start of the log line
130  * @param message The content of the log line.
131  * @param debub_class The debug class to log the message with.
132  * @param debug_level The debug level to log the message with.
133  */
134 void audit_log_json(
135         const char* prefix,
136         struct json_object* message,
137         int debug_class,
138         int debug_level)
139 {
140         TALLOC_CTX *ctx = talloc_new(NULL);
141         char *s = json_to_string(ctx, message);
142         DEBUGC(debug_class, debug_level, ("JSON %s: %s\n", prefix, s));
143         TALLOC_FREE(ctx);
144 }
145
146 /*
147  * @brief get a connection to the messaging event server.
148  *
149  * Get a connection to the messaging event server registered by server_name.
150  *
151  * @param msg_ctx a valid imessaging_context.
152  * @param server_name name of messaging event server to connect to.
153  * @param server_id The event server details to populate
154  *
155  * @return NTSTATUS
156  */
157 static NTSTATUS get_event_server(
158         struct imessaging_context *msg_ctx,
159         const char *server_name,
160         struct server_id *event_server)
161 {
162         NTSTATUS status;
163         TALLOC_CTX *frame = talloc_stackframe();
164         unsigned num_servers, i;
165         struct server_id *servers;
166
167         status = irpc_servers_byname(
168                 msg_ctx,
169                 frame,
170                 server_name,
171                 &num_servers,
172                 &servers);
173
174         if (!NT_STATUS_IS_OK(status)) {
175                 DBG_NOTICE(
176                         "Failed to find '%s' registered on the message bus to "
177                         "send audit events to: %s\n",
178                         server_name,
179                         nt_errstr(status));
180                 TALLOC_FREE(frame);
181                 return status;
182         }
183
184         /*
185          * Select the first server that is listening, because we get
186          * connection refused as NT_STATUS_OBJECT_NAME_NOT_FOUND
187          * without waiting
188          */
189         for (i = 0; i < num_servers; i++) {
190                 status = imessaging_send(
191                         msg_ctx,
192                         servers[i],
193                         MSG_PING,
194                         &data_blob_null);
195                 if (NT_STATUS_IS_OK(status)) {
196                         *event_server = servers[i];
197                         TALLOC_FREE(frame);
198                         return NT_STATUS_OK;
199                 }
200         }
201         DBG_NOTICE(
202                 "Failed to find '%s' registered on the message bus to "
203                 "send audit events to: %s\n",
204                 server_name,
205                 nt_errstr(status));
206         TALLOC_FREE(frame);
207         return NT_STATUS_OBJECT_NAME_NOT_FOUND;
208 }
209
210 /*
211  * @brief send an audit message to a messaging event server.
212  *
213  * Send the message to a registered and listening event server.
214  * Note: Any errors are logged, and the message is not sent.  This is to ensure
215  *       that a poorly behaved event server does not impact Samba.
216  *
217  *       As it is possible to lose messages, especially during server
218  *       shut down, currently this function is primarily intended for use
219  *       in integration tests.
220  *
221  * @param msg_ctx an imessaging_context, can be NULL in which case no message
222  *                will be sent.
223  * @param server_name the naname of the event server to send the message to.
224  * @param messag_type A message type defined in librpc/idl/messaging.idl
225  * @param message The message to send.
226  *
227  */
228 void audit_message_send(
229         struct imessaging_context *msg_ctx,
230         const char *server_name,
231         uint32_t message_type,
232         struct json_object *message)
233 {
234         struct server_id event_server;
235         NTSTATUS status;
236
237         const char *message_string = NULL;
238         DATA_BLOB message_blob = data_blob_null;
239         TALLOC_CTX *ctx = talloc_new(NULL);
240
241         if (msg_ctx == NULL) {
242                 DBG_DEBUG("No messaging context\n");
243                 TALLOC_FREE(ctx);
244                 return;
245         }
246
247         /* Need to refetch the address each time as the destination server may
248          * have disconnected and reconnected in the interim, in which case
249          * messages may get lost
250          */
251         status = get_event_server(msg_ctx, server_name, &event_server);
252         if (!NT_STATUS_IS_OK(status) &&
253             !NT_STATUS_EQUAL(status, NT_STATUS_OBJECT_NAME_NOT_FOUND)) {
254                 DBG_ERR("get_event_server for %s returned (%s)\n",
255                         server_name,
256                         nt_errstr(status));
257                 TALLOC_FREE(ctx);
258                 return;
259         }
260
261         message_string = json_to_string(ctx, message);
262         message_blob = data_blob_string_const(message_string);
263         status = imessaging_send(
264                 msg_ctx,
265                 event_server,
266                 message_type,
267                 &message_blob);
268
269         /*
270          * If the server crashed, try to find it again
271          */
272         if (NT_STATUS_EQUAL(status, NT_STATUS_OBJECT_NAME_NOT_FOUND)) {
273                 status = get_event_server(msg_ctx, server_name, &event_server);
274                 if (!NT_STATUS_IS_OK(status) &&
275                     !NT_STATUS_EQUAL(status, NT_STATUS_OBJECT_NAME_NOT_FOUND)) {
276                         DBG_ERR("get_event_server for %s returned (%s)\n",
277                                 server_name,
278                                 nt_errstr(status));
279                         TALLOC_FREE(ctx);
280                         return;
281                 }
282                 imessaging_send(
283                         msg_ctx,
284                         event_server,
285                         message_type,
286                         &message_blob);
287         }
288         TALLOC_FREE(ctx);
289 }
290
291 /*
292  * @brief Create a new struct json_object, wrapping a JSON Object.
293  *
294  * Create a new json object, the json_object wraps the underlying json
295  * implementations JSON Object representation.
296  *
297  * Free with a call to json_free_object, note that the jansson inplementation
298  * allocates memory with malloc and not talloc.
299  *
300  * @return a struct json_object, error will be set to true if the object
301  *         could not be created.
302  *
303  */
304 struct json_object json_new_object(void) {
305
306         struct json_object object;
307         object.error = false;
308
309         object.root = json_object();
310         if (object.root == NULL) {
311                 object.error = true;
312                 DBG_ERR("Unable to create json_object\n");
313         }
314         return object;
315 }
316
317 /*
318  * @brief Create a new struct json_object wrapping a JSON Array.
319  *
320  * Create a new json object, the json_object wraps the underlying json
321  * implementations JSON Array representation.
322  *
323  * Free with a call to json_free_object, note that the jansson inplementation
324  * allocates memory with malloc and not talloc.
325  *
326  * @return a struct json_object, error will be set to true if the array
327  *         could not be created.
328  *
329  */
330 struct json_object json_new_array(void) {
331
332         struct json_object array;
333         array.error = false;
334
335         array.root = json_array();
336         if (array.root == NULL) {
337                 array.error = true;
338                 DBG_ERR("Unable to create json_array\n");
339         }
340         return array;
341 }
342
343
344 /*
345  * @brief free and invalidate a previously created JSON object.
346  *
347  * Release any resources owned by a json_object, and then mark the structure
348  * as invalid.  It is safe to call this multiple times on an object.
349  *
350  */
351 void json_free(struct json_object *object)
352 {
353         if (object->root != NULL) {
354                 json_decref(object->root);
355         }
356         object->root = NULL;
357         object->error = true;
358 }
359
360 /*
361  * @brief is the current JSON object invalid?
362  *
363  * Check the state of the object to determine if it is invalid.
364  *
365  * @return is the object valid?
366  *
367  */
368 bool json_is_invalid(struct json_object *object)
369 {
370         return object->error;
371 }
372
373 /*
374  * @brief Add an integer value to a JSON object.
375  *
376  * Add an integer value named 'name' to the json object.
377  * In the event of an error object will be invalidated.
378  *
379  * @param object the JSON object to be updated.
380  * @param name the name of the value.
381  * @param value the value.
382  *
383  */
384 void json_add_int(struct json_object *object,
385                   const char* name,
386                   const int value)
387 {
388         int rc = 0;
389
390         if (object->error) {
391                 return;
392         }
393
394         rc = json_object_set_new(object->root, name, json_integer(value));
395         if (rc) {
396                 DBG_ERR("Unable to set name [%s] value [%d]\n", name, value);
397                 object->error = true;
398         }
399 }
400
401 /*
402  * @brief Add a boolean value to a JSON object.
403  *
404  * Add a boolean value named 'name' to the json object.
405  * In the event of an error object will be invalidated.
406  *
407  * @param object the JSON object to be updated.
408  * @param name the name.
409  * @param value the value.
410  *
411  */
412 void json_add_bool(struct json_object *object,
413                    const char* name,
414                    const bool value)
415 {
416         int rc = 0;
417
418         if (object->error) {
419                 return;
420         }
421
422         rc = json_object_set_new(object->root, name, json_boolean(value));
423         if (rc) {
424                 DBG_ERR("Unable to set name [%s] value [%d]\n", name, value);
425                 object->error = true;
426         }
427
428 }
429
430 /*
431  * @brief Add a string value to a JSON object.
432  *
433  * Add a string value named 'name' to the json object.
434  * In the event of an error object will be invalidated.
435  *
436  * @param object the JSON object to be updated.
437  * @param name the name.
438  * @param value the value.
439  *
440  */
441 void json_add_string(struct json_object *object,
442                      const char* name,
443                      const char* value)
444 {
445         int rc = 0;
446
447         if (object->error) {
448                 return;
449         }
450
451         if (value) {
452                 rc = json_object_set_new(
453                         object->root,
454                         name,
455                         json_string(value));
456         } else {
457                 rc = json_object_set_new(object->root, name, json_null());
458         }
459         if (rc) {
460                 DBG_ERR("Unable to set name [%s] value [%s]\n", name, value);
461                 object->error = true;
462         }
463 }
464
465 /*
466  * @brief Assert that the current JSON object is an array.
467  *
468  * Check that the current object is a JSON array, and if not
469  * invalidate the object. We also log an error message as this indicates
470  * bug in the calling code.
471  *
472  * @param object the JSON object to be validated.
473  */
474 void json_assert_is_array(struct json_object *array) {
475
476         if (array->error) {
477                 return;
478         }
479
480         if (json_is_array(array->root) == false) {
481                 DBG_ERR("JSON object is not an array\n");
482                 array->error = true;
483                 return;
484         }
485 }
486
487 /*
488  * @brief Add a JSON object to a JSON object.
489  *
490  * Add a JSON object named 'name' to the json object.
491  * In the event of an error object will be invalidated.
492  *
493  * @param object the JSON object to be updated.
494  * @param name the name.
495  * @param value the value.
496  *
497  */
498 void json_add_object(struct json_object *object,
499                 const char* name,
500                 struct json_object *value)
501 {
502         int rc = 0;
503         json_t *jv = NULL;
504
505         if (object->error) {
506                 return;
507         }
508
509         if (value != NULL && value->error) {
510                 object->error = true;
511                 return;
512         }
513
514         jv = value == NULL ? json_null() : value->root;
515
516         if (json_is_array(object->root)) {
517                 rc = json_array_append_new(object->root, jv);
518         } else if (json_is_object(object->root)) {
519                 rc = json_object_set_new(object->root, name,  jv);
520         } else {
521                 DBG_ERR("Invalid JSON object type\n");
522                 object->error = true;
523         }
524         if (rc) {
525                 DBG_ERR("Unable to add object [%s]\n", name);
526                 object->error = true;
527         }
528 }
529
530 /*
531  * @brief Add a string to a JSON object, truncating if necessary.
532  *
533  *
534  * Add a string value named 'name' to the json object, the string will be
535  * truncated if it is more than len characters long. If len is 0 the value
536  * is encoded as a JSON null.
537  *
538  * In the event of an error object will be invalidated.
539  *
540  * @param object the JSON object to be updated.
541  * @param name the name.
542  * @param value the value.
543  * @param len the maximum number of characters to be copied.
544  *
545  */
546 void json_add_stringn(
547         struct json_object *object,
548         const char *name,
549         const char *value,
550         const size_t len)
551 {
552
553         int rc = 0;
554         if (object->error) {
555                 return;
556         }
557
558         if (value != NULL && len > 0) {
559                 char buffer[len+1];
560                 strncpy(buffer, value, len);
561                 buffer[len] = '\0';
562                 rc = json_object_set_new(object->root,
563                                          name,
564                                          json_string(buffer));
565         } else {
566                 rc = json_object_set_new(object->root, name, json_null());
567         }
568         if (rc) {
569                 DBG_ERR("Unable to set name [%s] value [%s]\n", name, value);
570                 object->error = true;
571         }
572 }
573
574 /*
575  * @brief Add a version object to a JSON object
576  *
577  * Add a version object to the JSON object
578  *      "version":{"major":1, "minor":0}
579  *
580  * The version tag is intended to aid the processing of the JSON messages
581  * The major version number should change when an attribute is:
582  *  - renamed
583  *  - removed
584  *  - its meaning changes
585  *  - its contents change format
586  * The minor version should change whenever a new attribute is added and for
587  * minor bug fixes to an attributes content.
588  *
589  * In the event of an error object will be invalidated.
590  *
591  * @param object the JSON object to be updated.
592  * @param major the major version number
593  * @param minor the minor version number
594  */
595 void json_add_version(struct json_object *object, int major, int minor)
596 {
597         struct json_object version = json_new_object();
598         json_add_int(&version, "major", major);
599         json_add_int(&version, "minor", minor);
600         json_add_object(object, "version", &version);
601 }
602
603 /*
604  * @brief add an ISO 8601 timestamp to the object.
605  *
606  * Add the current date and time as a timestamp in ISO 8601 format
607  * to a JSON object
608  *
609  * "timestamp":"2017-03-06T17:18:04.455081+1300"
610  *
611  * In the event of an error object will be invalidated.
612  *
613  * @param object the JSON object to be updated.
614  */
615 void json_add_timestamp(struct json_object *object)
616 {
617         char buffer[40];        /* formatted time less usec and timezone */
618         char timestamp[65];     /* the formatted ISO 8601 time stamp     */
619         char tz[10];            /* formatted time zone                   */
620         struct tm* tm_info;     /* current local time                    */
621         struct timeval tv;      /* current system time                   */
622         int r;                  /* response code from gettimeofday       */
623
624         if (object->error) {
625                 return;
626         }
627
628         r = gettimeofday(&tv, NULL);
629         if (r) {
630                 DBG_ERR("Unable to get time of day: (%d) %s\n",
631                         errno,
632                         strerror(errno));
633                 object->error = true;
634                 return;
635         }
636
637         tm_info = localtime(&tv.tv_sec);
638         if (tm_info == NULL) {
639                 DBG_ERR("Unable to determine local time\n");
640                 object->error = true;
641                 return;
642         }
643
644         strftime(buffer, sizeof(buffer)-1, "%Y-%m-%dT%T", tm_info);
645         strftime(tz, sizeof(tz)-1, "%z", tm_info);
646         snprintf(
647                 timestamp,
648                 sizeof(timestamp),
649                 "%s.%06ld%s",
650                 buffer,
651                 tv.tv_usec,
652                 tz);
653         json_add_string(object, "timestamp", timestamp);
654 }
655
656
657 /*
658  *@brief Add a tsocket_address to a JSON object
659  *
660  * Add the string representation of a Samba tsocket_address to the object.
661  *
662  * "localAddress":"ipv6::::0"
663  *
664  * In the event of an error object will be invalidated.
665  *
666  * @param object the JSON object to be updated.
667  * @param name the name.
668  * @param address the tsocket_address.
669  *
670  */
671 void json_add_address(
672         struct json_object *object,
673         const char *name,
674         const struct tsocket_address *address)
675 {
676
677         if (object->error) {
678                 return;
679         }
680         if (address == NULL) {
681                 int rc = json_object_set_new(object->root, name, json_null());
682                 if (rc) {
683                         DBG_ERR("Unable to set address [%s] to null\n", name);
684                         object->error = true;
685                 }
686         } else {
687                 TALLOC_CTX *ctx = talloc_new(NULL);
688                 char *s = NULL;
689
690                 s = tsocket_address_string(address, ctx);
691                 json_add_string(object, name, s);
692                 TALLOC_FREE(ctx);
693         }
694 }
695
696 /*
697  * @brief Add a formatted string representation of a sid to a json object.
698  *
699  * Add the string representation of a Samba sid to the object.
700  *
701  * "sid":"S-1-5-18"
702  *
703  * In the event of an error object will be invalidated.
704  *
705  * @param object the JSON object to be updated.
706  * @param name the name.
707  * @param sid the sid
708  *
709  */
710 void json_add_sid(
711         struct json_object *object,
712         const char *name,
713         const struct dom_sid *sid)
714 {
715
716         if (object->error) {
717                 return;
718         }
719         if (sid == NULL) {
720                 int rc = json_object_set_new(object->root, name, json_null());
721                 if (rc) {
722                         DBG_ERR("Unable to set SID [%s] to null\n", name);
723                         object->error = true;
724                 }
725         } else {
726                 char sid_buf[DOM_SID_STR_BUFLEN];
727
728                 dom_sid_string_buf(sid, sid_buf, sizeof(sid_buf));
729                 json_add_string(object, name, sid_buf);
730         }
731 }
732
733 /*
734  * @brief Add a formatted string representation of a guid to a json object.
735  *
736  * Add the string representation of a Samba GUID to the object.
737  *
738  * "guid":"1fb9f2ee-2a4d-4bf8-af8b-cb9d4529a9ab"
739  *
740  * In the event of an error object will be invalidated.
741  *
742  * @param object the JSON object to be updated.
743  * @param name the name.
744  * @param guid the guid.
745  *
746  *
747  */
748 void json_add_guid(
749         struct json_object *object,
750         const char *name,
751         const struct GUID *guid)
752 {
753
754
755         if (object->error) {
756                 return;
757         }
758         if (guid == NULL) {
759                 int rc = json_object_set_new(object->root, name, json_null());
760                 if (rc) {
761                         DBG_ERR("Unable to set GUID [%s] to null\n", name);
762                         object->error = true;
763                 }
764         } else {
765                 char *guid_str;
766                 struct GUID_txt_buf guid_buff;
767
768                 guid_str = GUID_buf_string(guid, &guid_buff);
769                 json_add_string(object, name, guid_str);
770         }
771 }
772
773
774 /*
775  * @brief Convert a JSON object into a string
776  *
777  * Convert the jsom object into a string suitable for printing on a log line,
778  * i.e. with no embedded line breaks.
779  *
780  * If the object is invalid it returns NULL.
781  *
782  * @param mem_ctx the talloc memory context owning the returned string
783  * @param object the json object.
784  *
785  * @return A string representation of the object or NULL if the object
786  *         is invalid.
787  */
788 char *json_to_string(TALLOC_CTX *mem_ctx, struct json_object *object)
789 {
790         char *json = NULL;
791         char *json_string = NULL;
792
793         if (object->error) {
794                 return NULL;
795         }
796
797         /*
798          * json_dumps uses malloc, so need to call free(json) to release
799          * the memory
800          */
801         json = json_dumps(object->root, 0);
802         if (json == NULL) {
803                 DBG_ERR("Unable to convert JSON object to string\n");
804                 return NULL;
805         }
806
807         json_string = talloc_strdup(mem_ctx, json);
808         if (json_string == NULL) {
809                 free(json);
810                 DBG_ERR("Unable to copy JSON object string to talloc string\n");
811                 return NULL;
812         }
813         free(json);
814
815         return json_string;
816 }
817
818 /*
819  * @brief get a json array named "name" from the json object.
820  *
821  * Get the array attribute named name, creating it if it does not exist.
822  *
823  * @param object the json object.
824  * @param name the name of the array attribute
825  *
826  * @return The array object, will be created if it did not exist.
827  */
828 struct json_object json_get_array(struct json_object *object, const char* name)
829 {
830
831         struct json_object array = json_new_array();
832         json_t *a = NULL;
833
834         if (object->error) {
835                 array.error = true;
836                 return array;
837         }
838
839         a = json_object_get(object->root, name);
840         if (a == NULL) {
841                 return array;
842         }
843         json_array_extend(array.root, a);
844
845         return array;
846 }
847
848 /*
849  * @brief get a json object named "name" from the json object.
850  *
851  * Get the object attribute named name, creating it if it does not exist.
852  *
853  * @param object the json object.
854  * @param name the name of the object attribute
855  *
856  * @return The object, will be created if it did not exist.
857  */
858 struct json_object json_get_object(struct json_object *object, const char* name)
859 {
860
861         struct json_object o = json_new_object();
862         json_t *v = NULL;
863
864         if (object->error) {
865                 o.error = true;
866                 return o;
867         }
868
869         v = json_object_get(object->root, name);
870         if (v == NULL) {
871                 return o;
872         }
873         json_object_update(o.root, v);
874
875         return o;
876 }
877 #endif