Skip to content

Update manuals according to Drivers 5.0 changes #335

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

Merged
merged 9 commits into from
Oct 21, 2022
Merged

Update manuals according to Drivers 5.0 changes #335

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
8bdc62c
Updated Python manual with 5.0 changes, as well as some inevitable `c…
stefano-ottolenghi Oct 17, 2022
16997e1
Bring dotnet manual up to date for v5, plus some splitting away from …
stefano-ottolenghi Oct 20, 2022
f3dcd31
Update Go manual.
stefano-ottolenghi Oct 20, 2022
267a988
Java manual and fixes to async prefixes in dotnet.
stefano-ottolenghi Oct 20, 2022
b32996b
Updated javascript manual.
stefano-ottolenghi Oct 20, 2022
01a5001
Reverting changes to `Connecting to a service` section in `common-con…
stefano-ottolenghi Oct 20, 2022
9106710
Add mentions of `CanBeRetried` methods do Go and Javascript manuals.
stefano-ottolenghi Oct 20, 2022
c2f6ff4
Correct mistake for default value for `TrustedCertificates`.
stefano-ottolenghi Oct 20, 2022
9eb41d7
Extra line breaks.
stefano-ottolenghi Oct 20, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 6 additions & 38 deletions common-content/modules/ROOT/partials/client-applications.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -114,17 +114,7 @@ A connection URI identifies a graph database and how to connect to it.

The *_encryption_* and *_trust_* settings provide detail to how that connection should be secured.

[CAUTION]
====
*There are significant changes to security settings between Neo4j 3.x and Neo4j 4.x*

Please consider the information in this section before upgrading from a previous version.

The https://neo4j.com/docs/migration-guide/current/[Migration Guide] is also a good source of information about changes in functionality.
====

Starting with *Neo4j 4.0*, client-server communication uses only *_unencrypted local connections by default_*.

This is a change from previous versions, which switched on encryption by default, but generated a self-signed certificate out of the box.

When a full certificate is installed, and encryption is enabled on the driver, full certificate checks are carried out (refer to link:/docs/operations-manual/5.0/security/ssl-framework[Operations Manual -> SSL framework]).
Expand All @@ -141,23 +131,6 @@ To connect to *Neo4j Aura*, driver users must *_enable encryption_* and the comp
For more information, see xref:client-applications.adoc#driver-configuration-examples[Examples] below.
====

# tag::default-security-changes[]

.Changes in default security settings between 3.x and 4.x
[options="header"]
|===
| Setting | Neo4j 4.x | Neo4j 3.x (Drivers 1.x)
| Bundled certificate | none | auto-generated, self-signed
| Driver encryption | off | on
| Bolt interface | localhost |localhost
| Certificate expiry check | on |on
| Certificate CA check | on | off
| Certificate hostname check | on | off
|===

# end::default-security-changes[]


[[initial-address-resolution]]
=== Initial address resolution

Expand Down Expand Up @@ -1312,7 +1285,7 @@ Specify a custom server address resolver used by the routing driver to resolve t

Specify whether to use an encrypted connection between the driver and server.
+
*Default:* None
*Default:* False

# end::configuration-Encryption[]

Expand Down Expand Up @@ -1486,19 +1459,14 @@ include::{python-examples}/test_config_max_retry_time_example.py[tags=config-max

# tag::configuration-TrustStrategy[]

`TrustStrategy`::
`TrustedCertificates`::
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The example in this renamed section still uses TrustStrategy

I guess if this is an error, it's not a documentation fix, and as such shouldn't delay this PR.

Screenshot 2022-10-20 at 14 26 18

Copy link
Contributor Author

@stefano-ottolenghi stefano-ottolenghi Oct 20, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

tl;dr - It is a wrong label anyway, I can restore it to TrustStrategy if we want to avoid a pointless diff.

Right, so this is an annoying bit that basically has to do with the fact that different drivers have different option names, so that TrustedCertificates (or TrustStrategy, for that matter) is inaccurate for them all. This problem applies to all configuration options in that page.

What happened is that I started reviewing from the Python manual, which calls is trusted_certificates, so I renamed the section to TrustedCertificates - still wrong, but at least with the right words. Then I discovered that each language has it different (for ex, in the .NET screenshot here, it is WithTrustManager), so the correction is pointless. IIRC the Java driver is the only one having TrustStrategy, which would explain at least historically why that section had that name. Then Drivers diverged and we kept the same naming for all of them.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

maybe this is a good case for bringing this content into the individual language folders, and out of the common-content folder?

I think that could be done in another PR though, and shouldn't hold us up on this PR.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I would defer this to the re-design of the manuals :)


Specify how to determine the authenticity of encryption certificates provided by the Neo4j instance that you are connecting to.
There are three choices as to which strategy to use:

* `TRUST_SYSTEM_CA_SIGNED_CERTIFICATES` - Accept any certificate that can be verified against the system store.

* `TRUST_CUSTOM_CA_SIGNED_CERTIFICATES` - Accept any certificate that can be verified against a custom CA.

* `TRUST_ALL_CERTIFICATES` - Accept any certificate provided by the server, regardless of CA chain. *We do not recommend using this setting for production environments.*
Specify how to determine the authenticity of encryption certificates provided by the Neo4j instance that you are connecting to.
If encryption is disabled, this option has no effect.

+
*Default:* `TRUST_SYSTEM_CA_SIGNED_CERTIFICATES` (Note - only when encryption is enabled)

Possible values are:

# end::configuration-TrustStrategy[]

Expand Down
3 changes: 3 additions & 0 deletions common-content/modules/ROOT/partials/session-api.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -98,8 +98,11 @@ To that end, transaction functions can return values but these should be derived
*_When a transaction fails, the driver retry logic is invoked_*.
For several failure cases, the transaction can be immediately retried against a different server.
These cases include connection issues, server role changes (e.g. leadership elections) and transient errors.

====



# end::simple-transaction-fn[]

[.tabbed-example]
Expand Down
137 changes: 12 additions & 125 deletions dotnet-manual/modules/ROOT/pages/client-applications.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -102,11 +102,11 @@ include::{common-partial}/client-applications.adoc[tag=examples-pt2]
.Connecting to a service
The tables below illustrate examples of how to connect to a service with routing:

.Neo4j Aura, secured with full certificate
.Neo4j Aura or Neo4j >= 4.x, secured with full certificate
[cols="<15s,<85a"]
|===
| Product
| Neo4j Aura
| Neo4j Aura, Neo4j >= 4.x

| Security
| Secured with full certificate
Expand All @@ -118,24 +118,15 @@ The tables below illustrate examples of how to connect to a service with routing
GraphDatabase.Driver("neo4j+s://graph.example.com:7687", auth)
----

If you do not have at least the .NET Driver 4.0.1 patch installed, you will need this snippet instead:

[source, csharp, indent=0]
----
String uri = "neo4j://graph.example.com:7687";
IDriver driver = GraphDatabase.Driver(uri, auth,
o => o.WithEncryptionLevel(EncryptionLevel.Encrypted));
----

| Comments
| This is the default (and only option) for Neo4j Aura.
|===

.Neo4j 4.x, unsecured
.Neo4j >= 4.x, unsecured
[cols="<15s,<85a"]
|===
| Product
| Neo4j 4.x
| Neo4j >= 4.x

| Security
| Unsecured
Expand All @@ -148,40 +139,14 @@ GraphDatabase.Driver("neo4j://graph.example.com:7687", auth);
----

| Comments
| This is the default for Neo4j 4.x series
| This is the default for Neo4j >= 4.x series
|===

.Neo4j 4.x, secured with full certificate
.Neo4j >= 4.x, secured with self-signed certificate
[cols="<15s,<85a"]
|===
| Product
| Neo4j 4.x

| Security
| Secured with full certificate

| Code snippet
|
[source, csharp, indent=0]
----
GraphDatabase.Driver("neo4j+s://graph.example.com:7687", auth)
----

If you do not have at least the .NET Driver 4.0.1 patch installed, you will need this snippet instead:

[source, csharp, indent=0]
----
String uri = "neo4j://graph.example.com:7687";
IDriver driver = GraphDatabase.Driver(uri, auth,
o => o.WithEncryptionLevel(EncryptionLevel.Encrypted));
----
|===

.Neo4j 4.x, secured with self-signed certificate
[cols="<15s,<85a"]
|===
| Product
| Neo4j 4.x
| Neo4j >= 4.x

| Security
| Secured with self-signed certificate
Expand All @@ -192,89 +157,6 @@ IDriver driver = GraphDatabase.Driver(uri, auth,
----
GraphDatabase.Driver("neo4j+ssc://graph.example.com:7687", auth)
----

If you do not have at least the .NET Driver 4.0.1 patch installed, you will need this snippet instead:

[source, csharp, indent=0]
----
String uri = "neo4j://graph.example.com:7687";
IDriver driver = GraphDatabase.Driver(uri, auth,
o => o.WithEncryptionLevel(EncryptionLevel.Encrypted)
.WithTrustManager(TrustManager.CreateInsecure()));
----
|===

.Neo4j 3.x, secured with full certificate
[cols="<15s,<85a"]
|===
| Product
| Neo4j 3.x

| Security
| Secured with full certificate

| Code snippet
|
[source, csharp, indent=0]
----
GraphDatabase.Driver("neo4j+s://graph.example.com:7687", auth)
----

If you do not have at least the .NET Driver 4.0.1 patch installed, you will need this snippet instead:

[source, csharp, indent=0]
----
String uri = "neo4j://graph.example.com:7687";
IDriver driver = GraphDatabase.Driver(uri, auth,
o => o.WithEncryptionLevel(EncryptionLevel.Encrypted));
----
|===

.Neo4j 3.x, secured with self-signed certificate
[cols="<15s,<85a"]
|===
| Product
| Neo4j 3.x

| Security
| Secured with self-signed certificate

| Code snippet
|
[source, csharp, indent=0]
----
GraphDatabase.Driver("neo4j+ssc://graph.example.com:7687", auth)
----

If you do not have at least the .NET Driver 4.0.1 patch installed, you will need this snippet instead:

[source, csharp, indent=0]
----
String uri = "neo4j://graph.example.com:7687";
IDriver driver = GraphDatabase.Driver(uri, auth,
o => o.WithEncryptionLevel(EncryptionLevel.Encrypted)
.WithTrustManager(TrustManager.CreateInsecure()));
----

| Comments
| This is the default for Neo4j 3.x series
|===

.Neo4j 3.x, unsecured
[cols="<15s,<85a"]
|===
| Product
| Neo4j 3.x

| Security
| Unsecured

| Code snippet
|
[source, csharp, indent=0]
----
GraphDatabase.Driver("neo4j://graph.example.com:7687", auth);
----
|===

[NOTE]
Expand Down Expand Up @@ -430,6 +312,11 @@ include::{dotnet-examples}/Examples.cs[tags=config-max-retry-time]
======

include::{common-partial}/client-applications.adoc[tag=configuration-TrustStrategy]

* `TrustManager.CreateChainTrust()` - *[Default]* Accept any certificate that can be verified against the system store.
* `TrustManager.CreateCertTrust(new []{"/path/ca1.crt", "/path/ca2.crt"})` - Accept certificates at specified paths.
* `TrustManager.CreateInsecure()` - Accept any certificate, including self-signed ones. *Not recommended for production environments.*

+
.Configure trusted certificates
======
Expand Down
2 changes: 2 additions & 0 deletions dotnet-manual/modules/ROOT/pages/cypher-workflow.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -129,3 +129,5 @@ Inbound conversion is carried out using http://cldr.unicode.org/development/deve
== Exceptions and error handling

include::{common-partial}/cypher-workflow.adoc[tag=exceptions-errors]

The exception property `CanBeRetried` gives insights into whether a further attempt might be successful.
9 changes: 9 additions & 0 deletions dotnet-manual/modules/ROOT/pages/session-api.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,9 @@ See xref:session-api.adoc#dotnet-driver-session-configuration[Session configurat

include::{common-partial}/session-api.adoc[tag=simple-transaction-fn]

[CAUTION]
The methods `ExecuteRead` and `ExecuteWrite` have replaced `ReadTransaction` and `WriteTransaction`, which are deprecated in version 5.x and will be removed in version 6.0.

[source, csharp, indent=0]
----
include::{dotnet-examples}/Examples.cs[tags=transaction-function]
Expand Down Expand Up @@ -90,6 +93,9 @@ See xref:session-api.adoc#dotnet-driver-session-configuration[Session configurat

include::{common-partial}/session-api.adoc[tag=async-transaction-fn]

[CAUTION]
The methods `ExecuteReadAsync` and `ExecuteWriteAsync` have replaced `ReadTransactionAsync` and `WriteTransactionAsync`, which are deprecated in version 5.x and will be removed in version 6.0.

[source, csharp, indent=0]
----
include::{dotnet-examples}/ExamplesAsync.cs[tags=async-transaction-function]
Expand Down Expand Up @@ -150,6 +156,9 @@ include::{common-partial}/session-api.adoc[tag=rx-lifecycle]

include::{common-partial}/session-api.adoc[tag=rx-transaction-fn]

[CAUTION]
The methods `ExecuteRead` and `ExecuteWrite` have replaced `ReadTransaction` and `WriteTransaction`, which are deprecated in version 5.x and will be removed in version 6.0.

[source, csharp, indent=0]
----
include::{dotnet-examples}/ExamplesRx.cs[tags=rx-transaction-function]
Expand Down
Loading