Certificate Authentication Service provides the AIX 5.2 operating system with the ability to authenticate users using X.509 Public Key Infrastructure (PKI) certificates and to associate certificates with processes as proof of a user's identity. It provides this capability through the Loadable Authentication Module Framework (LAMF), the same extensible AIX mechanism used to provide DCE, Kerberos, and other authentication mechanisms.
This section discusses the following topics:
Every user account participating in PKI authentication has a unique PKI certificate. The certificate in conjunction with a password is used to authenticate the user during login. PKI certificates are based on public key/private key technology. This technology uses two asymmetric keys to encrypt and decrypt data. Data encrypted using one key can only be decrypted using the other key. A user keeps one key private, called the private key, storing it in a private keystore while publishing the other key, called the public key, in the form of a certificate. Certificates are commonly maintained on a Lightweight Directory Access Protocol (LDAP) server, either within an organization for intra-company usage or on the Internet for world-wide usage.
For a user named John to send a user named Kathy data that only she can decrypt, John would obtain the public key from Kathy's published certificate, encrypt the data using Kathy's public key, and send the data to her. Kathy would decrypt the data from John using her private key located in her private keystore.
This technology is also used for digital signatures. If Kathy wants to send data to John that is digitally signed by her, Kathy would use her private key to digitally sign the data and send the data and digital signature to John. John would obtain the public key from Kathy's published certificate and use the public key to verify the digital signature before using the data.
In both cases, Kathy's private key is maintained in a private keystore. The many types of private keystores include smart cards and files, but all keystore types protect private keys through the use of passwords or Personal Identification Numbers (PINs). They typically provide storage for multiple private keys along with certificates and other PKI objects. Users typically have their own keystores.
Certificate authentication service uses digital-signature technology to authenticate a user during login. Certificate authentication service locates the user's certificate and keystore based off the user's account name, obtains the certificate's matching private key from the user's keystore using the user's password, signs a data item with the user's private key, and checks the signature using the user's public key from the certificate. After the user authenticates, the system stores the user's certificate in protected memory, associating the certificate with every process created by the user. This in-memory association enables quick access to the user's certificate for any process owned by the user, as well as by the operating system's kernel.
Understanding certificate authentication service requires a basic understanding of certificates, certificate formats, and certificate life-cycle management. Certificates are standardized objects that follow the X.509 standard, of which version 3 (X.509v3) is the latest version. Certificates are created, signed, and issued by a Certificate Authority (CA) which is most commonly a software application that accepts and processes certificate requests. Certificates are comprised of several certificate attributes. Some of the attributes are required, but many are optional. Certificate attributes commonly used and discussed in this document are:
Each certificate has a unique version number that indicates with which version of the X.509 standard it conforms. Each certificate has a serial number which uniquely distinguishes it from all other certificates issued by the same CA. The serial number is unique only to the issuing CA. The certificate's issuer name identifies the issuing CA.
Certificates are valid only between two specified dates: the "Not Before" date and the "Not After" date. Therefore, certificates may be created prior to their validity date and expire at some date in the future. It's common for certificates to have a life span of 3 months to 5 years.
The subject distinguished name specifies the certificate owner by using a specialized naming format known as a Distinguished Name (DN). A DN allows for the specification of the country, organization, city, state, owner name, and other attributes associated with the requesting entity (usually a person, but not limited to a person). The subject alternate name e-mail allows for the specification of the owner's email address and the subject alternate name URI allows for the specification of the owner's Web site URI/URL.
Certificate Authorities issue, store, and typically publish certificates. A common place to publish certificates is on an LDAP server, since LDAP allows for easy access to community oriented data.
CAs also handle the revocation of certificates and the management of certificate revocation lists (CRLs). Revoking a certificate is the act of publishing the fact that a specific certificate is no longer valid due to reasons other than the expiration of the certificate's validity period. Because copies of certificates can be maintained and used outside the control of the issuing CA, CAs publish a list of revoked certificates in a CRL so that outside entities may query the list. This places the responsibility on entities using a copied certificate to compare the copied certificate against the issuing CA's CRL. A CA may only revoke certificates that it creates or issues. It cannot revoke certificates issued by other CAs.
Administrative reasons for revoking a certificate include:
CAs also have their own identifying certificate. This allows CAs to identify each other in peer-to-peer communications among other uses (for example, chains of trust).
Many CAs support the Certificate Management Protocol (CMP) for requesting and revoking certificates. The protocol supports multiple methods to establish a secure connection between a client (also known as an End Entity) and the CA, though not all clients and CAs support all methods. One common method requires each certificate creation and revocation request to use a reference number and password recognized by the CA. Other data such as a special certificate recognized by the CA may also be required. Revocation requests may require the matching private key of the certificate being revoked.
Although CMP provides for certificate creation and revocation requests, it does not support CRL query requests. In fact, CRLs are often accessed through out-of-band methods. Since CRLs are often published on LDAP servers, software applications can obtain the CRL from an LDAP server and manually scan the CRL. Another emerging method is the Online Certification Status Protocol (OCSP), but not all CAs support OCSP.
CAs are typically owned and operated by government organizations or trusted private organizations that attempt to provide assurance that certificates issued by them correspond to the person who requested the issuance of the certificate. The phrase issuing a certificate means to create a certificate and is not the same as requesting a copy of a published certificate.
The most common format for storing individual certificates is in Abstract Syntax Notation version 1 (ASN.1) format using the Distinguished Encoding Rules (DER). This format is referred to as DER format.
A keystore (sometimes called a keyset) contains a user's private keys matching the public keys of their certificates. A unique key label is assigned to every private key, usually by the user, for easy identification. Keystores are password-protected requiring a user to enter a password prior to accessing the keys or adding new keys. And typically, users have their own keystores. Keystores come in many different forms, for example: smart cards, LDAP-based, file-based, and so on. Not only do the forms vary, but so do the methods used to access them and the formats used to store the private key data. Certificate authentication service only supports file-based keystores.
Certificate authentication service functions as a client/server model. The server side contains a Certificate Authority (CA) for creating and maintaining X.509 version 3 certificates and certificate revocation lists (CRLs). (Typically, an organization uses one CA for the entire organization.) The client side contains the software (commands, libraries, load modules, and configuration files) required by every system participating in PKI authentication. The installation package for the server is cas.server and the installation package for the client is cas.client.
To create a PKI user account, use the AIX mkuser command. After it is created, each account has a certificate and a private keystore. (Existing accounts can be converted to PKI accounts too, but other steps are required.) The administrator supplies the keystore passwords to the new users, and new users can then log in to the system and change their keystore password.
This section describes how a PKI user is authenticated. Users can have multiple certificates associated with their accounts. Each certificate has a unique, user defined tag value associated with it for easy identification, but only one certificate can be specified as the authentication certificate. Certificate authentication service uses a per-user attribute named auth_cert to specify which of the user's certificates is the user's authentication certificate. The value of the auth_cert attribute is the certificate's tag value.
The certificates, tags, matching keystore locations, matching key labels, and other related data are maintained under LDAP on a per-user basis. The combination of the user name and tag allows certificate authentication service to locate the certificate under the LDAP server. For more information on the PKI LDAP layer, see PKI LDAP Layer (Certificate Storage).
At login, users supply a user name and password. Using the user name, the system retrieves the user's authentication certificate tag from the user's auth_cert attribute. Combining the user name and tag, the system retrieves the user's certificate, keystore location, and matching key label from LDAP. It checks the validity period values found in the certificate to determine if the certificate has expired or has not reached its activation date. The system then retrieves the user's private key by using the keystore location, key label, and supplied password. After the private key is retrieved, the system verifies that the private key and certificate match using an internal signing process. If the two match, the user passes the PKI authentication step of the login procedure. (This does not imply that the user is logged in. Several other account checks are performed by the AIX system on a user account before allowing the user access to the system.)
For a certificate to be used as an authentication certificate, the certificate must be signed using a trusted signing key. The signature is stored under LDAP with the certificate for later reference. The implementation requires that a certificate have a signature before the tag can be assigned to auth_cert.
The authentication process does not compare a certificate against a CRL. This is due to performance reasons (CRLs take time to acquire and scan and may be temporarily unavailable), but also due to publishing delays of CRLs (CAs may delay an hour or more before publishing a revoked certificate through a CRL, making certificate revocation a poor substitute for disabling a user's account).
It is also worth noting that authentication does not require a CA. The majority of the work is performed locally by certificate authentication service, with the exception of retrieving data stored under LDAP.
The server side of certificate authentication service implements a CA written in Java and contains a Registration Authority (RA) along with self-auditing features. It publishes certificates and CRLs that it creates to an LDAP server. The CA is configurable through a set of configuration files (Java property files). It contains an administrative application called runpki that provides sub-commands to start and stop the server among other functions and supports CMP for creating and revoking certificates. The CA requires Java 1.3.1, the IBM DB2 7.1 database, and the IBM Directory 4.1. Due to DB2 requirements, the CA must run under a user account other than the root user.
The server contains the following commands to help install and manage the cas.server component:
The runpki command must be run after performing an su - operation to the user account under which the certificate authority is running. The command is located in the javapki directory under the certificate authority user account's home directory. (The mksecpki command creates the certificate authority user account.)
For example, if the certificate authority user account is pkiinst, then with root authority, type the following:
The client side of certificate authentication service implements the user authentication, user administration, and user certificate management functions of certificate authentication service. After it is installed and configured on a system, certificate authentication service integrates into the existing user authentication and administration functions (such as the mkuser, chuser, passwd, and login commands) through the use of the AIX Loadable Authentication Module Framework (LAMF). It also adds several commands, libraries, and configuration files to help manage user certificates and keystores.
Certificate authentication service can be used in conjunction with either the AIX LDAP database mechanism or the file-based database mechanism for storing standard AIX attributes. Certificate authentication service always uses LDAP to maintain user certificates, even when the file-based database mechanism is used. For limitations when using the file-based database, see Planning for Certificate Authentication Service.
The client side of certificate authentication service contains the most user oriented software of the two parts. For this reason, the following sections describe how certificate authentication service maintains and uses the data required for PKI authentication.
The following list describes some of the general features of certificate authentication service:
The client architecture of certificate authentication service takes a layered approach and is divided into the following components:
At the foundation of the client side is a Java-based daemon using the JCE security package. The daemon manages user keystores, creates key pairs, performs CMP communications, and provides all hashing and encryption functions. Because APIs of PKI service provider packages are not standardized for C applications, a wrapper layer API called the Service Management Layer (SML) provides a normalized API to application programs and daemons.
The SML service for the Java daemon is named /usr/lib/security/pki/JSML.sml. SML creates certificates, and creates and manages keystores, but it doesn't manage certificate storage. Certificate storage is managed by the PKI LDAP Layer.
The Java daemon uses PKCS#12 formatted keystore files for storing user keys. The keystores are protected by a single password used to encrypt all the keys in the keystore. The location of a keystore is specified as a URI. By default, certificate authentication service maintains keystore files in the /var/pki/security/keys directory.
Keystores are typically limited in size, including file keystores. The SML Layer provides the API for managing keystores.
Certificate authentication service supports only file keystores. It does not support smart card or LDAP keystores. You can support roaming users by placing the file keystores on a shared file system under the same mount point on all systems.
Certificate authentication service stores certificates and other certificate related information on a per user basis in LDAP through the PKI LDAP Layer. Certificate authentication service maintains the certificate associations on a per user basis on an LDAP server. A user account can have multiple certificates associated with it. Each association has a unique, user-specified tag for easy identification and lookup. Certificate authentication service uses the combination of the user's name and the tag to locate a user's certificate association in LDAP.
For performance versus disk space trade-offs, certificate authentication service can save either the entire certificate under LDAP or just a URI reference to the certificate. If a URI reference is used instead of a certificate, certificate authentication service queries the reference to obtain the actual certificate. References are most commonly used in conjunction with a CA which publishes its certificates on an LDAP sever. The types of URI references currently supported by certificate authentication service are LDAP references. Certificate authentication service stores certificates in DER format and expects URI references to refer to DER formatted certificates.
Certificate authentication service also stores the type and location of each certificate's matching keystore and key label in the same record as the certificate association on the LDAP server. This allows users to have more than one keystore and allows certificate authentication service to quickly find a certificate's matching private key. To support roaming users, a user's keystore must reside in the same location on all systems.
Certificate authentication service maintains the auth_cert attribute in LDAP on a per-user basis. This attribute specifies the tag of the certificate used for authentication.
All LDAP information is readable by ordinary users, except for the auth_cert attribute which is restricted to the LDAP ldappkiadmin account. Since the root user has access to the LDAP ldappkiadmin password through the acct.cfg file, applications running with the effective UID of root can access the auth_cert attribute. (This applies to the accessibility of the URI reference value, not to the data referenced by the URI reference value. Typically, the data referenced by the URI reference value is public.) The API for managing the certificate storage is contained in the libpki.a library.
In addition to serving as the home of the SML APIs and the PKI LDAP Layer APIs, the libpki.a library houses several subroutines. The library includes APIs that do the following:
On top of the SML API and PKI LDAP API resides the Loadable Authentication Module Framework (LAMF) layer. LAMF supplies AIX authentication and user administration applications with common authentication and user administration APIs regardless of the underlying mechanism (for example, Kerberos, LDAP, DCE, files). LAMF uses the SML API and the PKI LDAP API as building blocks in implementing PKI authentication.
It does this through the use of load modules that map LAMF's API to different authentication/database technologies. Commands like login, telnet, passwd, mkuser, and others use the LAMF API to implement their functions; hence, these commands automatically support new authentication and database technologies when new load modules for these technologies are added to the system.
Certificate authentication service adds a new LAMF load module to the system named /usr/lib/security/PKI. The module must be added by the system administrator to the /usr/lib/security/methods.cfg file before using PKI for authentication. The module must also be paired with a database type (for example, LDAP) in the methods.cfg file before it can be used for authentication. An example of the methods.cfg file containing the LAMF module and database definition can be found in The methods.cfg File.
Once the definitions are added to methods.cfg, the administrator can set the registry and SYSTEM user attributes (defined in the /etc/security/user file) to the new stanza value or values for PKI authentication.
Above all the API layers (LAMF, PKI LDAP, and SML) reside the commands. Besides the standard AIX authentication and user administration commands supporting certificate authentication service (through LAMF), several certificate authentication service specific commands exist. These commands help the user manage certificates and keystores. Below is a list of the commands along with a brief description.
For more information about these commands. see the AIX 5L Version 5.2 Commands Reference.
The Process Authentication Group (PAG) commands are new to AIX. PAGs are data items that associate user-authentication data with processes. For certificate authentication service, if the PAG mechanism is enabled, the user's authentication certificate is associated with the user's login shell. As the shell creates child processes, the PAG propagates to each child.
The PAG mechanism requires the /usr/sbin/certdaemon daemon to be enabled in order to provide this functionality. By default, the mechanism is not enabled. Certificate authentication service does not require the PAG mechanism to be enabled, but works with the mechanism if it is enabled.
To enable the certdaemon daemon, add the following line to the /etc/inittab file:
certdaemon:2:wait:/usr/sbin/certdaemon
A list of PAG commands along with brief descriptions follows:
For more information about these commands, see the AIX 5L Version 5.2 Commands Reference.
Similar to user-authentication, certificate authentication service integrates with the AIX user-administration functions through the AIX LAMF. Commands like chuser, lsuser, mkuser, and passwd use the LAMF API to implement their functions. Therefore, these commands automatically support new authentication and database technologies when new load modules for these technologies are added to the system.
The subsections below provide a more in-depth look at how PKI authentication affects the user administration commands.
The following commands are affected by the PKI authentication process:
The certificate attributes listed by the lsuser command are as follows:
Many default values are required when automatically generating an authentication certificate for a user using the mkuser command. Many of these values are specified in the newuser stanza of the /usr/lib/security/pki/policy.cfg file. The newuser stanza provides administrative control over these default values. Some of the default values are as follows:
A behavioral difference between creating a PKI user account and a non-PKI user account is that creating a PKI user account requires a password to encrypt the private key if the mkuser command generates an authentication certificate for the account. Since the mkuser command is a non-interactive command, the command obtains the password from the policy.cfg file and sets the keystore password (the private key password) to this value; therefore, the account is immediately accessible after creation. When creating a non-PKI user account, the mkuser command sets the password to an invalid value, preventing accessibility.
Because file-based keystores encrypt their private keys using the user's password, the root user cannot reset a file-based keystore password without knowing the keystore's current password. If a user forgets their keystore password, the root user will not be able to reset the password unless root knows the keystore's password. If the password is unknown, a new keystore and new certificates may have to be issued to the user.
Certificate authentication service uses configuration files for configuring the client-side: acct.cfg, ca.cfg, and policy.cfg. The SMIT interface provides support for these configuration files. The following sections provide information about the configuration files.
The acct.cfg file consists of CA stanzas and LDAP stanzas. The CA stanzas contain private CA information not suitable for the publicly readable ca.cfg file, such as CMP reference numbers and passwords. The LDAP stanzas contain private LDAP information not suitable for public access, such as PKI LDAP administrative names and passwords.
For every CA stanza in the ca.cfg file, the acct.cfg file should contain an equivalently named CA stanza, and all CA stanzas must be uniquely named. The LDAP stanzas are all named ldap, and for this reason, a CA stanza cannot be named ldap. Also, no stanza can be named default. An LDAP stanza must exist, and at least one CA stanza, named local, must also exist.
CA stanzas contain the following attributes:
The LDAP stanza contains the following attributes:
The following is an example acct.cfg file:
local: carefnum = 12345678 capasswd = password1234 rvrefnum = 9478371 rvpasswd = password4321 keylabel = "Trusted Key" keypasswd = joshua ldap: ldappkiadmin = "cn=admin" ldappkiadmpwd = secret ldapservers = "ldap.server.austin.ibm.com" ldapsuffix = "ou=aix,cn=us"
For more information, see the AIX 5L Version 5.2 Files Reference.
The ca.cfg file consists of CA stanzas. The CA stanzas contain public CA information used by certificate authentication service for generating certificate requests and certificate revocation requests.
For every CA stanza in the ca.cfg file, the acct.cfg file should contain an equivalently named CA stanza. Each CA stanza name in the ca.cfg file must be unique. At least one stanza named local must exist. No stanzas should be named ldap or default.
CA stanzas contain the following attributes:
The default CA stanza is named local. The following is an example ca.cfg file:
local: program = /usr/lib/security/pki/JSML.sml trustedkey = file:/usr/lib/security/pki/trusted.p15 server = "cmp://9.53.230.186:1077" crl = "ldap://dracula.austin.ibm.com/o=aix,c=us" dn = "o=aix,c=us" url = "http://www.ibm.com/" algorithm = RSA keysize = 512 retries = 5 signinghash = MD5
For more information, see the AIX 5L Version 5.2 Files Reference.
The policy.cfg file consists of four stanzas: newuser, storage, crl, and comm. These stanzas modify the behavior of some system administration commands. The mkuser command uses the newuser stanza. The certlink command uses the storage stanza. The certadd and certlink commands use the comm and crl stanzas.
The newuser stanza contains the following attributes:
The storage stanza contains the following attributes:
The crl stanza contains the check attribute, which specifies whether the certadd and certlink commands should check the CRL (yes) or not (no).
The comm stanza contains the timeout attribute which specifies the timeout period in seconds used by certadd and certlink when requesting certificate information using HTTP (for example, retrieving CRLs).
The following is an example of the policy.cfg file:
newuser: cert = new ca = local passwd = pki version = "3" keysize = 512 keystore = "file:/var/pki/security/keys" validity = 86400 storage: replicate = no crl: check = yes comm: timeout = 10
For more information, see the AIX 5L Version 5.2 Files Reference.
The certificate authentication service client generates the following audit-log events:
The certificate authentication service client generates several new trace events in the 3B7 and 3B8 range.
Certificate authentication service is available beginning with AIX 5.2. The minimum software requirements for certificate authentication service are a DB2 server, an IBM Directory server, and a certificate authentication service server. All can be installed on one system or on a combination of systems. Each enterprise must determine the best choice for their environment.
This section provides information on planning for certificate authentication service, as follows:
Certificate authentication service supports X.509 version 3 certificates. It also supports several version 3 certificate attributes, but not all certificate attributes. For a list of supported certificate attributes, see the certcreate command and the ca.cfg file. Certificate authentication service contains limited support of the Teletex character set. Specifically, only 7-bit (ASCII subset of) Teletex is supported by certificate authentication service.
Certificate authentication service supports keystore files. Smart cards, LDAP keystores, and other types of keystores are not supported.
By default, user keystores are kept in the local file system under the /var/pki/security/keys directory. Because the keystores are local to the system, they cannot be accessed by other systems; thus, user authentication will be restricted to the system containing the user's keystore. To allow for roaming users, either copy the user's keystore to the identical location with the same keystore name on other systems or place the keystores on a distributed file system.
Certificate authentication service supports an LDAP user-registry. LDAP is also the recommended user registry type to use with certificate authentication service.
Certificate authentication service also supports a file-based user registry. Certain restrictions must be enforced by the administrator for file-based PKI to work correctly. Specifically, identically named user accounts on different systems participating in PKI authentication must refer to the same account.
For example, user Bob on system A and user Bob on system B must refer to the same user Bob. This is because certificate authentication service uses LDAP to store certificate information on a per user basis. The user name is used as the indexing key to access this information. Because file-based registries are local to each system and LDAP is global to all systems, the user names on all systems participating in PKI authentication must map to unique user names in the LDAP namespace. If user Bob on system A is different from user Bob on system B, either only one of the Bob's can participate in PKI authentication or each Bob account must use a different LDAP namespace/server.
For configuration simplicity, consider maintaining the three configuration files (acct.cfg, ca.cfg, and policy.cfg) on a distributed file system using symbolic links to avoid having to modify configuration files on every system. Maintain proper access-control settings on these files. This situation may increase your security vulnerability because the information in these files will be transferred across your network.
The acct.cfg file contains sensitive CA reference numbers and passwords (see the carefnum, capasswd, rvrefnum, and rvpasswd attribute descriptions for acct.cfg). These values are used solely for CMP communications with the CA when creating a certificate and revoking a certificate, respectively. If compromised, the compromiser may be able to create certificates at will, and revoke anyone's certificate at will.
To limit the exposure, consider restricting certificate creation or revocation to a small number of systems. The carefnum and capasswd attribute values are required only on systems where certificates are created (either through the certcreate or mkuser commands). This may imply limiting user account creation to the same set of systems.
The acct.cfg file also contains sensitive trusted signing key information (see the keylabel and keypasswd attribute descriptions for the acct.cfg file). These values are used solely for special certificate verification operations. If compromised, the compromiser may be able to forge verified certificates.
To limit the exposure, consider restricting certificate verification to a small number of systems. The keylabel and keypasswd attribute values of the acct.cfg file and the trustedkey attribute value of the ca.cfg file are required only on systems where certificate verification is required. Specifically, on systems where the mkuser (with automatic certificate creation enabled) and certverify commands are required.
When creating a PKI user account, if the cert attribute of the newuser stanza in the policy.cfg file is set to new, the mkuser command creates an active PKI account complete with a working certificate and password. The password on the account is specified by the passwd attribute in the newuser stanza. Because keystores require a password in order to store private keys. This differs from other types of user account creations where the administrator must first create the account, then set the password before the account is activated.
Unlike other account types where the root user can change an account's password without knowing the account's password, PKI accounts do not allow this. This is because account passwords are used to encrypt keystores and keystores cannot be decrypted without knowing the password. When users forget their passwords, new certificates must be issued and new keystores created.
Other considerations when planning for the certificate authentication service include the following:
Package Name | Fileset | Contents | Dependencies | Installation |
---|---|---|---|---|
cas.server | cas.server.rte | Certificate Authority (CA) |
|
Manual |
cas.client | cas.client.rte |
|
|
Manual |
cas.msg | cas.msg.[lang].client | Message catalogs | cas.client | Manual |
bos | bos.security.rte | PAG commands and daemon | n/a | Installed with kernel |
The cas.server package contains the CA and installs in the /usr/cas/server and /usr/cas/client directories. An organization typically uses only one CA, and therefore, this package is installed manually. This package prerequisites the IBM Directory server side, db2_07_01.client, Java131.rte, and Java131.ext.security. The Java131.rte package is installed by default when the AIX 5.2 operating system is installed, but the other packages are manually installed.
In order for the db2_07_01.client package to work, the db2_07_01.server package must be installed on a system that is on the network.
The cas.client package contains the files required for every client system supporting certificate authentication service. Without this package, a system cannot participate in AIX PKI authentication.
Installation of Certificate Authentication Services consists of performing the following procedures:
The following scenarios are possible when installing and configuring LDAP for PKI user certificate data.
Detailed instructions for installing the IBM Directory Server software can be found in the product documentation contained in the ldap.html.en_US.config fileset. After installing the ldap.html.en_US.config fileset, the documentation can be viewed using a Web browser at the following URL: file:/usr/ldap/web/C/getting_started.htm.
The LDAP Server installation procedure is as follows:
The filesets installed include the following:
The DB2 package, db2_07_01.jdbc, must also be installed. The DB2 package, db2_07_01.jdbc, is located on the Expansion Pack CD. Use the installation procedure listed above to install the db2_07_01.jdbc package.
After the LDAP and DB2 filesets have been installed, the LDAP server must be configured. Even though the configuration can be done through the command line and file editing, for ease of administration and configuration, the LDAP web administrator is recommended. This tool requires a web server.
The Apache web server application is located on the AIX Toolbox for LINUX Applications CD. Use either the SMIT interface or the geninstall command to install the Apache web server. Other web servers can also be used, see the LDAP documentation for details.
Detailed instructions for configuring LDAP can be found in the product HTML documentation. Below is a concise description of the configuration steps:
# ldapcfg -u cn=admin -p secret
The DN and password will be required later when configuring each client. Specifically, the DN and password will be used as the ldappkiadmin and ldappkiadmpwd attributes of an ldap stanza in the acct.cfg file.
# ldapcfg -s apache -f /etc/apache/httpd.conf
# /usr/local/bin/apachectl restart
Certificate authentication service requires two separate LDAP directory information trees. One tree is used by the CA for publishing certificates and CRLs. The other tree is used by each client for storing and retrieving per-user PKI data. The following steps configure the LDAP directory information tree used for storing and retrieving per-user PKI data.
To add the suffix configuration entry using the Web administrator, do the following:
To add the suffix configuration entry by editing the LDAP server configuration file, do the following:
ibm-slapdSuffix: cn=localhostThis is the default system suffix.
ibm-slapdSuffix: cn=aixdata
dn: cn=aixdata objectclass: top objectclass: container cn: aixdata dn: ou=pkidata,cn=aixdata objectclass: organizationalUnit ou: cert userPassword: <<password>>Edit the pkiconfig.ldif file and replace the <<password>> character string after the userPassword attribute with your password for the PKI data administrator.
The DN and userPassword values will be required later when configuring each client. Specifically, the DN (ou=pkidata,cn=aixdata) and value for password will be used as the ldappkiadmin and ldappkiadmpwd attributes of an ldap stanza in the acct.cfg file.
The second part of the file changes the ownership and adds the ACL for the PKI data as follows:
dn: ou=pkidata,cn=aixdata changetype: modify add: entryOwner entryOwner: access-id:ou=pkidata,cn=aixdata ownerPropagate: true dn: ou=pkidata,cn=aixdata changetype: modify add: aclEntry aclEntry: group:cn=anybody:normal:grant:rsc:normal:deny:w aclEntry: group:cn=anybody:sensitive:grant:rsc:sensitive:deny:w aclEntry: group:cn=anybody:critical:grant:rsc:critical:deny:w aclEntry: group:cn=anybody:object:deny:ad aclPropagate: true
# ldapadd -c -D cn=admin -w secret -f pkiconfig.ldif
To install and configure the certificate authentication service, do the following:
Configure certificate authentication service server to work with LDAP, by performing the following steps:
# ldapcfg -l /home/ldapdb2 -u "cn=admin" -p secret -s apache \ -f /usr/local/apache/conf/httpd.conf
It is assumed that the Web Server is the Apache Web Server in the above configuration command.
ibm-slapdSuffix: o=aix,c=us
You can specify a different distinguished name instead of o=aix,c=us.
# /usr/bin/slapd -f /etc/slapd32.conf
# ldapmodify -D cn=admin -w secret -f setup.ldifwhere setup.ldif contains the following:
dn: cn=schema changetype: modify add: objectClasses objectClasses: ( 2.5.6.21 NAME 'pkiuser' DESC 'auxiliary class for non-CA certificate owners' SUP top AUXILIARY MAY userCertificate ) dn: cn=schema changetype: modify add: objectClasses objectClasses: ( 2.5.6.22 NAME 'pkiCA' DESC 'class for Cartification Authorities' SUP top AUXILIARY MAY ( authorityRevocationList $ caCertificate $ certificateRevocationList $ crossCertificatePair ) ) dn:cn=schema changetype: modify replace: attributetypes attributetypes: ( 2.5.4.39 NAME ( 'certificateRevocationList' 'certificateRevocationList;binary' ) DESC ' ' SYNTAX 1.3.6.1.4.1.1466.115.121.1.5 SINGLE-VALUE ) replace:ibmattributetypes ibmattributetypes:( 2.5.4.39 DBNAME ( 'certRevocationLst' 'certRevocationLst' ) ACCESS-CLASS NORMAL)
# ldapadd -D cn=admin -w secret -f addentries.ldifwhere addentries.ldif contains the following:
dn: o=aix,c=us changetype: add objectclass: organization objectclass: top objectclass: pkiCA o: aix
Create the certificate authority as follows:
12345678 password1234 87654321 password4321
where 12345678 and 87654321 are reference numbers, and password1234 and password4321 are their respective passwords. Blank lines are not allowed. Space characters should not precede or follow reference numbers or passwords. At least one reference number and password must exist in the file. An example file can be found in /usr/cas/server/iafile. You will need to reference these values each time you set up a client.
# mksecpki -u pkiuser -f /usr/cas/server/iafile -p 1077 -H ldap.cert.mydomain.com \ -D cn=admin -w secret -i o=aix,c=us
Information on the mksecpki flags follows:
The mksecpki command automatically generates the trusted signing key with a key label of TrustedKey, the password of the CA user account, and places it in the /usr/lib/security/pki/trusted.pkcs12 keystore file. It's not necessary to perform the steps in Create the Trusted Signing Key unless you need to generate multiple keys or want a trusted signing key with a different key label and/or password.
The mksecpki command automatically generates a trusted signing key with a key label of TrustedKey, the password of the CA user account, and places it in the /usr/lib/security/pki/trusted.pkcs12 keystore file. If you need to generate a new trusted signing key or multiple trusted signing keys, then this section provides the steps needed to generate a trusted signing key.
All certificate authentication service clients where certificate creation and revocation are allowed require a trusted signing key for signing the user's authentication certificate. The key is saved in a separate keystore and is made available to all systems where certificates can be created. A single key can be used by all systems or, for a more secure approach, multiple keys can be created and distributed.
To create a trusted key, use the /usr/java131/bin/keytool command. Use a file name of a non-existing file. The keytool command prompts for a keystore password and key password. Both the keystore password and key password must be identical for certificate authentication service to access the key in the keystore. Run the keytool command as follows:
keytool -genkey -dname `cn=trusted key' -alias `TrustedKey' -keyalg RSA \ -keystore filename.pkcs12 -storetype pkcs12ks
In this example, the trusted key label is TrustedKey and the trusted keystore password is user-supplied. Remember these values, because you will need them when configuring the certificate authentication service clients. When configuring a certificate authentication service client, the keylabel and keypasswd attributes in the acct.cfg file will need to be set to the trusted key label and trusted keystore password, respectively.
For security reasons, make sure the keystore file (filename.pkcs12) is read and write protected. Only the root user should have access to this file. The trusted key should be the only object in the keystore.
There are many configuration options on the client side of certificate authentication service. The following sections provide the configuration procedure required for each system participating in PKI authentication.
Copy the trusted keystore containing the trusted signing key to the local system. For information on creating the trusted signing key, see Create the Trusted Signing Key. The default location for the trusted keystore is in the /usr/lib/security/pki directory.
For security reasons, make sure the keystore file is read and write protected. Only the root user should have access to this file.
Remove any ldap stanzas that may exist in the /usr/lib/security/pki/acct.cfg file using a text-based editor like the vi command.
Minimally, the local CA account must be configured. By default, the local CA account exists, but must be modified to match your environment.
Certificate authentication service supports the use of multiple CA's by a single system through stanza-based configuration files. The default CA stanza name of local is used when a CA is not specified by a user or by the software. All systems must have a valid local stanza definition in the appropriate certificate authentication service configuration files. Only one CA may have a stanza name of local. All other CA's must have a unique stanza name. CA stanza names cannot be ldap or default.
The following sections guide you through the SMIT configuration screens for configuring the local CA.
smitty pki
ldap://crlserver/o=XYZ,c=usThis field maps to the crl attribute in the /usr/lib/security/pki/ca.cfg file.
smitty pki
smitty pki
ldappkiadmin = "cn=admin"
ldappkiadmpwd = secret
ldapservers = ldapserver.mydomain.com
ldapsuffix = "ou=aix,cn=us"
Perform the same steps as in Add the CA LDAP Account, except use the values used in the Adding the PKI Suffix and ACL Database Entries step in Configuring the LDAP Server for PKI. Use the following values:
Press Enter to commit the changes.
smitty pki
The methods.cfg file specifies the definitions of the authentication grammar used by the registry and SYSTEM attributes. Specifically, this is where the authentication grammar for PKILDAP (for PKI using LDAP) and FPKI (files PKI) must be defined and added by the system administrator.
Below is a typical methods.cfg definition. The stanza names PKI, LDAP, and PKILDAP are arbitrary names and can be changed by the administrator. This section uses these stanza names throughout for consistency.
PKI: program = /usr/lib/security/PKI options = authonly LDAP: program = /usr/lib/security/LDAP PKILDAP: options = auth=PKI,db=LDAP
To support roaming users, use the same methods.cfg stanza names and attribute values across all systems that support roaming users.
To create a new PKI user account, use the mkuser command and the appropriate /usr/lib/security/methods.cfg stanza name (PKILDAP). Depending on the attribute settings in the /usr/lib/security/pki/policy.cfg file, the mkuser command can automatically create a certificate for the user. Below is a mkuser example that creates the user account bob:
mkuser -R PKILDAP SYSTEM="PKILDAP" registry=PKILDAP bob
There are a couple of different approaches for converting a non-PKI user account into a PKI user account. The first approach allows the system administrator access to the user's private keystore initially, which may or may not be acceptable in a given environment, but is the quickest way to convert a user. The second way requires interaction between the user and system administrator, which may take more time to setup.
Both examples use the following assumptions:
Example 1:
With root authority, the system administrator can perform the following commands for user account bob:
certcreate -f cert1.der -l auth_lbl1 cn=bob bob # Create & save cert in cert1.der. certadd -f cert1.der -l auth_lbl1 auth_tag1 bob # Add cert to LDAP as auth_tag1. certverify auth_tag1 bob # Verify & sign the cert in LDAP. chuser SYSTEM="PKILDAP" registry=PKILDAP bob # Change account type to PKILDAP. chuser -R PKILDAP auth_cert=auth_tag1 bob # Set the user's auth certificate.
Then, have user bob change his password on the keystore using the keypasswd command.
Example 2:
Have user bob execute the first 3 commands of example 1 above (certcreate, certadd, certverify), creating his own certificate and keystore. Then have the system administrator perform the last two chuser commands of example 1 above.
If a PKI user requires a new authentication certificate, the user can create a new certificate and have the system administrator make it the user's authentication certificate. Below is an example of user bob creating a certificate and the system administrator making the certificate the authentication certificate.
# Logged in as user account bob: certcreate -f cert1.der -l auth_lbl1 cn=bob # Create & save cert in cert1.der. certadd -f cert1.der -l auth_lbl1 auth_tag1 # Add cert to LDAP as auth_tag1. certverify auth_tag1 # Verify & sign the cert in LDAP. # As the system adminstrator: chuser -R PKILDAP auth_cert=auth_tag1 bob # Set the user's auth certificate.
Edit the passwd attribute value of the newuser stanza in the /usr/lib/security/pki/policy.cfg file to modify the password used to create the keystores of new PKI users.
The file that contains the trusted signing key needs to be replaced and the user authentication certificates need to be re-signed.
If a user's private key is compromised, the user or the administrator should revoke the certificate using the appropriate reason code, other users that use the public key should be notified of the compromise and, depending on the purpose of the private/public key, a new certificate should be issued. If the certificate was used as the user's authentication certificate, then another certificate (either the new certificate or an existing non-promised certificate owned by the user) should be added as the new authentication certificate.
Change the password on the keystore. Revoke all the user's certificates. Create new certificates for the user including a new authentication certificate. The compromised private keys may still be useful to the user for accessing previously encrypted data.
If a user's private key is compromised, the user or the administrator should revoke the certificate using the appropriate reason code, other users that use the public key should be notified of the compromise and, depending on the purpose of the private and public key, a new certificate should be issued. If the certificate was used as the user's authentication certificate, then another certificate (either the new certificate or an existing non-promised certificate owned by the user) should be added as the new authentication certificate.
Every user certificate maintained in LDAP contains the keystore location of its matching private key. To move a user's keystore from one directory to another or to change the name of the keystore, requires changing the LDAP keystore location and name associated with the user's certificates. If the user uses multiple keystores, then extra care must be taken to change only the LDAP information of the certificates affected by the keystore change.
To move a keystore from /var/pki/security/keys/user1.p12 to /var/pki/security1/keys/user1.p12:
# As root... cp /var/pki/security/keys/user1.p12 /var/pki/security1/keys/user1.p12 # Retrieve a list of all the certificates associated with the user. certlist ALL user1 # For each certificate associated with the keystore, do the following: # A) Retrieve the certificate's private key label and its "verified" status. # B) Retrieve the certificate from LDAP. # C) Replace the certificate in LDAP using the same private key label, # but the new keystore path name. # D) If the certificate was previously verified, it must verified again. # (Step D requires the password to the keystore.) # Example modifying one certificate. # Assume: # username: user1 # cert tag: tag1 # key label: label1 # Retrieve the certificate's private key label. certlist -a label tag1 user1 # Retrieve the certificate from LDAP and place it in file cert.der. certget -f cert.der tag1 user1 # Replace the certificate in LDAP. certadd -r -f cert.der -p /var/pki/security1/keys/user1.p12 -l label1 tag1 user1 # Re-verify the certificate if it was previously verified. # (Need to know the keystore password.) certverify tag1 user1