HP HP-UX Kerberos Data Security Product Guide

Download

Configuration Guide for Kerberos Client

Products on HP-UX

HP-UX 11.0, HP-UX 11i v1, HP-UX 11i v2, and HP-UX

11i v3

Manufacturing Part Number: 5991-7718

February 2007

Legal Notices



Confidential Computer Software. Valid license from HP required for possession, use or copying. Consistent wit h FAR 12.11 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commerc ial Ite m s are licen se d to the U.S. Govern m e nt under vendor’s standa rd commerc ial license.

The information contained herein is subject to change without notice. The only warranti es for HP products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein shall be construed as constituting an additional warranty. HP shall not be liable for technic al or edito r ial erro r s or omissions co ntained here in.

UNIX is a registered trademark of The Open Group.

OSF/Motif is a trademark of the Open Software Foundation, Inc. in the

U.S. and other countries.

MS-DOS and Microsoft are U.S. registered trademarks of Microsoft

Corporation.



California This software is based in part on the Fourth Berkeley Software

Distribution under lice nse f rom the Regents of the Univer sit y of California.



1. Overview

Kerberos Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Authentication Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Kerberos Products and GSS-API on HP-UX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

2. Introduction to the Kerberos Products and GSS-API

PAM Kerberos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

The PAM Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

The Authentication Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

The Password Module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Credential Cache. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

The Account Management Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

The Session Management Module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

The pam_user.conf File on HP-UX 11.0 and 11i v1. . . . . . . . . . . . . . . . . . . . . . . . . 47

The pam_user.conf File on HP-UX 11i v2 and HP-UX 11i v3. . . . . . . . . . . . . . . . . 47

The pam.c onf File on HP-UX 11.0 a nd HP-UX 11i v1 . . . . . . . . . . . . . . . . . . . . . . 47

The pam.conf File on HP-UX 11i v2 and HP-UX 11i v3 . . . . . . . . . . . . . . . . . . . . . 48

The pam_krb5 File on HP-UX 11.0 and HP-UX 11i v1. . . . . . . . . . . . . . . . . . . . . . 48

The pam_krb5 File on HP-U X 11i v2 and HP-UX 11i v3 . . . . . . . . . . . . . . . . . . . . 48

The pamkrbval Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Secure Internet Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

KRB5 Client Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Libraries and Header Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Kerberos Ut ilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

The kinit Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

The klist Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

The kdestroy Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

The kpasswd Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

The ktutil Utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

The kvno Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

HP Kerberos Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Kerberos Server Version 3.12 Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Graphical User Interface (GUI) Based Administration tool . . . . . . . . . . . . . . . . . . 65

Multithreaded Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

High Availability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Dynamic Propagation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

Scalability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

Contents

Windows 2000(R) Interoperability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

Choice of C-Tree or LDAP Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Auto-Configuration Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Gener ic S e curity S e rvice App licati on Progra m ming Interface (GSS -API) . . . . . . . . . . 68

Credential Management Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

Context Level Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

Authentication Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Confidentiality Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Support Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

3. Configuring the Kerberos Environment

Configuration Files for Kerberos Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

The services File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

Configuration Files for GSS-API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

The mech File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

The /etc/gss/qop File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

The gsscred.conf File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Configuring the Kerberos Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Configuring Your Microsoft Windows 2000 KDC . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Configuring the Kerberos Client. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

Configuring for PAM Kerberos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

4. Troubleshooting Kerberos Related Products

Troubleshooting PAM Kerberos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Troubleshooting the Kerberos C lient U tilities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

Troubleshooting GSS-API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Error Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Major and Minor Status Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Common GSS-API Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Calling Error Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

Other Common Causes of Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

Troubleshooting Using the pamkrbval Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

A. Sample pam.conf File

B. Sample krb5.conf File

C. Sample krb.conf File

D. Sample krb.realms File

E. Kerberos Error Messages

Kerberos V5 Library Error Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

Kerberos V5 Magic Numbers Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

ANSI.1 Error Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 32

GSSAPI Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

F. Kerberos Client Environment Variables

Kerberos Client Environment Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

Contents

Figures

Figure 1-1. Authentication Process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25

Figure 2-1. HP-UX authentication modules under PAM. . . . . . . . . . . . . . . . . . . . . . .34

Figure 2-2. PAM Kerberos calls libkrb5.sl through PAM . . . . . . . . . . . . . . . . . . . . . .35

Figure 2-3. SIS uses Kerberos Client Library Directly . . . . . . . . . . . . . . . . . . . . . . . .52

Figure 2-4. GSS-API Library. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .68

Figure 2-5. GSS-API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69

Figures

Tables

Table 1. Publishing History Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14

Table 2-1. PAM Kerberos Library libpam_krb5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35

Table 2-2. On HP-UX 11.0 and HP-UX 11i v1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37

Table 2-3. On HP-UX 11i v2 and HP-UX 11i v3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37

Table 2-4. On HP-UX 11.0 and 11iv1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38

Table 2-5. On HP-UX 11i v2 and HP-UX 11i v3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38

Table 2-6. Kerberos Client Libraries on HP-UX 11i v3 . . . . . . . . . . . . . . . . . . . . . . . .55

Table 2-7. Versions of Kerberos Server on HP-UX Operating Systems . . . . . . . . . . .64

Table 2-8. GSS-API Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70

Table 2-9. Additional files in the GSS-API product . . . . . . . . . . . . . . . . . . . . . . . . . . .70

Table 3-1. Kerberos Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .77

Table 3-2. Entries in the mech file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .82

Table 3-3. Format of the /etc/gss/qop file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84

Table 4-1. Error Codes and Corrective Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .91

Table 4-2. Kerberos Client Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .94

Table 4-3. Common GSS-API Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .96

Table 4-4. Calling Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .98

Table 4-5. Supplementary Bits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .98

Table 4-6. Error Messages that Appear During keytab Validation. . . . . . . . . . . . . .100

Tables

About This D ocument

This docum en t d es cr ibe s ho w to conf igure a Kerbe ros e nvironmen t on HP-UX servers and workstations running on HP-UX 11.0, HP-UX 11i v1, HP-UX 11i v2, and HP-UX servers running on HP-UX 11i v3.

This documen t is inte n d ed fo r sys te m man age r s or administrators who configure Kerberos related products on HP-UX. However, this document is not a replacement for the documents provided for HP’ s Kerberos Server ve rsion 3.12.

Publishing History

Table 1 describes the publishing details of this document for various HP-UX re l e ases.

Table 1 Publishing History Details

Document

Manufac turing P art

Number

J5849-90003 HP-UX 11.X December 2000 J5849-90007 HP-UX 11.X September 2001 T1417-90005 HP-UX 11.X June 2002 T1417-90006 HP-UX 11.X July 2003 5991-7718 HP-UX 11.X February 2007

The latest versio n of th is doc ume nt is available at: http://www.docs.hp.com.

The document printing date and part number indicate the document’s correct edition . The pr int ing d ate will ch ang e wh e n a new e ditio n is printed. Mino r change s m ay be made at rep rin t with o ut cha ngi ng the printing date. The doc um ent part numbe r will change when extens ive changes ar e mad e.

Document updates can be issued betwe e n ed itions to correct errors or document product changes. To ensure that you receive the updated or new edition, subs cr ibe to the app r opr iate sup p o rt servic e.

Operating

Systems

Supported

Publication Date

Contact your HP sales representative for details.

Document Organization

The Configuration Guide for Kerberos Related Products on HP-UX is organized as follow s:

Chapter 1 Chapter 1, Overview, – Provides an insight to the

Kerberos protocol.

Chapter 2 Chapter 2, Introduction to the Kerberos Products and

GSS-API, – Provides information about the different Kerberos products available on HP-UX.

Chapter 3 Chapter 3, Configuring the Kerberos Environment, –

Provides inst ructions for conf iguri ng a Kerberos environment.

Chapter 4 Chapter 4, Troub leshooting Kerber os Related Pr oducts ,

– Provides infor matio n to help you identi fy and troubleshoot some common pro blems th at might occur.

Appendix A Appendix A, Sample pam.conf File, – Provides a sample

pam.conf file.

Appendix B Appendix B, Sample krb5.con f File, – Provides a

sample krb5.conf file.

Appendix C Appendix C, Sample krb.conf File, – Provides a sampl e

krb.conf file.

Appendix D Appendix D, Sample krb.realms File, – Provides a

sample krb.realms file.

Appendix E Appendix E, Kerberos Error Message s, – Provides some

common Kerb er os e rr or mes sag es wit h thei r re spe cti ve error co d e s.

Appendix F Appendix F, Kerberos Client Environment Variables,--

Provides a l ist of common Kerberos Cl ient envir onment variables.

Typographic Conventions

This document uses the following typographic conventions: audit (5) An HP-UX manpage. In this example, audit is the

name and 5 is the section in the HP-UX Reference. On the Web and on the Instant Information CD, it may be

a link to the manpage itself. From the HP-UX comma nd line, yo u can enter “man audit” or “man 5

audit” to view the manpage. See man (1).

Book Title The title of a book. On the Web and on the Instant

Information CD, it may be a link to the book itself.

KeyCap The name of a keyboard key. Note that Return and Enter

both refer to the same key. Emphasis Text that is e mphasiz e d. Bold The defined use of an important word or phrase. ComputerOut Text displayed by the co mp uter. UserInput Comman d s and ot he r text that you type. Command A command name or qualified command phrase. Variable The na me of a variable th at you m ay replace in a

command o r func tio n o r information in a display th at

represents several possi ble valu es. | Separates item s in a list of choices. [] The contents are optional in formats and command

descriptions. If the contents are a list separated by |,

you can choose one of the items.

{} The contents are required in formats and command

descriptions. If the contents are a list separated by |,

you can choose one of the items. ... The preceding element may be repeated an arbitrary

number of times.

1 Overview

This chapter provides an overview of Kerberos and the available Kerberos products on HP-UX.

Chapter 1 21

Overview

It contains the following sections:

•“Kerberos Overview” on page 23

•“Authenticatio n Proces s” on page 24

•“Kerberos Products and GSS-API on HP-UX” on pa g e 28

Chapter 122

Overview

Kerberos Overview

Kerberos is a mature network authentication protocol based on the RFC 1510 specificatio n o f the IETF. It is designed to provide strong

auth enti ca t ion fo r client or s erver applications b y using t he sh a red secret-key cryptogra phy.

The basic currency of Kerberos is the ticket, which the user presents in order to use a specific ser vic e. Each service, be it a login se rv ice or an FTP service, requires a different kind of ticket. Fortunately, the Kerberized ap plications keep track of all the var ious ki nd s o f tickets, so you don’t have to.

You must authentic ate yourself to the server by p rovid in g yo u r use r name and password. In retu rn , the Kerberos server gives you an init ial ticket, whic h you use to request for additi onal tic kets from the Kerberos server for all the othe r serv ices. For this reason, the init ial tick e t is also often ca ll e d th e T i ck et Granti ng Ticket ( TGT).

Use the Kerberos protocol to secure the communication between the client and server. Thus, c lient programs make authentica tion requ ests to an authentication server, and server programs in turn service those client requests. Based on your user credentials, the server program grants or denies your request to access network applications and services . The Kerber os server allow s entities to authen ticat e themselves , without having to transmit their passwords in clear text form over the network.

Chapter 1 23

Overview

Authentication Process

Authentication Pro ce ss

The Kerberos server grants tickets to your user principal to access secured netwo r k ser vices. You m ust authentica te yourself to the serve r by providing your user name and password. When the server authenticates you, it returns a set of initial credentials for you, including a TGT and a session key.

The Kerberos serv er gra nts a ser vice t ic ket f or a spe cific servi ce prin cipal that can be associated with one or more Kerberos-secured services. A client application uses your service ticket to authenticate you to a Kerberos-secured network service. The secured client application automatically handles the transa ctions with t he Kerber os Serv er an d the secured applica tion server. Service ticke ts a nd asso cia te d s e ss ion keys are generally cached in your user credentials cache along with the TGT of the user.

Chapter 124

Figure 1-1 illustra te s the acti on s of th e compo nents and the Kerbe r os protocol in a secured environment.

Figure 1-1 Authentication Process

Overview

Authentication Process

The following is a des cr iptio n o f how a client and se rv er auth e ntic ate each other using Kerberos:

Step 1. Send a reque s t to th e AS fo r a TGT. You can choose to request spec if ic

ticket flags and spec if y the ke y ty pe to be us ed to co ns tru ct th e secre t key. You can also ac ce p t the default values configure d for t he client.

Send the following information to the Au the n tica tio n Se rv ice (A S) to obtain credentials :

• Client-indicates the user nam e, also refe rre d to as the prin cipal

name

• Server-indicates the TGS

Chapter 1 25

Overview

Authentication Process

• Time stamp

• Nonce

Step 2. If the AS decrypts the message successfully, it authenticates the

requesting user and issues a TGT. The TGT contains the user name, a session key fo r your use, and nam e of the se rv er to be used for a ny subsequent communication. The reply message is encrypted using your secret key.

NOTE The AS decrypts the request only when the pre-authentication option is

set in the AS reques t. If the pre- auth e ntic atio n option is not set, the AS issues the TGT if the principal is available in the Kerberos database.

Step 3. The clie nt de crypts the message using your sec ret k ey. The TGT and the

session key from the me ssage are stored in the client’s credent ia l cache. These credentials are used to obtain tickets for each network service the principal wan ts to acces s.

The Kerberos protocol exchange has the following important features:

• The authentic ation sc he m e does no t requ ire that the passwo r d be

sent across the network, either in encrypted form or in clear text.

• The client (or any other user) cannot view or modify the contents of

the TGT.

Step 4. To obtai n access to a secured ne t w o r k s e rvice su ch a s rlogin, rsh, rcp,

ftp, or telnet, the requestin g client application uses the previo u sly

obtained TGT in a dialogue wit h the TGS to obtain a servi ce t ic ket. The protocol is the same as used while obtaining the TGT, except that the messages contain the name of the server and a copy of the previously obtained TGT.

Step 5. The TGS returns a new service ticket that the applicati on clien t can us e

to authenticate to the service. The service ticket is encrypted with the service key shared between the KDC and the application server.

Step 6. The application server authenticat es the cl i en t usi n g the serv i ce key

present in the keytab file. It decrypts the service ticket using the service key and extracts th e session key. Us ing the session key, the server decrypts the authenticator and verifies the identity of the user. It also

Chapter 126

Overview

Authentication Process

verifies tha t t he u s er’s service ticket has not exp ir ed. If the user doe s not have a valid service ticket, th e n the se rv er will return an appropriat e error cod e to the cli ent.

Step 7. (Optional) At the client’s request, the application server can also return

the timestam p sen t by the client, en cryp te d in the se ssion key. This ensures a mutual authentication between the client and the server.

Chapter 1 27

Overview

Kerberos Products and GSS-API on HP-UX

HP-UX supports Kerberos pro ducts wit h a set of three s oftware packa ges and Generic Security Service Application Programming Interface (GSS-API) for HP-UX 11.0 onwards. These products are:

• P AM Kerberos (PAM-Kerberos)

• Kerberos Client Software

• Kerberos Server

• GSS-API

Application p rogrammers can cre a te “Kerberized” applicatio ns using either the GSS-APIs or the Kerberos APIs. However, HP recommends that GSS-APIs be used for application development. HP provides the following Kerberized applications through Secure Internet Services (SIS): ftp, rcp, remsh, rlogin, and telnet.

NOTE SIS is available on HP-UX 11.0 and HP-UX 11i v1 only. From HP-UX 11i

v2 onwards, all these applications directly link to libkrb5.

The HP-UX Kerberos-related product s and GSS-API are:

• PAM Kerberos (PAM-Kerberos): is the Kerberos implementation

of the PAM Framewor k based on the RFC 86.0 of Open Group. PAM allows multiple authentication technologies to co-exist on HP-UX.

• Kerberos Client Software: includes libraries, header files and

utilities for imple m en tin g Ke r be rized client/ server applications in either 32-bit or 64-bit develo pment environment.

The client libraries are based on MIT Kerberos V5 1.1.1 release. The KRB5-Client libr a ries su p por t DES e nc ry ptio n as sp ecifie d in RF C 1510 of the IETF.

Chapter 128

Overview

Kerberos Products and GSS-API on HP-UX

NOTE On HP-UX 11i v3, the KRB5-Client libraries are based on MIT

Kerberos V5 1.3.5 release. These KRB5-Client libraries support the DES, AES, 3DES and RC4 encryption types.

The Kerberos C lient utilities are as follows :

— kinit, klist, and kdestroy to manage credentials — kpasswd to change Kerberos passwords — ktutil to maintain keytab file — kvno to display the Kerberos key version number of the

principals.

• Kerberos Server Version 3.12: The current version of the

Kerberos server supersedes the earlier MIT-based Kerberos server (version 1.0), on HP-UX 11i.

The Kerberos Server is based on a distributed cl ie nt-s erv er architecture. It ensures secure communication in a networked environment by leveraging individual trust relationships. It then brokers that trust ac ross ente r p ris e-w ide, distributed client-serve r networks.

• GSS-API: is an interface that provides a secure client- server

application programming. The GSS-API also provides authenticati on , inte gri ty, and confidentiality services to the cal ling applications.

• SIS: is the built- i n suppo rt f o r s e cure Inte r n e t s e rvices su ch a s ftp,

rcp, rlogin, telnet and remsh utilities. When secure Internet

services are enabled, these commands use Kerberos for authenticati on without sending pa sswords in clear tex t ov er the network.

Chapter 1 29

Overview

Kerberos Products and GSS-API on HP-UX

Chapter 130

2 Introduction to the Kerberos

Products and GSS-API

This chapter describes the Kerberos-based products and GSS-API on HP-UX.

Chapter 2 31

Introduction to the Kerberos Products and GSS-API

It contains the following sections:

•“PAM Kerberos” on page 33

•“Secure Internet Services” on page 52

•“KRB5 Client Software” on page 5 4

•“HP Kerberos Server” on page 64

•“Generic Security Service Application Programming Interface

(GSS-API)” on page 68

Chapter 232

Introduction to the Ker beros Products and GSS-API

PAM Kerberos

HP-UX provides Kerberos authenti cat i on as part of the Plugga b l e Authentication Module (PAM) architecture as specified in RFC 86.0, of the Open Group. PAM allows multiple authentication technologies to co-exist on HP-UX. The /etc/pam.conf configuration file determines the authentication module to be used in a manner transparent to the applications th at use the PAM library.

This product con sists of the following :

• PAM Kerber o s li brary - libpam_krb5

• PAM Kerberos Configuration validatio n tool - pamkrbval. Refer to

“The pamkrbval Tool” on page 48, for more information.

Chapter 2 33

Introduction to the Kerberos Products and GSS-API

PAM Kerberos

The PAM Framewor k

Figure 2-1 shows the relationship between the PAM Kerberos Library and various authentication modules that HP-UX provides. Note that the PAM Kerberos Library is one of the many authentication modules that PAM can invoke based on what is defined under the PAM configuration file: /etc/pam.conf.

Figure 2-1 HP-UX authentication modules under

PAM

PAM library

passwd

Authentication Service

Use the PAM configuration file, pam. conf, to indicate which authentic atio n m od ule to u

UNIX DCE Kerberos LDAP NTLM

libpam_krb5.1 libpam_ntlm.1libpam_unix.1

libpam_dce.1 libpam_ldap.1

PAM Kerberos is invoked for user authentication, when PAM’s authentication-management module is pointed to the shared dynamically loadable PAM Kerberos library, libpam_krb5. Table 2-1 indicates the loca tio n o f the librar y on both It aniu m based platforms.



and PA-RISC

Chapter 234

Introduction to the Ker beros Products and GSS-API

Table 2-1 PAM Kerberos Library libpam_ krb5

Platform Location

Itanium

/usr/lib/security/$ISA/libpam_krb5.so.1



based platform

PAM Kerberos

PA-RISC

/usr/lib/security/libpam_krb5.1

platform

Figure 2-2 shows a secure environ ment con s i sti n g of the foll owin g nodes:

• KDC Server

• The application server (rlogind process)

• The applicat ion client (rlogin process)

The application client is not a KDC client under PAM Kerberos.

Figure 2-2 PAM Kerberos calls libkrb5.sl through

PAM

Chapter 2 35

Introduction to the Kerberos Products and GSS-API

PAM Kerberos

When using PAM Kerberos, users only configure the appl i cat i on server as a KDC client. Users are prompted for a password when they first log into the server from the application client. The user has no credential and their passw ord is sent in cle ar tex t to the app lic atio n se r ver. Following are the authentication steps as shown in Figure 2-2:

1. The user sends a password to a remote system

2. The application server invokes libkrb5.sl through PAM to request for authenticatio n from the KDC

3. KDC replies with an authenticator

4. If the password provided is valid, then the user is authenticated. If the password is incorrect, the user is denied access.

The Kerberos service module for PAM consists of the following four modules:

• Authentication module

• Account management module

• Session management module

• Password management module

All modules are supported through the same dynamically loadable library, libpam_krb5. The KRB5 PAM modules are compatible with MIT Kerberos 5 and Microsoft Window s 2000.

The Authentication Module

The Authentication module verifies the identity of a user and sets user-specific credentials. It authenticates th e user to K DC with a password. If the password matches, the user is authenticated and a Ticket Granting Ticket (TGT) is granted.

The Authentic atio n Mo d ul e su p por ts th e follo wing options:

• use_first_pass

• krb_prompt

• try_first_pass

• renewable=<time>

• forwardable

Chapter 236

Introduction to the Ker beros Products and GSS-API

PAM Kerberos

• proxiable

• debug

• ignore

The following paragraphs list and describe each of these options. Option Definition use_first_pass Uses the sam e p assword given to the firs t mod u le

configured for authent i cat i on in the pam.conf file (see Figure 2-1). The module does not prompt for the password if the user cannot be authenticated by the first password.

This option is used when the system administrator wants to enforce the same password across multi pl e modules.

In the fo l lowing code fragmen t from a pam.conf file, both libpam_krb5.1 and libpam_unix.1 are defined in the PAM stack as authentication modules. If a user is not authenticated under libpam_unix.1, PAM tr ies to authenticate the user through libpam_krb5.1 using the sam e p asswo r d used with libpam_unix.1. If the authentication fails, PA M does not prompt for another password.

Table 2-2 On HP-UX 11.0 and HP-UX 11i v1

Table 2-3 On HP-UX 11i v2 and HP-UX 11i v3

krb_prompt This option allows the administrator to change the

password prompt. When set, the password prompt displayed is, Kerberos Password.

try_first_pass This option is similar to the use_first_pass option,

except that if the p rimar y p assword is not valid, PAM prompts for a password.

Chapter 2 37

Introduction to the Kerberos Products and GSS-API

PAM Kerberos

In the fo l lowing code fragmen t from a pam.conf file, both libpam_krb5.1 and libpam_unix.1 are defined in the PAM stack as authentication modules. If a user is not authenticated under libpam_unix.1, PAM tr ies to authenticate the user through libpam_krb5.1 using the same pas sword that is used with libpam_unix.1. If the authentication fails, PAM prompts for another password and tries again.

Table 2-4 On HP-UX 11.0 and 11iv1

Table 2-5 On HP-UX 11i v2 and HP-UX 11i v3

renewable=<time> This option allows the user to implement ticket

renewal. Rene wabl e tickets have two “expiration times”: the first is when the current instance of the ticket expires , and the second is the latest permissible value for an individual expiration time. When the latest permissible expiration time arrives, the ticket expires permanently.

For renewable ti ck e ts t o be gr a nted, you m ust specify that the user can be grante d rene wable tick e ts in th e user’s account in the Kerberos KDC.

forwardable When a user obtains service tickets, they are for a

remote system. However, the user can use a secure service to access a remo te syst em an d run a secure service from th at rem o te system to a second remo te system. This requires a valid TGT for the first rem o te system. Kerberos provides the option to create TGTs with special attributes, which allow servic e tic kets to be forwarded to remote systems within th e r ea lm.

The forwardable flag in a ticket allows the serv i ce complete use of the client's identity. It is used when a user logs in to a remote syste m and wants authentica tion to work from that syst em as if the login were local.

Chapter 238

Introduction to the Ker beros Products and GSS-API

PAM Kerberos

For forwardable tickets to be granted, you must specify that the user can be granted forwardable tickets in the user's account in the Kerberos KDC.

proxiable At times, it may be necessary for a principal to allow a

service to perform an operatio n on its behalf. The service must be able to take on the identity of the client, but only for a particular purpose by granting it a proxy.

This option allo ws a client to pa ss a proxy ticket to a server to perform a remote request on its behalf. For example, a print service client can give the print server a proxy to access the client's files on a particular file server.

For proxy tickets to be granted, you must specify that the user can be gran te d prox y ticke ts in the user's account in the Kerberos KDC.

ignore The ignore option in the pam_user.conf file enables

you to configure PAM such that certain users or services need not be authenticated. This option returns PAM_IGNORE. HP recommends not to use this option for Kerberos authenticati on in the pam.conf fil e .

For example, with the following conf ig uration, no Kerberos authentication is condu cted for the root user.

On HP-UX 11.0 and HP-UX 11i v1

pam_user.conf: # # configuration for user root. KRB5 PAM module uses the ignore

# option and returns PAM_IGNORE without any processing. # root auth /usr/lib/security/libpam_krb5.1 ignore root password /usr/lib/security/libpam_krb5.1 ignore root account /usr/lib/security/libpam_krb5.1 ignore root session /usr/lib/security/libpam_krb5.1 ignore

On HP-UX 11i v2 and HP-UX 11i v3

pam_user.conf: # # configuration for user root. KRB5 PAM module uses the ignore

Chapter 2 39

Introduction to the Kerberos Products and GSS-API

PAM Kerberos

# option and returns PAM_IGNORE without any processing. # root auth /usr/lib/security/$ISA/libpam_krb5.so.1 ignore root password /usr/lib/security/$ISA/libpam_krb5.so.1 ignore root account /usr/lib/security/$ISA/libpam_krb5.so.1 ignore root session /usr/lib/security/$ISA/libpam_krb5.so.1 ignore

To enable the configuration defined in the pam_ use r.c on f file, the libpam_updbe m o dule m ust be the first module in the stack in the pam.conf file. PAM Kerberos uses libpam_updb e to r ea d u se r pol ic y d ef in itio ns from the pam_user.conf file. Refe r to the ma np age pam_updbe (5) for more in formati o n ab o ut per user PAM configuration.

debug The debug option sets syslog debugging inf orm ation

at the LOG_DEBUG leve l.

The Password Module

The Password Management module provides a function to change passwords in the Kerberos password database. Unlike when changing a Unix password, a root user is alway s prompt ed for the old pass wo rd.

The following o p tions can be passed to this PAM module thr o ug h the

/etc/pam.conf (4) file: debug This option allows syslog(3C) d eb ugg ing information

at LOG_DEBUG level.

krb_prompt This option allows the administrator to change the

password prompt. When set, the password prompt displayed is Old/New Kerberos Password.

When a user logs onto a system using PAM kerberos they obtain credentials tha t are stored i n a file. This file is deleted when the user logs out of the system if the /etc/pam.conf file contains an entry for PAM Kerb ero s und e r ses sio n m a n a ge me nt a n d th e application calls pam_close_session().

In the /etc/pam.conf, if the flag krb_prompt is added to either the login/password entry, the prompt explicitly specifies Kerberos as shown below:

$ old password <--- Previous output

Chapter 240

Introduction to the Ker beros Products and GSS-API

PAM Kerberos

$ old Kerberos password <--- Output if krb_prompt is specified

user_first_prompt This option allows the initial password (entered

when the use r is auth e ntic ate d to the first authentica tion m o dule in the stac k) to a uth entic a te with Kerberos. If the user cannot be authenticated or if this is the first auth e ntic atio n module in the stack , it quits without prompting for a password. HP recomme nd s us ing this option only if the authentica tion m od ule is des ign ate d as option al in the

/etc/pam.conf(4) configuration file.

try_first_pass This option allows the initial password (entered w hen

the user is authenticated to the first authentication module in the PAM stack) to authenticate with Kerberos. If the user cannot be authentic a te d or if this is the first auth e ntic atio n module in the stack , it prompts the user for a password.

ignore This option returns PAM_IGNORE. HP recommends not

using this option. However, if you do not want to authentic ate certa in use r s or services with Kerb ero s, you can use this option in the /etc/pam_user.conf(4) file for per user con figuration. HP reco m men d s not using this optio n in the pam.conf(4)file.

Refer to /etc/pam.krb5 in Appendix A, “Sample pam.co nf File,” for a sample pam.conf file configured for PAM Kerberos.

Cred ential C a c h e

The credential management function in Kerberos sets user-specific credentials. It stores the credentials in a cache file and exports the KRB5CCNAME environment variable to identify the cache file. Any subsequent kerbe ros ser v ice ac cess can use the same credential file. The name of that file is retrieve d f rom KRB5CCNAME.

A credential file is created in the /tmp directory when the user accesses the system.

If the user fi rst ac cesses the system fr om any sy stem en try servi ce -- su ch as login, ftp, rlogin, o r telnet -- a unique credential file is created in the /tmp/creds directory. This fil e is named krb5cc_<ppid>_<pid>, where:

Chapter 2 41

Introduction to the Kerberos Products and GSS-API

PAM Kerberos

ppid is the parent process pid is the process id of the process that is creating this

credential file

An example PAM configuration file is as sho wn belo w:

Chapter 242

Introduction to the Ker beros Products and GSS-API

PAM Kerberos

On HP-UX 11.0 and 11iv1

# # PAM confi gu ra tion # # Authen tic at ion manage ment # login auth sufficient /usr/lib/security/libpam_krb5.1 login auth required /usr/lib/security/libpam_unix.1 try_first_pass su auth sufficient /usr/lib/security/libpam_krb5.1 su auth required /usr/lib/security/libpam_unix.1 try_first_pass dtlogin auth sufficient /usr/lib/security/libpam_krb5.1 dtlogin auth required /usr/lib/security/libpam_unix.1 try_first_pass dtaction auth sufficient /usr/lib/security/libpam_krb5.1 dtaction auth required /usr/lib/security/libpam_unix.1 try_first_pass ftp auth sufficient /usr/lib/security/libpam_krb5.1 ftp auth required /usr/lib/security/libpam_unix.1 try_first_pass OTHER auth sufficient /usr/lib/security/libpam_unix.1 # # Accoun t man ag ement # login account re qu ir ed /usr/lib /security/libpam_krb5.1 login account re qu ir ed /usr/lib /security/libpam_unix.1 su account re qu ir ed /u sr/lib/security /libpam_krb5.1 su account re qu ir ed /u sr/lib/security /libpam_unix.1 dtlogi n accoun t re quired /usr /lib/security/libpam_krb5.1 dtlogi n accoun t re quired /usr /lib/security/libpam_unix.1 dtacti on accoun t required /u sr/lib/security/libpam_krb5 .1 dtacti on accoun t required /u sr/lib/security/libpam_unix .1 ftp accoun t re qu ir ed /usr/lib/securi ty/libpam_krb5.1 ftp accoun t re qu ir ed /usr/lib/securi ty/libpam_unix.1 OTHER account su ff ic ient /usr/l ib/security/libpam_unix.1 # # Sessio n man ag ement # login session re qu ir ed /usr/lib /security/libpam_krb5.1 login session re qu ir ed /usr/lib /security/libpam_unix.1 dtlogi n sessio n re quired /usr /lib/security/libpam_krb5.1 dtlogi n sessio n re quired /usr /lib/security/libpam_unix.1 dtacti on sessio n required /u sr/lib/security/libpam_krb5 .1 dtacti on sessio n required /u sr/lib/security/libpam_unix .1

Chapter 2 43

Introduction to the Kerberos Products and GSS-API

PAM Kerberos

OTHER session su ff ic ient /usr/l ib/security/libpam_unix.1 # # Passwo rd ma na gement # login password sufficient /usr/lib/security/libpam_krb5.1 login password required /usr/lib/security/libpam_unix.1 passwd password sufficient /usr/lib/security/libpam_krb5.1 passwd password required /usr/lib/security/libpam_unix.1 dtlogin password sufficient /usr/lib/security/libpam_krb5.1 dtlogin password required /usr/lib/security/libpam_unix.1 dtaction password sufficient /usr/lib/security/libpam_krb5.1 dtaction password required /usr/lib/security/libpam_unix.1 OTHER password sufficient /usr/lib/security/libpam_unix.1

On HP-UX 11i v2 and HP-UX 11i v3

# # PAM confi gu ra tion # # Notes: This pam.conf file is intended as an example only. # If the path to a library is not absolute, it is assumed to be # relative to one of the following directories: # /usr/l ib/ se curity (PA 32 -b it ) # /usr/l ib/ se curity/p a20_64 (PA 64-bit) # /usr/l ib/ se curity/h pux32 (IA 32-bit) # /usr/l ib/ se curity/h pux64 (IA 64-bit) # The IA file name convention is normally used; for example: # libpam _un ix .so.1 # For PA libp am _u nix.so.1 is a symbolic link to the PA library: # ln -s libpa m_ un ix.1 libpam _unix.so.1 # Also note that the use of pam_hpsec(5) is mandatory for some of the # services. See pam_hpsec(5). # Authen tic at ion manage ment # login auth sufficient libpam_krb5.so.1 login auth required libpam_unix.so.1 try_first_pass su auth sufficient libpam_krb5.so.1 su auth required libpam _unix. so.1 try_first_pass dtlogin auth sufficient libpam_krb5.so.1 dtlogin auth required libpam_unix.so.1 try_first_pass dtaction auth sufficient libpam_krb5.so.1 dtaction auth required libpam _unix. so.1 try_first_pass ftp auth sufficient libp am_krb5.so. 1

Chapter 244

Introduction to the Ker beros Products and GSS-API

ftp auth required libpam_unix.so.1 try_first_pass OTHER auth sufficient libpam_unix.so.1 # # Accoun t man ag ement # login account re qu ire d libpam _k rb 5.so.1 login account re qu ire d libpam_unix.s o.1 su account required libpam_krb5.so.1 su account required libpam_unix.so.1 dtlogi n accoun t re quired libpam_k rb5.so.1 dtlogi n accoun t re quired libpam_u nix.so.1 dtaction account required libpam_krb5.so.1 dtaction account required libpam_unix.so.1 ftp accoun t re qu ire d libpam_krb5.so.1 ftp accoun t re qu ire d libpam_unix.so.1 OTHER account su ff ici ent libpam _unix.so.1 # # Sessio n man ag ement # login session re qu ire d libpam_krb5.s o.1 login session re qu ire d libpam_unix.s o.1 dtlogi n sessio n re quired libpam_k rb5.so.1 dtlogi n sessio n re quired libpam_u nix.so.1 dtaction session required libpam_krb5.so.1 dtaction session required libpam_unix.so.1 OTHER session su ff ici ent libpam _unix.so.1 # # Passwo rd ma na gement # login password sufficient libpam_krb5.so.1 login password required libpam_unix.so.1 passwd password sufficient libpam_krb5.so.1 passwd password required libpam_unix.so.1 dtlogin password sufficient libpam_krb5.so.1 dtlogin password required libpam_unix.so.1 dtaction password sufficient libpam_krb5.so.1 dtaction password required libpam_unix.so.1 OTHER password sufficient libpam_unix.so.1

PAM Kerberos

Chapter 2 45

Introduction to the Kerberos Products and GSS-API

PAM Kerberos

The Account Management Module

The Account Manag e m ent mod ule pr o vides a function to perfo rm account ma nagement. This function re tr ie ve s the use r ’s account and password expiration information from the Kerberos database and verifies that they ha ve no t expi red. The module does not iss ue any warning if the account or the password is about to expire.

The following opti on s can be pa ssed t o t h e Acc ou nt Ma nagement module through the /etc/pam.conf(4) file :

debug This option allows syslog(3C) d eb ugg ing information

at LOG_DEBUG level.

ignore This option returns PAM_IGNORE. HP recommends not

using this option unless it is not nece ssar y to authentic ate certa in use r s or services with Kerb ero s. In such case s yo u c an use the ignore option in the pam_user.conf file for per use r configuration.

HP does not recommend using this option in the pam.conf file.

The Session Management Module

The session management module provides function to terminate sessions. It cleans up the credential cache file created by the Authentication module.

The following o ptio ns can be passed to th e session manage m en t m odu le through the /etc/pam.conf(4) file:

debug This option allows syslog(3C) d eb ugg ing information

at LOG_DEBUG level.

ignore This option returns PAM_IGNORE. HP recommends not

using this option unless it is not nece ssar y to authentic ate certa in use r s or services with Kerb ero s. In such case s yo u c an use the ignore opti on i n the pam_user.conf file for per user configuration. HP does not rec ommen d using this option in t he pam.conf file.

Chapter 246

Introduction to the Ker beros Products and GSS-API

Example

The following is a samp le configuration in which no authentication is done with Kerberos for root. KRB5 P AM module does nothi ng. It just returns PAM_IGNORE for user root. For every user other than root, i t tri es to authenticate using Kerberos. If Kerberos succeeds, the user is authenticated . If K erb ero s fails to authenticate the user, PAM tries to authenticate with UNIX PAM using the sam e pass wo rd.

The pam_user.conf File on HP-UX 11.0 and 11i v1

# config ura ti on for user roo t. KRB5 PAM module uses the # ignore option and returns PAM_IGNORE root auth /usr/lib /se cu rity/lib pam_krb5.1 ignore root passwor d /u sr /lib/secu rity/libpam_krb5.1 ignore root account /usr /l ib/securi ty/libpam_krb5.1 ignore root session /usr /l ib/securi ty/libpam_krb5.1 ignore

The pam_user.conf File on HP-UX 11i v2 and HP-UX 11i v3

# configuration for user root. KRB5 PAM module uses the # ignore option and returns PAM_IGNORE root auth /usr/lib/ se cu rity/$IS A/libpam_krb5.so.1 ignore root passwor d /u sr /lib/secu rity/$ISA/libpam_krb5.so.1 ign ore root account /usr /l ib/securi ty/$ISA/libpam_krb5.so.1 ignor e root session /usr /l ib/securi ty/$ISA/libpam_krb5.so.1 ignor e

PAM Kerberos

The pam.conf File on HP-UX 11.0 and HP-UX 11i v1

# For per user configuration the libpam_updbe.1 (pam_updbe(5)) module # must be the first module in the stack. If Kerberos authentication # is valid th e UN IX authentica tion function will not be invoked.

login auth required /usr/l ib /security /libpam_updbe.1 login auth sufficie nt /usr /lib/secu rity/libpam_krb5.1 login auth required /usr/l ib /security /libpam_unix.1 try_first_pass login passw or d req uired /usr/lib /security/libpam_updbe.1 login passw or d req uired /usr/lib /security/libpam_krb5.1 login passw or d req uired /usr/lib /security/libpam_unix.1 try_fi rst_pass login account required /usr/lib/security/libpam_updbe. login account required /usr/lib/security/libpam_krb5.1

Chapter 2 47

Introduction to the Kerberos Products and GSS-API

PAM Kerberos

The pam.conf File on HP-UX 11i v2 and HP-UX 11i v3

login auth required libpam _u pdbe.so.1 login auth sufficie nt libpam _k rb 5.s o.1 login auth required libpam _u nix.so.1 try_f ir st _pass login passw or d req uired libpam_updbe.so .1 login passw or d req uired libpam_krb5.so. 1 login passw or d req uired libpam_unix.so. 1 try_f ir st _pass login accou nt requi red libpam_updbe.so.1 login account required libpam_krb5.so.1

The pam_krb5 File on HP-UX 11.0 and HP-UX 11i v1

login account required /usr/lib/security/libpam_unix.1 login session required /usr/lib/security/libpam_updbe.1 login session required /usr/lib/security/libpam_krb5.1 login session required /usr/lib/security/libpam_unix.1

The pam_krb5 File on HP-UX 11i v2 and HP-UX 11i v3

login account required /usr/lib/security/$ISA/libpam_unix.so.1 login session required /usr/lib/security/$ISA/libpam_updbe.so.1 login session required /usr/lib/security/$ISA/libpam_krb5.so.1 login session required /usr/lib/security/$ISA/libpam_unix.so.1

The pamkrbval T ool

Use the pamkrbval tool to validate your PAM Kerberos configuration. This tool verifies PA M Kerberos configuration files and enables the system administra t or to diag nose th e probl em, if any. Following are the files, the pamkrbval tool verif ies:

• /etc/pam.conf

• /etc/pam_user.conf

• /etc/krb5.conf

• /etc/krb5.keytab

This tool also checks if the default realm KDC is up an d running. The pamkrbval tool validates the following:

Chapter 248

Introduction to the Ker beros Products and GSS-API

PAM Kerberos

• Checks for t he val i di t y o f t he control_flags and the module_types specified for the PAM Kerberos specific entrie s in the /etc/pam.conf file.

• Checks if the P A M Kerberos specifi c module_path specified in the /etc/pam.conf file exists. If the module_path nam e is not a bso lute

it is assumed to be relative to /usr/lib/security/$ISA/. The $ISA (Instruction Set Ar chitecture) token is rep lac e d by this to o l with hpux32 for Itanium Itanium



64 bit option (ia64), or with null for PA-32 bit option



32-bit option (ia32), or with hpux64 for

(pa32), or with pa20_64 for PA 64-bit option (pa64).

• Checks if the options specified for the pam_krb5 library are valid PAM Kerberos options.

• Validates the /etc/pam_user.conf file on ly if libpam_updbe is configured in the /etc/pam.conf file. This validatio n is similar to the /etc/pam.conf validation.

• Val idates the syntax of the Kerberos configuration file, /etc/krb5.conf.

• Validates if the defaul t re alm KDC is issuing tickets. At least one KDC must reply to the tick e t reque s ts for the default realm.

• Validates the host se r vic e prin ci pa l, host/<hostname>@default_realm> in /etc/krb5.keytab, if present. If the keytab entry for this host servi c e pri nci pal i s not present in the default keytab file, /etc/krb5.keytab the n that validation is ignor ed and suc cess is assumed.

NOTE An entry in /etc/pam.conf file is considered to be PAM Kerberos

entry if the file name in th e module_path begins with libpam_krb5. An example of a PAM Kerberos entry in /etc/pam.conf is as shown:

The machine is considered to be configured with libpam_updbe if th e fil e name in the module_path of an entry in /etc/pam.conf begins with

libpam_updbe. Following is an example of a pam_updbe entry in the /etc/pam.conf file:

Chapter 2 49

Introduction to the Kerberos Products and GSS-API

PAM Kerberos

Logging The pamkrbval tool logs all messages to stdout. Following are the log

catego ri e s p rovided : [LOG] These messages are logged when the verbose option is

set.

[NOTICE] These messages are logged to notify the user about the

erroneous lines in the PAM configuration files or notify about the skip p ing of /etc/pam_user.conf file validation.

[FAIL] These messa ge s are logge d when validation fail s. [WARNING] These messa ge s are logge d to no tify the use r abou t a

potentially erroneous configuration on the system that may result in failu re.

[PASS] These messages are logged whe n any va lidation

succeeds.

[IGNORE] These messages are logged when validation of the

/etc/krb5.keytab is ignored.

ERROR These messages are log ged to i nform the user about t he

exact problem in the PAM configuration file s

[HELP] These messages will give some minim al help to the

user to rectify the problem.

If you get any [FAIL] or ERROR messages, you mus t diagnose the nature of the problem. See “Troubleshooting Using the pamkrbval Tool” on page 100 for more information.

Options Use the followin g co mmand wit h the opti ons lis t ed below:

/usr/sbin/pamkrbval

-v[erbose] verbose output

-a {pa32 | pa64 |ia32 | ia64}

Depending on the architecture on which the validation need to be done this option needs to be set. Th e flags available are as listed belo w:

pa32 for PA 32-bit architecture pa64 for PA 64-bit architecture



ia32 for Itanium

32-bit architecture

Chapter 250

Introduction to the Ker beros Products and GSS-API

PAM Kerberos

ia64 for Itanium



64-bit architecture

Depending on this flag, $ISA in the module_path will be expanded as explaine d above.

-c Use t his opt ion w h e n Com m on Interne t Fi l e S y stem

(CIFS) is configured on the system.

Return Value The pamkrbval tool returns the following exit codes:

0 Successful configuration validation 1 Warnings were found dur ing configura tio n va li da tio n 2 Errors were det ecte d durin g co nfiguration valid atio n

Chapter 2 51

Introduction to the Kerberos Products and GSS-API

Secure Internet Services

If you want to authenticate users on remote systems without sending the password in c l ea r text over the net w ork, you can use the b uilt-in suppo rt that HP provides for the following secure Internet services applications:

• ftp

• rcp

• rlogin

• telnet

• remsh

In Figure 2-3, SIS invokes the libsis.sl library. Whe n SIS is enable d at the application clie nt , the p assword is not sent to the ap p lica tio n server. Instead, SIS uses an encrypted tic ket ea c h time the user r eq ue sts a remote service.

Figure 2-3 SIS uses Kerberos Client Library Directly

KDC

Server

libsis.sl

Application

Client

As shown in Figure 2-2:

1. The application client requests for credentials from the KDC

2. The application client obtains credentials for the remote host (the application serv e r)

Application

Server

Chapter 252

Introduction to the Ker beros Products and GSS-API

Secure Internet Services

3. Using the credentials, the application client creates an authenticator and sends the authe n tic a tor and service ticket to the rem ote h os t.

4. The kerberized telnet serv er on the remo te host veri fi es the user identity by decrypting the service ticket.

To turn on SIS, issue the following command at the HP-UX command prompt:

inetsvcs_sec enable

NOTE The library, libsis.sl, is supported upto the HP-UX 11i v1.5 release.

From the HP-UX 11i v1.6 release onw a rds the library, libkrb5.so is supported.

Chapter 2 53

Introduction to the Kerberos Products and GSS-API

KRB5 Clie n t Software

KRB5 Client Software

This section presents an overview of the KRB5-Client software, which consists of libr ari es, header files , manpages, and Kerberos uti l iti es. The section is divided into two parts. The following subsection, “Libraries and Header Files”, discusses the libraries and header files supplied with the KRB5 - Client so f t w a r e. The secon d subsecti o n ,“Kerberos Utilities” on page 56, discusses the Kerb ero s ut ilitie s.

Libraries and Header Files

This section lists and desc ri bes the librar ie s and he ad er file s supplied with the KRB5-Clie nt software.

You can use th e KR B 5 - C lient libraries to de velop secure client/serve r applications for either 32-bit or 64-bit environments on any of the HP-UX 11.X platforms.

The client libraries are based on MIT Kerberos V5 1.1.1 release. This release is compatible with MIT Ke r be ros 1.2 and interope r able with Microsoft Windows 2000.

NOTE On HP-UX 11i v3, the KRB5-Client librar ie s are based on MIT Kerberos

V5 1.3.5 release. These KRB5-Client libraries suppor t the DES, AES, 3DES and RC4 encryption types.

The Kerberos Client Library (libkrb5.so) replaces the KRB-Support Library (libsis.sl) from the HP-UX 11i v1.6 release onwards.

The KRB5-Client libraries support Data Encry ptio n Stan dard (DES) as specified in RFC 15 10 of the IET F.

Chapter 254

Introduction to the Ker beros Products and GSS-API

Table 2-6 lists and describes the Kerberos client libraries.

Table 2-6 Kerberos Client Libr aries on H P-UX 11i v3

KRB5 Clie n t Software

Architect-

ure

PA-RISC

32-bit 64-bit Functionality

/usr/lib/libkrb5.sl

->/usr/lib/libkrb5.1

/usr/lib/ libcom_err.sl -> /usr/lib/libcom_err.1

/usr/lib/ libk5crypto.sl -> /usr/lib/libk5crypto.1

/usr/lib/pa20_64/ libkrb5.sl -> /usr/lib/pa20_64/ librb5.1

/usr/lib/pa20_64/ libcom_err.sl -> /usr/lib/pa20_64/ libcom_err.1

/usr/lib/pa20_64/ libk5crypto.sl -> /usr/lib/pa20_64/ libk5crypto.1

Authenticates users, verifies tickets, creates authenticator, and manages the co ntext

Prints appropriate error messages to stderr, based on the error code returned by th e Kerb eros APIs

Encrypts (using DES, 3DES , AES, and RC4 cryptographic algorithms) and decrypts all communication between users to ensure privacy and data integrity

/usr/lib/gss/ libgssapi_krb5.sl -> /usr/lib/gss/libgssapi_ krb5.1

The Kerberos client softw a re also provides the following header fil es :

• /usr/include/profile.h

• /usr/include/krb5.h

Chapter 2 55

/usr/lib/pa20_64/ gss/ libgssapi_krb5.sl

/usr/lib/pa20_64/ gss/libgssapi_krb

5.1

Kerberos mechanis m specific library used by GSSAPI (/usr/lib/libgss. sl)

Introduction to the Kerberos Products and GSS-API

KRB5 Clie n t Software

• /usr/include/com_err.h

• /usr/include/krb5/gssapi.h

HP-UX includ e s DC E Kerberos an d it s ma np ages, so you must use specific manpage numbers for the Kerberos client softw are. For example, refer to man 1 kinit for the Kerberos manpages and to man 1m kinit for the DCE manpage. The default is the Kerberos manpage.

Refer to /usr/share/man/man3.Z/libkrb5.3 for more information on the libkrb5 library. Se e “Kerberos Utilities” on page 56 for information on other Kerbe r os utilities.

NOTE IPv6 support for Kerberos Clients has been enabled only for the

Itanium



binaries on HP-UX 11i v2 and PA-RISC and Itanium binaries

on HP-UX 11i v3 syste m s.

Kerberos Utilities

The HP-UX imp lem en tati on of Ker b ero s ut ilitie s is com p ati b le with the MIT reference implementation.

On HP-UX 11i onwards, the Kerberos uti l iti es are part of the OS core . On HP-UX 11.0, the y are bu ndled w ith PAM Kerberos from th e quart erly distributed App lic atio n C D.

All the utilities, except ktutil, are available for all users. The ktutil utility is re stricte d for a d m inistrator use onl y.

The kinit Utility

Description The kinit utility obtains the Kerberos ticket-granting ticket for the

requesting principa l and stores it in the creden tial cache file.

Synopsis

/usr/bin/kinit -l lifetime [principal] /usr/bin/kinit -s start_time [principal] /usr/b in /ki nit -v [prin cipal] /usr/b in /ki nit -p [prin cipal] /usr/b in /ki nit -f [prin cipal] /usr/bin/kinit -r renewable_life [principal]

Chapter 256

Introduction to the Ker beros Products and GSS-API

KRB5 Clie n t Software

/usr/b in /ki nit -R [prin cipal] /usr/bin/kinit -k [-t keytab_file][principal] /usr/bin/kinit -c [cache_name] [principal] /usr/bin/kinit -S service_name [principal]

Options -l lifetime The -l option requests a ticket with the life time of the

value defined in lifetime. The value for life_time must be followed immediately by one of the following delimiters:

• s - seco nds

• m- minutes

• h- hours

• d- days

For e xample: kinit -l 90m for 90 minutes You cannot mix units; a value of 3h30m will result in an

error. If the -l option is not specified, the default ticket

lifetime (configured by each site) i s used. Speci f yin g a ticket lifetime longer than the maximum ticket life (conf igured by each site) re sults in a tick et with th e maximum lifetime.

-s start_time The -s option requests a postdate d ticke t, va lid starting at start_time. Postdated tickets are issued with the invalid flag set, and need to be passed back to the KDC before use.

-v The -v option requests that the TGT in the cache be passed to the KDC for validation. If the tick et i s wit hin its requ est ed ti me ra ng e, the ca c he is repl ac ed wi th the validated ticket.

-p The -p option requests a proxiable ticket.

-f The -f option requests a forwardable ticket.

-r renewable_life The -r option requests renewable tickets, with a

total lifetime of renewable_life. The duration is in the same format as the -l option, wi t h t h e same delimiters.

Chapter 2 57

Introduction to the Kerberos Products and GSS-API

KRB5 Clie n t Software

-R The -R option request s ren ew a l of t he TGT. You cannot renew an expired ticket even if the ticket is still within its renewable life.

-k [-t keytab_file] The -k option requests a host ticket obtained from a key in the local host’s key tab file. You can specify the name and location of the keytab file with the -t keytab_file option; otherwise the default name and location will be used.

The default credentials cache can vary between systems. If the KRB5CCNAME environment variable is set, its value is used to name the default ticket cach e. Any existing contents of the cache are destroyed by kinit.

-c [cache_filename] The -c option uses cache_name as the credentials (ti cket) cac he n ame and l ocation ; ot herwi se, the default cache name and location will be used.

-S service_name The -s option specifies an alternate service name to get initial tickets.

Principal The Principal uses the principal name from an

existing cache, if there is one.

The kinit utility supports the [appdefau lts] section. The relation sh ip s specified here can be over-ridden by the command-line options. The following relationships are supported by kinit in the [appdefaults] section:

forwardable This relatio n shi p speci fi es if an user can obta in a

forwardable ticket. Valid values with which it can be set are true, false, yes, y, no, n, on , and off.

proxiable This relationship specifies if a user can obtain a

proxiable ticket. Valid values to which it can be set are true, false, yes, y, no, n, on, and off.

tkt_lifeti me This relationship spec ifies the lifetime of the ticke t to

be obtained. The unit of lifetime is either seconds, minutes, hour s o r day s.

renew_lifetime This relationship specifies the renewab l e l ife of the

ticket to be obtained. The unit of lifet i me is ei ther seconds, mi nut e s, hou rs or d ays.

Chapter 258

Introduction to the Ker beros Products and GSS-API

KRB5 Clie n t Software

NOTE F or DCE operations use /opt/dce/bin/kinit.

Reference To vie w t he ki ni t man page, i ss ue th e f ollow i ng co m mand:

$ man 1 kinit

The kl ist Utility

Description The klist utilit y lists the Kerbero s principal and Kerbe ro s tic kets held

in a credentials cache, or the keys held in a keytab file.

Synopsis

/usr/b in /kl ist [-e] /usr/b in /kl ist [-c] [ca che_name] /usr/b in /kl ist [-f] [ca che_name] /usr/b in /kl ist [-s] [ca che_name] /usr/b in /kl ist [-k] [ke ytab_name] /usr/b in /kl ist [-t] [ke ytab_name] /usr/b in /kl ist [-K] [ke ytab_name]

Options -e The -e option displ ays the encryption types of the

session key and the ticket for each creden tial in the credential cache, or each key in the keytab file.

-c The -c option lists tickets held in a credentials cache. This is the default if neither -c nor -k is specifie d.

-f The -f option shows the flags present in the credentials, using the following abbreviations:

• F - forwardable

• f - forwarded

• P - Proxiable

• p - proxy

• D - postDateable

• d - postdated

• R- Renewable

Chapter 2 59

Introduction to the Kerberos Products and GSS-API

KRB5 Clie n t Software

• I - Initial

• i - invalid

-s The -s option sets exit status without klist output.

-k The -k option lists keys held in a keytab file.

-t The -t option displays the time entry timestamps for

each keytab entry in the keytab fi le .

-K The -K option displays the value of the encryption key in each keytab entry in the keytab file.

Reference To view the klist man page, issue the following command:

$ man 1 klist

The kdestroy Utility

Description The kdestroy utility destroys the user’s active Kerberos authorization

tickets by writing zeros to the specified credentials cache that contains them. If the credentia l cache is not specified, t he default credential cache is destroyed.

A user's credentials are not automatically removed by exiting from a

SHELL or logging out. You need to remove the credential cache files

manually before lo ggi ng o ut using the kdestroy command. If you use the csh shell, you can include kdestroy in the .logout file in

your home directory. Additionally, the system admini str ator can remove expired credential cache files using either a start script or a cron job to recover disk space and prevent maliciously access to the network credentials.

Synopsis

/usr/bin/kdestroy [-q] /usr/bin/kdestroy [-c] [cache_name]

Options -q The -q option suppresses beeps if it fails to destroy the

user’s tickets.

-c The -c option uses cache_name as the credentials (ticke t) ca che name and lo cat ion; if ca che_name is not specified, th e default cach e n a me and location ar e used.

Reference To view the kdestroy manpage, i ss ue th e f ollow i ng command:

Chapter 260

Introduction to the Ker beros Products and GSS-API

KRB5 Clie n t Software

$ man 1 kdest ro y

The kpasswd Utility

Description The kpasswd utility changes a user’s Kerberos password.

If the optional parameter principal is not used , kpasswd uses the principal name from an existi ng cache i f there is one . If not, the pr incipa l is derived from the identity of the user by invoking kpasswd.

The kpasswd utility prompts for the current Kerberos password that is used to obtain a changepw ticket from the KDC for the user’s Kerberos

REALM. If kpasswd succe ssfully obtains the changepw ticket, the user is

prompted twice for a new password to make the password change. Use kpasswd for your MIT KD C server only, not for Microsoft 2000

KDC. Also, note that kpasswd only changes Kerberos passwords on the KDC, not the UNIX passwor d. Use t he UNIX passwd command to change your UNI X password on th e /etc/passwd file.

Synopsis

/usr/b in /kp asswd [pri ncipal]

Reference To view the kpasswd m anp age, issue the following command:

$ man 1 kpass wd

The ktutil Utility

Description The ktutil utility m ain tains the keytab files. It is restrict e d only for

system administrator’s use.

Synopsis

/usr/sbin/ktutil ktutil : lis t (A lias: l) ktutil : rea d_ kt keytab (A lias: rkt) ktutil : rea d_ st srvtab (A lias: rst) ktutil : wri te _kt keytab (Alias: wkt) ktutil : wri te _st srvtab (Alias: wst) ktutil : cle ar _list (Ali as: clear) ktutil : del et e_entry sl ot (Alias: delete) ktutil : lis t_ requests (Alias: lr or ?)

Chapter 2 61

Introduction to the Kerberos Products and GSS-API

KRB5 Clie n t Software

ktutil : qui t (A lias: exit or q)

Options list (Alias: l) The l option displays the cu rr ent keylist.

read_kt keytab (Alias: rkt) The rkt option reads the Kerberos V5

keytab file key tab into the current keylist .

read_st srvtab (Alias: rst) The rst option reads the Kerberos V4

server

KEYTAB file server keytab into the current

keylist.

write_kt keytab (Alias: wkt) The wkt option writes the current keylist

into the Kerberos V5 keytab file keytab.

write_st srvtab (Alias: wst) The wst option writes the current keylist

into the Kerberos V4 server keytab file.

clear_list (Alias: clear) The clear option clears the current keylist. delete_entry slot (Alias: delete) The delete option deletes the entry

in slot number slot from the current keylist.

list_requests (Alias: lr or ?) The list_request option displays a

list of available command s.

Reference To view the ktutil manpage, issue the following command:

$ man 1 ktuti l

The kvno Util ity

Description The kvno utility acquires a service ticket for the specified Kerberos

princip als to retu rn key ver si o n numbers o f Kerbero s p ri ncipals. The kvno utility uses the environment variable KRB5CCNAME, which

records the location of the credentials (ticket) cache.

Synopsis

/usr/bin/kvno [-e etype] service1, [service2,...]

Options -e etype Specifies the encryption type which will be requested

for the session key of all the services named on the command line. Th is is useful in certain backward compatibility situations. The value of etype can be one

DES-CBC-CRC, DES-CBC-RAW or DES-CBC-MD5.

[service1], [service2] Service name(s) or principal name(s). To view the kvno manpage, issue the following command:

Chapter 262

$ man 1 kvno

Introduction to the Ker beros Products and GSS-API

KRB5 Clie n t Software

Chapter 2 63

Introduction to the Kerberos Products and GSS-API

HP Kerberos Server

Kerberos Server ensures secure communication in a networked environment b y leverag ing in dividua l tr ust rel ationships . It then b roker s that trust across enterprise wide, distributed client-server networks.

T able2-7 lists the various versions of Kerberos Server av ail ab l e for different HP-UX operating systems.

Table 2-7 Versions of Kerberos Server on HP-UX Operating Systems

Kerberos Server

Version

Kerberos Server v 2.1 HP-UX 11.0 and HP-UX

Kerberos Server v3.1 HP-UX 11i v2 Kerberos Server v3.12 HP-UX 11i v3

HP-UX OS Version

11i v1

Kerberos Server Versio n 3.12 F eatures

This version of the Kerberos Server offers the following features on HP-UX 11i v3:

•“Graphical User Interface (GUI) Based Administration tool” on

page 65

•“Multithreaded Server” on pag e 65

•“High Availability” on page 65

•“Dynamic Propagati on ” on page 66

•“Scalability” on page 66

•“Windows 2000(R) Interoper ability” on page 66

•“Choice of C-Tree or LDAP Database” on pag e 67

•“Auto-Configuration Tool” on page 67

This version o f the Kerber os s erver i ntegrates with t he exis ting Kerbe ros clients on HP-UX 11i, thus providing the end user a full fledged s ecurit y solution.

Chapter 264

Introduction to the Ker beros Products and GSS-API

HP Kerberos Server

Kerberos server v3.1 2 s uper s edes t he earlier MIT based Kerber os server (version 1.0), on HP-UX 11i. This vers i on of the Kerberos ser ver offers many enhancements when compared to the previous version.

F or info rmat i on on previou s Kerberos Server versi on s , see the Release Notes at www.docs.hp.com/en/internet.html#Kerberos

Graphical User Interface (GUI) Based Administration tool

Use the GUI to create and manage principals in the Kerberos Realms. This includes both the remote ad m in istr a tor, kadmin_ui, and the local administrator, kadminl_ui. Following are t he func t i ons you can perform using the GUI:

• create, modify and delete principals

• alter principal account key type settings

• assign admin istr ative permissions

• modify the default group principals

• extract keys of principals to service key table files

• change the p rincipal’s pass word

• add a new realm or delete existing realms

Multithreaded Server

Kerberos server version 3.12 is a pre-threaded concurrent server. This feature enables the server to service multiple user requests in the KDC, thus enhancing the performance of the server. The server uses kernel space threads.

High Availability

The Kerberos server daemon (kdcd) is constan tly m o nit ore d by a parent process. If the child process dies or crashes, t he parent proc ess automatically spawns a new server daemon. This provides for high availability in the case of mission critical applic ations.

In addition, it allows fo r multi p le sec ond ary secur ity serve rs to be configured. The seconda ry secur i ty server services authentication requests, once it has been configured to authenticate and receive information propag ated from the pri mary secur ity serv e r. This enables load balancing for the primary server, with automatic incremental propagation, withou t any pe rformance degradation.

Chapter 2 65

Introduction to the Kerberos Products and GSS-API

HP Kerberos Server

The secondar y securit y serve r also pro vides re d undancy again st a singl e point of failure . The Kerberos Serv er also al lo ws admin i strators to organize realms according to the types of users or services.

Dynamic Propagation

In Kerberos server version 1.0, the enti re database had to be periodi cally dumped and propagated. This resulted in heavy network traffic and thus reduced performance .

It is important that secondary servers are configured to act as authentication servers. This allows the primary server to be available for tasks other than authenti c a tion. When a secondary server is config ur ed, both the servers must be synchronized with each other. If entries are updated on the primary server, they must be updated on the secondary server as well. The databases on the primar y and the seco n da ry ser ve rs are synchronized by a mechanism call ed ‘propagation’. The kpropd daemon running on the primary server ensures that the data is synchronized with the other secondary server.

Kerberos Server version 3.12 also supports hierarchical propagation. The primary server need not propagate the database to all the secondary servers in the realm, except for a designated secondary server. This designated seco nd ar y se rv er will th en pro p agate the d atabase to the other secondary servers available in the realm. This is possible by defining such a propagation hierarchy in the configuration files.

Scalability

This version of the Kerberos Server is hig hly scala bl e, and has been tested to support up to 2,000,000 (two million) users in the database. In addition, it supports simultaneous requests from multiple clients and ensures that these queries are not lo st eve n when the syst em is heav i l y loaded.

Windows 2000

(R)

Interoperabili ty

T o enable th e user to w ork in a mixe d platform en vironment, this ver sion of the Kerberos Server is interoperable with the Windows 2000 Server and client. A Kerberos Server in the Windows 2000

(R)

environment can

(R)

talk to th e HP-UX Ke rberos se rver, for cross-rea lm authe ntica ti o n.

Chapter 266

Introduction to the Ker beros Products and GSS-API

HP Kerberos Server

Choice of C-Tree or LDAP Databa se

Kerberos server version 3.12 allows you to use a C-Tree or an LDAP database as the backend database. By integrating the Kerberos principals with t he corresponding use rs i n the LDAP di rec tory, you store data in a common repository. For more information, see Kerberos Server V ersion 3.12 Administrator’s Guide (5991-7686) on ww w.docs.hp.com.

Auto-Configuration Tool

An automated tool named, krbsetup, has been provided to auto-configure your Kerberos Server. Using this tool, you can configure, unconfig ur e, start, a nd sto p the kdcd and the kadmind daemons. This tool is installed in the following directory:

/opt/krb5/sbin The krbsetup tool autom a tic ally c re ate s your configuratio n f iles,

krb.conf and krb.realms, kpropd.ini files and places them in the /opt/krb5 directory. The sections in the con figur atio n files is set to its

default values. If you want to customize these sections, you must manually edit the co n figur atio n files and restart the kdcd and kadmind daemons using this tool.

You can also use the krbsetup tool to configure your secondary security servers.

Chapter 2 67

Introduction to the Kerberos Products and GSS-API

Generic Security Service Application Programming Interface (GSS-API)

The GSS-API provides authentication, integrity, and confidentiality services to the call ing ap plication.

Figure 2-4 shows the libgss.sl shared library, which is independ e nt of underlying se cu ri ty m e chan isms. Th e fig ure illu strates how the underlyi ng security mecha nisms -- such as Kerberos, Sim ple Publi c Ke y Management (SPKM) -- work with respect to the GSS-API library. If you are developing applic atio n s usin g GSS- AP I s, you do not have to change the application’s code whenever the underlying security mechanism is changed. Instead, you can change the underlying security mechanism at runtime using the configuration options.

Figure 2-4 GSS-API Library

Chapter 268

With an Open System architecture, GSS-API provides portability in a heterogeneous environ ment. It contains all the GSS-APIs spec i fi ed in RFC 2743. It is implemented as a package of C-language interfaces as defined in RFC 2744, Generic Security Service API: C-bindings. The Kerberos Version 5 GSS-API Mechanism is explained in RFC 1964.

GSS-API provides secure communicat i on between two peers wit h a security context established by an exchange of tokens. As shown in Figure 2-5, GSS-API is indepe ndent of communication protocols . The GSS-API libraries on the two hosts are responsible for creating and processing th e t oken s, but the application is respon sib l e for transporting the tokens betwee n th e clien t and the serv er.

Figure 2-5 GSS-API

Operation

Introduction to the Ker beros Products and GSS-API

Generic Security Service Application Programming Interface (GSS-API)

Application Application

GSS-API Transport Transport GSS-API

Mech-1 Mech-2 Mech-1 Mech-2

It is the GSS-API caller’s responsibility to transfer GSS-API-provided data element to the peer end to parse communicate d messages, and to separate GSS-API related data elemen ts from call er-provided data. GSS-API provides either context level tokens or per-message tokens for the caller to trans por t and get the results.

Chapter 2 69

Introduction to the Kerberos Products and GSS-API

Generic Security Service Application Programming Interface (GSS-API)

GSS-API filesets are listed in Table 2-8 and Table 2-9.

Table 2-8 GSS-API Libraries

Library Availability Functionality

• Itanium



32 -

/usr/lib/hpux32/libgss.so

• PA-RISC 32 - /usr/lib/libgss.sl



• Itanium

64 -

/usr/lib/hpux64/libgss.so

• PA-RISC 64 -

/usr/lib/pa20_64/libgss.sl

Table 2-9 Additional files in the GSS-API product

File Types File Names

Header files /usr/include/gssapi/gssapi.h

/usr/include/gssapi.h (a link to /usr/include/gssapi/gssapi.h) /usr/include/gssapi_ext.h (a link to /usr/include/gssapi/gssapi_ext.h)

Configuration /etc/gss/mech

/etc/gss/qop /etc/gss/gsscred.conf

This is the front-e nd GSS-API library, which has all the GSS-APIs

Examples In the /usr/contrib/gssapi/sample directory

/usr/contrib/gssapi/sample/README - README file for the samples

manpage s The Engli sh- language m anp ages for all the

GSS-APIs are under /usr/share/man/man3.Z. (The manpages in the Japanese manpage filesets are also available in Englis h. )

Following lists the services th at the GSS- AP I inte r f ace p rovide s:

•“Cred enti a l M anag emen t S e rvic es” on page 71

Chapter 270

Introduction to the Ker beros Products and GSS-API

Generic Security Service Application Programming Interface (GSS-API)

•“Context Level Services” on page 71

•“Auth e ntication Services” on page 72

•“Confidentiality Service” on page 72

•“Support Services” on page 72

Cred ential M anagem e n t Servi ces

Credential management function calls acquire and release credentials by principals.

Applications are responsible for establishing a security mechanism based on the initial credent ials. GSS-AP I mechanisms are responsible fo r management of credentials on the local machine.

The GSS-API function calls for credential management are:

• gss_acquire_cred: Obtain credentials for use

• gss_release_cred: Release credentials after use

• gss_add_cred: Adds credent ial el eme n ts incrementally

• gss_inquire_cred: Display information about credential s

Context Level Services

Context level fun ction calls manage se curity co ntext bet we e n p eers. A context’s initiator calls gss_init_sec_context(), resulting in generalization of a token that the caller passes to the target. The target then passes the to ken to gss_accept_sec_context(). It can take multiple exchanges of tokens to establish the security context depending on the options used.

The GSS-API context level function cal ls are:

• gss_init_sec_context: Initiat e o utbound se curity co ntext

• gss_accept_sec_context: Accept inbound security context

• gss_delete_sec_context: Remove context that is no longer needed

• gss_export_sec_context: Transfer context to other process

• gss_import_sec_context: Import context from other process

• gss_inquire_context: Display informatio n abo ut con te xt

Chapter 2 71

Introduction to the Kerberos Products and GSS-API

Generic Security Service Application Programming Interface (GSS-API)

• gss_context_time: Indic ate validity time remaining in context

Authentication Services

Two sets of per-message calls provide security to the context. The gss_get_mic() and gss_verify_mic()function calls provide data origin authentication and data integrity services. The gss_wrap() and gss_unwrap() function calls support caller requested confidentiality. F o r more inf o rm a tion, see “Confidentiality Service” on page 72.

The gss_get_mic() function call generates a token. The peer that receives the app licat io n da ta along with the message toke n ve ri fi es the communication using gss_verify_mic().

Each deployment can select their own conf igurable Q uality O f Protect ion (QOP) options.

In summary, per-message calls that authenticate messages are:

• gss_get_mic: Apply integrity check, receive as token separate from

message

• gss_verify_mic: Validate integrity check token along with message.

Confidentiality Service

GSS-APIs provide confidentiality with the gss_wrap() and gss_unwrap() functions. The output of gss_wrap() is passed to the

remote peer encapsulated and optionally encrypted with the associated token. This data eleme nt is an inp ut to gss_unwrap() at the target, where it is decapsulated or optiona l ly decr ypt ed.

In summary, the APIs for confid en tiali ty se rv ice incl ud e the following:

• gss_wrap: Sign, optionally encrypt , enca ps ula t e

• gss_unwrap: Decapsulate, decrypt if needed, validate integrity

check.

Support Services

GSS-API support services include the following APIs:

• gss_display_status: Translate status codes into prin tabl e format

• gss_indicate_mechs: Indicate suppor ted mech _t yp e on local system

Chapter 272

Introduction to the Ker beros Products and GSS-API

Generic Security Service Application Programming Interface (GSS-API)

• gss_compare_name: C o mpare two n ames

• gss_display_name: Translat e name to printable form at

• gss_import_name: Convert printable name to normalized form

• gss_release_name: Free storage of name

• gss_release_buffer: Free storage of general GSS-allocated object

• gss_release_OID_set: Free storage of OID set object

• gss_create_empty_OID_set: Create empty OID set

• gss_add_OID_set_member: Add member to OID set

• gss_test_OID_set_member: Test if OID is a member of a OID set

• gss_inquire_names_for_mech: Indicate name types supported

• gss_inquire_mechs_for_name: Indicates mechanisms supporting

name type

• gss_canonicalize_name: Translate name to per mechanis m form

• gss_export_name: Externalize per-mechanism name

• gss_duplicate_name: Duplicate name object

• gss_inquire_cred_by_mech: Provides per-mechanism information

about a credential

• gss_process_context_token:

• gss_wrap_size_limit: Determines a token - size lim it for gss_wrap

in a context

Chapter 2 73

Introduction to the Kerberos Products and GSS-API

Generic Security Service Application Programming Interface (GSS-API)

Chapter 274

3 Configuring the Kerberos

Environment

This chapter descri bes t he fil es and proc edures t hat are used t o conf igure Kerberos on HP-UX.

Chapter 3 75

Configuring the Kerberos Environment

It contains the following sections:

•“Configur a tio n Files for Kerb e r os Cli en ts” on page 77

•“Configur atio n Files for GSS-A P I ” on page 82

•“Configuring the Kerberos Server” on page 85

—“Configuring Y our Microsoft Windows 2000 KDC” on page 85

•“Configuring the Kerberos Client” on page 87

•“Configuring for PAM Kerberos” on page 88

Chapter 376

Configuring the Kerberos Environment

Configuration Files for Kerberos Clients

T able3-1 lists and describes the files that you use to configu re a Kerberos server or a Kerberos c l ie nt using PAM Kerberos. Samples of al l the configuration fil es shown in the table are listed in the Append ices .

Table 3-1 Kerberos Configuration Files

Purposes

Configure Kerberos as the module for authentication and password management

Specify the defaults and the location of the Kerberos server

Associate the Kerberos services with the ports

Specify Kerberos configuration information including defaults use d to issue Kerberos tickets

Kerberos

Server

N/A N/A /etc/pam.

/opt/krb5/krb. conf

/etc/services /etc/services /etc/servi

/opt/krb5/krb. conf /opt/krb5/krb. realms

Kerberos

Client

/etc/krb5.conf /etc/krb5.

N/A N/A

PAM

Kerberos

conf

ces

Chapter 3 77

Configuring the Kerberos Environment

Configuration Fi les for Kerberos Client s

pam.conf The configuration file /etc/pam.conf controls the behavior of the PAM

modules. The pam.conf file contains a listing of system entr y se rv ices, each of which is paired with its correspo ndin g serv i ce module . When a service is requeste d , its asso ciat ed m od ule is invok e d .

Each entry has the following format:

<service_name> <module_type> <control_flag> <module_path> <options>

The followin g is a s ample ent ry for PAM Kerberos in the pam.conf file on HP-UX 11.0 and 11i v1:

The followin g is a s ample ent ry for PAM Kerberos in the pam.conf file on HP-UX 11i v2 and HP-UX 11i v3:

As mentioned in Chapter 2, “Introduction to the Kerberos Products and GSS-API,” on page 31 the PAM Kerberos module provides functionality for the authentic atio n (auth), and password management (p assword) modules.

Using eit h er the required, optional, or sufficient option, the control_flag field determines the priority and beha v io r of the modul es stacked for a module_type. For exampl e,

The PAM Kerberos opti on s are renewable=<time>, forwardable, proxiable, use_first_pass, try_first_pass, ignore, a n d debug.

For more information, see the pam. conf(4) and the pam_krb5(5) manpages.

Appendix A, “Sample pam.conf File,” on page 105 contains a sample /etc/pam.conf file.

In the HP-UX 11i ver sion, a sam ple pam.conf file for Kerberos is available as /etc/pam.krb5.

Chapter 378

Configuring the Kerberos Environment

Configuration Files for Kerberos Clients

krb5.conf The krb5.conf file specifies the defaults for the

applications, mappings of the hostnames onto Kerber os location of KDCs for Kerberos

REALMs. Application clients depend on the

configuration file /etc/krb5.conf to locate the The [libdefaults] sec tion of t he krb5.conf file spec ifies variou s

parameters for the Kerberos library. In order for the utility klist to work wi th PAM Kerbe ros, it must inclu de “ccache_type = 2.”

[libdefaults] default_realm = KDC.SUBDOMAIN.DOMAIN.COM defaul t_ tkt _enctype s = DES-CBC-CRC defaul t_ tgs _enctype s = DES-CBC-CRC ccache_type = 2

The [realms] section of the krb5.conf file specifies th e KD C server and the Kerberos admin server, kadmind that manages the adm in istr atio n interface to KDC.

The default ports used by Kerberos are port 88 for the KDC, port 749 for the kadmin service, and port 751 for kpasswd. You can optionally choose to run on other ports, as long as the ports are specified in each host’s

/etc/services, and in the krb5.conf file s.

[realms]

KDC.SUBDOMAIN.DOMAIN.COM = {

kdc = hostname.subdomain.domain.com:88 admin_s er ve r = hostname.subdomain.domain.com:749

REALM and Kerberos

REALMs, and the

REALM's KDC.

}

To configure for multiple Ke rbe r o s REALMs, list th em in the order of priority, as in the following example:

[libdefaults] default_realm = KDC1.SUBDOMAIN.DOMAIN.COM defaul t_ tkt _enctype s = DES-CBC-CRC defaul t_ tgs _enctype s = DES-CBC-CRC ccache_type = 2

[realms]

KDC1.SUBDOMAIN.DOMAIN.COM = {

kdc = hostname1.subdomain.domain.com:88 admin_s er ve r = hostname1.subdomain.domain.com:749 }

KDC2.SUBDOMAIN.DOMAIN.COM = {

kdc = hostname2.subdomain.domain.com:88 admin_s er ve r = hostname2.subdomain.domain.com:749

Chapter 3 79

Configuring the Kerberos Environment

Configuration Fi les for Kerberos Client s

}

[domain_realm]

.subdomain.domain.com = KDC1.SUBDOMAIN.DOMAIN.COM .subdomain.domain.com = KDC2.SUBDOMAIN.DOMAIN.COM

The ldapux_multidomain Option

The ldapux_multidomain option needs to be set to 1 by the administrator if the realm name of the user needs to be obtained from the W2K multidomain. Se e the ldapux (5) manpage for more inf ormation to configure W 2K m ult id omain.

The appdefaults Section

The appdefaults sectio n denotes the default val ue s used by Kerberos V5 applications.

Each tag in the [appdefaults] sect ion names a Kerberos V5 application. The value of the tag is a subsection with relations that define the default behavior s for that applic ation . For example:

[appdefaults] kinit = { forwa rda ble = true }

You can find the list of options for each applicat i on in the respec t i ve application manp ages. The application d efau lts sp ec if ied in this se ct ion are overridden by those specified in the [realms] sec tio n.

See the krb5.conf(4) manpage for more information. Appendix B, “Sample kr b5 . co n f F i le ,” on page 111 contains a sample copy

of the /etc/krb5.conf file. In the HP-UX 11i version of the operating system, a sample krb5.conf

file is available as /etc/krb5.conf.sample.

The services File

The services file contains en tr ies that allo w client ap plications to establish socket con nec t i ons to the KDC or to the application serv ers. A Kerberos client requires the following entries in the /etc/services file:

# # PAM Kerbe ro s se rvices #

Chapter 380

Configuring the Kerberos Environment

Configuration Files for Kerberos Clients

kerberos5 88/udp kdc # Kerberos authentication kerberos5 88/tcp kdc # Kerberos authentication kerberos-adm 749/tcp kerberos_adm # Kerberos admin/changepw kerberos-cpw 751/tcp kerberos_master # Kerberos changepw krb5_p ro p 754/tc p # Kerbero s slave propogation

For more information on services, see services(4).

Chapter 3 81

Configuring the Kerberos Environment

Configuration Files for GSS-API

Following configuration files are essential for proper functioning of GSS-API:

•“The mech File” on page 82

•“The /e t c/gss / q op File ” on page 83

•“The gsscred.conf File” on page 84

NOTE IPv6 support for GSS-API has been enabled only for the Itanium

binaries on HP-UX 11i v2 and HP-UX 11i v3 syst ems.

The mech File

The mechanism file, or mech file (/etc/gss/mech) specifies the underl ying securit y mechani sm. Table 3-2 lists and describe s the entries in the mech file.

Table 3-2 Entries in the mech file

Column Description

First column Contains the names of the back-end security

mechanism that support GSSAPI.

Second column

Contains the Object Identifier (OID).

Chapter 382

Table 3-2 Entries in the mech file (Continued)

Column Description

Third column Contains the name of the shared library that

implements the back-end secu rit y mec han ism for GSSAPI.

The back-end library must be placed in the

/usr/lib/gss path for 32-bit and the /usr/lib/pa20_64/gss path for 64-bit versions

on PA-RISC based systems. The back-end library has to be placed in the

/usr/lib/hpux32/gss path for 32-bit and the /usr/lib/hpux64/gss path for 64-bit versions on

Itanium based systems.

Configuring the Kerberos Environment

Configuration Files f or GSS-API

Fourth column

This is an optional field. In HP-UX 11i v3, this field lists the krb5 kernel module.

You can use the GSSAPI_MECH_CONF environment variable to change the path of the mechanism file (/etc/gss/mech) file.

Example mech File on HP-UX 11.0 and HP-UX 11i v1

# Mechanism Name Object Identifier Shared Library # krb5_mech 1.2.840.113554.1.2.2 libgssapi_krb5.sl

Example mech File on HP-UX 11i v2

# Mechanism Name Object Identifier Shared Libr ary # krb5_mech 1.2.840.113554.1.2.2 libgssapi_krb5.so

Example mech File on HP-UX 11i v3

# Mechan ism Nam e Object Identifier Share d Li br ar y Kernel Modu le # krb5_m ec h 1.2.840.113554.1.2.2 libgssapi_kr b5.so krb5

The /etc/gss/qop File

The /etc/gss/qop file contains information about the GSSAPI-based Quality Of Protection (QOP) for each underlying security mechanism.

Chapter 3 83

Configuring the Kerberos Environment

Configuration Files for GSS-API

QOP values are used with the Kerberos V5 GSS-API mechanism as input to gss_wrap() and gss_get_mic() in orde r to selec t altern ate integrity and confidentiality algorithms.

Table 3-3 shows the format of the /etc/gss/qop fi le:

Table 3-3 Format of the /etc/gss/qop file

Column Description

First column Specifies the string name of QOP. Second column Contains its QOP value (32-bit

Third column Conta ins names of the securi ty

Following is a sample /etc/gss/qop file:

# QOP string QOP Value Mechanism Name # GSS_KRB5_INTEG_C_QOP_DES_MD5 0 krb5_mech

integer).

mechanism.

The gsscred.conf File

Use the gsscred.conf file to deter mine the underly ing gsscred backend used to store the gsscred table. In HP-UX, it must contain an entry only as files.

Following is a sample /etc/gss/gsscred.conf file:

# gsscred configuration file # # Valid gsscred backend mechanisms are # files # files

Chapter 384

Configuring the Kerberos Environment

Configuring the Kerber os Server

Configuring the Kerberos Server

You can configure a Kerberos client in the same way whether your KDC server is a Kerberos server on HP-UX 11i or a Microsoft 2000 KDC server. However, for a Microsoft Windows 2000 KDC server or the Kerberos server on HP-UX 11i, the server configuration procedures are different. To configure a Microsoft Windows 2000 KDC server or Kerberos server on HP-UX 11i, you must follow the KDC Server configuration instr uc tio ns ac com p an ied with your server softwar e.

You can configure your Kerberos server with C-Tree or LDAP as the backend database. For instructions on configuring HP’s Kerberos Server, see Kerberos Server Version 3.12 Administrator’s Guide (5991-7686) available on www.docs.h p.com

Configuring Your Microsoft Windows 2000 KDC

To configure your Microsoft Windows 2000 KDC, complet e the followin g steps:

1. Use the Active Directory Management tool to creat e a new account for the UNIX host:

• From Administrators Tools, select Active Directo ry Users and

Computers.

• Select the Users folder, select Action from the top menu, click

New, then cl ic k User.

• Add the name of a UNIX host as a user by en tering the hostname

as the user name, and host/hostname as user logo n na m e.

2. Create a keytab file for the Kerberos client on Microsoft Windo ws 2000 KDC.

• Locate ktpass on Microsoft Windows 2000

• Use ktpass to create th e

the UNIX host.

C:> ktpa ss -p ri nc host/hostname@NT-DNS-REALM-NAME

-mapuser hostname -pass your-password -out hostname.keytab

where:

Chapter 3 85

KEYTAB file and set up the account for

Configuring the Kerberos Environment

Configuring the Kerberos Server

3. Follow step 3 under “Configu rin g the Kerberos Clien t” on page 87 to merge the

4. For eac h user in the Kerberos cli en t , cr ea te a Kerberos principa l in the KDC Server:

• From Administrators Tools, select the Active Directory Users

• Select the Users folder, select Action from the top menu, click

• Add the name of each UNIX user by entering the user’s first and

— hostname is the unix host DNS name. — NT-DNS-REALM-NAME is the uppercase name of the Windows

2000 domain. All domai n name s sh ould be in upper case. — your-password is the password for this principal, hostname. This step create s an acc ount in the name of

host/hostname.subdomain.domain.com.

KEYTAB file at the Kerberos client system.

and Computers.

New, then cl ic k User.

last na m e, login name, and us er’s password.

Chapter 386

Configuring the Kerberos Environment

Configur i ng the K e r b e r os Clie nt

Configuring the Kerberos Client

T o conf i gure t he Kerberos Client, complete the followi ng steps :

1. Edit the configuration files, /etc/krb5.conf and /etc/services as described in “Configuratio n Files fo r Ker b ero s Clie n ts” on page 77.

2. All Kerberos systems need a authenticate th emselves to the KDC. Create a

KEYTAB file (/etc/krb5.keytab) to

KEYTAB file for each

KDC client on your KDC Server.

3. Transfer (ftp) the

KEYTAB file from the KDC Server to the client

without overwritin g any keys install ed for other applications . For example, use /tmp/hostname.keytab as the tem por ary dest inat ion filename. Use the Kerberos utility ktutil to merge the

KEYTAB data.

The following example shows how to merge the keyt ab usi ng ktutil:

$ /usr/s bin /k tutil

ktutil : rkt /tmp/hostname.key

ktutil : lis t

You can view the KEYTAB file using klist command. For example:

# klist -k

Keytab name: FILE:/etc/krb5.keytab

KVNO Principal

----------------------------------------------------------

2 host/hostname.domain.com@KDC.SUBDOMAIN.DOMAIN.COM

4. If the UNIX users do not exist, add the equivalent KDC users as UNIX users in the UNIX /etc/passwd password file. When creating a credential file for a user, the user’s entry in the /etc/passwd is accessed for its UID number.

5. Synchronize the KDC client’s clock to the KDC server’s cloc k (within two minutes) .

Chapter 3 87

Configuring the Kerberos Environment

Configuring for P AM Kerberos

Configuring for PAM Kerberos

If you want to run PAM Kerberos, after you complete KDC client configuration from the previou s section, you must ed it the PAM configuration files for PAM Kerberos. Using the /etc/pam.krb5 file as an example, edit the /etc/pam.conf as described in “Configuration Files for Kerberos Clients” on pa g e 77.

Chapter 388

4 Trou bleshoot ing Kerberos

Troubleshooting PAM Kerberos

Troub le shooting PAM Kerberos

The PAM Kerberos module returns debug and e rro r messages that are logged using the syslog utility . Use the appropriate syslog log levels to gather more informatio n about err or scen ari os.

Debug logging is e nabled using the debug option in the /etc/pam.conf file for Kerberos PAM module, as shown in following example:

When using the deb ug option, make sure you designate a log file for debugging by modifying the /etc/syslog.conf file. For example:

*.debug<tab>/var/adm/syslog/pam.log

You can instruct the syslog daemon, /etc/syslogd, to re-read its configuration file by sendin g it a HAN GUP sign al as fol lows:

kill -HUP ‘cat /var/run/syslog.pid‘

The syslog also con tain s all the auth en tic atio n m e ssa ge s f or AR PA services such as ftp and telnet. For more i nf o rmatio n, see the syslogd(1M) manpage.

In addition, the syslog contains PAM error codes from the /usr/include/security/pam_appl.h include file. Table 4-1 provides a list of error codes with the suggested corrective actions.

Table 4-1 Error Codes and Corrective Actions

Error

No.

1 PAM_SYSTEM_ERR System error Generic System Error. See

2 PAM_BUF_ERR Memory buffer

3 PAM_PERM_DENIED No permission Check the

Chapter 4 91

PAM Error Code Meaning

error

Reason/ Corrective

Actions

syslog outputs for specific information .

Ensure that sufficient system memory is available for all processes .

permissions/ACLs.

Troubleshoot ing K er beros Related Products

T roubleshooting PAM Kerberos

Table 4-1 Error Codes and Corrective Actions (Continued)

Error

No.

4 PAM_AUTH_ERR Authentication

5 PAM_CRED_INSUFFICIENT Cannot access

6 PAM_AUTHINFO_UNAVAIL Authentication

7 PAM_USER_UNKNOWN User unknown to

8 PAM_CRED_UNAVAIL Cannot retrieve

PAM Error Code Meaning

failure

authentication data: insufficient credentials

service not available

Kerb e r os service

user c redentia l s

Reason/ Corrective

Actions

The user's password may be wrong, or the host machine identity is not present, or the credential cache may not be writable.

KDC Server is down or not reachable.

Ensure that the user is present in Kerberos KDC.

KRB5CCNAME is not set or the credential file does not exist or the user is not permitted to use the credential cache.

9 PAM_CRED_EXPIRED User credentials

expired

10 PAM_CRED_ERR Failure setting

user c redentia l s

11 PAM_ACCT_EXPIRED User ac co unt has

expired

12 PAM_AUTHTOK_ERR Authentication

token manipulation error.

Credential expired. Re-initiali ze the credentials.

Check user's permissions to write to credential cache.

Ensure that the user's accou nt i s va lid.

Check the password entered.

Chapter 492

Troubleshooting Kerberos Related Products

Troubleshooting PAM Kerberos

Table 4-1 Error Codes and Corrective Actions (Continued)

Error

No.

13 PAM_AUTHTOK_RECOVE

14 PAM_TRY_AGAIN Preliminary check

15 OTHER Errors See the syslog(1M)

PAM Error Code Meaning

Authentication

RY_ERR

information cannot be recovered.

by password service failed.

Reason/ Corrective

Actions

Old password is not correct.

Try again.

manpage for more specific information .

Chapter 4 93

Troubleshoot ing K er beros Related Products

T roubleshoot ing t he Kerberos Client Utilities

Troub le sho oti ng the Kerberos Cli ent Utili t ie s

Kerberos utilitie s, kdestroy, kinit, klist, and kpasswd can retu rn the following errors. Table 4-2 provides a list of errors with their meaning and suggested cor re ct i ve acti on s f or eac h erro r.

Table 4-2 Kerberos Client Error Co des

Error

No.

1 kdestroy: No credentials

cache file found while destroying cache. Ticket cache not destroyed!

2 kinit: Key table entry

not found while getting initial credentials.

3 kinit: Client not found

in Kerberos database while getting initial credentials.

4 klist: No credentials

cache file found

Error Meaning

The credentials cache file was not found.

The local keytab file does not conta in the ke y for the principal whose credentials are being requested.

The principal whose credentials are being requested does not exist in the Kerberos database.

No credentials cache file was found.

Reason/Corrective

Action

The credential file may have been deleted. Recreate the creden tials (TGT) using kinit.

Add the principal key entry to the keytab fi le.

Verify that there is a principal entry available for the client in the Kerberos database. If there is no entry, you must create it.

This could be due to the deletion of credentials. Recreate the creden tials using kinit or if t he credential file is different from the one indicated by klist; then export the KRB5CCNAME envir onm e nt va r iab le to specify the correct filename.

Chapter 494

Troubleshooting Kerberos Related Products

T r oubleshooting t he Kerberos Client Utilities

Table 4-2 Kerberos Client Error Co des (Contin ued)

Error

No.

5 klist: No such file or

directory while star ting keytab scan

6 klist: Bad format in

credentials cache while setting cache fla gs

7 kpasswd: New passwords

do not match - password not changed .

8 kpasswd: Unknown

creden ti a l cache type while reading principal name from credential cache.

Error Meaning

The keytab file was not found. (The default location of the keytab file is /etc/krb5.keytab.)

The credential cache file is not in the proper format.

The principal whose password you want to change does not exist in the Kerberos database.

The credential cache file is of an unknown type.

Reason/Corrective

Action

V er i fy the keytab file . If the keytab file does not exist, create the keytab file with specific entries. If the keytab file location is differ ent from the default location, then use -t option to specify the correct locat i o n.

Reinitialize the credentials by using kinit.

Create a principal entry in Kerberos database.

Credential file may be corrupted. Obtain the credentials using kinit.

9 KDC has no support for

encryption type while getting creden tials.

10 kpasswd: when kpasswd

gets the princi pa l from the cache f ile, it fin ds the principle in bad format.

You can find Kerberos V5 Library Error Codes from Appe ndix A of MIT’s Kerberos V5 System Administrator’s Guide.

Chapter 4 95

Encryption type requested f o r the se ssion key is not sup por te d .

Check user's permissions to write to credential cache.

Use the supported encryption type.

Credential file may be corrupted. Obtain the credentials using

kinit.

Troubleshoot ing K er beros Related Products

T roubleshoot ing GS S-A PI

Troub lesho oti ng GSS-API

This section provides troubleshooting tips for GSS-API.

Error Codes

It is the responsibility of the app lication programm e r to check for the major and m inor st atus val ues. F o r debug ging purp oses , HP recom mends using the gss_display_status() function call for gettin g the te xtu a l representatio n of a GSS-API status code that can be displa y ed to a user or used for logging.

Major and Minor Status Values

Major status values are generic API routine errors or calling errors defined in RFC 2744.

Minor status valu es ind ic ate mech anis m - spe cific erro rs. Mino r statu s values usually c ontain more detailed info rmation about the erro r. They are not, however, portable between GSS-API implementations.

When designing portable applicat io ns, use ma jor sta tus values for handling errors. Use mino r status values to debu g ap plications and to display error and error-recovery information to users.

Comm on GSS-API Er rors

Table 4-3 lists common GSS-API errors and their meanings:

Table 4-3 Common GSS-API Errors

Error

No.

1 GSS_S_BAD_MECH The required

2 GSS_S_BAD_NAME The name passed is

Name Meaning

mechanism is unsupported.

invalid.

Chapter 496

Troubleshooting Kerberos Related Products

Table 4-3 Common GSS-API Errors (Continued)

T roubleshooti ng GSS- API

Error

No.

3 GSS_S_BAD_NAMETYPE The name type passed

4 GSS_S_BAD_BINDINGS The channel bin d ing s

5 GSS_S_BAD_STATUS A status value is

6 GSS_S_BAD_SIG A tok en has an invalid

7 GSS_S_NO_CRED No credentials are

8 GSS_S_NO_CONTEXT No context established. 9 GSS_S_DEFECTIVE_TOKEN Invalid token. 10 GSS_S_DEFECTIVE_CREDENTIAL Invalid credential. 11 GSS_S_CREDENTIALS_EXPIRED The refere nced

12 GSS_S_CONTEXT_EXPIRED The context expired.

Name Meaning

is unsupported.

are incorrect.

invalid.

signature.

supplied.

credentials expired.

13 GSS_S_FAILURE The routine failed. 14 GSS_S_BAD_QOP The quality of

protecti on reques t e d cannot be provided.

15 GSS_S_UNAUTHORIZED The operation is

forbidden by local security policy.

Calling Error Values

Chapter 4 97

Troubleshoot ing K er beros Related Products

T roubleshoot ing GS S-A PI

Table 4-4 lists the calling error values and their meanings:

Table 4-4 Calling Errors

Error

No.

1 GSS_S_CALL_INACCESSIBLE_READ Cannot read a

2 GSS_S_CALL_INACCESSIBLE_WRITE Cannot wr ite a

3 GSS_S_BAD_STRUCTURE Cannot structure

Supplementary Bits

Table 4-5 list s the supplementary bi t va lues and their meanings:

Table 4-5 Supplementary Bits

Bit

No.

0 GSS_S_CONTINUE_NEEDED Call the routine again

Name Meaning

required input parameter.

required output parameter.

parameter correctly.

Name Meaning

to complete its function.

1 GSS_S_DUPLICATE_TOKEN The token is a

duplicate of an earlier token.

2 GSS_S_OLD_TOKEN The token’s validity

period expired; the routine ca nnot veri fy that the token is not a duplicate of an earlier token.

3 GSS_S_UNSEQ_TOKEN A later token has been

processed.

Chapter 498

Troubleshooting Kerberos Related Products

T roubleshooti ng GSS- API

Other Common Causes of Errors

Other co m m on causes o f er ro rs include the f o l lowing:

• If KRB5-Client product is not installed, you can get an error trying to use gssapi with /etc/gss/mech configured to krb5_mech.

• Improper permissions of the libgssapi_krb5.sl / libgssapi_krb5.so library.

• Specifying the full path of the backend libr ary in the /etc/gss/mech (for example, when using the 64-bit library, one should not specify the library path as /usr/lib/pa20_64/gss/libgssapi_krb5.sl, but only as libgssapi_krb5.sl ; then the 64-bit libgss.sl library will take care of linking it).

• Absence of GSS-A PI configuration files.

• In case of GSSAPI-SSP I inte r o per abilit y, the entries must use the

DES-CBC-MD5 encryption type instead of the default DES-CBC-CRC.

NOTE There is a sample GSS-A P I clie nt-se r ver ap plic atio n in the

/usr/contrib/gssapi/sample dire ctory that yo u can use for troubleshooting.

You can find additional GSS-API Error Codes from the Appendix A of MIT’s Kerberos V5 System Ad ministrator’s Guid e .

Chapter 4 99

Troubleshoot ing K er beros Related Products

T roubleshooting Using the pamkrbval Tool

Troubleshooting Using the pamkrbval Tool

This section provides tips for troubleshooting with the pamkrbval tool. When you use the pamkrbval tool for troubleshooting, you can get error messages when validating the keytab file.

NOTE Use the pamkrbval command with the -c option to troubleshoot

CIFS-related issues.

Table 4-6 lists various errors that can occur and provides methods to troubleshoot the errors.

Table 4-6 Error Messages that Appear During keytab Validation

Error/Warning Messages Reason for Message Troubleshooting

[WARNING] : host/example.com@EXAMPLE.C OM found on KDC but not found in keytab file

[FAIL] : The keytab valida ti on Fa iled

[WARNING] : Client not found in Kerberos database

[WARNING] : The keytab entry for the host service principal host/example.com@EXAMPLE.C OM is invalid

[FAIL] : The keytab valida ti on Fa iled

The keytab validation has failed because the key table entry is no t found in the client’s keytab file. There is a host principal pres ent at the KDC.

The keytab validation has faile d beca u se th ere is no keytab entry in the client’s keytab file and KDC.

Extract the k eytab e ntr y for the host principal on your system.

You must create the keytab entry on the Kerberos server and extract this keytab entry on your system.

Chapter 4100

HP HP-UX Kerberos Data Security Product Guide

Specifications and Main Features

Frequently Asked Questions

User Manual

1 Overview

Kerberos Overview

Kerberos Products and GSS-API on HP-UX

PAM Kerberos

The PAM Framewor k

The Authentication Module

The Password Module

Cred ential C a c h e

The Account Management Module

The Session Management Module

Example

The pam_user.conf File on HP-UX 11.0 and 11i v1

The pam_user.conf File on HP-UX 11i v2 and HP-UX 11i v3

The pam.conf File on HP-UX 11.0 and HP-UX 11i v1

The pam.conf File on HP-UX 11i v2 and HP-UX 11i v3

The pam_krb5 File on HP-UX 11.0 and HP-UX 11i v1

The pam_krb5 File on HP-UX 11i v2 and HP-UX 11i v3

The pamkrbval T ool

Secure Internet Services

KRB5 Clie n t Software

Libraries and Header Files

Kerberos Utilities

The kinit Utility

The kl ist Utility

The kdestroy Utility

The kpasswd Utility

The ktutil Utility

The kvno Util ity

HP Kerberos Server

Kerberos Server Versio n 3.12 F eatures

Graphical User Interface (GUI) Based Administration tool

Multithreaded Server

High Availability

Dynamic Propagation

Scalability

Choice of C-Tree or LDAP Databa se

Auto-Configuration Tool

Generic Security Service Application Programming Interface (GSS-API)

Cred ential M anagem e n t Servi ces

Context Level Services

Authentication Services

Confidentiality Service

Support Services

Configuration Files for Kerberos Clients

The services File

Configuration Files for GSS-API

The mech File

The /etc/gss/qop File

The gsscred.conf File

Configuring the Kerber os Server

Configuring Your Microsoft Windows 2000 KDC

Configur i ng the K e r b e r os Clie nt

Configuring for P AM Kerberos

Troubleshooting PAM Kerberos

T roubleshoot ing t he Kerberos Client Utilities

T roubleshoot ing GS S-A PI

Error Codes

Major and Minor Status Values

Comm on GSS-API Er rors

Other Common Causes of Errors

T roubleshooting Using the pamkrbval Tool