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_LOAD_FILE(3) DragonFly Library Functions Manual TLS_LOAD_FILE(3)
NAME
tls_load_file, tls_unload_file, tls_config_set_ca_file,
tls_config_set_ca_path, tls_config_set_ca_mem, tls_config_set_cert_file,
tls_config_set_cert_mem, tls_config_set_crl_file, tls_config_set_crl_mem,
tls_config_set_key_file, tls_config_set_key_mem,
tls_config_set_ocsp_staple_mem, tls_config_set_ocsp_staple_file,
tls_config_set_keypair_file, tls_config_set_keypair_mem,
tls_config_set_keypair_ocsp_file, tls_config_set_keypair_ocsp_mem,
tls_config_add_keypair_file, tls_config_add_keypair_ocsp_mem,
tls_config_add_keypair_ocsp_file, tls_config_add_keypair_mem,
tls_config_clear_keys, tls_config_set_verify_depth,
tls_config_verify_client, tls_config_verify_client_optional -- TLS cer-
tificate and key configuration
SYNOPSIS
#include <tls.h>
uint8_t *
tls_load_file(const char *file, size_t *len, char *password);
void
tls_unload_file(uint8_t *buf, size_t len);
int
tls_config_set_ca_file(struct tls_config *config, const char *ca_file);
int
tls_config_set_ca_path(struct tls_config *config, const char *ca_path);
int
tls_config_set_ca_mem(struct tls_config *config, const uint8_t *cert,
size_t len);
int
tls_config_set_cert_file(struct tls_config *config,
const char *cert_file);
int
tls_config_set_cert_mem(struct tls_config *config, const uint8_t *cert,
size_t len);
int
tls_config_set_crl_file(struct tls_config *config, const char *crl_file);
int
tls_config_set_crl_mem(struct tls_config *config, const uint8_t *crl,
size_t len);
int
tls_config_set_key_file(struct tls_config *config, const char *key_file);
int
tls_config_set_key_mem(struct tls_config *config, const uint8_t *key,
size_t len);
int
tls_config_set_ocsp_staple_mem(struct tls_config *config,
const uint8_t *staple, size_t len);
int
tls_config_set_ocsp_staple_file(struct tls_config *config,
const char *staple_file);
int
tls_config_set_keypair_file(struct tls_config *config,
const char *cert_file, const char *key_file);
int
tls_config_set_keypair_mem(struct tls_config *config,
const uint8_t *cert, size_t cert_len, const uint8_t *key,
size_t key_len);
int
tls_config_set_keypair_ocsp_file(struct tls_config *config,
const char *cert_file, const char *key_file,
const char *staple_file);
int
tls_config_set_keypair_ocsp_mem(struct tls_config *config,
const uint8_t *cert, size_t cert_len, const uint8_t *key,
size_t key_len, const uint8_t *staple, size_t staple_len);
int
tls_config_add_keypair_file(struct tls_config *config,
const char *cert_file, const char *key_file);
int
tls_config_add_keypair_mem(struct tls_config *config,
const uint8_t *cert, size_t cert_len, const uint8_t *key,
size_t key_len);
int
tls_config_add_keypair_ocsp_file(struct tls_config *config,
const char *cert_file, const char *key_file,
const char *staple_file);
int
tls_config_add_keypair_ocsp_mem(struct tls_config *config,
const uint8_t *cert, size_t cert_len, const uint8_t *key,
size_t key_len, const uint8_t *staple, size_t staple_len);
void
tls_config_clear_keys(struct tls_config *config);
int
tls_config_set_verify_depth(struct tls_config *config, int verify_depth);
void
tls_config_verify_client(struct tls_config *config);
void
tls_config_verify_client_optional(struct tls_config *config);
DESCRIPTION
tls_load_file() loads a certificate or key from disk into memory to be
used with tls_config_set_ca_mem(), tls_config_set_cert_mem(),
tls_config_set_crl_mem() or tls_config_set_key_mem(). A private key will
be decrypted if the optional password argument is specified.
tls_unload_file() unloads the memory that was returned from an earlier
tls_load_file() call, ensuring that the memory contents is discarded.
tls_config_set_ca_file() sets the filename used to load a file containing
the root certificates.
tls_config_set_ca_path() sets the path (directory) which should be
searched for root certificates.
tls_config_set_ca_mem() sets the root certificates directly from memory.
tls_config_set_cert_file() sets file from which the public certificate
will be read.
tls_config_set_cert_mem() sets the public certificate directly from mem-
ory.
tls_config_set_crl_file() sets the filename used to load a file contain-
ing the Certificate Revocation List (CRL).
tls_config_set_crl_mem() sets the CRL directly from memory.
tls_config_set_key_file() sets the file from which the private key will
be read.
tls_config_set_key_mem() directly sets the private key from memory.
tls_config_set_ocsp_staple_file() sets a DER-encoded OCSP response to be
stapled during the TLS handshake from the specified file.
tls_config_set_ocsp_staple_mem() sets a DER-encoded OCSP response to be
stapled during the TLS handshake from memory.
tls_config_set_keypair_file() sets the files from which the public cer-
tificate, and private key will be read.
tls_config_set_keypair_mem() directly sets the public certificate, and
private key from memory.
tls_config_set_keypair_ocsp_file() sets the files from which the public
certificate, private key, and DER-encoded OCSP staple will be read.
tls_config_set_keypair_ocsp_mem() directly sets the public certificate,
private key, and DER-encoded OCSP staple from memory.
tls_config_add_keypair_file() adds an additional public certificate, and
private key from the specified files, used as an alternative certificate
for Server Name Indication (server only).
tls_config_add_keypair_mem() adds an additional public certificate, and
private key from memory, used as an alternative certificate for Server
Name Indication (server only).
tls_config_add_keypair_ocsp_file() adds an additional public certificate,
private key, and DER-encoded OCSP staple from the specified files, used
as an alternative certificate for Server Name Indication (server only).
tls_config_add_keypair_ocsp_mem() adds an additional public certificate,
private key, and DER-encoded OCSP staple from memory, used as an alterna-
tive certificate for Server Name Indication (server only).
tls_config_clear_keys() clears any secret keys from memory.
tls_config_set_verify_depth() limits the number of intermediate certifi-
cates that will be followed during certificate validation.
tls_config_verify_client() enables client certificate verification,
requiring the client to send a certificate (server only).
tls_config_verify_client_optional() enables client certificate verifica-
tion, without requiring the client to send a certificate (server only).
RETURN VALUES
tls_load_file() returns NULL on error or an out of memory condition.
The other functions return 0 on success or -1 on error.
SEE ALSO
tls_config_ocsp_require_stapling(3), tls_config_set_protocols(3),
tls_config_set_session_id(3), tls_configure(3), tls_init(3)
HISTORY
tls_config_set_ca_file(), tls_config_set_ca_path(),
tls_config_set_cert_file(), tls_config_set_cert_mem(),
tls_config_set_key_file(), tls_config_set_key_mem(), and
tls_config_set_verify_depth() appeared in OpenBSD 5.6 and got their final
names in OpenBSD 5.7.
tls_load_file(), tls_config_set_ca_mem(), and tls_config_clear_keys()
appeared in OpenBSD 5.7.
tls_config_verify_client() and tls_config_verify_client_optional()
appeared in OpenBSD 5.9.
tls_config_set_keypair_file() and tls_config_set_keypair_mem() appeared
in OpenBSD 6.0, and tls_config_add_keypair_file() and
tls_config_add_keypair_mem() in OpenBSD 6.1.
tls_config_set_crl_file() and tls_config_set_crl_mem() appeared in
OpenBSD 6.2.
AUTHORS
Joel Sing <jsing@openbsd.org> with contibutions from
Ted Unangst <tedu@openbsd.org> and
Bob Beck <beck@openbsd.org>.
tls_load_file() and tls_config_set_ca_mem() were written by
Reyk Floeter <reyk@openbsd.org>.
DragonFly 5.5 August 21, 2018 DragonFly 5.5