in which the CA publishes Identity Certificates
The CA and LDAP servers are independent of Akenti and can be run by administrators or organizations other than the one that is running the Akenti resource server. The Akenti resource server needs to have the x509 identity certificates and public keys of all the CA's that it is going to trust. It must also know the location of the LDAP server or some other location in which each CA publishes its certificates.
An Akenti secure resource server can run by itself without the monitor server, cache server or resource definition server. It can either call the Akenti standalone server to make authorization decisions or it can compile in the Akenti policy engine libraries and make the decsions itself. Without the monitor server logging will simply be done to stderr. Without the cache server, no caching will be done and repeated accesses to resources will be just as slow as the first access. If the resource definition server is not running, stakeholders will be unable to use the interactive GUI programs to issue new UseCondition or Attribute certificates. The alternative way to create certificates,is to create a correct XML definition of the certificate and use the program CertGen.java to create a signed certificate from it.
See Akenti Server infrastructure for more
details on what these servers do.
2. Configuration and Policy Certificates
There are several configuration files used by Akenti. Akenti.conf is the starting point. It defines the pathname to the root of the resource tree(s), defines the file names for Policy certificates and the Resource Definition File, defines the ports and other parameters for Akenti server, the cache server, the monitor server and the resource definition server. There is a resource definition file that defines the attribute names, values, issuers and actions that are make sense for resource domain. The hierarchical set of Policy Certificates define the trusted CAs and the stakeholders. There may optionally be a resource map that maps the resource names that a user might access, to one that matches the Akenti resource names. This mapping is just a convenience feature to map from a name in the style that a resource gatekeeper can use (for example the full pathname of an executable) to a name that is easier for Akenti to deal with. The Akenti policy engine, the Cache server and Monitor server all read Akenti.conf to find out various parameters and locations. The policy certificate are used both by the Akenti policy engine and the Resource Definition server. To use the Akenti/Apache Web server, you need set the SSL parameters and add an entry with the name of the Akent.conf file.
3. Configuration for the Akenti Policy Engine
Akenti Policy Certificates
The Akenti policy engine uses a hierarchical set of policy certificates to determine
access to a resource.
The default name for these files is .htauthority, but it can
be redefined
in the Akenti.conf file and in the case of the Akenti Web server in the
httpd.conf file as well - (e.g. AccessFileName .htauthority). There must
be a .htauthority file in the resource root directory. The resource root is
defined in Akenti.conf as RootResourceName (and also in the httpd.conf file, if any, as DoucmentRoot).
The policy certificate in the root must contain the Distinguished Names and pem-encoded certificates of
all the Certificate Authorities that this server will trust. It must also
contain a pointer to at least one UseCondition that at least grants
access to the resources the root level and may grant access to the entire resource tree. If no such UseCondition exists, Akenti will
permit no access to the resources.
A minimal root policy certificate that trusts one CA, allows only one stakeholder to
impose UseConditions at the root level looks like:
<AkentiCertificate>
<SignablePart>
<Header type="policyCertificate" SignatureDigestAlg="RSA-MD5" CanonAlg="AkentiV1">
(...)
</Header>
<PolicyCert>
<ResourceName>ResName</ResourceName>
<CAInfo>
<CADN>/C=US/O=Lawrence Berkeley National Laboratory/OU==ICSD/CN=IDCG-C</CADN>
<X509Certificate>
-----BEGIN CERTIFICATE-----
pem encoded X509 certificate of CA
-----END CERTIFICATE-----
</X509Certificate>
<IdDirs>
<URL> ldap://idcg-ca.lbl.gov/</URL>
</IdDirs>
<CRLDirs>
<URL> ldap://idcg-ca.lbl.gov/</URL>
</CRLDirs>
</CAInfo>
<UseCondIssuerGroup>
<Principal>
<UserDN>/C=US/O=LBNL/OU=ICSD/CN=Mary R. Thompson</UserDN>
<CADN> /C=US/O=LBNL/OU=ICSD/CN=IDCG-CA</CADN>
</Principal>
<URL> http://www-itg.lbl.gov/~mrt/Certificates/</URL>
<UseCondIssuerGroup>
<AttrDirs>
<URL>file:/usr/mrt/Attributes</URL>
<URL> http://idcg-ds.lbl.gov/~kjackson/Certificates/</URL>
</AttrDirs>
<CacheTime>1800</CacheTime>
</PolicyCert>
</SignablePart>
</AkentiCertificate>
The CAInfo element specifies the directory srvice which stores the
Identity Certificates issued by the CA. The UseCondIsserGroup element
specifies the URL that points to the directory in which UseConditions
are stored.for a complete expanation see Policy Certificate
There is a template for this certificate in the Akenti distribution in
testResourceTree/TEST/rootPolicy.xml.orig. It should be edited to
reflect your local CA, LDAP server and stakeholders and then a
crtificate should be generated and signed using the CertGen
program. The key that is used to sign it must belong to the Issuer
specified in the Header who must also be one of the Principal listed
in a UseCondIssuerGroup.
Subdirectories under the ResourceRoot may have their own .htauthority files
that can further limit access or grant more actions to the resources in that
subtree.
Resource Definition Files
The UseCondition, Attribute and Policy Certificate generator
applications need some information about the resource for which they
are generating certificates. This information is stored in a file
named .resattributes. There
is also a template for this file in the Akenti distribution in
testResourceTree/TEST/resattributes.orig. This file specifies a list
of CA's, the attributes they can define, and the host name of their
directory server; a list of attribute, values and who can issue
attribute certificates for them; and a list of actions that can be
defined for the resource.
The resattributes.orig should be copied and renamed to .resattributes
during Akenti setup and edited to reflect your CA's, users and
resources.
4. Setting up Akenti Standalone Server
The Akenti server code can be run either in an insecure mode which assumes
that it is running on the same host as the resource gateway, or a secure
mode in which it can be called accross a network. If it is run in a secure
mode it must have its own X.509 identity certificate.
Generate a signing certificate for Akenti
The Akenti secure server needs a private/public key to sign the capability
certificates that it returns containing the user's permissions with respect
to a given resource. It also uses this certificate to identify
itself to a client. The DN in the certificate should identify itself
as an Akenti server. This key pair can be generated in several ways;
we have provided a simple program to generate key pairs and either
self-signed or CA signed X.509 certificates; or you can use the
commands that are part of the OpenTLS openssl program, e.g. generate a
key pair, generate a certificate request and sign the certificate
request with key you have generated. You should chose a name that
identifies your Akenti server, such as Akenti-<host>, the
private key needs to be stored unencrypted so that the Akenti policy
engine code can use it. It not necessary to have the
certificate signed by a CA but it can be. To use the tools/genX509cert
program to generate a self-signed certificate:
genX509cert -self -DN /C=us/O=Your_Org/CN=Akenti-your_host -key AkPrivKey.pem
-cert AkCert.pem
The name and location of
these keys is specified in the Akenti configuration file as follows:
- ServerKeyFile /home/http/ssl/private/AkPrivKey.pem
- unencrypted Akenti private key
- ServerCertFile /home/http/ssl/certs/AkCert.pem
- certificate containing Akenti ID and public key
5. Setting up a Secure Resource server
To create or adapt a resource server to use Akenti authorization, it must
communicate with its clients through a protocol such as SSL which uses
client and server X.509 certificates to establish an authenticated connection.
The Akenti policy engine requires either the authenticated user's DN and its
certificate issuer's DN or else the X.509 certificate or certificate chain that
was used to establish the connection. Such a server will need to have an
identity certificate of its own, which can be generated with the genX509cert
program or openssl or requested from a standard CA.
The resource server can either compile with the akenti policy engine libraries
and use the API check access calls (see Akenti API
for details) or it can link with the Akenti client libraries and call the
Akenti standalone server (see Akenti Server
Interface)
Akenti Web server configuration
We have added an Akenti authorization module for the apache-SSL server v1.3.
and built a Web server that will call the Akenti policy engine to make access
control decisions. To deploy this server follow the instructions for the
Apache SSL server with respect to the values of the SSL directives in the
httpd.conf file. A directive naming the Akenti.conf file needs ot also be
included in the httpd.conf.
You will need to generate a server identity for it, which you can do using
the genX509cert program. It can be either self-signed or signed by a CA whose
certificate can be imported to the user's browsers.
The Akenti Web server uses both Akenti.conf and httpd.conf. The DocumentRoot and AccessFileName are defined in both these files and must be the same.
The DocumentRoot directory is both where Akenti looks for a oot policy certificate
and where the Web server expects the root of the document tree to be.
The Akenti Web server considers each directory in the document tree to be a
resource to which access can be individually controlled. Thus, you can
put additional Authority Files (.htauthority) at any level in the document tree
and it can affect the access from that point on down.
Note that every resource must have an applicable root policy
certificate. Akenti normally the root policy is to regress up a
resource tree until the DocumentRoot is found and use that
.htauthority file. Thus, the simplest way to setup your web server is
to have all the resources located under the document root. Directories
like cgi-bin and icons which are typically put above the DocumentRoot
should be under the DoucmentRoot instead. If you wish to allow access
to individual UserDir's the user's must put root policy certificatesin
their top level public web directories or put a reference back to the
DocumentRoot authority file. If Akenti is unable to find a root policy
certificate for a resource, it will not permit any access to that
resource.
6. Overview of Netscape 4.3 Certificate Management System
Any user who wants to access Akenti protected resources must have an
Identity Certificate.If your resource users have access to a CA, the
Akenti server can add the Identity certficates of those CA's to its root
policy certificate. If you need issue your users certificate's Netscape's
Certificate Management System provides relatively easy to use CA and LDAP
servers.
The CMS system should be set up with at least a CA and one LDAP server that
where it will publish its certificate. There should be at least two
privileged users authorized to issue certificates for a CA. When a CA is
installed one person
is automatically given privileged status. When a certifcate is issued, the
issuer has a choice to make the new certificate holder a privileged user.
The user who resuests a certificate from his home Netscape browser by going
to the main CA Web page. The forms, ManUserEnroll.html and cms-funcs.js,
and that are presented to the user can be modified to present a list of
default values for Organization and Organizational Units.
Once the user has submitted a request, the designated list of agents will
receive email, containing a link that can be used to process the request.
Adding A User to LDAP database
The certificate needs to be published to the LDAP server so that Akenti
can find the certificates for people that have signed use-condition, policy
and attribute certificates. In the current version of CMS, the user needs
to be manually added to the publishing LDAP server, before the certificate
can be published. If it is added before
you issue the certificate, the certificate will be automatically added to the
LDAP entry. If you issue the certificate before the LDAP entry is made, you must
go back to the Netscape CA web page and do an "update LDAP directory" action.
The certificates must be in the LDAP data base for Akenti to use them.
In this example, I will use:
E=CTLarsen@lbl.gov, CN=Case Larsen, UID=clarsen, OU=ICSD, O=Lawrence
Berkeley National Laboratory, C=US
- go to http://idcg-ds.lbl.gov/,
- select "new entry"
- type in the "CN" they requested into CN.
e.g. Case Larsen
- select ICSD to put the user in the ICSD organizational unit.
This should be the same organizational unit that they requested
for their certificate.
In other words, the DN in their certificate should match the DN
of the new entry which you are creating.
- Click on "continue"
You may be asked to authenticate to the directory server.
Authenticate as the Directory Manager and type the Directory Manager
root password which is 'p*'.
- On the "New Person - Case Larsen, ICSD" page:
type in
last name, email, uid, organizational unit, and title
.
The title
should be "user" This is the minimum information
required so that the Netscape CA can match the entry when inserting
the certificate.