SSL configuration module docs
[openssl.git] / doc / ssl / SSL_CTX_config.pod
1 =pod
2
3 =head1 NAME
4
5 SSL_CTX_config, SSL_config - configure SSL_CTX or SSL structure.
6
7 =head1 SYNOPSIS
8
9  #include <openssl/ssl.h>
10
11  int SSL_CTX_config(SSL_CTX *ctx, const char *name);
12  int SSL_config(SSL *s, const char *name);
13
14 =head1 DESCRIPTION
15
16 The functions SSL_CTX_config() and SSL_config() configure an B<SSL_CTX> or
17 B<SSL> structure using the configuration B<name>.
18
19 =head1 NOTES
20
21 By calling SSL_CTX_config() or SSL_config() an application can perform many
22 complex tasks based on the contents of the configuration file: greatly
23 simplifying application configuration code. A degree of future proofing
24 can also be achieved: an application can support configuration features
25 in newer versions of OpenSSL automatically.
26
27 A configuration file must have been previously loaded, for example using
28 CONF_modules_load_file(). See L<config(3)> for details of the configuration
29 file syntax.
30
31 =head1 RETURN VALUES
32
33 SSL_CTX_config() and SSL_config() return 1 for success or 0 if an error
34 occurred.
35
36 =head1 EXAMPLE
37
38 If the file "config.cnf" contains the following:
39
40  testapp = test_sect
41
42  [test_sect]
43  # list of confuration modules
44
45  ssl_conf = ssl_sect
46
47  [ssl_sect]
48
49  server = server_section
50
51  [server_section]
52
53  RSA.Certificate = server-rsa.pem
54  ECDSA.Certificate = server-ecdsa.pem
55  Ciphers = ALL:!RC4
56
57 An application could call:
58
59  if (CONF_modules_load_file("config.cnf", "testapp", 0) <= 0) {
60       fprintf(stderr, "Error processing config file\n");
61       goto err;
62  }
63
64  ctx = SSL_CTX_new(TLS_server_method());
65
66  if (SSL_CTX_config(ctx, "server") == 0) {
67      fprintf(stderr, "Error configuring server.\n");
68      goto err;
69  }
70
71 In this example two certificates and the cipher list are configured without
72 the need for any additional application code.
73
74 =head1 SEE ALSO
75
76 L<config(3)>,
77 L<SSL_CONF_cmd(3)>,
78 L<CONF_modules_load_file(3)>
79
80 =head1 HISTORY
81
82 SSL_CTX_config() and SSL_config() were first added to OpenSSL 1.1.0
83
84 =cut