diff options
Diffstat (limited to 'lib/public_key/doc/src/public_key.xml')
| -rw-r--r-- | lib/public_key/doc/src/public_key.xml | 150 |
1 files changed, 134 insertions, 16 deletions
diff --git a/lib/public_key/doc/src/public_key.xml b/lib/public_key/doc/src/public_key.xml index a34c9de76b..5230cef496 100644 --- a/lib/public_key/doc/src/public_key.xml +++ b/lib/public_key/doc/src/public_key.xml @@ -119,6 +119,10 @@ <tag><c>ec_private_key() =</c></tag> <item><p><c>#'ECPrivateKey'{}</c></p></item> + <tag><c>key_params() =</c></tag> + <item><p> #'DHParameter'{} | {namedCurve, oid()} | #'ECParameters'{} + | {rsa, Size::integer(), PubExp::integer()} </p></item> + <tag><c>public_crypt_options() =</c></tag> <item><p><c>[{rsa_pad, rsa_padding()}]</c></p></item> @@ -129,18 +133,31 @@ <p><c>| 'rsa_no_padding'</c></p> </item> + <tag><c>public_sign_options() =</c></tag> + <item><p><c>[{rsa_pad, rsa_sign_padding()} | {rsa_pss_saltlen, integer()}]</c></p></item> + + <tag><c>rsa_sign_padding() =</c></tag> + <item> + <p><c>'rsa_pkcs1_padding'</c></p> + <p><c>| 'rsa_pkcs1_pss_padding'</c></p> + </item> + <tag><c>digest_type() = </c></tag> <item><p>Union of <c>rsa_digest_type()</c>, <c>dss_digest_type()</c>, and <c>ecdsa_digest_type()</c>.</p></item> <tag><c>rsa_digest_type() = </c></tag> - <item><p><c>'md5' | 'sha' | 'sha224' | 'sha256' | 'sha384' | 'sha512'</c></p></item> + <item><p><c>'md5' | 'ripemd160' | 'sha' | 'sha224' | 'sha256' | 'sha384' | 'sha512'</c></p></item> <tag><c>dss_digest_type() = </c></tag> - <item><p><c>'sha'</c></p></item> + <item><p><c>'sha' | 'sha224' | 'sha256' | 'sha384' | 'sha512'</c></p> + <p>Note that the actual supported dss_digest_type depends on the underlying crypto library. + In OpenSSL version >= 1.0.1 the listed digest are supported, while in 1.0.0 only + sha, sha224 and sha256 are supported. In version 0.9.8 only sha is supported.</p> + </item> <tag><c>ecdsa_digest_type() = </c></tag> - <item><p><c>'sha'| 'sha224' | 'sha256' | 'sha384' | 'sha512'</c></p></item> + <item><p><c>'sha' | 'sha224' | 'sha256' | 'sha384' | 'sha512'</c></p></item> <tag><c>crl_reason() = </c></tag> <item> @@ -331,13 +348,16 @@ </func> <func> - <name>generate_key(Params) -> {Public::binary(), Private::binary()} | #'ECPrivateKey'{} </name> + <name>generate_key(Params) -> {Public::binary(), Private::binary()} | #'ECPrivateKey'{} | #'RSAPrivateKey'{}</name> <fsummary>Generates a new keypair.</fsummary> <type> - <v>Params = #'DHParameter'{} | {namedCurve, oid()} | #'ECParameters'{}</v> + <v>Params = key_params()</v> </type> <desc> - <p>Generates a new keypair.</p> + <p>Generates a new keypair. Note that except for Diffie-Hellman + the public key is included in the private key structure. See also + <seealso marker="crypto:crypto#generate_key/2">crypto:generate_key/2</seealso> + </p> </desc> </func> @@ -617,8 +637,8 @@ fun(OtpCert :: #'OTPCertificate'{}, <v>OTPCertificate = #'OTPCertificate'{}</v> <v>DPAndCRLs = [{DP::#'DistributionPoint'{}, {DerCRL::der_encoded(), CRL::#'CertificateList'{}}}] </v> <v>Options = proplists:proplist()</v> - <v>CRLStatus() = valid | {bad_cert, revocation_status_undetermined} | - {bad_cert, {revoked, crl_reason()}}</v> + <v>CRLStatus() = valid | {bad_cert, revocation_status_undetermined} | {bad_cert, {revocation_status_undetermined, + {bad_crls, Details::term()}}} | {bad_cert, {revoked, crl_reason()}}</v> </type> <desc> <p>Performs CRL validation. It is intended to be called from @@ -646,7 +666,7 @@ fun(OtpCert :: #'OTPCertificate'{}, <tag>{issuer_fun, fun()}</tag> <item> <p>The fun has the following type specification:</p> - + <code> fun(#'DistributionPoint'{}, #'CertificateList'{}, {rdnSequence,[#'AttributeTypeAndValue'{}]}, term()) -> @@ -656,7 +676,15 @@ fun(#'DistributionPoint'{}, #'CertificateList'{}, that has signed the CRL. </p> <code> fun(DP, CRL, Issuer, UserState) -> {ok, RootCert, CertChain}</code> - </item> + </item> + + <tag>{undetermined_details, boolean()}</tag> + <item> + <p>Defaults to false. When revocation status can not be + determined, and this option is set to true, details of why no + CRLs where accepted are included in the return value.</p> + </item> + </taglist> </desc> </func> @@ -744,6 +772,85 @@ fun(#'DistributionPoint'{}, #'CertificateList'{}, </desc> </func> + <func> + <name>pkix_test_data(Options) -> Config </name> + <fsummary>Creates certificate test data.</fsummary> + <type> + <v>Options = #{chain_type() := chain_opts()} </v> + <d>Options for ROOT, Intermediate and Peer certs</d> + + <v>chain_type() = server_chain | client_chain </v> + + <v>chain_opts() = #{chain_end() := [cert_opt()], + intermediates => [[cert_opt()]]}</v> + <d>A valid chain must have at least a ROOT and a peer cert</d> + + <v>chain_end() = root | peer </v> + + <v>cert_opt() = {Key, Value}</v> + <d>For available options see <seealso marker="#cert_opt"> cert_opt()</seealso> below.</d> + + <v>Config = #{server_config := [conf_opt()], + client_config := [conf_opt()]}</v> + + <v>conf_opt() = {cert, der_encoded()} | {key, der_encoded()} |{cacerts, [der_encoded()]}</v> + <d>This is a subset of the type <seealso marker="ssl:ssl#type-ssloption"> ssl:ssl_option()</seealso> </d> + </type> + + <desc> + <p>Creates certificate test data to facilitate automated testing + of applications using X509-certificates often through + SSL/TLS. The test data can be used when you have control + over both the client and the server in a test scenario. + </p> + + <p> The <marker id="cert_opt"/> cert_opt() type consists of the following options: </p> + <taglist> + <tag> {digest, digest_type()}</tag> + <item><p>Hash algorithm to be used for + signing the certificate together with the key option. Defaults to sha that is sha1. + </p></item> + <tag> {key, key_params() | private_key()}</tag> + <item><p>Parameters to be used to call public_key:generate_key/1, to generate a key, or an existing + key. Defaults to generating an ECDSA key. Note this could fail if Erlang/OTP is compiled with a very old + cryptolib.</p></item> + <tag> {validity, {From::erlang:timestamp(), To::erlang:timestamp()}} </tag> + <item><p>The validity period of the certificate.</p></item> + <tag> {extensions, [#'Extension'{}]}</tag> + <item><p> Extensions to include in the certificate.</p> + + <p>Default extensions included in CA certificates if not + otherwise specified are: </p> + <code>[#'Extension'{extnID = ?'id-ce-keyUsage', + extnValue = [keyCertSign, cRLSign], + critical = false}, +#'Extension'{extnID = ?'id-ce-basicConstraints', + extnValue = #'BasicConstraints'{cA = true}, + critical = true}] + </code> + + <p>Default extensions included in the server peer cert if not + otherwise specified are: </p> + <code>[#'Extension'{extnID = ?'id-ce-keyUsage', + extnValue = [digitalSignature, keyAgreement], + critical = false}, +#'Extension'{extnID = ?'id-ce-subjectAltName', + extnValue = [{dNSName, Hostname}], + critical = false}] + </code> + <p>Hostname is the result of calling net_adm:localhost() in the Erlang node + where this funcion is called. + </p></item> + + </taglist> + + <note><p> + Note that the generated certificates and keys does not provide a formally correct PKIX-trust-chain + and they can not be used to achieve real security. This function is provided for testing purposes only. +</p></note> + </desc> + </func> + <func> <name>pkix_verify(Cert, Key) -> boolean()</name> <fsummary>Verifies PKIX x.509 certificate signature.</fsummary> @@ -764,19 +871,20 @@ fun(#'DistributionPoint'{}, #'CertificateList'{}, <type> <v>Cert = der_encoded() | #'OTPCertificate'{} </v> <v>ReferenceIDs = [ RefID ]</v> - <v>RefID = {IdType,string()}</v> - <v>IdType = dns_id | srv_id | uri_id</v> + <v>RefID = {dns_id,string()} | {srv_id,string()} | {uri_id,string()} | {ip,inet:ip_address()|string()} | {OtherRefID,term()}}</v> + <v>OtherRefID = atom()</v> <v>Opts = [ PvhOpt() ]</v> <v>PvhOpt = [MatchOpt | FailCallBackOpt | FqdnExtractOpt]</v> - <v>MatchOpt = {fun(RefId | FQDN::string(), PresentedID) -> boolean() | default}</v> - <v>PresentedID = {dNSName,string()} | {uniformResourceIdentifier,string()}</v> + <v>MatchOpt = {match_fun, fun(RefId | FQDN::string(), PresentedID) -> boolean() | default}</v> + <v>PresentedID = {dNSName,string()} | {uniformResourceIdentifier,string() | {iPAddress,list(byte())} | {OtherPresId,term()}}</v> + <v>OtherPresID = atom()</v> <v>FailCallBackOpt = {fail_callback, fun(#'OTPCertificate'{}) -> boolean()}</v> <v>FqdnExtractOpt = {fqdn_fun, fun(RefID) -> FQDN::string() | default | undefined}</v> </type> <desc> <p>This function checks that the <i>Presented Identifier</i> (e.g hostname) in a peer certificate - conforms with the Expected Identifier that the client wants to connect to. - This functions is intended to be added as an extra client check to the peer certificate when performing + is in agreement with the <i>Reference Identifier</i> that the client expects to be connected to. + The function is intended to be added as an extra client check of the peer certificate when performing <seealso marker="public_key:public_key#pkix_path_validation-3">public_key:pkix_path_validation/3</seealso> </p> <p>See <url href="https://tools.ietf.org/html/rfc6125">RFC 6125</url> @@ -786,11 +894,18 @@ fun(#'DistributionPoint'{}, #'CertificateList'{}, <seealso marker="using_public_key#verify_hostname_examples">code examples</seealso> describes this function more detailed. </p> + <p>The <c>{OtherRefId,term()}</c> is defined by the user and is passed to the <c>match_fun</c>, if defined. + If that term is a binary, it will be converted to a string. + </p> + <p>The <c>ip</c> Reference ID takes an <seealso marker="inet:inet#type-ip_address">inet:ip_address()</seealso> + or an ip address in string format (E.g "10.0.1.1" or "1234::5678:9012") as second element. + </p> </desc> </func> <func> <name>sign(Msg, DigestType, Key) -> binary()</name> + <name>sign(Msg, DigestType, Key, Options) -> binary()</name> <fsummary>Creates a digital signature.</fsummary> <type> <v>Msg = binary() | {digest,binary()}</v> @@ -799,6 +914,7 @@ fun(#'DistributionPoint'{}, #'CertificateList'{}, digest.</d> <v>DigestType = rsa_digest_type() | dss_digest_type() | ecdsa_digest_type()</v> <v>Key = rsa_private_key() | dsa_private_key() | ec_private_key()</v> + <v>Options = public_sign_options()</v> </type> <desc> <p>Creates a digital signature.</p> @@ -891,6 +1007,7 @@ fun(#'DistributionPoint'{}, #'CertificateList'{}, <func> <name>verify(Msg, DigestType, Signature, Key) -> boolean()</name> + <name>verify(Msg, DigestType, Signature, Key, Options) -> boolean()</name> <fsummary>Verifies a digital signature.</fsummary> <type> <v>Msg = binary() | {digest,binary()}</v> @@ -899,6 +1016,7 @@ fun(#'DistributionPoint'{}, #'CertificateList'{}, <v>DigestType = rsa_digest_type() | dss_digest_type() | ecdsa_digest_type()</v> <v>Signature = binary()</v> <v>Key = rsa_public_key() | dsa_public_key() | ec_public_key()</v> + <v>Options = public_sign_options()</v> </type> <desc> <p>Verifies a digital signature.</p> |