JDK-8241871 : Support the 'canonicalize' setting (krb5.conf) in the Kerberos client
  • Type: CSR
  • Component: security-libs
  • Sub-Component: javax.security
  • Priority: P3
  • Status: Closed
  • Resolution: Approved
  • Fix Versions: 15
  • Submitted: 2020-03-30
  • Updated: 2020-05-04
  • Resolved: 2020-05-04
Related Reports
CSR :  

Extend the Kerberos configuration file (*krb5.conf*, specified by the *java.security.krb5.conf* system property) to include a 'canonicalize' option under the 'libdefaults' section. Change the Kerberos client default behavior to send the 'canonicalize' bit *off* in all Authentication Service (AS) requests.


After the implementation of [RFC 6806][1] ([JDK-8215032]), the Kerberos client sends the 'canonicalize' bit *on* by default in all KDC requests (including those used to get TGTs as well as those to get TGSs tickets). As described in the referred RFC, this option bit announces support for Referrals and Name Canonicalization from the client side.

One of the consequences of the previous is that the KDC may issue a TGT ticket -in response to an AS request- with a different Client Name (cname) than the one requested.

Even though the Kerberos client and the JAAS framework  are ready to handle such change, some applications -which get the ticket through undocumented APIs- consider it too disruptive.

In addition, old KDCs such as Windows AD 2008, change the cname when 'canonicalize' is *on* but do not include the security scheme proposed by RFC 6806 in [Section 11][2] to mitigate associated security risks. These responses are then rejected by the client.


Change the Kerberos client default behavior to send 'canonicalize' bit *off* in all AS requests. Introduce a Kerberos configuration to turn 'canonicalize' *on* for AS requests. These changes will bring better alignment with the [MIT's Kerberos client][3].

Note: the 'sun.security.krb5.disableReferrals' system and security properties can be used to turn Name Canonicalization *off*. However, that also implies that TGS referrals -when requesting TGS tickets- will be disabled too. The proposed solution allows to disabled Name Canonicalization only, while continue supporting RFC 6806 TGS referrals.


1) The Kerberos client sends 'canonicalize' bit *off* in all AS requests by default. The previous behavior is not modified for TGS requests, which continue including the 'canonicalize' bit *on* by default and a fallback scheme in case the server returns an unexpected error.

2) A new 'canonicalize' option in the Kerberos configuration file (*krb5.conf*, specified by the *java.security.krb5.conf* system property) is introduced under the 'libdefaults' section. The default value is *false*. If the 'canonicalize' option is set *true*, all AS requests will contain the 'canonicalize' bit *on* (unless referrals were disabled through *sun.security.krb5.disableReferrals*).

Grammar for 'canonicalize' option in the Kerberos configuration file:

    canonicalize = true|false

Example of a *krb5.conf* file with 'canonicalize' *on*:

    canonicalize = true

Specs that need to be updated:

 * 7 Java Generic Security Services (Java GSS-API)
   * The Kerberos 5 GSS-API Mechanism
     * Supported krb5.conf Settings
         * Add 'canonicalize' in '[libdefaults]' section, above 'renewable' (so we group request options together)
         * Add 'canonicalize = false' in defaults for the *krb5.conf* file parameters, above 'renewable = false' (for the previous reason).

Review discussion thread and further information [here][4].

  [1]: https://tools.ietf.org/html/rfc6806
  [2]: https://tools.ietf.org/html/rfc6806#section-11
  [3]: https://web.mit.edu/kerberos/krb5-1.12/doc/admin/conf_files/krb5_conf.html#libdefaults
  [4]: https://mail.openjdk.java.net/pipermail/security-dev/2020-March/021494.html
Moving to Approved.

Renamed the CSR title to be more descriptive than the bug report title. Joe Darcy, can I move this CSR to Finalized?

[~darcy], I just created a sub-task at JDK-8242409. Thanks.

[~weijun], please file on docs bug to update the "The Kerberos 5 GSS-API Mechanism " so that [~mbalao] can advance this request to Finalized; thanks.

@Joe Darcy: * A grammar for the new configuration option was added, as well as an example to clarify how a possible instantiation of that would look like. * Reference to the Specs that need to be changed (and how the should be changed) added. * Yes, a Release Note is required. I will create one. Can I move the CSR to Finalized now?

Moving to Provisional. Before this request is Finalized, please state what specs need to be updated and show any such updates. Please provide a grammar for the new conf section. Should this change have a release note?

It's desirable to have this change for JDK-15. The proposed patch has been reviewed and approved (see [here][1]). CSR approval is the only missing part. [1]: https://mail.openjdk.java.net/pipermail/security-dev/2020-March/021495.html

What releases is this change intended for?