From b0c245e8132bb13171e277b1af59c0cec00c9459 Mon Sep 17 00:00:00 2001 From: Hans Nilsson Date: Mon, 19 Dec 2016 18:26:01 +0100 Subject: public_key: pkix_verify_hostname (RFC 6125) --- lib/public_key/doc/src/public_key.xml | 33 ++++ lib/public_key/doc/src/using_public_key.xml | 253 ++++++++++++++++++++++++++++ 2 files changed, 286 insertions(+) (limited to 'lib/public_key/doc') diff --git a/lib/public_key/doc/src/public_key.xml b/lib/public_key/doc/src/public_key.xml index c503230d70..37aa05e0fd 100644 --- a/lib/public_key/doc/src/public_key.xml +++ b/lib/public_key/doc/src/public_key.xml @@ -756,6 +756,39 @@ fun(#'DistributionPoint'{}, #'CertificateList'{}, + + pkix_verify_hostname(Cert, ReferenceIDs) -> boolean() + pkix_verify_hostname(Cert, ReferenceIDs, Opts) -> boolean() + Verifies that a PKIX x.509 certificate presented identifier (e.g hostname) is + an expected one. + + Cert = der_encoded() | #'OTPCertificate'{} + ReferenceIDs = [ RefID ] + RefID = {IdType,string()} + IdType = dns_id | srv_id | uri_id + Opts = [ PvhOpt() ] + PvhOpt = [MatchOpt | FailCallBackOpt | FqdnExtractOpt] + MatchOpt = {fun(RefId | FQDN::string(), PresentedID) -> boolean() | default} + PresentedID = {dNSName,string()} | {uniformResourceIdentifier,string()} + FailCallBackOpt = {fail_callback, fun(#'OTPCertificate'{}) -> boolean()} + FqdnExtractOpt = {fqdn_fun, fun(RefID) -> FQDN::string() | default | undefined} + + +

This function checks that the Presented Identifier (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 + public_key:pkix_path_validation/3 +

+

See RFC 6125 + for detailed information about hostname verification. + The User's Manual + and + code examples + describes this function more detailed. +

+ + + sign(Msg, DigestType, Key) -> binary() Creates a digital signature. diff --git a/lib/public_key/doc/src/using_public_key.xml b/lib/public_key/doc/src/using_public_key.xml index e3a1eed4be..417d479da3 100644 --- a/lib/public_key/doc/src/using_public_key.xml +++ b/lib/public_key/doc/src/using_public_key.xml @@ -417,6 +417,259 @@ true = public_key:verify(Digest, none, Signature, PublicKey), +
+ + Verifying a certificate hostname +
+ Background +

When a client checks a server certificate there are a number of checks available like + checks that the certificate is not revoked, not forged or not out-of-date. +

+

There are however attacks that are not detected by those checks. Suppose a bad guy has + succeded with a DNS infection. Then the client could belive it is connecting to one host but + ends up at another but evil one. Though it is evil, it could have a perfectly legal + certificate! The certificate has a valid signature, it is not revoked, the certificate chain + is not faked and has a trusted root and so on. +

+

To detect that the server is not the intended one, the client must additionaly perform + a hostname verification. This procedure is described in + RFC 6125. The idea is that the certificate + lists the hostnames it could be fetched from. This is checked by the certificate issuer when + the certificate is signed. So if the certificate is issued by a trusted root the client + could trust the host names signed in it. +

+

There is a default hostname matching procedure defined in + RFC 6125, section 6 + as well as protocol dependent variations defined in + RFC 6125 appendix B. + The default procedure is implemented in + public_key:pkix_verify_hostname/2,3. + It is possible for a client to hook in modified rules using the options list. +

+

Some terminology is needed: the certificate presents hostname(s) on which it is valid. + Those are called Presented IDs. The hostname(s) the client belives it connects to + are called Reference IDs. The matching rules aims to verify that there is at least + one of the Reference IDs that matches one of the Presented IDs. If not, the verification fails. +

+

The IDs contains normal fully qualified domain names like e.g foo.example.com, + but IP addresses are not recommended. The rfc describes why this is not recommended as well + as security considerations about how to aquire the Reference IDs. +

+

Internationalized domain names are not supported. +

+
+
+ The verification process +

Traditionally the Presented IDs were found in the Subject certificate field as CN + names. This is still quite common. When printing a certificate they show up as: +

+ + $ openssl x509 -text < cert.pem + ... + Subject: C=SE, CN=example.com, CN=*.example.com, O=erlang.org + ... + +

The example Subject field has one C, two CN and one O part. It is only the + CN (Common Name) that is used by hostname verification. The two other (C and O) is not used + here even when they contain a domain name like the O part. The C and O parts are defined + elsewhere and meaningful only for other functions. +

+

In the example the Presented IDs are example.com as well as hostnames matching + *.example.com. For example foo.example.com and bar.example.com both + matches but not foo.bar.example.com. The name erlang.org matches neither + since it is not a CN. +

+

In case where the Presented IDs are fetched from the Subject certificate field, the + names may contain wildcard characters. The function handles this as defined in + chapter 6.4.3 in RFC 6125. +

+

There may only be one wildcard character and that is in the first label, for example: + *.example.com. This matches foo.example.com but neither example.com nor + foo.bar.example.com. +

+

There may be label characters before or/and after the wildcard. For example: + a*d.example.com matches abcd.example.com and ad.example.com, + but not ab.cd.example.com. +

+

In the previous example there is no indication of which protocols are expected. So a client + has no indication of whether it is a web server, an ldap server or maybe a sip server it is + connected to. + There are fields in the certificate that can indicate this. To be more exact, the rfc + introduces the usage of the X509v3 Subject Alternative Name in the X509v3 extensions + field: +

+ + $ openssl x509 -text < cert.pem + ... + X509v3 extensions: + X509v3 Subject Alternative Name: + DNS:kb.example.org, URI:https://www.example.org + ... + +

Here kb.example.org serves any protocol while www.example.org presents a secure + web server. +

+ +

The next example has both Subject and Subject Alternate Name present:

+ + $ openssl x509 -text < cert.pem + ... + Subject: C=SE, CN=example.com, CN=*.example.com, O=erlang.org + ... + X509v3 extensions: + X509v3 Subject Alternative Name: + DNS:kb.example.org, URI:https://www.example.org + ... + +

The RFC states that if a certificate defines Reference IDs in a Subject Alternate Name + field, the Subject field MUST NOT be used for host name checking, even if it contains + valid CN names. + Therefore only kb.example.org and https://www.example.org matches. The match fails + both for example.com and foo.example.com becuase they are in the Subject + field which is not checked because the Subject Alternate Name field is present. +

+
+ +
+ + Function call examples + +

Other applications like ssl/tls or https might have options that are passed + down to the public_key:pkix_verify_hostname. You will probably not + have to call it directly

+ +

Suppose our client expects to connect to the web server https://www.example.net. This + URI is therefore the Reference IDs of the client. + The call will be: +

+ + public_key:pkix_verify_hostname(CertFromHost, + [{uri_id, "https://www.example.net"} + ]). + +

The call will return true or false depending on the check. The caller + do not need to handle the matching rules in the rfc. The matching will proceed as: +

+ + If there is a Subject Alternate Name field, the {uri_id,string()} in the + function call will be compared to any + {uniformResourceIdentifier,string()} in the Certificate field. + If the two strings() are equal (case insensitive), there is a match. + The same applies for any {dns_id,string()} in the call which is compared + with all {dNSName,string()} in the Certificate field. + + If there is NO Subject Alternate Name field, the Subject field will be + checked. All CN names will be compared to all hostnames extracted from + {uri_id,string()} and from {dns_id,string()}. + + +
+
+ Extending the search mechanism +

The caller can use own extraction and matching rules. This is done with the two options + fqdn_fun and match_fun. +

+
+ Hostname extraction +

The fqdn_fun extracts hostnames (Fully Qualified Domain Names) from uri_id + or other ReferenceIDs that are not pre-defined in the public_key function. + Suppose you have some URI with a very special protocol-part: + myspecial://example.com". Since this a non-standard URI there will be no hostname + extracted for matching CN-names in the Subject.

+

To "teach" the function how to extract, you can give a fun which replaces the default + extraction function. + The fqdn_fun takes one argument and returns + either a string() to be matched to each CN-name or the atom default which will invoke + the default fqdn extraction function. The return value undefined removes the current + URI from the fqdn extraction. +

+ + ... + Extract = fun({uri_id, "myspecial://"++HostName}) -> HostName; + (_Else) -> default + end, + ... + public_key:pkix_verify_hostname(CertFromHost, RefIDs, + [{fqdn_fun, Extract}]) + ... + +
+
+ Re-defining the match operations +

The default matching handles dns_id and uri_id. In an uri_id the value is tested for + equality with a value from the Subject Alternate Name. If som other kind of matching + is needed, use the match_fun option. +

+

The match_fun takes two arguments and returns either true, + false or default. The value default will invoke the default + match function. +

+ + ... + Match = fun({uri_id,"myspecial://"++A}, + {uniformResourceIdentifier,"myspecial://"++B}) -> + my_match(A,B); + (_RefID, _PresentedID) -> + default + end, + ... + public_key:pkix_verify_hostname(CertFromHost, RefIDs, + [{match_fun, Match}]), + ... + +

In case of a match operation between a ReferenceID and a CN value from the Subject + field, the first argument to the fun is the extracted hostname from the ReferenceID, and the + second argument is the tuple {cn, string()} taken from the Subject field. That + makes it possible to have separate matching rules for Presented IDs from the Subject + field and from the Subject Alternate Name field. +

+

The default matching transformes the ascii values in strings to lowercase before comparing. + The match_fun is however called without any transfomation applied to the strings. The + reason is to enable the user to do unforseen handling of the strings where the original format + is needed. +

+
+
+
+ "Pinning" a Certificate +

The RFC 6125 defines pinning + as:

+ +

"The act of establishing a cached name association between + the application service's certificate and one of the client's + reference identifiers, despite the fact that none of the presented + identifiers matches the given reference identifier. ..." +

+ +

The purpose is to have a mechanism for a human to accept an otherwise faulty Certificate. + In for example a web browser, you could get a question like

+ +

Warning: you wanted to visit the site www.example.com, + but the certificate is for shop.example.com. Accept anyway (yes/no)?" +

+ +

This could be accomplished with the option fail_callback which will + be called if the hostname verification fails: +

+ + -include_lib("public_key/include/public_key.hrl"). % Record def + ... + Fail = fun(#'OTPCertificate'{}=C) -> + case in_my_cache(C) orelse my_accept(C) of + true -> + enter_my_cache(C), + true; + false -> + false + end, + ... + public_key:pkix_verify_hostname(CertFromHost, RefIDs, + [{fail_callback, Fail}]), + ... + +
+
+
SSH Files -- cgit v1.2.3