Man page - tls_peer_cert_hash(3)

Packages contains this manual

Manual

TLS_CONN_VERSION (3) Library Functions Manual TLS_CONN_VERSION (3)

NAME

tls_conn_version, tls_conn_cipher, tls_conn_cipher_strength, tls_conn_alpn_selected, tls_conn_servername, tls_conn_session_resumed, tls_peer_cert_provided, tls_peer_cert_contains_name, tls_peer_cert_chain_pem, tls_peer_cert_issuer, tls_peer_cert_subject, tls_peer_cert_hash, tls_peer_cert_notbefore, tls_peer_cert_notafter — inspect an established TLS connection

SYNOPSIS

#include <tls.h>

const char *

tls_conn_version ( struct tls *ctx );

const char *

tls_conn_cipher ( struct tls *ctx );

int

tls_conn_cipher_strength ( struct tls *ctx );

const char *

tls_conn_alpn_selected ( struct tls *ctx );

const char *

tls_conn_servername ( struct tls *ctx );

int

tls_conn_session_resumed ( struct tls *ctx );

int

tls_peer_cert_provided ( struct tls *ctx );

int

tls_peer_cert_contains_name ( struct tls *ctx , const char *name );

const uint8_t *

tls_peer_cert_chain_pem ( struct tls *ctx , size_t *size );

const char *

tls_peer_cert_issuer ( struct tls *ctx );

const char *

tls_peer_cert_subject ( struct tls *ctx );

const char *

tls_peer_cert_hash ( struct tls *ctx );

time_t

tls_peer_cert_notbefore ( struct tls *ctx );

time_t

tls_peer_cert_notafter ( struct tls *ctx );

DESCRIPTION

These functions return information about a TLS connection and will only succeed after the handshake is complete (the connection information applies to both clients and servers, unless noted otherwise):

tls_conn_version () returns a string corresponding to a TLS version negotiated with the peer connected to ctx .

tls_conn_cipher () returns a string corresponding to the cipher suite negotiated with the peer connected to ctx .

tls_conn_cipher_strength () returns the strength in bits for the symmetric cipher that is being used with the peer connected to ctx .

tls_conn_alpn_selected () returns a string that specifies the ALPN protocol selected for use with the peer connected to ctx . If no protocol was selected then NULL is returned.

tls_conn_servername () returns a string corresponding to the servername that the client connected to ctx requested by sending a TLS Server Name Indication extension (server only).

tls_conn_session_resumed () indicates whether a TLS session has been resumed during the handshake with the server connected to ctx (client only).

tls_peer_cert_provided () checks if the peer of ctx has provided a certificate.

tls_peer_cert_contains_name () checks if the peer of a TLS ctx has provided a certificate that contains a SAN or CN that matches name .

tls_peer_cert_chain_pem () returns a pointer to memory containing a PEM-encoded certificate chain for the peer certificate from ctx .

tls_peer_cert_subject () returns a string corresponding to the subject of the peer certificate from ctx .

tls_peer_cert_issuer () returns a string corresponding to the issuer of the peer certificate from ctx .

tls_peer_cert_hash () returns a string corresponding to a hash of the raw peer certificate from ctx prefixed by a hash name followed by a colon. The hash currently used is SHA256, though this could change in the future. The hash string for a certificate in file mycert.crt can be generated using the commands:

h=$(openssl x509 -outform der -in mycert.crt | sha256)
printf "SHA256:${h}\n"

tls_peer_cert_notbefore () returns the time corresponding to the start of the validity period of the peer certificate from ctx .

tls_peer_cert_notafter () returns the time corresponding to the end of the validity period of the peer certificate from ctx .

RETURN VALUES

The tls_conn_session_resumed () function returns 1 if a TLS session was resumed or 0 if it was not.

The tls_peer_cert_provided () and tls_peer_cert_contains_name () functions return 1 if the check succeeds or 0 if it does not.

tls_peer_cert_notbefore () and tls_peer_cert_notafter () return a time in epoch-seconds on success or -1 on error.

The functions that return a pointer return NULL on error or an out of memory condition.

SEE ALSO

tls_configure (3), tls_handshake (3), tls_init (3), tls_ocsp_process_response (3)

HISTORY

tls_conn_version (), tls_conn_cipher (), tls_peer_cert_provided (), tls_peer_cert_contains_name (), tls_peer_cert_issuer (), tls_peer_cert_subject (), tls_peer_cert_hash (), tls_peer_cert_notbefore (), and tls_peer_cert_notafter () appeared in OpenBSD 5.9.

tls_conn_servername () and tls_conn_alpn_selected () appeared in OpenBSD 6.1.

tls_conn_session_resumed () appeared in OpenBSD 6.3.

tls_conn_cipher_strength () appeared in OpenBSD 6.7.

AUTHORS

Bob Beck < beck@openbsd.org >
Joel Sing < jsing@openbsd.org > Debian November 2, 2019 TLS_CONN_VERSION (3)