New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

security: Stabilize AdvancedTlsX509TrustManager. #11216

Open

erm-g wants to merge 16 commits into grpc:master from erm-g:TrustManager

+229 −46

Contributor

erm-g commented May 16, 2024

This PR is a part of 'Stabilize Advanced TLS' effort.
Clean up, improve javadoc, de-experimentalize of AdvancedTlsX509TrustManager, add a unit test (e2e already exists).

erm-g added 2 commits

May 16, 2024 03:26


          Stabilization of API and unit testing

2075b79


          unused import

edcbd0a

erm-g requested a review from matthewstevenson88

May 16, 2024 04:27

matthewstevenson88 reviewed

View reviewed changes

Contributor

matthewstevenson88 left a comment

Thanks for the PR @erm-g! Generally LG, just a few minor comments.

util/src/main/java/io/grpc/util/AdvancedTlsX509TrustManager.java

                     keyStore.setCertificateEntry(alias, cert);
                     i++;
                   }
-                  X509ExtendedTrustManager newDelegateManager = createDelegateTrustManager(keyStore);
-                  this.delegateManager = newDelegateManager;
+                  this.delegateManager = createDelegateTrustManager(keyStore);

Contributor

matthewstevenson88 May 16, 2024

Pre-existing readability nit: this. is redundant here and can be removed. There seem to be a few other instances of this pattern in this file, feel free to clean them all up if you like.

Contributor Author

erm-g May 16, 2024

Agreed, it's redundant here and the G style guide suggest to omit it.
I code it that way because it was the style here and at KeyManager, plus it also exists at

grpc-java/api/src/main/java/io/grpc/TlsServerCredentials.java

Line 326 in 8aaace1

this.keyManagers = keyManagerList;

Let's defer to Eric

util/src/main/java/io/grpc/util/AdvancedTlsX509TrustManager.java Outdated

@@ @@ -43,30 +44,38 @@ @@
               /**
                * AdvancedTlsX509TrustManager is an {@code X509ExtendedTrustManager} that allows users to configure
                * advanced TLS features, such as root certificate reloading, peer cert custom verification, etc.
+               * We expect only one of {@link AdvancedTlsX509TrustManager#useSystemDefaultTrustCerts()},

Contributor

matthewstevenson88 May 16, 2024

Can you elaborate on what happens if the user does not respect this?

Contributor Author

erm-g May 16, 2024

Theoretically speaking, a user can do the following trick:

Some process (non gRPC) updates the cert file
User spawns a thread to periodically call updateTrustCredentialsFromFile(file)
User calls updateTrustCredentialsFromFile(File trustCertFile, long period, TimeUnit unit,
ScheduledExecutorService executor) multiple times without cancelling the result

As a result an outdated version of creds might be used till the next update. It's not truly a synchronization issue (that's why we don't guard this methods with locks) but a similar to it - so we decided to add a warning. Definitely the example is a made up one and we don't expect a user do anything like that

Contributor

matthewstevenson88 May 16, 2024

Makes sense, thanks for clarifying.

util/src/main/java/io/grpc/util/AdvancedTlsX509TrustManager.java Outdated

@@ @@ -43,30 +44,38 @@ @@
               /**
                * AdvancedTlsX509TrustManager is an {@code X509ExtendedTrustManager} that allows users to configure
                * advanced TLS features, such as root certificate reloading, peer cert custom verification, etc.
+               * We expect only one of {@link AdvancedTlsX509TrustManager#useSystemDefaultTrustCerts()},

Contributor

matthewstevenson88 May 16, 2024

Optional presentation suggestion: Consider structuring the Javadoc as:

AdvancedTlsX509TrustManager is an {@code X509ExtendedTrustManager} that allows users to configure
advanced TLS features, such as root certificate reloading, peer cert custom verification, etc.

For Android users: this class is only supported in API level 24 and above.

We expect only one of {@link AdvancedTlsX509TrustManager#useSystemDefaultTrustCerts()},
{@link AdvancedTlsX509TrustManager#updateTrustCredentials(X509Certificate[])},
 {@link AdvancedTlsX509TrustManager#updateTrustCredentialsFromFile(File, long, TimeUnit,
 ScheduledExecutorService)},
{@link AdvancedTlsX509TrustManager#updateTrustCredentialsFromFile(File)} methods to be called
 after instantiation of this class.

Contributor Author

erm-g May 16, 2024

I like the idea of extra empty LOCs for separation (pushed). But I prefer the current order because of

Overall description
Impl notes (for all users, including Android)
Extra note (for Android users only)

Contributor

matthewstevenson88 May 16, 2024

SG, just an optional suggestion. :)

util/src/main/java/io/grpc/util/AdvancedTlsX509TrustManager.java Outdated

                 /**
                  * Schedules a {@code ScheduledExecutorService} to read trust certificates from a local file path
-                 * periodically, and update the cached trust certs if there is an update.
+                 * periodically, and update the cached trust certs if there is an update. Please make sure to

Contributor

matthewstevenson88 May 16, 2024

micro-nit: s/and update the/and updates the

Contributor Author

erm-g May 16, 2024

2 instances fixed, thank you!

util/src/main/java/io/grpc/util/AdvancedTlsX509TrustManager.java Outdated

               @IgnoreJRERequirement
               public final class AdvancedTlsX509TrustManager extends X509ExtendedTrustManager {
                 private static final Logger log = Logger.getLogger(AdvancedTlsX509TrustManager.class.getName());
+                // Minimum allowed period for refreshing files with credential information.
+                private static final int MINIMUM_REFRESH_PERIOD = 1;

Contributor

matthewstevenson88 May 16, 2024

nit: Prefer using Duration here.

Contributor Author

erm-g May 16, 2024

Same problem with the KeyManager - they use 'period' as a param name (plus it's long + TimeUnit) -

grpc-java/util/src/main/java/io/grpc/util/AdvancedTlsX509TrustManager.java

Line 222 in 8aaace1

    
           public Closeable updateTrustCredentialsFromFile(File trustCertFile, long period, TimeUnit unit,

Let's defer to Eric if I need to refactor all of it.

util/src/test/java/io/grpc/util/AdvancedTlsX509TrustManagerTest.java Outdated

+              @RunWith(JUnit4.class)
+              public class AdvancedTlsX509TrustManagerTest {
+                public static final String CA_PEM_FILE = "ca.pem";

Contributor

matthewstevenson88 May 16, 2024

nit: Constants generally should be private unless we have a need for them to be visible.

Contributor Author

erm-g May 16, 2024

Agreed - nothing in the codebase depends on this const. However this style is in AdvancedTlsTest -

grpc-java/netty/src/test/java/io/grpc/netty/AdvancedTlsTest.java

Line 72 in 8aaace1

public static final String CA_PEM_FILE = "ca.pem";

Let's defer to Eric, I can also refactor the AdvancedTlsTest to make it consistent

Contributor Author

erm-g May 31, 2024

Fixed here and in AdvancedTlsTest (#11139)

util/src/test/java/io/grpc/util/AdvancedTlsX509TrustManagerTest.java

+                }
+                @Test
+                public void credentialSetting() throws Exception {

Contributor

matthewstevenson88 May 16, 2024

Same style nits here RE test structure as in the key manager PR, but we can defer to Eric if you prefer.

erm-g added 4 commits

May 16, 2024 16:39


          restructure of javadoc

2f16e36


          grammar fix

ecff6ee


          fixed <p> tags

c3a0b77


          fixed <p> tags

70eb15b

erm-g requested review from ejona86

May 16, 2024 19:20

erm-g added 5 commits

May 29, 2024 22:41


          Adjust style to KeyManager

b6d069c


          Adjust style to KeyManager

d2050b7


          FakeClock migration

af55922


          Delete TearDown

53b92b5


          Delete unused imports

3adc392

matthewstevenson88 approved these changes

View reviewed changes

Contributor

matthewstevenson88 left a comment

LGTM modulo readability concerns, for which I'll defer to @ejona86.

Member

ejona86 commented May 30, 2024

API review meeting notes:

CERTIFICATE_ONLY_VERIFICATION and INSECURELY_SKIP_ALL_VERIFICATION

Should document that these are dangerous to us, unless also specifying your own cert validation. Yes, one has INSECURELY in its name, but there should be some javadoc.

INSECURELY_SKIP_ALL_VERIFICATION

Mention that any loaded trust certs will be ignored. Yes, that's what it says, but just "those other methods that you use all the time stop doing anything" is helpful to point out.

Add docs to say that after build, no trust certs are loaded. You need to call one of the update/usesystem methods.
Builder needs more docs. For example, to explain that setSslSocketAndEnginePeerVerifier is called in addition to verifying certs as specified by Verification.
Should make clear that it is normal for nothing in the builder needs to be called? That should be the common case. Maybe just improve the AdvancedTlsX509TrustManager javadoc with a code snippet?

The minimum refresh period of 1 minute is enforced.

"enforced" could mean several different things, including "causes an error." Probably want to tweak that to be more clear.

erm-g added 5 commits

May 31, 2024 23:04


          Improved javadoc

3a384f6


          Improved javadoc

8b52b12


          Improved javadoc

c9fd8b0


          Improved javadoc

000e7d8


          Improved javadoc

da84d77

Contributor Author

erm-g commented Jun 1, 2024

API review meeting notes:

CERTIFICATE_ONLY_VERIFICATION and INSECURELY_SKIP_ALL_VERIFICATION

Should document that these are dangerous to us, unless also specifying your own cert validation. Yes, one has INSECURELY in its name, but there should be some javadoc.

INSECURELY_SKIP_ALL_VERIFICATION

Mention that any loaded trust certs will be ignored. Yes, that's what it says, but just "those other methods that you use all the time stop doing anything" is helpful to point out.

Add docs to say that after build, no trust certs are loaded. You need to call one of the update/usesystem methods.

Builder needs more docs. For example, to explain that setSslSocketAndEnginePeerVerifier is called in addition to verifying certs as specified by Verification.

Should make clear that it is normal for nothing in the builder needs to be called? That should be the common case. Maybe just improve the AdvancedTlsX509TrustManager javadoc with a code snippet?

The minimum refresh period of 1 minute is enforced.

"enforced" could mean several different things, including "causes an error." Probably want to tweak that to be more clear.

Done - I also reworded few comments before 'bumping up' to javadoc level. PTAL

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment