Summary
-------

Improve the security configuration of the JDK by providing a more flexible mechanism to disable X.509 certificate chains with SHA-1 based signatures.


Non-Goals
---------

It is not a goal for the mechanism to disable all usages of SHA-1 certificates. Only X.509 certificate chains that are validated by the `PKIX` implementation of the `CertPathValidator` and `CertPathBuilder` APIs and the `SunX509` and `PKIX` implementations of the `TrustManagerFactory` API are subject to the restrictions.  Other usages (parsing, etc.) of X.509 certificates in the JDK are not affected. Third-party implementations of `CertPathValidator`, `CertPathBuilder`, and `TrustManagerFactory` are directly responsible for enforcing their own restrictions.


Motivation
----------

The use of SHA-1 based digital signature algorithms is increasingly a security concern due to the risk of [collision attacks][Wikipedia, SHA-1 Attacks]. NIST recommends in [SP 800-57, Part 1][SP 800-57, Part 1 - Rev. 4] that SHA-1 should no longer be used to apply digital signatures to data. The CA/Browser Forum's [Baseline Requirements for Publicly-Trusted SSL Certificates][CABForum BR 1.3.0] state that as of 1 January 2016, Certificate Authorities must not issue any subordinate CA or subscriber certificates using SHA-1. Other software vendors ([Google][Google, Gradually sunsetting SHA-1], [Microsoft][Microsoft, SHA-1 Deprecation Update], [Mozilla][Mozilla, Continuing to Phase Out SHA-1 Certificates], [Apple][Apple, Safari and WebKit ending support for SHA-1 certificates]) have published plans to deprecate SHA-1 in certificates. In the JDK, X.509 certificate chains are used for authentication of servers and clients in TLS and for verifying the integrity and authors of signed code.


Description
-----------

The usage of SHA-1 certificates continues to decrease, especially for publicly-trusted SSL/TLS servers (as of March 3, 2017, [0.0%][SSL Pulse] of popular SSL websites still use SHA-1). However, many enterprises use private Certificate Authorities that typically need more time to adjust to new algorithm restrictions. Additionally, code that has been previously signed and timestamped with SHA-1 certificates should continue to work for some time into the future. Thus, disabling *all* SHA-1 certificates could break many applications. Therefore, this JEP will enhance the algorithm constraints mechanism to allow for more flexible SHA-1 restriction policies to be implemented.

Specifically, the following enhancements were made to the specification of the `jdk.certpath.disabledAlgorithms` security property:

 1. A new constraint named `jdkCA`, that when set, restricts the algorithm if it is used in a certificate chain that is anchored by a trust anchor that is pre-installed in the JDK [cacerts][cacerts] keystore. This condition does not apply to certificate chains that are anchored by other certificates, including those that are subsequently added to the `cacerts` keystore. Also, note that the restriction does not apply to trust anchor certificates, since they are directly trusted.

 2. A new constraint named `denyAfter`, that when set, restricts the algorithm if it is used in a certificate chain after the specified date. The restriction does not apply to trust anchor certificates, since they are directly trusted. Also, code signing certificate chains as used in signed JARs are treated specially as follows:

    a. if the certificate chain is used with a signed JAR that is not timestamped, it will be restricted after the specified date

    b. if the certificate chain is used with a signed JAR that is timestamped, it will not be restricted if it is timestamped before the specified date. If the JAR is timestamped after the specified date, it will be restricted.

 3. A new constraint named `usage`, that when set, restricts the algorithm if it is used in a certificate chain for the specified use(s). Three usages are initially supported: `TLSServer` for TLS/SSL server certificate chains, `TLSClient` for TLS/SSL client certificate chains, and `SignedJAR` for certificate chains used with signed JARs. 

The specification of the `jdk.certpath.disabledAlgorithms` security property after the enhancements above is (see the `java.security` file for definitions of each constraint):

    DisabledAlgorithms:
        " DisabledAlgorithm { , DisabledAlgorithm } "
   
    DisabledAlgorithm:
        AlgorithmName [Constraint] { '&' Constraint }

    AlgorithmName:
        (see below)

    Constraint:
        KeySizeConstraint | CAConstraint | DenyAfterConstraint |
        UsageConstraint

    KeySizeConstraint:
        keySize Operator KeyLength
   
    Operator:
        <= | < | == | != | >= | >

    KeyLength:
        Integer value of the algorithm's key length in bits

    CAConstraint:
        jdkCA

    DenyAfterConstraint:
        denyAfter YYYY-MM-DD

    UsageConstraint: 
        usage [TLSServer] [TLSClient] [SignedJAR]

Also, the following enhancements were made to the specification of the `jdk.jar.disabledAlgorithms` security property:

 1. A new constraint named `denyAfter`, that when set, restricts the algorithm if it is used in a signed JAR after the specified date, as follows:

    a. if the JAR is not timestamped, it will be restricted (treated as unsigned) after the specified date

    b. if the JAR is timestamped, it will not be restricted if it is timestamped before the specified date. If the JAR is timestamped after the specified date, it will be restricted.

The specification of the `jdk.jar.disabledAlgorithms` security property after the enhancements above is (see the `java.security` file for definitions of each constraint):

    DisabledAlgorithms:
        " DisabledAlgorithm { , DisabledAlgorithm } "
 
    DisabledAlgorithm:
        AlgorithmName [Constraint] { '&' Constraint }
 
    AlgorithmName:
        (see below)
 
    Constraint:
        KeySizeConstraint | DenyAfterConstraint
 
    KeySizeConstraint:
        keySize Operator KeyLength
 
    DenyAfterConstraint:
        denyAfter YYYY-MM-DD
 
    Operator:
        <= | < | == | != | >= | >
 
    KeyLength:
        Integer value of the algorithm's key length in bits

Here are some examples:

To disable SHA-1 certificates that chain to trust anchors pre-installed in the cacerts file, add `"SHA1 jdkCA"` to the `jdk.certpath.disabledAlgorithms` security property:

    jdk.certpath.disabledAlgorithms=MD2, MD5, RSA keySize < 1024, \
            DSA keySize < 1024, EC keySize < 224, SHA1 jdkCA

To disable SHA-1 certificates used for authentication of TLS servers and that chain to trust anchors pre-installed in the cacerts file, add `"SHA1 jdkCA & usage TLSServer"` to the `jdk.certpath.disabledAlgorithms` security property:

    jdk.certpath.disabledAlgorithms=MD2, MD5, RSA keySize < 1024, \
            DSA keySize < 1024, EC keySize < 224, SHA1 jdkCA & usage TLSServer

To disable SHA-1 in signed JARs with the exception of JARs timestamped before January 1, 2017 , add `"SHA1 usage SignedJAR & denyAfter 2017-01-01"` to the `jdk.certpath.disabledAlgorithms` security property and `"SHA1 denyAfter 2017-01-01"` to the `jdk.jar.disabledAlgorithms` security property:

    jdk.certpath.disabledAlgorithms=MD2, MD5, RSA keySize < 1024, \
            DSA keySize < 1024, EC keySize < 224, \
            SHA1 usage SignedJAR & denyAfter 2017-01-01

    jdk.jar.disabledAlgorithms=MD2, MD5, RSA keySize < 1024, \
            DSA keySize < 1024, SHA1 denyAfter 2017-01-01



Testing
---------

Many security library regression tests currently use SHA-1 certificates. These will be modified to re-enable SHA-1 or alternatively, the certificates will be replaced with SHA-2 certificates.


Risks and Assumptions
---------------------

The Description section outlined additional constraints that will help mitigate the compatibility risk for certain use cases. We will also be working to communicate the changes via other forums and programs to help make sure that users are aware of them and understand how to configure and test their applications before new restrictions go into affect.

Dependences
-----------

This JEP depends upon three enhancements to the existing algorithm-constraints mechanism
([8140422][8140422], [8154005][8154005], [8160655][8160655]).


[Wikipedia, SHA-1 Attacks]: https://en.wikipedia.org/wiki/SHA-1#Attacks
[SP 800-57, Part 1 - Rev. 4]: http://dx.doi.org/10.6028/NIST.SP.800-57pt1r4
[CABForum BR 1.3.0]: https://cabforum.org/wp-content/uploads/CAB-Forum-BR-1.3.0.pdf
[Google, Gradually sunsetting SHA-1]: https://security.googleblog.com/2016/11/sha-1-certificates-in-chrome.html
[Microsoft, SHA-1 Deprecation Update]: https://blogs.windows.com/msedgedev/2016/04/29/sha1-deprecation-roadmap/
[Mozilla, Continuing to Phase Out SHA-1 Certificates]: https://blog.mozilla.org/security/2015/10/20/continuing-to-phase-out-sha-1-certificates/
[Apple, Safari and WebKit ending support for SHA-1 certificates]: https://support.apple.com/en-us/HT207459
[SSL Pulse]: https://www.trustworthyinternet.org/ssl-pulse/
[cacerts]: https://docs.oracle.com/javase/9/tools/keytool.htm#GUID-5990A2E4-78E3-47B7-AE75-6D1826259549__CACERTS
[8140422]: https://bugs.openjdk.java.net/browse/JDK-8140422
[8154005]: https://bugs.openjdk.java.net/browse/JDK-8154005
[8160655]: https://bugs.openjdk.java.net/browse/JDK-8160655