z/OS - Group home

This topic would be introduced by two parts:

Part 1 access LDAP using SSL/TLS

Part 2 Certificate bind to RACF ID through LDAP SSL/TLS in two ways

In Part 1, I have introduced the basic knowledge of Certificate, SSL, access LDAP using SSL/TLS.

In this part, I will introduce the three way of Certificate bind to RACF ID and how to access through LDAP SSL/TLS.

This will benefit anyone who wants to get authentication from other platform to z/OS in a flexible way with security assurance.

I will introduce the method in following sections. there are specific examples within them:

1. Support of certificate bind in LDAP

2. Certificate bind to RACF ID

2.1 One-to-one certificate to user ID association

2.2 Certificate name filtering

1. Support of certificate bind in LDAP

The SASL bind mechanism of EXTERNAL is supported by the LDAP server. This means that the authentication on the bind is performed using the data obtained during the SSL/TLS client authentication that was performed on the SSL/TLS handshake with the client.

To use SASL EXTERNAL bind, the following steps must occur:

• The LDAP server must be configured and started with sslAuth set to serverClientAuth so that the server can authenticate the client.

• The client connects to the LDAP server and performs the SSL/TLS handshake. The handshake sends the client certificate to the LDAP server.

• The client performs a SASL bind with the mechanism of EXTERNAL.

At this point, the LDAP server considers the bind DN of the client for authorization purposes to be the clients DN as transmitted in the client certificate on the handshake. The name specified in the BIND request must match the subject name in the client certificate or must be null.

The RACF RACDCERT command is used to associate a certificate with a RACF user ID. If check, add, or replace is specified on the sslMapCertificate configuration option, the LDAP server determines if the client certificate used during an EXTERNAL bind is associated with a RACF user ID, therefore, adds that RACF user ID to the bind information kept for this client.

After an EXTERNAL bind, the client can access LDBM, CDBM, TDBM, and GDBM backends based on the bind DN and the groups it belongs to. If the sslMapCertificate option is set to keep the associated RACF user ID in the bind information, the client can perform SDBM operations to access RACF data, under the context of the RACF user ID.

2. Certificate bind to RACF ID

Without digital certificates, RACF® users of traditional client/server applications authenticate themselves to servers by presenting their user IDs and passwords. Successful authentication adds a security context, a control block called the accessor environment element (ACEE), to the user's address space. Subsequently, units of work initiated by the client are tagged with the client's identity, or security context. In this environment, the client's user ID and password provide identification and authentication.

In the z/OS® digital certificate environment, the secure handshake protocol accomplishes identification and authentication when the client presents its certificate as identification and its proof-of-possession as authentication. The client's ACEE is created when the application invokes the SAF callable service called initACEE (IRRSIA00) to determine the client's user ID based on information in the client's certificate.

2.1 One-to-one certificate to user ID association

Whenever you generate a certificate using the RACDCERT GENCERT command, RACF registers it to a user ID and adds it to the RACF database. You can also store a previously generated certificate and register it to a user ID using the RACDCERT ADD command. These methods establish a direct one-to-one association, or mapping, between each certificate and one specific user ID. You can create direct mappings for each of your users by simply adding individual certificates for each user to the RACF database. However, the administrative cost of this approach might only be feasible for you when handling a limited number of certificates.

Registered certificates are stored in certificate profiles. These profiles contain an exact copy of the certificate and, for user IDs on this system, the private key, if it exists. Certificates stored in this way can be used to simply associate a certificate with a user ID or they can be gathered into a collection, or key ring, for use by other applications as part of a secure network protocol. For details, see Using the RACDCERT command to administer certificates and RACF and key rings.

Examples1: associate with RACF user ID using a new generated certificate.

Create a certificate associated to RACF User ID and connect it to the RACF key ring.

In this example, I will user the RACF ID SUIMGUC with TSO information. If you need to create a new RACF ID. For details, see ADDUSER command.

You can get a certificate in these ways:

1. Use the RACDCERT GENCERT command
2. Use the gskkyman utility
3. Create it from any other platform and transfer to z/OS with binary format.

For using RACDCERT GENCERT command:

RACDCERT GENCERT ID(SUIMGUC)

  KEYUSAGE(HANDSHAKE DATAENCRYPT DOCSIGN CERTSIGN)

  WITHLABEL('One-to-One')

SETROPTS RACLIST(DIGTCERT) REFRESH

For the parameter ID(SUIMGUC)means that the new certificate is a user certificate associated with the user ID SUIMGUC, for detail. See RACDCERT GENCERT command.

You can view the certificate information by issue this command:

RACDCERT ID(SUIMGUC) LIST(LABEL(''One-to-One'))

Now I already associated a certificate to the RACF user ID. I need to connect it into a RACF key ring, if you don’t have one, you need to create it first. I created a new key ring:

RACDCERT ID(SUIMGUC) ADDRING(LDAP_one_one_RACF_associated)

SETROPTS RACLIST(DIGTRING) REFRESH

Then connect the certificate to the key ring:
RACDCERT CONNECT(LABEL('One-to-One') RING(LDAP_one_one_RACF_associated)) ID(SUIMGUC)

To verify that result, we can use the command:

RACDCERT ID(SUIMGUC) LISTSTRING(LDAP_one_one_RACF_associated)

This certificate would be used as the client side when using LDAP SSL communication.

If you want to use gskkyman utility to create the certificate, you can see Part 1 for detail steps. After that, you need to use RACDCERT ADD command to associated to the RACF ID.

Similarly, you could create the server certificate. Because the server certificate wouldn’t used for user ID bind, we can use the server certificate label named ssl_server created in Certificate bind to RACF ID through LDAP SSL/TLS in three ways Part 1. The only action is to add it to the client key ring.

RACDCERT CONNECT(SITE LABEL('ssl_server')

  RING(LDAP_one_one_RACF_associated) USAGE(PERSONAL))

  ID(SUIMGUC)

SETROPTS RACLIST(DIGTCERT, DIGTRING) REFRESH

Establish the LDAP SSL communication:

In order to use certificate bind in LDAP to associate to RACF user ID, the bi-directional SSL configuration is need. It means sslAuth set to serverClientAuth so that the server can authenticate the client. So we need to add the certificate labeled One-to-One as client certificate(only with public key) in to the key string which the LADP server stored in, and also need to add the LDAP server’s certificate in to the client’s key ring. We use RACDCERT CONNECT command to add a digital certificate to a key ring.

Add client’s certificate to server’s key ring:

RACDCERT CONNECT(LABEL('One-to-One') RING(LDAP_External_SSL_Keyring)) ID(SUIMGUC)

SETROPTS RACLIST(DIGTCERT, DIGTRING) REFRESH

We will use the similar LDAP server configuration as in Certificate bind to RACF ID through LDAP SSL/TLS in three ways Part 1:

adminDN C=CN

adminPW password

listen ldaps://:2305

listen ldap://:pc

allowAnonymousBinds off

schemaPath /home/ldap/lib/schema

serverCompatLevel 7

srvStartUpError ignore

sslAuth serverClientAuth

sslCertificate server

sslCipherSpecs ANY

sslKeyRingFile LDAP_External_SSL_Keyring

sslMapCertificate check fail

database SDBM GLDBSD31/GLDBSD64 sdbm

suffix "cn=sdbm"

enableResources on

Started the LDAP server, we need to use the EXTERNAL bind in search command:

ldapsearch -h xxxxx -p 2305 -Z -K LDAP_one_one_RACF_associated -N 'One-to-One' -S EXTERNAL -s sub -b "profiletype=user,cn=sdbm" "objectclass=*"

The search result should be like this:

We can verify the final bind user ID from LDAP debug trace:

From the trace, we can see the safUserID is SUIMGUC, the bind DN is CN=TEST, is just the same as the certificate we created. So the One-to-one certificate to user ID association has succeed.

2.2 Certificate name filtering(coming soon)

As more and more users access your system from the Web, you face an increasing administrative burden to securely manage their digital certificates. Certificate name filtering is a method for administering large numbers of user certificates, without storing each certificate in the RACF® database. Certificates managed using certificate name filtering:

• Require no individual administration to be registered or to be replaced when they expire.
• Occupy very little space in the RACF database.
• Can be used to allow several users to share the same user ID in a secure manner.
• Can be selectively mapped to different user IDs based on system and application criteria.
• Are logged on use with audit records that include the associated user ID and the certificate's full subject's and issuer's name.

Certificate name filters are used to determine the operational user ID when RACF is called to create a security context for a client login using a certificate, such as during SSL client authentication. Certificate name filters cannot be used in protocols where the client certificate or the client private key is required. Therefore, certificate name filters are ideally suited for use with SSL client authentication which requires that only the client's root certificate, not the client certificate, be stored in the RACF database.

Interpreting the X.500 directory information tree

When you use certificate name filtering, RACF provides the ability to allow several users to share the same user ID on your system based on the subject's distinguished name and the issuer's distinguished name as contained in X.509 certificates. The subject's distinguished names and issuer's distinguished names for three sample certificates are listed in Table 1 and are shown in the address form used by RACF:

Table 1. Subject's and issuer's distinguished names

The distinguished names contained in the certificates shown in Table 1 are represented in the X.500 directory information tree shown in Figure 3.

                                        |

                                       / \

                                      /   \

                                     /     \

                                    /       \

                      O=World Sales Corp    L=Internet

                                  /           \

                                 /            O=VeriSign, Inc.

                                /               \

                              OU=US             OU=VeriSign Class 1

                             /     \             Individual Subscriber

                            /       \

                           /         \

                OU=New York         OU=Los Angeles

                /         \                \

               /           \                \

           OU=Sales      OU=Admin        OU=Sales

             /               \                \

            /                 \                \

CN=Agneta Berglund        CN=Hiro Ogura      CN=Timo Kokkonen     

Figure 3. Example of an X.500 directory information tree

Now, let's look at the left branch of the tree in Figure 3 as representing a hierarchical organization, with each level of the tree, or node, representing a different level within an organization. For example, Agneta works in the Sales department in New York for the US division of the World Sales Corporation. If viewed as a hierarchy of user groups, each level of the tree might represent increased access authority, with each group consisting of the groups below it.

For example, as an employee of World Sales, Agneta might have access to the internal phone numbers of all World Sales employees. As a member of the US division, she might also have access to the US division internal Web site, in addition to the phone numbers of all employees. Being in New York might allow her to run sales reports for the New York office, as well as to access the Web site and employee phone numbers. Being in the Sales department might allow her to place customer orders, in addition to all other access authorities.

You can associate a user ID with each node in a directory information tree using certificate name filtering. Each user ID can represent a number of users, each of whom has one or more digital certificates. Therefore, you can administer several certificates and the access authorities for several users, through a single user ID. For each node that you associate with a user ID, you create a certificate name filter that contains partial or full distinguished names, depending on where the node falls in the hierarchy.

Creating certificate name filters

You create certificate name filters using the RACDCERT MAP command. Certificate name filters are used by RACF (specifically, the initACEE callable service) to analyze the subject's and issuer's distinguished names in a given certificate to determine the user ID to associate with it. You can create filters based on the full issuer's distinguished names in order to administer all certificates by a given issuer as a single user ID. You can also create filters based on portions of the subject's distinguished name, and a variety of filters based on certain combinations of partial and full distinguished names. See Types of certificate name filters.

Example: Creates a certificate name filter based on the subject's distinguished name.

In this example, we use the RACF ID SUIMGUC, then associate with a certificate name filter. Because the user ID is shared by all the user who’s certificate subject name are compliance with the filter.

Then use RACDCERT MAP command to associates the user ID SUIMGUC to any user presenting a certificate that subject name is compliance with the filter.

RACDCERT ID(SUIMGUC) MAP WITHLABEL('LDAP certify filter users') TRUST

  SDNFILTER('OU=LDAP')

SETROPTS RACLIST(DIGTNMAP) REFRESH

You can check the map rule with the RACDCERT LISTMAP command:

RACDCERT LISTMAP(LABEL('LDAP certify filter users')) ID(SUIMGUC)

Then I created normal certificate:

RACDCERT GENCERT SITE WITHLABEL('client with filter')

  SUBJECTSDN(CN('client cert 1') OU('LDAP'))

  KEYUSAGE(HANDSHAKE DATAENCRYPT DOCSIGN CERTSIGN)

SETROPTS RACLIST(DIGTCERT) REFRESH

The certificate subject’s name is:

CN('client cert 1') OU('LDAP')

This would be in the subject name filter’s scope.

Then I create a new key ring to store the certificate and also connected it to the key ring of LDAP_External_SSL_Keyring which the LDAP server certificate stored in.

RACDCERT ID(SUIMGUC) ADDRING(LDAP_certificate_filter_RACF_associated)

RACDCERT CONNECT(SITE LABEL('client with filter')

  RING(LDAP_certificate_filter_RACF_associated) USAGE(PERSONAL))

  ID(SUIMGUC)

RACDCERT CONNECT(SITE LABEL('client with filter')

 RING(LDAP_External_SSL_Keyring) USAGE(PERSONAL))

 ID(SUIMGUC)

SETROPTS RACLIST(DIGTCERT, DIGTRING) REFRESH

Remember to add the LDAP server certificate to the new key ring too.

RACDCERT CONNECT(SITE LABEL('ssl_server')

 RING(LDAP_certificate_filter_RACF_associated) USAGE(PERSONAL))

 ID(SUIMGUC)

SETROPTS RACLIST(DIGTRING) REFRESH

Now we have one certificate filter that can let all the certificates which subject name is in the scope of OU=LDAP to associate the RACF ID SUIMGUC.

I started the LDAP server to verify it. I used the same configuration in the first example.

Then I used the EXTERNAL bind in search command:

ldapsearch -h xxx -p 2305 -Z -K LDAP_certificate_filter_RACF_associated  -N 'client with filter' -S EXTERNAL -s base -b "profiletype=user,cn=sdbm" "objectclass=*"

The search result should be like this:

We can verify the final bind user ID from LDAP debug trace:

From the trace, we can see the safUserID is SUIMGUC, the bind DN is “CN=Client cert 1, OU=LDAP”, which is just the same as the certificate we created. This meant that  certificate filter to user ID association has succeed.