romenskiy2012/curl
1
0
Fork 0
mirror of https://github.com/curl/curl.git synced 2026-08-24 17:33:33 +03:00
Code Issues Projects Releases Packages Wiki Activity

hsts: add read/write callbacks

Browse source 
- read/write callback options
- man pages for the 4 new setopts
- test 1915 verifies the callbacks

Closes #5896
This commit is contained in:
Daniel Stenberg 2020-11-02 23:17:01 +01:00
parent 7385610d0c
commit 2cfc4ed983
No known key found for this signature in database
GPG key ID: 5CC908FDB71E12C2
27 changed files with 652 additions and 22 deletions
Download patch file Download diff file Expand all files Collapse all files

8
docs/libcurl/curl_easy_setopt.3
View file

@ -323,6 +323,14 @@ Enable and configure Alt-Svc: treatment. See \fICURLOPT_ALTSVC_CTRL(3)\fP
Set HSTS cache file. See \fICURLOPT_HSTS(3)\fP
.IP CURLOPT_HSTS_CTRL
Enable HSTS. See \fICURLOPT_HSTS_CTRL(3)\fP
.IP CURLOPT_HSTSREADFUNCTION
Set HSTS read callback. See \fICURLOPT_HSTSREADFUNCTION(3)\fP
.IP CURLOPT_HSTSREADDATA
Pass pointer to the HSTS read callback. See \fICURLOPT_HSTSREADDATA(3)\fP
.IP CURLOPT_HSTSWRITEFUNCTION
Set HSTS write callback. See \fICURLOPT_HSTSWRITEFUNCTION(3)\fP
.IP CURLOPT_HSTSWRITEDATA
Pass pointer to the HSTS write callback. See \fICURLOPT_HSTSWRITEDATA(3)\fP
.IP CURLOPT_HTTPGET
Do an HTTP GET request. See \fICURLOPT_HTTPGET(3)\fP
.IP CURLOPT_REQUEST_TARGET

66
docs/libcurl/opts/CURLOPT_HSTSREADDATA.3 Normal file
View file

@ -0,0 +1,66 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
.\" * are also available at https://curl.haxx.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_HSTSREADDATA 3 "14 Sep 2020" "libcurl 7.74.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_HSTSREADDATA \- pointer passed to the HSTS read callback
.SH SYNOPSIS
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HSTSREADDATA, void *pointer);
.SH EXPERIMENTAL
Warning: this feature is early code and is marked as experimental. It can only
be enabled by explicitly telling configure with \fB--enable-hsts\fP. You are
advised to not ship this in production before the experimental label is
removed.
.SH DESCRIPTION
Data \fIpointer\fP to pass to the HSTS read function. If you use the
\fICURLOPT_HSTSREADFUNCTION(3)\fP option, this is the pointer you'll get as
input in the 3rd argument to the callback.
This option doesn't enable HSTS, you need to use \fICURLOPT_HSTS_CTRL(3)\fP to
do that.
.SH DEFAULT
NULL
.SH PROTOCOLS
This feature is only used for HTTP(S) transfer.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
struct MyData this;
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "http://example.com");
/* pass pointer that gets passed in to the
CURLOPT_HSTSREADFUNCTION callback */
curl_easy_setopt(curl, CURLOPT_HSTSREADDATA, &this);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.74.0
.SH RETURN VALUE
This will return CURLE_OK.
.SH "SEE ALSO"
.BR CURLOPT_HSTSREADFUNCTION "(3), " CURLOPT_HSTSWRITEDATA "(3), "
.BR CURLOPT_HSTSWRITEFUNCTION "(3), "

81
docs/libcurl/opts/CURLOPT_HSTSREADFUNCTION.3 Normal file
View file

@ -0,0 +1,81 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
.\" * are also available at https://curl.haxx.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_HSTSREADFUNCTION 3 "14 Sep 2020" "libcurl 7.74.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_HSTSREADFUNCTION \- read callback for HSTS hosts
.SH SYNOPSIS
#include <curl/curl.h>
CURLSTScode hstsread(CURL *easy, struct curl_hstsentry *sts, void *userp);
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HSTSREADFUNCTION, hstsread);
.SH EXPERIMENTAL
Warning: this feature is early code and is marked as experimental. It can only
be enabled by explicitly telling configure with \fB--enable-hsts\fP. You are
advised to not ship this in production before the experimental label is
removed.
.SH DESCRIPTION
Pass a pointer to your callback function, as the prototype shows above.
This callback function gets called by libcurl repeatedly when it populates the
in-memory HSTS cache.
Set the \fIuserp\fP argument with the \fICURLOPT_HSTSREADDATA(3)\fP option or
it will be NULL.
When this callback is invoked, the \fIsts\fP pointer points to a populated
struct: Copy the host name to 'name' (no longer than 'namelen' bytes). Make it
null-terminated. Set 'includeSubDomains' to TRUE or FALSE. Set 'expire' to a
date stamp or a zero length string for *forever* (wrong date stamp format
might cause the name to not get accepted)
The callback should return \fICURLSTS_OK\fP if it returns a name and is
prepared to be called again (for another host) or \fICURLSTS_DONE\fP if it has
no entry to return. It can also return \fICURLSTS_FAIL\fP to signal error.
This option doesn't enable HSTS, you need to use \fICURLOPT_HSTS_CTRL(3)\fP to
do that.
.SH DEFAULT
NULL - no callback.
.SH PROTOCOLS
This feature is only used for HTTP(S) transfer.
.SH EXAMPLE
.nf
{
/* set HSTS read callback */
curl_easy_setopt(curl, CURLOPT_HSTSREADFUNCTION, hstsread);
/* pass in suitable argument to the callback */
curl_easy_setopt(curl, CURLOPT_HSTSREADDATA, &hstspreload[0]);
result = curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.74.0
.SH RETURN VALUE
This will return CURLE_OK.
.SH "SEE ALSO"
.BR CURLOPT_HSTSREADDATA "(3), " CURLOPT_HSTSWRITEFUNCTION "(3), "
.BR CURLOPT_HSTS "(3), " CURLOPT_HSTS_CTRL "(3), "

66
docs/libcurl/opts/CURLOPT_HSTSWRITEDATA.3 Normal file
View file

@ -0,0 +1,66 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
.\" * are also available at https://curl.haxx.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_HSTSWRITEDATA 3 "14 Sep 2020" "libcurl 7.74.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_HSTSWRITEDATA \- pointer passed to the HSTS write callback
.SH SYNOPSIS
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HSTSWRITEDATA, void *pointer);
.SH EXPERIMENTAL
Warning: this feature is early code and is marked as experimental. It can only
be enabled by explicitly telling configure with \fB--enable-hsts\fP. You are
advised to not ship this in production before the experimental label is
removed.
.SH DESCRIPTION
Data \fIpointer\fP to pass to the HSTS write function. If you use the
\fICURLOPT_HSTSWRITEFUNCTION(3)\fP option, this is the pointer you'll get as
input in the 4th argument to the callback.
This option doesn't enable HSTS, you need to use \fICURLOPT_HSTS_CTRL(3)\fP to
do that.
.SH DEFAULT
NULL
.SH PROTOCOLS
This feature is only used for HTTP(S) transfer.
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
struct MyData this;
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "http://example.com");
/* pass pointer that gets passed in to the
CURLOPT_HSTSWRITEFUNCTION callback */
curl_easy_setopt(curl, CURLOPT_HSTSWRITEDATA, &this);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.74.0
.SH RETURN VALUE
This will return CURLE_OK.
.SH "SEE ALSO"
.BR CURLOPT_HSTSWRITEFUNCTION "(3), " CURLOPT_HSTSREADDATA "(3), "
.BR CURLOPT_HSTSREADFUNCTION "(3), "

79
docs/libcurl/opts/CURLOPT_HSTSWRITEFUNCTION.3 Normal file
View file

@ -0,0 +1,79 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
.\" * are also available at https://curl.haxx.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_HSTSWRITEFUNCTION 3 "14 Sep 2020" "libcurl 7.74.0" "curl_easy_setopt options"
.SH NAME
CURLOPT_HSTSWRITEFUNCTION \- write callback for HSTS hosts
.SH SYNOPSIS
#include <curl/curl.h>
CURLSTScode hstswrite(CURL *easy, struct curl_hstsentry *sts,
struct curl_index *count, void *userp);
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HSTSWRITEFUNCTION, hstswrite);
.SH EXPERIMENTAL
Warning: this feature is early code and is marked as experimental. It can only
be enabled by explicitly telling configure with \fB--enable-hsts\fP. You are
advised to not ship this in production before the experimental label is
removed.
.SH DESCRIPTION
Pass a pointer to your callback function, as the prototype shows above.
This callback function gets called by libcurl repeatedly to allow the
application to store the in-memory HSTS cache when libcurl is about to discard
it.
Set the \fIuserp\fP argument with the \fICURLOPT_HSTSWRITEDATA(3)\fP option or
it will be NULL.
When the callback is invoked, the \fIsts\fP pointer points to a populated
struct: Read the host name to 'name' (it is 'namelen' bytes long and null
terminated. The 'includeSubDomains' field is non-zero if the entry matches
subdomains. The 'expire' string is a date stamp null-terminated string using
the syntax YYYYMMDD HH:MM:SS.
The callback should return \fICURLSTS_OK\fP if it succeeded and is prepared to
be called again (for another host) or \fICURLSTS_DONE\fP if there's nothing
more to do. It can also return \fICURLSTS_FAIL\fP to signal error.
.SH DEFAULT
NULL - no callback.
.SH PROTOCOLS
This feature is only used for HTTP(S) transfer.
.SH EXAMPLE
.nf
{
/* set HSTS read callback */
curl_easy_setopt(curl, CURLOPT_HSTSWRITEFUNCTION, hstswrite);
/* pass in suitable argument to the callback */
curl_easy_setopt(curl, CURLOPT_HSTSWRITEDATA, &hstspreload[0]);
result = curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.74.0
.SH RETURN VALUE
This will return CURLE_OK.
.SH "SEE ALSO"
.BR CURLOPT_HSTSWRITEDATA "(3), " CURLOPT_HSTSWRITEFUNCTION "(3), "
.BR CURLOPT_HSTS "(3), " CURLOPT_HSTS_CTRL "(3), "

3
docs/libcurl/opts/CURLOPT_WRITEFUNCTION.3
View file

@ -67,6 +67,9 @@ transfer to become paused. See \fIcurl_easy_pause(3)\fP for further details.
Set this option to NULL to get the internal default function used instead of
your callback. The internal default function will write the data to the FILE *
given with \fICURLOPT_WRITEDATA(3)\fP.
This option doesn't enable HSTS, you need to use \fICURLOPT_HSTS_CTRL(3)\fP to
do that.
.SH DEFAULT
libcurl will use 'fwrite' as a callback by default.
.SH PROTOCOLS

4
docs/libcurl/opts/Makefile.inc
View file

@ -181,6 +181,10 @@ man_MANS = \
CURLOPT_HEADERFUNCTION.3 \
CURLOPT_HEADEROPT.3 \
CURLOPT_HSTS.3 \
CURLOPT_HSTSREADDATA.3 \
CURLOPT_HSTSREADFUNCTION.3 \
CURLOPT_HSTSWRITEDATA.3 \
CURLOPT_HSTSWRITEFUNCTION.3 \
CURLOPT_HSTS_CTRL.3 \
CURLOPT_HTTP09_ALLOWED.3 \
CURLOPT_HTTP200ALIASES.3 \

7
docs/libcurl/symbols-in-versions
View file

@ -447,6 +447,10 @@ CURLOPT_HEADERFUNCTION 7.7.2
CURLOPT_HEADEROPT 7.37.0
CURLOPT_HSTS 7.74.0
CURLOPT_HSTS_CTRL 7.74.0
CURLOPT_HSTSREADDATA 7.74.0
CURLOPT_HSTSREADFUNCTION 7.74.0
CURLOPT_HSTSWRITEDATA 7.74.0
CURLOPT_HSTSWRITEFUNCTION 7.74.0
CURLOPT_HTTP09_ALLOWED 7.64.0
CURLOPT_HTTP200ALIASES 7.10.3
CURLOPT_HTTPAUTH 7.10.6
@ -812,6 +816,9 @@ CURLSSLSET_NO_BACKENDS 7.56.0
CURLSSLSET_OK 7.56.0
CURLSSLSET_TOO_LATE 7.56.0
CURLSSLSET_UNKNOWN_BACKEND 7.56.0
CURLSTS_DONE 7.74.0
CURLSTS_FAIL 7.74.0
CURLSTS_OK 7.74.0
CURLUE_BAD_HANDLE 7.62.0
CURLUE_BAD_PARTPOINTER 7.62.0
CURLUE_BAD_PORT_NUMBER 7.62.0