diff options
Diffstat (limited to 'lib/public_key/doc/src/public_key.xml')
| -rw-r--r-- | lib/public_key/doc/src/public_key.xml | 128 |
1 files changed, 75 insertions, 53 deletions
diff --git a/lib/public_key/doc/src/public_key.xml b/lib/public_key/doc/src/public_key.xml index 64f01e670b..76d50c7c63 100644 --- a/lib/public_key/doc/src/public_key.xml +++ b/lib/public_key/doc/src/public_key.xml @@ -36,7 +36,7 @@ <description> <p>Provides functions to handle public-key infrastructure, for details see - <seealso marker="public_key_app">public_key(6)</seealso>. + <seeapp marker="public_key_app">public_key(6)</seeapp>. </p> </description> @@ -46,8 +46,8 @@ <note><p>All records used in this Reference Manual <!-- except #policy_tree_node{} --> are generated from ASN.1 specifications - and are documented in the User's Guide. See <seealso - marker="public_key_records">Public-key Records</seealso>. + and are documented in the User's Guide. See <seeguide + marker="public_key_records">Public-key Records</seeguide>. </p></note> <p>Use the following include directive to get access to the @@ -93,13 +93,14 @@ <desc> <code>Cipher = "RC2-CBC" | "DES-CBC" | "DES-EDE3-CBC"</code> <p><c>Salt</c> could be generated with - <seealso marker="crypto:crypto#strong_rand_bytes-1"><c>crypto:strong_rand_bytes(8)</c></seealso>.</p> + <seemfa marker="crypto:crypto#strong_rand_bytes/1"><c>crypto:strong_rand_bytes(8)</c></seemfa>.</p> </desc> </datatype> <datatype> <name name="public_key"/> <name name="rsa_public_key"/> + <name name="rsa_pss_public_key"/> <name name="dsa_public_key"/> <name name="ec_public_key"/> <name name="ecpk_parameters"/> @@ -118,6 +119,7 @@ <datatype> <name name="private_key"/> <name name="rsa_private_key"/> + <name name="rsa_pss_private_key"/> <name name="dsa_private_key"/> <name name="ec_private_key"/> <desc> @@ -151,7 +153,7 @@ </datatype> <datatype> - <name name="issuer_id"/> + <name name="cert_id"/> <desc> </desc> </datatype> @@ -196,8 +198,8 @@ <name name="decrypt_private" arity="3" since="OTP R14B"/> <fsummary>Public-key decryption.</fsummary> <desc> - <p>Public-key decryption using the private key. See also <seealso - marker="crypto:crypto#private_decrypt/4">crypto:private_decrypt/4</seealso></p> + <p>Public-key decryption using the private key. See also <seemfa + marker="crypto:crypto#private_decrypt/4">crypto:private_decrypt/4</seemfa></p> </desc> </func> @@ -206,8 +208,8 @@ <name name="decrypt_public" arity="3" since="OTP R14B"/> <fsummary>Public-key decryption.</fsummary> <desc> - <p>Public-key decryption using the public key. See also <seealso - marker="crypto:crypto#public_decrypt/4">crypto:public_decrypt/4</seealso></p> + <p>Public-key decryption using the public key. See also <seemfa + marker="crypto:crypto#public_decrypt/4">crypto:public_decrypt/4</seemfa></p> </desc> </func> @@ -254,8 +256,8 @@ <fsummary>Public-key encryption using the private key.</fsummary> <desc> <p>Public-key encryption using the private key. - See also <seealso - marker="crypto:crypto#private_encrypt/4">crypto:private_encrypt/4</seealso>.</p> + See also <seemfa + marker="crypto:crypto#private_encrypt/4">crypto:private_encrypt/4</seemfa>.</p> </desc> </func> @@ -264,8 +266,8 @@ <name name="encrypt_public" arity="3" since="OTP 21.1"/> <fsummary>Public-key encryption using the public key.</fsummary> <desc> - <p>Public-key encryption using the public key. See also <seealso - marker="crypto:crypto#public_encrypt/4">crypto:public_encrypt/4</seealso>.</p> + <p>Public-key encryption using the public key. See also <seemfa + marker="crypto:crypto#public_encrypt/4">crypto:public_encrypt/4</seemfa>.</p> </desc> </func> @@ -275,7 +277,7 @@ <desc> <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> + <seemfa marker="crypto:crypto#generate_key/2">crypto:generate_key/2</seemfa> </p> </desc> </func> @@ -376,9 +378,9 @@ <func> <name name="pkix_issuer_id" arity="2" since="OTP R14B"/> - <fsummary>Returns the issuer id.</fsummary> + <fsummary>Returns the x509 certificater issuer id.</fsummary> <desc> - <p>Returns the issuer id.</p> + <p>Returns the x509 certificater issuer id, if it can be determined.</p> </desc> </func> @@ -405,8 +407,8 @@ <v>CertChain = [der_encoded()]</v> <d>A list of DER-encoded certificates in trust order ending with the peer certificate.</d> <v>Options = proplists:proplist()</v> - <v>PublicKeyInfo = {?'rsaEncryption' | ?'id-dsa', - rsa_public_key() | integer(), 'NULL' | 'Dss-Parms'{}}</v> + <v>PublicKeyInfo = {?'rsaEncryption' | ?'id-RSASSA-PSS'| ?'id-dsa', + rsa_public_key() | integer(), 'NULL' | 'RSASSA-PSS-params'{} | 'Dss-Parms'{}}</v> <v>PolicyTree = term()</v> <d>At the moment this is always an empty list as policies are not currently supported.</d> <v>Reason = cert_expired | invalid_issuer | invalid_signature | name_not_permitted | @@ -417,8 +419,8 @@ <p> Performs a basic path validation according to <url href="http://www.ietf.org/rfc/rfc5280.txt">RFC 5280.</url> - However, CRL validation is done separately by <seealso - marker="#pkix_crls_validate-3">pkix_crls_validate/3 </seealso> and is to be called + However, CRL validation is done separately by <seemfa + marker="#pkix_crls_validate/3">pkix_crls_validate/3 </seemfa> and is to be called from the supplied <c>verify_fun</c>. </p> @@ -448,6 +450,10 @@ fun(OtpCert :: #'OTPCertificate'{}, verifying application-specific extensions. If called with an extension unknown to the user application, the return value <c>{unknown, UserState}</c> is to be used.</p> + <warning><p> + Note that user defined custom <c>verify_fun</c> may alter original + path validation error (e.g <c>selfsigned_peer</c>). Use with caution. + </p></warning> </item> <tag>{max_path_length, integer()}</tag> @@ -505,8 +511,8 @@ fun(OtpCert :: #'OTPCertificate'{}, <fsummary>Performs CRL validation.</fsummary> <desc> <p>Performs CRL validation. It is intended to be called from - the verify fun of <seealso marker="#pkix_path_validation-3"> pkix_path_validation/3 - </seealso>.</p> + the verify fun of <seemfa marker="#pkix_path_validation/3"> pkix_path_validation/3 + </seemfa>.</p> <p>Available options:</p> @@ -565,8 +571,8 @@ fun(#'DistributionPoint'{}, #'CertificateList'{}, <fsummary>Creates a distribution point for CRLs issued by the same issuer as <c>Cert</c>.</fsummary> <desc> <p>Creates a distribution point for CRLs issued by the same issuer as <c>Cert</c>. - Can be used as input to <seealso - marker="#pkix_crls_validate-3">pkix_crls_validate/3 </seealso> + Can be used as input to <seemfa + marker="#pkix_crls_validate/3">pkix_crls_validate/3 </seemfa> </p> </desc> </func> @@ -578,7 +584,15 @@ fun(#'DistributionPoint'{}, #'CertificateList'{}, <p> Extracts distribution points from the certificates extensions.</p> </desc> </func> - + + <func> + <name name="pkix_hash_type" arity="1" since="@master@"/> + <fsummary>Translates OID to Erlang digest type</fsummary> + <desc> + <p>Translates OID to Erlang digest type</p> + </desc> + </func> + <func> <name name="pkix_match_dist_point" arity="2" since="OTP 19.0"/> <fsummary>Checks whether the given distribution point matches the @@ -626,19 +640,19 @@ fun(#'DistributionPoint'{}, #'CertificateList'{}, <d> A valid chain must have at least a ROOT and a peer cert. The root cert can be given either as a cert pre-generated by - <seealso marker="#pkix_test_root_cert-2"> + <seemfa marker="#pkix_test_root_cert/2"> pkix_test_root_cert/2 - </seealso>, or as root cert generation options. + </seemfa>, or as root cert generation options. </d> <v>root_cert() = #{cert := der_encoded(), key := Key}</v> <d> A root certificate generated by - <seealso marker="#pkix_test_root_cert-2"> + <seemfa marker="#pkix_test_root_cert/2"> pkix_test_root_cert/2 - </seealso>. + </seemfa>. </d> <v>cert_opt() = {Key, Value}</v> - <d>For available options see <seealso marker="#cert_opt"> cert_opt()</seealso> below.</d> + <d>For available options see <seeerl marker="#cert_opt"> cert_opt()</seeerl> below.</d> <v>Config = #{server_config := [conf_opt()], client_config := [conf_opt()]}</v> @@ -646,9 +660,9 @@ fun(#'DistributionPoint'{}, #'CertificateList'{}, <v>conf_opt() = {cert, der_encoded()} | {key, PrivateKey} |{cacerts, [der_encoded()]}</v> <d> This is a subset of the type - <seealso marker="ssl:ssl#type-tls_option"> ssl:tls_option()</seealso>. + <seetype marker="ssl:ssl#tls_option"> ssl:tls_option()</seetype>. <c>PrivateKey</c> is what - <seealso marker="#generate_key-1">generate_key/1</seealso> + <seemfa marker="#generate_key/1">generate_key/1</seemfa> returns. </d> </type> @@ -675,9 +689,9 @@ fun(#'DistributionPoint'{}, #'CertificateList'{}, as root of the client certificate chain. Vice versa applies to the <c>cacerts</c> returned for the client. The root cert(s) can either be pre-generated with - <seealso marker="#pkix_test_root_cert-2"> + <seemfa marker="#pkix_test_root_cert/2"> pkix_test_root_cert/2 - </seealso>, or if options are specified; it is (they are) + </seemfa>, or if options are specified; it is (they are) generated. </p> <p> @@ -752,27 +766,35 @@ fun(#'DistributionPoint'{}, #'CertificateList'{}, <v>Options = [cert_opt()]</v> <d> For available options see - <seealso marker="#cert_opt">cert_opt()</seealso> + <seeerl marker="#cert_opt">cert_opt()</seeerl> under - <seealso marker="#pkix_test_data-1">pkix_test_data/1</seealso>. + <seemfa marker="#pkix_test_data/1">pkix_test_data/1</seemfa>. </d> <v>RootCert = #{cert := der_encoded(), key := Key}</v> <d> A root certificate and key. The <c>Key</c> is generated by - <seealso marker="#generate_key-1">generate_key/1</seealso>. + <seemfa marker="#generate_key/1">generate_key/1</seemfa>. </d> </type> <desc> <p> Generates a root certificate that can be used in multiple calls to - <seealso marker="#pkix_test_data-1">pkix_test_data/1</seealso> + <seemfa marker="#pkix_test_data/1">pkix_test_data/1</seemfa> when you want the same root certificate for several generated certificates. </p> </desc> </func> + <func> + <name name="pkix_subject_id" arity="1" since="@maint@"/> + <fsummary>Returns the X509 certificate subject id.</fsummary> + <desc> + <p>Returns the X509 certificate subject id.</p> + </desc> + </func> + <func> <name name="pkix_verify" arity="2" since="OTP R14B"/> <fsummary>Verifies PKIX x.509 certificate signature.</fsummary> @@ -803,20 +825,20 @@ fun(#'DistributionPoint'{}, #'CertificateList'{}, <p>This function checks that the <i>Presented Identifier</i> (e.g hostname) in a peer certificate is in agreement with at least one of 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> + <seemfa marker="public_key:public_key#pkix_path_validation/3">public_key:pkix_path_validation/3</seemfa> </p> <p>See <url href="https://tools.ietf.org/html/rfc6125">RFC 6125</url> for detailed information about hostname verification. - The <seealso marker="using_public_key#verify_hostname">User's Guide</seealso> + The <seeguide marker="using_public_key#verify_hostname">User's Guide</seeguide> and - <seealso marker="using_public_key#verify_hostname_examples">code examples</seealso> + <seeguide marker="using_public_key#verify_hostname_examples">code examples</seeguide> 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 the term in <c>OtherRefId</c> is a binary, it will be converted to a string. </p> <p>The <c>ip</c> Reference ID takes an - <seealso marker="kernel:inet#type-ip_address">inet:ip_address()</seealso> + <seetype marker="kernel:inet#ip_address">inet:ip_address()</seetype> or an ip address in string format (E.g "10.0.1.1" or "1234::5678:9012") as second element. </p> <p>The options are:</p> @@ -832,9 +854,9 @@ fun(....) -> true; % My special case (_, _) -> default % all others falls back to the inherit tests end </code> - <br/>See <seealso marker="#pkix_verify_hostname_match_fun-1">pkix_verify_hostname_match_fun/1</seealso> for a + <br/>See <seemfa marker="#pkix_verify_hostname_match_fun/1">pkix_verify_hostname_match_fun/1</seemfa> for a function that takes a protocol name as argument and returns a <c>fun/2</c> suitable for this option and - <seealso marker="using_public_key#redefining_match_op">Re-defining the match operation</seealso> + <seeguide marker="using_public_key#redefining_match_op">Re-defining the match operation</seeguide> in the User's Guide for an example. </item> @@ -844,7 +866,7 @@ end of such a function. This <c>fun/1</c> is called when no <c>ReferenceID</c> matches. The return value of the fun (a <c>boolean()</c>) decides the outcome. If <c>true</c> the the certificate is accepted otherwise it is rejected. See - <seealso marker="using_public_key#-pinning--a-certificate">"Pinning" a Certificate</seealso> + <seeguide marker="using_public_key#-pinning--a-certificate">"Pinning" a Certificate</seeguide> in the User's Guide. </item> @@ -858,7 +880,7 @@ end will return <c>false</c>.</item> </list> <br/>For an example, see - <seealso marker="using_public_key#hostname_extraction">Hostname extraction</seealso> + <seeguide marker="using_public_key#hostname_extraction">Hostname extraction</seeguide> in the User's Guide. </item> </taglist> @@ -874,15 +896,15 @@ end <v>Protocol = https</v> <d>The algorithm for wich the fun should implement the special matching rules</d> <v>RefId</v> - <d>See <seealso marker="#pkix_verify_hostname-3">pkix_verify_hostname/3</seealso>.</d> + <d>See <seemfa marker="#pkix_verify_hostname/3">pkix_verify_hostname/3</seemfa>.</d> <v>FQDN</v> - <d>See <seealso marker="#pkix_verify_hostname-3">pkix_verify_hostname/3</seealso>.</d> + <d>See <seemfa marker="#pkix_verify_hostname/3">pkix_verify_hostname/3</seemfa>.</d> <v>PresentedID</v> - <d>See <seealso marker="#pkix_verify_hostname-3">pkix_verify_hostname/3</seealso>.</d> + <d>See <seemfa marker="#pkix_verify_hostname/3">pkix_verify_hostname/3</seemfa>.</d> </type> <desc> <p>The return value of calling this function is intended to be used in the <c>match_fun</c> option in - <seealso marker="#pkix_verify_hostname-3">pkix_verify_hostname/3</seealso>. + <seemfa marker="#pkix_verify_hostname/3">pkix_verify_hostname/3</seemfa>. </p> <p>The returned fun augments the verify hostname matching according to the specific rules for the protocol in the argument. @@ -941,7 +963,7 @@ end <desc> <p>Encodes a list of SSH file entries (public keys and attributes) to a binary. Possible attributes depend on the file type, see - <seealso marker="#ssh_decode-2"> ssh_decode/2 </seealso>. + <seemfa marker="#ssh_decode/2"> ssh_decode/2 </seemfa>. </p> <p>If the <c>Type</c> is <c>ssh2_pubkey</c>, the <c>InData</c> shall be <c>InData_ssh2_pubkey</c>. Otherwise it shall be <c>OtherInData</c>. @@ -955,8 +977,8 @@ end <name since="OTP 19.2">ssh_hostkey_fingerprint([DigestType], HostKey) -> [string()]</name> <fsummary>Calculates a ssh fingerprint for a hostkey.</fsummary> <type> - <v>HostKey = <seealso marker="#type-public_key">public_key()</seealso></v> - <v>DigestType = <seealso marker="#type-digest_type">digest_type()</seealso></v> + <v>HostKey = <seetype marker="#public_key">public_key()</seetype></v> + <v>DigestType = <seetype marker="#digest_type">digest_type()</seetype></v> </type> <desc> <p>Calculates a ssh fingerprint from a public host key as openssh does.</p> |