Security SPI for C++

This section describes the Service Provider Interface (SPI) classes as defined for VisiSecure for C++. These SPI classes provide advanced security functionality and allow other security providers to plug their own implementation of security services into VisiSecure for their use.

Plugin Mechanism and SPIs

VisiSecure for C++ provides interfaces for you to plug in your own security implementations. In order for the ORB to find your implementation, all plugins must use the REGISTER_CLASS macro provided by VisiSecure to register your classes. The name of the class must be specified in full together with its namespace upon registration. Namespace must be specified in a normalized form supported by VisiSecure, using either a '.' or '::' separated-string starting from the outer namespace. For example:

MyNameSpace {
class MyLoginModule {
......
}
}

Thus MyLoginModule shall be specified as either MyNameSpace.MyLoginModule or MyNameSpace::MyLoginModule.

There are six pluggable components:

•	LoginModules: You can implement your own login modules by extending vbsec::LoginModule. To use the login module, you need to set it in the authentication configuration file, just like any other login module.

•	Callback handlers: You can implement your own callbacks by extending vbsec::CallbackHandler. To use the callback, you need to set it in the authentication configuration file, just like any other callback handler.

•

Identity adapters, Mechanism adapters, and Authentication Mechanisms: These interfaces are provided for users to implement their own authentication mechanisms and identity interpretations. IdentityAdaptor is to interpret identities, MechanismAdaptor is a specialized identity adaptor which also changes target information. AuthenticationMechanism is a pluggable service to authenticate users.

To use these plug-ins, you need to set the vbroker.security.identity.xxx properties to define the plug-ins and their properties. For example, an identity adapter or mechanism adapter could specify:

vbroker.security.identity.adapters=MyAdapter
vbroker.security.adapter.MyAdapter.property1=value1
vbroker.security.adapter.MyAdapter.property2=value1

while an authentication mechanism would provide:

vbroker.security.identity.mechanisms=MyMechanism
vbroker.security.adapter.MyMechanism.property1=value1
vbroker.security.adapter.MyMechanism.property2=value2

The properties specified will be passed to the user plug-in during initialization as a string map. The map contains truncated key/value pairs like property1, value1.

•	Attribute codec: This allows you to plug in an attribute codec to encode and decode attributes in their own format. VisiSecure for C++ has one build-in codec, the ATS codec.

To use your codec plug-in, you need to set properties to define the codecs and their properties. For example:

vbroker.security.identity.attributeCodecs=MyCodec
vbroker.security.adapter.attributeCodec.property1=xxx
vbroker.security.adapter.attributeCodec.property2=xxx

The properties specified will be passed to the user plug-in during initialization as a string map.

•

Authorization service provider: You can plugin an authorization service for each authorization domain. VisiSecure has its default implementation, which uses the rolemap. Like the other pluggable services, you will need to define the authorization service with properties which are then passed as string maps. For example:

vbroker.security.auth.domains=MyDomain
vbroker.security.domain.MyDomain.provider=MyProvider
vbroker.security.domain.MyDomain.property1=xxx
vbroker.security.domain.MyDomain.property2=xxx

•

Trust provider: This allows you to plug in an assertion trust mechanism. Assertion can happen in multi-hop scenarios, or can be explicitly called through assertion API. The server can have rules to determine whether the peer is trusted to make the assertion or not. The default implementation uses property setting to configure trusted peers on the server side. During runtime, the peer must pass authentication and authorization in order to be trusted to make assertions.

Like the other pluggable services, you will need to define the authorization service with properties which are then passed as string maps. For example:

vbroker.security.trust.trustProvider=MyProvider
vbroker.security.trust.trustProvider.MyProvider.property1=xxx
vbroker.security.trust.trustProvider.MyProvider.property2=xxx

There can be only one trust provider specified for the whole security service.

Providers

Each provider instance is created by the VisiSecure 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 VisiSecure parses the property and passes the options to the corresponding provider. The following table shows the properties for plugging in different provider implementations.

Module Name	Property to set	Interface to implement	Options Prefix
IdentityAdapter	vbroker.security.identity.adapters	vbsec::IdentityAdapter	vbroker.security.identity.adapter.<name>
Authentication Mechanism	vbroker.security.identity.mechanisms	vbsec::AuthenticationMechanisms	vbroker.security.identity.mechanism.<name>
AttributeCodec	vbroker.security.identity.attributeCodecs	vbsec::AttributeCodec	vbroker.security.identity.attributeCodec.<name>
TrustProvider	vbroker.security.trustProvider	vbsec::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 VisiSecure.

•

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 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 VisiSecure 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.

vbsec::LoginModule

LoginModule serves as the parent of all login modules. User plugin login modules must extend this class. Login modules are configured in the authentication configuration file and called during the login process. Login modules are responsible for authenticating the given subject and associating relevant Principals and Credentials with the subject. They are also responsible for removing and disposing of such security information during logout.

Include File

The vbauthn.h file should be included when you use this class.

Methods

void initialize (Subject* subj=0, CallbackHandler *handler=0, LoginModule::states* sharedStates=0, LoginModule::options* options=0)

This method initializes the login module.

Arguments

This method utilizes the following four arguments:

•	subj: the subject to be authenticated.

•	handler: the callback handler to use.

•	sharedStates: additional authentication state provided by other login modules. Currently not used.

•	options: configuration options specified in the authentication configuration file.

Returns

Void.

bool login()

Performs the login. This is called during the login process. The login module shall authenticate the subject located in the module and determine if the login is successful.

Returns

true if the login succeeds, false otherwise.

bool logout()

Performs the logout. This is called during the logout process. The login module shall logout the subject located in the module and determine if the logout is successful. The login module might remove any credentials or identities that were established during login and dispose of them.

Returns

true if the logout succeeds, false otherwise.

bool commit()

Commits the login. This is part of the login process, called when the login succeeds according to the configuration options specified in the pertinent login modules. The login module then associates relevant Principals and Credentials with the Subject located in the module if its own authentication attempt succeeded. Or if not, it shall remove and destroy any state that was saved before.

Returns

true if the commit succeeds, false otherwise.

bool abort()

Aborts the login. This is part of the login process, called when the overall login fails according to the configuration options specified in the login modules. The login module shall remove and destroy any state that was saved before.

Returns

true if the abort succeeds, false otherwise.

vbsec::CallbackHandler

CallbackHandler is the mechanism that produces any necessary user callbacks for authentication credentials and other information. Seven types of callbacks are provided. There is a default handler that handles all callbacks in interactive text mode.

Include file

The vbauthn.h file should be included when you use this class.

Methods

void handle (Callback::array& callbacks)

Handle the callbacks.

Arguments

the array of callbacks to be processed.

Returns

Void.

vbsec::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 VisiSecure

The following IdentityAdapters are provided with the VisiSecure:

•	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

Virtual void initialize (const std::string& name, ::vbsec::InitOptions&) =0;

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 InitOptions for the specified IdentityAdapter.

Exceptions

Throws InitializationException if initialization fails.

virtual std::string getName() const=0;

This returns the name of the IdentityAdapter.

Returns

The name of the IdentityAdapter.

Exceptions

none

virtual ::CSI::IdentityToken* exportIdentity(::vbsec::Subject&, ::CSI::IdentityToken&) =0;

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.

virtual void importIdentity (::vbsec::Subject&, ::CSI::IdentityToken&) =0;

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.

virtual ::vbsec::Privileges* getPrincipal (::vbsec::Subject&anp;) =0;

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

Arguments

The principal subject.

Returns

A Principal object.

Exceptions

none

virtual ::vbsec::Privileges* getPrivileges (::vbsec::Subject&) =0;

Arguments

The target subject.

Returns

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

Exceptions

none

virtual ::vbsec::setPrivileges (::vbsec::Privileges*) =0;

This methods sets the privilege attribute for the identity.

Arguments

The privilege attribute to be set for the identity.

Exceptions

none

virtual void deleteIdentity (::vbsec::Subject&) =0;

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

vbsec::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 VisiSecure, 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

virtual const ::CSI::StringOID_var getOid() const =0;

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

virtual ::vbsec::Target* getTarget (const std::string& realm, const std::vector<AppConfigurationEntry*>&) =0;

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

The corresponding target object.

Exceptions

none

virtual ::vbsec::Target* getTarget (const ::CSI::GSS_NT_ExportedName&) =0;

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

vbsec::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 VisiSecure 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.

virtual ::vbsec::Subject* acquireCredentials (::vbsec::Target&, ::vbsec::CallbackHandler*) =0;

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

virtual ::vbsec::Subject* acquireCredentials (const std::string& target, ::vbsec::CallbackHandler*) =0;

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

virtual void destroyPrivateCredentials (::vbsec::Subject&) =0;

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

virtual ::CORBA::OctetSeq* createInitContext (::vbsec::Subject&) =0;

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.

virtual ::vbsec::Target* processInitContext (::vbsec::Subject&, ::CORBA::OctetSeq&) =0;

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

virtual ::CSI::GSSToken* createFinalContext (::vbsec::Subject&) =0;

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

Arguments

The Subject.

Returns

A final context token.

Exceptions

none

virtual void processFinalContext (::vbsec::Subject&, ::CORBA::OctetSeq&) =0;

Consumes a final context token returned by the server.

Arguments

The target subject.

Exceptions

none

virtual ::CSI::GSSToken* createErrorContext (::vbsec::Subject&) =0;

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

Arguments

The target subject.

Returns

An error context token.

Exceptions

none

virtual ::vbsec::Subject* processErrorContext (::vbsec::Subject&, ::CSI::GSSToken&, ::vbsec::CallbackHandler*) =0;

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

vbsec::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

virtual std::string getName () const =0;

This method returns the display name of the target.

Returns

The target name string.

Exceptions

none

virtual ::CSI::OID getOid () const =0;

This method returns the target OID.

Returns

The target OID string.

Exceptions

none

virtual ::CORBA::OctetSeq getEncodedName () const =0;

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

Returns

The encoded target name.

Exceptions

none

vbsec::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. One Authorization Service is installed for 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 important 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 is again consulted to return the alias that must be used to “run-as” in the context of the rules specified for this authorization domain.

Methods

virtual void initialize (const std::string& name, ::vbsec::InitOptions& options) =0;

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 SimpleLogger instance used for login in the current system.
LogLevel	An integer value denoting the security logging level.

Exceptions

Throws InitializationException if initialization of the Authorization provider fails.

virtual std::string getName() const =0;

Returns the name for this Authorization Service implementation.

Returns

The Authorization Service name.

Exceptions

none

virtual ::vbsec::PermissionCollection* getPermissions (const ::vbsec::Resource* resource, const ::vbsec::Privileges* callerPrivileges) =0;

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 Privileges.

•	The resource object upon which access is to be attempted.

Returns

A PermissionCollection object represents this subject's Permissions.

Exceptions

none

vbsec::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

virtual std::string getName () const =0;

Returns the string representation of the resource being accessed.

Returns

Name of the resource.

Exceptions

none

vbsec::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. 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

Privileges (const std::string& name, ::vbsec::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

::vbsec::Subject& getSubject() const ;

This method returns the subject that the privileges object represents.

Returns

The target subject.

Exceptions

none

std::string getSubjectName() const;

This method returns the name of the associated subject object.

Returns

The target subject.

Exceptions

none

const ::vbsec::ATTRIBUTE_MAP& getAttributes() const ;

This method returns the attribute map of the user.

Returns

The user's attribute map.

Exceptions

none

void setDBAttributes (const ::vbsec::ATTRIBUTE_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

const ::vbsec::ATTRIBUTE_MAP* getDNAttributes() const;

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

Returns

User's DN Attributes map, which is not modifiable.

Exceptions

none

bool isDestroyed() const;

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

Returns

true|false

Exceptions

none

std::string toString() const;

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

vbsec::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

virtual void initialize (const std::string& name, vbsec::InitOptions& options) =0;

This method initializes this instance of the AttributeCodec implementation. There can be multiple implementations 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 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.

virtual std::string getName() const =0;

This method returns the name of the provider implementation.

Returns

The provider name string.

Exceptions

none

virtual CSIIOP::ServiceConfigurationList* getPrivilegeAuthorities() const =0;

This method returns a list of supported privilege authorities.

Returns

A list of privilege authorities.

Exceptions

none

virtual CSI::AuthorizationElementType getSupportedEncoding() const = 0;

This method returns the supported AuthorizationElement type.

Returns

An AuthorizationElement type.

Exceptions

none

virtual bool supportsClientDelegation() const =0;

Returns whether this implementation supports ClientDelegation.

Returns

true|false

Exceptions

none

virtual CSI::AuthorizationToken* encode (const CSIIOP::ServiceConfigurationList& privilege_authorities, vbsec::Privileges& caller_privileges, vbsec::Privileges& asserter_privileges) =0;

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.

virtual void decode (const ::CSI::AuthorizationToken& encoded_attributes, vbsec::Privileges& caller_privileges, vbsec::Privileges& asserter_privileges) =0;

This method decodes authorization elements and populates the corresponding privilege 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 Authorization Elements.

•	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.

vbsec::Permission

Permission represents the authorization information to access resources. Every permission has a name, which can be interpreted only by the actual implementation.

Include file

The vbsecspishared.h file should be included when you use this class.

Methods

bool implies (const Permission& p) const

Evaluate if the permission implies another given permission. This is used during the authorization process to determine if the caller permissions imply the permissions required by the resource. Access will be granted if the caller permissions imply the required permission, or denied if not.

Arguments

the permission p to be evaluated.

Returns

true if the permission implies an existing permission, false otherwise.

bool operator==(const Permission& p) const

Checks if the permission equals another given permission.

Arguments

the permission p to be evaluated.

Returns

true if the permissions are equal, false otherwise.

std::string getName () const

Gets the name of the permission.

Returns

The name of the permission.

std::string getActions () const

Get the actions of the permission as a string. It is only interpreted by the actual implementation.

Returns

The string representation of the action for the permission.

std::string toString () const

Get the string representation of the permission.

Returns

The string representation of the permission.

vbsec::PermissionCollection

PermissionCollection represents a collection of permissions.

Include file

The vbsecspishared.h file should be included when you use this class.

Methods

bool implies (const Permission& p) const

Evaluate if the PermissionCollection implies the given permission.

Arguments

the permission p to be evaluated.

Returns

true if the PermissionCollection implies the given one, false otherwise.

vbsec::RolePermission

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

Constructors

RolePermission (const std::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

virtual bool implies (const Permission& permission) const;

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:

1	the permission object given is an instance of RolePermission, and

2	the name of the permission object given equals the name of this RolePermission.

Arguments

A Permission object to check.

Returns

True|False

Exceptions

none

virtual std::string getActions() const;

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

vbsec::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 underlying 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:

1	Provide class implementations representing a proxy endorsement attribute.

2	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.

3	Provide the method implementation based on the proxy endorsement attribute of the caller and the privileges of the asserter.

This type of 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 VisiSecure installation. For more information, see “Trust assertions and plug-ins”.

Methods

virtual void initialize (::vbsec::InitOptions&, std::map<std::string, std::string>&) =0;

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 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.

virtual bool isAssertionTrusted (const ::vbsec::Subject&, const ::vbsec::Privileges&) =0;

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

vbsec::InitOptions

InitOptions is a data structure passed to user plug-ins during initialization calls that facilitates the initialization process.

Include file

The vbsecspishared.h file should be included when you use this class.

Data Members

std::map<std::string, std::string>* options

A string map containing name/value pairs presenting parsed property setting.

::PortableInterceptor::ORBInitInfo* initInfo

Object representing the ORB initialization information.

::IOP::Codec* codec

An IOP Codec object.

::vbsec::SimpleLogger* logger

A logger object.

int logLevel

The log level currently configured for the security service.

vbsec::SimpleLogger

SimpleLogger 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.

Include file

The vbsecspishared.h file should be included when you use this class.

Methods

::std::ostream& WARNING()

Returns the logging output stream for warning messages.

Returns

The logging output stream for LEVEL_WARNING.

::std::ostream& NOTICE()

Returns the logging output stream for notice messages.

Returns

The logging output stream for LEVEL_NOTICE, or a fake stream if the log level is set below LEVEL_NOTICE.

::std::ostream& INFO()

Returns the logging output stream for info messages.

Returns

The logging output stream for LEVEL_INFO, or a fake stream if the log level is set below LEVEL_INFO.

::std::ostream& DEBUG()

Returns the logging output stream for debug messages.

Returns

The logging output stream for LEVEL_DEBUG, or a fake stream if the log level is set below LEVEL_DEBUG.