diff options
Diffstat (limited to 'python/hpack/man_page/hpack.1')
| -rw-r--r-- | python/hpack/man_page/hpack.1 | 313 |
1 files changed, 313 insertions, 0 deletions
diff --git a/python/hpack/man_page/hpack.1 b/python/hpack/man_page/hpack.1 new file mode 100644 index 0000000000..f53f6d03f3 --- /dev/null +++ b/python/hpack/man_page/hpack.1 @@ -0,0 +1,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. +. |