Skip to content

Commit 91f0f0f

Browse files
rashtaoSimran-B
rashtao
and
Simran-B
authored
[DE-1055] Java Driver: added new SSL configuration properties (#746)
* Java Driver: added new SSL configuration properties * Review --------- Co-authored-by: Simran Spiller <[email protected]>
1 parent d15a10f commit 91f0f0f

File tree

3 files changed

+198
-129
lines changed

3 files changed

+198
-129
lines changed

‎site/content/3.11/develop/drivers/java/reference-version-7/driver-setup.md‎

Lines changed: 64 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -72,27 +72,30 @@ Here are examples to integrate configuration properties from different sources:
7272

7373
`ArangoDB.Builder` has the following configuration methods:
7474

75-
- `host(String, int)`: adds a host (hostname and port) to connect to, multiple hosts can be added
76-
- `protocol(Protocol)`: communication protocol, possible values are: `VST`, `HTTP_JSON`, `HTTP_VPACK`, `HTTP2_JSON`, `HTTP2_VPACK`, (default: `HTTP2_JSON`)
77-
- `timeout(Integer)`: connection and request timeout (ms), (default `0`, no timeout)
78-
- `user(String)`: username for authentication, (default: `root`)
79-
- `password(String)`: password for authentication
75+
- `host(String, int)`: Adds a host (hostname and port) to connect to, multiple hosts can be added
76+
- `protocol(Protocol)`: Communication protocol, possible values are: `VST`, `HTTP_JSON`, `HTTP_VPACK`, `HTTP2_JSON`, `HTTP2_VPACK`, (default: `HTTP2_JSON`)
77+
- `timeout(Integer)`: Connection and request timeout (ms), (default `0`, no timeout)
78+
- `user(String)`: Username for authentication, (default: `root`)
79+
- `password(String)`: Password for authentication
8080
- `jwt(String)`: JWT for authentication
81-
- `useSsl(Boolean)`: use SSL connection, (default: `false`)
81+
- `useSsl(Boolean)`: Use SSL connection, (default: `false`)
8282
- `sslContext(SSLContext)`: SSL context
83-
- `verifyHost(Boolean)`: enable hostname verification, (HTTP only, default: `true`)
83+
- `sslCertValue(String)`: SSL certificate value as Base64-encoded String
84+
- `sslAlgorithm(String)`: Name of the SSL Trust manager algorithm (default: `SunX509`)
85+
- `sslProtocol(String)`: Name of the SSLContext protocol (default: `TLS`)
86+
- `verifyHost(Boolean)`: Enable hostname verification, (HTTP only, default: `true`)
8487
- `chunkSize(Integer)`: VST chunk size in bytes, (default: `30000`)
85-
- `maxConnections(Integer)`: max number of connections per host, (default: 1 VST, 1 HTTP/2, 20 HTTP/1.1)
86-
- `connectionTtl(Long)`: time to live of an inactive connection (ms), (default: `30_000` for HTTP, no TTL for VST)
88+
- `maxConnections(Integer)`: Max number of connections per host, (default: 1 VST, 1 HTTP/2, 20 HTTP/1.1)
89+
- `connectionTtl(Long)`: Time to live of an inactive connection (ms), (default: `30_000` for HTTP, no TTL for VST)
8790
- `keepAliveInterval(Integer)`: VST keep-alive interval (s), (default: no keep-alive probes will be sent)
88-
- `acquireHostList(Boolean)`: acquire the list of available hosts, (default: `false`)
89-
- `acquireHostListInterval(Integer)`: acquireHostList interval (ms), (default: `3_600_000`, 1 hour)
90-
- `loadBalancingStrategy(LoadBalancingStrategy)`: load balancing strategy, possible values are: `NONE`, `ROUND_ROBIN`, `ONE_RANDOM`, (default: `NONE`)
91-
- `responseQueueTimeSamples(Integer)`: amount of samples kept for queue time metrics, (default: `10`)
92-
- `serde(ArangoSerde)`: serde to serialize and deserialize user-data
93-
- `serdeProviderClass(Class<? extends ArangoSerdeProvider>)`: serde provider to be used to instantiate the user-data serde
94-
- `protocolConfig(ProtocolConfig)`: configuration specific for the used protocol provider implementation
95-
- `pipelining(Boolean):`: use HTTP pipelining, (`HTTP/1.1` only, default `false`)
91+
- `acquireHostList(Boolean)`: Acquire the list of available hosts, (default: `false`)
92+
- `acquireHostListInterval(Integer)`: The interval for acquiring the host list (ms), (default: `3_600_000`, 1 hour)
93+
- `loadBalancingStrategy(LoadBalancingStrategy)`: Load balancing strategy, possible values are: `NONE`, `ROUND_ROBIN`, `ONE_RANDOM`, (default: `NONE`)
94+
- `responseQueueTimeSamples(Integer)`: Amount of samples kept for queue time metrics, (default: `10`)
95+
- `serde(ArangoSerde)`: Serde to serialize and deserialize user-data
96+
- `serdeProviderClass(Class<? extends ArangoSerdeProvider>)`: Serde provider to be used to instantiate the user-data serde
97+
- `protocolConfig(ProtocolConfig)`: Configuration specific for the used protocol provider implementation
98+
- `pipelining(Boolean):`: Use HTTP pipelining, (`HTTP/1.1` only, default `false`)
9699

97100
### HTTP Protocol Provider Configuration
98101

@@ -133,6 +136,9 @@ The properties read are:
133136
- `password`
134137
- `jwt`
135138
- `useSsl`
139+
- `sslCertValue`: SSL certificate as Base64-encoded string
140+
- `sslAlgorithm`: SSL trust manager algorithm (default: `SunX509`)
141+
- `sslProtocol`: SSLContext protocol (default: `TLS`)
136142
- `verifyHost`
137143
- `chunkSize`
138144
- `maxConnections`
@@ -147,8 +153,9 @@ The properties read are:
147153

148154
## SSL
149155

150-
To use SSL, you have to set the configuration `useSsl` to `true` and set a `SSLContext`
151-
(see [example code](https://github.com/arangodb/arangodb-java-driver/blob/main/test-functional/src/test-ssl/java/com/arangodb/SslExampleTest.java)).
156+
To use SSL, you have to set the configuration `useSsl` to `true`.
157+
By default, the driver uses the default `SSLContext`.
158+
To change this, you can provide the `SSLContext` instance to use:
152159

153160
```java
154161
ArangoDB arangoDB = new ArangoDB.Builder()
@@ -157,6 +164,22 @@ ArangoDB arangoDB = new ArangoDB.Builder()
157164
.build();
158165
```
159166

167+
Alternatively, the driver can create a new `SSLContext` using the provided
168+
configuration. In this case, it is required to set the configuration `sslCertValue`
169+
with the SSL certificate value as Base64-encoded String:
170+
171+
```java
172+
ArangoDB arangoDB = new ArangoDB.Builder()
173+
.useSsl(true)
174+
.sslCertValue("<certificate>") // SSL certificate as Base64-encoded String
175+
.sslAlgorithm("SunX509") // SSL Trust manager algorithm (optional, default: SunX509)
176+
.sslProtocol("TLS") // SSLContext protocol (optional, default: TLS)
177+
.build();
178+
```
179+
180+
See the [example code](https://github.com/arangodb/arangodb-java-driver/blob/main/test-functional/src/test-ssl/java/com/arangodb/SslExampleTest.java)
181+
for more details on SSL configuration.
182+
160183
## Connection Pooling
161184

162185
The driver keeps a pool of connections for each host, the max amount of
@@ -194,9 +217,9 @@ To use this feature just call the method `host(String, int)` multiple times.
194217

195218
```java
196219
ArangoDB arangoDB = new ArangoDB.Builder()
197-
.host("host1", 8529)
198-
.host("host2", 8529)
199-
.build();
220+
.host("host1", 8529)
221+
.host("host2", 8529)
222+
.build();
200223
```
201224

202225
The driver is also able to acquire a list of known hosts in a cluster. For this the driver has
@@ -206,8 +229,8 @@ feature:
206229

207230
```java
208231
ArangoDB arangoDB = new ArangoDB.Builder()
209-
.acquireHostList(true)
210-
.build();
232+
.acquireHostList(true)
233+
.build();
211234
```
212235

213236
## Load Balancing
@@ -221,8 +244,8 @@ host than the request before.
221244

222245
```java
223246
ArangoDB arangoDB = new ArangoDB.Builder()
224-
.loadBalancingStrategy(LoadBalancingStrategy.ROUND_ROBIN)
225-
.build();
247+
.loadBalancingStrategy(LoadBalancingStrategy.ROUND_ROBIN)
248+
.build();
226249
```
227250

228251
The second load balancing strategy picks a random host from host list
@@ -231,8 +254,8 @@ connection is open.
231254

232255
```java
233256
ArangoDB arangoDB = new ArangoDB.Builder()
234-
.loadBalancingStrategy(LoadBalancingStrategy.ONE_RANDOM)
235-
.build();
257+
.loadBalancingStrategy(LoadBalancingStrategy.ONE_RANDOM)
258+
.build();
236259
```
237260

238261
## Active Failover
@@ -255,8 +278,8 @@ The driver supports setting a TTL (time to live) for connections:
255278

256279
```java
257280
ArangoDB arango = new ArangoDB.Builder()
258-
.connectionTtl(5 * 60 * 1000) // ms
259-
.build();
281+
.connectionTtl(5 * 60 * 1000) // ms
282+
.build();
260283
```
261284

262285
In this example, inactive connections are closed after 5 minutes.
@@ -269,21 +292,21 @@ If set to `null`, no automatic connection closure is performed.
269292

270293
The driver allows configuring the underlying Vert.x WebClient to work
271294
with HTTP proxies. The configuration is specific to the HTTP protocol
272-
and uses the `io.vertx.core.net.ProxyOptions` class of
295+
and uses the `io.vertx.core.net.ProxyOptions` class of
273296
[Vert.x Core](https://www.javadoc.io/doc/io.vertx/vertx-core/4.5.7/io/vertx/core/net/ProxyOptions.html):
274297

275298
```java
276299
ArangoDB arango = new ArangoDB.Builder()
277-
// ...
278-
.protocolConfig(HttpProtocolConfig.builder()
279-
.proxyOptions(new ProxyOptions()
280-
.setType(ProxyType.HTTP)
281-
.setHost("172.28.0.1")
282-
.setPort(8888)
283-
.setUsername("user")
284-
.setPassword("password"))
285-
.build())
286-
.build();
300+
// ...
301+
.protocolConfig(HttpProtocolConfig.builder()
302+
.proxyOptions(new ProxyOptions()
303+
.setType(ProxyType.HTTP)
304+
.setHost("172.28.0.1")
305+
.setPort(8888)
306+
.setUsername("user")
307+
.setPassword("password"))
308+
.build())
309+
.build();
287310
```
288311

289312
## VST Keep-Alive

‎site/content/3.12/develop/drivers/java/reference-version-7/driver-setup.md‎

Lines changed: 67 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -72,28 +72,31 @@ Here are examples to integrate configuration properties from different sources:
7272

7373
`ArangoDB.Builder` has the following configuration methods:
7474

75-
- `host(String, int)`: adds a host (hostname and port) to connect to, multiple hosts can be added
76-
- `protocol(Protocol)`: communication protocol, possible values are: `HTTP_JSON`, `HTTP_VPACK`, `HTTP2_JSON`, `HTTP2_VPACK`, `VST` (unsupported from ArangoDB v3.12 onward), (default: `HTTP2_JSON`)
77-
- `timeout(Integer)`: connection and request timeout (ms), (default `0`, no timeout)
78-
- `user(String)`: username for authentication, (default: `root`)
79-
- `password(String)`: password for authentication
75+
- `host(String, int)`: Adds a host (hostname and port) to connect to, multiple hosts can be added
76+
- `protocol(Protocol)`: Communication protocol, possible values are: `HTTP_JSON`, `HTTP_VPACK`, `HTTP2_JSON`, `HTTP2_VPACK`, `VST` (unsupported from ArangoDB v3.12 onward), (default: `HTTP2_JSON`)
77+
- `timeout(Integer)`: Connection and request timeout (ms), (default `0`, no timeout)
78+
- `user(String)`: Username for authentication, (default: `root`)
79+
- `password(String)`: Password for authentication
8080
- `jwt(String)`: JWT for authentication
81-
- `useSsl(Boolean)`: use SSL connection, (default: `false`)
81+
- `useSsl(Boolean)`: Use SSL connection, (default: `false`)
8282
- `sslContext(SSLContext)`: SSL context
83-
- `verifyHost(Boolean)`: enable hostname verification, (HTTP only, default: `true`)
84-
- `maxConnections(Integer)`: max number of connections per host, (default: `1` for `HTTP/2`, `20` for `HTTP/1.1`)
85-
- `connectionTtl(Long)`: time to live of an inactive connection (ms), (default: `30_000`)
86-
- `acquireHostList(Boolean)`: acquire the list of available hosts, (default: `false`)
87-
- `acquireHostListInterval(Integer)`: acquireHostList interval (ms), (default: `3_600_000`, 1 hour)
88-
- `loadBalancingStrategy(LoadBalancingStrategy)`: load balancing strategy, possible values are: `NONE`, `ROUND_ROBIN`, `ONE_RANDOM`, (default: `NONE`)
89-
- `responseQueueTimeSamples(Integer)`: amount of samples kept for queue time metrics, (default: `10`)
90-
- `compression(Compression)`: the `content-encoding` and `accept-encoding` to use for HTTP requests, possible values are: `NONE`, `DEFLATE`, `GZIP`, (default: `NONE`)
91-
- `compressionThreshold(Integer)`: the minimum HTTP request body size (in bytes) to trigger compression, (default: `1024`)
92-
- `compressionLevel`: compression level between 0 and 9, (default: `6`)
93-
- `serde(ArangoSerde)`: serde to serialize and deserialize user-data
94-
- `serdeProviderClass(Class<? extends ArangoSerdeProvider>)`: serde provider to be used to instantiate the user-data serde
95-
- `protocolConfig(ProtocolConfig)`: configuration specific for the used protocol provider implementation
96-
- `pipelining(Boolean):`: use HTTP pipelining, (`HTTP/1.1` only, default `false`)
83+
- `sslCertValue(String)`: SSL certificate value as Base64-encoded String
84+
- `sslAlgorithm(String)`: Name of the SSL Trust manager algorithm (default: `SunX509`)
85+
- `sslProtocol(String)`: Name of the SSLContext protocol (default: `TLS`)
86+
- `verifyHost(Boolean)`: Enable hostname verification, (HTTP only, default: `true`)
87+
- `maxConnections(Integer)`: Max number of connections per host, (default: `1` for `HTTP/2`, `20` for `HTTP/1.1`)
88+
- `connectionTtl(Long)`: Time to live of an inactive connection (ms), (default: `30_000`)
89+
- `acquireHostList(Boolean)`: Acquire the list of available hosts, (default: `false`)
90+
- `acquireHostListInterval(Integer)`: The interval for acquiring the host list (ms), (default: `3_600_000`, 1 hour)
91+
- `loadBalancingStrategy(LoadBalancingStrategy)`: Load balancing strategy, possible values are: `NONE`, `ROUND_ROBIN`, `ONE_RANDOM`, (default: `NONE`)
92+
- `responseQueueTimeSamples(Integer)`: Amount of samples kept for queue time metrics, (default: `10`)
93+
- `compression(Compression)`: The `content-encoding` and `accept-encoding` to use for HTTP requests, possible values are: `NONE`, `DEFLATE`, `GZIP`, (default: `NONE`)
94+
- `compressionThreshold(Integer)`: The minimum HTTP request body size (in bytes) to trigger compression, (default: `1024`)
95+
- `compressionLevel`: Compression level between 0 and 9, (default: `6`)
96+
- `serde(ArangoSerde)`: Serde to serialize and deserialize user-data
97+
- `serdeProviderClass(Class<? extends ArangoSerdeProvider>)`: Serde provider to be used to instantiate the user-data serde
98+
- `protocolConfig(ProtocolConfig)`: Configuration specific for the used protocol provider implementation
99+
- `pipelining(Boolean):`: Use HTTP pipelining, (`HTTP/1.1` only, default `false`)
97100

98101
### HTTP Protocol Provider Configuration
99102

@@ -134,6 +137,9 @@ The properties read are:
134137
- `password`
135138
- `jwt`
136139
- `useSsl`
140+
- `sslCertValue`: SSL certificate as Base64-encoded string
141+
- `sslAlgorithm`: SSL trust manager algorithm (default: `SunX509`)
142+
- `sslProtocol`: SSLContext protocol (default: `TLS`)
137143
- `verifyHost`
138144
- `chunkSize`
139145
- `maxConnections`
@@ -151,8 +157,9 @@ The properties read are:
151157

152158
## SSL
153159

154-
To use SSL, you have to set the configuration `useSsl` to `true` and set a `SSLContext`
155-
(see [example code](https://github.com/arangodb/arangodb-java-driver/blob/main/test-functional/src/test-ssl/java/com/arangodb/SslExampleTest.java)).
160+
To use SSL, you have to set the configuration `useSsl` to `true`.
161+
By default, the driver uses the default `SSLContext`.
162+
To change this, you can provide the `SSLContext` instance to use:
156163

157164
```java
158165
ArangoDB arangoDB = new ArangoDB.Builder()
@@ -161,6 +168,22 @@ ArangoDB arangoDB = new ArangoDB.Builder()
161168
.build();
162169
```
163170

171+
Alternatively, the driver can create a new `SSLContext` using the provided
172+
configuration. In this case, it is required to set the configuration `sslCertValue`
173+
with the SSL certificate value as Base64-encoded String:
174+
175+
```java
176+
ArangoDB arangoDB = new ArangoDB.Builder()
177+
.useSsl(true)
178+
.sslCertValue("<certificate>") // SSL certificate as Base64-encoded String
179+
.sslAlgorithm("SunX509") // SSL Trust manager algorithm (optional, default: SunX509)
180+
.sslProtocol("TLS") // SSLContext protocol (optional, default: TLS)
181+
.build();
182+
```
183+
184+
See the [example code](https://github.com/arangodb/arangodb-java-driver/blob/main/test-functional/src/test-ssl/java/com/arangodb/SslExampleTest.java)
185+
for more details on SSL configuration.
186+
164187
## Connection Pooling
165188

166189
The driver keeps a pool of connections for each host, the max amount of
@@ -198,9 +221,9 @@ To use this feature just call the method `host(String, int)` multiple times.
198221

199222
```java
200223
ArangoDB arangoDB = new ArangoDB.Builder()
201-
.host("host1", 8529)
202-
.host("host2", 8529)
203-
.build();
224+
.host("host1", 8529)
225+
.host("host2", 8529)
226+
.build();
204227
```
205228

206229
The driver is also able to acquire a list of known hosts in a cluster. For this the driver has
@@ -210,8 +233,8 @@ feature:
210233

211234
```java
212235
ArangoDB arangoDB = new ArangoDB.Builder()
213-
.acquireHostList(true)
214-
.build();
236+
.acquireHostList(true)
237+
.build();
215238
```
216239

217240
## Load Balancing
@@ -225,8 +248,8 @@ host than the request before.
225248

226249
```java
227250
ArangoDB arangoDB = new ArangoDB.Builder()
228-
.loadBalancingStrategy(LoadBalancingStrategy.ROUND_ROBIN)
229-
.build();
251+
.loadBalancingStrategy(LoadBalancingStrategy.ROUND_ROBIN)
252+
.build();
230253
```
231254

232255
The second load balancing strategy picks a random host from host list
@@ -235,8 +258,8 @@ connection is open.
235258

236259
```java
237260
ArangoDB arangoDB = new ArangoDB.Builder()
238-
.loadBalancingStrategy(LoadBalancingStrategy.ONE_RANDOM)
239-
.build();
261+
.loadBalancingStrategy(LoadBalancingStrategy.ONE_RANDOM)
262+
.build();
240263
```
241264

242265
## Connection time to live
@@ -245,8 +268,8 @@ The driver supports setting a TTL (time to live) for connections:
245268

246269
```java
247270
ArangoDB arango = new ArangoDB.Builder()
248-
.connectionTtl(5 * 60 * 1000) // ms
249-
.build();
271+
.connectionTtl(5 * 60 * 1000) // ms
272+
.build();
250273
```
251274

252275
In this example, inactive connections are closed after 5 minutes.
@@ -259,19 +282,19 @@ If set to `null`, no automatic connection closure is performed.
259282

260283
The driver allows configuring the underlying Vert.x WebClient to work
261284
with HTTP proxies. The configuration is specific to the HTTP protocol
262-
and uses the `io.vertx.core.net.ProxyOptions` class of
285+
and uses the `io.vertx.core.net.ProxyOptions` class of
263286
[Vert.x Core](https://www.javadoc.io/doc/io.vertx/vertx-core/4.5.7/io/vertx/core/net/ProxyOptions.html):
264287

265288
```java
266289
ArangoDB arango = new ArangoDB.Builder()
267-
// ...
268-
.protocolConfig(HttpProtocolConfig.builder()
269-
.proxyOptions(new ProxyOptions()
270-
.setType(ProxyType.HTTP)
271-
.setHost("172.28.0.1")
272-
.setPort(8888)
273-
.setUsername("user")
274-
.setPassword("password"))
275-
.build())
276-
.build();
290+
// ...
291+
.protocolConfig(HttpProtocolConfig.builder()
292+
.proxyOptions(new ProxyOptions()
293+
.setType(ProxyType.HTTP)
294+
.setHost("172.28.0.1")
295+
.setPort(8888)
296+
.setUsername("user")
297+
.setPassword("password"))
298+
.build())
299+
.build();
277300
```

0 commit comments

Comments
 (0)