Chapter 8   Setting Security

This chapter describes how SilverStream manages security, and how you can control security settings at the server level through user authentication, and at the application level using access control.

The chapter contains sections on:

• Security configuration

• Establishing a secure connection to the server

• Accessing security provider systems

• Security provider login formats

• Using certificates

• Enabling authentication

• Setting up access control

• Excluding robots

• Locking down an application or a server

• Security checklist

    For information about setting up SilverStream users and groups, see Setting Up Users and Groups.

Security configuration   

SilverStream supports both regular HTTP and HTTP using the Secure Socket Layer (SSL) 3.0 protocol (HTTPS). HTTPS provides data encryption between the SilverStream client and server to ensure privacy and data integrity.

About SSL

The SSL (Secure Socket Layer) handshake protocol was developed by Netscape to provide security and privacy over the Internet. The protocol supports server and client authentication. The SSL protocol is application-independent, allowing protocols like HTTP and FTP to be layered on top of it transparently. The SSL protocol is able to negotiate encryption keys as well as authenticate the server before data is exchanged by the higher-level application. The SSL protocol maintains the security and integrity of the transmission channel by using encryption, authentication, and message authentication codes.

About HTTPS

With HTTPS, you get a communications channel that provides privacy, user authentication, and message integrity. SSL is implemented in SilverStream as follows:

• The SilverStream Server must have an authentication certificate (also called public-key certificate, digital ID, or digital certificate) to make an SSL connection. The certificate is a digital "ID card" that cannot be forged. This certificate describes the server and includes a chain of trust.

• Both the client and server encrypt what they send using information from both their own certificate and the certificate at the other end (if the client has a certificate). This means the sender can be sure that only the intended recipient can de-encrypt the data. The recipient can be sure the data came from the place it claims to have come from, and that no tampering has occurred.

Types of authentication

Authentication begins and ends with the client session. The session operates in one of three modes:

• RSA (Rivest-Shamir-Adleman). Used for asymmetrical cipher using a public key and a private key. Used between HTML clients and the SilverStream Server.

• DSA (Diffie-Hellman). Provides a secure channel for the SilverStream Server to communicate with Java clients (SilverStream Designer, SilverJRunner, and non-SilverStream Java clients).

• Base64 encoding. Used for HTTP validation (that is, when SSL is not implemented). The SilverMaster stores SilverStream user names with encrypted passwords, or you can use any of the external security providers supported by SilverStream. For external security systems, SilverStream verifies the password information with the external security system provider.

Security architecture   

In the SilverStream three-tiered architecture, security is set up at the server tier, between the client tier and the database tier (see the figure below). The SilverStream Server acts as a single database user with multiple connections into a database. Acting in this manner, the server adds extra user and object security for the database. In effect, the SilverStream Server is treated as just another user with access privileges. Native database activity and security measures are not compromised.

Security functions   

SilverStream security performs four major functions:

• Authentication. This is done through a "challenge," such as requesting a user ID/password pair when using HTTP, or through an authentication certificate when using HTTPS.

• Access control. Once the system verifies a user's identity, it checks whether the user is allowed to perform the requested operation on the requested object.

• Data integrity. The system ensures that the data received over the network is the same data that was sent.

• Data privacy. The system prevents unauthorized users from seeing data during transmission.

The SilverStream security system handles all data integrity and data privacy functions with virtually no administrator involvement. The remainder of this chapter describes how to implement authentication and access control in the SilverStream environment.

Establishing a secure connection to the server   

When doing administrative tasks such as adding users and adding databases to the server, you probably want a secure (SSL) connection between the server and the client you are using (such as the SMC, the SilverStream Designer, or perhaps a browser) so all communication is encrypted.

By default, all communication to the server is unsecured. This section describes how to establish a secure connection to the server so that all information is encrypted. The procedure depends on whether the client is a Java client (such as the SMC, SilverJRunner, the SilverStream Designer, or an external Java client) or an HTML client (a browser).

Establishing a secure connection between a Java client and the SilverStream Server   

To establish a secure (SSL) connection between a Java client and the SilverStream Server:

1. Install a DSA certificate on the SilverStream Server.

       For information, see Creating and installing server certificates.

2. Enable the DSA port in the SMC.

       For information, see Enabling RSA/DSA ports.

3. Connect your client to the server using HTTPS at the DSA port.

   With the SMC, click the Choose (server) icon. With the SilverStream Designer, click the Choose Server icon. In the resulting dialog, specify this server:

     https://server:DSA_port 
   

   For example:

     https://tara:444 
   

   With SilverJRunner, specify https://server:DSA_port on the command line for the hostname.

Establishing a secure connection between an HTML client and the SilverStream Server   

To establish a secure (SSL) connection between an HTML client and the SilverStream Server:

1. Install an RSA certificate on the SilverStream Server.

       For information, see Creating and installing server certificates.

2. Enable the RSA port in the SMC.

       For information, see Enabling RSA/DSA ports.

3. Connect your browser to the server using HTTPS at the RSA port:

     https://server:RSA_port 
   

   For example:

     https://tara:443 
   

Accessing security provider systems   

The system verifies users and their permission levels within a SilverStream application according to lists of groups and users that you provide. User and group information can be defined in SilverStream or can be obtained from an external security system. For SilverStream-defined entities, all information is stored in the SilverMaster database catalog. For external security, all information is obtained from the external system.

SilverStream recognizes users and groups from the following security providers:

• SilverStream Security. Native security that maintains a list of valid users and groups in the SilverMaster database.

• Windows NT directory services. Capability to connect the SilverStream Server to the NT Domain name registry.

• Lightweight Directory Access Protocol (LDAP). A directory service that connects the SilverStream Server to defined LDAP directories.

• NisPlus. Also referred to as NIS+ (Network Information Services Plus), a name service that is available on SunOS 5.x and later operating systems.

• X.509 certificates. SilverStream supports client certificates generated from authority servers such as VeriSign, Netscape Certificate Server, and Microsoft Certificate Server. For more information, see Using certificates.

SilverStream implements the Java Naming and Directory Interface (JNDI), which connects the SilverStream Server to native UNIX security and to Windows NT and LDAP directories.

Adding security provider access   

You can use the SMC to access security provider systems. After you set up access to provider directories, you can use users and groups in expressions to define access control.

    For information about setting up SilverStream users and groups, see Setting Up Users and Groups. For information about access control, see Setting up access control.

To add security provider access:

1. Invoke the SMC.

2. Select Security options.

3. Select the Security Providers panel.

   

   Any LDAP and Nis+ servers that are known to the SilverStream Server are listed.

4. Select the type of provider you want to register (all providers are selected by default).
   • NT is valid only when running Windows NT. If you choose NT, it is not necessary to add a NT domain; NT provides system calls that SilverStream uses to discover the primary and trusted domains. But you do need to set up the server so users can log in with their NT names. See Using NT security.

   • NIS+ is valid only when running Solaris.

5. To add an LDAP or Nis+ server connection, choose the appropriate item and click Add.
   • For more information on adding the LDAP security provider, see Using LDAP security.

   • For more information on adding the Nis+ security provider, see Using NisPlus security.

Resetting the security resource timeout

The SMC also allows you to set the security resource timeout period. This tells the server how frequently to reload the list of available users and groups from defined security providers.

To reset security resource timeout:

1. Invoke the SMC.

2. Select Security options.

3. Select the Server Security panel.

   

4. Edit the Security resource timeout value as needed.

   This setting determines how frequently the SilverStream Server will upload current lists of users and groups from the NT, LDAP, and/or NIS+ servers, which would include any updates to these lists. The default value is 15 minutes.

   You might want to increase this number if the information in the external system does not change frequently or if the connection to it is slow.

Using NT security   

To simplify security administration, SilverStream allows you to set up your server so that users can log in using their NT user name and password. Users logging in with their NT user name and password information (when answering a login prompt) only have to do this once per session.

NOTE   When running the SilverStream Server as a service in NT under the System account, you need to make two changes to NT Security if SilverStream is running in a multiple domain environment: The user who is logged into on the computer that is running the SilverStream Server must have the following two privileges: Act as Part of the Operating System and Log on as a Service. Also, all users from non-local trusted domains who log into the SilverStream Server need the privilege to Log on Locally.

To set up NT security:

1. Go to the Windows NT Start menu and choose Programs and then Administrative Tools.

2. Start the User Manager.

   If you are running NT Server, complete steps 3 to the end. If you are running an NT workstation, go to step 5 and continue to the end.

3. Select Domain from the User menu.

4. Set the Domain field to the name of the machine in the dialog, so that the rights being set will apply to this machine. Click OK to close this dialog.

5. Select User Rights from the Policies menu. The User Rights Policy dialog appears.

6. Make sure that the Show Advanced User Rights checkbox is checked.

7. Select Act as part of the operating system from the dropdown list. All users and groups that have this privilege are listed in the Grant To field of the dialog box.

   

8. If the name of the account that launches the SilverStream Server does not appear in this list, click the Add button and add the user to this list.

   This is all you have to do if your NT users are in the same domain as the user starting the server. Go to step 11.

   But if you have users from trusted domains who need to log in to the server as well, you need to perform the following steps as well.

9. Select Log on locally from the dropdown list.

10. Add the desired users from the trusted domains.

    These users will now be able to log in to the SilverStream Server.

11. Reboot your computer for these settings to take effect.

    NOTE   You can add NT users to Silver Server groups.

Using LDAP security   

Lightweight Directory Access Protocol (LDAP) is a directory service that allows Internet clients to query and manage an arbitrary database of hierarchical attribute/value pairs over a TCP/IP connection. LDAP provides a specification that allows applications to communicate with the directory service. SilverStream allows you to specify LDAP users and groups, to display LDAP attributes, and to use LDAP users and groups in access control expressions.

To set up LDAP security:

1. Invoke the SMC.

2. Select Security options.

3. Select the Security Providers panel.

4. Select LDAP in the provider list, then click Add.

   A wizard appears.

5. Select LDAP and click Next.

   The following dialog displays. Use this dialog to specify the server and (optionally) the login attribute.

   

   Item	Description
   Server	The name of the LDAP server. The server name must be recognized on your network.
   User Login Attribute	(Optional) If an attribute is specified as the value of this property, it defines the LDAP attribute that can be used to uniquely identify a user. It is your responsibility to pick an attribute that is unique for all users. Specifying a value here can simplify login for LDAP users. For more information, see Simplifying login for LDAP users.

6. Click Next.

   The following dialog displays. Use this dialog to specify groups on the LDAP server.

   

   Item	Description
   Group Location	A distinguished name that identifies the level in the hierarchy where you want to start specifying group entries. For example, to start at an organizational unit called "employees", which exists under the organization called "silverstream", enter the following: ou=employees,o=silverstream Every group under and including "employees" in the hierarchy will be included.
   Group Filter	The LDAP search filter is used to determine what constitutes a group for this LDAP server. A common usage is to identify the class schema of a group. For example: (objectclass=groupofuniquenames)
   Group Description Attribute	An attribute used to identify a group description in SilverStream. The name you enter is the LDAP attribute to which you want to map the description. For example: notes
   Group Additional Attributes	Select All if you want all of the specified LDAP group attributes to be listed in SilverStream. Select None if you want no additional attributes to appear. The specified attributes will be displayed in a tab when you select a group in the Users & Groups panel and open the Property Inspector.
   Group/Users Attribute	An attribute used to display all members (users) of a group in SilverStream. The name you enter is the LDAP group attribute that lists users. For example: uniquemember

7. Click Next when you have finished specifying groups. The next panel asks you to specify users on the LDAP server.

   

   The following describes each item on this panel.

   Item	Description
   User Location	A distinguished name that identifies the point in the hierarchy where you want to start specifying users. For example, to start at a point (or node) entitled "developers", which exists under "software", enter the following: ou=developers,o=software Every user under and including "developers" in the hierarchy will be included.
   User Filter	The LDAP search filter is used to determine what constitutes a user for this LDAP server. A common usage is to identify the class schema of a user. The filter must be enclosed by parentheses. For example: (objectclass=person)
   User Description Attribute	An attribute used to identify a user description in SilverStream. The name you enter is the LDAP attribute to which you want to map the description. For example: title
   Additional Attributes	Select All if you want all of the specified LDAP user attributes to be listed in SilverStream. Select None if you want no additional attributes to appear. The specified attributes will be displayed in a tab when you select a user in the Users & Groups panel and open the Property Inspector.
   Full Name	Specifies the full name attribute, if available. For example: cn

8. Click Finish.

   The SMC displays the settings under the LDAP directory. You can access the new settings at any time by selecting Users& Groups in the Security options in the SMC.

Using NisPlus security   

NisPlus, also referred to as NIS+ (Network Information Services Plus), is a name service that is available on SunOS 5.x and later operating systems. Users are contained in the NisPlus table identified by passwd.org_dir, and groups by group.org_dir. After you have added users and groups, you can use them in security expressions for access control.

To set up NisPlus security:

1. Invoke the SMC.

2. Select Security options.

3. Select the Security Providers panel.

4. Select Nis+ from the provider list, then click Add.

   A wizard appears.

5. Select Nis+ and click Next.

6. Type the name of the NisPlus server. The server name must be recognized on your network.

Accessing users and groups   

You can use the SMC to view users and groups that you have defined for any security provider.

To view user and groups:

1. Invoke the SMC.

2. Select Security options.

3. Select Users & Groups.

4. Highlight the appropriate icon to view the users and groups known to the server.

   

   You can expand a selected item to show specific users and groups.

Security provider login formats   

SilverStream supports a number of security realms including SilverStream security, NT security, LDAP security, NisPlus security, and certificate security. All except certificate security involve establishing an identity by providing user name information and a password.

When users log in, they are presented with a dialog similar to the following.

If the authentication dialog is being presented by a browser, the dialog--defined by the browser--will look a little different than the dialog shown above, but will consist of the same fields.

Colons cannot be used in user names or passwords

User authentication in HTTP works by taking the user name and password separated by a colon ( : ). So make sure that user names and passwords don't contain colons. In particular, with LDAP distinguished names, which can be quite long, make sure no component of the name has a colon in it.

User name components

In SilverStream a user name is composed of three parts delimited by backslash characters: Realm\Authority\Name:

Component	Description
Realm	SilverStream supports the following security provider realms for login: SSSW (for SilverStream users) NT LDAP NisPlus
Authority	Authorities are as follows: For SilverStream, there is no authority. For NT, the authority is the NT domain. For LDAP, the authority is the server. For NisPlus, the authority is the server name and the domain name, separated by a forward slash (/).
Name	The user name.

By default, the SilverStream Server allows shortcuts to the full user login name, as follows:

• SilverStream. If the user enters one part for a user name, a SilverStream user name is assumed. For example:

  emilyh is translated to SSSW\\emilyh

  NOTE   For SilverStream security, the authority is an empty string--nothing between the two backslashes; the authority is not needed because an external security system is not used.

• Windows NT. If the user enter two parts to a user name, an NT user name is assumed, with the format domain\userName. For example:

  mydomain\craigh is translated to NT\mydomain\craigh

By default, LDAP and NisPlus names must be fully qualified, as follows:

• LDAP. Login syntax for user name: LDAP\serverName\distinguishedName

  The user must enter the entire path name. For example:

    LDAP\myServer\cn=Nancy Smith,ou=SilverStream Software 
  

• NisPlus. Login syntax for user name: NisPlus\server/nisDomain\username

  The user must enter the entire path name. Note that the authority has two components, separated by a forward slash. For example:

    NisPlus\myServer/domain1.com\jeanw 
  

You can change these default login specifications, as described next.

Overriding defaults for login name components   

You can override the defaults for login name components. So if you use only one type of external security system (and perhaps only one external security authority), you can allow your users to provide a shortened name, thus simplifying the login procedure.

To override the defaults for login name components:

1. Invoke the SMC.

2. Select Security options.

3. Select the Server Security panel.

4. Specify your default realm and, optionally, your default authority.

   Field	Description
   Default Security Realm	Defines the security realm for any login name that does not explicitly define a realm. Possible values are SilverStream, NT, LDAP, NIS+, or No Default Specified.
   Default Security Authority	(Enabled only if a default security realm has been defined) Defines the authority for any login name that does not explicitly define an authority. SilverStream provides a list of valid authorities based on the selected default realm.

A full login name can always be specified, in which case the defaults are ignored.

Example

Suppose your site uses security names from a single LDAP server. You could set the following defaults:

Field	Value
Default Security Realm	LDAP
Default Security Authority	ServerName

Users that exist in the LDAP server can now just use their LDAP user name and password when logging into the SilverStream Server.

In this same example a user that exists as part of the SilverStream security realm must now specify a full login name:

  SSSW\\SilverName 

Simplifying login for LDAP users

In LDAP, a user name is specified relative to the LDAP naming hierarchy as a distinguished name (DN). The DN is a comma-separated list of nodes that contain attribute-name pairs from the leaf node where the user resides back to the root node.

By default, LDAP users logging in to the SilverStream Server are required to enter the entire DN, which can be quite lengthy. You can simplify login for LDAP users by specifying the User Login Attribute property when adding an LDAP server as a security provider. For more information on this property, see Using LDAP security.

If you have specified a User Login Attribute, when the user credentials are being verified during the login sequence, a search is performed for the specified User Login Attribute, with a value that matches the Name portion of the login user name.

The search starts from a point in the LDAP hierarchy identified as User Location when defining the LDAP server to SilverStream (see Using LDAP security).

If the search is successful, the DN of the corresponding user (the first one found if there are multiple hits), is used to construct a fully qualified login name, and the login operation continues. If the search is not successful, the operation continues as though the Name field were the distinguished name of the LDAP user. This allows LDAP logins using either form when the attribute is set.

Example 1

Assume the following server properties are specified:

Field	Value
Default Security Realm (specified in Server Security panel in SMC)	LDAP
User Login Attribute (specified when defining the LDAP server to SilverStream)	mail
User Location (specified when defining the LDAP server to SilverStream)	o=SilverStream Software,c=US

Here, a default security realm is defined, and the login attribute is set to mail. At this site, each user's mail attribute is that user's full e-mail address.

A user defined in an LDAP server named myServer, with a distinguished name of uid=ecraig,ou=Development,ou=Burlington,o=SilverStream Software,c=US and an e-mail address of ecraig@silverstream.com (that is, a user whose mail attribute is ecraig@silverstream.com) could use a login name of either:

  myServer\uid=ecraig,ou=Development,ou=Burlington,o=SilverStream Software,c=US  

or

  myServer\ecraig@silverstream.com 

Example 2

Assume the following server properties are specified:

Field	Value
Default Security Realm (specified in Server Security panel in SMC)	LDAP
Default Security Authority (specified in Server Security panel in SMC)	myServer
User Login Attribute (specified when defining the LDAP server to SilverStream)	uid
User Location (specified when defining the LDAP server to SilverStream)	o=SilverStream Software,c=US

In this example, a default security authority has now been specified, in addition to the default security realm. The login attribute has now been set to uid.

The same user as above (whose uid is ecraig) could use a login name of either:

  uid=ecraig,ou=Development,ou=Burlington,o=SilverStream Software,c=US 

or

  ecraig 

Using certificates   

Certificates are required when using HTTP with the Secure Socket Layer (SSL) 3.0 protocol (HTTPS). HTTPS provides data encryption between the SilverStream client and server to ensure privacy and data integrity. Certificates can also be used to authenticate users of SilverStream applications.

This section contains the following topics:

• About certificates

• Creating and installing server certificates

• Viewing server certificates

• Enabling RSA/DSA ports

• Turning off HTTP communications

• Restricting SSL cipher suites

• Managing Certificate Authorities

• Installing and managing client certificates

About certificates   

A certificate (also called a public-key certificate, digital ID, or digital certificate) is a file that authenticates the identity of an individual or a group. The certificate is a kind of license issued by a trusted organization called a Certificate Authority. A Certificate Authority might be an external company that offers certificate services, such as VeriSign, or an internal organization, such as a corporate MIS department.

For Internet applications, it is generally a good idea to have a server certificate that is signed by a widely recognized and trusted guarantor. For intranet applications, it may be sufficient to have the guarantor be the company in which the application is running.

Both users and servers can have certificates attesting to their identity. If you want to use SSL for privacy, the SilverStream Server must have a server certificate. Once enabled, the server might request a client certificate from the browser attesting to the identity of the user.

Advantages of certificates

Certificates provide these important security services:

• Enhanced authentication and security. Clients can be assured that they are communicating with who they think they are. Similarly, applications can be sure of who their users are. Certificate-based authentication is more secure than traditional methods of user authentication, such as user name/password.

• Real-time encryption over SSL. SSL's encryption scheme requires that the server present its digital certificate to the client as part of the SSL handshake. Verifying the server's certificate gives the client a level of trust about the server's identity.

• Convenience. Certificates allow a user to use a single user login over the intranet and across the Internet. Users log in once to the browser, for example, (a local operation) and then the browser presents client certificates to servers as needed.

Certificate support in SilverStream

The following is a summary of certificate support in SilverStream.

• Server certificates. A server certificate is required for SSL/HTTPS. This allows clients to authenticate the server. There are two types of certificates, depending on the type of client:
  • SilverStream supports RSA-encoded server certificates for HTTPS/SSL communications between the SilverStream Server and HTML clients.

  • SilverStream supports Diffie-Hellman (DSA) server certificates for HTTPS/SSL communications between the SilverStream Server and Java clients (such as the Designer, the SMC, SilverJRunner, or non-SilverStream Java client).

• Client certificates. Client certificates are optional and are used for user authentication by the server. They are installed in a browser. You can get client certificates from a number of authorities, including VeriSign. Each client certificate includes the Certificate Authority (CA) certificate that generated it. The server must have a corresponding CA certificate.

  NOTE   The SilverStream Server does not support DSA client certificates.

• CA certificates on the server. CA certificates are required on the server for verifying corresponding certificates on the HTML client. The server will only authenticate client certificates that were generated/signed by one of its installed CA certificates.

Creating and installing server certificates   

Using a server certificate with the SilverStream Server involves the following steps:

1. Generating a certificate.

2. Installing the certificate in the SilverStream Server.

To help you create and install server certificates, SilverStream provides the following executables:

Executable	Description
AgDigitalIDStep1	Used to prepare either of the following: A Certificate Signing Request (CSR) for an RSA certificate. The CSR is an encrypted file that contains information that identifies the organization running the SilverStream Server. The CSR is submitted to a certificate issuer (such as VeriSign) that will use the information to create a certificate signed by the issuer. The certificate is then installed using AgDigitalIDStep2. A self-signed DSA certificate that identifies the organization running the SilverStream Server. The certificate is then installed using AgDigitalIDStep2.
AgDigitalIDStep2	Prompts for the certificate information returned by the issuer as well as the private key used to protect the data, then installs the certificate (without private key information) into the SilverStream Server.

You invoke these executables at the command line, outside the SilverStream environment. The procedures are described in the following sections:

• Generating an RSA server certificate

• Generating a DSA server certificate

• Installing the certificate

Generating an RSA server certificate

To enable HTTPS/SSL communications between an HTML client (browser) and the SilverStream Server, you need to install an RSA certificate on the server.

To generate an RSA server certificate for use with HTML clients:

1. Change your working directory to SilverStream\bin.

2. At the command line, specify the following command:

     AgDigitalIDStep1 
   

   The following form appears:

   

   NOTE   In UNIX, this utility runs using a GUI and cannot be run in a character terminal window. If you log in remotely to the UNIX machine, make sure that you set your DISPLAY environment variable appropriately.

3. Complete the items on this form as described below.

   Field	Entry
   Server DNS Name	The TCP/IP host name, which may be different from your machine name. (You can issue ping localhost from the command line to determine the TCP/IP name of the local host.)
   Organization	Your company name in full unabbreviated legal form.
   Organizational Unit	(Optional) Your department within the company.
   City/Locale	(Optional) The city where your company does business.
   State/Region	The full name of the state where your company does business. Do not abbreviate the name of the state.
   Country	The country where your company does business. You must use the ISO two-letter country code. For example, the ISO code for the United States is US.

4. Click Next.

   In the domestic version of SilverStream, the following screen appears, allowing you to specify the size of the key pair to generate (in the export version of SilverStream, the key pair is always 512 bits and cannot be changed).

   

5. If prompted, specify the size of the key pair to generate.

6. Click Next.

   The following screen appears.

   

7. Enter a password, then confirm it. This password will be used to encrypt your private key. Be sure to record this password, because you will need it to install the certificate into the server.

8. Click Next.

   The following screen appears.

   

   This screen shows the paths for the CSR (Certificate Signing Request) and the password-protected private key. You may edit these paths if you choose. You will use this information later when installing the certificate.

   NOTE   The file that contains the private key must be kept physically secure. Otherwise, anyone who can obtain the server's certificate can masquerade as the server.

9. Click Next.

   If the wizard hasn't been able to collect enough randomness information to generate cryptographically good keys from the key presses and mouse movements you have made, the following screen appears.

   

10. If prompted, type random characters in the edit box and move the mouse around to create an encrypted private key. When the wizard has enough randomness information, the OK button is enabled.

    The wizard generates the certificate signing request and private key.

11. Click OK.

    The following screen appears.

    

12. Click Copy CSR to Clipboard to copy the contents of the CSR to the clipboard for use in the next step.

13. Follow the directions to request a certificate for your SilverStream server (for example, by using the VeriSign Web site http://digitalid.verisign.com). Once your request is approved, the certificate authority sends the new certificate back to you through e-mail.

14. Click Finish.

You use AgDigitalIDStep2 to install the certificate. See Installing the certificate.

Generating a DSA server certificate

To enable HTTPS/SSL communications between a Java client and the SilverStream Server, you need to install a DSA certificate on the server.

To generate a DSA server certificate for use with Java clients:

1. Change your working directory to SilverStream\bin.

2. At the command line, specify the following command:

     AgDigitalIDStep1 dsa 
   

   The following form appears:

   

   NOTE   In UNIX, this utility runs using a GUI and cannot be run in a character terminal window. If you log in remotely to the UNIX machine, make sure that you set your DISPLAY environment variable appropriately.

3. Specify the following information.

   Field	Entry
   Server DNS Name	The TCP/IP host name, which may be different from your machine name. (You can issue ping localhost from the command line to determine the TCP/IP name of the local host.)
   Organization	Your company name in full unabbreviated legal form.
   Organizational Unit	(Optional) Your department within the company.
   City/Locale	(Optional) The city where your company does business.
   State/Region	The full name of the state where your company does business. Do not abbreviate the name of the state.
   Country	The country where your company does business. You must use the ISO two-letter country code. For example, the ISO code for the United States is US.

4. Click Next. In the domestic version of SilverStream, the following screen appears, allowing you to specify the size of the key pair to generate (in the export version of SilverStream, the key pair is always 512 bits and cannot be changed).

   

5. If prompted, specify the size of the key pair to generate.

6. Click Next.

   The following screen appears.

   

   This screen shows the paths for the certificate and the private key. You may edit these paths if you choose. You will use this information later when installing the certificate.

   NOTE   The file that contains the private key must be kept physically secure. Otherwise, anyone who can obtain the server's certificate can masquerade as the server.

7. Click Next.

   If the wizard hasn't been able to collect enough randomness information to generate cryptographically good keys from the key presses and mouse movements you have made, the following screen appears.

   

8. If prompted, type random characters in the edit box and move the mouse around to create an encrypted private key. When the wizard has enough randomness information, the OK button is enabled.

   The wizard generates the certificate.

9. Click OK. The following screen appears.

   

10. Copy the certificate to the clipboard for use when installing the certificate.

11. Click Finish.

You use AgDigitalIDStep2 to install the certificate. See Installing the certificate next.

Installing the certificate

Once you receive your RSA certificate from the certificate authority or have generated a DSA certificate using AgDigitalIDStep1, you can install the certificate using the AgDigitalIDStep2 program.

To install the certificate:

1. Make sure the SilverStream Server is running.

2. Change your working directory to SilverStream\bin.

3. At the command line, specify the following command:

     AgDigitalIDStep2 
   

   The following form appears:

   

4. Paste the certificate into the dialog.

5. Click Next.

   The following screen appears.

   

   This screen asks you for the path for the private key (you might need to edit the name of the private key, since the names are different for RSA and DSA certificates) and asks you to confirm your password (there is no password for a DSA private key).

6. Click Next.

   The following screen appears.

   

7. Enter your server name and the port number to use. By default, the SilverStream Server listens to port 80.

8. Click Finish. The following confirmation message appears:

     The Digital ID has been successfully installed in the server "your_server". 
   

9. To activate the certificate, click the Restart (server) button on the SMC.

   When the server is restarted, it is automatically configured to listen using HTTPS at the RSA or DSA port depending on which kind of certificate you just installed (in addition, by default, to listening for HTTP requests at the HTTP port).

       For more information, see Enabling RSA/DSA ports and Specifying general server properties.

When you are ready for production, use the SMC to enable authorization. See Enabling authentication.

Viewing server certificates   

To view certificates that have been installed on the server:

1. Invoke the SMC.

2. Select Security options.

3. Select the Certificates panel.

   

4. Select either the RSA Certificate tab or the DSA Certificate tab.

Enabling RSA/DSA ports   

By default, SilverStream uses ports 443 and 444 for RSA and DSA communications respectively. You can use the SMC to enable and modify the port settings.

To enable and change RSA/DSA ports:

1. Invoke the SMC.

2. Select the Security options.

3. Select the Server Security panel.

   

4. Check Enable DSA Port or Enable RSA Port:
   • Enable RSA only after you have installed an RSA server certificate from a provider such as VeriSign.

   • Enable DSA only if you have installed a DSA certificate on the server.

     NOTE   The ports are automatically enabled after the server is restarted after a server certificate has been installed.

         For more information, see Creating and installing server certificates.

5. Change the RSA and DSA port numbers if necessary.

   With a UNIX server, specify port numbers above 1024 if the server is not being run with root access (ports below 1024 are reserved for root access).

       For information about cipher suites, see Restricting SSL cipher suites.

6. Select Update.

7. To activate the changes, click Restart (server).

Turning off HTTP communications   

You can turn off HTTP communications and allow client communications only using HTTPS or RMI.

To disable HTTP communications:

1. Invoke the SMC.

2. Select Configuration options.

3. Select the General panel.

4. Deselect the Enable HTTP port check box.

5. Select Update.

6. To activate the change, select the Restart button. For more information, see Restarting the SilverStream Server.

Now the server will not listen on the HTTP server port.

Restricting SSL cipher suites   

When an SSL connection is initialized, the client and server determine a common cipher value to be used for key exchange and encryption. Various cipher values offer different types of encryption algorithms and levels of security. United States security currently prohibits the export of high-level cipher values. By default the domestic version of the SilverStream Server has a full set of cipher suites. This makes it capable of servicing a range of clients from low-level encryption (such as the International version of the Netscape browser with 40-bit encryption) to high levels (such as the domestic version of Internet Explorer with 128-bit encryption).

You can restrict the levels of encryption (cipher values) used by the server when communicating in HTTPS through the RSA port and through the DSA port. This allows you to have a server capable of high-level encryption while preventing connections from lower-level security clients.

During server startup, the list of allowed cipher suites is read (high level encryption will not be allowed from an international server). Only those cipher suites that are requested and allowed will be used to initialize the appropriate SSL socket.

By default, all cipher suites are allowed. You can use the SMC to disallow certain cipher suites.

To specify which cipher suites are allowed:

1. Invoke the SMC.

2. Select Security options.

3. Select the Server Security panel.

4. Select the Enable DSA Port and/or Enable RSA Port check boxes to enable secure DSA (Java-client) and/or RSA (HTML-client) communications.

5. Specify which cipher suites are allowed by clicking DSA Cipher Suites or RSA Cipher Suites and selecting and deselecting the cipher suites in the resulting dialogs, as described in the table below. If you select a cipher suite, its description displays in the dialog.

6. Click Update.

7. To activate the changes, click Restart (server).

Table of cipher suites

The table below shows the cipher suites supported by the server when using secure communications (HTTPS). Note that only the suites marked exportable are available in the international release. The domestic release is capable of handling all of these security protocols and will load them by default.

SSL cipher suite	Where available
RSA cipher suites
SSL_RSA_WITH_NULL_MD5	exportable (0 bit)
SSL_RSA_WITH_NULL_SHA	exportable (0 bit)
SSL_RSA_EXPORT_WITH_RC4_40_MD5	exportable (40 bit)
SSL_RSA_WITH_RC4_128_MD5	domestic only (128 bit)
SSL_RSA_WITH_RC4_128_SHA	domestic only (128 bit)
SSL_RSA_EXPORT_WITH_DES_40_CBC_SHA	exportable (40 bit)
SSL_RSA_WITH_DES_CBC_SHA	domestic only (56 bit)
SSL_RSA_WITH_3DES_EDE_CBC_SHA	domestic only (168 bit)
DSA cipher suites
SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA	exportable (40 bit)
SSL_DHE_DSS_WITH_DES_CBC_SHA	domestic only (56 bit)
SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA	domestic only (168 bit)
SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA	exportable (40 bit)
SSL_DHE_RSA_WITH_DES_CBC_SHA	domestic only (56 bit)
SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA	domestic only (192)
SSL_DH_anon_EXPORT_WITH_RC4_40_MD5	exportable (40 bit)
SSL_DH_anon_WITH_RC4_128_MD5	domestic only (128)
SSL_DH_anon_EXPORT_WITH_DES_40_CBC_SHA	exportable (40 bit)
SSL_DH_anon_WITH_DES_CBC_SHA	domestic only (56 bit)
SSL_DH_anon_WITH_3DES_EDE_CBC_SHA	domestic only (168 bit)

Example

To allow only greater than 40-bit encryption with RSA communications, select only the following cipher suites under RSA Cipher Suites:

• SSL_RSA_WITH_RC4_128_MD5

• SSL_RSA_WITH_RC4_128_SHA

• SSL_RSA_WITH_DES_CBC_SHA

• SSL_RSA_WITH_3DES_EDE_CBC_SHA

Managing Certificate Authorities   

The SilverStream Server maintains a list of Certificate Authorities (CAs) for verifying client certificates. This represents the list of guarantors the server will trust. There are three common CAs installed when the server is initially configured. These CAs are from VeriSign Inc.and represent different levels of trust. Class 1 represents a certificate that has minimal trust. Class 3 represents the highest level of trust.

When a user with a client certificate attempts to access the server, the server first checks the list of CAs to verify that the certificate has been approved by a known party, then checks for a valid timestamp to verify that the certificate has not expired. After completing the verification the server handles the connection request according to the Client Certificate Level parameter that you can set using the SMC. This setting is described in Installing and managing client certificates.

In addition, Silverstream allows the server to extract the CA from an unrecognized client certificate. For more information, see Installing and managing client certificates.

To install or delete a CA certificate:

1. Invoke the SMC.

2. Select Security options.

3. Select the Certificates panel.

4. Select the CA Certificates tab.

   This tab contains information about each Certificate Authority and allows you to add new CAs to allow a broader range of clients to be trusted, or you can delete CAs to tighten the level of security on the server.

5. To add a Certificate Authority, click Add Certificate Authority and select the file. To delete a Certificate Authority, highlight it and click Delete Certificate Authority (you are asked to confirm the deletion).

Installing and managing client certificates   

In the HTTPS environment a client certificate establishes the identity of a user when communicating with a server. Client certificates can be obtained from various sources, but to be useful the certificate must be signed by a guarantor (Certificate Authority) that is trusted by the server.

The SilverStream Server supports client certificates from standard Internet browsers (including Netscape and Internet Explorer) that use RSA encryption, and supports X.509 certificates, which is a particular implementation of the Certificate interface used by many certificate issuers.

Enabling and installing client certificates

Using the SMC, you can determine how the server will handle connection attempts from users with valid client certificates. Seven parameter options are available, each representing a different level of restriction. Two of the options will automatically install new certificates that are verified by the server and add them to the database as new users in the Certificate Security realm. You can also install the certificates manually (see Manually installing client certificates).

To enable client certificates on the server:

1. Invoke the SMC.

2. Select Security options.

3. Select the Server Security panel.

   

4. Select an option from the dropdown list labeled Client certificate level in HTTPS, then click Update.

   

   You need to restart the server only if you changed from level 0 to another level.

   Your selection determines how the server will handle all valid client certificates. The table that follows describes each option.

   The options are numbered from 0 (no verification) to 6 (most restrictive level).

   Certificate verification level	Description
   Certificate not requested or required (0)	Turns off the use of certificates for establishing a client's identity. A client that connects via HTTPS will still benefit from secure communications and can check the identity of the server, but will not be asked to present its own certificate
   Certificate requested but not required (1)	The server will request a certificate from the client. If the client does not have a certificate, or has a certificate that has not been validated by the server, a connection is allowed but the user remains Anonymous. If a certificate is presented for an established user, the client takes on the identity of the Certificate Security user.
   Certificate requested, not required; auto-add if not in database (2)	The server will request a certificate from the client. If the client does not have a certificate, a connection is allowed but the user will remain Anonymous. If a legitimate certificate is presented but it does not yet correspond to a client validated by the server, the server will automatically add the certificate and the client takes on the identity of the newly created Certificate Security user. If a certificate is presented for an established user, the client takes on the identity of the previously established Certificate Security user.
   Certificate required; auto-add if not in database (3)	The server will request a certificate from the client. If the client does not have a certificate, the connection is denied. If a legitimate certificate is presented but it does not yet correspond to a client validated by the server, the server will automatically add the certificate and the client takes on the identity of the newly created Certificate Security user. If a certificate is presented for an established user, the client takes on the identity of the previously established Certificate Security user.
   Certificate required; Anonymous if not in database (4)	The server will request a certificate from the client. If the client does not have a certificate, the connection is denied. If a legitimate certificate is presented but it does not yet correspond to a client validated by the server, the client is allowed to connect but remains Anonymous. If a certificate is presented for an established user, the client takes on the identity of the previously established Certificate Security user.
   Certificate required for known user (5)	The server will request a certificate from the client. If the client does not have a certificate, or has a certificate that does not correspond to a client previously validated by the server, the connection is denied. If a certificate is presented for an established user, the client takes on the identity of the previously established Certificate Security user.
   Certificate required for known user, but remain Anonymous. (6)	The server will request a certificate from the client. If the client does not have a certificate, or has a certificate that does not correspond to a client previously validated by the server, the connection is denied. If a certificate is presented for an established user, the client is allowed to connect but still remains Anonymous.

Manually installing client certificates

The previous section describes parameter options that automatically add new validated certificates to the database on the server. You might prefer to install the certificates separately. This section describes how to manually add client certificates to the database. It consists of two procedures, one for client machine and the other for the server.

To install a client certificate, client machine:

NOTE   For this procedure to work, the certificate validation level on the server must be set to 1, 2, or 4 (see the Certificate verification table in the previous section).

1. Make sure that you have a valid client certificate installed on your browser.

2. Open your browser and go to the following URL:

     https://server/SilverStream/Meta/Certificates?action=data 
   

   where server is the name of your server.

   The server will extract the user information from the certificate and send it back to the client.

3. Save the file that the server presents to an appropriate area.

To install a client certificate, server machine:

1. Start the SMC.

2. Select Security options.

3. Select the Users & Groups panel.

4. Select Certificate Security.

5. Choose the New User icon at the bottom of the right pane.

   The following dialog appears.

   

6. Choose Certificate user.

   

7. Enter the file name obtained by the client from the previous procedure and click Finish.

   This adds the certificate as a new user to the database on the server.

Extracting a CA from a client certificate

The SilverStream Server also allows you to extract the CA from a client certificate if the CA is not installed on the server. This section consists of two procedures, one for the client machine and the other for the server.

To extract the CA from a certificate, client machine:

NOTE   For this procedure to work the certificate validation level on the server must be set to 1 or 2. (see the Certificate verification table in the previous section.)

1. Make sure that you have a valid client certificate installed on your browser.

2. Open your browser and go to the following URL:

     https://server/SilverStream/Meta/Certificates?action=dataCA 
   

   where server is the name of your server.

   The server will extract the CA from the certificate and send it back to the client.

3. Save the file that the server presents to an appropriate area.

To extract a CA from a client certificate, server:

1. Invoke the SMC.

2. Select Security options.

3. Select the Certificates panel.

4. Select the CA Certificates tab.

5. Click Add Certificate Authority.

6. Browse for the location of the extracted CA, then click Open.

   The program installs the new CA to the database.

7. To activate the new CA, restart the server by clicking the Restart (server) icon.

Accessing certificate users

Certificate users are added to a security realm called Certificate Security. This realm is included in the lists of users and groups supported by the Silverstream Server.

To access certificate users:

1. Invoke the SMC.

2. Select the Security options.

3. Select the Users & Groups panel.

4. Navigate to a user from the Certificate Security list.

   

5. Use this dialog to view current users or add users to groups.

       For more information about users and groups, see Setting Up Users and Groups.

You can use certificate users in security expressions exactly as you use other users in SilverStream. For more information about security expressions, see Setting up access control.

Updating client certificates

An X.509 certificate includes a start and end date. A client will not be allowed to connect to the server with a certificate that has expired. You can update the certificate representing an established Certificate Security user by obtaining a new certificate and assigning it to a user already known to the SilverStream Server. This ensures that any security expressions involving the old user will continue to work properly.

Normally an existing certificate user would present the updated certificate to the server using the URL described in Manually installing client certificates.

NOTE   If you are running the server with one of the auto-install parameters described previously (level 2 or 3) and an existing client certificate holder attempts to access the server with a new (updated) certificate that the server validates, that client will be installed as a new user. This client might be restricted from resources available to the previous user.

To update an existing certificate user:

1. Select Security options.

2. Select the Users & Groups panel.

3. From the Certificate Security domain navigate to the user you want to update.

4. Select the Properties button. .

5. This displays a form with three tabs.

   The General tab shows general information concerning the user. The Additional Attributes tab displays information about the certificate. The Update tab allows you to update the certificate for the selected user.

6. Select the Update tab.

7. Enter the file name for the updated certificate, then click Update.

   This replaces the old certificate with the new version without changing the identity of the user on the server.

Enabling authentication   

The SMC lets you enable user authentication and activate related settings. Use these settings when you are ready to deploy authentication for both HTTP user/password protection and HTTPS certificates.

To enable user authentication:

1. Invoke the SMC.

2. Select Security options.

3. Select the Server Security panel.

   

4. Activate the security options, as described in the following table.

   Item	Description
   Require user authentication	Requires users when first accessing the server to authenticate themselves, either through a certificate or user name/password. Once authenticated, users do not have to be authenticated again during the session. Setting this option disallows Anonymous users--if you don't set this option, a user can access the server without logging in or sending a certificate, in which case the user is known as Anonymous. If you are using this option with HTTPS, activate Client certificate level in HTTPS as well. NOTE   You can also require login on a per-object basis. See Changing access.
   Disable HTML directory listing	Disables the listing of server directory contents in a browser when the browser points to the directory's URL. Prevents users from seeing directory contents. If this option is turned on, the server returns a FORBIDDEN error.
   Allow users to modify own account	By default, users can change their own user properties. You can turn off this privilege by deselecting this check box. If this privilege is turned off, only administrators (that is, individuals with Read Server Configuration and Modify Server Configuration permissions) can change user properties.     For more information, see Editing user properties.
   Security resource timeout	Specifies how frequently the SilverStream Server will upload current lists of users and groups from the NT, LDAP, and/or NIS+ servers, which would include any updates to these lists.     For more information, see Resetting the security resource timeout.
   Client certificate level in HTTPS	Activates the use of client certificates for HTTPS security (requires a server certificate).     For more information, see Enabling and installing client certificates.

5. For changes to take effect, click Update.

Setting up access control   

SilverStream supports the Java security Access Control List (ACL) API, allowing developers to programmatically control access to any SilverStream object, including data and application objects. This Java security is complementary to the security provided by the SMC and the SilverStream Server Administration API.

    For more information about the SilverStream API, see Using the Server Administration API.

You can use the SMC to control SilverStream Server administration at the server or cluster level and to control access to the following:

• A SilverStream database

• The design of individual SilverStream database tables

• Rows within a table

• Directories

• Pages, forms, and views

• Media objects

• Business objects

You specify access by setting permissions, as described next.

Permission types   

SilverStream allows you to set up access control on various operations through permissions. Each object type has a different set of supported permissions. You can set the following permissions:

Permission	Description
Read Server Configuration (on servers and clusters only)	Lets the user view administration settings and connection parameters.
Modify Server Configuration (on servers and clusters only)	Lets the user administer the server or cluster by, for example, changing connection parameters. Also lets a user add users and groups and change user passwords.
Read Directory Listing (on servers and clusters only)	Lets the user browse the server directories. Does not affect whether a user can access an object.
Read Users and Groups (on servers and clusters only)	Lets the user see users and groups that have been defined on the server. Users must have this permission in order to set permissions, because otherwise they cannot see the users and groups.
Read	For an object, lets the user look at the object but not make modifications to it. For a database or directory, lets the user list the contents of the database or directory and look at objects in that database or directory. To easily prevent users from accessing objects in a database or directory, deny them Read access at the database or directory level.
Modify	Lets the user create and modify an object.
Write (on media objects such as images and sounds only)	Lets the user create and overwrite an object.
Set Permissions	Lets the user limit who can alter access control information on an object. For example, you may decide that only administrators should be able to change the security properties on this object.
Default Execute (on databases and directories only)	Sets the default Execute permission for objects within the database or directory.
Execute	Lets the user run an object, such as a form, page, view, or business object. In order to run an object, the user does not need Read permission for the object, but does need Read permission for the directory containing the object.
Read Design (on tables only)	Lets the user read table design information.
Modify Design (on tables only)	Lets the user modify tables.
Select (on tables only)	Lets the user set up row-level retrieval access on individual tables by creating selection criteria through the Expression Builder. This is useful if you want to set up row-level security in a table. To restrict write access to the table's data, you need to write a business object. For more information, see the chapter on table-modified business objects in the Programmer's Guide.

Default object security   

SilverStream sets up security by default. Object security defaults are set as follows:

• All users have full access permissions on objects unless otherwise specified.

• If you define a particular access at the directory level, it becomes the default access for any new objects created within that SilverStream directory. A directory is a container for objects of one type. For example, all forms are in the Forms directory. When you have selected the Permissions panel in the SMC, you can expand directories to see their contents (assuming you have the Read permission on that directory).

  Any new object takes on the access security of the immediate parent object. For example, if you create a new form in a SilverStream database, the form is saved in the Forms directory and takes on the security settings of the Forms directory.

How access works   

• Most directory levels in the hierarchy allow you to set Read, Write, Execute, and Set Permissions access rights. Each object or resource within a hierarchy can be secured in an identical fashion.

• If access rights are defined at the database level, you see all databases but can only expand or open the ones for which you have Read access.

• If you have Read access to a particular directory, you can see the named contents of that directory.

• Requests for the contents of the named object may be restricted based on expressions set on that object.

• You can change security access rights only if you have Set Permissions rights to the SilverStream database directory or object. You can then use specific access expressions to further limit modifications.

• To restrict write access to rows on INSERT, UPDATE, or DELETE, you can create business objects that enforce access restrictions.

      For more information, see the chapter on table-modified business objects in the Programmer's Guide.

Changing access   

You can change object security at the server or cluster level, at the directory level, or at the object level by setting permissions in the SMC.

NOTE   In addition to setting permissions in the SMC, you can also set permissions at the command line using a SilverCmd utility. For more information, see SetSecurity in the SilverCmd Reference in the online Tools Guide.

To change user access:

1. Select Security options.

2. Select the Permissions panel.

   The SMC view changes: All the clusters, servers, and databases being administered by the SMC are now expandable, allowing you to list their contents in order to set permissions at any level you want.

   

3. Select an object or directory and set your permissions as described in Setting permissions.

Setting permissions on multiple objects

You can set permissions on more than one object at a time as long as all the objects are in one directory (that is, the objects are all the same type, such as forms or pages, and they are all on the same server): Select Shift+Click for contiguous entries or Ctrl+Click for non-contiguous entries and specify the permissions for all the selected objects.

Setting the scope of the permissions and whether login is required

The buttons that appear at the bottom of the Permissions panel depend on whether you selected a directory or an object. The following is a description of each button that might appear.

Item	Description
Apply to this directory only	Appears for directory selections only. Applies permissions only to the selected directory, and becomes the default setting for new objects in the directory structure. This selection does not change permissions for existing objects in the directory.
Apply to this directory and all descendants	Appears for directory selections only. Applies permissions to the selected directory and all existing objects within that directory (including subdirectories) as well as new objects. This selection overrides any existing settings for existing objects.
Require login for access	Appears for object selections only. Requires the user accessing the object to be authenticated, either by a client certificate or by being logged on. This sets authentication on a per-object basis. You can also require authentication at the server level. See Enabling authentication.

Setting permissions   

Each tab on the form represents a permission type that applies to the selected directory or object. By default, all access is unrestricted. To restrict access, select a tab, deselect Unrestricted, then select either Simple list or Advanced expression.

CAUTION!   When you uncheck Unrestricted, be sure to modify the Simple list or Advanced expression, otherwise, no one will have access. This problem will also occur if you clear all previous Simple list entries. If you find yourself in the situation where no one has read access to the server, you can run SilverMasterInit using the -a command-line option. For more information, see Using the SilverMasterInit program.

Using simple lists

This option allows you to specify users and groups that are known to a security provider and have access permission as defined in the provider setup.

To use simple lists:

1. In the SMC, select Security options.

2. Select the Permissions panel.

3. Select the objects or directory you want to set permissions for on the left side of the SMC.

4. In the Permissions panel, select the tab for the permission type you want to restrict.

5. Turn off Unrestricted to activate the Simple List button.

6. Simple List is the default selection. From the form, select the users and groups to whom you want to grant permission, then click >. To select all users or groups, click >>. Selected users and groups are listed in the list box on the right.

   To remove the permission from users or groups, select the user or group and click <. To remove all users and groups, select <<.

   

Using advanced expressions

Use this option to build expressions that let you specify access according to particular criteria. To use advanced expressions, select Advanced Expression instead of Simple List (see the previous procedure). Expressions can include any of the following:

• Identity/group membership
• Built-in functions, which can perform logical and relational operations
• Database content, for row-based access control

To use advanced expressions:

1. Select the objects or directory you want to set permissions for on the left side of the SMC.

2. In the Permissions panel, select the tab for the permission type you want to restrict.

3. Turn off Unrestricted and select Advanced Expression.

   The SilverStream Expression Builder displays selection panes for variables, functions, and operators.

   

Examples of advanced expressions

The following are examples of advanced security expressions.

• Use the day() method to disallow access to the object on weekends (the day() function returns a number from 0 to 6, where 0 indicates Sunday, 1 indicates Monday, and so on):

    day(now()) >= 1 and day(now())<= 5 
  

• Similarly, the following expression disallows access to an object except between 9:00 and 5:00, Monday through Friday:

    (day(now()) >= 1) and 
    (day(now()) <= 5) and 
    (hour(now()) >= 9) and 
    (hour(now()) <= 17) 
  

    For more information about specifying expressions, see the chapter on expressions in the Programmer's Guide.

UUID support

The Expression Builder supports Universally Unique Identifiers (UUIDs) for security expressions. These provide a more secure system than simple integer IDs. UUIDs are used by default in simple security expressions, and are available in advanced expressions.

You can enter UUID expressions directly in the Expression Builder, or access them from the ID section in the Functions panel.

Function	Description
userID()	Finds the UUID of the user currently logged on.
userID('name')	Finds the UUID of a specific user. To create a qualified name, start with the security realm (SSSW, NT, LDAP, or NisPlus), add security authority (such as the NT domain name or LDAP/NisPlus server name), then add the user name. Separate each component with two backward slashes (\\). (You need to escape backslashes in user names by doubling the backslashes.) By default, if both the realm and authority are missing, a SilverStream user is assumed. By default, if realm is missing, an NT user is assumed, with the first component assumed to be the NT domain. For example: userID('bobh') refers to the SilverStream user bobh (user defined in Silver Security) userID('DEVA\\JWilkins') refers to the NT user JWilkins, who is in the NT domain DEVA.
groupID('name')	Finds the UUID of a specific group. Group names, like user names, consist of a qualified name. For example: groupID('Administrators') refers to the Silver Security Administrators group. groupID('DEVA\\Accounting') refers to the NT Accounting group in the DEVA domain.
UUID('uuidString')	Finds the UUID corresponding to the string representation of a UUID. This form is used when a group ID or user ID cannot be resolved. SilverStream translates names into corresponding UUIDs before storing them in the AgAccessRights system table. Similarly, when the client views the expression, the internal form is translated back into human-readable names. If an internal UUID cannot be translated (for example, if it has been deleted), UUID() is used.

Examples

The following are examples of security expressions using UUID.

• This example restricts access to the Silver Security users administrator and bobh:

    userID() in (userID('administrator'),userID('bobh')) 
  

• This example restricts access to the Silver Security user bobh and the NT user JWilkins, who is in the NT domain DEVA:

    userID() in (userID('bobh'),userID('DEVA\\JWilkins')) 
  

• This example restricts access to the SilverStream user administrator and any user in the SilverStream Developers group:

    userID() in (userID('administrator')) or userID() userin (groupID('Developers')) 
  

• This example restricts access to the SilverStream user administrator and any user in the NT Accounting group, which is in the DEVA domain:

    userID() in (userID('administrator')) or userID() userin (groupID('DEVA\\Accounting')) 
  

    For more information about specifying expressions, see the chapter on expressions in the Programmer's Guide.

Row-level expressions

You can perform database table and row-based access control through the SELECT expression on a table. Row-level expressions work as follows:

• The expression may involve any number of columns.

• The SilverStream Server (or the database) evaluates this expression during a SELECT operation.

• Only rows that pass the SELECT expression are returned.

To use row-level security:

1. Select the table for which you want to set permissions.

2. On the Permissions panel, select the Select tab.

3. Turn off Unrestricted and select Advanced expression.

   

4. Select the column in the left panel and write an expression.

Examples of SELECT expressions

The following are examples of row-level SELECT expressions.

• This example uses a group and a table column called SalesCode. The SELECT expression will show orders whose sales codes are between 100 and 200 only to users who are in the Northeast sales group.

    userID() userin (groupID('NorthEast-Sales')) AND orders.SalesCode BETWEEN 100 AND 200 
  

• This example uses an if...then statement to use a conditional expression. The following SELECT expression will show employees whose status is 3 only to managers.

    if (userID() userin(groupID('Managers')))  
    then (employees.status>0)  
    else (employees.status<>3)  
    endif 
  

    For more information about specifying expressions, see the chapter on expressions in the Programmer's Guide.

The INLIST operator

The INLIST operator is a SilverStream construct that can be used in an advanced SELECT security expression. For example, you may have special columns in your tables that contain information about who can view them. The rows are retrieved and then filtered through this expression using the column's values.

Example

For example:

• The Project table has a column called Allowed_Groups, which has a type varchar(100).

• The first row has the following value for Allowed_Groups: "Administrators Developers Designers".

• The second row has the following value for Allowed_Groups: "Administrators"

• The third row has the following value for Allowed_Groups: "Administrators Developers".

Suppose a user named Dev1 belonging to the Developers group logs in to the server. The following shows the SELECT security expression on table Project.

  userID() userin (inlist(PROJECT.ALLOWED_GROUPS)) 

Next, Dev1 creates a form against Project table and runs it. The server retrieves three rows and applies the SELECT expression to every row before giving the form back to the client. Because Dev1 belongs to the Developers group, the server shows only the first and third rows, but not the second row, which is restricted to the Administrators group.

Excluding robots   

Robots are programs, such as search engines and web crawlers, that can traverse many pages on a Web site by recursively retrieving linked pages. The SilverStream Server supports the commonly used robot exclusion protocol that allows you to specify exactly what files and directories robots that conform to the exclusion protocol can access on your Web site.

NOTE   The robot exclusion protocol is purely voluntary. There is no guarantee that a robot conforms to the protocol, but most do.

In this exclusion protocol, the access policy for robots is specified in a file called robots.txt. The robots.txt file that is shipped with SilverStream tells robots not to proceed below the root of the server (that is, it disallows all access to all robots that conform to the exclusion protocol). So by default, conforming robots are disallowed all access to the Web site you have developed with SilverStream.

You can modify robots.txt to specify the kind of access you want to provide to robots. For example, you might want to allow search-engine access to some directories but not to others.

To modify robot access:

• Edit robots.txt in the SilverStream\resources directory.

      For information about the protocol's format and semantics, including examples, see http://info.webcrawler.com/mak/projects/robots/norobots.html.

  The next time a conforming robot requests the access policy from the server, the updated robots.txt file will be read and the information sent back to the robot.

Locking down an application or a server   

At certain points in the development and deployment process, you will want to lock down an application database, a server, or an entire cluster, that is, secure it so that the appropriate access permissions are set. For example, when deploying an application, you might want to lock down the application database so no one can access it except you, then progressively unlock it as appropriate in the production environment.

Included with the SilverStream Server (in the SilverStream\DTDs directory) are three sample XML files that are input files for the SilverCmd SetSecurity command. These files show how you can lock down an application, a server, or a cluster using SilverCmd.

All the files are well-commented with usage notes.

    For information on using SilverCmd, see the SilverCmd Reference in the online Tools Guide.

About the XML

If you look at the XML files, you will see that permissions are set differently and sometimes have different names than you are accustomed to in the SMC. That's because the SMC has an interface designed to make it as easy as possible for you to administer the server. Under the covers, permissions are set by assigning values to resources; it is those resources that are referenced in the XML files. You don't need to know anything about the specific resources when using the SMC.

Locking down an application   

The secure_application_sample.xml input file shows you how to lock down an application.

You might want to apply this file to an application database just before deploying it in order to secure it properly.

Locking down a server   

The secure_server_sample.xml input file shows you how to lock down an entire server.

You might want to apply this file to a server when putting it into production.

Locking down a cluster   

The secure_cluster_sample.xml input file shows you how to lock down a cluster.

You might want to apply this file after you have secured each server in a production cluster using secure_server_sample.xml.

Security checklist   

The levels and types of security that you implement depend on the scale and demands of your particular enterprise. This section provides a security checklist for the production and development server environments, and recapitulates some of the security features covered in this chapter.

Securing the production server   

The following is a security checklist for the production environment.

• Make sure that the SilverStream Server is installed inside any firewalls your company uses.

      For more information, see Server Configuration.

• Set up a unique database account for SilverStream to use to connect to each database.

      For more information, see Setting up a supported database.

• If you intend to use SSL communications, obtain a certificate and install it on the server.

      For more information, see Using certificates.

• Change the default password for Administrator, or create another user with the Locksmith privilege, and delete Administrator.

      For more information, see Setting Up Users and Groups.

• Use the SMC to enable authentication and disable HTML directory listing on the server.

      For more information, see Enabling authentication.

• Use the SMC to secure directory and object access for users and groups using simple and advanced expressions. Use the Require login for access option for selected objects as needed.

      For more information, see Setting up access control and Locking down an application or a server.

Securing the development server    

The following is a security checklist for the development environment.

• Add your developers to the Developers group and restrict access to this group as described below.

      For more information, see Setting Up Users and Groups.

• Optionally, you can use secure communications between the SilverStream Server and Java clients such as the SilverStream Designer and SMC through a DSA certificate.

      For more information, see Using certificates.

• As an administrator with the Locksmith privilege, secure any objects from specific developers as needed. You can do this at the server, cluster, or object level.

  You can require login for forms, tables, views, and pages by activating Require login for access.

  Secure access by directory or object type, for example:

  • The Tables directory, allowing write access only to designated database developers

  • The Form, View, and Pages directories, allowing write access only to developers

  • The Objects directory, allowing write access only to designated business object developers

    NOTE   The ability to write a business object is like "superuser" access. A business object can bypass other SilverStream security and shut down the server or otherwise compromise data.

  • The Media directory and its subdirectories, allowing write permissions only to developers

  • If necessary, set up row-level security on selected tables.

        For more information, see Setting up access control and Locking down an application or a server.

Securing server administration   

You must limit server administration to authorized individuals. The following is a checklist for administrative security.

• Using the Locksmith privilege, use the SMC to give yourself Write and Set Permissions privileges to the server.

      For more information, see Using the Locksmith privilege.

• Secure each object and database, allowing Set Permissions access only to server administrators. Decide whether to restrict access by user, group, or by advanced expression.

      For more information, see Setting up access control.