Secure Transportation

In intranet scenarios, it may be safe to transfer information (including sensitive data, such as user authentication credentials) using IIOP over plain sockets. However, when the network environment is not trusted (such as the Internet, or even an intranet), you need to guarantee integrity (the message was not modified or tampered with during the transmission) and confidentiality (the message cannot be read by anybody even if they intercepted it during transmission) of messages being transmitted over the network. This is achieved by using secure sockets (SSL).

VisiSecure functions in two transport environments:

•	using IIOP over plain sockets - (clear mode)

•	using secure sockets (SSL) - (encrypted mode)

Encryption

Public-key encryption

In addition to username/password-based authentication, VisiSecure also supports public-key encryption. In public-key encryption, each user holds two keys: a public key and a private key. A user makes the public key widely available, but keeps the private key secret.

Data that has not been encrypted is often referred to as clear-text, while data that has been encrypted is called cipher-text. When a public key and a private key are used with the public-key encryption algorithm, they perform inverse functions of one another, as shown in the following diagram.

•	In the first case, the public key is used to encrypt a clear-text message into a cipher-text message; the private key is used to decrypt the resulting cipher-text message.

•	In the second case, the private key is used to encrypt a message (typically in the case of digital signatures—that is, “signed” messages), while the public key is used to decrypt it.

If someone wants to send you sensitive data, they acquire your public key and use it to encrypt that data. Once encrypted, the data can only be decrypted with the private key. Not even the sender of the data will be able to decrypt the data. Note that encryption can be asymmetric or symmetric.

Asymmetric encryption

Asymmetric encryption uses both a public and a private key. Both keys are linked such that you can encrypt with the public key but can only decrypt with the private key, and vice-versa. This is the most secure form of encryption.

Symmetric encryption

Symmetric encryption uses only one key for both encryption and decryption. Although faster than asymmetric encryption, it requires an already secure channel to exchange the keys, and allows only a single communication.

Certificates and Certificate Authority

When you distribute your public key, the recipients of that key need some sort of assurance that you are indeed who you claim to be. The ISO X.509 standard defines a mechanism called a certificate, which contains a user's public key that has been digitally signed by a trusted entity called a Certificate Authority (CA). When a client application receives a certificate from a server, or vice-versa, the CA that issued the certificate can be used to verify that it did indeed issue the certificate. The CA acts like a notary and a certificate is like a notarized document.

You obtain a certificate by constructing a certificate request and sending it to a CA.

Distinguished names

A distinguished name represents the name of a user or the CA that issued the user's certificate. When you submit a certificate request, it includes a distinguished name for the user that is made up of the components listed in the following table.

Tag	Description	Required Component
Common-Name	The name to be associated with the user.	Yes
Organization	The name of the user's company or organization.	Yes
Country	The two character country code that identifies the user's location.	Yes
Email	The user’s email address.	No
Phone	The user's phone number.	No
Organizational Unit	The user's department name.	No
Locality	The city in which the user resides.	No

Certificate chains

The ISO X.509 standard provides a mechanism for peers who wish to communicate, but whose certificates were issued by different certificate authorities. Consider the following figure, in which Joe and Ted have certificates issued by different CAs.

For Joe to verify the validity of Ted's certificate, he must inspect each CA in the chain until a trusted CA is found. If a trusted CA is not found, it is the responsibility of the server to choose whether to accept or reject the connection. In the case shown in the preceding figure, Joe would follow these steps:

1	Joe obtains Ted's certificate and determines the issuing CA, Acme.

2	Since the Acme CA is not in Joe's certificate chain, Joe obtains the issuer of the certificate for CA_2.

3	Because CA_2 is not a trusted CA, the server decides whether to accept or reject the connection.

Notes

•	The manner in which you obtain certificate information from a CA is defined by that CA.

•	A VisiBroker server using the MFCryptLib/OpenSSL security provider never trusts a peer certificate if there is no valid CA intermediate/root certificate provided for it.

Generating a private key and certificate request

To obtain a certificate to use in your application, you need to first generate a private key and certificate request. To automate this process, for Java applications you can use the Java keytool, or for C++ applications you can use open source tools such as the openssl utility.

After you generate the files, you should submit the certificate request to a CA. The procedure for submitting your certificate request to a CA is determined by the certificate authority which you are using. If you are using a CA that is internal to your organization, contact your system administrator for instructions. If you are using a commercial CA, you should contact them for instructions on submitting your certificate request. The certificate request you send to the CA will contain your public key and your distinguished name.

Digital signatures

Digital signatures are similar to handwritten signatures in terms of their purpose; they identify a unique author. Digital signatures can be created through a variety of methods. Currently, one of the more popular methods involves an encrypted hash of data.

1	The sender produces a one-way hash of the data to be sent.

2	The sender digitally signs the data by encrypting the hash with a private key.

3	The sender sends the encrypted hash and the original data to the recipient.

4	The recipient decrypts the encrypted hash using the sender's public key.

5	The recipient produces a one-way hash of the data using the same hashing algorithm as the sender.

6	If the original hash and the derived hash are identical, the digital signature is valid, implying that the document is unchanged and the signature was created by the owner of the public key.

Enabling SSL

For Java only:

VisiSecure uses Java Secure Sockets Extension (JSSE) to perform SSL communication. VisiSecure SPI Secure Socket Provider class provides access to the underlying SSL implementation. Any appropriate implementation following Java Secure Socket Extension (JSSE) framework can be easily plugged in, independent of other provider mechanisms. The only necessary step is mapping the interfaces (or, in other words, callback methods) defined to the corresponding JSSE implementation. For more information on the SPI Secure Socket Provider class, see VisiSecure SPI for Java and “Security SPI for C++”.

For the “out-of-box” installation of VisiBroker, the JSSE implementation provided by the Java SDK is used.

Setting the level of encryption

The SSL product uses a number of encryption mechanisms. These mechanisms are industry-standard combinations of authentication, privacy, and message integrity algorithms. This combination of characteristics is referred to as a cipher suite.

The client and server have a static list of supported cipher suites. This list is used during the handshake phase of the connection to determine which cipher suite will be used. The client sends a list of all cipher suites it knows to the server. The server then takes this information and determines which cipher suites both the server and client understand. By default, the server selects the strongest available cipher suite.

While this cipher suite order ensures strong security, you may want to adopt a different cipher suite order based on application-specific security requirements. When you want to change the order of the cipher suites, use the Quality of Protection (QoP) API function calls; you can retrieve a list of the currently available cipher suites, then set the list to a new order so weaker cipher suites are used before stronger cipher suites.

Note

You cannot add new cipher suites. You can modify only the order of the cipher suites that are available and remove cipher suites you do not want to use.

Cipher suites

A cipher suite is a set of valid encoding algorithms used to encrypt data. Cipher suites have different security levels and can serve different purposes. For example, some ciphers provide for authentication while others do not; some provide for encryption and others do not.

Segments of the name of the cipher indicate what the cipher suite does or does not provide. The general format for cipher suite names is:

[TLS|SSL]_<Key Exchange Algorithm>_WITH_<Encryption Algorithm>_<Hashing Algorithm>

For example:

•	TLS_RSA_WITH_AES_128_CBC_SHA256

•	TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA

•	TLS_DH_anon_WITH_AES_128_CBC_SHA256

Note

Note that for security reasons, cipher suites that include usage of the RC4 cipher are no longer supported in VisiBroker for C++.

 

If you need to know more about cipher suite names or the possible values of the name segments, you can consult an SSL/TLS reference work.

The list of supported cipher suites for VisiSecure is determined by the underlying security implementation. For VisiSecure for Java, this is the JSSE package used, which in turn depends on the version and manufacturer of the JDK used. For VisiSecure for C++, it depends whether you are using the Certicom or the MFCryptLib/OpenSSL security provider (see “Specifying the Security Provider”); in either case you can find the list of supported ciphers in the <install_dir>/include/csstring.h file, or by using the ssl::CipherSuiteInfoList* listAvailableCipherSuites() API.

Using ECDH cipher suites

VisiBroker supports ECDH cipher suites. To enable these cipher suites a private key and certificate chain must be provided that conform to the following requirements:

•	For ECDH using ECC certificates signed by ECDSA, the identity certificate must contain an ECC public key that is enabled for ECDH usage. The supported cipher suites are:

TLS v1.0

•	TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA

•	TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA

•	TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA

TLS v1.2

•	TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256

•	TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256

•	TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384

•	TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384

•	For ECDH using ECC certificates signed by RSA, the server's private key which matches the public key in the server's identity certificate must be an RSA key that is authorized for signing. The supported cipher suites are:

TLS v1.0

•	TLS_ECDH_RSA_WITH_AES_128_CBC_SHA

•	TLS_ECDH_RSA_WITH_AES_256_CBC_SHA

•	TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA

TLS v1.2:

•	TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256

•	TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256

•	TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384

•	For ECDHE using ECC certificates signed by ECDSA, identity certificate must contain an ECDSA-capable public key.The supported cipher suites are:

TLS v1.0:

•	TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA

•	TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA

•	TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA

TLS v1.2

•	TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256

•	TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256

•	TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384

•	TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

•	For ECDHE using RSA certificates, the server's private key which matches the public key in the server's identity certificate must be an RSA key that is authorized for signing. The supported cipher suites are:

TLS v1.0:

•	TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA

•	TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA

•	TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA

TLS v1.2

•	TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256

•	TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

•	TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384

•	TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

In addition in all cases, the following requirements must be met:

•	The identity certificate must be signed by a capable ECDSA or RSA (as appropriate) certificate (intermediate or root).

•	The complete certificate chain must be provided.

•	For a server, the ECC private key that corresponds to the identity certificate must be provided.

ECC Curves

OpenSSL supports many pre-defined ECC curves (also known as 'named curves' or ‘elliptic curves’), used in ECDH and ECDHE ciphers. A complete list of the supported named curves can be obtained by executing the following command, using the openssl utility (in this example, for RedHat Linux):

./openssl ecparam -list_curves

VisiBroker supports the well-known TLS elliptic curves as defined in the following IANA RFC:

•	RFC4492: http://www.iana.org/go/rfc4492

•	RFC7027: http://www.iana.org/go/rfc7027

You are free to select any of the curves from the supported list (provided the key length is a minimum of 256 bits; see Note below) when generating your ECC keys/certificates. OpenSSL treats keys generated using these curves transparently.

While you may use any of the supported curves, the following curves were selected for the purposes of verifying the behavior of VisiBroker 8.5:

•	brainpoolP512r1

•	prime256v1

•

secp256k1

Note

VisiBroker inherits OpenSSL's default behavior, which is to disable all elliptic curves weaker than 256-bit unless configured otherwise.

ECDHE ephemeral keys

When an elliptic curve key is specified as part of the server's certificate and key configuration, ECDHE ephemeral keys are created on the same curve that is chosen for the server's primary key.

The list of supported curves that may be used with the vbroker.security.server.socket.ecdheCurve property is as follows:

•	The following older curves, now insecure, are included only for backward compatibility:

•

sect163k1

•

sect163r1

•

sect163r2

•

sect193r1

•

sect193r2

•

sect233k1

•

sect233r1

•

sect239k1

•

sect283k1

•

sect283r1

•

sect409k1

•

sect409r1

•

sect571k1

•

sect571r1

•

secp160k1

•

secp160r1

•

secp160r2

•

secp192k1

•

secp192r1

•	Secure curves:

•	prime192v1

•

secp224k1

•

secp224r1

•

secp256k1

•

secp256r1

•	prime256v1

•

secp384r1

•

secp521r1

•	brainpoolP256r1

•	brainpoolP384r1

•	brainpoolP512r1

Further curves may be added as the TLS specification changes in the future.

If no elliptic curve key is detected, the ECDHE_RSA cipher suites require that an elliptic curve is chosen to create the ECDHE temporary keys that will be used in the session. The ECDHE_RSA curve will be selected automatically. However you can also use the new server-side property vbroker.security.server.socket.ecdheCurve to set the curve that will be used for ECDHE cipher suites. The value of this property is a comma-separated list of curves, each of which must match one of the well-known elliptic curves as defined by IANA (the Internet Assigned Numbers Authority) for use with TLS.

•	If one curve name is listed, that curve is used for all ECDHE_RSA keys.

•	If more than one curve is listed, those named replace the default curved collection (listed under the next bullet point) that is used to produce a random choice of curve. Specifying multiple curves enables you to remove any that become deprecated in future.

Each curve in the list is checked at the time of the first connection and any invalid strings result in an EINVAL exception, with a logged message indicating the invalid string if the security module's logging is switched on.

•	If no curve is set, the property defaults to using a random curve from the following list of the most secure curves:

•	secp192r1 (also listed as prime192v1)

•

secp224k1

•

secp224r1

•

secp256k1

•	prime256v1 (also listed as secp256r1)

•

secp384r1

•

secp521r1

•	brainpoolP256r1

•	brainpoolP384r1

•	brainpoolP512r1

Note:

If secp192r1 is specified, prime192v1 will appear in the logs; these names indicate the same curve. Similarly, if prime256v1 is specified, secp256r1 will appear.

A previous ANSI X9.62 standard, Public Key Cryptography For The Financial Services Industry, defined some of the same curves as the IANA list, but with different names. Where this occurs either name can be used in the VisiBroker configuration.

For example:

•	The IANA secp192r1 is the same as the ANSI prime192v1

•	The IANA secp256r1 is the same as the ANSI prime256v1

 

Enabling Security

For an ORB to be secure, it must have the following property set:

vbroker.security.disable=false

Enabling SSL

To use SSL, your security in the ORB must be enabled. Once the security is enabled, SSL is enabled by default.

To disable the SSL

To disable the SSL on the client side, set the property on the client side as given below.

Vbroker.security.secureTransport=false

To disable the SSL on the server side, you must set the property on the server side as given below.

vBroker.security.server.transport=CLEAR_ONLY

Setting the Log Level

Logging in VisiBroker employs one or more Logger objects. Applications can log messages to the Default Logger as well, to integrate their logging output with that of the ORB, or they can create one or more other Loggers, to log messages independently as said earlier.

All log messages to a single logger are bound to a common set of destinations. By using multiple loggers for logging, messages from different components could be output to various independent end points.

ORB and all its C++ services use a special Logger instance (the ‘Default Logger’ with the name “default”), which is created automatically the first time the ORB logs a message. For more information, refer to the chapter on ‘VisiBroker logging’ in the VisiBroker for C++ Developer’s Guide.

SimpleLogger class is a mechanism to log information of various levels. Currently, it supports four different levels: LEVEL_WARNING, LEVEL_NOTICE, LEVEL_INFO, and LEVEL_DEBUG, with increasingly detailed information. There is only one logger in the whole security service. For information on the SimpleLogger class, see “vbsec::SimpleLogger”.

VisiSecure Java

Messages from VisiSecure Java internal are logged under the source name "secure".

For setting VisiSecure java logging messages to level info, set the following property to true:

vbroker.log.enable=true

vbroker.log.default.filter.secure.logLevel=info

The default value is "debug".

The VisiBroker Java logging mechanism applies to VisiSecure Java as well.

VisiSecure C++

VisiBroker for C++ provides a logging mechanism, which allows applications to log messages and have them directed, via configurable logging forwarders called appenders, to an appropriate destination or destinations. The ORB and all its services themselves use this mechanism for the output of any error, warning or informational messages.

The VisiBroker C++ logging mechanism applies to VisiSecure C++ as well.

For setting VisiSecure csiv2 related logging messages, set the following property to true:

vbroker.log.enable=true

vbroker.log.default.filter.v_seccsiv2.logLevel=info

The default value is "debug".

Messages from VisiSecure C++ internal are logged under four separate source names as given below.

Types of message	Source name
Authentication-related messages	v_secauthn
Authorization-related messages	v_secauthz
SSL-related messages	v_secssl
CSIV2-related messages	v_seccsiv2

Using IIOP/HTTPS

VisiBroker has a feature that allows tunneling of IIOP inside the HTTP protocol. This is an extended feature in VisiBroker called HIOP. With VisiSecure enabled, the secure version of HIOP is available. This allows tunneling of IIOP inside HTTPS.

You can make use of HTTPS, featured in most browsers. The following guidelines should be followed:

•	The VisiBroker proxy server GateKeeper must be running with SSL enabled on the exterior.

•	An applet that only uses IIOP/HTTPS requires no pre-installation of software (either classes or native libraries) on the client as long as the browser or applet viewer is HTTPS enabled.

•	An applet using IIOP/HTTPS cannot use the X509Certificate[] class to set or examine identities. All certificate and private key administration is handled by the browser. Furthermore, when the ORBalwaysTunnel parameter in the applet tag is set to true, the ORB cannot resolve SSLCurrent objects.

•	To enable an applet to use only IIOP/HTTPS, set ORBalwaysTunnel to true in the HTML page. If ORBalwaysTunnel is set to false (or unspecified) the ORB first tries to use IIOP/SSL, which requires the SSL classes and native SSL library to be installed locally.

•	In general, IIOP/HTTPS is not available to Java applications because HTTPS is not supported by the JDK. However, there are no restrictions in VisiBroker for Java that prevent the addition of HTTPS support to the JDK and the use of IIOP/HTTPS in Java applications.

Browser considerations

Some browser versions require the installation of the CA certificate before allowing an IIOP/HTTPS connection. Follow these guidelines to use IIOP/HTTPS with such browsers:

•	Make sure your server certificates are issued by a CA that is already trusted.

•	Install the root certificate as a trusted certificate. Opening a certificate file (for example, cacert.crt in bank_https) gives you the opportunity to install the certificate.

•	Use the GateKeeper to download the root certificate to the browser. The bank_https example shows how to do this.

•	Commercial CAs usually provide a link that allows you to install their root certificate.

•	GateKeeper, by default, does not ask for the client identity. You can enable this function by setting ssl_request_client_certificate to true in the GateKeeper configuration file.

Microsoft Internet Explorer

To use IIOP/HTTPS with Microsoft Internet Explorer, you must make sure that the HTTPS connection requires no user interaction. For example, if the browser visits a HTTPS site with an untrusted root certificate, the browser will ask for permission before establishing an HTTPS connection. The Microsoft JVM, due to a known bug, fails on this connection.

Here are several examples that illustrate this condition and ways in which you can work:

•

Internet Explorer ships with a list of trusted Network Server Certificates Authority. If your server certificate is not issued by one of the trusted CAs, (the certificates shipped with bank_https, for example) IE asks for permission before establishing an HTTPS connection. The IIOP/HTTPS operation fails because the Microsoft JVM does not seem to support an HTTPS connection that requires user interaction. There are a number of ways to handle this situation:

•	Make sure your server certificates are issued by a CA already trusted by Internet Explorer.

•	Install the root certificate into IE as a trusted Network Server certificate. Opening a certificate file (for example, cacert.crt in bank_https) gives you the opportunity to install the certificate.

•	Use the GateKeeper to download the root certificate to the browser. The bank_https example shows how to do this.

•	Commercial CAs usually provide a link that allows you to install their root certificate.

•	GateKeeper, by default, does not ask for the client identity. Although you can enable this function by setting ssl_request_client_certificate=true in the GateKeeper configuration file, you cannot use IIOP/HTTPS because the browser asks for permission before responding with the user's credentials.

Internet Explorer optionally requires the Common Name field within the server certificate to be the same as the host name of the server. From the View > Internet Options menu, select the Advanced tab and scroll to the Security section. Make sure the box next to Warn about invalid site certificates is not checked to use a server certificate that does not contain the host name of the server.