diff options
Diffstat (limited to 'doc/sources')
| -rw-r--r-- | doc/sources/index.rst | 1 | ||||
| -rw-r--r-- | doc/sources/security.rst | 33 | ||||
| -rw-r--r-- | doc/sources/tutorial-client.rst | 27 | ||||
| -rw-r--r-- | doc/sources/tutorial-hpack.rst | 30 | ||||
| -rw-r--r-- | doc/sources/tutorial-server.rst | 43 |
5 files changed, 51 insertions, 83 deletions
diff --git a/doc/sources/index.rst b/doc/sources/index.rst index b03c348..e181645 100644 --- a/doc/sources/index.rst +++ b/doc/sources/index.rst @@ -18,7 +18,6 @@ Contents: package_README contribute - security building-android-binary tutorial-client tutorial-server diff --git a/doc/sources/security.rst b/doc/sources/security.rst deleted file mode 100644 index 5a8fcd0..0000000 --- a/doc/sources/security.rst +++ /dev/null @@ -1,33 +0,0 @@ -Security Process -================ - -If you find a vulnerability in our software, please send the email to -"tatsuhiro.t at gmail dot com" about its details instead of submitting -issues on github issue page. It is a standard practice not to -disclose vulnerability information publicly until a fixed version is -released, or mitigation is worked out. In the future, we may setup a -dedicated mail address for this purpose. - -If we identify that the reported issue is really a vulnerability, we -open a new security advisory draft using `GitHub security feature -<https://github.com/nghttp2/nghttp2/security>`_ and discuss the -mitigation and bug fixes there. The fixes are committed to the -private repository. - -We write the security advisory and get CVE number from GitHub -privately. We also discuss the disclosure date to the public. - -We make a new release with the fix at the same time when the -vulnerability is disclosed to public. - -At least 7 days before the public disclosure date, we open a new issue -on `nghttp2 issue tracker -<https://github.com/nghttp2/nghttp2/issues>`_ which notifies that the -upcoming release will have a security fix. The ``SECURITY`` label is -attached to this kind of issue. The issue is not opened if a -vulnerability is already disclosed, and it is publicly known that -nghttp2 is affected by that. - -Before few hours of new release, we merge the fixes to the master -branch (and/or a release branch if necessary) and make a new release. -Security advisory is disclosed on GitHub. diff --git a/doc/sources/tutorial-client.rst b/doc/sources/tutorial-client.rst index 95a6230..be6eb55 100644 --- a/doc/sources/tutorial-client.rst +++ b/doc/sources/tutorial-client.rst @@ -171,7 +171,7 @@ session object and several callbacks:: nghttp2_session_callbacks_new(&callbacks); - nghttp2_session_callbacks_set_send_callback(callbacks, send_callback); + nghttp2_session_callbacks_set_send_callback2(callbacks, send_callback); nghttp2_session_callbacks_set_on_frame_recv_callback(callbacks, on_frame_recv_callback); @@ -246,8 +246,8 @@ HTTP request in the ``submit_request()`` function:: MAKE_NV(":path", stream_data->path, stream_data->pathlen)}; fprintf(stderr, "Request headers:\n"); print_headers(stderr, hdrs, ARRLEN(hdrs)); - stream_id = nghttp2_submit_request(session_data->session, NULL, hdrs, - ARRLEN(hdrs), NULL, stream_data); + stream_id = nghttp2_submit_request2(session_data->session, NULL, hdrs, + ARRLEN(hdrs), NULL, stream_data); if (stream_id < 0) { errx(1, "Could not submit HTTP request: %s", nghttp2_strerror(stream_id)); } @@ -258,11 +258,11 @@ HTTP request in the ``submit_request()`` function:: We build the HTTP request header fields in ``hdrs``, which is an array of :type:`nghttp2_nv`. There are four header fields to be sent: ``:method``, ``:scheme``, ``:authority``, and ``:path``. To queue the -HTTP request, we call `nghttp2_submit_request()`. The ``stream_data`` +HTTP request, we call `nghttp2_submit_request2()`. The ``stream_data`` is passed via the *stream_user_data* parameter, which is helpfully later passed back to callback functions. -`nghttp2_submit_request()` returns the newly assigned stream ID for +`nghttp2_submit_request2()` returns the newly assigned stream ID for the request. The next bufferevent callback is ``readcb()``, which is invoked when @@ -270,12 +270,12 @@ data is available to read from the bufferevent input buffer:: static void readcb(struct bufferevent *bev, void *ptr) { http2_session_data *session_data = (http2_session_data *)ptr; - ssize_t readlen; + nghttp2_ssize readlen; struct evbuffer *input = bufferevent_get_input(bev); size_t datalen = evbuffer_get_length(input); unsigned char *data = evbuffer_pullup(input, -1); - readlen = nghttp2_session_mem_recv(session_data->session, data, datalen); + readlen = nghttp2_session_mem_recv2(session_data->session, data, datalen); if (readlen < 0) { warnx("Fatal error: %s", nghttp2_strerror((int)readlen)); delete_http2_session_data(session_data); @@ -293,8 +293,8 @@ data is available to read from the bufferevent input buffer:: } In this function we feed all unprocessed, received data to the nghttp2 -session object using the `nghttp2_session_mem_recv()` function. -`nghttp2_session_mem_recv()` processes the received data and may +session object using the `nghttp2_session_mem_recv2()` function. +`nghttp2_session_mem_recv2()` processes the received data and may invoke nghttp2 callbacks and queue frames for transmission. Since there may be pending frames for transmission, we call immediately ``session_send()`` to send them. ``session_send()`` is defined as @@ -313,15 +313,16 @@ follows:: The `nghttp2_session_send()` function serializes pending frames into wire format and calls the ``send_callback()`` function to send them. -``send_callback()`` has type :type:`nghttp2_send_callback` and is +``send_callback()`` has type :type:`nghttp2_send_callback2` and is defined as:: - static ssize_t send_callback(nghttp2_session *session _U_, const uint8_t *data, - size_t length, int flags _U_, void *user_data) { + static nghttp2_ssize send_callback(nghttp2_session *session _U_, + const uint8_t *data, size_t length, + int flags _U_, void *user_data) { http2_session_data *session_data = (http2_session_data *)user_data; struct bufferevent *bev = session_data->bev; bufferevent_write(bev, data, length); - return (ssize_t)length; + return (nghttp2_ssize)length; } Since we use bufferevent to abstract network I/O, we just write the diff --git a/doc/sources/tutorial-hpack.rst b/doc/sources/tutorial-hpack.rst index 36e82d9..82acd94 100644 --- a/doc/sources/tutorial-hpack.rst +++ b/doc/sources/tutorial-hpack.rst @@ -24,11 +24,11 @@ deflater object for the dynamic header table. If in doubt, just specify 4096 here, which is the default upper bound of dynamic header table buffer size. -To encode header fields, use the `nghttp2_hd_deflate_hd()` function:: +To encode header fields, use the `nghttp2_hd_deflate_hd2()` function:: - ssize_t nghttp2_hd_deflate_hd(nghttp2_hd_deflater *deflater, - uint8_t *buf, size_t buflen, - const nghttp2_nv *nva, size_t nvlen); + nghttp2_ssize nghttp2_hd_deflate_hd2(nghttp2_hd_deflater *deflater, + uint8_t *buf, size_t buflen, + const nghttp2_nv *nva, size_t nvlen); The *deflater* is the deflater object initialized by `nghttp2_hd_deflate_new()` described above. The encoded byte string is @@ -44,7 +44,7 @@ cookies), set the :macro:`NGHTTP2_NV_FLAG_NO_INDEX` flag in sensitive header fields by compression based attacks: This is achieved by not inserting the header field into the dynamic header table. -`nghttp2_hd_deflate_hd()` processes all headers given in *nva*. The +`nghttp2_hd_deflate_hd2()` processes all headers given in *nva*. The *nva* must include all request or response header fields to be sent in one HEADERS (or optionally following (multiple) CONTINUATION frame(s)). The *buf* must have enough space to store the encoded @@ -55,13 +55,13 @@ of the encoded result length, use `nghttp2_hd_deflate_bound()`:: const nghttp2_nv *nva, size_t nvlen); Pass this function the same parameters (*deflater*, *nva*, and -*nvlen*) which will be passed to `nghttp2_hd_deflate_hd()`. +*nvlen*) which will be passed to `nghttp2_hd_deflate_hd2()`. -Subsequent calls to `nghttp2_hd_deflate_hd()` will use the current +Subsequent calls to `nghttp2_hd_deflate_hd2()` will use the current encoder state and perform differential encoding, which yields HPAC's fundamental compression gain. -If `nghttp2_hd_deflate_hd()` fails, the failure is fatal and any +If `nghttp2_hd_deflate_hd2()` fails, the failure is fatal and any further calls with the same deflater object will fail. Thus it's very important to use `nghttp2_hd_deflate_bound()` to determine the required size of the output buffer. @@ -78,14 +78,14 @@ header data. To initialize the object, use int nghttp2_hd_inflate_new(nghttp2_hd_inflater **inflater_ptr); -To inflate header data, use `nghttp2_hd_inflate_hd2()`:: +To inflate header data, use `nghttp2_hd_inflate_hd3()`:: - ssize_t nghttp2_hd_inflate_hd2(nghttp2_hd_inflater *inflater, - nghttp2_nv *nv_out, int *inflate_flags, - const uint8_t *in, size_t inlen, - int in_final); + nghttp2_ssize nghttp2_hd_inflate_hd3(nghttp2_hd_inflater *inflater, + nghttp2_nv *nv_out, int *inflate_flags, + const uint8_t *in, size_t inlen, + int in_final); -`nghttp2_hd_inflate_hd2()` reads a stream of bytes and outputs a +`nghttp2_hd_inflate_hd3()` reads a stream of bytes and outputs a single header field at a time. Multiple calls are normally required to read a full stream of bytes and output all of the header fields. @@ -119,7 +119,7 @@ If *in_final* is zero and the :macro:`NGHTTP2_HD_INFLATE_EMIT` flag is not set, it indicates that all given data was processed. The caller is required to pass additional data. -Example usage of `nghttp2_hd_inflate_hd2()` is shown in the +Example usage of `nghttp2_hd_inflate_hd3()` is shown in the `inflate_header_block()` function in `deflate.c`_. Finally, to delete a :type:`nghttp2_hd_inflater` object, use diff --git a/doc/sources/tutorial-server.rst b/doc/sources/tutorial-server.rst index 41680bd..bf71296 100644 --- a/doc/sources/tutorial-server.rst +++ b/doc/sources/tutorial-server.rst @@ -220,7 +220,7 @@ session object and several callbacks:: nghttp2_session_callbacks_new(&callbacks); - nghttp2_session_callbacks_set_send_callback(callbacks, send_callback); + nghttp2_session_callbacks_set_send_callback2(callbacks, send_callback); nghttp2_session_callbacks_set_on_frame_recv_callback(callbacks, on_frame_recv_callback); @@ -275,12 +275,12 @@ this pending data. To process the received data, we call the ``session_recv()`` function:: static int session_recv(http2_session_data *session_data) { - ssize_t readlen; + nghttp2_ssize readlen; struct evbuffer *input = bufferevent_get_input(session_data->bev); size_t datalen = evbuffer_get_length(input); unsigned char *data = evbuffer_pullup(input, -1); - readlen = nghttp2_session_mem_recv(session_data->session, data, datalen); + readlen = nghttp2_session_mem_recv2(session_data->session, data, datalen); if (readlen < 0) { warnx("Fatal error: %s", nghttp2_strerror((int)readlen)); return -1; @@ -296,9 +296,9 @@ this pending data. To process the received data, we call the } In this function, we feed all unprocessed but already received data to -the nghttp2 session object using the `nghttp2_session_mem_recv()` -function. The `nghttp2_session_mem_recv()` function processes the data -and may both invoke the previously setup callbacks and also queue +the nghttp2 session object using the `nghttp2_session_mem_recv2()` +function. The `nghttp2_session_mem_recv2()` function processes the +data and may both invoke the previously setup callbacks and also queue outgoing frames. To send any pending outgoing frames, we immediately call ``session_send()``. @@ -316,11 +316,12 @@ The ``session_send()`` function is defined as follows:: The `nghttp2_session_send()` function serializes the frame into wire format and calls the ``send_callback()``, which is of type -:type:`nghttp2_send_callback`. The ``send_callback()`` is defined as +:type:`nghttp2_send_callback2`. The ``send_callback()`` is defined as follows:: - static ssize_t send_callback(nghttp2_session *session _U_, const uint8_t *data, - size_t length, int flags _U_, void *user_data) { + static nghttp2_ssize send_callback(nghttp2_session *session _U_, + const uint8_t *data, size_t length, + int flags _U_, void *user_data) { http2_session_data *session_data = (http2_session_data *)user_data; struct bufferevent *bev = session_data->bev; /* Avoid excessive buffering in server side. */ @@ -329,7 +330,7 @@ follows:: return NGHTTP2_ERR_WOULDBLOCK; } bufferevent_write(bev, data, length); - return (ssize_t)length; + return (nghttp2_ssize)length; } Since we use bufferevent to abstract network I/O, we just write the @@ -509,11 +510,11 @@ Sending the file content is performed by the ``send_response()`` function:: static int send_response(nghttp2_session *session, int32_t stream_id, nghttp2_nv *nva, size_t nvlen, int fd) { int rv; - nghttp2_data_provider data_prd; + nghttp2_data_provider2 data_prd; data_prd.source.fd = fd; data_prd.read_callback = file_read_callback; - rv = nghttp2_submit_response(session, stream_id, nva, nvlen, &data_prd); + rv = nghttp2_submit_response2(session, stream_id, nva, nvlen, &data_prd); if (rv != 0) { warnx("Fatal error: %s", nghttp2_strerror(rv)); return -1; @@ -521,7 +522,7 @@ Sending the file content is performed by the ``send_response()`` function:: return 0; } -nghttp2 uses the :type:`nghttp2_data_provider` structure to send the +nghttp2 uses the :type:`nghttp2_data_provider2` structure to send the entity body to the remote peer. The ``source`` member of this structure is a union, which can be either a void pointer or an int (which is intended to be used as file descriptor). In this example @@ -529,11 +530,11 @@ server, we use it as a file descriptor. We also set the ``file_read_callback()`` callback function to read the contents of the file:: - static ssize_t file_read_callback(nghttp2_session *session _U_, - int32_t stream_id _U_, uint8_t *buf, - size_t length, uint32_t *data_flags, - nghttp2_data_source *source, - void *user_data _U_) { + static nghttp2_ssize file_read_callback(nghttp2_session *session _U_, + int32_t stream_id _U_, uint8_t *buf, + size_t length, uint32_t *data_flags, + nghttp2_data_source *source, + void *user_data _U_) { int fd = source->fd; ssize_t r; while ((r = read(fd, buf, length)) == -1 && errno == EINTR) @@ -544,7 +545,7 @@ file:: if (r == 0) { *data_flags |= NGHTTP2_DATA_FLAG_EOF; } - return r; + return (nghttp2_ssize)r; } If an error occurs while reading the file, we return @@ -553,8 +554,8 @@ library to send RST_STREAM to the stream. When all data has been read, the :macro:`NGHTTP2_DATA_FLAG_EOF` flag is set to signal nghttp2 that we have finished reading the file. -The `nghttp2_submit_response()` function is used to send the response to the -remote peer. +The `nghttp2_submit_response2()` function is used to send the response +to the remote peer. The ``on_stream_close_callback()`` function is invoked when the stream is about to close:: |