1// Copyright 2011 The Go Authors. All rights reserved. 2// Use of this source code is governed by a BSD-style 3// license that can be found in the LICENSE file. 4 5package x509 6 7import ( 8 "bytes" 9 "errors" 10 "fmt" 11 "net" 12 "net/url" 13 "reflect" 14 "runtime" 15 "strings" 16 "time" 17 "unicode/utf8" 18) 19 20type InvalidReason int 21 22const ( 23 // NotAuthorizedToSign results when a certificate is signed by another 24 // which isn't marked as a CA certificate. 25 NotAuthorizedToSign InvalidReason = iota 26 // Expired results when a certificate has expired, based on the time 27 // given in the VerifyOptions. 28 Expired 29 // CANotAuthorizedForThisName results when an intermediate or root 30 // certificate has a name constraint which doesn't permit a DNS or 31 // other name (including IP address) in the leaf certificate. 32 CANotAuthorizedForThisName 33 // TooManyIntermediates results when a path length constraint is 34 // violated. 35 TooManyIntermediates 36 // IncompatibleUsage results when the certificate's key usage indicates 37 // that it may only be used for a different purpose. 38 IncompatibleUsage 39 // NameMismatch results when the subject name of a parent certificate 40 // does not match the issuer name in the child. 41 NameMismatch 42 // NameConstraintsWithoutSANs is a legacy error and is no longer returned. 43 NameConstraintsWithoutSANs 44 // UnconstrainedName results when a CA certificate contains permitted 45 // name constraints, but leaf certificate contains a name of an 46 // unsupported or unconstrained type. 47 UnconstrainedName 48 // TooManyConstraints results when the number of comparison operations 49 // needed to check a certificate exceeds the limit set by 50 // VerifyOptions.MaxConstraintComparisions. This limit exists to 51 // prevent pathological certificates can consuming excessive amounts of 52 // CPU time to verify. 53 TooManyConstraints 54 // CANotAuthorizedForExtKeyUsage results when an intermediate or root 55 // certificate does not permit a requested extended key usage. 56 CANotAuthorizedForExtKeyUsage 57) 58 59// CertificateInvalidError results when an odd error occurs. Users of this 60// library probably want to handle all these errors uniformly. 61type CertificateInvalidError struct { 62 Cert *Certificate 63 Reason InvalidReason 64 Detail string 65} 66 67func (e CertificateInvalidError) Error() string { 68 switch e.Reason { 69 case NotAuthorizedToSign: 70 return "x509: certificate is not authorized to sign other certificates" 71 case Expired: 72 return "x509: certificate has expired or is not yet valid: " + e.Detail 73 case CANotAuthorizedForThisName: 74 return "x509: a root or intermediate certificate is not authorized to sign for this name: " + e.Detail 75 case CANotAuthorizedForExtKeyUsage: 76 return "x509: a root or intermediate certificate is not authorized for an extended key usage: " + e.Detail 77 case TooManyIntermediates: 78 return "x509: too many intermediates for path length constraint" 79 case IncompatibleUsage: 80 return "x509: certificate specifies an incompatible key usage" 81 case NameMismatch: 82 return "x509: issuer name does not match subject from issuing certificate" 83 case NameConstraintsWithoutSANs: 84 return "x509: issuer has name constraints but leaf doesn't have a SAN extension" 85 case UnconstrainedName: 86 return "x509: issuer has name constraints but leaf contains unknown or unconstrained name: " + e.Detail 87 } 88 return "x509: unknown error" 89} 90 91// HostnameError results when the set of authorized names doesn't match the 92// requested name. 93type HostnameError struct { 94 Certificate *Certificate 95 Host string 96} 97 98func (h HostnameError) Error() string { 99 c := h.Certificate 100 101 if !c.hasSANExtension() && matchHostnames(c.Subject.CommonName, h.Host) { 102 return "x509: certificate relies on legacy Common Name field, use SANs instead" 103 } 104 105 var valid string 106 if ip := net.ParseIP(h.Host); ip != nil { 107 // Trying to validate an IP 108 if len(c.IPAddresses) == 0 { 109 return "x509: cannot validate certificate for " + h.Host + " because it doesn't contain any IP SANs" 110 } 111 for _, san := range c.IPAddresses { 112 if len(valid) > 0 { 113 valid += ", " 114 } 115 valid += san.String() 116 } 117 } else { 118 valid = strings.Join(c.DNSNames, ", ") 119 } 120 121 if len(valid) == 0 { 122 return "x509: certificate is not valid for any names, but wanted to match " + h.Host 123 } 124 return "x509: certificate is valid for " + valid + ", not " + h.Host 125} 126 127// UnknownAuthorityError results when the certificate issuer is unknown 128type UnknownAuthorityError struct { 129 Cert *Certificate 130 // hintErr contains an error that may be helpful in determining why an 131 // authority wasn't found. 132 hintErr error 133 // hintCert contains a possible authority certificate that was rejected 134 // because of the error in hintErr. 135 hintCert *Certificate 136} 137 138func (e UnknownAuthorityError) Error() string { 139 s := "x509: certificate signed by unknown authority" 140 if e.hintErr != nil { 141 certName := e.hintCert.Subject.CommonName 142 if len(certName) == 0 { 143 if len(e.hintCert.Subject.Organization) > 0 { 144 certName = e.hintCert.Subject.Organization[0] 145 } else { 146 certName = "serial:" + e.hintCert.SerialNumber.String() 147 } 148 } 149 s += fmt.Sprintf(" (possibly because of %q while trying to verify candidate authority certificate %q)", e.hintErr, certName) 150 } 151 return s 152} 153 154// SystemRootsError results when we fail to load the system root certificates. 155type SystemRootsError struct { 156 Err error 157} 158 159func (se SystemRootsError) Error() string { 160 msg := "x509: failed to load system roots and no roots provided" 161 if se.Err != nil { 162 return msg + "; " + se.Err.Error() 163 } 164 return msg 165} 166 167func (se SystemRootsError) Unwrap() error { return se.Err } 168 169// errNotParsed is returned when a certificate without ASN.1 contents is 170// verified. Platform-specific verification needs the ASN.1 contents. 171var errNotParsed = errors.New("x509: missing ASN.1 contents; use ParseCertificate") 172 173// VerifyOptions contains parameters for Certificate.Verify. 174type VerifyOptions struct { 175 // DNSName, if set, is checked against the leaf certificate with 176 // Certificate.VerifyHostname or the platform verifier. 177 DNSName string 178 179 // Intermediates is an optional pool of certificates that are not trust 180 // anchors, but can be used to form a chain from the leaf certificate to a 181 // root certificate. 182 Intermediates *CertPool 183 // Roots is the set of trusted root certificates the leaf certificate needs 184 // to chain up to. If nil, the system roots or the platform verifier are used. 185 Roots *CertPool 186 187 // CurrentTime is used to check the validity of all certificates in the 188 // chain. If zero, the current time is used. 189 CurrentTime time.Time 190 191 // KeyUsages specifies which Extended Key Usage values are acceptable. A 192 // chain is accepted if it allows any of the listed values. An empty list 193 // means ExtKeyUsageServerAuth. To accept any key usage, include ExtKeyUsageAny. 194 KeyUsages []ExtKeyUsage 195 196 // MaxConstraintComparisions is the maximum number of comparisons to 197 // perform when checking a given certificate's name constraints. If 198 // zero, a sensible default is used. This limit prevents pathological 199 // certificates from consuming excessive amounts of CPU time when 200 // validating. It does not apply to the platform verifier. 201 MaxConstraintComparisions int 202} 203 204const ( 205 leafCertificate = iota 206 intermediateCertificate 207 rootCertificate 208) 209 210// rfc2821Mailbox represents a “mailbox” (which is an email address to most 211// people) by breaking it into the “local” (i.e. before the '@') and “domain” 212// parts. 213type rfc2821Mailbox struct { 214 local, domain string 215} 216 217// parseRFC2821Mailbox parses an email address into local and domain parts, 218// based on the ABNF for a “Mailbox” from RFC 2821. According to RFC 5280, 219// Section 4.2.1.6 that's correct for an rfc822Name from a certificate: “The 220// format of an rfc822Name is a "Mailbox" as defined in RFC 2821, Section 4.1.2”. 221func parseRFC2821Mailbox(in string) (mailbox rfc2821Mailbox, ok bool) { 222 if len(in) == 0 { 223 return mailbox, false 224 } 225 226 localPartBytes := make([]byte, 0, len(in)/2) 227 228 if in[0] == '"' { 229 // Quoted-string = DQUOTE *qcontent DQUOTE 230 // non-whitespace-control = %d1-8 / %d11 / %d12 / %d14-31 / %d127 231 // qcontent = qtext / quoted-pair 232 // qtext = non-whitespace-control / 233 // %d33 / %d35-91 / %d93-126 234 // quoted-pair = ("\" text) / obs-qp 235 // text = %d1-9 / %d11 / %d12 / %d14-127 / obs-text 236 // 237 // (Names beginning with “obs-” are the obsolete syntax from RFC 2822, 238 // Section 4. Since it has been 16 years, we no longer accept that.) 239 in = in[1:] 240 QuotedString: 241 for { 242 if len(in) == 0 { 243 return mailbox, false 244 } 245 c := in[0] 246 in = in[1:] 247 248 switch { 249 case c == '"': 250 break QuotedString 251 252 case c == '\\': 253 // quoted-pair 254 if len(in) == 0 { 255 return mailbox, false 256 } 257 if in[0] == 11 || 258 in[0] == 12 || 259 (1 <= in[0] && in[0] <= 9) || 260 (14 <= in[0] && in[0] <= 127) { 261 localPartBytes = append(localPartBytes, in[0]) 262 in = in[1:] 263 } else { 264 return mailbox, false 265 } 266 267 case c == 11 || 268 c == 12 || 269 // Space (char 32) is not allowed based on the 270 // BNF, but RFC 3696 gives an example that 271 // assumes that it is. Several “verified” 272 // errata continue to argue about this point. 273 // We choose to accept it. 274 c == 32 || 275 c == 33 || 276 c == 127 || 277 (1 <= c && c <= 8) || 278 (14 <= c && c <= 31) || 279 (35 <= c && c <= 91) || 280 (93 <= c && c <= 126): 281 // qtext 282 localPartBytes = append(localPartBytes, c) 283 284 default: 285 return mailbox, false 286 } 287 } 288 } else { 289 // Atom ("." Atom)* 290 NextChar: 291 for len(in) > 0 { 292 // atext from RFC 2822, Section 3.2.4 293 c := in[0] 294 295 switch { 296 case c == '\\': 297 // Examples given in RFC 3696 suggest that 298 // escaped characters can appear outside of a 299 // quoted string. Several “verified” errata 300 // continue to argue the point. We choose to 301 // accept it. 302 in = in[1:] 303 if len(in) == 0 { 304 return mailbox, false 305 } 306 fallthrough 307 308 case ('0' <= c && c <= '9') || 309 ('a' <= c && c <= 'z') || 310 ('A' <= c && c <= 'Z') || 311 c == '!' || c == '#' || c == '$' || c == '%' || 312 c == '&' || c == '\'' || c == '*' || c == '+' || 313 c == '-' || c == '/' || c == '=' || c == '?' || 314 c == '^' || c == '_' || c == '`' || c == '{' || 315 c == '|' || c == '}' || c == '~' || c == '.': 316 localPartBytes = append(localPartBytes, in[0]) 317 in = in[1:] 318 319 default: 320 break NextChar 321 } 322 } 323 324 if len(localPartBytes) == 0 { 325 return mailbox, false 326 } 327 328 // From RFC 3696, Section 3: 329 // “period (".") may also appear, but may not be used to start 330 // or end the local part, nor may two or more consecutive 331 // periods appear.” 332 twoDots := []byte{'.', '.'} 333 if localPartBytes[0] == '.' || 334 localPartBytes[len(localPartBytes)-1] == '.' || 335 bytes.Contains(localPartBytes, twoDots) { 336 return mailbox, false 337 } 338 } 339 340 if len(in) == 0 || in[0] != '@' { 341 return mailbox, false 342 } 343 in = in[1:] 344 345 // The RFC species a format for domains, but that's known to be 346 // violated in practice so we accept that anything after an '@' is the 347 // domain part. 348 if _, ok := domainToReverseLabels(in); !ok { 349 return mailbox, false 350 } 351 352 mailbox.local = string(localPartBytes) 353 mailbox.domain = in 354 return mailbox, true 355} 356 357// domainToReverseLabels converts a textual domain name like foo.example.com to 358// the list of labels in reverse order, e.g. ["com", "example", "foo"]. 359func domainToReverseLabels(domain string) (reverseLabels []string, ok bool) { 360 for len(domain) > 0 { 361 if i := strings.LastIndexByte(domain, '.'); i == -1 { 362 reverseLabels = append(reverseLabels, domain) 363 domain = "" 364 } else { 365 reverseLabels = append(reverseLabels, domain[i+1:]) 366 domain = domain[:i] 367 } 368 } 369 370 if len(reverseLabels) > 0 && len(reverseLabels[0]) == 0 { 371 // An empty label at the end indicates an absolute value. 372 return nil, false 373 } 374 375 for _, label := range reverseLabels { 376 if len(label) == 0 { 377 // Empty labels are otherwise invalid. 378 return nil, false 379 } 380 381 for _, c := range label { 382 if c < 33 || c > 126 { 383 // Invalid character. 384 return nil, false 385 } 386 } 387 } 388 389 return reverseLabels, true 390} 391 392func matchEmailConstraint(mailbox rfc2821Mailbox, constraint string) (bool, error) { 393 // If the constraint contains an @, then it specifies an exact mailbox 394 // name. 395 if strings.Contains(constraint, "@") { 396 constraintMailbox, ok := parseRFC2821Mailbox(constraint) 397 if !ok { 398 return false, fmt.Errorf("x509: internal error: cannot parse constraint %q", constraint) 399 } 400 return mailbox.local == constraintMailbox.local && strings.EqualFold(mailbox.domain, constraintMailbox.domain), nil 401 } 402 403 // Otherwise the constraint is like a DNS constraint of the domain part 404 // of the mailbox. 405 return matchDomainConstraint(mailbox.domain, constraint) 406} 407 408func matchURIConstraint(uri *url.URL, constraint string) (bool, error) { 409 // From RFC 5280, Section 4.2.1.10: 410 // “a uniformResourceIdentifier that does not include an authority 411 // component with a host name specified as a fully qualified domain 412 // name (e.g., if the URI either does not include an authority 413 // component or includes an authority component in which the host name 414 // is specified as an IP address), then the application MUST reject the 415 // certificate.” 416 417 host := uri.Host 418 if len(host) == 0 { 419 return false, fmt.Errorf("URI with empty host (%q) cannot be matched against constraints", uri.String()) 420 } 421 422 if strings.Contains(host, ":") && !strings.HasSuffix(host, "]") { 423 var err error 424 host, _, err = net.SplitHostPort(uri.Host) 425 if err != nil { 426 return false, err 427 } 428 } 429 430 if strings.HasPrefix(host, "[") && strings.HasSuffix(host, "]") || 431 net.ParseIP(host) != nil { 432 return false, fmt.Errorf("URI with IP (%q) cannot be matched against constraints", uri.String()) 433 } 434 435 return matchDomainConstraint(host, constraint) 436} 437 438func matchIPConstraint(ip net.IP, constraint *net.IPNet) (bool, error) { 439 if len(ip) != len(constraint.IP) { 440 return false, nil 441 } 442 443 for i := range ip { 444 if mask := constraint.Mask[i]; ip[i]&mask != constraint.IP[i]&mask { 445 return false, nil 446 } 447 } 448 449 return true, nil 450} 451 452func matchDomainConstraint(domain, constraint string) (bool, error) { 453 // The meaning of zero length constraints is not specified, but this 454 // code follows NSS and accepts them as matching everything. 455 if len(constraint) == 0 { 456 return true, nil 457 } 458 459 domainLabels, ok := domainToReverseLabels(domain) 460 if !ok { 461 return false, fmt.Errorf("x509: internal error: cannot parse domain %q", domain) 462 } 463 464 // RFC 5280 says that a leading period in a domain name means that at 465 // least one label must be prepended, but only for URI and email 466 // constraints, not DNS constraints. The code also supports that 467 // behaviour for DNS constraints. 468 469 mustHaveSubdomains := false 470 if constraint[0] == '.' { 471 mustHaveSubdomains = true 472 constraint = constraint[1:] 473 } 474 475 constraintLabels, ok := domainToReverseLabels(constraint) 476 if !ok { 477 return false, fmt.Errorf("x509: internal error: cannot parse domain %q", constraint) 478 } 479 480 if len(domainLabels) < len(constraintLabels) || 481 (mustHaveSubdomains && len(domainLabels) == len(constraintLabels)) { 482 return false, nil 483 } 484 485 for i, constraintLabel := range constraintLabels { 486 if !strings.EqualFold(constraintLabel, domainLabels[i]) { 487 return false, nil 488 } 489 } 490 491 return true, nil 492} 493 494// checkNameConstraints checks that c permits a child certificate to claim the 495// given name, of type nameType. The argument parsedName contains the parsed 496// form of name, suitable for passing to the match function. The total number 497// of comparisons is tracked in the given count and should not exceed the given 498// limit. 499func (c *Certificate) checkNameConstraints(count *int, 500 maxConstraintComparisons int, 501 nameType string, 502 name string, 503 parsedName any, 504 match func(parsedName, constraint any) (match bool, err error), 505 permitted, excluded any) error { 506 507 excludedValue := reflect.ValueOf(excluded) 508 509 *count += excludedValue.Len() 510 if *count > maxConstraintComparisons { 511 return CertificateInvalidError{c, TooManyConstraints, ""} 512 } 513 514 for i := 0; i < excludedValue.Len(); i++ { 515 constraint := excludedValue.Index(i).Interface() 516 match, err := match(parsedName, constraint) 517 if err != nil { 518 return CertificateInvalidError{c, CANotAuthorizedForThisName, err.Error()} 519 } 520 521 if match { 522 return CertificateInvalidError{c, CANotAuthorizedForThisName, fmt.Sprintf("%s %q is excluded by constraint %q", nameType, name, constraint)} 523 } 524 } 525 526 permittedValue := reflect.ValueOf(permitted) 527 528 *count += permittedValue.Len() 529 if *count > maxConstraintComparisons { 530 return CertificateInvalidError{c, TooManyConstraints, ""} 531 } 532 533 ok := true 534 for i := 0; i < permittedValue.Len(); i++ { 535 constraint := permittedValue.Index(i).Interface() 536 537 var err error 538 if ok, err = match(parsedName, constraint); err != nil { 539 return CertificateInvalidError{c, CANotAuthorizedForThisName, err.Error()} 540 } 541 542 if ok { 543 break 544 } 545 } 546 547 if !ok { 548 return CertificateInvalidError{c, CANotAuthorizedForThisName, fmt.Sprintf("%s %q is not permitted by any constraint", nameType, name)} 549 } 550 551 return nil 552} 553 554// isValid performs validity checks on c given that it is a candidate to append 555// to the chain in currentChain. 556func (c *Certificate) isValid(certType int, currentChain []*Certificate, opts *VerifyOptions) error { 557 if len(c.UnhandledCriticalExtensions) > 0 { 558 return UnhandledCriticalExtension{} 559 } 560 561 if len(currentChain) > 0 { 562 child := currentChain[len(currentChain)-1] 563 if !bytes.Equal(child.RawIssuer, c.RawSubject) { 564 return CertificateInvalidError{c, NameMismatch, ""} 565 } 566 } 567 568 now := opts.CurrentTime 569 if now.IsZero() { 570 now = time.Now() 571 } 572 if now.Before(c.NotBefore) { 573 return CertificateInvalidError{ 574 Cert: c, 575 Reason: Expired, 576 Detail: fmt.Sprintf("current time %s is before %s", now.Format(time.RFC3339), c.NotBefore.Format(time.RFC3339)), 577 } 578 } else if now.After(c.NotAfter) { 579 return CertificateInvalidError{ 580 Cert: c, 581 Reason: Expired, 582 Detail: fmt.Sprintf("current time %s is after %s", now.Format(time.RFC3339), c.NotAfter.Format(time.RFC3339)), 583 } 584 } 585 586 maxConstraintComparisons := opts.MaxConstraintComparisions 587 if maxConstraintComparisons == 0 { 588 maxConstraintComparisons = 250000 589 } 590 comparisonCount := 0 591 592 var leaf *Certificate 593 if certType == intermediateCertificate || certType == rootCertificate { 594 if len(currentChain) == 0 { 595 return errors.New("x509: internal error: empty chain when appending CA cert") 596 } 597 leaf = currentChain[0] 598 } 599 600 if (certType == intermediateCertificate || certType == rootCertificate) && 601 c.hasNameConstraints() && leaf.hasSANExtension() { 602 err := forEachSAN(leaf.getSANExtension(), func(tag int, data []byte) error { 603 switch tag { 604 case nameTypeEmail: 605 name := string(data) 606 mailbox, ok := parseRFC2821Mailbox(name) 607 if !ok { 608 return fmt.Errorf("x509: cannot parse rfc822Name %q", mailbox) 609 } 610 611 if err := c.checkNameConstraints(&comparisonCount, maxConstraintComparisons, "email address", name, mailbox, 612 func(parsedName, constraint any) (bool, error) { 613 return matchEmailConstraint(parsedName.(rfc2821Mailbox), constraint.(string)) 614 }, c.PermittedEmailAddresses, c.ExcludedEmailAddresses); err != nil { 615 return err 616 } 617 618 case nameTypeDNS: 619 name := string(data) 620 if _, ok := domainToReverseLabels(name); !ok { 621 return fmt.Errorf("x509: cannot parse dnsName %q", name) 622 } 623 624 if err := c.checkNameConstraints(&comparisonCount, maxConstraintComparisons, "DNS name", name, name, 625 func(parsedName, constraint any) (bool, error) { 626 return matchDomainConstraint(parsedName.(string), constraint.(string)) 627 }, c.PermittedDNSDomains, c.ExcludedDNSDomains); err != nil { 628 return err 629 } 630 631 case nameTypeURI: 632 name := string(data) 633 uri, err := url.Parse(name) 634 if err != nil { 635 return fmt.Errorf("x509: internal error: URI SAN %q failed to parse", name) 636 } 637 638 if err := c.checkNameConstraints(&comparisonCount, maxConstraintComparisons, "URI", name, uri, 639 func(parsedName, constraint any) (bool, error) { 640 return matchURIConstraint(parsedName.(*url.URL), constraint.(string)) 641 }, c.PermittedURIDomains, c.ExcludedURIDomains); err != nil { 642 return err 643 } 644 645 case nameTypeIP: 646 ip := net.IP(data) 647 if l := len(ip); l != net.IPv4len && l != net.IPv6len { 648 return fmt.Errorf("x509: internal error: IP SAN %x failed to parse", data) 649 } 650 651 if err := c.checkNameConstraints(&comparisonCount, maxConstraintComparisons, "IP address", ip.String(), ip, 652 func(parsedName, constraint any) (bool, error) { 653 return matchIPConstraint(parsedName.(net.IP), constraint.(*net.IPNet)) 654 }, c.PermittedIPRanges, c.ExcludedIPRanges); err != nil { 655 return err 656 } 657 658 default: 659 // Unknown SAN types are ignored. 660 } 661 662 return nil 663 }) 664 665 if err != nil { 666 return err 667 } 668 } 669 670 // KeyUsage status flags are ignored. From Engineering Security, Peter 671 // Gutmann: A European government CA marked its signing certificates as 672 // being valid for encryption only, but no-one noticed. Another 673 // European CA marked its signature keys as not being valid for 674 // signatures. A different CA marked its own trusted root certificate 675 // as being invalid for certificate signing. Another national CA 676 // distributed a certificate to be used to encrypt data for the 677 // country’s tax authority that was marked as only being usable for 678 // digital signatures but not for encryption. Yet another CA reversed 679 // the order of the bit flags in the keyUsage due to confusion over 680 // encoding endianness, essentially setting a random keyUsage in 681 // certificates that it issued. Another CA created a self-invalidating 682 // certificate by adding a certificate policy statement stipulating 683 // that the certificate had to be used strictly as specified in the 684 // keyUsage, and a keyUsage containing a flag indicating that the RSA 685 // encryption key could only be used for Diffie-Hellman key agreement. 686 687 if certType == intermediateCertificate && (!c.BasicConstraintsValid || !c.IsCA) { 688 return CertificateInvalidError{c, NotAuthorizedToSign, ""} 689 } 690 691 if c.BasicConstraintsValid && c.MaxPathLen >= 0 { 692 numIntermediates := len(currentChain) - 1 693 if numIntermediates > c.MaxPathLen { 694 return CertificateInvalidError{c, TooManyIntermediates, ""} 695 } 696 } 697 698 return nil 699} 700 701// Verify attempts to verify c by building one or more chains from c to a 702// certificate in opts.Roots, using certificates in opts.Intermediates if 703// needed. If successful, it returns one or more chains where the first 704// element of the chain is c and the last element is from opts.Roots. 705// 706// If opts.Roots is nil, the platform verifier might be used, and 707// verification details might differ from what is described below. If system 708// roots are unavailable the returned error will be of type SystemRootsError. 709// 710// Name constraints in the intermediates will be applied to all names claimed 711// in the chain, not just opts.DNSName. Thus it is invalid for a leaf to claim 712// example.com if an intermediate doesn't permit it, even if example.com is not 713// the name being validated. Note that DirectoryName constraints are not 714// supported. 715// 716// Name constraint validation follows the rules from RFC 5280, with the 717// addition that DNS name constraints may use the leading period format 718// defined for emails and URIs. When a constraint has a leading period 719// it indicates that at least one additional label must be prepended to 720// the constrained name to be considered valid. 721// 722// Extended Key Usage values are enforced nested down a chain, so an intermediate 723// or root that enumerates EKUs prevents a leaf from asserting an EKU not in that 724// list. (While this is not specified, it is common practice in order to limit 725// the types of certificates a CA can issue.) 726// 727// WARNING: this function doesn't do any revocation checking. 728func (c *Certificate) Verify(opts VerifyOptions) (chains [][]*Certificate, err error) { 729 // Platform-specific verification needs the ASN.1 contents so 730 // this makes the behavior consistent across platforms. 731 if len(c.Raw) == 0 { 732 return nil, errNotParsed 733 } 734 for i := 0; i < opts.Intermediates.len(); i++ { 735 c, err := opts.Intermediates.cert(i) 736 if err != nil { 737 return nil, fmt.Errorf("crypto/x509: error fetching intermediate: %w", err) 738 } 739 if len(c.Raw) == 0 { 740 return nil, errNotParsed 741 } 742 } 743 744 // Use platform verifiers, where available, if Roots is from SystemCertPool. 745 if runtime.GOOS == "windows" || runtime.GOOS == "darwin" || runtime.GOOS == "ios" { 746 if opts.Roots == nil { 747 return c.systemVerify(&opts) 748 } 749 if opts.Roots != nil && opts.Roots.systemPool { 750 platformChains, err := c.systemVerify(&opts) 751 // If the platform verifier succeeded, or there are no additional 752 // roots, return the platform verifier result. Otherwise, continue 753 // with the Go verifier. 754 if err == nil || opts.Roots.len() == 0 { 755 return platformChains, err 756 } 757 } 758 } 759 760 if opts.Roots == nil { 761 opts.Roots = systemRootsPool() 762 if opts.Roots == nil { 763 return nil, SystemRootsError{systemRootsErr} 764 } 765 } 766 767 err = c.isValid(leafCertificate, nil, &opts) 768 if err != nil { 769 return 770 } 771 772 if len(opts.DNSName) > 0 { 773 err = c.VerifyHostname(opts.DNSName) 774 if err != nil { 775 return 776 } 777 } 778 779 var candidateChains [][]*Certificate 780 if opts.Roots.contains(c) { 781 candidateChains = append(candidateChains, []*Certificate{c}) 782 } else { 783 if candidateChains, err = c.buildChains(nil, []*Certificate{c}, nil, &opts); err != nil { 784 return nil, err 785 } 786 } 787 788 keyUsages := opts.KeyUsages 789 if len(keyUsages) == 0 { 790 keyUsages = []ExtKeyUsage{ExtKeyUsageServerAuth} 791 } 792 793 // If any key usage is acceptable then we're done. 794 for _, usage := range keyUsages { 795 if usage == ExtKeyUsageAny { 796 return candidateChains, nil 797 } 798 } 799 800 for _, candidate := range candidateChains { 801 if checkChainForKeyUsage(candidate, keyUsages) { 802 chains = append(chains, candidate) 803 } 804 } 805 806 if len(chains) == 0 { 807 return nil, CertificateInvalidError{c, IncompatibleUsage, ""} 808 } 809 810 return chains, nil 811} 812 813func appendToFreshChain(chain []*Certificate, cert *Certificate) []*Certificate { 814 n := make([]*Certificate, len(chain)+1) 815 copy(n, chain) 816 n[len(chain)] = cert 817 return n 818} 819 820// maxChainSignatureChecks is the maximum number of CheckSignatureFrom calls 821// that an invocation of buildChains will (transitively) make. Most chains are 822// less than 15 certificates long, so this leaves space for multiple chains and 823// for failed checks due to different intermediates having the same Subject. 824const maxChainSignatureChecks = 100 825 826func (c *Certificate) buildChains(cache map[*Certificate][][]*Certificate, currentChain []*Certificate, sigChecks *int, opts *VerifyOptions) (chains [][]*Certificate, err error) { 827 var ( 828 hintErr error 829 hintCert *Certificate 830 ) 831 832 considerCandidate := func(certType int, candidate *Certificate) { 833 for _, cert := range currentChain { 834 if cert.Equal(candidate) { 835 return 836 } 837 } 838 839 if sigChecks == nil { 840 sigChecks = new(int) 841 } 842 *sigChecks++ 843 if *sigChecks > maxChainSignatureChecks { 844 err = errors.New("x509: signature check attempts limit reached while verifying certificate chain") 845 return 846 } 847 848 if err := c.CheckSignatureFrom(candidate); err != nil { 849 if hintErr == nil { 850 hintErr = err 851 hintCert = candidate 852 } 853 return 854 } 855 856 err = candidate.isValid(certType, currentChain, opts) 857 if err != nil { 858 return 859 } 860 861 switch certType { 862 case rootCertificate: 863 chains = append(chains, appendToFreshChain(currentChain, candidate)) 864 case intermediateCertificate: 865 if cache == nil { 866 cache = make(map[*Certificate][][]*Certificate) 867 } 868 childChains, ok := cache[candidate] 869 if !ok { 870 childChains, err = candidate.buildChains(cache, appendToFreshChain(currentChain, candidate), sigChecks, opts) 871 cache[candidate] = childChains 872 } 873 chains = append(chains, childChains...) 874 } 875 } 876 877 for _, root := range opts.Roots.findPotentialParents(c) { 878 considerCandidate(rootCertificate, root) 879 } 880 for _, intermediate := range opts.Intermediates.findPotentialParents(c) { 881 considerCandidate(intermediateCertificate, intermediate) 882 } 883 884 if len(chains) > 0 { 885 err = nil 886 } 887 if len(chains) == 0 && err == nil { 888 err = UnknownAuthorityError{c, hintErr, hintCert} 889 } 890 891 return 892} 893 894func validHostnamePattern(host string) bool { return validHostname(host, true) } 895func validHostnameInput(host string) bool { return validHostname(host, false) } 896 897// validHostname reports whether host is a valid hostname that can be matched or 898// matched against according to RFC 6125 2.2, with some leniency to accommodate 899// legacy values. 900func validHostname(host string, isPattern bool) bool { 901 if !isPattern { 902 host = strings.TrimSuffix(host, ".") 903 } 904 if len(host) == 0 { 905 return false 906 } 907 908 for i, part := range strings.Split(host, ".") { 909 if part == "" { 910 // Empty label. 911 return false 912 } 913 if isPattern && i == 0 && part == "*" { 914 // Only allow full left-most wildcards, as those are the only ones 915 // we match, and matching literal '*' characters is probably never 916 // the expected behavior. 917 continue 918 } 919 for j, c := range part { 920 if 'a' <= c && c <= 'z' { 921 continue 922 } 923 if '0' <= c && c <= '9' { 924 continue 925 } 926 if 'A' <= c && c <= 'Z' { 927 continue 928 } 929 if c == '-' && j != 0 { 930 continue 931 } 932 if c == '_' { 933 // Not a valid character in hostnames, but commonly 934 // found in deployments outside the WebPKI. 935 continue 936 } 937 return false 938 } 939 } 940 941 return true 942} 943 944func matchExactly(hostA, hostB string) bool { 945 if hostA == "" || hostA == "." || hostB == "" || hostB == "." { 946 return false 947 } 948 return toLowerCaseASCII(hostA) == toLowerCaseASCII(hostB) 949} 950 951func matchHostnames(pattern, host string) bool { 952 pattern = toLowerCaseASCII(pattern) 953 host = toLowerCaseASCII(strings.TrimSuffix(host, ".")) 954 955 if len(pattern) == 0 || len(host) == 0 { 956 return false 957 } 958 959 patternParts := strings.Split(pattern, ".") 960 hostParts := strings.Split(host, ".") 961 962 if len(patternParts) != len(hostParts) { 963 return false 964 } 965 966 for i, patternPart := range patternParts { 967 if i == 0 && patternPart == "*" { 968 continue 969 } 970 if patternPart != hostParts[i] { 971 return false 972 } 973 } 974 975 return true 976} 977 978// toLowerCaseASCII returns a lower-case version of in. See RFC 6125 6.4.1. We use 979// an explicitly ASCII function to avoid any sharp corners resulting from 980// performing Unicode operations on DNS labels. 981func toLowerCaseASCII(in string) string { 982 // If the string is already lower-case then there's nothing to do. 983 isAlreadyLowerCase := true 984 for _, c := range in { 985 if c == utf8.RuneError { 986 // If we get a UTF-8 error then there might be 987 // upper-case ASCII bytes in the invalid sequence. 988 isAlreadyLowerCase = false 989 break 990 } 991 if 'A' <= c && c <= 'Z' { 992 isAlreadyLowerCase = false 993 break 994 } 995 } 996 997 if isAlreadyLowerCase { 998 return in 999 } 1000 1001 out := []byte(in) 1002 for i, c := range out { 1003 if 'A' <= c && c <= 'Z' { 1004 out[i] += 'a' - 'A' 1005 } 1006 } 1007 return string(out) 1008} 1009 1010// VerifyHostname returns nil if c is a valid certificate for the named host. 1011// Otherwise it returns an error describing the mismatch. 1012// 1013// IP addresses can be optionally enclosed in square brackets and are checked 1014// against the IPAddresses field. Other names are checked case insensitively 1015// against the DNSNames field. If the names are valid hostnames, the certificate 1016// fields can have a wildcard as the left-most label. 1017// 1018// Note that the legacy Common Name field is ignored. 1019func (c *Certificate) VerifyHostname(h string) error { 1020 // IP addresses may be written in [ ]. 1021 candidateIP := h 1022 if len(h) >= 3 && h[0] == '[' && h[len(h)-1] == ']' { 1023 candidateIP = h[1 : len(h)-1] 1024 } 1025 if ip := net.ParseIP(candidateIP); ip != nil { 1026 // We only match IP addresses against IP SANs. 1027 // See RFC 6125, Appendix B.2. 1028 for _, candidate := range c.IPAddresses { 1029 if ip.Equal(candidate) { 1030 return nil 1031 } 1032 } 1033 return HostnameError{c, candidateIP} 1034 } 1035 1036 candidateName := toLowerCaseASCII(h) // Save allocations inside the loop. 1037 validCandidateName := validHostnameInput(candidateName) 1038 1039 for _, match := range c.DNSNames { 1040 // Ideally, we'd only match valid hostnames according to RFC 6125 like 1041 // browsers (more or less) do, but in practice Go is used in a wider 1042 // array of contexts and can't even assume DNS resolution. Instead, 1043 // always allow perfect matches, and only apply wildcard and trailing 1044 // dot processing to valid hostnames. 1045 if validCandidateName && validHostnamePattern(match) { 1046 if matchHostnames(match, candidateName) { 1047 return nil 1048 } 1049 } else { 1050 if matchExactly(match, candidateName) { 1051 return nil 1052 } 1053 } 1054 } 1055 1056 return HostnameError{c, h} 1057} 1058 1059func checkChainForKeyUsage(chain []*Certificate, keyUsages []ExtKeyUsage) bool { 1060 usages := make([]ExtKeyUsage, len(keyUsages)) 1061 copy(usages, keyUsages) 1062 1063 if len(chain) == 0 { 1064 return false 1065 } 1066 1067 usagesRemaining := len(usages) 1068 1069 // We walk down the list and cross out any usages that aren't supported 1070 // by each certificate. If we cross out all the usages, then the chain 1071 // is unacceptable. 1072 1073NextCert: 1074 for i := len(chain) - 1; i >= 0; i-- { 1075 cert := chain[i] 1076 if len(cert.ExtKeyUsage) == 0 && len(cert.UnknownExtKeyUsage) == 0 { 1077 // The certificate doesn't have any extended key usage specified. 1078 continue 1079 } 1080 1081 for _, usage := range cert.ExtKeyUsage { 1082 if usage == ExtKeyUsageAny { 1083 // The certificate is explicitly good for any usage. 1084 continue NextCert 1085 } 1086 } 1087 1088 const invalidUsage ExtKeyUsage = -1 1089 1090 NextRequestedUsage: 1091 for i, requestedUsage := range usages { 1092 if requestedUsage == invalidUsage { 1093 continue 1094 } 1095 1096 for _, usage := range cert.ExtKeyUsage { 1097 if requestedUsage == usage { 1098 continue NextRequestedUsage 1099 } 1100 } 1101 1102 usages[i] = invalidUsage 1103 usagesRemaining-- 1104 if usagesRemaining == 0 { 1105 return false 1106 } 1107 } 1108 } 1109 1110 return true 1111} 1112