DragonFly On-Line Manual Pages
TLS(2) DragonFly System Calls Manual TLS(2)
NAME
set_tls_area, get_tls_area -- kernel TLS (thread local storage) support
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <sys/tls.h>
int
set_tls_area(int which, struct tls_info *info, size_t infosize);
int
get_tls_area(int which, struct tls_info *info, size_t infosize);
DESCRIPTION
The set_tls_area() system call creates an entry for the TLS facility
which representing thread local storage as specified by the info
structure. A descriptor representing the facility is returned, or -1 if
an error occurred. The facility may be cleared by specifying a NULL
pointer and an infosize of 0. The get_tls_area() system call retrieves
the requested TLS facility. A descriptor representing the facility is
returned, or -1 if an error occurred. If you simply want the descriptor
you may specify a NULL pointer and an infosize of 0.
The returned descriptor and the TLS mechanism is machine-dependent. On
IA32 three global segment descriptors are supported (0, 1, and 2) and
the %gs load value is returned.
The tls_info structure passed to set_tls_area() should first be zerod (to
remain compatible with future extensions) and then initialized.
struct tls_info {
void *base; /* base address of TLS area */
int size; /* size of TLS area in bytes */
};
The actual implementation of the area is machine-dependent. If the
kernel is unable to accommodate the supplied size it may create a larger
area. If the kernel is unable to accommodate the supplied base address
an error will be returned.
RETURN VALUES
A return value of 0 is returned on success, -1 on error.
EXAMPLES
/*
* Pseudo example showing how the TLS system calls work on IA32.
*/
#include <stdio.h>
#include <unistd.h>
#include <stdlib.h>
#include <errno.h>
#include <sys/tls.h>
int X;
static int getdata(int offset);
int
main(int ac, char **av)
{
int i;
int gs;
struct tls_info info;
info.base = &X;
info.size = sizeof(X);
if ((gs = set_tls_area(0, &info, sizeof(info))) < 0) {
perror("setarea");
exit(1);
}
printf("gs = %04x\n", gs);
__asm __volatile("mov %0,%%gs" : : "g" (gs) );
if (get_tls_area(0, &info, sizeof(info)) < 0) {
perror("getarea");
exit(1);
}
printf("%p/%d\n", info.base, info.size);
X = 1;
printf("should be 1: %d\n", getdata(0));
X = 2;
printf("should be 2: %d\n", getdata(0));
printf("this should fault:\n");
fflush(stdout);
getdata(4);
return(0);
}
static int
getdata(int offset)
{
int rv;
__asm __volatile("movl %%gs:(%0),%%eax; movl %%eax,%1" : "+r" (offset) : "m"
(rv) : "ax");
return (rv);
}
ERRORS
[ERANGE] The specified facility index, which, is not supported.
[EINVAL] An invalid parameter has been specified.
[ENOENT] (get_tls_area) The specified facility has not been
initialized with sys_set_tls_area().
SEE ALSO
umtx(2)
HISTORY
The set_tls_area(), and get_tls_area() function calls first appeared in
DragonFly 1.1.
DragonFly 5.5 February 21, 2005 DragonFly 5.5
TLS_CONN_VERSION(3) DragonFly Library Functions Manual TLS_CONN_VERSION(3)
NAME
tls_conn_version, tls_conn_cipher, 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);
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 nego-
tiated 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_alpn_selected() returns a string that specifies the ALPN proto-
col 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 cer-
tificate.
tls_peer_cert_contains_name() checks if the peer of a TLS ctx has pro-
vided 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 gen-
erated 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.
POINTER TO tls_ocsp_process_response(3)
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.
AUTHORS
Bob Beck <beck@openbsd.org>
Joel Sing <jsing@openbsd.org>
DragonFly 5.5 May 26, 2018 DragonFly 5.5