1---
2c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_ISSUERCERT
5Section: 3
6Source: libcurl
7See-also:
8  - CURLOPT_CRLFILE (3)
9  - CURLOPT_SSL_VERIFYHOST (3)
10  - CURLOPT_SSL_VERIFYPEER (3)
11---
12
13# NAME
14
15CURLOPT_ISSUERCERT - issuer SSL certificate filename
16
17# SYNOPSIS
18
19~~~c
20#include <curl/curl.h>
21
22CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ISSUERCERT, char *file);
23~~~
24
25# DESCRIPTION
26
27Pass a char pointer to a null-terminated string naming a *file* holding a CA
28certificate in PEM format. If the option is set, an additional check against
29the peer certificate is performed to verify the issuer is indeed the one
30associated with the certificate provided by the option. This additional check
31is useful in multi-level PKI where one needs to enforce that the peer
32certificate is from a specific branch of the tree.
33
34This option makes sense only when used in combination with the
35CURLOPT_SSL_VERIFYPEER(3) option. Otherwise, the result of the check is
36not considered as failure.
37
38A specific error code (CURLE_SSL_ISSUER_ERROR) is defined with the option,
39which is returned if the setup of the SSL/TLS session has failed due to a
40mismatch with the issuer of peer certificate (CURLOPT_SSL_VERIFYPEER(3)
41has to be set too for the check to fail). (Added in 7.19.0)
42
43The application does not have to keep the string around after setting this
44option.
45
46# DEFAULT
47
48NULL
49
50# PROTOCOLS
51
52All TLS-based protocols
53
54# EXAMPLE
55
56~~~c
57int main(void)
58{
59  CURL *curl = curl_easy_init();
60  if(curl) {
61    CURLcode res;
62    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
63    curl_easy_setopt(curl, CURLOPT_ISSUERCERT, "/etc/certs/cacert.pem");
64    res = curl_easy_perform(curl);
65    curl_easy_cleanup(curl);
66  }
67}
68~~~
69
70# AVAILABILITY
71
72If built TLS enabled
73
74# RETURN VALUE
75
76Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
77CURLE_OUT_OF_MEMORY if there was insufficient heap space.
78