Security API and Property Reference for Java Applications

This document contains the complete API and property reference for Borland Enterprise Server's J2EE and CORBA security implementation.

Note: For the VisiBroker Edition, all security features are supported by VisiSecure. VisiSecure components includes Authorization, Authentication, and SSL.

Service Provider Interface (SPI) com.borland.security.spi

This section describes the Service Provider Interface (SPI) classes as defined in the Borland Security Services (BSS) package com.borland.security.spi. These SPI classes provide advanced pluggability of security functionality and allow other security providers to plug in their own implementation of security services into the BSS flawlessly for use within the Borland Enterprise Server.

Providers

Each provider instance is created by the BSS using a Java reflection API. After the instance has been constructed, the initialize method, which must be provided by the implementer, is called passing in a map of options specific for the implementation. The options entries are defined by the implementers of the particular provider. Users specify the options in a property file and the BSS parses the property and passes the options to the corresponding provider. The following table shows the properties for plugging in different provider implementations.

Settings for Security Service Provider Implementations

Module Name	Property to set	Interface to implement	Options Prefix
IdentityAdapter	vbroker.security.identity.adapters	com.borland.security.spi.IdentityAdapter	vbroker.security.identity.adapter.<name>
AuthenticationMechanism	vbroker.security.identity.mechanisms	com.borland.security.spi.AuthenticationMechanisms	vbroker.security.identity.mechanism.<name>
AttributeCodec	vbroker.security.identity.attributeCodecs	com.borland.security.spi.AttributeCodec	vbroker.security.identity.attributeCodec.<name>
TrustProvider	vbroker.security.trustProvider	com.borland.security.spi.TrustProvider	vbroker.security.trust.trustProvider.<name>

In the preceding table:

The first column lists the provider module names.
The second column lists the property you set to define each module. Use a comma to separate multiple modules. For example, the following property has two additional IdentityAdapter implementations installed for the ORB:
```
vbroker.security.identity.adapters=ID_ADA1,ID_ADA2
```
The third column gives the interface each implementation must implement. The interface defines a contract between the implementers and the core BSS.
The final column gives the options prefix for the specific module. The ORB parses the property file and passes the corresponding entries to each of the modules in the initial method as the (Map options) parameter. For example, for the ID_ADA1 IdentityAdapter defined in the previous example, all the entries with the vbroker.security.identity.adapters.ID_ADA1 prefix will be passed to the initial method of ID_ADA1 IdentityAdapter.

Providers and exceptions

During the initialization, if anything goes wrong the initialize method should throw an instance of InitializationException. For certain categories of providers, there can be multiple instances with different implementations co-existing. Each of them is identified by the name within the BSS system, which is passed as the first parameter in the initialize method. While for some categories of providers there can be only one instance existing for the whole ORB (such as in the case of the TrustProvider, in this case, the initialize method has only one single parameter—the options map.

com.borland.security.spi.IdentityAdapter

IdentityAdapter binds to a particular mechanism. The main purpose of an IdentityAdapter is to interpret identities specific to a mechanism. It is used to perform the decoding and encoding between mechanism-specific and mechanism-independent representations of the entities.

IdentityAdapters included with the BSS

The following IdentityAdapters are provided with the BSS:

AnonymousAdapter, with the name "anonymous"
DNAdapter, with the name "DN"
X509CertificateAdapter (as an implementation of the sub-interface AuthenticationMechanism)
GSSUPAuthenticationMechanism (as an implementation of the sub-interface AuthenticationMechanism)

Methods


void initialize (java.lang.String name, java.util.Map options)

This method initializes the IdentityAdapter with the given name and set of options.

Arguments

This method takes the following two arguments:

The IdentityAdapter name.
A set of options for the specified IdentityAdapter.

Exceptions

Throws InitializationException if initialization fails.


public java.lang.String getName ()

This returns the name of the IdentityAdapter.

Returns

The name of the IdentityAdapter.

Exceptions

none


public org.omg.CSI.IdentityToken exportIdentity (

javax.security.auth.Subject caller)

Exports the identity of the IdentityAdapter as an IdentityToken.

Arguments

The subject whose identity is to be exported.

Returns

An IdentityToken data.

Exceptions

Throws NoCredentialsException if no credentials recognized by this IdentityAdapter are found in the subject.


public void importIdentity (javax.security.auth.Subject caller, 

 org.omg.CSI.IdentityToken data)

Imports the IdentityToken and populates the caller subject with the appropriate principals associated with this identity.

Arguments

The subject whose identity is to be imported.

Exceptions

Throws NoCredentialsException if no credentials recognized by this IdentityAdapter are found in the subject.


public java.security.Principal getPrincipal (javax.security.auth.Subject subject)

Returns a Principal representing this identity. This method is used for interfacing with EJBs and servlets.

Arguments

The principal subject.

Returns

A principle object.

Exceptions

none


public Privileges getPrivileges (javax.security.auth.Subject subject)

Arguments

The target subject.

Returns

The privilege attributes for this target subject recognized by this IdentityAdapter.

Exceptions

none


public void setPrivileges (Privileges privileges)

This methods sets the privilege attribute for the identity.

Arguments

The privilege attribute to be set for the identity.

Exceptions

none


public void deleteIdentity (javax.security.auth.Subject subject)

This method deletes the principals and the credentials associated with the specified target subject.

Arguments

The target subject for which the principals and the credentials recognized by this IdentityAdapter are to be deleted.

Exceptions

none

com.borland.security.spi.MechanismAdapter

Extending from IdentityAdapter, a MechanismAdapter has the additional capability of changing the target information. This is very useful in the case where the mechanism used in a remote site is not available locally. Therefore, the local identity must be adapted before sending to the remote site.

In the out-of-box installation of BSS, there is no class direct implementation of MechanismAdapter, while a few classes implement the sub-interface AuthenticationMechanism, which in turn gives the support of this interface.

Methods


public java.lang.String getOid ()

Returns a string representation of the mechanism OID. For example, the string representation for a GSSUP mechanism would be oid:2.23.130.1.1.1.

Returns

The mechanism OID string.

Exceptions

none


public Target getTarget (java.lang.String realm, 

 javax.security.auth.login.AppConfigurationEntry [] entries)

Given a realm name and a list of AppConfigurationEntry objects, returns the corresponding target.

Arguments

This method takes the following two arguments:

A realm name.
A list of AppConfigurationEntry objects.

Returns

Returns the corresponding target object.

Exceptions

none


public Target getTarget (byte [] encoded)

Returns a Target object representing the encoded target representation.

Arguments

A Target encoded in GSS Mechanism-Independent Exported Name format (as defined in [IETF RFC2743]).

Returns

A Target object.

Exceptions

none

com.borland.security.spi.AuthenticationMechanisms

This class represents a full-fledged mechanism which provides all the functionality needed to support an authentication mechanism in conjunction with the CSIv2 protocol.

Included with BSS are the following implementations for GSSUP based and X509 Certificate based authentication mechanisms respectively:

GSSUPAuthenticationMechanism
X509CertificateAdapter

In addition to the methods inherited from its super interfaces, AuthenticationMechanism also has the following categories of methods defined.

Credential-related methods

Use these methods to acquire and/or destroy credentials.


public javax.security.auth.Subject acquireCredentials (Target target, 

 javax.security.auth.callback.CallbackHandler handler)

This method acquires credentials for a given target. The credentials acquired depend on the mechanism and the information it requires for authentication.

Arguments

This method takes the following two arguments:

A Target object.
The callback handler to be used to communicate with the user for acquiring the credentials for this Target.

Returns

The Subject containing the acquired credentials (will be null in the case where the operation fails).

Exceptions

none


public javax.security.auth.Subject acquireCredentials (java.lang.String target,

 javax.security.auth.callback.CallbackHandler handler)

This method acquires credentials for a given string representation of the Target. The credentials acquired depend on the mechanism and the information it requires for authentication.

Arguments

This method takes the following two arguments:

A string representation of the Target.
The corresponding callback handlers used to communicate with user for acquiring the credential.

Returns

A subject object containing the acquired credentials (will be null in the case where the operation fails).

Exceptions

none


public void destroyPrivateCredentials (javax.security.auth.Subject subject)

This method destroys the private credentials of the specified subject.

Arguments

The subject for which the private credentials are to be destroyed.

Exceptions

none

Context-related methods


public byte [] createInitContext (javax.security.auth.Subject subject)

Returns a mechanism-specific client authentication token. The token represents the authentication credentials for the specified target.

Arguments

The target subject.

Returns

The authentication token for the specified target subject.

Exceptions

Throws NoCredentialsException if no authentication credentials recognized by this mechanism exist in this Subject.


public Target processInitContext (javax.security.auth.Subject subject,

 byte [] initial_context)

This method consumes the mechanism-specific client authentication token. The initial authentication token is decoded and the method populates the given subject with the corresponding authentication credentials.

Arguments

The subject to be populated with authentication credentials.

Exceptions

none


public byte [] createFinalContext (javax.security.auth.Subject subject)

This method creates a final context token to return to a client.

Arguments

The Subject.

Returns

A final context token.

Exceptions

none


public void processFinalContext (javax.security.auth.Subject subject

 byte [] final_context)

Consumes a final context token returned by the server.

Arguments

The target subject.

Exceptions

none


public byte [] createErrorContext (javax.security.auth.Subject subject,

 java.lang.Throwable cause)

Creates an error context token in the case of an authentication failure.

Arguments

This method takes the following two arguments:

A target subject.
The exception that caused the authentication failure.

Returns

An error context token.

Exceptions

none


public void processErrorContext (javax.security.auth.Subject subject, 

 byte [] error_token, javax.security.auth.callback.CallbackHandler handler)

Consumes an error token returned from server. The callback handler is used to interact with a user trying to reacquire credentials. If credentials are required, the client-side security service attempts to establish the context again.

Arguments

This method takes the following two arguments:

A target subject.
A callback handler.

Exceptions

none

com.borland.security.spi.Target

This class gives the runtime representation of a target authenticating principal. The context includes names for the target required in different scenarios, such as the display name, or the DER representation of the OID.

Methods


public java.lang.String getName ()

This method returns the display name of the target.

Returns

The target name string.

Exceptions

none


public byte [] getOid ()

This method returns the target OID.

Returns

The target OID string.

Exceptions

none


public byte [] getEncodedName ()

This method returns the mechanism-specific encoding of the target name.

Returns

The encoded target name.

Exceptions

none

com.borland.security.spi.AuthorizationServicesProvider

The implementer of the Authorization Service provides the collection of permission objects granted access to certain resources. Whenever an access decision is going to be made, the AuthorizationServicesProvider is consulted. The Authorization Service is closely associated with the Authorization domain concept. An Authorization Service is installed per each Authorization domain implementation, and functions only for that particular Authorization domain.

The AuthorizationServicesProvider is initialized during the construction of its corresponding Authorization domain. Use the following property to set the implementing class for the AuthorizationServicesProvider:


vbroker.security.domain.<domain name>.provider

During runtime, this property is loaded by way of Java reflection.

Another import functionality of the Authorization Service is to return the run-as alias for a particular role given. The security service is configured with a set of identities, identified by aliases. When resources request to "run-as" a given role the AuthorizationServices again is consulted to return the alias that must be used to "run-as" in the context of the rules specified for this authorization domain.

Methods


public void initialize (java.lang.String name, java.util.Map options)

This method initializes an Authorization Services provider.

Arguments

This method takes the following arguments:

A provider name.
The provider options.

In addition to the provider's options, the following information is passed to facilitate the interaction between this Authorization Service provider and the VisiBroker ORB:

Name	Description
`ORB`	The ORB instance used for the current system.
`Logger`	A `com.inprise.vbroker.Logging.SimpleLogger` instance used for loggin in the current system.
`LogLevel`	An integer value denoting the security logging level.

Exceptions

Throws InitializationException if initialization of the Authorization provider fails.


public java.lang.String getName ()

Returns the name for this Authorization Service implementation.

Returns

The Authorization Service name.

Exceptions

none


public java.lang.String getRunAsAlias (java.lang.String runAsRole)

Returns the run-as alias for a given role.

Arguments

The run as role.

Returns

The run-as role alias name.

Exceptions

none


public java.security.PermmissionCollection getPermissions 

 (Resource resource, Privileges callerPrivileges)

Returns a homogeneous collection of permission attributes for the given privileges as well as the resource upon which the access is attempted.

Arguments

This method takes the following two arguments:

The caller Priviliges.
The resource object upon which access is to be attempted.

Returns

A PermissionCollection object represents this subject's Permissions.

Exceptions

none

com.borland.security.spi.Resource

The Resource interface gives a generic abstraction of resource. The resource can be anything upon which the access will be made, such as a remote method of a CORBA object, or a servlet which is essentially a resource.

Methods


public java.lang.String getName ()

Returns the string representation of the resource being accessed.

Returns

Name of the resource.

Exceptions

none

com.borland.security.spi.Privileges

The Privileges class gives an abstraction of the privileges for a subject. It is the container of authorization privilege attributes, such as Distinguished Name (DN) attributes, and such. The AuthorizationService makes the decision on whether the subject has permission to access the certain resource based on the privileges object of the subject.

The privileges object is stored inside the subject as one of the PublicCredentials. At the same time, privileges hold one reference to the referring subject. Privileges also contain a DN attributes map, as well as a map of other authorization attributes.

The Privileges class implements the javax.security.auth.Destroyable interface.

Constructors


public Privileges (java.lang.String name, javax.security.auth.Subject subject)

This constructor creates a privileges object with the given name and associates it with the given subject.

Arguments

The method takes the following two arguments:

Name of the Privileges object, which is actually the associated Subject's name.
The target subject.

Exceptions

none

Methods


public javax.security.auth.Subject getSubject ()

This method returns the subject that the privileges object represents.

Returns

The target subject.

Exceptions

none


public java.lang.String getSubjectName ()

This method returns the name of the associated subject object.

Returns

The target subject.

Exceptions

none


public java.util.Map getAttributes ()

This method returns the attribute map of the user.

Returns

The user's attribute map.

Exceptions

none


public void setDNAttributes (java.util.Map map)

This method updates the DN Attributes of the user.

Arguments

The new DN Attributes Map.

Note: After the DN Attributes Map has been set, the Privileges object will set the underlying DN Attributes Map as unmodifiable.

Exceptions

none


public java.util.Map getDNAttributes ()

This method returns the DN Attributes of the Privileges object, which can be null.

Returns

User's DN Attributes map, which is unmodifiable.

Exceptions

none


public boolean isDestroyed ()

This method checks whether the privileges object has been destroyed or not.

Returns

true|false

Exceptions

none


public void destroy ()

This method destroys the credentials associated with this privileges object, including the name, the association with the subject, and all the privilege attributes.

Exceptions

none


public java.lang.String toString ()

This method overrides the default toString implementation of java.lang.Object, and returns "Privileges for <subject name>" information.

Returns

List of privileges for each subject name.

Exceptions

none

com.borland.security.spi.AttributeCodec

The AttributeCodec objects are responsible for encoding and decoding privileges attributes of a given subject. This allows clients and servers to communicate privilege information to each other. Though the privilege information is used as the basis for the Authorization decision-making process, AttributeCodec selection is based on the information presented in the IOR published by the server. Inside the IOR, the server publishes information on the encoding scheme supported, while clients select an AttributeCodec that supports the given encoding.

All the AttributeCodecs implementations are registered with the IdentityServices, which is called upon during the import/export of the authorization elements process.

Methods


public void initialize (java.lang.String name, java.util.Map options)

This method initializes this instance of the AttributeCodec implementation. There can be multiply implementations existing in one ORB, and each is addressed internally using the name provided.

Arguments

This method takes the following arguments:

A string of AttributeCodec implementation names.
Provider options.

For the provider's options, the following additional information is also passed during the initialization:

Name	Description
`ORB`	The ORB instance used for the current system.
`Logger`	A `com.inprise.vbroker.Logging.SimpleLogger` instance used for the current system for the purpose of logging.
`LogLevel`	An integer value denoting the security logging level.

Exceptions

Throws InitializationException if initialization of this AttributeCodec object fails.


public java.lang.String getName ();

This method returns the name of the provider implementation.

Returns

The provider name string.

Exceptions

none


public org.omg.CSIIOP.ServiceConfiguration [] getPrivilegeAuthorities ()

This method returns a list of supported privilege authorities.

Returns

A list of privilege authorities.

Exceptions

none


public int getSupportedEncoding ()

This method returns the supported AuthorizationElement type.

Returns

An AuthorizationElement type.

Exceptions

none


public boolean supportsClientDelegation ()

Returns whether this implementation supports ClientDelegation.

Returns

true|false

Exceptions

none


public org.omg.CSI.AuthorizationElement [] encode

 (org.omg.CSIIOP.ServiceConfiguration [] privilege_authorities, 

 Privileges caller_privileges, Privileges asserter_privileges)

This method encodes privileges as AuthorizationElements. This method encodes the privilege attributes of the given caller and the given asserter, if there is one. It will extract the privilege information from the subject and privilege map of the caller and the asserter.

Additionally, an implementation of the AttributeCodec (if supports ClientDelegation) may choose to verify whether the asserter is allowed to assert the caller based on the client delegation information presented by this caller.

Arguments

This method takes the following arguments:

A set of caller privileges attributes.
A set of asserter privileges attributes.

Returns

Encoded caller and asserter privileges.

Exceptions

Throws NoDelegationPermissionException if the assertion is not allowed.


public void decode (org.omg.CSI.AuthorizationElement [] encoded_attributes,

 Privileges caller_privileges, Privileges asserter_privileges)

This method decodes authorization elements and populates the corresponding privileges objects. This is the inversion process of the encode method. When a server receives a set of encoded AuthorizationElements, it passes these elements to the AttributeCodec for interpretation. Based on the encoding method, one particular AttributeCodec consumes the attributes it understands. It may update the caller's or asserter's Privileges, or may add RolePermission directly to the subject's public credentials.

Arguments

This method takes the following arguments:

A set of encoded AuthorizationElements.
A set of caller privileges.
A set of asserter privileges.

Returns

This method returns nothing. Upon a successful processing, this AttributeCode object updates the caller's or asserter's Privileges maps as appropriate based on the information available in the authorization elements.

Exceptions

Throws NoDelegationPermissionException if the assertion is not authorized.

com.borland.security.spi.RolePermission

The RolePermission class provides the basis for authorization and trust in the BSS system.

Constructors


public RolePermission (java.lang.String role)

This constructor creates a RolePermission object representing a logic role.

Arguments

A logical role string this RolePermission object represents.

Returns

A RolePermission object.

Exceptions

none

Methods


public boolean implies (java.security.Permission permission)

This method checks whether the permission object passed in implies this RolePermission object. The check is based on strict equality, as the method only returns true (implies) when ALL the following conditions exist:

the permission object given is an instance of RolePermission, and
the name of the permission object given equals the name of this RolePermission.

Arguments

A Permission object to check.

Returns

True|False

Exceptions

none


public java.lang.String getActions ()

This method returns the action associated with this RolePermission.

Returns

Always returns null, since there are no actions associated with a RolePermission object.

Exceptions

none

com.borland.security.spi.TrustProvider

When a remote peer (server or process) makes identity assertions in order to act on behalf of the callers, the end-tier server needs to trust the peer to make such assertions. This is meant to prevent untrusted clients from making assertions.

The key method is isAssertionTrusted, which is called to determine whether the assertion is trusted given the caller subject and asserter's privileges. This method is called (by the underline implementation) after the corresponding authorization elements transmitted from a client to the server have been consumed.

You use the TrustProvider class to implement trust rules which determine whether the end-tier server accepts identity assertions from a given asserting subject. The TrustProvider class is very closely related to the implementation of the AttributeCodec objects and the privileges. For example, it is possible to provide the decision-making implementation as follows:

Provide class implementations representing a proxy endorsement attribute,
AttributeCodec implements the necessary logic then passes the attributes and imports them to the caller subject on the server-side. It is also necessary to return true for the method supportsClientDelegation defined in the AttributeCodec interface.
Provide the method implementation based on the proxy endorsement attribute of the caller and the privileges of the asserter.

This type evaluation of trust, which is based on rules provided by the caller, is referred to as Forward Trust. Backward Trust is when the evaluation of trust is based on the rules of the target. Backward Trust is the default provided with the BSS installation.

Methods


public void initialize (java.util.Map options)

This method initializes the TrustProvider. There can be only one instance of the TrustProvider implementation existing for each process.

Arguments

For the provider's options, the following additional information is also passed during the initialization:

Name	Description
`ORB`	The ORB instance used for the current system.
`Logger`	A `com.inprise.vbroker.Logging.SimpleLogger` instance used for the current system for the purpose of logging.
`LogLevel`	An integer value denoting the security logging level.

Exceptions

Throws InitializationException if initialization of the TrustProvider fails.


public boolean isAssertionTrusted (javax.security.auth.Subject caller,

 Privileges asserterPrivileges)

This method verifies whether an assertion of the caller by the asserter with the provided privileges is trusted or not. The implementation makes use of the internal trust rules for this process to determine the validity of the assertion.

Arguments

This method takes the following two arguments:

The caller.
The set of asserter privileges.

Returns

true|false

Exceptions

none

SSL APIs and properties

com.borland.security.Context

This interface represents the security context for SSL transport. Security Context can be used to trigger a login, to specify an identity to be used, to obtain or set static SSL communication-related information, to obtain currently-set identities, or generate and use an Identity Vault. This interface is resolved through the call:


(com.borland.security.Context)orb.resolve_initial_references("VBSecurityContext")

The following shows some sample code utilizing Context:


public static void main(String args[]) {

   org.omg.CORBA.ORB orb = org.omg.CORBA.ORB.init(args,null);

   com.borland.security.Context ctx = 

      (com.borland.security.Context)orb.resolve_initial_references("VBSecurityContext");

   if(ctx !=null) {

   .

   .

}

Methods


public List listRunAsIdentities();

This method returns a list of the aliases that correspond to the set of configured run-as identities.

Returns

A list of alias names.

Exceptions

None


public Subject getRunAsIdentity(String alias);

This method returns the subject that maps to a run-as alias.

Arguments

A string which is the run-as alias name.

Returns

An authenticated Subject corresponding to the alias.

Exceptions

None


public Principal getPrincipal(String target);

This method returns the principal representing the current system identity for the specified target realm.

Arguments

A string which is the name of the target realm in which the principal resides.

Returns

A java.security.Principal object.

Exceptions

None


public SSLSession getPeerSession(org.omg.CORBA.Object target);

This method returns the SSL session of the connection used to communicate with the specified target.

Arguments

The target object with which an SSL connection is established.

Returns

The SSLSession on which outgoing requests will be made. If the specified target has not been bound to yet or the session is over a clear transport, a value of null returns.

Exceptions

None.


public SecureRandom getSecureRandom();

This method returns the SecureRandom class used to generate the random numbers needed for SSL. If the user does not set a SecureRandom, by default one is created.

Returns

The current SecureRandom object.

Exceptions

None


public String[] getEnabledCipherSuites();

This method returns a list of the cipher suites available to the system that are currently enabled for all SSL sessions.

Returns

A string array containing the cipher suites.

Exceptions

None


public String[] listAvailableCipherSuites();

This method returns a list of all cipher suites available to the system for use with the SSL layer.

Note: This method differs from getEnabledCiperSuites, in that not all the available cipher suites may be currently enabled.

Returns

A string array containing the cipher suites.

Exceptions

None


public Principal authenticate (Wallet wallet);

This method imports an identity into the system. It authenticates the user represented by the specified wallet and returns the associated principal.

Note: Deprecated as of BES 5.2 release. Please use public Subject authenticateUser(Wallet wallet);.

Arguments

The wallet representing the identity.

Returns

The principal representing the identity.

Exceptions

Throws org.omg.CORBA.NO_PERMISSION if authentication fails.


public Subject authenticateUser(Wallet wallet);

This method imports an identity into the system. This authenticates the user represented by the specified wallet and returns the associated Subject.

Arguments

The wallet object representing the identity to import.

Returns

The Subject representing the identity.

Exceptions

Throws org.omg.CORBA.NO_PERMISSION if authentication fails.


public Subject getSubject(String target);

This method returns the subject that corresponds to the specified target realm.

Arguments

This method takes a string array containing:

The target as a Formatted Target,
or a realm name.

Returns

The subject representing the identity for the specified target.

Exceptions

None


public Principal import_wallet (Wallet wallet);

This method imports and identity into the system. This method does not authenticate the user represented by the specified wallet, but returns a principal representing the user.

Note: Deprecated as of BES 5.2 release. Please use public Subject importIdentity (Wallet wallet);.

Arguments

The wallet representing the identity to import.

Returns

The principal representing the identity.

Exceptions

None


public Subject importIdentity (Wallet wallet);

This method imports an identity into the system. This method does not authenticate the user represented by the specified wallet, but returns a Subject representing the user.

Arguments

The wallet object representing the identity to import.

Returns

The subject representing the identity.

Exceptions

None


public TrustManager getTrustManager();

This method returns the currently registered Trust Manager. To perform trust checks in addition to what the default Trust Manager performs, get the default Trust Manager and set your own Trust Manager to delegate to the default Trust Manager.

Returns

The currently registered/installed Trust Manager. If none of the users has installed a Trust Manager, the default Trust Manager is returned.

Exceptions

None


public void setTrustManager(TrustManager trustManager);

This method specified the Trust Manager to use for verifying trust in peer certificates when using SSL authentication.

Arguments

An implementation of the TrustManager interface.

Exceptions

None


public void addRunAsIdentity (String alias, Wallet runas);

This methods adds a run-as identity. It maps an alias to an authenticated subject acquired by authenticating the credentials supplied by the wallet. This identity can then be used with run-as.

Arguments

This method takes the following two arguments:

A string which is the name of the alias to map to.
The wallet object representing the credentials for the run as identity.

Exceptions

None


public void enableCipherSuites(String[] cipherSuites);

Use this method to specify a subset of supported cipher suites to be used for SSL sessions.

Arguments

A string array list of cipher suites to be enabled.

Exceptions

None


public void generateVault(OutputStream stream, byte[] password);

This method generates a Vault that is written out to the stream that is passed in and encrypted using the password provided. The password may be null; the vault contains all the credentials for the system identity and the run-as map.

Arguments

This method takes the following two arguments:

The OutputStream into which to write the vault information.
A byte array representing the password used for encrypting the vault. If no password is supplied (value=null) then a non-password-based encryption will take place.

Exceptions

None


public void login (InputStream stream,

 byte[] password);

This method logs into the system using a previously generated vault and the password associated with that vault, and loads all run-as identities configured by the specified vault.

Note: Deprecated as of BES 5.2 release. Please use public void loadVault (InputStream stream, byte[] password);.

Arguments

This method takes the following two arguments:

The stream containing the vault data.
The vault password.

Exceptions

Throws org.omg.CORBA.NO_PERMISSION if login fails


public void loadVault (InputStream stream, byte[] password);

This method logs into the system using a previously generated Vault and the password associated with that Vault, and loads all run-as identities configured by the specified Vault.

Arguments

The stream containing the Vault data.
The Vault password.

Exceptions

Throws org.omg.CORBA.NO_PERMISSION if login fails.


public void login();

This method logs into the system using the vbroker.security.login.realms property. It traverses the list of realms specified and authenticates against each realm.

Arguments

A list of realms. An entry in this list may also be a formatted target name—in which case, this method collects credentials for the corresponding target without authenticating the user.

Exceptions

Throws org.omg.CORBA.NO_PERMISSION if the login fails.


public void login(String realm);

This method logs into the specified realm.

Arguments

A string which is the name of the realm to log into. The realm can be specified in the JAAS configuration or as a Formatted Target. In the case of a Formatted Target, the credentials appropriate to that Target are acquired, but no authentication is performed.

Exceptions

None


public void login(String realm, CallbackHandler handler);

This method logs into the specified realm using the specified callback handler.

Arguments

This method takes the following two arguments:

a realm to log into.
a handler to use to log into the specified realm.

Exceptions

None


public void login(CallbackHandler handler);

This method uses a specified callback handler to collect user information and login to the system.

Arguments

This method takes the classname of the callback handler to use.

Exceptions

Throws org.omg.CORBA.NO_PERMISSION if the login fails.


public void login(Wallet wallet);

This method logs into the system using a specified wallet. The resulting authentication is locally trusted. This will also set the appropriate identity. At this time, a wallet can be either of type IdentityWallet or CertificateWallet. For more information, go to com.borland.security.provider.IdentityWallet or com.borland.security.provider.CertificateWallet.

Arguments

This method takes the wallet object type with the user's credentials.

Exceptions

Throws org.omg.CORBA.NO_PERMISSION if the login fails.


public void login(Wallet[] wallets, boolean useSystemOnly);

This method logs into the system using the specified wallets.

Arguments

The wallet object types with each of the user's credentials. The useSystemOnly flag is ignored.

Note: Deprecated as of BES 5.2 release. Please use public void login(Wallet[] wallets);.

Exceptions

Throws org.omg.CORBA.NO_PERMISSION if login fails.


public void login(Wallet[] wallets);

This method logs into the system using the specified Wallets. If the corresponding realms exist locally, then the security service attempts to authenticate locally. At this time, a wallet can be either of type IdentityWallet or CertificateWallet. For more information, go to com.borland.security.provider.IdentityWallet or com.borland.security.provider.CertificateWallet.

Arguments

This method takes a wallet array listing wallets to use to log into the system.

Exceptions

Throws org.omg.CORBA.NO_PERMISSION if login fails.

public void logout();

Logs the user out.

Exceptions

None


public void logout(String realm);

This method logs the user out of the specified realm.

Arguments

The realm to log the user out of.

Exceptions

None


public void removeRunAsIdentity (String alias);

Unmaps or removes a run-as identity alias.

Arguments

A string which is the name of the run-as alias to remove.

Exceptions

None


public void setCallbackHandler(CallbackHandler callbackHandler);

Sets the default JAAS Callback Handler.

Arguments

The Callback Handler object. This can be set to null, in which case there is no default Callback Handler.

Exceptions

None


public void setSecureRandom(SecureRandom random);

This method sets the secure random to be used for generating the random numbers needed for SSL. This method sets the PRNG for JSSE-based SSL. Make sure that the SecureRandom object is seeded—that is, call setSeed on it.

Arguments

The SecureRandom object to be used.

Exceptions

None

com.borland.security.Current

This interface represents the view to the thread-specific security information. All the calls are relevant only in the context of a method invocation. This interface can be obtained from the call:


orb.resolve_initial_references("VBSecurityCurrent")

The Current interface can be used to obtain or assert an identity, get the caller and peer identities, and obtain SSL Session information. The following shows some sample code utilizing Current:


public static void main(String args[]) {

 org.omg.CORBA.ORB orb = org.omg.CORBA.ORB.init(args,null); 

 com.borland.security.Current current =

 com.borland.security.Current)orb.resolve_initial_references("VBSecurityCurrent"); 

  if(current !=null) { 

  . 

  . 

}

Methods


public Principal getCallerPrincipal ();

This method returns the original caller principal.

Returns

A java.security.Principal object.

Exceptions

None


public Principal getPeerPrincipal();

This method returns the authenticated peer principal.

Returns

A java.security.Principal associated with the peer.

Exceptions

None


public Subject getCallerSubject();

This method returns the original caller subject.

Returns

A java.security.Subject object.

Exceptions

None


public Subject getPeerSubject();

This method returns the peer subject.

Returns

A java.security.Subject object.

Exceptions

None


public SSLSession getPeerSession();

This method returns the SSLSession object associated with the invocation context.

Returns

An SSLSession object.

Exceptions

Throws org.omg.CORBA.BAD_OPERATION if:

called outside the context of a request,
or the session is over a clear TCP connection.


public void assert (Principal caller);

This method asserts a principal as the caller. All future invocations will be made with this identity as the caller.

Note: Deprecated as of BES 5.2 release. As of JDK 1.4, "assert" becomes a keyword. Please use public void asserting (Principal caller);.

Arguments

The principal to be asserted as the caller.

Returns

The principal representing the identity.

Exceptions

None


public void asserting (Principal caller);

This method asserts a principal as the caller. This operation pushes this principal on the assertion stack. This method is privileged and requires java.security.SecurityPermission("setIdentityInfo");

Arguments

The principal to be asserted as the caller.

Exceptions

None


public void assert (Subject caller);

This method asserts a subject as the caller. All future invocations are made with the specified subject identity as the caller.

Arguments

The subject to be asserted as the caller.

Exceptions

None


public void clearAssertion();

This method clears the last asserted caller from the assertion stack.

Note: Since an assertion represents a change in caller identity, not clearing an assertion implies that the assertion may remain valid (even outside the scope of the method in which the assert is called).

Exceptions

Throws java.util.NoSuchElementException if a corresponding assert is not called.

com.borland.security.provider.IdentityWallet

An IdentityWallet represents a username/password based identity that can be used with the Borland Security Provider.

You can use the IdentityWallet to specify traditional username/password/realm triads or use it to specify certificate alias/private-key-password/"CERTIFICATE"-realm triads that point to KeyStore entries. The alias represents a specific identity in the default KeyStore that can be used for authentication, for example. The realm must be set to "CERTIFICATE" to do this.

Constructors


public IdentityWallet (String username, char[] password,

String realm);

This constructor creates an IdentityWallet with the given username and password for a specified realm.

Attributes

This constructor takes the following attributes:

The username stored in the wallet.
The password associated with this identity.
The realm in which this username and password are valid. The realm can be a defined realm or a formatted target.

Exceptions

None


public IdentityWallet (String username, String Realm, Map attributes)

This constructor creates an IndentityWallet with the given username for a specified realm, and a set oprivilegege attributes for this user.

Attributes

This constructor takes the following attributes:

The username stored in the wallet.
The realm in which the username is valid. The realm can be a defined realm or a formatted target.
The set of privilege attributes for the specified user. The Map values can be a string or a java.util.set containing strings.

Exceptions

None


public IdentityWallet (String username, char[] password,

String realm, String[] groups)

This constructor creates an IndentyWallet with the given username, password, realm, and a list of groups to which the user belongs.

Note: Deprecated as of BES 5.2 release. Please use public IdentityWallet (String username, char[] password, String realm, String[] groups).

Attributes

This constructor takes the following attributes:

The username stored in the wallet.
The password which is ignored because this identity can only be used for assertion.
The realm in which the username is valid. The realm can be a defined realm or a formatted target.
The list of groups to which the user belongs.

Exceptions

None


public IdentityWallet (String username, char[] password, String realm, String[] groups)

This constructor creates an IndentyWallet with the given username, password, realm, and a list of groups to which the user belongs.

Attributes

This constructor takes the following attributes:

The username stored in the wallet.
The password which is ignored because this identity can only be used for assertion.
The realm in which the username is valid. The realm can be a defined realm or a formatted target.
The list of groups to which the user belongs.

Exceptions

None


public IdentityWallet (String username, String realm, String[] groups)

This constructor creates an IndentyWallet with the given username for a specified realm, and a list of groups to which this user belongs.

Attributes

This constructor takes the following attributes:

The username stored in the wallet.
The realm in which the username is valid. The realm can be a defined realm or a formatted target.
The list of groups to which the user belongs.

Exceptions

None

Methods


String getTarget();

This method gets the target that this identity represents.

Returns

The target name.

Exceptions

None

com.borland.security.provider.CertificateWallet

This wallet is used for certificate identities. Use the CertificateWallet to specify certificate-based identities that may be used for authentication. You can also pass PKCS12 byte-streams containing certificates and private keys.

Constructors


public CertificateWallet (String alias,

 java.security.cert.X509Certificate[] chain,

 java.security.PrivateKey key,

 char[] password)

This constructor creates a certificate wallet with the given certificate chain and the private key as a PKCS8.

Attributes

This constructor takes the following attributes:

The alias name to use to identify the passed certificates and private keys.
The user's certificate chain array. The chain must be ordered with the user's certificate being the 0th element and the root of the chain being the last element.
The PKCS8 encoded private key for this identity.
The password used to unlock the private key.

Exceptions

Throws org.omg.CORBA.BAD_PARAM if invalid parameters are entered.


public CertificateWallet (byte[] pkcs12DERbytes, char[] password)

Use this constructor to create a certificate wallet using a DER-encoded PKCS12 certificate.

Attributes

This constructor takes the following attributes:

The PKCS12 certificate.
The password used to unlock the PKCS12 and the internal private key.

Exceptions

Throws org.omg.CORBA.BAD_PARAM if invalid parameters are entered.


public CertificateWallet (KeyStore ks, char[] keyPassword);

This constructor creates a certificate wallet with the given KeyStore and the private key password. This constructor uses the first identity from which it is able to recover a private key using the given password.

Attributes

This constructor takes the following attributes:

The keystore object.
The private key password.

Exceptions

Throws org.omg.CORBA.BAD_PARAM if invalid parameters are entered.


public CertificateWallet (X509Certificate[] chain);

This constructor creates a certificate wallet to represent the identity corresponding to the given certificate chain.

Note: A certificate identity created using this constructor cannot be used to establish secure connections with authentication because there is no private key. A wallet created using this constructor may only be used to assert an identity represented by the given certificate chain (used for example, at perimeter boundaries, where the SSL connection that received the request is not managed by the Borland Security Service).

Attributes

The user's certificate chain. The chain must be ordered with the 0th element being the user's certificate and the root of the chain being the last element.

Exceptions

Throws org.omg.CORBA.BAD_PARAM if invalid parameters are entered.


public CertificateWallet (String filename,

 char[] filePassword, String alias,

 char[] password)

This constructor creates a certificate wallet using a DER encoded PKCS12 certificate.

Attributes

This constructor takes the following attributes:

The filename path to the key store.
The File password.
The alias name to use to identify the passed certificates and private keys.
The password used to access the private key stored in the key store.

Exceptions

None


public CertificateWallet (String fileName, char[] chain, filePassword,

String alias, char[] password, short usage)

This constructor creates a certificate wallet from a key store on disk for a specific role.

Attributes

This constructor takes the following attributes:

The file name path to the KeyStore.
The key store file password.
The alias name to use to identify the passed certificates and private keys.
The private key password for the identity represented by the given alias.
The type of certificate usage. The following are the possible values:
Certificate short usage values

Value Description

ALL This identity is for server and client roles.

SERVER This identity is for server role only.

CLIENT This identity is for client role only.

Value	Description
ALL	This identity is for server and client roles.
SERVER	This identity is for server role only.
CLIENT	This identity is for client role only.

Exceptions

None

Methods


Public String getTarget()

This method gets the target that this certificate wallet identity represents.

Returns

The target object.

Exceptions

None


Public short getUsage()

Use this method to get the usage for a Certificate wallet identity.

Returns

Based on the identity usage, the following are the possible values that the target returns:

getUsage() certificate usage values

Value	Description
Certificate#ALL	This identity is for all roles.
Certificate#SERVER	This identity is for server role only.
Certificate#CLIENT	This identity is for client role only.

Exceptions

None


Public void setUsage(short usage)

Use this method to set the usage for a certificate wallet identity.

Arguments

setUsage certificate usage values

Value	Description
ALL	Sets this identity for all roles.
CLIENT	Sets this identity for client role only.
SERVER	Sets this identity for server role only.

Exceptions

None

Quality of Protection APIs and properties

com.borland.security.csiv2.ClientQoPConfig

The ClientQoPConfig class represents the Quality of Protection (QoP) configuration for CSIv2 clients. Use this class to set a policy on the target by using the orb.set_policy_overrides () call. Use the create method on the ClientQoPConfigDefaultFactory class to create a ClientQoPConfig object, and then set it on the target object.

IDL definition


#pragma prefix "borland.com"

module csiv2 {

  ...



  typedef short TransportQoP;



  value ClientQoPConfig {

    public TransportQoP transport;

    public boolean trustInTarget;



    factory create (in TransportQoP trans, in boolean trustInTarget);

  };



  ...

}

Attributes

This class consists of the following attributes:

transportQoP–which can be set to the following:

ClientQoPConfig transportQoP values

Value	Description
ClientQoPPolicy.CLEAR_ONLY	No secure transport is necessary
ClientQoPPolicy.SECURE_ONLY	Only secure connections are permitted
ClientQoPPolicy.USE_ANY	(default) Any method of transport is allowed

trustInTarget–(true|false) if set to true, requires the target to prove its identity to the client. The default is true.

Example


  org.omg.CORBA.Object target = ...

  ... 

  // secure transport and trustInTarget required

  ClientQoPConfig clientQop = new ClientQoPConfigDefaultFactory().create (ClientQoPPolicy.SECURE_ONLY, true);

  Any any = orb.create_any ();

  ClientQoPConfigHelper.insert (any, clientQop);

  Policy clientQopPolicy = orb.create_policy (CLIENT_QOP_CONFIG_TYPE.value, any);



  target._set_policy_override (new Policy [] {clientQopPolicy}, SetOverrideType.SET_OVERRIDE);

  ...

com.borland.security.csiv2.ServerQoPConfig

This class represents the Quality of Protection (QoP) configuration for CSIv2 Servers.

IDL definition


#pragma "borland.com"



module csiv2 {

  typedef short TransportQoP;



  ... ...

  valuetype ServerQoPConfig {

    public boolean disable;

    public TransportQoP transport;

    public boolean supportIdentityAssertion;

    public AccessPolicyManager access_manager;

    public boolean trustInClient;

    public CORBA::StringSequence realms;

    ... ...



    factory create (in boolean disable, in TransportQoP transport,

                    in boolean trustInClient, 

                    in AccessPolicyManager access_manager);

  };

  ... ...

};

Use the ServerQoPConfig policy to apply quality-of-protection policies to individual POAs in servers and tune their security-related behavior. Use the create method on the ServerQoPConfigDefaultFactory class to create an object, updating the setting if necessary, and apply it when creating the POA.

Attributes

This class consists of the following attributes:

disable–setting this attribute to true disables all security and QoP values for such a connection. The transport will be clear, no trustInClient will be enforced, and it will be assumed that there is no access_manager. Use this option as a master switch to turn off security. When applied to a POA, it disables all security-related aspects on that POA.

transportQoP–which can be set to the following:

ServerQoPConfig transportQoP values

Value	Description
ServerQoPPolicy.CLEAR_ONLY	No secure transport is necessary
ServerQoPPolicy.SECURE_ONLY	Only secure connections are permitted
ServerQoPPolicy.ALL	Any method of transport is allowed

supportIdentityAssertion–(true|false) indicates if the server supports identity assertion. The default is true.
AccessPolicyManager–an instance of the interface accessing the RoleDB to set access policies for POA objects.
trustInClient–(true|false) if set to true, requires the client to provide an authenticated identity. The default is false.
realms–a sequence of strings indicating the authenticating realms exposed by the server IOR. By default, all of the authenticating realms on the server side are exposed in the IOR.

Example


  ... 

  // secure transport and trustInClient required

  ServerQoPConfig ServerQop = new ServerQoPConfigDefaultFactory().create (false, ServerQoPPolicy.SECURE_ONLY, true, null);

  Any any = orb.create_any ();

  ServerQoPConfigHelper.insert (any, ServerQop);

  Policy serverQopPolicy = orb.create_policy (SERVER_QOP_CONFIG_TYPE.value, any);



  org.omg.CORBA.Policy [] policies = { ..., serverQopPolicy};



  myPOA = rootPOA.create_POA (serverID, rootPOA.the_POAManager (), policies);

  ...