Artifactspublic-v0

curl

master
ply4 git calls214 ms289 KiB2 cachedprotocol v2
172 lines4.8 KiBRaw

NAME

CURLINFO_TLS_SSL_PTR - TLS session info

SYNOPSIS

c
#include <curl/curl.h>

CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_TLS_SSL_PTR,
                           struct curl_tlssessioninfo **session);

DESCRIPTION

Pass a pointer to a struct curl_tlssessioninfo *. The pointer is initialized to refer to a struct curl_tlssessioninfo * that contains an enum indicating the SSL library used for the handshake and a pointer to the respective internal TLS session structure of this underlying SSL library.

This option may be useful for example to extract certificate information in a format convenient for further processing, such as manual validation. Refer to the LIMITATIONS section.

c
struct curl_tlssessioninfo {
  curl_sslbackend backend;
  void *internals;
};

The backend struct member is one of these defines: CURLSSLBACKEND_NONE (when built without TLS support), CURLSSLBACKEND_WOLFSSL, CURLSSLBACKEND_SECURETRANSPORT, CURLSSLBACKEND_GNUTLS, CURLSSLBACKEND_MBEDTLS, CURLSSLBACKEND_NSS, CURLSSLBACKEND_OPENSSL or CURLSSLBACKEND_SCHANNEL. (Note that the OpenSSL forks are all reported as OpenSSL here.)

The internals struct member points to a TLS library specific pointer for the active ("in use") SSL connection, with the following underlying types:

GnuTLS

gnutls_session_t

OpenSSL

CURLINFO_TLS_SESSION(3): SSL_CTX *

CURLINFO_TLS_SSL_PTR(3): SSL *

mbedTLS

mbedTLS_ssl_context *

Secure Channel

CtxtHandle *

wolfSSL

SSL *

If the internals pointer is NULL then either the SSL backend is not supported, an SSL session has not yet been established or the connection is no longer associated with the easy handle (e.g. curl_easy_perform(3) has returned).

LIMITATIONS

This option has some limitations that could make it unsafe when it comes to the manual verification of certificates.

This option only retrieves the first in-use SSL session pointer for your easy handle, however your easy handle may have more than one in-use SSL session if using FTP over SSL. That is because the FTP protocol has a control channel and a data channel and one or both may be over SSL. Currently there is no way to retrieve a second in-use SSL session associated with an easy handle.

This option has not been thoroughly tested with clear text protocols that can be upgraded/downgraded to/from SSL: FTP, SMTP, POP3, IMAP when used with CURLOPT_USE_SSL(3). Though you can to retrieve the SSL pointer, it is possible that before you can do that, data (including auth) may have already been sent over a connection after it was upgraded.

Renegotiation. If unsafe renegotiation or renegotiation in a way that the certificate is allowed to change is allowed by your SSL library this may occur and the certificate may change, and data may continue to be sent or received after renegotiation but before you are able to get the (possibly) changed SSL pointer, with the (possibly) changed certificate information.

Instead of using this option to poll for certificate changes use CURLOPT_SSL_CTX_FUNCTION(3) to set a verification callback, if supported. That is safer and does not suffer from any of the problems above.

How are you using this option? Are you affected by any of these limitations? Please let us know by making a comment at https://github.com/curl/curl/issues/685

%PROTOCOLS%

EXAMPLE

c
#include <curl/curl.h>
#include <openssl/ssl.h>

static CURL *curl;

static size_t wf(char *ptr, size_t size, size_t nmemb, void *stream)
{
  const struct curl_tlssessioninfo *info = NULL;
  CURLcode result = curl_easy_getinfo(curl, CURLINFO_TLS_SSL_PTR, &info);
  if(info && !result) {
    if(CURLSSLBACKEND_OPENSSL == info->backend) {
      printf("OpenSSL ver. %s\n", SSL_get_version((SSL*)info->internals));
    }
  }
  return size * nmemb;
}

int main(int argc, char *argv[])
{
  CURLcode result = CURLE_OK;
  curl = curl_easy_init();
  if(curl) {
    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
    curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, wf);
    result = curl_easy_perform(curl);
    curl_easy_cleanup(curl);
  }
  return (int)result;
}

HISTORY

This option supersedes CURLINFO_TLS_SESSION(3) which was added in 7.34.0. This option is exactly the same as that option except in the case of OpenSSL.

Non-OpenSSL support was added in 7.48.0.

%AVAILABILITY%

RETURN VALUE

curl_easy_getinfo(3) returns a CURLcode indicating success or error.

CURLE_OK (0) means everything was OK, non-zero means an error occurred, see libcurl-errors(3).

1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLINFO_TLS_SSL_PTR
5Section: 3
6Source: libcurl
7See-also:
8 - CURLINFO_TLS_SESSION (3)
9 - curl_easy_getinfo (3)
10 - curl_easy_setopt (3)
11Protocol:
12 - TLS
13TLS-backend:
14 - GnuTLS
15 - mbedTLS
16 - OpenSSL
17 - Schannel
18 - wolfSSL
19Added-in: 7.48.0
20---
22# NAME
24CURLINFO_TLS_SSL_PTR - TLS session info
26# SYNOPSIS
28~~~c
29#include <curl/curl.h>
31CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_TLS_SSL_PTR,
32 struct curl_tlssessioninfo **session);
33~~~
35# DESCRIPTION
37Pass a pointer to a *struct curl_tlssessioninfo **. The pointer is initialized
38to refer to a *struct curl_tlssessioninfo ** that contains an enum indicating
39the SSL library used for the handshake and a pointer to the respective
40internal TLS session structure of this underlying SSL library.
42This option may be useful for example to extract certificate information in a
43format convenient for further processing, such as manual validation. Refer to
44the **LIMITATIONS** section.
46~~~c
47struct curl_tlssessioninfo {
48 curl_sslbackend backend;
49 void *internals;
50};
51~~~
53The *backend* struct member is one of these defines: CURLSSLBACKEND_NONE (when
54built without TLS support), CURLSSLBACKEND_WOLFSSL,
55CURLSSLBACKEND_SECURETRANSPORT, CURLSSLBACKEND_GNUTLS, CURLSSLBACKEND_MBEDTLS,
56CURLSSLBACKEND_NSS, CURLSSLBACKEND_OPENSSL or CURLSSLBACKEND_SCHANNEL. (Note
57that the OpenSSL forks are all reported as OpenSSL here.)
59The *internals* struct member points to a TLS library specific pointer for
60the active ("in use") SSL connection, with the following underlying types:
62## GnuTLS
64**gnutls_session_t**
66## OpenSSL
68CURLINFO_TLS_SESSION(3): **SSL_CTX ***
70CURLINFO_TLS_SSL_PTR(3): **SSL ***
72## mbedTLS
74**mbedTLS_ssl_context ***
76## Secure Channel
78**CtxtHandle ***
80## wolfSSL
82**SSL ***
84##
86If the *internals* pointer is NULL then either the SSL backend is not
87supported, an SSL session has not yet been established or the connection is no
88longer associated with the easy handle (e.g. curl_easy_perform(3) has
89returned).
91# LIMITATIONS
93This option has some limitations that could make it unsafe when it comes to
94the manual verification of certificates.
96This option only retrieves the first in-use SSL session pointer for your easy
97handle, however your easy handle may have more than one in-use SSL session if
98using FTP over SSL. That is because the FTP protocol has a control channel and
99a data channel and one or both may be over SSL. Currently there is no way to
100retrieve a second in-use SSL session associated with an easy handle.
102This option has not been thoroughly tested with clear text protocols that can
103be upgraded/downgraded to/from SSL: FTP, SMTP, POP3, IMAP when used with
104CURLOPT_USE_SSL(3). Though you can to retrieve the SSL pointer, it is possible
105that before you can do that, data (including auth) may have already been sent
106over a connection after it was upgraded.
108Renegotiation. If unsafe renegotiation or renegotiation in a way that the
109certificate is allowed to change is allowed by your SSL library this may occur
110and the certificate may change, and data may continue to be sent or received
111after renegotiation but before you are able to get the (possibly) changed SSL
112pointer, with the (possibly) changed certificate information.
114Instead of using this option to poll for certificate changes use
115CURLOPT_SSL_CTX_FUNCTION(3) to set a verification callback, if supported.
116That is safer and does not suffer from any of the problems above.
118How are you using this option? Are you affected by any of these limitations?
119Please let us know by making a comment at
120https://github.com/curl/curl/issues/685
122# %PROTOCOLS%
124# EXAMPLE
126~~~c
127#include <curl/curl.h>
128#include <openssl/ssl.h>
130static CURL *curl;
132static size_t wf(char *ptr, size_t size, size_t nmemb, void *stream)
134 const struct curl_tlssessioninfo *info = NULL;
135 CURLcode result = curl_easy_getinfo(curl, CURLINFO_TLS_SSL_PTR, &info);
136 if(info && !result) {
137 if(CURLSSLBACKEND_OPENSSL == info->backend) {
138 printf("OpenSSL ver. %s\n", SSL_get_version((SSL*)info->internals));
139 }
140 }
141 return size * nmemb;
144int main(int argc, char *argv[])
146 CURLcode result = CURLE_OK;
147 curl = curl_easy_init();
148 if(curl) {
149 curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
150 curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, wf);
151 result = curl_easy_perform(curl);
152 curl_easy_cleanup(curl);
153 }
154 return (int)result;
156~~~
158# HISTORY
160This option supersedes CURLINFO_TLS_SESSION(3) which was added in 7.34.0.
161This option is exactly the same as that option except in the case of OpenSSL.
163Non-OpenSSL support was added in 7.48.0.
165# %AVAILABILITY%
167# RETURN VALUE
169curl_easy_getinfo(3) returns a CURLcode indicating success or error.
171CURLE_OK (0) means everything was OK, non-zero means an error occurred, see
172libcurl-errors(3).
Diagnostics4 git calls · 214 ms
CallStatusSizeTime0214 ms
discover200152 B3 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
git.response.bytes=152
git.server.agent=gitty/1.0
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch object-format
git.server.fetch=shallow filter sideband-all
git.protocol.version=2
git.pkt.frames=8
git.pkt.data=6
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=152
git.pkt.payload.max=34
ls-refs200149 B · hit3 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
git.response.bytes=149
git.response.cache=HIT
git.response.duration_ms=3
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=149
git.pkt.payload.max=78
git.ls_refs.count=2
git.ls_refs.head=refs/heads/master
fetchblob:none · deepen 10200287 KiB · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=3
git.response.bytes=293470
git.response.cache=HIT
git.response.duration_ms=3
git.fetch.filter=blob:none
git.fetch.filter.requested=tree:0
git.fetch.filter.fallback=blob:none
git.fetch.filter.learned=false
git.fetch.wants=31c911efe5652725e930f4d2e60c9060e5f6646d
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=10
git.pkt.data=8
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=293470
git.pkt.payload.max=65516
git.sideband.band1.bytes=293354
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=87
git.pack.bytes=293354
git.pack.ofs_delta=0
git.pack.ref_delta=1
git.pack.chain.max=1
git.pack.trailer=6a646bcda6740bab42e321b51998b52ea15146c0
git.pack.full=86
Open pack map
fetch2002.3 KiB208 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=208
git.response.bytes=2311
git.response.cache=MISS
git.response.duration_ms=208
git.fetch.wants=f5c979b57177d0ab6178aea0efe499332223bdf4
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=2311
git.pkt.payload.max=2290
git.sideband.band1.bytes=2289
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.

Remote
https://5ad2236b39de4c8bd8f6270ea63f3ea9.artifacts.cloudflare.net/git/public-v0/curl.git
Ref
refs/heads/master
Commit
31c911efe5652725e930f4d2e60c9060e5f6646d
cf-ray
a5e31323eb243e6e
Request
f9fc8006…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format