You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: Documentation/MATLABInterface.md
+89-24Lines changed: 89 additions & 24 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -45,8 +45,10 @@ of the `rabbitmq.ConnectorProperties` class or using YAML configuration files.
45
45
*Default:* Default `rabbitmq.Credentials`
46
46
:routingkey: Routing key to subscribe to or poll on - only used for Consumer, when working with Producer the routing key is specified on a per message basis when publishing a message.\
47
47
*Default:*``"test-topic"``
48
+
:sslcontext: SSL/TLS Configuration. Leave empty if the AMQP connection does not use SSL.\
:client: Client SSL Configuration. Required to be configured if the RabbitMQ server requires client certificates. Leave unset if the connection is SSL secured but without client certificates.\
:truststore: Location of the trust store containing the server certificate (chain) and/or trusted root CA(s).
107
+
108
+
:passphrase: Passphrase/password of the trust store.
109
+
110
+
:type: Type of trust store\
111
+
*Default:*`"JKS"`
112
+
113
+
:hostnameVerification: Whether or not hostname verification is enabled. Generally should be left at its default `true`. Only temporarily disable this when debugging SSL/TLS connection issues.\
114
+
*Default:*`true`
115
+
116
+
**rabbitmq.KeyManagerProperties**
117
+
118
+
:keystore: Location of the keystore containing the client certificate and corresponding private key.
119
+
120
+
:passphrase: Passphrase/password of the keystore.
121
+
122
+
:type: Type of keystore.\
123
+
*Default:*`"PKCS12"`
124
+
91
125
Setting properties values can be done through traditional MATLAB class syntax:
92
126
93
127
```matlab
@@ -142,34 +176,53 @@ configuration file for the MATLAB Production Server interface:
142
176
# Messaging connection and routing properties
143
177
messageQueue:
144
178
queue:
145
-
name: RabbitMQ # Name of the Queue on RabbitMQ Server
client: # Client Certificate Configuration. Omit this section entirely if your server does not require client certificates
209
+
keystore: /some/location # Location of the keystore containing client certificate and private key
210
+
passphrase: supersecret # Passphrase/password of the keystore
211
+
type: PKCS12 # Type of keystore
167
212
```
168
213
169
214
```{note}
170
215
The `arguments` option can be omitted entirely for both `queue` and `exchange` if it is not necessary to set additional arguments. There is no fixed set of arguments which can be added and the entered argument names are not checked by the interface; they are passed on the server as-is. Check the RabbitMQ documentation to learn more about which exact arguments can be configured.
171
216
```
172
217
218
+
```{note}
219
+
The `sslcontext` section is omitted entirely if not working with an SSL secured endpoint. If working with an SSL secured endpoint, the `sslcontext` section must be added and the `server` section must be configured. The `client` section is optional; it is needed if your server requires client certificates but is omitted when client certificates are not required/used.
220
+
```
221
+
222
+
#### SSL/TLS Configuration
223
+
224
+
More details about working with SSL/TLS secured channels can be found in [](./SSLTLS.md).
225
+
173
226
### RabbitMQ Producer for publishing messages `rabbitmq.Producer`
174
227
To work with `rabbitmq.Producer` in MATLAB, first create an instance with
175
228
`rabbitmq.ConnectorProperties` or configuration YAML-file as input:
@@ -189,6 +242,18 @@ message as input:
189
242
producer.publish('my-routing-key','Hello World');
190
243
```
191
244
245
+
And to send a message with headers use `publishWithHeaders` where headers are
246
+
specified as a cell-array with pairs of values where the first value is the header
247
+
name and the second value is the header value; repeat to set multiple headers.
Copy file name to clipboardExpand all lines: Documentation/MessageBroker.md
+45-30Lines changed: 45 additions & 30 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -122,45 +122,60 @@ the options to match your configuration.
122
122
The `arguments` for `queue` and `exchange` will likely have to be removed, they are not often used and shown here mainly for illustrative purposes to show *where* these can be added *if* they are needed. There is no fixed set of arguments which can be added and argument names are not verified by `MessageBroker`; they are send to the server as-is. Check the RabbitMQ documentation to learn more about the argument its supports.
123
123
```
124
124
125
+
```{note}
126
+
The `sslcontext` section should be omitted entirely if the amqp channel is not SSL/TLS secured at all. If the channel is SSL/TLS secured, the section must be present and the `server` section must be configured. The `client` section is optional; it must be configured if the server requires client certificates but is omitted if it does not. Also see [](./SSLTLS.md) to learn more about the SSL/TLS configuration.
127
+
```
128
+
125
129
```yaml
126
130
# MATLAB Production Server connection properties
127
131
mps:
128
-
protocol: http # Protocol used by the MPS Instance
129
-
host: localhost # Hostname or IP of the MPS Instance
130
-
port: 9910 # Port the MPS Instance runs on
131
-
archive: demo # Name of the CTF containing the function which
132
-
# is to be called on MPS when a message received
133
-
function: MPSreceive # Function inside the archive which is to be called
134
-
timeoutms: 120000 # Timeout on the request to MATLAB Production Server
135
-
# MessageBroker will log an error if the request
136
-
# to MATLAB Production Server did not complete within
137
-
# this time
132
+
protocol: http # Protocol used by the MPS Instance
133
+
host: localhost # Hostname or IP of the MPS Instance
134
+
port: 9910 # Port the MPS Instance runs on
135
+
archive: demo # Name of the CTF containing the function which
136
+
# is to be called on MPS when a message received
137
+
function: MPSreceive # Function inside the archive which is to be called
138
+
timeoutms: 120000 # Timeout on the request to MATLAB Production Server
139
+
# MessageBroker will log an error if the request
140
+
# to MATLAB Production Server did not complete within
141
+
# this time
138
142
139
143
# Messaging connection and routing properties
140
144
messageQueue:
141
145
queue:
142
-
name: RabbitMQ # Name of the Queue on RabbitMQ Server
RabbitMQ supports [securing its (AMQP) channels using TLS](https://www.rabbitmq.com/docs/ssl). If working with such a TLS secured endpoint, the MATLAB RabbitMQ interface or MATLAB Production Server MessageBroker must explicitly be configured for this, in such cases you must:
4
+
5
+
1. Provide a trust store containing the server certificate chain and/or trusted root CAs, and
6
+
2. Optionally provide a keystore containing the client certificate and private key if your server requires client certificates.
7
+
8
+
Since the MATLAB RabbitMQ interfaces build on top of the RabbitMQ Java libraries, the trust store and key store need to be provided in Java compatible formats. Typically the trust store is in `JKS` format (with no predefined extension) and the keystore can be provided as `PKCS12` file (typically with the `.pfx` or `.p12` extension).
9
+
10
+
```{hint}
11
+
The server administrators who secured the RabbitMQ server with TLS in the first place, can likely help you with obtaining the correct certificates and keys, and in the right formats.
12
+
13
+
If you are not an expert in this area, it is typically recommended to reach out to the experts within your company rather than try to obtain and/or convert the certificates on your own.
14
+
15
+
Nevertheless some further hints and tips are provided below.
16
+
```
17
+
18
+
## Trust Store
19
+
20
+
The Trust Store needs to contain the actual server certificate and/or chain and/or root CA(s) of the server which you want to connect to. The Trust Store is typically provided in `JKS` format. If you have a certificate (chain) in PEM-format instead, you can use Java's `keytool` to import it into a `JKS` Trust Store, for example:
This will import the certificate(s) from `certificate.pem` into a new store in the current directory named `mytruststore`. `keytool` will ask for a new passphrase/password with which to secure this trust store.
27
+
28
+
## Key Store
29
+
30
+
If your server requires client certificates as well, you need to provide the client certificate and corresponding private key in the form of a `PKCS12` file; typically a file with `.p12` or `.pfx` extension. If you have the client certificate and corresponding key in two separate PEM-format files you will need to convert this to `PKCS12` format first, for example using the `openssl` commandline tool:
This this the private key from the `client_key.pem` and certificate from `client_certificate.crt` and together with the CA certificate from `CA.crt` writes it out to `client.p12` in `PKCS12` format.
37
+
38
+
```{hint}
39
+
Depending on the version(s) of tooling used, the (relatively old) Java Runtime as included with MATLAB by default, may not be able to read the client private key from the PKCS12 file. In such cases you may need to configure MATLAB to work with a newer (OpenJDK) Java Runtime, see:
0 commit comments