z/OS - Group home

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

  

With more and more modern open source technol­­ogy used in business, our Mainframe customers express the desire to authenticate those external applications through z/OS RACF.

Today, I will introduce a method of using certificate bind to RACF ID through LDAP protocol under SSL/TLS communication.

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

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

 

I will introduce the basic knowledge of Certificate, SSL, access LDAP using SSL/TLS in Part1. If you are familiar with this part of content, you can ignore it and jump to Part 2 directly.

 

1. Overview of digital certificates

1.1 Public and private keys

1.2 Certificate data structure

1.3 Certificate hierarchies

2. Overview of SSL/TLS

2.1 The secure handshake

2.2 Access LDAP using SSL/TLS

 

1. Overview of digital certificates

In a client-server network environment, entities identify themselves with digital certificates using a public key protocol, such as Secure Sockets Layer (SSL). Public key protocols are based on asymmetric encryption, in which mathematical properties are used to produce an encryption key pair, a value formed by pairing a public key with a related private key. The public key, as implied by its name, is public information that can be disseminated freely. The private key, on the other hand, is private and should never be revealed to anyone other than the owner of the key pair.

 

1.1 Public and private keys

 

A public key and a related private key are numerically associated with each other. Therefore, any data encrypted using one of the key values can only be decrypted using the other key value. Network protocols take advantage of this in the following ways:

  • Data can be securely sent from one party to another if the sending party knows the public key of the receiving party. The sender encrypts the data with the public key before sending. Upon receipt, the receiving party recovers the data by decrypting it with the private key. Because the intended recipient is the only party that possesses the private key, only the intended recipient can recover the data.
  • One party can digitally sign data by encrypting a copy of the data using her own private key. If the signer's public key is known, the signature can be verified by decrypting the signed data using the signer's public key. If the recovered data matches the expected value (the original data), then it is the data signed by the original party, not forged by another, because only the original party has the matching private key.

In practical terms, symmetric encryption algorithms, such as Data Encryption Standard (DES), perform much faster than asymmetric encryption algorithms. Therefore, public key protocols use a combination of symmetric and asymmetric encryption. For example, in SSL, the message data is symmetrically encrypted only after asymmetric encryption is used to exchange the symmetric encryption key. Also, to reduce the size of the message transmitted, the data to be digitally signed is compressed using a one-way hashing function before being encrypted with the signer's private key. The signature verifier then performs the same hashing function on the recovered data before comparing the signature.

  1.  

1.2 Certificate data structure

Public keys can be freely disseminated. In fact, the success of the various public key protocols requires a systematic and trustworthy way of distributing public keys and securely storing their associated private keys. The X.509 digital certificate is the packaging that enables the distribution of a single public key. The X.509 standard is the subsection of the International Telecommunication Union (ITU) X.500 directory standard that defines certificates.

The X.509 digital certificate is a data structure that contains, at minimum, the following fields:

  • The distinguished name of the owner of the public key, also called the subject's name
  • The distinguished name of the issuer of the certificate, also called the issuer's name
  • The public key itself
  • The time period during which the certificate is valid, also called the validity period
  • The certificate's serial number as designated by the issuer
  • The issuer's digital signature

In addition to these required fields, an X.509 certificate might contain one or more extensions that hold information about how the key is to be used or how the certificate authority conducts its business.

In its simplest form, a digital certificate is a binding between a named entity (a person or device) and a public key. It is a declaration that, for example, party A owns public key 123. Digital certificates can be issued by certificate authorities or they can be self-issued. Certificate authorities (CAs) are often well-known commercial organizations or they can be local or internal organizations. When a certificate authority uses its private key to sign and issue a certificate, it makes the declaration that binds the entity (subject) to its public key. When an organization issues its own certificate with itself as subject and issuer, signing with its own private key, the certificate is a called a self-signed certificate.

  1.  

1.3 Certificate hierarchies

Certificate authorities digitally sign the certificates they issue using their own private key. Thus, another party can verify the information in a certificate, including its extensions, by validating the signature on the certificate with the certificate authority's own public key. The other party gets the certificate authority's public key from a certificate issued to the certificate authority and does a signature check that might involve the public key from yet another certificate. The chain of verification can be quite long, depending on the certificate hierarchy. Figure 1 is an example of a simple certificate hierarchy.

 

image

Figure 1 is a representation of a certificate hierarchy containing four entities where the end-entity certificate is issued by subordinate certificate authority (CA #2). The certificate of CA #2 is issued by subordinate certificate authority (CA #1). The certificate of CA #1 is issued by the root certificate authority. The certificate of the root certificate authority is self-issued, meaning that its certificate is signed by its own private key (a self-signed certificate).

The chain of signature verification begins with the end-entity certificate. The public key of CA #2 is used to verify the signature of the end-entity certificate. If the signature is valid, the public key of CA #1 is used to verify the signature of the CA #2 certificate. If the signature is valid, the public key of the root certificate is used to verify the signature of the CA #1 certificate. Finally, the signature of the root certificate is verified using its own public key.

Signature verification for the self-signed root certificate simply provides assurance that the root certificate is unaltered. It does not guarantee that the information in the certificate, or the certificate authority itself, is trustworthy because anyone can create a self-signed certificate and claim to be a certificate authority. You must establish trust in your own selected set of certificate authorities and individual certificates before using public key protocols.

Your selected set of trusted certificates or CAs might be referred to using various terms, such as your trusted roots, trusted signers, or, simply, your trust policy. RACF supports your trust policies through RACF key rings.

2. Overview of SSL/TLS

2.1 The secure handshake

A network protocol where a z/OS® application is playing the role of the client or the server is shown in Figure 2. Each party, both client and server, has its own certificate, a matching private key, and a list of trusted certificate-authority certificates. When the client needs to authenticate itself to the server to be able to perform a transaction, both the server and client need to verify one another. The protocol for a secure handshake for mutual verification begins with the parties exchanging certificates. Each party then separately validates the other's certificate to make sure that its signature is valid, that the subject name in the certificate is correct, and that the certificate originated from a trusted certificate authority. If successful, each party must prove to the other that it owns the private key that matches its public key certificate. This step establishes proof of possession and can be accomplished by having each party sign a known unique value, such as a hash of the message traffic between the two parties. If each signature can be validated using the associated public key, the proofs are successful. The final step in this handshake is for one of the parties to generate a random symmetric key, encrypt it using the other party's public key, and send it to the other party. This random symmetric key can then be used to encrypt the data for the remainder of the session. Once the secure handshake is complete, secure transactions can be safely handled in the z/OS environment between this client and server.

 

image
 

Figure 2. A high-level view of a secure z/OS handshake using a public key network protocol

  1.  

2.2 access LDAP using SSL/TLS

 

Creating and using key databases, key rings, or PKCS #11 tokens

The LDAP client and server use the System SSL functions provided in z/OS to set up SSL/TLS protected communications. The System SSL capability requires a key database, RACF key ring, or PKCS #11 token to be set up before SSL/TLS protected communications can begin.

The key database is a password protected file stored in the file system. This file is created and managed using a utility program provided with System SSL called gskkyman. See z/OS Cryptographic Services System SSL Programming for more information about the gskkyman utility. The key database file that is created must be accessible by the LDAP server.

The key ring is maintained by RACF. This object is created and managed using the RACF Digital Certificate command, RACDCERT. Directions for using the RACDCERT command can be found in z/OS Security Server RACF Command Language Reference.

The user ID under which the LDAP server runs must be authorized by RACF to use RACF key rings. To authorize the LDAP server, you can use the RACF commands in the following example:

RDEFINE RDATALIB <ringowner>.<ringname>.LST UACC(NONE)

PERMIT <ringowner>.<ringname>.LST CLASS(RDATALIB) ID(<RACF ID>) ACCESS(READ)

Remember to refresh RACF after doing the authorizations.

SETROPTS RACLIST(RDATALIB) REFRESH

OR

RDEFINE FACILITY IRR.DIGTCERT.LISTRING UACC(NONE)

PERMIT IRR.DIGTCERT.LISTRING CLASS(FACILITY) ID(<RACF ID>) ACCESS(READ)

SETROPTS RACLIST(FACILITY) REFRESH

 

In this example, I will use SUIMGUC as the ‘<RACF ID>’ and <ringowner>.  

In order to practice the two ways to create certificate, I will use gskkyman utility to create a client certificate and use RACDCERT command to create the key ring and a server certificate.

 

Using gskkyman utility to create a client certificate:

 

image
 

 

If you already have a key database, you can enter 2 and input the path of the database and input the correct password. In this example we will create a new database called ssl_client.kdb.

 

image
 

 

After inputted the database name, password and other parameters default, I create a new one.

 

image
 

 

 

And I created a new certificate with label name ssl_client. The certificate information showed as follow:

 

image
 

 

Using RACDCERT command to create a server certificate:

First I created a server certificate with label name of ssl_server.

 

RACDCERT GENCERT SITE

  SUBJECTSDN(CN('ssl test')) WITHLABEL('ssl_server')

  KEYUSAGE(HANDSHAKE DATAENCRYPT DOCSIGN CERTSIGN)

SETROPTS RACLIST(DIGTCERT) REFRESH

 

If without error message, the certificate would be created. You can use this command to check if it is created:

RACDCERT LIST(LABEL('ssl_server')) SITE

 

Then I created a key ring:

RACDCERT ID(SUIMGUC) ADDRING(LDAP_External_SSL_Keyring)

If without error message, the key ring would be created. You can use this command to check if it is created:

RACDCERT LISTRING(LDAP_External_SSL_Keyring)

Then I needed to add the server certificate to the key ring:

RACDCERT CONNECT(SITE LABEL('ssl_server')

  RING(LDAP_External_SSL_Keyring) USAGE(PERSONAL))

  ID(SUIMGUC)

SETROPTS RACLIST(DIGTCERT, DIGTRING) REFRESH

 

image
 

 

Please pay attention to the keyword USAGE: it specifies how this certificate is used within the specified ring. It has three optional values: PERSONAL | SITE | CERTAUTH

If no usage is specified, it defaults to the usage of the certificate being connected.

The USAGE keyword allows the altering of the trust policy within the confines of a specific key ring. For example, if you are operating your own certificate authority, your certificate server application would have its own certificate. Because the certificate does represent a certificate authority, it should be installed under CERTAUTH, thus setting its default usage for all other applications and users. However, your certificate server application would need to use the certificate's private key for signing. The default usage of CERTAUTH does not allow this. So, for the certificate server application's key ring only, the certificate should be connected with USAGE(PERSONAL).

You can confirm whether the certificate is added to the key ring:

RACDCERT ID(SUIMGUC) LISTRING(LDAP_External_SSL_Keyring)

In order to establish bi-directional SSL communication, I needed to import the client certificate (only with public key) to the server’s key ring and import the server certificate (only with public key) to the client’s key database:

 

Import the client certificate (only with public key) to the server’s key ring:

I used gskkyman to export the client certificate to a file named ssl_client.cert.

 

image
 

 

Then I copied this file to a z/OS dataset:

cp ssl_client.cert  "//'SUIMGUC.PRIVATE.SSLCLT'"

 

In your own environment, if you create the client certificate in other platform, you may use FTP to send the exported file to server(z/OS).

Then I imported it with the label name of ssl_client:

RACDCERT  SITE

  ADD('SUIMGUC.PRIVATE.SSLCLT')

  WITHLABEL('ssl_client') trust

SETROPTS RACLIST(DIGTCERT) REFRESH

 

Then I added it to the server key ring:

RACDCERT CONNECT(SITE LABEL('ssl_client')

  RING(LDAP_External_SSL_Keyring) USAGE(PERSONAL))

  ID(SUIMGUC)

SETROPTS RACLIST(DIGTCERT, DIGTRING) REFRESH

 

image
 

Import the server certificate (only with public key) to the client key database:

Similarly, I exported the server certificate to a dataset.

 

RACDCERT EXPORT( LABEL('ssl_server')) SITE

   DSN('SUIMGUC.PRIVATE.SSLSRV')

 

Then I copied this file to a the USS directory:

cp "//'SUIMGUC.PRIVATE.SSLSRV'"  ./ssl_server.cert

 

Then I imported it into the client key database by gskkyman utility:

 

image
 

Now all the Pre-conditions are ready for SSL communication.

I would use the following configuration for my LDAP server that would use SSL in request operation:

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 ssl_server

sslCipherSpecs ANY

sslKeyRingFile LDAP_External_SSL_Keyring

sslMapCertificate check fail

 

database SDBM GLDBSD31/GLDBSD64 sdbm

suffix "cn=sdbm"

enableResources on

 

From this configuration you can see that, My LDAP server would use server and client authentication. This means the client sends a certificate on the initial SSL handshake, it must be validated by the LDAP server before the secure encrypted communication channel is established between them.

So, when I use the ldapsearch utility to search something that I need to give the client certificate:

 

ldapsearch -h xxx -p 2305 -Z -K /home/suimguc/cert-stores/ssl_client.kdb -P ibm -N ssl_client -D c=cn -w password  -b cn=schema -s base "objectclass=*"

ps: xxx is you ldap server IP or host name.

Then I gotten the expired search result. The SSL commutation succeed. This only meant that all the data would be sent in a secure way. Next section I will introduce the how to certificate bind in LDAP.

 

image
 

If you have any error message related to SSL, please refer to z/OS Cryptographic Services System SSL Programming SSL function return codes for help,  such as: 428 Key entry does not contain a private key.  This may indicate that The key entry does not contain a private key or the private key is not usable.

This error can also occur if the private key is stored in ICSF and ICSF services are not available, if using a SAF key ring that is owned by another user, if the private key size is greater than the supported configuration limit or the application is executing in FIPS mode. Certificates that are meant to represent a server or client must be connected to a SAF key ring with a USAGE value of PERSONAL and either be owned by the user ID of the application or be SITE certificates. This error can occur when using z/OS PKCS #11 tokens if the user ID of the application does not have appropriate access to the CRYPTOZ class. This error can occur when using private keys associated with user certificates in a SAF key ring that is owned by another user if the user ID of the application does not have appropriate access to the ringOwner.ringName.LST resource in the RDATALIB class.