summaryrefslogtreecommitdiffstats
path: root/python/hpack/man_page/hpack.1
blob: f53f6d03f3fe7f18eb26d86765eaf99f4c3c60da (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
.\" Man page generated from reStructuredText.
.
.TH "HPACK" "1" "December 17, 2016" "2.3.0" "hpack"
.SH NAME
hpack \- hpack Documentation
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.sp
hpack provides a simple Python interface to the \fI\%HPACK\fP compression algorithm,
used to compress HTTP headers in HTTP/2. Used by some of the most popular
HTTP/2 implementations in Python, HPACK offers a great Python interface as well
as optional upgrade to optimised C\-based compression routines from \fI\%nghttp2\fP\&.
.sp
Using hpack is easy:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
from hpack import Encoder, Decoder

e = Encoder()
encoded_bytes = e.encode(headers)

d = Decoder()
decoded_headers = d.decode(encoded_bytes)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
hpack will transparently use nghttp2 on CPython if it\(aqs available, gaining even
better compression efficiency and speed, but it also makes available a
pure\-Python implementation that conforms strictly to \fI\%RFC 7541\fP\&.
.SH CONTENTS
.SS Installing hpack
.sp
hpack is trivial to install from the Python Package Index. Simply run:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ pip install hpack
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Alternatively, feel free to download one of the release tarballs from
\fI\%our GitHub page\fP, extract it to your favourite directory, and then run
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ python setup.py install
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
hpack has no external dependencies.
.SS Using nghttp2
.sp
If you want to use nghttp2 with hpack, all you need to do is install it along
with its Python bindings. Consult \fI\%nghttp2\(aqs documentation\fP for instructions
on how to install it.
.SS hpack API
.sp
This document provides the HPACK API.
.INDENT 0.0
.TP
.B class hpack.Encoder
An HPACK encoder object. This object takes HTTP headers and emits encoded
HTTP/2 header blocks.
.INDENT 7.0
.TP
.B encode(headers, huffman=True)
Takes a set of headers and encodes them into a HPACK\-encoded header
block.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBheaders\fP \-\- 
.sp
The headers to encode. Must be either an iterable of
tuples, an iterable of \fBHeaderTuple\fP, or a \fBdict\fP\&.
.sp
If an iterable of tuples, the tuples may be either
two\-tuples or three\-tuples. If they are two\-tuples, the
tuples must be of the format \fB(name, value)\fP\&. If they
are three\-tuples, they must be of the format
\fB(name, value, sensitive)\fP, where \fBsensitive\fP is a
boolean value indicating whether the header should be
added to header tables anywhere. If not present,
\fBsensitive\fP defaults to \fBFalse\fP\&.
.sp
If an iterable of \fBHeaderTuple\fP, the tuples must always be
two\-tuples. Instead of using \fBsensitive\fP as a third
tuple entry, use \fBNeverIndexedHeaderTuple\fP to request that
the field never be indexed.
.sp
\fBWARNING:\fP
.INDENT 2.0
.INDENT 3.5
HTTP/2 requires that all special headers
(headers whose names begin with \fB:\fP characters)
appear at the \fIstart\fP of the header block. While
this method will ensure that happens for \fBdict\fP
subclasses, callers using any other iterable of
tuples \fBmust\fP ensure they place their special
headers at the start of the iterable.
.sp
For efficiency reasons users should prefer to use
iterables of two\-tuples: fixing the ordering of
dictionary headers is an expensive operation that
should be avoided if possible.
.UNINDENT
.UNINDENT

.IP \(bu 2
\fBhuffman\fP \-\- (optional) Whether to Huffman\-encode any header sent as
a literal value. Except for use when debugging, it is
recommended that this be left enabled.
.UNINDENT
.TP
.B Returns
A bytestring containing the HPACK\-encoded header block.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B header_table_size
Controls the size of the HPACK header table.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class hpack.Decoder(max_header_list_size=65536)
An HPACK decoder object.
.sp
Changed in version 2.3.0: Added \fBmax_header_list_size\fP argument.

.INDENT 7.0
.TP
.B Parameters
\fBmax_header_list_size\fP (\fBint\fP) \-\- 
.sp
The maximum decompressed size we will allow
for any single header block. This is a protection against DoS attacks
that attempt to force the application to expand a relatively small
amount of data into a really large header list, allowing enormous
amounts of memory to be allocated.
.sp
If this amount of data is exceeded, a \fIOversizedHeaderListError
<hpack.OversizedHeaderListError>\fP exception will be raised. At this
point the connection should be shut down, as the HPACK state will no
longer be useable.
.sp
Defaults to 64kB.

.UNINDENT
.INDENT 7.0
.TP
.B decode(data, raw=False)
Takes an HPACK\-encoded header block and decodes it into a header set.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBdata\fP \-\- A bytestring representing a complete HPACK\-encoded header
block.
.IP \(bu 2
\fBraw\fP \-\- (optional) Whether to return the headers as tuples of raw
byte strings or to decode them as UTF\-8 before returning
them. The default value is False, which returns tuples of
Unicode strings
.UNINDENT
.TP
.B Returns
A list of two\-tuples of \fB(name, value)\fP representing the
HPACK\-encoded headers, in the order they were decoded.
.TP
.B Raises HPACKDecodingError
If an error is encountered while decoding
the header block.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B header_table_size
Controls the size of the HPACK header table.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class hpack.HeaderTuple
A data structure that stores a single header field.
.sp
HTTP headers can be thought of as tuples of \fB(field name, field value)\fP\&.
A single header block is a sequence of such tuples.
.sp
In HTTP/2, however, certain bits of additional information are required for
compressing these headers: in particular, whether the header field can be
safely added to the HPACK compression context.
.sp
This class stores a header that can be added to the compression context. In
all other ways it behaves exactly like a tuple.
.UNINDENT
.INDENT 0.0
.TP
.B class hpack.NeverIndexedHeaderTuple
A data structure that stores a single header field that cannot be added to
a HTTP/2 header compression context.
.UNINDENT
.INDENT 0.0
.TP
.B class hpack.HPACKError
The base class for all \fBhpack\fP exceptions.
.UNINDENT
.INDENT 0.0
.TP
.B class hpack.HPACKDecodingError
An error has been encountered while performing HPACK decoding.
.UNINDENT
.INDENT 0.0
.TP
.B class hpack.InvalidTableIndex
An invalid table index was received.
.UNINDENT
.INDENT 0.0
.TP
.B class hpack.OversizedHeaderListError
A header list that was larger than we allow has been received. This may be
a DoS attack.
.sp
New in version 2.3.0.

.UNINDENT
.SS Vulnerability Notifications
.sp
This section of the page contains all known vulnerabilities in the HPACK
library. These vulnerabilities have all been reported to us via our
\fI\%vulnerability disclosure policy\fP\&.
.SS Known Vulnerabilities
.TS
center;
|l|l|l|l|l|l|.
_
T{
#
T}	T{
Vulnerability
T}	T{
Date Announced
T}	T{
First Version
T}	T{
Last Version
T}	T{
CVE
T}
_
T{
1
T}	T{
\fBHPACK Bomb\fP
T}	T{
2016\-08\-04
T}	T{
1.0.0
T}	T{
2.2.0
T}	T{
CVE\-2016\-6581
T}
_
.TE
.SH AUTHOR
Cory Benfield
.SH COPYRIGHT
2015, Cory Benfield
.\" Generated by docutils manpage writer.
.