lib/util/data_blob.h

   1 /*
   2    Unix SMB/CIFS implementation.
   3    DATA BLOB
   4
   5    Copyright (C) Andrew Tridgell 2001
   6    Copyright (C) Andrew Bartlett 2001
   7
   8    This program is free software; you can redistribute it and/or modify
   9    it under the terms of the GNU General Public License as published by
  10    the Free Software Foundation; either version 3 of the License, or
  11    (at your option) any later version.
  12
  13    This program is distributed in the hope that it will be useful,
  14    but WITHOUT ANY WARRANTY; without even the implied warranty of
  15    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16    GNU General Public License for more details.
  17
  18    You should have received a copy of the GNU General Public License
  19    along with this program.  If not, see <http://www.gnu.org/licenses/>.
  20 */
  21
  22 /* This is a public header file that is installed as part of Samba.
  23  * If you remove any functions or change their signature, update
  24  * the so version number. */
  25
  26 #ifndef _SAMBA_DATABLOB_H_
  27 #define _SAMBA_DATABLOB_H_
  28
  29 #ifndef _PUBLIC_
  30 #define _PUBLIC_
  31 #endif
  32
  33 #include <talloc.h>
  34 #include <stdbool.h>
  35 #include <stdint.h>
  36
  37 /* used to hold an arbitrary blob of data */
  38 typedef struct datablob {
  39         uint8_t *data;
  40         size_t length;
  41 } DATA_BLOB;
  42
  43 /* by making struct ldb_val and DATA_BLOB the same, we can simplify
  44    a fair bit of code */
  45 #define ldb_val datablob
  46
  47 #define data_blob(ptr, size) data_blob_named(ptr, size, "DATA_BLOB: " __location__)
  48 #define data_blob_talloc(ctx, ptr, size) data_blob_talloc_named(ctx, ptr, size, "DATA_BLOB: " __location__)
  49 #define data_blob_dup_talloc(ctx, blob) data_blob_talloc_named(ctx, (blob).data, (blob).length, "DATA_BLOB: " __location__)
  50
  51 /**
  52  construct a data blob, must be freed with data_blob_free()
  53  you can pass NULL for p and get a blank data blob
  54 **/
  55 _PUBLIC_ DATA_BLOB data_blob_named(const void *p, size_t length, const char *name);
  56
  57 /**
  58  construct a data blob, using supplied TALLOC_CTX
  59 **/
  60 _PUBLIC_ DATA_BLOB data_blob_talloc_named(TALLOC_CTX *mem_ctx, const void *p, size_t length, const char *name);
  61
  62 /**
  63  construct a zero data blob, using supplied TALLOC_CTX.
  64  use this sparingly as it initialises data - better to initialise
  65  yourself if you want specific data in the blob
  66 **/
  67 _PUBLIC_ DATA_BLOB data_blob_talloc_zero(TALLOC_CTX *mem_ctx, size_t length);
  68
  69 /**
  70 free a data blob
  71 **/
  72 _PUBLIC_ void data_blob_free(DATA_BLOB *d);
  73
  74 /**
  75 clear a DATA_BLOB's contents
  76 **/
  77 _PUBLIC_ void data_blob_clear(DATA_BLOB *d);
  78
  79 /**
  80 free a data blob and clear its contents
  81 **/
  82 _PUBLIC_ void data_blob_clear_free(DATA_BLOB *d);
  83
  84 /**
  85 check if two data blobs are equal
  86 **/
  87 _PUBLIC_ int data_blob_cmp(const DATA_BLOB *d1, const DATA_BLOB *d2);
  88
  89 /**
  90 check if two data blobs are equal, where the time taken should not depend on the
  91 contents of either blob.
  92 **/
  93 _PUBLIC_ bool data_blob_equal_const_time(const DATA_BLOB *d1, const DATA_BLOB *d2);
  94
  95 /**
  96 print the data_blob as hex string
  97 **/
  98 _PUBLIC_ char *data_blob_hex_string_upper(TALLOC_CTX *mem_ctx, const DATA_BLOB *blob);
  99
 100 /**
 101 print the data_blob as hex string
 102 **/
 103 _PUBLIC_ char *data_blob_hex_string_lower(TALLOC_CTX *mem_ctx, const DATA_BLOB *blob);
 104
 105 /**
 106   useful for constructing data blobs in test suites, while
 107   avoiding const warnings
 108 **/
 109 _PUBLIC_ DATA_BLOB data_blob_string_const(const char *str);
 110
 111 /**
 112   useful for constructing data blobs in test suites, while
 113   avoiding const warnings
 114
 115   includes the terminating null character (as opposed to data_blo_string_const)
 116 **/
 117 _PUBLIC_ DATA_BLOB data_blob_string_const_null(const char *str);
 118
 119 /**
 120  * Create a new data blob from const data
 121  */
 122 _PUBLIC_ DATA_BLOB data_blob_const(const void *p, size_t length);
 123
 124 /**
 125   realloc a data_blob
 126 **/
 127 _PUBLIC_ bool data_blob_realloc(TALLOC_CTX *mem_ctx, DATA_BLOB *blob, size_t length);
 128
 129 /**
 130   append some data to a data blob
 131 **/
 132 _PUBLIC_ bool data_blob_append(TALLOC_CTX *mem_ctx, DATA_BLOB *blob,
 133                                    const void *p, size_t length);
 134
 135 /**
 136   pad the length of a data blob to a multiple of
 137   'pad'. 'pad' must be a power of two.
 138 **/
 139 _PUBLIC_ bool data_blob_pad(TALLOC_CTX *mem_ctx, DATA_BLOB *blob,
 140                             size_t pad);
 141
 142 extern const DATA_BLOB data_blob_null;
 143
 144 #endif /* _SAMBA_DATABLOB_H_ */