mf-client.dat Configuration Options

Use this section to configure one or more directories for Micro Focus Client Configuration (MFCC). MFCC uses directories to locate services hosted by Enterprise Server, such as deployment services. The default configuration is for MFCC to connect to MFDS on the local system.

The port specification ":0" means MFCC will first look for the CCITCP2_PORT environment variable for the port to connect to. If that is not set, it will try to look up the "mfcobol" service name in the /etc/services directory , and use that port. If that is not found either, it will use the official Micro Focus Directory Server directory port, which is 86.

For example:

[directories]
mrpi://127.0.0.1:0

Note: The list keyword can also be used here. See [service list] section for more information.

Use this optional section to provide default credentials for binding to the Micro Focus Directory Server (MFDS).

If these are not set, and the application does not specify any, an anonymous bind is attempted.

These credentials can be literal strings, or they can refer to secrets in a 'vault' accessed through the Micro Focus Vault feature. Vault secrets are specified as mfsecret:<config>:<name>, where <config> is an optional vault configuration tag (leave blank for the default vault), and <name> is the name given to the secret in the vault.

To use a literal string containing a colon, you can prefix it with "literal:" to prevent it being interpreted as another type of value.

For example:

username=mf_dep
password=mf_dep

Another option in this section is credentials, which can be set to the location of a vault secret which contains a username and password in ESCWA JSON format:

{ "mfUser": "username", "mfPassword": "password" }

If this option is set and the vault secret location is valid and contains valid data, MFCC will use that username and password to bind to MFDS.

From release 10.0 onwards, this is set to:

[mldap]
credentials=mfsecret::microfocus/common/readonly

which contains the credentials for an account with read-only access to MFDS data.

By default, if MFCC receives an invalid-credentials error from MFDS when trying to bind using the credentials configured with any of these options (username, password, and credentials), it will try again using an anonymous bind. This behavior can be disabled by adding the following configuration setting to this section:

try anonymous if bind fails=no

Note: This account is created at installation time, as part of the default VSAM ESM Module Security configuration.

Use this section to enable MFCC tracing; higher numbers log more information.

For example:

[tracing]
level=3

Use this section to specify default values for some MFCC parameters when they are not specified by the application:

connect-timeout

Changes the default MFCC timeout for connecting to a server and waiting to receive a response. This value is used if the application does not set timeouts directly (by calling the MFCC API), and the environment variable MFC_CONNECT_TIMEOUT is not set.

timeout

Changes the default MFCC timeout. This value is used if the application does not set timeouts directly (by calling the MFCC API), and the environment variable MFC_TIMEOUT is not set.

availability

Controls which instances of a service are considered available when requesting a list of service providers, or attempting to connect to any available instance of a service:

available: Only listeners that are listed as available and started are returned. This is the default option.
non-responding: Listeners that are listed as 'Not responding' in the directory can also be returned.
any: Returns any listener, even if it is listed as stopped in the directory.

mfbinp-digest

Enables the data-integrity digest option for MFBINP requests, which are used for COBOL EJBs and a number of internal services such as JCL job submission. The digest is disabled by default. For TLS (SSL) connections,l the digest is unnecessary, as TLS will guarantee data integrity.

For example:

[defaults]
connect-timeout=15
timeout=30
availability=available
mfbinp-digest=md5

Use this section to specify the following processing options:

relax-URL-rules: Allows characters forbidden by the standard in HTTP URLs.
proxy: Specifies the URL of a proxy for HTTP. This feature is experimental.

For example:

[options]
relax-URL-rules=true
proxy=https://proxy.host.com

Use this section to control some aspects of MFCC operation:

preferred-server: This value can be set to either the name of an enterprise server region, or to an environment variable specified as $NAME or %NAME%, in which case the value of the environment variable will be used. If this setting is configured, when MFCC is asked to search for a service and it finds a suitable service under more than one server, it will prefer the instance of the service that belongs to the preferred server. This is mostly useful for controlling service deployment in systems that have multiple enterprise server region configured.

For example:

[operation]
preferred-server=$ES_SERVER

Use this section to set default values for connections using TLS (also known as SSL), such as HTTPS connections.

Note: In product releases prior to Visual COBOL 5.0, this section was called [SSL]. The old section name can still be used. If both sections are present and have conflicting settings, the settings in the [TLS] section will be used.

You can specify the following parameters:

root

The collection of trusted certificates. Typically this file contains one or more CA root certificates. It might include roots for commercial CAs, roots for a private CA run by your organization, and/or a root for development purposes, such as one generated by the DemoCA product component. It can also contain trusted intermediate and even entity certificates. It should be a file in PEM format.

This is the root for a local Demo CA installation.

Note: Demo CA is not automatically installed. The installer is included in the product but must be run manually if you need Demo CA. See Tutorial: Configuring SSL Security in the Server.

If you use MFCC to connect to HTTPS servers on the public Internet, a useful root-certificate collection file is CARootCerts.pem, found in the bin directory of your Visual COBOL product installation. It contains root and intermediate certificates for many public CAs.

You can concatenate multiple PEM files together to assemble whatever root collection meets your needs.

certificate

The optional default client certificate. An MFCC application can override this value. Most servers do not ask clients to provide certificates also known as symmetric authentication. This value should be the pathname of a file in PEM or DER format.

key

The file with the private key corresponding to the client certificate. The supported file types are PEM and DER.

passphrase

Private keys are often stored encrypted, in which case MFCC needs a passphrase to use the key. The passphrase can be a literal string or a vault reference, as with the values in the [mldap] section described above.

verify peer

If the client should verify the server's certificate, set this option to a string beginning with "y", "t", or "1" (case-insensitive), then peer verification is enabled; otherwise it is disabled. The default is to enable peer verification.

Applications can override this setting, but rarely do.

Verification is critical to TLS security. It should only be disabled for testing, for example, to diagnose a certificate name-matching problem and similar purposes, and only temporarily.

verify depth

Set the maximum number of intermediate certificates in the server's certificate chain. The server's certificate chain is the certificate that identifies the server itself, the CA's root certificate, and any intermediate certificates between them. For example, the CA might have used its root certificate to sign an intermediate issuing certificate, which it then used to sign the server's certificate; or there might be two or more intermediates.

A depth of 1 allows one intermediate certificate between the root and the server's certificate, and so on.

Historically, this setting was used to prevent misusing entity certificates to sign other certificates. With modern (X.509v3) certificates, it is largely unnecessary, and should be set to a large enough value to accommodate all the server certificate chains that MFCC clients will see.

MFCC applications can override this value, but usually do not. If the application does not set a value, the configured value is used. If it is not specified in the configuration, the default is 2.

This setting has no effect if peer verification is disabled. See verify peer setting above.

The value must be non-negative (0 or greater).

verify peer name

Enables or disables verifying that a name in the server's certificate matches the hostname (or IP address) used to connect to the server. A certificate includes one or more names, indicating who or what the certificate is meant to identify. Typically, a client must check to see that the certificate it receives from the server matches the host it wants to connect to.

If this option is set to a string beginning with "y", "t", or "1" (case-insensitive), then name verification is enabled; otherwise it is disabled. The default is enabled.

By default, this is enabled, MFCC attempts to match each of the names in the server's certificate against the hostname that the application specified when MFCC requests to open the connection. The comparison is case-insensitive. Some CAs will issue certificates with wildcard names like *.foo.bar.com, which should match any hostname like a.foo.bar.com. Support in MFCC for wildcard names is experimental. Also, certificates can include IP addresses, which would be used for comparison if the application specifies an address rather than a hostname. Support for IP addresses is experimental.

Note: The name that the application gives to MFCC must match one of the names in the certificate. If the certificate only identifies myhost but the application tries to connect to myhost.mydomain.com, the conversation is rejected.

Name matching is critical to TLS security. It should only be disabled for testing, for example, to diagnose a certificate name-matching problem or similar purposes, and only temporarily.

This setting has no effect if peer verification is disabled. See verify peer setting above.

protocols

The TLS protocols option specifies the list of protocols (TLS versions) to be used, and the order of preference in which they are to be used. By default, TLS 1.0 through 1.3 are enabled, and later versions are preferred.

cipher suites

Set the list of cipher suites the client can use. This list also sets the client's order of preference, but many servers use their own preference when deciding which suite to use.

See Configuring a Cipher Suites List for more information on setting the cipher suites and what suites are enabled by default. The default list includes only ciphers still considered secure for normal use when the product release was developed.

TLS1.3 cipher suites

TLS version 1.3 has different cipher suites from previous protocol versions, and so it has its own cipher suite list. It is rarely necessary to set this configuration option.

min dh size

The minimum size in bits of the modulus length of the Diffie-Hellman (DH) group that is used to negotiate with connecting peers when using DH cipher suites. The default is suitable for normal application needs. See Using Diffie-Hellman Cryptography for more information.

cipher groups

The Cipher Groups option (previously known as "ECC curves") configures ECC parameters. For TLS 1.3, it sets the ECC group list; for earlier protocol versions, it sets the permitted curves. It is rarely necessary to use this configuration option. See Using Elliptic Curve Cryptography for more information.

middlebox workaround

Enables or disables the TLS 1.3 "middlebox workaround", a feature which lets TLS 1.3 work on some connections that traverse routers, firewalls, and other systems which do not correctly handle TLS 1.3. It is enabled by default, and it is rarely necessary to change this setting. Possible values are disable and enable.

For example:

[TLS]
root=/path/to/root/cert.type
certificate=/path/to/client/cert.type
key=/path/to/client/keyfile.type
passphrase=keyfile passphrase
middlebox workaround=enable
verify peer name=yes
verify depth=2
verify peer=yes

Use this (optional) section to set credentials (username and password) for HTTP and HTTPS requests to a given host and port, if the application does not specify them. This can be used to supply credentials to HTTP hosts that use HTTP Basic Authentication. The username and password are separated by a colon, as they would be in a URL (http://user:pass@host:port/path).

For example:

[credentials]
www.tempuri.org=username:password
myhost:9000=someuser:somepass

Use this optional section to provide a simple directory in the configuration file itself, rather than using an MFDS server and repository. If "list" appears in the directory list (see [directories] section above), then when MFCC reaches that point in the directory list, it will search this section.

Each entry in this section takes one of two forms:

service name=location: The location string is interpreted as the location of the service. It can be a URL or an MFDS location string, for example, protocol:hostname:port.
service name=[section name]: MFCC will look for a section with the given name. It must contain an entry named 'location' with the location specified as above. It can also contain an entry named 'config', which names yet another section, holding service configuration values. This is potentially useful for defining deployment services in the service list.

For example:

[service list]
service1=http://tempuri.com
service2=[service2 definition]

[service2 definition]
location=tcpssl:myhost:9443
config=[service2 config]

[service2 config]
name1=value1
name2=value2