VisiSecure employs the Java Authentication and Authorization Service (JAAS) framework to facilitate the interaction between the entities and the system. At the same time, the authentication mechanism concept is employed to represent the format (encoding and decoding process) for communicating or transporting authentication information between various components of the security subsystem.
The Java Authentication and Authorization Service (JAAS) defines extensions that allow pluggable authorization and user-based authentication. This framework effectively separates the implementation of authentication from authorization, allowing greater flexibility and broader vendor support. The fine-grained access control capabilities allow application developers to control access to critical resources at the granularity level that makes the most sense.
VisiSecure employs the Java Authentication and Authorization Service (JAAS) framework to facilitate the interaction between the entities and the system. The three essential concepts of the framework are subject, principal, and credential.
JAAS uses the term subject to refer to any user of a computing service or resource. Another computing service or resource, therefore, is also considered a subject when it requests another service or resource. The requested service or resource relies on names in order to authenticate a subject. However, different services may require different names in order to use them.
A principal represents any name associated with a subject. A subject could have multiple names, potentially one for each different service it needs to access. A subject, therefore, comprises a set of principals, such as in the code sample below:
To return the principal name(s) for a subject from the application context, use getCallerPrincipal.
In the event that you want to associate other security-related attributes with a subject, you may use what JAAS calls credentials. Credentials are generic security-related attributes like passwords and public-key certificates. Credentials can be any type of object, allowing you to migrate any existing credential information or implementation into JAAS. Or, if you want to keep some authentication data on a separate server or other piece of hardware, you can simply store a reference to the data as a credential. For example, you can use JAAS to support a security-card reader.
Credentials in JAAS come in two types, public and private. Public credentials do not require permissions to access them. Private credentials require security checks. Public credentials could contain public keys and so on, while private credentials are private keys, encryption keys, sensitive passwords, and so on. Consider the following subject:
No additional permissions would be necessary to retrieve the public credentials from the subject, but the situation changes when trying to retrieve private credentials with following APIs:
The authentication mechanism concept is employed to represent the “format” for communicating (or transporting) authentication information between various components of the security subsystem. The security service provider for the authentication/identification process implements the specific format (encoding and decoding process) that is to be used by the underlying core system.
In a distributed environment, the authentication process is further complicated by the fact that the representation of the entity and the corresponding credential must be transported among peers in a generic fashion. Therefore, the VisiSecure Java SPI employs the concept of the AuthenticationMechanism and defines a set of classes for doing authentication/identification in a distributed environment.
An authentication mechanism represents the encoding/decoding for communicating authentication information between various components of the security subsystem. For example, it represents how LoginModules communicate with the mechanism and how the mechanism on one process communicates with an equivalent mechanism on another process.
For VisiBroker for C++ users, a set of APIs that allow trustpoints (trusted certificates) to be configured is provided as well. For more information, see “VisiSecure for C++ APIs”.
For example, if the following is the server side configuration file, then the information collected or entered by a user will be used for its JDBCLoginModule.
The default behavior of the process can be changed through properties. You can set the retry count by setting vbroker.security.authentication.retryCount. The default is 3. The security properties including those for authentication are listed and described in “Security Properties for Java” and “Security Properties for C++”.
The configuration must specify which LoginModules should be used for a particular application, and in what order the LoginModules should be invoked. For more information, see “Associating a LoginModule with a realm”.
An example of the config.jaas file looks like this:
This defines a realm called customrealm, which requires the use of the CustomLoginModule. Each realm entry has a particular syntax that must be followed. For more information on realm syntax, see “Syntax of a realm entry”.
The Flag value controls the overall behavior as authentication proceeds down the stack. For a description of the valid values for Flag and their respective semantics, see “Syntax of a realm entry”.
The authentication policy—whether it is server or client authentication and whether it is done using public-key certificates or passwords—is determined by property settings. For more information, see “Security Properties for C++” and “Security Properties for Java”.
Set the property vbroker.security.login=true
Set the property vbroker.security.login.realms=payroll,hr
Set the following realm information in a file reference by vbroker.security.authentication.config=<config-file>
Set the property vbroker.security.callbackhandler=<callback-handler>
Set the property vbroker.security.login.realms=payroll,hr
Set the following realm information in a file reference by vbroker.security.authentication.config=<config-file>
Set the property vbroker.security.callbackhandler=<callback-handler>
In the <config-file> setup the following:
|
•
|
The process will already know something about the realms to which it needs to authenticate through the property vbroker.security.login.realms.
|
The format of the realm information passed into vbroker.security.login.realms is as follows:
This format is called Formatted target.
In the above example, realm1, realm3 and realm4 are specific instances of GSSUP authentication mechanism. GSSUP is assumed by default if no other authentication mechanism is specified.
|
1
|
Set the vbroker.security.authentication.config property to the path of the configuration file.
|
|
1
|
|
2
|
Use the property vbroker.security.authentication.config to involve the configuration file into the runtime.
|
In the above example, the realm entry is named "customrealm". This name must be unique as it will be used by the VisiSecure to refer to this entry. The entry specifies the LoginModule to be used for the user authentication.
For setting up the configuration file for client and server, refer to the basic authentication example in the <install_dir>\examples\vbroker\security\basic folder. The example given here has all the basic setting needed to secure the application.
For more information on the authentication realm (user domain), see “Authentication realm (user domain)”.
With the VisiBroker implementation of JAAS, you can set up different mechanisms of authentication. You can have server authentication, where servers are authenticated by clients using public-key certificates. You can also have client authentication. Clients can be authenticated using passwords or public-key certificates. That is, the server can be configured to authenticate clients with a password or clients with public-key certificates. Whether it is server or client authentication and whether it is done using public-key certificates or passwords, it is determined by property settings. For more information see “Authentication property settings”.
Keeping these constraints in mind, VisiSecure supports the following usage of authentication models: GSSUP mechanism and Certificate mechanism. You can use any of these to provide an identity to the server or client.
An authentication mechanism represents the encoding/decoding for communicating authentication information between various components of the security subsystem.
VisiSecure provides a mechanism for a simple username/password authentication scheme. This mechanism is called GSSUP. The OMG CSIv2 standard defines the interoperable format for this mechanism. The LoginModule to mechanism interaction model is defined by Micro Focus. This is because the mechanism implementation needs to translate the information provided by a LoginModule to information (to a specific format) it can transmit over the wire using CSIv2.
The following code sample demonstrates the use of the login APIs. This case uses a wallet. For a full description of the four login modes supported, see “VisiSecure for C++ APIs” and “Security SPI for C++”.
The following code sample demonstrates the use of the login APIs. This case uses a wallet. For a full description of the four login modes supported, see “LoginModules”.
The Certificate mechanism is a mechanism that uses certificates for authentication. This mechanism is different from GSSUP; certificates are used instead of username/password, and these identities are used at the SSL layer and not at the higher CSIv2 over IIOP layer.
You can put certificates into VisiSecure using certificate login or wallet APIs. When using wallet APIs, you need to specify the usage through the constant definitions in the vbsec.h file, class vbsec::WalletFactory. For more information, see “class vbsec::WalletFactory”.
A process can have either a client and server identity that are different or an identity that is used in all roles, but not both. In other words, you cannot establish an identity in the Certificate#CLIENT and the Certificate#ALL targets simultaneously.
For backward compatibility, wallet properties and SSL APIs are supported; certificate identities established this way are only treated as Certificate#ALL.
|
1
|
|
2
|
|
6
|
Open the property files cpp_server.properties and cpp_client.properties and notice how the certificates and private keys are installed using the wallet property set in the files.
|
|
7
|
Browse through the content of subdirectory identities and trustpoints and understand how the directory wallet and trustpoints are structured.
|
We recommend that you check your ${VBROKER_DIR}/lib (on UNIX) or <install_dir>\bin (on Windows) directory.
|
1
|
Build the example as mentioned in the security/bank_SSL example in the example folder by executing the command:
|
A successful build creates the executables SecureServer.exe and SecureClient.exe on Windows, or SecureServer and SecureClient on UNIX.
|
2
|
Make sure osagent is up and running.
|
|
5
|
Launch either server or client or both using -Dvbroker.app.useCRL=true, and notice how the mutual SSL authentication fails and client gets NO_PERMISSION exception.
|
|
6
|
Read and learn from SecureServer.C, SecureClient.C:
|
|
•
|
|
•
|
If you do not want to use KeyStores directly, you can specify certificates and private keys using the CertificateWalletAPI. This class also supports the pkcs12 file format.
|
1
|
Build the example as mentioned in the bank_SSL example in the security folder by executing the command:
|
When the build completes, the executable pkcs12Server.exe is created on Windows, or pkcs12Server on UNIX platforms.
|
5
|
Launch the client using -Dvbroker.app.useCRL=true, and notice how the mutual SSL authentication fails and the client gets a NO_PERMISSION exception.
|
It is IMPORTANT to note that in the resulting list, the order is reversed. The root cert is list[0].
You can use the same APIs discussed in “Username/password authentication using APIs” to login using PKCS#12 KeyStores. The realm name in the IdentityWallet should be CERTIFICATE#ALL, the username corresponds to an alias name in the default KeyStore that refers to a Key entry, and the password refers to the password needed to unlock the PKCS#12 file. The property javax.net.ssl.KeyStore specifies the location of the PKCS#12 file.
The vbroker.security.wallet.identity property is ignored for a PKCS12 keystore, but the property must be set.
If you do not want to use KeyStores directly, you can import certificates and private keys using the CertificateFactoryAPI. This class also supports the PKCS#12 file format.
A LoginModule defines an authentication mechanism and provides the code to interact with a specific type of authentication mechanism. Each LoginModule is customized using authentication options that point it to a specific data source and provide other customizable behavior as defined by the author of the LoginModule.
Each LoginModule authenticates to a particular authentication realm (any authenticating body or authentication provider—for example, an NT domain). An authentication realm is represented by a configuration entry in a JAAS configuration file. A JAAS configuration entry contains one or more LoginModule entries with associated options to configure the realm. For more information, see “Associating a LoginModule with a realm” on page 32.
VisiSecure uses the class LoginContext as the user API for the authentication framework. The LoginContext class uses the JAAS configuration file to determine which authentication service to plug-in under the current application.
Authentication proceeds in two phases in order to assure that all stacked LoginModules succeed (or fail, otherwise).
|
1
|
The first phase is the “login phase,” during which the LoginContext invokes login() on all configured LoginModules and instructs each to attempt authentication.
 |
|
2
|
If all necessary LoginModules successfully pass, the second, “commit phase” begins, and LoginContext calls commit() on each LoginModule to formally end the authentication process. During this phase the LoginModules also populate the subject with whatever credentials and/or authenticated principals are necessary for continued work.
 |
If either phase fails, the LoginContext calls abort() on each LoginModule and ends all authentication attempts.
|
Figure 2
|
//server-side realms for clients to authenticate against
realm-name {
loginModule-class-name required|sufficient|requisite|optional
[loginModule-properties];
...
};
realm-name {
loginModule-class-name required|sufficient|requisite|optional
[loginModule-properties];
...
};
|
•
|
Realm Name—the logical name of the authentication realm represented by the corresponding LoginModule configuration
|
|
•
|
LoginModule Name—the fully-qualified class name of the LoginModule to be used
|
|
•
|
Authentication Requirements Flag—there are four values for this flag—required, requisite, sufficient, and optional. You must provide a flag value for each LoginModule in the realm entry. Overall authentication succeeds only if all required and requisite LoginModules succeed. If a sufficient LoginModule is configured and succeeds, then only the required and requisite LoginModules listed prior to that sufficient LoginModule need to have succeeded for the overall authentication to succeed. If no required or requisite LoginModules are configured for an application, then at least one sufficient or optional LoginModule must succeed. The four flag values are defined as follows:
|
|
•
|
required—the LoginModule is required to succeed. If it succeeds or fails, authentication still continues to proceed down the LoginModule list for each realm.
|
|
•
|
requisite—the LoginModule is required to succeed. If it succeeds, authentication continues down the LoginModule list in the realm entry. If it fails, control immediately returns to the application—that is, authentication does not proceed down the LoginModule list.
|
|
•
|
sufficient—the LoginModule is not required to succeed. If it does succeed, control immediately returns to the application—again, authentication does not proceed down the LoginModule list. If it fails, authentication continues down the list.
|
|
•
|
optional—the LoginModule is not required to succeed. If it succeeds or fails, authentication still continues to proceed down the LoginModule list.
|
|
•
|
LoginModule-specific properties—each LoginModule may have properties that need to be provided by the server administrator. The necessary properties for each LoginModule provided by Micro Focus are described below.
|
|
•
|
Basic LoginModule—this LoginModule uses a proprietary schema to store and retrieve user information. It uses standard JDBC to store its data in any relational database. This module also supports the proprietary schema used by the Tomcat JDBC realm.
|
|
•
|
JDBC LoginModule—this LoginModule uses a standard JDBC database interface to authenticate the user against native database user tables.
|
|
•
|
LDAP LoginModule—similar to the JDBC LoginModule, but uses LDAP as its authentication back-end.
|
|
•
|
Host LoginModule—for authentication to the operating system hosting the server. This is the only LoginModule supported for C++.
|
When running clients, the security subsystem has the opportunity to interact with users to acquire credentials for authentication. This is done using a callback handler, as mentioned in “Using the callback handler to communicate with users”. However, when running servers (your Visibroker server or a Partition), it is not desirable or even possible to have user interaction at start up time. A typical example of this if the server is started as a service at the startup time of a host or from a automated script of some sort.
The vault was designed to provide the identity information to the security subsystem in such environments. Note that the vault itself is not directly tied to the security subsystem. It is merely a tool to replace the user interaction.
To create a vault, you can use the vaultgen command-line tool from your installation's bin directory. Its usage is as follows:
<driver-options> are optional, and can be any of the following:
|
•
|
-J<option>: passes a -J Java option directly to the JVM
|
|
•
|
-VBJVersion: prints VBJ version information
|
|
•
|
-VBJDebug: prints VBJ debugging information
|
|
•
|
-VBJClasspath: specify a classpath that will precede the CLASSPATH environment variable
|
|
•
|
-VBJProp <name=value>: passes the name/value pair to the VM
|
|
•
|
-VBJjavavm: specify the path to the Java VM
|
|
•
|
-VBJaddJar <jar-file>: appends the JAR file to the CLASSPATH before executing the VM
|
-config <config.jaas-file> points to the location of the config.jaas file containing the realms the identities in the vault will authenticate to. -vault <vault-name> is the path to the vault to be generated. You can also specify an existing vault in order to add additional identities to it.
<options> are other optional arguments, and can be any of the following:
|
•
|
-?, -h, -help, -usage: prints usage information
|
|
•
|
-driverusage: prints usage information, including driver options
|
|
•
|
-interactive: enables an interactive shell
|
<command> is the command you want vaultgen to execute. You can select any one of the following:
|
•
|
login <realm|formatted-target>: establishes an identity in the vault for a given realm or formatted target. The identity is first established when the vault is used for login during system startup.
|
|
•
|
logout <realm|formatted-target>: removes an identity from the vault for a given realm or formatted target.
|
|
•
|
runas <alias> <realm>: configures a run-as alias with the identity provided for a given realm.
|
|
•
|
removealias <alias>: removes a configured run-as alias from the vault.
|
|
•
|
realms: lists the available realms for this configuration.
|
|
•
|
mechanisms: lists the available mechanisms (for formatted targets) for this configuration.
|
|
•
|
aliases: lists configured aliases in the vault.
|
|
•
|
identities: lists configured identities in the vault.
|
This example uses VaultGen. Assume we want to create a vault called MyVault for use with a domain called base. First, we need to know which security profile the domain is using so that we can reference its config.jaas file. We check the value of the domain's vbroker.security.profile property in the domain's orb.properties file:
#
# Security for the user domain
#
# Disable user domain security by default
vbroker.security.profile=default
vbroker.security.vault=${properties.file.path}/../security/scu_vault
# Security for the user domain
#
# Disable user domain security by default
vbroker.security.profile=default
vbroker.security.vault=${properties.file.path}/../security/scu_vault
The name of the security profile is default. This tells us that the path to the profile's config.jaas file is:
c:/BDP/var/security/profiles/default/config.jaas
Now we can check which realms are contained in the profile for which we want to create identities. We navigate to the installation's bin directory, and use the realms command:
vaultgen tells us the following realms are available:
c:\BDP\bin> vaultgen -config ../var/security/profiles/default/config.jaas -vault myVault login UserRealm
vaultgen prompts us for the username and password for the UserRealm, which we enter. We then repeat the process for each additional realm. At the end of each command, vaultgen informs us that it has logged-in the new identity and saved changes to MyRealm.
The vault is created in the directory you specify in the command, in this case the bin directory. A good place to put the actual vault files are in the domain's security directory, located in:
This example illustrates the use of the Security Context Interface's APIs generateVault(std::osstream& os, CSI::UTF8String& pass), login(std::istream& is) which can be used to explicitly login to the server. The example given here has all the basic setting needed to secure an application.
The API generateVault will take a file output stream and store the userid/password and realm in a file. It generates a byte stream from the login information by encrypting the login (Userid/password/realm) information. After encrypting, it closes the files and logs out.
The different properties files (server.properties, client.properties) and the server.config files for the basic vault example are in the <install_dir>\examples\vbroker\security\basic folder. The Bank Agent example has a simple AccountManager interface to open an Account and to query the balance in that account.
prompt% Server -DORBpropStorage=cpp_server.properties -genVault <vaultfileName>
prompt% Server -DORBpropStorage=cpp_server.properties -useVault <vaultfileName>
prompt% Client -DORBpropStorage=cpp_client.properties
When signed public key certificates are created by a Certificate Authority (CA), each certificate has an expiration date that indicates when it is no longer valid. However, in order to address the case where a certificate becomes invalid for some reason before the date of expiration, the Certificate Revocation List (CRL) feature is provided for VisiSecure for C++. For more information about Certificate Authorities (CA)s, see “Certificates and Certificate Authority”.
The CRL files can be in either DER binary format or base 64 text format. When an application adds a trusted certificate into a VBSSLContext instance, the corresponding CRL of that trusted certificate can be passed as second parameter of the call to the addTrustedCertificate() method. For this, the physical CRL bytes (if in DER) or string characters (if in B64) need to be wrapped in an instance of CORBAsec::ASN1Object, which is actually a CORBA octet sequence. See the VBSSLContext API in header file vbssp.h.
You can enable CAPI support in VisiBroker C++ by setting the vbroker.security.useCAPI property to true.
A new property has been introduced to assist in selecting the right client certificate if the user has multiple identity certificates that are eligible. See vbroker.security. identityCertificates. nameMustContain for details.
By setting the vbroker.security.client. socket.allowedDigests parameter to short you can prevent the use of the SHA-2 family of digests (SHA-256, etc). You may need to set this on the client side when the client is using a DSS certificate, unless you are using .1 or earlier, or you are using an add-on Credential Service Provider (CSP) that supports both DSA and SHA-512.
A known Java bug, JDK-6483657, means that it is not possible to access specific certificates in the store when there is more than one certificate sharing the same alias.
A new property is required to work around the bug. See vbroker.security.mscapiAliasFix for details. VisiBroker recommends setting this property to true unless it is known that there are definitely no certificates sharing an alias.