aboutsummaryrefslogtreecommitdiffstats
path: root/lib/ssl/doc/src
diff options
context:
space:
mode:
authorIngela Anderton Andin <[email protected]>2015-05-04 11:06:09 +0200
committerIngela Anderton Andin <[email protected]>2015-05-04 11:06:09 +0200
commite14b011a35b39e12d75786b07f5fd27e09530dad (patch)
tree9b49a28e65e38648b7ec5254ce9ac06ff434c10c /lib/ssl/doc/src
parent33a27226f7402b2daea5c107e94790426e66ea74 (diff)
parent3ca0dbbcfaab00810c2c19980a2e7041d6ba5567 (diff)
downloadotp-e14b011a35b39e12d75786b07f5fd27e09530dad.tar.gz
otp-e14b011a35b39e12d75786b07f5fd27e09530dad.tar.bz2
otp-e14b011a35b39e12d75786b07f5fd27e09530dad.zip
Merge branch 'ia/ssl/docs'
* ia/ssl/docs: ssl: Add missing tag ssl: Put back marker ssl: Fix links ssl: Align with application naming rules ssl: Keep information in one place only ssl: Correct makefile
Diffstat (limited to 'lib/ssl/doc/src')
-rw-r--r--lib/ssl/doc/src/Makefile2
-rw-r--r--lib/ssl/doc/src/ssl.xml39
-rw-r--r--lib/ssl/doc/src/ssl_app.xml16
-rw-r--r--lib/ssl/doc/src/ssl_crl_cache.xml6
-rw-r--r--lib/ssl/doc/src/ssl_crl_cache_api.xml2
-rw-r--r--lib/ssl/doc/src/ssl_distribution.xml38
-rw-r--r--lib/ssl/doc/src/ssl_protocol.xml10
-rw-r--r--lib/ssl/doc/src/ssl_session_cache_api.xml4
-rw-r--r--lib/ssl/doc/src/using_ssl.xml4
9 files changed, 60 insertions, 61 deletions
diff --git a/lib/ssl/doc/src/Makefile b/lib/ssl/doc/src/Makefile
index cfbf98f6e3..143756bd39 100644
--- a/lib/ssl/doc/src/Makefile
+++ b/lib/ssl/doc/src/Makefile
@@ -37,7 +37,7 @@ RELSYSDIR = $(RELEASE_PATH)/lib/$(APPLICATION)-$(VSN)
# Target Specs
# ----------------------------------------------------
XML_APPLICATION_FILES = refman.xml
-XML_REF3_FILES = ssl.xml ssl_crl_cache.xml ssl_crl_cache.xml ssl_session_cache_api.xml
+XML_REF3_FILES = ssl.xml ssl_crl_cache.xml ssl_crl_cache_api.xml ssl_session_cache_api.xml
XML_REF6_FILES = ssl_app.xml
XML_PART_FILES = release_notes.xml usersguide.xml
diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml
index d070cb4019..cdf6870c25 100644
--- a/lib/ssl/doc/src/ssl.xml
+++ b/lib/ssl/doc/src/ssl.xml
@@ -37,8 +37,7 @@
<title>SSL</title>
<list type="bulleted">
- <item><c>ssl</c> requires the <c>crypto</c> and <c>public_key</c>
- applications.</item>
+ <item>For application dependencies see <seealso marker="ssl_app"> ssl(6)</seealso> </item>
<item>Supported SSL/TLS-versions are SSL-3.0, TLS-1.0,
TLS-1.1, and TLS-1.2.</item>
<item>For security reasons SSL-2.0 is not supported.</item>
@@ -46,7 +45,7 @@
but can be configured.</item>
<item>Ephemeral Diffie-Hellman cipher suites are supported,
but not Diffie Hellman Certificates cipher suites.</item>
- <item>Elliptic Curve cipher suites are supported if the <c>crypto</c>
+ <item>Elliptic Curve cipher suites are supported if the Crypto
application supports it and named curves are used.
</item>
<item>Export cipher suites are not supported as the
@@ -64,7 +63,7 @@
<section>
<title>DATA TYPES</title>
- <p>The following data types are used in the functions for <c>ssl</c>:</p>
+ <p>The following data types are used in the functions for SSL:</p>
<taglist>
@@ -82,9 +81,9 @@
<p>For valid options, see the
<seealso marker="kernel:inet">inet(3)</seealso> and
<seealso marker="kernel:gen_tcp">gen_tcp(3)</seealso> manual pages
- in <c>kernel</c>.</p></item>
+ in Kernel.</p></item>
- <tag><c>ssloption()</c></tag>
+ <tag><marker id="type-ssloption"></marker><c>ssloption()</c></tag>
<item><p><c>= {verify, verify_type()}</c></p>
<p><c>| {verify_fun, {fun(), term()}}</c></p>
<p><c>| {fail_if_no_peer_cert, boolean()} {depth, integer()}</c></p>
@@ -262,7 +261,7 @@ atom()}} |
</code>
<p>The verification fun is called during the X509-path
- validation when an error or an extension unknown to the <c>ssl</c>
+ validation when an error or an extension unknown to the SSL
application is encountered. It is also called
when a certificate is considered valid by the path validation
to allow access to each certificate in the path to the user
@@ -339,7 +338,7 @@ marker="public_key:public_key#pkix_path_validation-3">public_key:pkix_path_valid
<tag><c>{crl_check, boolean() | peer | best_effort }</c></tag>
<item>
Perform CRL (Certificate Revocation List) verification
- <seealso marker="public_key:public_key#pkix_crl_validate-3">
+ <seealso marker="public_key:public_key#pkix_crls_validate-3">
(public_key:pkix_crls_validate/3)</seealso> on all the certificates during the path validation
<seealso
marker="public_key:public_key#pkix_path_validation-3">(public_key:pkix_path_validation/3)
@@ -376,14 +375,15 @@ marker="public_key:public_key#pkix_path_validation-3">public_key:pkix_path_valid
<tag><c>{partial_chain, fun(Chain::[DerCert]) -> {trusted_ca, DerCert} |
unknown_ca }</c></tag>
<item><p>Claim an intermediate CA in the chain as trusted. TLS then
- performs <c>public_key:pkix_path_validation/3</c>
+ performs <seealso
+ marker="public_key:public_key#pkix_path_validation-3">public_key:pkix_path_validation/3</seealso>
with the selected CA as trusted anchor and the rest of the chain.</p></item>
<tag><c>{versions, [protocol()]}</c></tag>
<item><p>TLS protocol versions supported by started clients and servers.
This option overrides the application environment option
<c>protocol_version</c>. If the environment option is not set, it defaults
- to all versions, except SSL-3.0, supported by the <c>ssl</c> application.
+ to all versions, except SSL-3.0, supported by the SSL application.
See also <seealso marker="ssl:ssl_app">ssl(6).</seealso></p></item>
<tag><c>{hibernate_after, integer()|undefined}</c></tag>
@@ -1000,21 +1000,21 @@ fun(srp, Username :: string(), UserState :: term()) ->
<func>
<name>start() -> </name>
<name>start(Type) -> ok | {error, Reason}</name>
- <fsummary>Starts the <c>ssl</c>application.</fsummary>
+ <fsummary>Starts the SSL application.</fsummary>
<type>
<v>Type = permanent | transient | temporary</v>
</type>
<desc>
- <p>Starts the <c>ssl</c> application. Default type
+ <p>Starts the SSL application. Default type
is <c>temporary</c>.</p>
</desc>
</func>
<func>
<name>stop() -> ok </name>
- <fsummary>Stops the <c>ssl</c> application.</fsummary>
+ <fsummary>Stops the SSL application.</fsummary>
<desc>
- <p>Stops the <c>ssl</c> application.</p>
+ <p>Stops the SSL application.</p>
</desc>
</func>
@@ -1056,16 +1056,16 @@ fun(srp, Username :: string(), UserState :: term()) ->
<func>
<name>versions() -> [versions_info()]</name>
<fsummary>Returns version information relevant for the
- <c>ssl</c> application.</fsummary>
+ SSL application.</fsummary>
<type>
<v>versions_info() = {app_vsn, string()} | {supported | available, [protocol()] </v>
</type>
<desc>
- <p>Returns version information relevant for the <c>ssl</c>
+ <p>Returns version information relevant for the SSL
application.</p>
<taglist>
<tag><c>app_vsn</c></tag>
- <item>The application version of the <c>ssl</c> application.</item>
+ <item>The application version of the SSL application.</item>
<tag><c>supported</c></tag>
<item>TLS/SSL versions supported by default.
@@ -1078,8 +1078,8 @@ fun(srp, Username :: string(), UserState :: term()) ->
</seealso>.</item>
<tag><c>available</c></tag>
- <item>All TLS/SSL versions supported by the <c>ssl</c> application.
- TLS 1.2 requires sufficient support from the <c>crypto</c>
+ <item>All TLS/SSL versions supported by the SSL application.
+ TLS 1.2 requires sufficient support from the Crypto
application.</item>
</taglist>
</desc>
@@ -1095,4 +1095,3 @@ fun(srp, Username :: string(), UserState :: term()) ->
</section>
</erlref>
-
diff --git a/lib/ssl/doc/src/ssl_app.xml b/lib/ssl/doc/src/ssl_app.xml
index 43c69ba377..f17f5cb9fe 100644
--- a/lib/ssl/doc/src/ssl_app.xml
+++ b/lib/ssl/doc/src/ssl_app.xml
@@ -35,21 +35,21 @@
<description></description>
<section>
<title>DEPENDENCIES</title>
- <p>The <c>ssl</c> application uses the <c>public_key</c> and
- <c>crypto</c> application to handle public keys and encryption, hence
- these applications must be loaded for the <c>ssl</c> application to work.
+ <p>The SSL application uses the <c>public_key</c> and
+ Crypto application to handle public keys and encryption, hence
+ these applications must be loaded for the SSL application to work.
In an embedded environment this means they must be started with
- <c>application:start/[1,2]</c> before the <c>ssl</c> application is
+ <c>application:start/[1,2]</c> before the SSL application is
started.</p>
</section>
<section>
<title>CONFIGURATION</title>
<p>The application environment configuration parameters in this section
- are defined for the <c>ssl</c> application. For more information
+ are defined for the SSL application. For more information
about configuration parameters, see the
<seealso marker="kernel:application">application(3)</seealso>
- manual page in <c>kernel</c>.</p>
+ manual page in Kernel.</p>
<p>The environment parameters can be set on the command line,
for example:</p>
@@ -60,7 +60,7 @@
<tag><c><![CDATA[protocol_version = <seealso marker="kernel:error_logger">ssl:protocol()</seealso> <optional>]]></c>.</tag>
<item><p>Protocol supported by started clients and
servers. If this option is not set, it defaults to all
- protocols currently supported by the <c>ssl</c> application.
+ protocols currently supported by the SSL application.
This option can be overridden by the version option
to <c>ssl:connect/[2,3]</c> and <c>ssl:listen/2</c>.</p></item>
@@ -91,7 +91,7 @@
<section>
<title>ERROR LOGGER AND EVENT HANDLERS</title>
- <p>The <c>ssl</c> applications uses the default <seealso marker="kernel:error_logger">OTP error logger</seealso> to log unexpected errors and TLS alerts. The logging of TLS alerts may be turned off with the <c>log_alert</c> option. </p>
+ <p>The SSL application uses the default <seealso marker="kernel:error_logger">OTP error logger</seealso> to log unexpected errors and TLS alerts. The logging of TLS alerts may be turned off with the <c>log_alert</c> option. </p>
</section>
<section>
diff --git a/lib/ssl/doc/src/ssl_crl_cache.xml b/lib/ssl/doc/src/ssl_crl_cache.xml
index 62bf2ea7b7..83b03375b1 100644
--- a/lib/ssl/doc/src/ssl_crl_cache.xml
+++ b/lib/ssl/doc/src/ssl_crl_cache.xml
@@ -29,7 +29,7 @@
<p>
Implements an internal CRL (Certificate Revocation List) cache.
In addition to implementing the <seealso
- marker="ssl_cache_crl_api"> ssl_cache_crl_api</seealso> behaviour
+ marker="ssl_crl_cache_api"> ssl_crl_cache_api</seealso> behaviour
the following functions are available.
</p>
</description>
@@ -44,7 +44,7 @@
<v> Reason = term()</v>
</type>
<desc>
- Delete CRLs from the ssl applications local cache.
+ <p>Delete CRLs from the ssl applications local cache. </p>
</desc>
</func>
<func>
@@ -58,7 +58,7 @@
<v> Reason = term()</v>
</type>
<desc>
- Insert CRLs into the ssl applications local cache.
+ <p>Insert CRLs into the ssl applications local cache. </p>
</desc>
</func>
</funcs>
diff --git a/lib/ssl/doc/src/ssl_crl_cache_api.xml b/lib/ssl/doc/src/ssl_crl_cache_api.xml
index 557b7814b8..1d9353a2cc 100644
--- a/lib/ssl/doc/src/ssl_crl_cache_api.xml
+++ b/lib/ssl/doc/src/ssl_crl_cache_api.xml
@@ -70,7 +70,7 @@
</type>
<desc>
<p> <c>fun fresh_crl/2 </c> will be used as input option <c>update_crl</c> to
- <seealso marker="public_key#pkix_path_validation-3">public_key:pkix_crls_validate/3 </seealso> </p>
+ <seealso marker="public_key:public_key#pkix_crls_validate-3">public_key:pkix_crls_validate/3 </seealso> </p>
</desc>
</func>
diff --git a/lib/ssl/doc/src/ssl_distribution.xml b/lib/ssl/doc/src/ssl_distribution.xml
index c9f7b1b27f..effb304938 100644
--- a/lib/ssl/doc/src/ssl_distribution.xml
+++ b/lib/ssl/doc/src/ssl_distribution.xml
@@ -38,11 +38,11 @@
connection-based protocol as bearer. However, a module that
implements the protocol-specific parts of the connection setup is
needed. The default distribution module is <c>inet_tcp_dist</c>
- in the <c>kernel</c> application. When starting an
+ in the Kernel application. When starting an
Erlang node distributed, <c>net_kernel</c> uses this module to
set up listen ports and connections.</p>
- <p>In the <c>ssl</c> application, an exra distribution
+ <p>In the SSL application, an exra distribution
module, <c>inet_tls_dist</c>, can be used as an
alternative. All distribution connections will use SSL and
all participating Erlang nodes in a distributed system must use
@@ -57,7 +57,7 @@
<list type="bulleted">
<item><em>Step 1:</em> Build boot scripts including the
- <c>ssl</c> application.</item>
+ SSL application.</item>
<item><em>Step 2:</em> Specify the distribution module for
<c>net_kernel</c>.</item>
<item><em>Step 3:</em> Specify the security options and other
@@ -74,8 +74,8 @@
see the <c>sasl</c> documentation. This is only an example of
what can be done.</p>
- <p>The simplest boot script possible includes only the <c>kernel</c>
- and <c>stdlib</c> applications. Such a script is located in the
+ <p>The simplest boot script possible includes only the Kernel
+ and STDLIB applications. Such a script is located in the
<c>bin</c> directory of the Erlang distribution. The source for the
script is found under the Erlang installation top directory under
<c><![CDATA[releases/<OTP version>/start_clean.rel]]></c>.</p>
@@ -84,12 +84,12 @@
<list type="bulleted">
<item><p>Copy that script to another location (and preferably another
name).</p></item>
- <item><p>Add the applications <c>crypto</c>, <c>public_key</c>, and
- <c>ssl</c> with their current version numbers after the
- <c>stdlib</c>application.</p></item>
+ <item><p>Add the applications Crypto, Public Key, and
+ SSL with their current version numbers after the
+ STDLIB application.</p></item>
</list>
- <p>The following shows an example <c>.rel</c> file with <c>ssl</c>
+ <p>The following shows an example <c>.rel</c> file with SSL
added:</p>
<code type="none">
{release, {"OTP APN 181 01","R15A"}, {erts, "5.9"},
@@ -132,27 +132,27 @@ Eshell V5.0 (abort with ^G)
1> whereis(ssl_manager).
<0.41.0> ]]></code>
- <p>The <c>whereis</c> function-call verifies that the <c>ssl</c>
+ <p>The <c>whereis</c> function-call verifies that the SSL
application is started.</p>
<p>As an alternative to building a bootscript, you can explicitly
- add the path to the <c>ssl</c> <c>ebin</c> directory on the command
+ add the path to the SSL <c>ebin</c> directory on the command
line. This is done with command-line option <c>-pa</c>. This
- works as the <c>ssl</c> application does not need to be started for the
- distribution to come up, as a clone of the <c>ssl</c> application is
- hooked into the <c>kernel</c> application. So, as long as the
- <c>ssl</c> application code can be reached, the distribution starts.
+ works as the SSL application does not need to be started for the
+ distribution to come up, as a clone of the SSL application is
+ hooked into the Kernel application. So, as long as the
+ SSL application code can be reached, the distribution starts.
The <c>-pa</c> method is only recommended for testing purposes.</p>
- <note><p>The clone of the <c>ssl</c> application must
+ <note><p>The clone of the SSL application must
enable the use of the SSL code in such an early bootstage as
needed to set up the distribution. However, this makes it
- impossible to soft upgrade the <c>ssl</c> application.</p></note>
+ impossible to soft upgrade the SSL application.</p></note>
</section>
<section>
<title>Specifying Distribution Module for net_kernel</title>
- <p>The distribution module for <c>ssl</c> is named <c>inet_tls_dist</c>
+ <p>The distribution module for SSL is named <c>inet_tls_dist</c>
and is specified on the command line with option <c>-proto_dist</c>.
The argument to <c>-proto_dist</c> is to be the module
name without suffix <c>_dist</c>. So, this distribution
@@ -172,7 +172,7 @@ Eshell V5.0 (abort with ^G)
(ssl_test@myhost)1> </code>
<p>However, a node started in this way refuses to talk
- to other nodes, as no <c>ssl</c> parameters are supplied
+ to other nodes, as no SSL parameters are supplied
(see the next section).</p>
</section>
diff --git a/lib/ssl/doc/src/ssl_protocol.xml b/lib/ssl/doc/src/ssl_protocol.xml
index 20f53c98e1..cc49515066 100644
--- a/lib/ssl/doc/src/ssl_protocol.xml
+++ b/lib/ssl/doc/src/ssl_protocol.xml
@@ -32,19 +32,19 @@
<file>ssl_protocol.xml</file>
</header>
- <p>The Erlang <c>ssl</c> application implements the SSL/TLS protocol
+ <p>The Erlang SSL application implements the SSL/TLS protocol
for the currently supported versions, see the
<seealso marker="ssl">ssl(3)</seealso> manual page.
</p>
- <p>By default <c>ssl</c> is run over the TCP/IP protocol even
+ <p>By default SSL/TLS is run over the TCP/IP protocol even
though you can plug in any other reliable transport protocol
with the same Application Programming Interface (API) as the
- <c>gen_tcp</c> module in <c>kernel</c>.</p>
+ <c>gen_tcp</c> module in Kernel.</p>
<p>If a client and a server wants to use an upgrade mechanism, such as
defined by RFC 2817, to upgrade a regular TCP/IP connection to an SSL
- connection, this is supported by the Erlang <c>ssl</c> API. This can be
+ connection, this is supported by the Erlang SSL application API. This can be
useful for, for example, supporting HTTP and HTTPS on the same port and
implementing virtual hosting.
</p>
@@ -143,7 +143,7 @@
connections. Sessions are used to avoid the expensive negotiation
of new security parameters for each connection."</p>
- <p>Session data is by default kept by the <c>ssl</c> application in a
+ <p>Session data is by default kept by the SSL application in a
memory storage, hence session data is lost at application
restart or takeover. Users can define their own callback module
to handle session data storage if persistent data storage is
diff --git a/lib/ssl/doc/src/ssl_session_cache_api.xml b/lib/ssl/doc/src/ssl_session_cache_api.xml
index 9cd16c5f58..c89d3874a1 100644
--- a/lib/ssl/doc/src/ssl_session_cache_api.xml
+++ b/lib/ssl/doc/src/ssl_session_cache_api.xml
@@ -108,8 +108,8 @@
API functions. Is called by the cache handling processes
<c>init</c> function, hence putting the same requirements on it
as a normal process <c>init</c> function. This function is
- called twice when starting the <c>ssl</c> application, once with
- the role client and once with the role server, as the <c>ssl</c>
+ called twice when starting the SSL application, once with
+ the role client and once with the role server, as the SSL
application must be prepared to take on both roles.
</p>
</desc>
diff --git a/lib/ssl/doc/src/using_ssl.xml b/lib/ssl/doc/src/using_ssl.xml
index 01b7970fb6..dbbc1aa9d3 100644
--- a/lib/ssl/doc/src/using_ssl.xml
+++ b/lib/ssl/doc/src/using_ssl.xml
@@ -32,10 +32,10 @@
<file>using_ssl.xml</file>
</header>
<p>To see relevant version information for ssl, call
- <seealso marker="ssl:versions-0"><c>ssl:versions/0</c></seealso>
+ <seealso marker="ssl:ssl#versions-0"><c>ssl:versions/0</c></seealso>
.</p>
- <p>To see all supported cipher suites, call <seealso marker="ssl:cipher_suites-1"><c>ssl:cipher_suites(all)</c> </seealso>.
+ <p>To see all supported cipher suites, call <seealso marker="ssl:ssl#cipher_suites-1"><c>ssl:cipher_suites(all)</c> </seealso>.
The available cipher suites for a connection depend on your certificate.
Specific cipher suites that you want your connection to use can also be
specified. Default is to use the strongest available.</p>