← Back to branch summary

~alinuxninja/nginx-edge/trunk

« back to all changes in this revision

Viewing changes to debian/modules/ngx_pagespeed/psol/include/third_party/boringssl/src/include/openssl/bytestring.h

  • Committer: Vivian
  • Date: 2015-12-04 18:20:11 UTC
  • Revision ID: git-v1:a36f2bc32e884f7473b3a47040e5411306144d7d
* Do not extract psol.tar.gz

Show diffs side-by-side

added added

removed removed

Lines of Context:
debian/modules/ngx_pagespeed/psol/include/third_party/boringssl/src/include/openssl/bytestring.h
1
 
/* Copyright (c) 2014, Google Inc.
2
 
 *
3
 
 * Permission to use, copy, modify, and/or distribute this software for any
4
 
 * purpose with or without fee is hereby granted, provided that the above
5
 
 * copyright notice and this permission notice appear in all copies.
6
 
 *
7
 
 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
8
 
 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
9
 
 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
10
 
 * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
11
 
 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
12
 
 * OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
13
 
 * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */
14
 
 
15
 
#ifndef OPENSSL_HEADER_BYTESTRING_H
16
 
#define OPENSSL_HEADER_BYTESTRING_H
17
 
 
18
 
#include <openssl/base.h>
19
 
 
20
 
#if defined(__cplusplus)
21
 
extern "C" {
22
 
#endif
23
 
 
24
 
 
25
 
/* Bytestrings are used for parsing and building TLS and ASN.1 messages.
26
 
 *
27
 
 * A "CBS" (CRYPTO ByteString) represents a string of bytes in memory and
28
 
 * provides utility functions for safely parsing length-prefixed structures
29
 
 * like TLS and ASN.1 from it.
30
 
 *
31
 
 * A "CBB" (CRYPTO ByteBuilder) is a memory buffer that grows as needed and
32
 
 * provides utility functions for building length-prefixed messages. */
33
 
 
34
 
 
35
 
/* CRYPTO ByteString */
36
 
 
37
 
struct cbs_st {
38
 
  const uint8_t *data;
39
 
  size_t len;
40
 
};
41
 
 
42
 
/* CBS_init sets |cbs| to point to |data|. It does not take ownership of
43
 
 * |data|. */
44
 
OPENSSL_EXPORT void CBS_init(CBS *cbs, const uint8_t *data, size_t len);
45
 
 
46
 
/* CBS_skip advances |cbs| by |len| bytes. It returns one on success and zero
47
 
 * otherwise. */
48
 
OPENSSL_EXPORT int CBS_skip(CBS *cbs, size_t len);
49
 
 
50
 
/* CBS_data returns a pointer to the contents of |cbs|. */
51
 
OPENSSL_EXPORT const uint8_t *CBS_data(const CBS *cbs);
52
 
 
53
 
/* CBS_len returns the number of bytes remaining in |cbs|. */
54
 
OPENSSL_EXPORT size_t CBS_len(const CBS *cbs);
55
 
 
56
 
/* CBS_stow copies the current contents of |cbs| into |*out_ptr| and
57
 
 * |*out_len|. If |*out_ptr| is not NULL, the contents are freed with
58
 
 * OPENSSL_free. It returns one on success and zero on allocation failure. On
59
 
 * success, |*out_ptr| should be freed with OPENSSL_free. If |cbs| is empty,
60
 
 * |*out_ptr| will be NULL. */
61
 
OPENSSL_EXPORT int CBS_stow(const CBS *cbs, uint8_t **out_ptr, size_t *out_len);
62
 
 
63
 
/* CBS_strdup copies the current contents of |cbs| into |*out_ptr| as a
64
 
 * NUL-terminated C string. If |*out_ptr| is not NULL, the contents are freed
65
 
 * with OPENSSL_free. It returns one on success and zero on allocation
66
 
 * failure. On success, |*out_ptr| should be freed with OPENSSL_free.
67
 
 *
68
 
 * NOTE: If |cbs| contains NUL bytes, the string will be truncated. Call
69
 
 * |CBS_contains_zero_byte(cbs)| to check for NUL bytes. */
70
 
OPENSSL_EXPORT int CBS_strdup(const CBS *cbs, char **out_ptr);
71
 
 
72
 
/* CBS_contains_zero_byte returns one if the current contents of |cbs| contains
73
 
 * a NUL byte and zero otherwise. */
74
 
OPENSSL_EXPORT int CBS_contains_zero_byte(const CBS *cbs);
75
 
 
76
 
/* CBS_mem_equal compares the current contents of |cbs| with the |len| bytes
77
 
 * starting at |data|. If they're equal, it returns one, otherwise zero. If the
78
 
 * lengths match, it uses a constant-time comparison. */
79
 
OPENSSL_EXPORT int CBS_mem_equal(const CBS *cbs, const uint8_t *data,
80
 
                                 size_t len);
81
 
 
82
 
/* CBS_get_u8 sets |*out| to the next uint8_t from |cbs| and advances |cbs|. It
83
 
 * returns one on success and zero on error. */
84
 
OPENSSL_EXPORT int CBS_get_u8(CBS *cbs, uint8_t *out);
85
 
 
86
 
/* CBS_get_u16 sets |*out| to the next, big-endian uint16_t from |cbs| and
87
 
 * advances |cbs|. It returns one on success and zero on error. */
88
 
OPENSSL_EXPORT int CBS_get_u16(CBS *cbs, uint16_t *out);
89
 
 
90
 
/* CBS_get_u24 sets |*out| to the next, big-endian 24-bit value from |cbs| and
91
 
 * advances |cbs|. It returns one on success and zero on error. */
92
 
OPENSSL_EXPORT int CBS_get_u24(CBS *cbs, uint32_t *out);
93
 
 
94
 
/* CBS_get_u32 sets |*out| to the next, big-endian uint32_t value from |cbs|
95
 
 * and advances |cbs|. It returns one on success and zero on error. */
96
 
OPENSSL_EXPORT int CBS_get_u32(CBS *cbs, uint32_t *out);
97
 
 
98
 
/* CBS_get_bytes sets |*out| to the next |len| bytes from |cbs| and advances
99
 
 * |cbs|. It returns one on success and zero on error. */
100
 
OPENSSL_EXPORT int CBS_get_bytes(CBS *cbs, CBS *out, size_t len);
101
 
 
102
 
/* CBS_get_u8_length_prefixed sets |*out| to the contents of an 8-bit,
103
 
 * length-prefixed value from |cbs| and advances |cbs| over it. It returns one
104
 
 * on success and zero on error. */
105
 
OPENSSL_EXPORT int CBS_get_u8_length_prefixed(CBS *cbs, CBS *out);
106
 
 
107
 
/* CBS_get_u16_length_prefixed sets |*out| to the contents of a 16-bit,
108
 
 * big-endian, length-prefixed value from |cbs| and advances |cbs| over it. It
109
 
 * returns one on success and zero on error. */
110
 
OPENSSL_EXPORT int CBS_get_u16_length_prefixed(CBS *cbs, CBS *out);
111
 
 
112
 
/* CBS_get_u24_length_prefixed sets |*out| to the contents of a 24-bit,
113
 
 * big-endian, length-prefixed value from |cbs| and advances |cbs| over it. It
114
 
 * returns one on success and zero on error. */
115
 
OPENSSL_EXPORT int CBS_get_u24_length_prefixed(CBS *cbs, CBS *out);
116
 
 
117
 
 
118
 
/* Parsing ASN.1 */
119
 
 
120
 
#define CBS_ASN1_BOOLEAN 0x1
121
 
#define CBS_ASN1_INTEGER 0x2
122
 
#define CBS_ASN1_BITSTRING 0x3
123
 
#define CBS_ASN1_OCTETSTRING 0x4
124
 
#define CBS_ASN1_NULL 0x5
125
 
#define CBS_ASN1_OBJECT 0x6
126
 
#define CBS_ASN1_ENUMERATED 0xa
127
 
#define CBS_ASN1_SEQUENCE (0x10 | CBS_ASN1_CONSTRUCTED)
128
 
#define CBS_ASN1_SET (0x11 | CBS_ASN1_CONSTRUCTED)
129
 
#define CBS_ASN1_GENERALIZEDTIME 0x18
130
 
 
131
 
#define CBS_ASN1_CONSTRUCTED 0x20
132
 
#define CBS_ASN1_CONTEXT_SPECIFIC 0x80
133
 
 
134
 
/* CBS_get_asn1 sets |*out| to the contents of DER-encoded, ASN.1 element (not
135
 
 * including tag and length bytes) and advances |cbs| over it. The ASN.1
136
 
 * element must match |tag_value|. It returns one on success and zero
137
 
 * on error.
138
 
 *
139
 
 * Tag numbers greater than 30 are not supported (i.e. short form only). */
140
 
OPENSSL_EXPORT int CBS_get_asn1(CBS *cbs, CBS *out, unsigned tag_value);
141
 
 
142
 
/* CBS_get_asn1_element acts like |CBS_get_asn1| but |out| will include the
143
 
 * ASN.1 header bytes too. */
144
 
OPENSSL_EXPORT int CBS_get_asn1_element(CBS *cbs, CBS *out, unsigned tag_value);
145
 
 
146
 
/* CBS_peek_asn1_tag looks ahead at the next ASN.1 tag and returns one
147
 
 * if the next ASN.1 element on |cbs| would have tag |tag_value|. If
148
 
 * |cbs| is empty or the tag does not match, it returns zero. Note: if
149
 
 * it returns one, CBS_get_asn1 may still fail if the rest of the
150
 
 * element is malformed. */
151
 
OPENSSL_EXPORT int CBS_peek_asn1_tag(const CBS *cbs, unsigned tag_value);
152
 
 
153
 
/* CBS_get_any_asn1_element sets |*out| to contain the next ASN.1 element from
154
 
 * |*cbs| (including header bytes) and advances |*cbs|. It sets |*out_tag| to
155
 
 * the tag number and |*out_header_len| to the length of the ASN.1 header. Each
156
 
 * of |out|, |out_tag|, and |out_header_len| may be NULL to ignore the value.
157
 
 *
158
 
 * Tag numbers greater than 30 are not supported (i.e. short form only). */
159
 
OPENSSL_EXPORT int CBS_get_any_asn1_element(CBS *cbs, CBS *out,
160
 
                                            unsigned *out_tag,
161
 
                                            size_t *out_header_len);
162
 
 
163
 
/* CBS_get_any_ber_asn1_element acts the same as |CBS_get_any_asn1_element| but
164
 
 * also allows indefinite-length elements to be returned. In that case,
165
 
 * |*out_header_len| and |CBS_len(out)| will both be two as only the header is
166
 
 * returned, otherwise it behaves the same as the previous function. */
167
 
OPENSSL_EXPORT int CBS_get_any_ber_asn1_element(CBS *cbs, CBS *out,
168
 
                                                unsigned *out_tag,
169
 
                                                size_t *out_header_len);
170
 
 
171
 
/* CBS_get_asn1_uint64 gets an ASN.1 INTEGER from |cbs| using |CBS_get_asn1|
172
 
 * and sets |*out| to its value. It returns one on success and zero on error,
173
 
 * where error includes the integer being negative, or too large to represent
174
 
 * in 64 bits. */
175
 
OPENSSL_EXPORT int CBS_get_asn1_uint64(CBS *cbs, uint64_t *out);
176
 
 
177
 
/* CBS_get_optional_asn1 gets an optional explicitly-tagged element
178
 
 * from |cbs| tagged with |tag| and sets |*out| to its contents. If
179
 
 * present, it sets |*out_present| to one, otherwise zero. It returns
180
 
 * one on success, whether or not the element was present, and zero on
181
 
 * decode failure. */
182
 
OPENSSL_EXPORT int CBS_get_optional_asn1(CBS *cbs, CBS *out, int *out_present,
183
 
                                         unsigned tag);
184
 
 
185
 
/* CBS_get_optional_asn1_octet_string gets an optional
186
 
 * explicitly-tagged OCTET STRING from |cbs|. If present, it sets
187
 
 * |*out| to the string and |*out_present| to one. Otherwise, it sets
188
 
 * |*out| to empty and |*out_present| to zero. |out_present| may be
189
 
 * NULL. It returns one on success, whether or not the element was
190
 
 * present, and zero on decode failure. */
191
 
OPENSSL_EXPORT int CBS_get_optional_asn1_octet_string(CBS *cbs, CBS *out,
192
 
                                                      int *out_present,
193
 
                                                      unsigned tag);
194
 
 
195
 
/* CBS_get_optional_asn1_uint64 gets an optional explicitly-tagged
196
 
 * INTEGER from |cbs|. If present, it sets |*out| to the
197
 
 * value. Otherwise, it sets |*out| to |default_value|. It returns one
198
 
 * on success, whether or not the element was present, and zero on
199
 
 * decode failure. */
200
 
OPENSSL_EXPORT int CBS_get_optional_asn1_uint64(CBS *cbs, uint64_t *out,
201
 
                                                unsigned tag,
202
 
                                                uint64_t default_value);
203
 
 
204
 
/* CBS_get_optional_asn1_bool gets an optional, explicitly-tagged BOOLEAN from
205
 
 * |cbs|. If present, it sets |*out| to either zero or one, based on the
206
 
 * boolean. Otherwise, it sets |*out| to |default_value|. It returns one on
207
 
 * success, whether or not the element was present, and zero on decode
208
 
 * failure. */
209
 
OPENSSL_EXPORT int CBS_get_optional_asn1_bool(CBS *cbs, int *out, unsigned tag,
210
 
                                              int default_value);
211
 
 
212
 
 
213
 
/* CRYPTO ByteBuilder.
214
 
 *
215
 
 * |CBB| objects allow one to build length-prefixed serialisations. A |CBB|
216
 
 * object is associated with a buffer and new buffers are created with
217
 
 * |CBB_init|. Several |CBB| objects can point at the same buffer when a
218
 
 * length-prefix is pending, however only a single |CBB| can be 'current' at
219
 
 * any one time. For example, if one calls |CBB_add_u8_length_prefixed| then
220
 
 * the new |CBB| points at the same buffer as the original. But if the original
221
 
 * |CBB| is used then the length prefix is written out and the new |CBB| must
222
 
 * not be used again.
223
 
 *
224
 
 * If one needs to force a length prefix to be written out because a |CBB| is
225
 
 * going out of scope, use |CBB_flush|. */
226
 
 
227
 
struct cbb_buffer_st {
228
 
  uint8_t *buf;
229
 
  size_t len;      /* The number of valid bytes. */
230
 
  size_t cap;      /* The size of buf. */
231
 
  char can_resize; /* One iff |buf| is owned by this object. If not then |buf|
232
 
                      cannot be resized. */
233
 
};
234
 
 
235
 
struct cbb_st {
236
 
  struct cbb_buffer_st *base;
237
 
  /* offset is the offset from the start of |base->buf| to the position of any
238
 
   * pending length-prefix. */
239
 
  size_t offset;
240
 
  /* child points to a child CBB if a length-prefix is pending. */
241
 
  struct cbb_st *child;
242
 
  /* pending_len_len contains the number of bytes in a pending length-prefix,
243
 
   * or zero if no length-prefix is pending. */
244
 
  uint8_t pending_len_len;
245
 
  char pending_is_asn1;
246
 
  /* is_top_level is true iff this is a top-level |CBB| (as opposed to a child
247
 
   * |CBB|). Top-level objects are valid arguments for |CBB_finish|. */
248
 
  char is_top_level;
249
 
};
250
 
 
251
 
/* CBB_init initialises |cbb| with |initial_capacity|. Since a |CBB| grows as
252
 
 * needed, the |initial_capacity| is just a hint. It returns one on success or
253
 
 * zero on error. */
254
 
OPENSSL_EXPORT int CBB_init(CBB *cbb, size_t initial_capacity);
255
 
 
256
 
/* CBB_init_fixed initialises |cbb| to write to |len| bytes at |buf|. Since
257
 
 * |buf| cannot grow, trying to write more than |len| bytes will cause CBB
258
 
 * functions to fail. It returns one on success or zero on error. */
259
 
OPENSSL_EXPORT int CBB_init_fixed(CBB *cbb, uint8_t *buf, size_t len);
260
 
 
261
 
/* CBB_cleanup frees all resources owned by |cbb| and other |CBB| objects
262
 
 * writing to the same buffer. This should be used in an error case where a
263
 
 * serialisation is abandoned. */
264
 
OPENSSL_EXPORT void CBB_cleanup(CBB *cbb);
265
 
 
266
 
/* CBB_finish completes any pending length prefix and sets |*out_data| to a
267
 
 * malloced buffer and |*out_len| to the length of that buffer. The caller
268
 
 * takes ownership of the buffer and, unless the buffer was fixed with
269
 
 * |CBB_init_fixed|, must call |OPENSSL_free| when done.
270
 
 *
271
 
 * It can only be called on a "top level" |CBB|, i.e. one initialised with
272
 
 * |CBB_init| or |CBB_init_fixed|. It returns one on success and zero on
273
 
 * error. */
274
 
OPENSSL_EXPORT int CBB_finish(CBB *cbb, uint8_t **out_data, size_t *out_len);
275
 
 
276
 
/* CBB_flush causes any pending length prefixes to be written out and any child
277
 
 * |CBB| objects of |cbb| to be invalidated. It returns one on success or zero
278
 
 * on error. */
279
 
OPENSSL_EXPORT int CBB_flush(CBB *cbb);
280
 
 
281
 
/* CBB_add_u8_length_prefixed sets |*out_contents| to a new child of |cbb|. The
282
 
 * data written to |*out_contents| will be prefixed in |cbb| with an 8-bit
283
 
 * length. It returns one on success or zero on error. */
284
 
OPENSSL_EXPORT int CBB_add_u8_length_prefixed(CBB *cbb, CBB *out_contents);
285
 
 
286
 
/* CBB_add_u16_length_prefixed sets |*out_contents| to a new child of |cbb|.
287
 
 * The data written to |*out_contents| will be prefixed in |cbb| with a 16-bit,
288
 
 * big-endian length. It returns one on success or zero on error. */
289
 
OPENSSL_EXPORT int CBB_add_u16_length_prefixed(CBB *cbb, CBB *out_contents);
290
 
 
291
 
/* CBB_add_u24_length_prefixed sets |*out_contents| to a new child of |cbb|.
292
 
 * The data written to |*out_contents| will be prefixed in |cbb| with a 24-bit,
293
 
 * big-endian length. It returns one on success or zero on error. */
294
 
OPENSSL_EXPORT int CBB_add_u24_length_prefixed(CBB *cbb, CBB *out_contents);
295
 
 
296
 
/* CBB_add_asn1 sets |*out_contents| to a |CBB| into which the contents of an
297
 
 * ASN.1 object can be written. The |tag| argument will be used as the tag for
298
 
 * the object. Passing in |tag| number 31 will return in an error since only
299
 
 * single octet identifiers are supported. It returns one on success or zero
300
 
 * on error. */
301
 
OPENSSL_EXPORT int CBB_add_asn1(CBB *cbb, CBB *out_contents, uint8_t tag);
302
 
 
303
 
/* CBB_add_bytes appends |len| bytes from |data| to |cbb|. It returns one on
304
 
 * success and zero otherwise. */
305
 
OPENSSL_EXPORT int CBB_add_bytes(CBB *cbb, const uint8_t *data, size_t len);
306
 
 
307
 
/* CBB_add_space appends |len| bytes to |cbb| and sets |*out_data| to point to
308
 
 * the beginning of that space. The caller must then write |len| bytes of
309
 
 * actual contents to |*out_data|. It returns one on success and zero
310
 
 * otherwise. */
311
 
OPENSSL_EXPORT int CBB_add_space(CBB *cbb, uint8_t **out_data, size_t len);
312
 
 
313
 
/* CBB_add_u8 appends an 8-bit number from |value| to |cbb|. It returns one on
314
 
 * success and zero otherwise. */
315
 
OPENSSL_EXPORT int CBB_add_u8(CBB *cbb, uint8_t value);
316
 
 
317
 
/* CBB_add_u16 appends a 16-bit, big-endian number from |value| to |cbb|. It
318
 
 * returns one on success and zero otherwise. */
319
 
OPENSSL_EXPORT int CBB_add_u16(CBB *cbb, uint16_t value);
320
 
 
321
 
/* CBB_add_u24 appends a 24-bit, big-endian number from |value| to |cbb|. It
322
 
 * returns one on success and zero otherwise. */
323
 
OPENSSL_EXPORT int CBB_add_u24(CBB *cbb, uint32_t value);
324
 
 
325
 
/* CBB_add_asn1_uint64 writes an ASN.1 INTEGER into |cbb| using |CBB_add_asn1|
326
 
 * and writes |value| in its contents. It returns one on success and zero on
327
 
 * error. */
328
 
OPENSSL_EXPORT int CBB_add_asn1_uint64(CBB *cbb, uint64_t value);
329
 
 
330
 
 
331
 
#if defined(__cplusplus)
332
 
}  /* extern C */
333
 
#endif
334
 
 
335
 
#endif  /* OPENSSL_HEADER_BYTESTRING_H */