5 — Extended Interfaces

[Previous] [Next] [Table of Contents] [Index]

This chapter describes interfaces provided by Gradient Technologies to supplement the interfaces of the CORBA Security Specification. These extended interfaces provide additional functionality for administrators and application developers.

Gradient extended interfaces include:

GradAuditPolicy Interface
GradCredentials Interface
GradCurrent Interface
GradDelegationPolicy
GradDomainAccessPolicy
GradDomainManager
GradPolicy
GradReceivedCredentials Interface
GradRequiredRights Interface
GradSecureInvocationPolicy
GradVault

5.1 GradAuditPolicy Interface

This interface derives from AuditPolicy and adds operations to make administration easier.

The GradAuditPolicy interface supports the following operations:

enumerate_events
enumerate_interfaces
get_audit_channel

enumerate_events

The enumerate_events method returns a list of the events that have a selector list for the specified interface and within the audit policy.

Syntax

IDL 

Security::AuditEventTypeList enumerate_events(in CORBA::RepositoryId 
interface_name)

Parameters

interface_name
Interface name.

Return Value

List of event types defined for interface.

enumerate_interfaces

The enumerate_interfaces method returns a list of the interfaces that have a set audit policy.

Syntax

IDL 

CORBA::RepositoryIdSeq enumerate_interfaces()
C++ 





Java























 Return Value






List of interface repository IDs.






 get_audit_channel






The get_audit_channel method allows an administrator to retrieve the audit policy's audit channel identifier. This operation is not provided as an attribute because the matching set_audit_channel is defined on the AuditPolicy interface.






 Syntax




 
 





IDL




Security::AuditChannelId get_audit_channel()




















 Return Value






Audit channel defined for the policy. 






5.2  GradCredentials Interface






This interface extends the Credentials interface to allow application developers to determine if the credentials belong to a specific user or group.  The two simplest methods, of the three described here, automatically make use of the GradVault interface.





The GradCurrent interface supports the following operations:



is_principal



is_in_group



has_attributes






 is_principal






The is_principal method determines if the credentials belong to the named user. If the specified user does not exist, this method throws a CORBA::BAD_PARAM exception.






 Syntax




 
 





IDL




boolean is_principal(in string principal_name)




















 Parameters







principal_name





String containing principal name.






 Return Value






True — The credentials belong to the named user.





False — The credentials do not belong to the named user.






 is_in_group






The is_in_group method determines if the credentials belong to the named group.





If the specified group does not exist, this method throws a CORBA::BAD_PARAM exception.






 Syntax




 
 





IDL




boolean is_in_group(in string group_name)




















 Parameters







group_name






String containing group name.







 Return Value






True — The credentials belong to the named group.





False — The credentials do not belong to the named group.






 has_attributes






The has_attributes method determines if the credentials contain all of the passed-in attributes, allowing the application developer to check if the credentials belong to multiple groups all at once. To create the attributes for the parameter attribute array, use the methods of the GradVault interface.






 Syntax




 
 





IDL




boolean has_attributes(in Security::AttributeList attributes)




















 Parameters







attributes






List of security attributes.







 Return Value






True — The credentials contain all the passed attributes.





False — The credentials do not contain all the passed attributes.






5.3  GradCurrent Interface






The GradCurrent interface contains miscellaneous routines, which are not part of the CORBA Security Specification, to assist application developers. For example, GradCurrent can be used to retrieve the current time in the appropriate format for calls to AuditChannel::audit_write and can be used to access the domain hierarchy.





The GradCurrent interface supports the following operations:



current_domain



current_time



root_domain






 current_domain






The current_domain attribute returns the domain manager for the domain specified by the GradPolicy command-line setting. The current domain is the domain used to retrieve policies that affect the running of the CORBA security service for the running application.






 Syntax




 
 





IDL




readonly attribute GradDomainManager current_domain




















 Return Value







GradDomainManager





Domain manager of capsule's domain.






 current_time






The current_time attribute allows applications to generate the required current time parameter for AuditChannel::audit_write.





This attribute returns the current time as a UtcT. The UtcT time data structure is opaque even though the fields are defined in the IDL file. The field definitions allow the UtcT to be passed as a parameter, but applications should not assume that fields can be directly read. 






 Syntax




 
 





IDL




readonly attribute Security::UtcT current_time




















 Return Value






Current time.






 root_domain






The root_domain attribute returns the domain manager for the root domain of the policy domain hierarchy.






 Syntax




 
 





IDL




readonly attribute GradDomainManager root_domain




















 Return Value






Root domain manager of domain hierarchy.






5.4  GradDelegationPolicy






This interface derives from DelegationPolicy and includes an operation to unset delegation options.





The GradDelegationPolicy interface supports the following operations:



enumerate_interfaces



unset_delegation_mode






 enumerate_interfaces






The enumerate_interfaces method returns a list of the interfaces that have a set delegation policy.






 Syntax




 
 





IDL




CORBA::RepositoryIdSeq enumerate_interfaces()




















 Return Value






List of interface repository IDs.






 unset_delegation_mode






The unset_delegation_mode method clears the delegation mode settings for the interface you specify. After the setting is cleared, the default interface setting is used.






 Syntax




 
 





IDL




void unset_delegation_mode(
  in  CORBA::RepositoryId  interface_name
);




















 Parameters







interface_name






CORBA::RepositoryId data type. Name of the interface 
whose delegation mode you are clearing.







 Return Value






None.






5.5  GradDomainAccessPolicy






This interface extends from DomainAccessPolicy and supports interfaces to make access policy management simpler.  





The GradDomainAccessPolicy supports the following operations:



get_all_domain_effective_rights



get_domain_effective_rights






 get_all_domain_effective_rights






The get_domain_effective_rights method is similar to DomainAccessPolicy::get_all_effective_rights, except that it returns the rights granted by the access policy in the current domain and the access policies in any higher domains.  This is the method that NetCrusader/CORBA uses at runtime to find the set of effective rights before making an access control decision.





This operation returns the rights granted for all rights families, in the current domain only.






 Syntax




 
 





IDL




Security::RightList get_all_domain_effective_rights(
  in    Security::AttributeList    attrib_list,
  in    Security::DelegationState  del_state
);




















 Parameters







attrib_list






AttributeList data type. Security attributes whose effective rights 
you are requesting. Use only AccessId, GroupId, PrimaryGroupId, or Public 
attributes in the attrib_list.






del_state






DelegationState data type. Delegation state whose rights you are 
requesting.







 Return Value






RightsList of effective rights.






 get_domain_effective_rights






The get_domain_effective_rights method returns the rights granted by a domain (rather than the entire domain hierarchy) for a particular rights family.





This method is similar to DomainAccessPolicy::get_effective_rights, except that it returns the set of rights granted by the access policy in the current domain and the access policies in any higher domain.






 Syntax




 
 





IDL




Security::RightsList get_domain_effective_rights(
  in  Security::AttributeList  attrib_list,
  in  Security::DelegationState del_state,
  in  Security::ExtensibleFamily rights_family
);




















 Parameters







attrib_list






AttributeList data type. Security attributes whose effective rights 
you are requesting. Use only AccessId, GroupId, PrimaryGroupId, or Public 
attributes in the attrib_list.






del_state





DelegationState data type. Delegation state whose rights you are requesting.






rights_family





ExtensibleFamily data type. Rights family for which you are requesting rights.






 Return Value






RightsList of effective rights.






5.6  GradDomainManager






This interface allows an administrator or the security runtime to navigate the domain hierarchy. This interface derives from the CORBA::DomainManager interface described in the CORBA/IIOP Specification and referenced in the CORBA Security Specification.





The GradDomainManager interface supports the following operations:



add_domain



add_policy



admins



cache_lifetime



delete_domain



description



domain_name



get_sub_domain_manager



grant_admin_rights



grant_user_rights



parent_domain



remove_policy



revoke_rights



simple_domain_name



sub_domains



users






 add_domain






The add_domain method creates a subdomain inside the current domain.






 Syntax




 
 





IDL




void add_domain(in string domain)




















 Parameters







domain






String for the name of the new subdomain. The string must not 
include the characters colon (:) or slash (/).







 Return Value






None.






 add_policy






The add_policy method creates a new policy and adds it to the domain. The newly-created policy is returned as a return value. If the domain already contains a policy of the same type, then this operation throws a CORBA::BAD_PARAM exception and the existing policy is not modified.





See Current::get_policy for a list of supported policy types. 






 Syntax




 
 





IDL




CORBA::Policy add_policy(in CORBA::PolicyType policy_type)




















 Parameters







polic_typey






CORBA::Policy data type. Policy to add to the domain. For a list 
of supported policy types, refer to the section get_policy on page 28.







 Return Value






New policy.






 admins






The admins attribute returns the set of security attributes that currently have domain administration rights assigned to them.






 Syntax




 
 





IDL




readonly attribute Security::AttributeList admins




















 Return Value






AttributeList of security attributes.






 cache_lifetime






The cache_lifetime attribute controls the length of time in seconds that data remains in the cache. The default is 60 minutes. You can use the special constant infinite_cache_lifetime to prevent the domain from ever updating its cache.





Policy settings are cached in memory based on the values in the Security Server. The cache is always updated when the local application changes policy settings, but if a different application changes policy, policy settings in memory may be out of synch with those in the Security Server during the time it takes them to expire. 






 Syntax




 
 





IDL




readwrite attribute unsigned long cache_lifetime




















 Parameters







cache_lifetime 






Unsigned long data type. New cache lifetime in seconds.







 Return Value






Current cache lifetime in seconds.






 delete_domain






The delete_domain method deletes the current domain from the Security Server. After calling this method, the interface is no longer usable and should be released. 





You cannot delete the root domain. This method will throw CORBA::BAD_PARAM if an application attempts to delete the root domain.






 Syntax




 
 





IDL




void delete_domain()




















 description






The description attribute allows an administrator to view or update a domain's description.






 Syntax




 
 





IDL




readwrite attribute string description




















 Parameters







description






Used only with write. String value for the new description.







 Return Value






Description string (only for read).






 domain_name






The domain_name attribute returns the fully-qualified name of a domain. The name includes the names of all parent domains, separated by forward slashes. For example:





<parent-domain/next-domain/this-domain>






 Syntax




 
 





IDL




readonly attribute string domain_name




















 Parameters






None.






 Return Value






String value for domain name and parent domains.






 get_sub_domain_manager






The get_sub_domain_manager method returns the domain manager for the subdomain you specify. The subdomain name may be a qualified name, relative to the current domain. You cannot use ".." to navigate up the domain hierarchy; instead, use parent_domain. If the sub-domain is not found, then the return parameter will be GradDomainManager::_nil().






 Syntax




 
 





IDL




GradDomainManager get_sub_domain_manager(in string sub_domain)




















 Parameters







sub_domain






String value for subdomain name. This may be a qualified name 
(relative to the current domain). 







 Return Value






Subdomain manager. If the subdomain is not found, this value will be GradDomainManager::_nil(). 






 grant_admin_rights






The grant_admin_rights method allows the domain administrator to grant administration rights to the domain. Rights are granted based on the security attributes that a particular principal holds. 





There are three rights levels: Administrator, User, and None (deny access to domain). Administrators hold User rights, but do not appear in the list of users.





To reduce the rights assigned to a security attribute, call grant_admin_rights with a rights_type that has fewer rights than currently assigned to the attribute. 






 Syntax




 
 





IDL




void grant_admin_rights(
  in Security::SecAttribute   priv_attr
);




















 Parameters







priv_attr






SecAttribute data type. Security attribute that a principal should 
hold to be granted the specified right.







 grant_user_rights






The grant_user_rights method allows the domain administrator to grant user rights to the domain. Rights are granted based on the security attributes that a particular principal holds. 





There are three rights levels: Administrator, User, and None (deny access to domain). Administrators hold User rights, but do not appear in the list of users.





To reduce the rights assigned to a security attribute, call grant_user_rights with a rights_type that has fewer rights than currently assigned to the attribute. 






 Syntax




 
 





IDL




void grant_user_rights(
  in Security::SecAttribute   priv_attr
);




















 Parameters







priv_attr






SecAttribute data type. Security attribute that a principal should 
hold to be granted the specified right.







 parent_domain






The parent_domain attribute returns the parent domain. If the current domain is the root, then the call returns GradDomainManager::_nil().





Every domain has exactly one parent, except for the root domain, which has no parent.






 Syntax




 
 





IDL




readonly attribute GradDomainManager parent_domain




















 Return Value






Parent domain.






 remove_policy






The remove_policy method removes the specified policy from the domain.  If a policy of the specified type does not belong to the domain, this call will throw a CORBA::BAD_PARAM exception.






 Syntax




 
 





IDL




void remove_policy(in CORBA::PolicyType policy_type)




















 Parameters







policy_type





CORBA::PolicyType data type. Type of policy.






 revoke_rights






The revoke_rights method allows the domain administrator to revoke rights to this domain.  Rights are revoked for the principal represented by the security attribute.





There are three rights levels: Administrator, User, and None (deny access to domain). Administrators hold User rights, but do not appear in the list of users.






 Syntax




 
 





IDL




void revoke_rights(
  in Security::SecAttribute   priv_attr
);




















 Parameters







priv_attr






SecAttribute data type. Security attribute that a principal should 
hold for the rights to be revoked.







 simple_domain_name






The simple_domain_name attribute returns the simple (unqualified) name of the domain.






 Syntax




 
 





IDL




readonly attribute string simple_domain_name




















 Return Value






String name of domain.






 sub_domains






The sub_domains attribute returns the list of sub-domains for the current domain. The list can be empty.






 Syntax




 
 





IDL




readonly attribute GradDomainManagerList sub_domains




















 Return Value






List of subdomains.






 users






The users attribute returns the set of security attributes that have user rights for the domain. Only attributes that are granted users rights will be included in this list. Administrators hold User rights, but do not appear in the list of users. 






 Syntax




 
 





IDL




readonly attribute Security::AttributeList users




















 PReturn Value






List of security attributes.






5.7  GradPolicy






The GradPolicy interface is a base-interface of GradDomainAccessPolicy, GradDelegationPolicy, GradSecureInvocationPolicy, and GradAuditPolicy. It allows the application developer to locate the domain manager for any given policy object.





The GradPolicy interface supports the domain_manager attribute.






 domain_manager






The domain_manager attribute returns the domain manager for the domain where this policy resides.






 Syntax




 
 





IDL




readonly attribute GradDomainManager domain_manager




















 Return Value






Domain manager.






5.8  GradReceivedCredentials Interface






The GradReceivedCredentials interface extends the ReceivedCredentials and GradCredentials interfaces to allow application developers to call the methods of GradCredentials on a set of ReceivedCredentials.There are no additional methods defined by this interface.






5.9  GradRequiredRights Interface






The GradRequiredRights interface extends the RequiredRights interface to make it easier for administrative tools to read the current required rights settings. Included are operations to clear existing required rights for a particular operation on an interface or to delete a set of required rights for a set of interfaces in a module.





The GradRequiredRights interface supports the following operations:



clear_required_rights



delete_module



delete_required_rights



enumerate_interfaces



enumerate_methods






 clear_required_rights






The clear_required_rights method removes the required rights for the specified operation (method) on the interface. The operation_name parameter may be NULL.






 Syntax




 
 





IDL




void clear_required_rights(






            in   CORBA::Identifier operation_name,






            in   CORBA::RepositoryId interface_name)




















 Parameters







interface_name





Name of interface.






operation_name





Name of operation.






 Return Value






None.






 delete_module






The delete_module method removes the required rights on all interfaces that are part of the specified module.






 Syntax




 
 





IDL




void delete_module(






            in   CORBA::Identifier module_name)

























 Parameters







module_name





Name of module.






 Return Value






None.






 delete_required_rights






The delete_required_rights method removes the required rights for the specified interface.






 Syntax




 
 





IDL




void delete_required_rights(






 	in   CORBA::RepositoryId interface_name)




















 Parameters







interface_name





Name of the interface whose required rights you want to delete.






 Return Value






None.






 enumerate_interfaces






The enumerate_interfaces method returns a list of the interfaces that have required rights.






 Syntax




 
 





IDL




CORBA::RepositoryIdSeq enumerate_interfaces()




















 Return Value






List of repository IDs.






 enumerate_methods






The enumerate_methods method returns a list of the methods that have required rights for the specified interface.






 Syntax




 
 





IDL




CORBA::StringSequence enumerate_interfaces(in CORBA::RepositoryId 
int_name)




















 Parameters







int_name





Name of interface.






 Return Value






List of protected methods on interface.






5.10  GradSecureInvocationPolicy






The GradSecureInvocationPolicy interface derives from SecureInvocationPolicy and supports the following operations:





enumerate_interfaces





unset_association_options






 enumerate_interfaces






The enumerate_interfaces method returns a list of the interfaces that have a set secure invocation policy.






 Syntax




 
 





IDL




CORBA::RepositoryIdSeq enumerate_interfaces()




















 Return Value






List of interface repository IDs.






 unset_association_options






The unset_association_options method removes the association options from policy for the interface specified.  After these settings have been removed, the settings for the default interface or the default handling will be used.






 Syntax




 
 





IDL




void unset_association_options(






            in   CORBA::RepositoryId interface_name)




















 Parameters







interface_name





Interface name.






5.11  GradVault






The GradVault interface extends the Vault interface to allow application developers to create security attributes that represent users and groups. These attributes do not grant rights to the caller, since rights are granted only to Credentials that contain the appropriate attributes. The methods of GradVault allow you to determine if a set of Credentials belong to a named user or group.





The GradVault interface supports the following operations:



create_group_attribute



create_principal_attribute






 create_group_attribute






The create_group_attribute method creates an attribute to represent the named group. You can use this attribute to test if a set of Credentials belong to this group. The GradCredentials::is_in_group method is the preferred method to use since it verifies group membership in one step. 





If the named group does not exist, this method will throw a CORBA::BAD_PARAM exception.






 Syntax




 
 





IDL




Security::SecAttribute create_group_attribute(in string group_name)




















 Parameters







group_name





Name of group.






 Return Value






Security::SecAttribute. New group attribute.






 create_principal_attribute






The create_principal_attribute method creates an attribute to represent the named user (principal). You can use this attribute to test if a set of Credentials belong to this user. The GradCredentials::is_principal method is the preferred method to use since it verifies this in one step. 





If the named user does not exist, this method will throw a CORBA::BAD_PARAM exception. 






 Syntax




 
 





IDL




Security::SecAttribute create_principal_attribute(in string 
principal_name)




















 Parameters







principal_name





String containing user name.






 Return Value






Security::SecAttribute. New principal attribute.






[Previous]
 [Next]
[Table of Contents]
 [Index]



To make comments or ask for help, contact 

support@gradient.com. 




Copyright © 1999 Gradient Technologies, Inc.