ssl

模块

SSL

模块摘要

安全套接字层的接口函数

描述

该模块包含SSL / TLS协议的接口功能。有关支持的标准的详细信息，请参阅ssl(6)。

数据类型

SSL的函数中使用了以下数据类型：

boolean() =

true | false

option() =

socketoption() | ssl_option() | transport_option()

socketoption() =

proplists:property()

默认套接字选项是[{mode,list},{packet, 0},{header, 0},{active, true}]。

有关有效选项，请参见inet(3)和gen_tcp(3)内核中的手册页。

ssl_option() =

{verify, verify_type()}

| {verify_fun, {fun(), term()}}

| {fail_if_no_peer_cert, boolean()}

| {depth, integer()}

| {cert, public_key:der_encoded()}

| {certfile, path()}

| {key, {'RSAPrivateKey'| 'DSAPrivateKey' | 'ECPrivateKey' | 'PrivateKeyInfo', public_key:der_encoded()}}

| {keyfile, path()}

| {password, string()}

| {cacerts, [public_key:der_encoded()]}

| {cacertfile, path()}

| {dh, public_key:der_encoded()}

| {dhfile, path()}

| {ciphers, ciphers()}

| {user_lookup_fun, {fun(), term()}}, {psk_identity, string()}, {srp_identity, {string(), string()}}

| {reuse_sessions, boolean()}

| {reuse_session, fun()} {next_protocols_advertised, [binary()]}

| {client_preferred_next_protocols, {client | server, [binary()]} | {client | server, [binary()], binary()}}

| {log_alert, boolean()}

| {server_name_indication, hostname() | disable}

| {sni_hosts, [{hostname(), [ssl_option()]}]}

| {sni_fun, SNIfun::fun()}

transport_option() =

{cb_info, {CallbackModule::atom(), DataTag::atom(), ClosedTag::atom(), ErrTag:atom()}}

默认为{gen_tcp, tcp, tcp_closed, tcp_error}。可以用来定制传输层。回调模块必须实现可靠的传输协议，表现为gen_tcp，与具有对应于函数inet:setopts/2，inet:getopts/2，inet:peername/1，inet:sockname/1，和inet:port/1。回调gen_tcp被专门处理并inet直接调用。

CallbackModule =

atom()

DataTag =

atom()

用于套接字数据消息。

ClosedTag =

atom()

用于套接字关闭消息。

verify_type() =

verify_none | verify_peer

path() =

string()

表示文件路径。

public_key:der_encoded() =

binary()

ASN.1编码实体为Erlang二进制。

host() =

hostname() | ipaddress()

hostname() =

string() - DNS hostname

ip_address() =

{N1,N2,N3,N4} % IPv4 | {K1,K2,K3,K4,K5,K6,K7,K8} % IPv6

sslsocket() =

opaque()

protocol() =

sslv3 | tlsv1 | 'tlsv1.1' | 'tlsv1.2'

ciphers() =

= [ciphersuite()] | string()

根据旧API。

ciphersuite() =

{key_exchange(), cipher(), MAC::hash()} | {key_exchange(), cipher(), MAC::hash(), PRF::hash()}

key_exchange()=

rsa | dhe_dss | dhe_rsa | dh_anon | psk | dhe_psk | rsa_psk | srp_anon | srp_dss | srp_rsa | ecdh_anon | ecdh_ecdsa | ecdhe_ecdsa | ecdh_rsa | ecdhe_rsa

cipher() =

rc4_128 | des_cbc | '3des_ede_cbc' | aes_128_cbc | aes_256_cbc | aes_128_gcm | aes_256_gcm | chacha20_poly1305

hash() =

md5 | sha | sha224 | sha256 | sha348 | sha512

prf_random() =

client_random | server_random

srp_param_type() =

srp_1024 | srp_1536 | srp_2048 | srp_3072 | srp_4096 | srp_6144 | srp_8192

SNIfun::fun()

= fun(ServerName :: string()) -> [ssl_option()]

named_curve() =

sect571r1 | sect571k1 | secp521r1 | brainpoolP512r1 | sect409k1 | sect409r1 | brainpoolP384r1 | secp384r1 | sect283k1 | sect283r1 | brainpoolP256r1 | secp256k1 | secp256r1 | sect239k1 | sect233k1 | sect233r1 | secp224k1 | secp224r1 | sect193r1 | sect193r2 | secp192k1 | secp192r1 | sect163k1 | sect163r1 | sect163r2 | secp160k1 | secp160r1 | secp160r2

SSL选项描述-服务器和客户端常见

以下选项在客户机和服务器中具有相同的含义：

{protocol, tls | dtls}

选择TLS或DTLS协议作为传输层安全性。默认为tls在OTP 20中引入的DTLS支持在本版本中被认为是实验性的。对于UDP以外的其他传输，还不支持dtl。

{cert, public_key:der_encoded()}

DER编码的用户证书。如果提供此选项，它将覆盖选项certfile。

{certfile, path()}

包含用户证书的文件的路径。

{key, {'RSAPrivateKey'| 'DSAPrivateKey' | 'ECPrivateKey' |'PrivateKeyInfo', public_key:der_encoded()}}

DER编码的用户私钥。如果提供此选项，它将覆盖选项keyfile。

{keyfile, path()}

包含用户专用PEM编码密钥的文件的路径。由于PEM文件可以包含多个条目，因此该选项默认为与选项所给定的文件相同certfile。

{password, string()}

包含用户密码的字符串。仅在私钥文件受密码保护时才使用。

{ciphers, ciphers()}

支持的密码套件。该功能cipher_suites/0可用于查找默认支持的所有密码。cipher_suites(all)可以调用来查找所有可用的密码套件。如果此选项明确启用，预共享密钥（RFC 4279和RFC 5487），安全远程密码（RFC 5054），RC4密码套件和匿名密码套件才可用; 它们也被同伴支持/启用。匿名密码套件仅用于测试目的，并且在安全性问题时不会使用。

{eccs, [named_curve()]}

允许指定命名曲线的优先顺序，并在使用支持它们的密码套件时限制它们的使用。

{secure_renegotiate, boolean()}

指定是否拒绝不合格的重新协商尝试RFC 5746。默认情况下secure_renegotiate设置为false，即尽可能使用安全重新协商，但如果对等不支持，则会回退到不安全的重新协商RFC 5746。

{depth, integer()}

可以在有效证书路径中跟随对等证书的非自发中间证书的最大数量。因此，如果深度为0，则PEER必须由可信任的ROOT-CA直接签名; 如果1的路径可以是PEER，CA，ROOT-CA; 如果2的路径可以是PEER，CA，CA，ROOT-CA等。默认值是1。

{verify_fun, {Verifyfun :: fun(), InitialUserState :: term()}}

验证函数的定义如下：

fun(OtpCert :: #'OTPCertificate'{}, Event :: {bad_cert, Reason :: atom() | {revoked,
atom()}} |
	     {extension, #'Extension'{}}, InitialUserState :: term()) ->
	{valid, UserState :: term()} | {valid_peer, UserState :: term()} |
	{fail, Reason :: term()} | {unknown, UserState :: term()}.
	

当遇到错误或SSL应用程序未知的扩展时，在X509路径验证期间调用验证函数。当通过路径验证将证书视为有效时，也会调用它以允许访问用户应用程序路径中的每个证书。它通过使用valid_peer或valid作为验证函数的第二个参数区分对等证书和CA证书。请参阅public_key User's Guide用于定义#'OTPCertificate'{}和#'Extension'{}。

• 如果验证回调函数返回{fail, Reason}，则立即停止验证过程，向对等方发送警报，并终止TLS / SSL握手。

• 如果验证回调函数返回{valid, UserState}，则验证过程继续。

• 如果验证回调始终返回{valid, UserState}，TLS/SSL握手不会终止有关验证失败和建立连接的操作。

• 如果使用用户应用程序未知的扩展名调用，则返回值。{unknown, UserState}就是被利用。

请注意，如果unknown标记为关键的扩展的函数返回，则验证将失败。

默认选项verify_fun在verify_peer mode*

{fun(_,{bad_cert, _} = Reason, _) ->
	 {fail, Reason};
    (_,{extension, _}, UserState) ->
	 {unknown, UserState};
    (_, valid, UserState) ->
	 {valid, UserState};
    (_, valid_peer, UserState) ->
         {valid, UserState}
 end, []}
      

默认选项verify_fun在模verify_none*

{fun(_,{bad_cert, _}, UserState) ->
	 {valid, UserState};
    (_,{extension, #'Extension'{critical = true}}, UserState) ->
	 {valid, UserState};
    (_,{extension, _}, UserState) ->
	 {unknown, UserState};
    (_, valid, UserState) ->
	 {valid, UserState};
    (_, valid_peer, UserState) ->
         {valid, UserState}
 end, []}
      

可能的路径验证错误在表单{bad_cert, Reason}上给出，其中Reason：

unknown_ca

在可信存储区中找不到可信的CA. 可信CA通常是所谓的ROOT CA，它是一个自签名证书。可以通过使用选项为中间CA声明信任（可信锚点不必根据X-509自签名）partial_chain。

selfsigned_peer

该链只包含一个自签名证书。

PKIX X-509-path validation error

出于可能的原因，请参见public_key:pkix_path_validation/3

{crl_check, boolean() | peer | best_effort }

在证书链(public_key:pkix_crls_validate/3)路径验证期间对所有证书执行CRL（证书吊销列表）验证(public_key:pkix_path_validation/3)。默认为false。

peer仅对对等证书执行检查。best_effort如果无法确定证书吊销状态，则该状态将被接受为有效。

为连接指定的CA证书将用于构造验证CRLS的证书链。

CRLS将从本地或外部缓存中获取。见ssl_crl_cache_api(3)...

{crl_cache, {Module :: atom(), {DbHandle :: internal | term(), Args :: list()}}}

指定如何执行证书吊销列表的查找和缓存。Module默认为ssl_crl_cache带着DbHandle存在internal还有一个空的论证列表。

有两种实现：

ssl_crl_cache

该模块维护CRLS的缓存。可以使用以下函数将crls添加到缓存中。ssl_crl_cache:insert/1，如果指定了以下参数，则可以通过HTTP自动获取：

{http, timeout()}

中指定为http URI的CRL的获取。X509 certificate extensions需要OTP INTS应用程序。

ssl_crl_hash_dir

该模块使用一个目录，其中CRLS存储在由颁发者名称的散列命名的文件中。

文件名由八个十六进制数字和后面的十六进制数字组成。.rN，在哪里N是整数，例如。1a2b3c4d.r0.关于CRL的第一版，N从零开始，对于每一个新版本，N增加一倍。OpenSSL实用程序c_rehash根据此模式创建符号链接。

对于给定的散列值，此模块将查找所有连续的哈希值。.r*从零开始的文件，这些文件加在一起构成撤销列表。CRL文件nextUpdate字段是过去的，或者是由其他CA发出的，而这些CA恰好具有相同的名称哈希，但这些字段都被排除在外。

需要进行以下论证：

{dir, string()}

指定可在其中找到CRL的目录。

max_handshake_size

整数（24位无符号）。用于限制有效TLS握手数据包的大小以避免DoS攻击。默认为256 * 1024。

{partial_chain, fun(Chain::[DerCert]) -> {trusted_ca, DerCert} | unknown_ca }

将链中的中间CA声称为可信。然后public_key:pkix_path_validation/3，TLS 将选定的CA作为可信锚点和链的其余部分执行。

{versions, [protocol()]}

TLS协议版本由已启动的客户端和服务器支持。该选项将覆盖应用程序环境选项protocol_version。如果环境选项未设置，则默认为SSL应用程序支持的所有版本，SSL-3.0除外。也可以看看ssl(6).

{hibernate_after, integer()|undefined}

当指定一个整数值时，ssl_connection在指定的毫秒数不活动之后进入休眠状态，从而减少内存占用量。当undefined指定时（这是默认设置），该进程永远不会进入休眠状态。

{user_lookup_fun, {Lookupfun :: fun(), UserState :: term()}}

查找函数的定义如下：

fun(psk, PSKIdentity ::string(), UserState :: term()) ->
	{ok, SharedSecret :: binary()} | error;
fun(srp, Username :: string(), UserState :: term()) ->
	{ok, {SRPParams :: srp_param_type(), Salt :: binary(), DerivedKey :: binary()}} | error.
	

对于预共享密钥（PSK）密码套件，查找乐趣由客户端和服务器调用以确定共享密钥。当被客户端调用时，PSKIdentity被设置为由服务器提供的提示或未定义的。当被服务器调用时，PSKIdentity客户端提供的是身份。

对于安全远程密码（SRP），只有服务器才能使用它来获取用于生成会话密钥的参数。DerivedKey是根据和派生出来的： RFC 2945 RFC 5054crypto:sha([Salt, crypto:sha([Username, <<$:>>, Password])])

{padding_check, boolean()}

仅影响TLS-1.0连接。如果设置为false，则禁用块密码填充检查以便能够与传统软件进行互操作。

警告

使用{padding_check, boolean()}使得TLS容易受到贵宾犬的攻击。

{beast_mitigation, one_n_minus_one | zero_n | disabled}

仅影响ssl-3.0和tls-1.0连接.。用于改变猛兽缓解策略，使其与遗留软件进行互操作。默认为one_n_minus_one...

one_n_minus_one - 执行1 / n-1 BEAST缓解。

zero_n - 执行0 / n BEAST缓解。

disabled - 禁用BEAST缓解。

警告

使用{beast_mitigation, disabled}会使SSL或TLS容易受到BEAST攻击。

SSL选项描述-客户端

以下选项是特定于客户端的，或者在客户机中的含义与服务器中略有不同：

{verify, verify_type()}

在模式verify_none，默认行为是允许所有x509路径验证错误。另请参见选项verify_fun。

{reuse_sessions, boolean()}

指定客户端是否在可能时尝试重用会话。

{cacerts, [public_key:der_encoded()]}

编码的可信证书。如果提供此选项，则它将重写选项。cacertfile...

{cacertfile, path()}

包含PEM编码的CA证书的文件的路径。CA证书在服务器身份验证和构建客户端证书链时使用。

{alpn_advertised_protocols, [binary()]}

客户端支持的用于应用程序层协议协商%28ALPN%29的协议列表。如果服务器支持ALPN，那么它将从这个列表中选择一个协议；否则，它将失败，其连接将为“no”。[医]应用[医]“警报”。不支持ALPN的服务器将忽略此值。

协议列表不能包含空二进制文件。

可以使用negotiated_protocol/1功能。

{client_preferred_next_protocols, {Precedence :: server | client, ClientPrefs :: [binary()]}}

{client_preferred_next_protocols, {Precedence :: server | client, ClientPrefs :: [binary()], Default :: binary()}}

指示客户端要尝试执行下一个协议协商。

如果优先级是服务器，则协商协议是第一个显示在服务器公告列表上的协议，该列表也显示在客户端首选项列表上。

如果优先级是客户端，则协商协议是第一个显示在客户端首选项列表上的协议，该协议也显示在服务器公告列表上。

如果客户端不支持任何服务器通告的协议或服务器不通告任何协议，则客户端将回退到其列表中的第一个协议或默认协议（如果提供了默认协议）。如果服务器不支持Next Protocol Negotiation，则在没有提供默认协议的情况下连接终止。

{psk_identity, string()}

指定客户端向服务器显示的标识。匹配的秘密是通过调用user_lookup_fun...

{srp_identity, {Username :: string(), Password :: string()}

指定用于对服务器进行身份验证的用户名和密码。

{server_name_indication, HostName :: hostname()}

指定要在TLS服务器名称指示扩展中使用的主机名。当将TCP套接字升级到TLS套接字或主机名不能从主机参数派生为ssl:connect/3还将导致客户端预先形成对等证书的主机名验证。public_key:pkix_verify_hostname(PeerCert, [{dns_id, HostName}])

在x509路径验证期间。如果检查失败，则会将错误{bad_cert，hostname_check_failiure}传播到路径验证函数verify_fun{server_name_indication, disable}

在不升级的情况下启动TLS连接时，如果可能，可以从Host参数派生到Server Name Indication扩展ssl:connect/3。该选项可用于禁用该行为。

注

请注意，这还禁用对等证书的默认主机名验证检查。

{fallback, boolean()}

发送特殊的密码套件TLS_FALLBACK_SCSV以避免不需要的TLS版本降级。默认为false

警告

注意，此选项在正常的TLS使用中不需要，也不应用于实现新的客户端。但是以下列方式重试连接的遗留客户端

ssl:connect(Host, Port, [...{versions, ['tlsv2', 'tlsv1.1', 'tlsv1', 'sslv3']}])

ssl:connect(Host, Port, [...{versions, [tlsv1.1', 'tlsv1', 'sslv3']}, {fallback, true}])

ssl:connect(Host, Port, [...{versions, ['tlsv1', 'sslv3']}, {fallback, true}])

ssl:connect(Host, Port, [...{versions, ['sslv3']}, {fallback, true}])

可能会使用它来避免不需要的TLS版本降级。请注意，服务器还必须支持TLS_FALLBACK_SCSV以防止工作。

{signature_algs, [{hash(), ecdsa | rsa | dsa}]}

除了用于密钥交换，有效载荷加密，消息认证和伪随机计算的密码套件协商的算法之外，TLS签名算法扩展Section 7.4.1.4.1 in RFC 5246可以用于TLS 1.2，以协商在TLS握手期间使用哪种签名算法。如果不支持低于1.2的TLS版本，则客户端将发送TLS签名算法扩展，其中包含此选项指定的算法。默认为

[
%% SHA2
{sha512, ecdsa},
{sha512, rsa},
{sha384, ecdsa},
{sha384, rsa},
{sha256, ecdsa},
{sha256, rsa},
{sha224, ecdsa},
{sha224, rsa},
%% SHA
{sha, ecdsa},
{sha, rsa},
{sha, dsa},
]

算法应按优先顺序排列。选定的签名算法可以限制可以选择的散列函数。在ssl-8.0中删除{md5，rsa}的默认支持

SSL选项说明-服务器端

以下选项是特定于服务器的，或者在服务器中与客户机中的含义略有不同：

{cacerts, [public_key:der_encoded()]}

DER编码的可信证书。如果提供此选项，它将覆盖选项cacertfile。

{cacertfile, path()}

包含PEM编码的CA证书的文件的路径。CA证书用于构建服务器证书链和客户端身份验证。CA还用于请求证书时传递给客户端的可接受客户端CA列表。如果不需要验证客户端，如果服务器证书没有中间CA，则可以省略。

{dh, public_key:der_encoded()}

DER编码的Diffie-Hellman参数。如果指定，它将覆盖选项dhfile。

{dhfile, path()}

如果协商使用Diffie Hellman密钥交换的密码套件，则服务器将使用包含PEM编码的Diffie Hellman参数的文件的路径。如果未指定，则使用默认参数。

{verify, verify_type()}

服务器仅在模式下执行x509路径验证verify_peer，因为它随后将证书请求发送到客户端（如果验证选项是不发送此消息verify_none）。然后你也可以指定选项fail_if_no_peer_cert。

{fail_if_no_peer_cert, boolean()}

{verify, verify_peer}通过SSL服务器一起使用。如果设置为true，则如果客户端没有要发送的证书，则服务器将失败，即发送空证书。如果设置为false，则仅在客户端发送无效证书时才会失败（空证书被视为有效）。默认为false。

{reuse_sessions, boolean()}

指定服务器是否同意在客户端请求时重用会话。另请参见选项reuse_session。

{reuse_session, fun(SuggestedSessionId, PeerCert, Compression, CipherSuite) -> boolean()}

使SSL服务器有一个本地策略来决定会话是否被重用。 只有在reuse_sessions设置为true时才有意义。 SuggestedSessionId是二进制（），PeerCert是DER编码证书，Compression是枚举整数，CipherSuite是ciphersuite（）类型。

{alpn_preferred_protocols, [binary()]}

表示服务器将尝试执行应用层协议协商（ALPN）。

协议列表按优先顺序排列。协商的协议将是列表中的第一个与客户通告的协议之一匹配。如果没有协议匹配，服务器将通过“no_application_protocol”警报来断开连接。

可以使用negotiated_protocol/1功能。

{next_protocols_advertised, Protocols :: [binary()]}

如果客户端表示支持下一个协议扩展，则向客户端发送的协议列表。客户端可以选择不在此列表中的协议。协议列表不能包含空二进制文件。如果服务器协商下一个协议，则可以使用negotiated_next_protocol/1方法。

{psk_identity, string()}

指定服务器向客户端显示的服务器标识提示。

{log_alert, boolean()}

如果设置为false，则不显示错误报告。

{honor_cipher_order, boolean()}

如果设置为true，则使用服务器首选项进行密码选择。如果设置为false（默认），请使用客户端首选项。

{sni_hosts, [{hostname(), [ssl_option()]}]}

如果服务器从客户端收到与sni_hosts选项中列出的主机相匹配的SNI（服务器名称指示），则该主机的特定选项将覆盖先前指定的选项。该选项sni_fun，并且sni_hosts是互斥的。

{sni_fun, SNIfun::fun()}

如果服务器从客户端收到SNI（服务器名称指示），则将调用给定的功能以检索[ssl_option()]指定的服务器。这些选项将合并到预定义的[ssl_option()]。该函数应该被定义为：fun(ServerName :: string()) -> [ssl_option()]并且可以被指定为一个有趣的或者被命名fun module:function/1的选项sni_fun，并且sni_hosts是互斥的。

{client_renegotiation, boolean()}在支持客户端启动的重新协商的协议中，服务器的这种操作的资源成本高于客户端。这可以充当拒绝服务攻击的载体。SSL应用程序已采取措施来对付此类尝试，但可通过将此选项设置为严格禁用客户端启动的重新协商false。默认值是true。请注意，禁用重新协商可能会导致长时间连接变得不可用，因为对底层密码套件可以加密的消息数量有限制。{honor_cipher_order, boolean()}如果为true，请使用服务器的首选项进行密码选择。如果为false（默认），请使用客户的偏好。{honor_ecc_order, boolean()}如果为true，请使用服务器的首选项来选择ECC曲线。如果为false（默认），请使用客户的偏好。{signature_algs, [{hash(), ecdsa | rsa | dsa}]}

该选项指定的算法将是TLS-1.2中引入的签名算法协商中服务器接受的算法。如果客户端证书被请求，算法也将被提供给客户端。欲了解更多详情，请参阅corresponding client option。

{v2_hello_compatible, boolean()}如果为true，则服务器接受以SSL-2.0格式发送hello消息的客户端，但提供受支持的SSL / TLS版本。默认为false，即服务器不会与提供SSL-2.0的客户端交互操作。

一般

当SSL套接字处于活动模式时（默认），来自套接字的数据以消息的形式传递给套接字的所有者：

• {ssl, Socket, Data}

• {ssl_closed, Socket}

• {ssl_error, Socket, Reason}

一个Timeout参数指定以毫秒为单位超时。参数的默认值Timeout是infinity。

输出

cipher_suites() ->cipher_suites(Type) -> ciphers()

类型

返回支持的密码套件列表。cipher_suites()相当于提供cipher_suites(erlang).Type openssl以向后兼容使用OpenSSL的旧SSL。cipher_suites(all)返回所有可用的密码套件。除非用户明确配置，否则不会使用密码套件cipher_suites(erlang)但包含在内cipher_suites(all)。

eccs() ->eccs(protocol()) -> [named_curve()]

返回支持的ECC列表。eccs()相当于eccs(Protocol)使用所有支持的协议进行调用，然后对输出进行重复数据删除。

clear_pem_cache() -> ok

缓存ssl API函数使用的PEM文件。定期检查高速缓存以查看是否应该使任何高速缓存条目无效，但是此函数提供了一种无条件地清除整个高速缓存的方法。

connect(Socket, SslOptions) ->connect(Socket, SslOptions, Timeout) -> {ok, SslSocket} | {error, Reason}

类型

将gen_tcp连接的套接字升级到SSL套接字，即执行客户端ssl握手。

connect(Host, Port, Options) ->connect(Host, Port, Options, Timeout) -> {ok, SslSocket} | {error, Reason}

类型

打开SSL连接Host，Port。

close(SslSocket) -> ok | {error, Reason}

类型

关闭SSL连接。

close(SslSocket, How) -> ok | {ok, port()} | {error, Reason}

类型

关闭或降级SSL连接。在后一种情况下，传输连接将NewController在接收到来自对端的TLS关闭警报后切换到流程。返回的传输套接字将设置以下选项：[{active, false}, {packet, 0}, {mode, binary}]

controlling_process(SslSocket, NewOwner) -> ok | {error, Reason}

类型

为SSL套接字分配一个新的控制进程。控制进程是SSL套接字的所有者，接收来自套接字的所有消息。

connection_information(SslSocket) -> {ok, Result} | {error, Reason}

类型

上面没有指定的有意义的原子是SSL选项名。

返回关于连接的最相关信息，未定义的ssl选项将被过滤掉。请注意，只有connection_information / 2显式请求才会返回影响连接安全性的值。

connection_information(SslSocket, Items) -> {ok, Result} | {error, Reason}

类型

请注意，client_random，server_random和master_secret是影响连接安全性的值。有意义的原子，未在上面指定，是ssl选项名称。

如果已定义连接，则返回所请求的有关连接的信息项。

注

如果只请求未定义的选项，则结果列表可以为空。

format_error(Reason) -> string()

类型

以可打印字符串的形式显示SSL函数返回的错误。

getopts(Socket, OptionNames) -> {ok, [socketoption()]} | {error, Reason}

类型

获取指定套接字选项的值。

getstat(Socket) -> {ok, OptionValues} | {error, inet:posix()}getstat(Socket, OptionNames) -> {ok, OptionValues} | {error, inet:posix()}

类型

获取基础TCP套接字的一个或多个统计选项。

有关统计选项的描述，请参阅inet：getstat / 2。

listen(Port, Options) -> {ok, ListenSocket} | {error, Reason}

类型

创建SSL侦听套接字。

negotiated_protocol(Socket) -> {ok, Protocol} | {error, protocol_not_negotiated}

类型

返回通过ALPN或NPN扩展协商的协议。

peercert(Socket) -> {ok, Cert} | {error, Reason}

类型

对等证书作为DER编码二进制返回。证书可以用解码public_key:pkix_decode_cert/2。

peername(Socket) -> {ok, {Address, Port}} | {error, Reason}

类型

返回对等方的地址和端口号。

prf(Socket, Secret, Label, Seed, WantedLength) -> {ok, binary()} | {error, reason()}

类型

使用TLS会话的伪随机函数（PRF）生成额外的密钥材料。 它要么接收用户生成的Secret和Seed的值，要么使用原子指示它使用会话安全参数中的特定值。

只能与TLS连接一起使用; {error, undefined}返回SSLv3连接。

recv(Socket, Length) ->recv(Socket, Length, Timeout) -> {ok, Data} | {error, Reason}

类型

从被动模式的套接字接收数据包。关闭的套接字由返回值指示{error, closed}。

Length仅当套接字处于模式raw并且表示要读取的字节数时，参数才有意义。如果Length= 0，则返回所有可用字节。如果Length> 0，Length则返回确切的字节或错误; Length当套接字从另一端关闭时可能丢弃少于数据字节的数据。

可选参数Timeout指定超时（以毫秒为单位）。默认值是infinity。

renegotiate(Socket) -> ok | {error, Reason}

类型

启动新的握手。值得注意的返回值是{error, renegotiation_rejected}指示对等方拒绝接受重新协商，但是使用先前协商的会话，连接仍处于活动状态。

send(Socket, Data) -> ok | {error, Reason}

类型

写入Data到Socket。

值得注意的返回值{error, closed}表示套接字已关闭。

setopts(Socket, Options) -> ok | {error, Reason}

类型

根据Options套接字设置选项Socket。

shutdown(Socket, How) -> ok | {error, Reason}

类型

立即关闭一个或两个方向的插座。

How == write 意味着关闭写入套接字，读取它仍然是可能的。

为了能够处理对端在写入端执行关闭操作，选项{exit_on_close, false}很有用。

ssl_accept(Socket) ->ssl_accept(Socket, Timeout) -> ok | {error, Reason}

类型

执行SSL/TLS服务器端握手。

Socket返回的套接字。ssl:transport_accept/[1,2]

ssl_accept(Socket, SslOptions) ->ssl_accept(Socket, SslOptions, Timeout) -> {ok, Socket} | ok | {error, Reason}

类型

如果Socket是socket()*升级gen_tcp，或者等效于SSL套接字，即执行SSL/TLS服务器端握手并返回SSL套接字。

警告

侦听套接字将处于模式。{active, false}在告诉客户端服务器已准备好通过调用此函数进行升级之前，否则升级会成功或不会成功，这取决于时间。

如果Socket是sslsocket()：：提供额外的SSL/TLS选项给ssl:listen/2然后执行SSL/TLS握手。

sockname(Socket) -> {ok, {Address, Port}} | {error, Reason}

类型

返回套接字的本地地址和端口号Socket。

start() ->start(Type) -> ok | {error, Reason}

类型

启动SSL应用程序。默认类型是temporary。

stop() -> ok

停止SSL应用程序。

transport_accept(ListenSocket) ->transport_accept(ListenSocket, Timeout) -> {ok, NewSocket} | {error, Reason}

类型

在侦听套接字上接受传入的连接请求。ListenSocket必须是从中返回的套接字ssl:listen/2。返回的套接字将被传递到ssl:ssl_accept[2,3]完成握手，即建立SSL / TLS连接。

警告

返回的套接字只能用于ssl:ssl_accept[2,3]。在该呼叫之前不能发送或接收流量。

接受的套接字继承了在ssl：listen / 2中为ListenSocket设置的选项。

Timeout的默认值是无穷大。 如果指定了超时，并且在给定时间内没有接受任何连接，则返回{error，timeout}。

versions() -> [versions_info()]

类型

返回与SSL应用程序相关的版本信息。

app_vsn SSL应用程序的应用程序版本。 支持默认支持的TLS / SSL版本。 由connect / [2,3,4]上的版本选项覆盖，listen / 2和ssl_accept / [1,2,3]。 有关协商的TLS / SSL版本，请参阅ssl：connection_information / 1。 可用SSL应用程序支持的所有TLS / SSL版本。 TLS 1.2需要Crypto应用程序的充分支持。

另见

inet(3)和gen_tcp(3)

	ssl
	1.简介（ssl） | 1. Introduction (ssl)	详细
	2. TLS及其前身SSL | 2. TLS and its Predecessor, SSL	详细
	3.使用SSL API | 3. Using SSL API	详细
	4.使用SSL进行Erlang分发 | 4. Using SSL for Erlang Distribution	详细
	ssl	详细
	ssl_crl_cache	详细
	ssl_crl_cache_api	详细
	ssl_session_cache_api	详细