Security for Dummies

Security for Dummies



Project Title: OGSA-DAI

Document Title: Security for Dummies

Document Identifier: SECURITY-FOR-DUMMIES-v1.2

Editor: Mike Jackson

Approval List: NCH

Document History:

Personnel Date Summary Version
MJJ 29/10/03 Revised in light of comments from Jarek Gawor 1.2
MJJ 16/10/03 Revised in light of comments from Charles Bacon 1.1
NCH 17/9/03 Approved for external distribution 1.0
MJJ 25/07/03 0.1


SECURITY-FOR-DUMMIES-v1.2 2

Contents

1 Introduction 4
2 Security Concepts 5
2.1 Public Key Cryptography 5
2.1.1 Securing Private Keys 5
2.2 Signing 5
2.3 Certificates 5

2.3.1 Certificate Authorities 6
2.4 Mutual Authentication 6
2.5 Confidential Communication 6
2.6 Delegation, Single Sign-On and Proxies 7
2.7 Grid Map Files 7
3 Globus Toolkit 3 Grid Security Infrastructure (GSI) 8
3.1 Why? 8
3.2 Java Authentication and Authorization Service (JAAS) 8
3.3 Message Level Security 8
3.3.1 GSI Secure Conversation 9
3.3.2 GSI XML Signature 9
3.4 Server-side Security 9
3.4.1 WS-Security Handler 10
3.4.2 Security Policy Handler 10
3.4.3 Authorization Handler 10
3.4.4 Service 11
3.4.5 Reply to Client 11
3.5 Client-side Security 11
3.5.1 Outbound Client-side Security Handlers 12
3.5.2 Inbound Client-side Handler (WS-Security Client Handler) 12
4 General Configuration 13
4.1 Set GLOBUS_LOCATION 13
4.2 Install JAAS 13
4.3 Configure Tomcat 13
4.4 Note a xalan.jar Issue 13
5 Globus Toolkit Installation 14
5.1 Install Globus Toolkit 3 and Configure Environment Variables 14
5.2 Configure GSI 14
5.3 The /etc/grid-security directory 15
5.3.1 Creating /etc/grid-security 15

5.3.2 Contents of /etc/grid-security 16
5.4 /etc/grid-security/grid-mapfile 17
5.5 Get a Host Certificate 18
5.5.1 Get a Host Certificate from the Globus CA 18
6 Configuring Server-side Security 20
6.1 Security Handlers 20
6.2 GSI Authentication Service 20
6.3 Operation Providers and Notification 20
6.4 Service Credentials 21
6.5 Service Authorization Settings 21
6.6 Security Deployment Descriptors 22
6.6.1 Specifying Security Deployment Descriptor Locations 22
6.6.2 Security Deployment Descriptor Content 22
6.6.3 Default Security Deployment Descriptor 25
7 Client Development 26
7.1 Security Handlers 26
7.2 The <USER>/.globus Directory 26
7.2.1 Keys and Certificates from Multiple CAs 27
7.3 Get a User Certificate 27
7.3.1 Get a User Certificate from the Globus CA 27
7.3.2 Keys and Certificates from Multiple CAs 30


SECURITY-FOR-DUMMIES-v1.2 3

7.4 Configure Java CoG 30
7.4.1 Java CoG Default Values 30
7.4.2 Providing a cog.properties File 31
7.5 Generate a Client Proxy 31
7.5.1 Generate a Proxy Using the grid-proxy-init Script 32

7.5.2 Generate a Proxy Using the org.globus.tools.ProxyInit Program 33
7.5.3 Generate a Proxy Using the org.globus.tools.proxy.GridProxyInit Program 33
7.6 Write Your Client 34
7.6.1 Required Classes 34
7.6.2 Configure the Service Stub Prior to Each Operation Call 34
7.7 Run Your Client 36
7.8 Common Problems 37
7.8.1 Class Missing when Running Client 37
7.8.2 Class Missing when Running Client 37
7.8.3 Server-side SEC05 Error 37
7.8.4 Server-side SEC06 Error 37
7.8.5 Authentication Error 37
7.8.6 FileNotFound Error 37
8 Other Useful Information 39
8.1 GT3 Scripts 39
8.2 Useful Credential Manipulation 39
8.2.1 To get default (user proxy) credentials 39
8.2.2 To save credentials 39
8.2.3 To load user proxy from a file 39
8.2.4 To get remaining lifetime of the credential 39
8.2.5 To get the identity of the credential (in Globus format) 40
8.3 Useful Service Operations 40
8.3.1 Setting service owner with caller's delegated credential 40
8.3.2 Getting caller's identity 40
8.3.3 Getting the JAAS invocation Subject 40
8.3.4 Credential Refresh 41
8.4 GSI Notifications 41
8.4.1 Sink 41
8.4.2 Source 41
8.5 Limitations 42

8.5.1 ServiceLocator/GridLocator Reuse 42
8.5.2 Persistent Services Activation Run-As Identity 42
8.6 Credential Acquisition Rules 42
9 Getting Certificates from the UK Grid Support Centre 43
10 Sources / Further Information 44
10.1 Overview 44
10.2 Grid Security Infrastructure, Certificates and Proxies 44
10.3 General Globus Toolkit 3 Security Documentation 45
10.4 Java CoG Kit 45
10.5 JAAS 45


SECURITY-FOR-DUMMIES-v1.2 4

1 Introduction

This document provides an introduction to using message level security, in particular GSI Secure
Conversation message level security, with the Globus Toolkit 3. It is based upon and replicates
documentation listed in section 10 but combines this into a (hopefully) more coherent and useful form.

Transport level security is not described since this is to be deprecated in future releases.

I did not have root access so some of the issues relating to configuring GSI and installing
host certificates is conjecture (!).




SECURITY-FOR-DUMMIES-v1.2 5

2 Security Concepts

This section provides a brief overview of general security concepts for reference or refreshment.

2.1 Public Key Cryptography

• Keys are mathematical numbers.
• Public key is known to the world.
• Private key is known only to you.

Sender: EncryptedMessage = SenderPrivateKey(OriginalMessage)
Receiver: OriginalMessage = SenderPublicKey(EncryptedMessage)

OR

Sender: EncryptedMessage = ReceiverPublicKey(OriginalMessage)
Receiver: OriginalMessage = ReceiverPrivateKey(EncryptedMessage)
2.1.1 Securing Private Keys

• Private keys are stored in files.
• Encrypted via a password/pass phrase.
• User must enter the pass phrase to access the private key.

2.2 Signing

• Assures recipient that message has not been interfered with since it left the sender.
• The sender and recipient use an agreed publicly-available algorithm for both signing messages
and validating the signature of messages.
• Sender:
o Hash = PublicAlgorithm(Message).

o EncryptedHash = SenderPrivateKey(Hash).
o SignedMessage + EncryptedHash + Message.
o Sends SignedMessage.
• Recipient:
o Receives SignedMessage.
o Extracts Message from SignedMessage.
o RequiredHash = PublicAlgorithm(Message)
o Extracts EncryptedHash from SignedMessage.
o Hash = SenderPublicKey(EncryptedHash)
o If RequiredHash = Hash then the SignedMessage was not interfered with.

2.3 Certificates

• Identifies users and services – vital for identification and authentication.
• Includes:
o Subject name: identity of user or service represented AKA distinguished name.
o Public key of subject.
o Identity of Certificate Authority (CA) signing certificate.
o Digital signature of CA.


SECURITY-FOR-DUMMIES-v1.2 6

o Details on the public algorithm the CA used to sign the certificate.
• X509 format – defined by the IETF (Internet Engineering Task Force).
o Binds a public key to a name.
o Can be shared with other public key-based software e.g. Netscape, Internet Explorer.
• Host certificates:
o AKA server certificates.
o These can be needed for a server to perform secure operations. In GT3 these are

needed for GridFTP and GRAM services, for example.
2.3.1 Certificate Authorities

• AKA trusted party / issuer.
• Provide certificates for users.
• To get a certificate:
o User’s public + private key pair used to create a Certificate Request.
o Certificate Request and public key forwarded to CA.
o CA creates and signs certificate and returns to user.
• CA certificate provides a guarantees that the public key belongs to subject and that the CA
guarantees the identity of the subject.
• The identity of the subject is established by the CA via non-cryptographic means.

2.4 Mutual Authentication

• Uses certificates.
• Requires co-operating agents to trust each other’s CAs.
o Need copies of CA certificates – including CA’s public keys.
o Need to trust that certificates actually do belong to the CAs.
• SSL Protocol (AKA Transport Layer Security (TLS)).
• Example:
o A connects to B.
o A gives their certificate to B.
o B validates A’s certificate by checking the CA’s digital signature to ensure that:
 A’s CA signed certificate.
 A’s certificate not tampered with.
o B can now trust the CA that signed A’s certificate.
o B validates A:
 B sends a random message to A.
 A encrypts message using their private key.

 A sends the encrypted message to B.
 B decrypts the encrypted message using A’s public key as stored in A’s
certificate.
 If the result is the original random message send by B to A then A is indeed
who they claim to be.
o A then validates B via validation of B’s CA, their certificate and the use of a random
message as above.

2.5 Confidential Communication

• Communication integrity: eavesdroppers can read communications but not modify them.
Signing messages supports this.
• Communication privacy: eavesdroppers cannot read communications. Encrypting messages
supports this.



SECURITY-FOR-DUMMIES-v1.2 7

2.6 Delegation, Single Sign-On and Proxies

• Extension of SSL protocol.
• Designed to avoid re-entry of pass phrases for accessing private keys in situations where a
large number of signed or encrypted messages are being generated.
• User creates a proxy which has a new:
o Proxy private key.
o Proxy certificate:
 New proxy public key.
 User identity + indication that it is a proxy.
 Signature of the user – certificate is signed by user and not a CA.

 A life time.
• Proxy private key is stored in file:
o Access permissions are used to restrict access.
o There is no pass phrase providing additional security however.
• Mutual authentication example:
o A creates a proxy Ap.
o Ap connects to B.
o Ap gives a proxy certificate to B.
o Ap also gives A’s certificate to B.
o B uses A’s certificate to validate the signature on Ap’s certificate – did A sign Ap’s
certificate?
o B uses A’s certificate – in particular information on the CA that signed A’s certificate
– to validate A.





2.7 Grid Map Files

• Grid Map Files are used for resource authorization.
• Map Grid identities – subject name on a user’s X509 security certificate to a local identity
associated with a user account.




SECURITY-FOR-DUMMIES-v1.2 8

3 Globus Toolkit 3 Grid Security Infrastructure (GSI)

Globus Toolkit 3 Java Grid Security Infrastructure (GSI) is based on the implementation of GSI in the
Java CoG Kit. GT3 provides message level security based on WS-Security, XML Encryption and XML
Signature standards.

The Java GSI implementation is an implementation of the Java Generic Security Services API (GSS-
API). It supports the GSS-API extensions and the new proxy certificate format specifications as
defined by the Global Grid Forum.

GT3’s security library features include:

• Secure communication and authentication.
• Mutual authentication.
• Single sign-on including credential delegation and proxies:
o Authentication.
o Message protection.
• PKI – Public Key Infrastructure.
• Instance-based security – each service instance can have its own credentials, gridmap file, etc.
• Declarative security – the security behavior of a service can be specified in a security
deployment descriptor.
• Programmatic security – security API are provided to service developers for fine-grained
security control.
• Java Authentication and Authorization Service (JAAS) integration – permits services to be
independent from underlying authentication technologies.

GSI’s default configuration is non-confidential communications – only authentication is supported.
However, private keys shared between communicating parties for encryption and decryption can be
configured if desired. Communication integrity is supported by default however communication
privacy can also be configured.

3.1 Why?

• Need for secure communication (authenticated and perhaps confidential) between elements of
a computational Grid.
• Need to support security across organizational boundaries, thus prohibiting a centrally-
managed security system.
• Need to support "single sign-on" for users of the Grid, including delegation of credentials for
computations that involve multiple resources and/or sites.

3.2 Java Authentication and Authorization Service (JAAS)

The Java Authentication and Authorization Service (JAAS) is a standard extension to Java

1.3 and is a
part of Java 1.4. JAAS provides access control based on where code originates from, who signed the
code, and who runs the code.

3.3 Message Level Security

• Based on the following standards
o WS-Security
o XML Encryption


SECURITY-FOR-DUMMIES-v1.2 9

o XML Signature
• Security is applied entirely at the SOAP level.
3.3.1 GSI Secure Conversation

• AKA GSI Secure Session.
• Session-based security model.
• Uses a GSI Secure Conversation Service to establish a context between two parties, for
example a client and a service.
• Context is established before any data is communicated.
• This context provides a shared secret key.
• Parties uses context to sign, verify, encrypt, and decrypt messages.
• Clients can then securely communicate with service and vice versa.
• Trust between parties is established at the outset of communications between the parties.
Subsequent messages can then be transmitted and received with less overhead since trust does
not have to be re-established on a message-by-message basis.
3.3.2 GSI XML Signature

• AKA GSI Secure Message.
• Per-message-based security model.
• Messages are signed with X509 certificates.
• Greater computational overhead than GSI Secure Conversation.

3.4 Server-side Security

• Message flow and processing that occurs for a security-enabled service.
• Security is specified via deployment descriptors.
• JAX-RPC handlers that are involved in security-related message processing on a server.

SecConv
Service
Authorization
Handler
Service
Security Policy

Handler
JAAS
Sec Conv
Msg Handler
WS-Security
Handler
Client
Server Hosting Environmen
t
Figure 1:Server-side security – GSI Secure Conversation



SECURITY-FOR-DUMMIES-v1.2 10



Authorization
Handler
Service
Security Policy
Handler
JAAS
XML Sig
Handler
WS-Security
Handler
Client
Server Hosting Environment
Figure 2: Server-side security – GSI XML Signature

The SOAP engine invokes several security-related handlers as follows:
3.4.1 WS-Security Handler

• Searches the message for any WS-Security headers.
• Extracts any keying material:
o An X509 certificate and associated certificate chain.
o OR
o Reference to a previously established secure conversation session.
• Checks any signatures and/or decrypts elements in the SOAP body.
• Populates a peer Java Authentication and Authorization Service (JAAS) subject object –
which represents some user – with principals and any associated keying material whose
veracity was ascertained during the signature checking or decryption step.
3.4.2 Security Policy Handler

• Checks that incoming messages fulfill any security requirements the service has.
• Requirements are specified, on a per-operation basis, as part of a security descriptor during
deployment.
• Identifies the correct JAAS subject to associate with the current thread of execution.
o Chooses between:
 Peer subject populated by the WS-Security handler.
 Subject associated with the hosting environment.
 Subject associated with the service itself.
 Association is done by the pivot handler, a non-security handler that handles
the details of delivering the message the service.
3.4.3 Authorization Handler

• Verifies that the principal established by the WS-Security handler is authorized to invoke the
service.
• Type of authorization that is performed is specified as part of a deployment descriptor.
• Three authorization modes:

o none
o self – which authorizes incoming messages whose associated principal/identity
coincides with the service owner.


SECURITY-FOR-DUMMIES-v1.2 11

o gridmap – which looks up authorized principal/identities in a file-based access
control list.
3.4.4 Service

• Service processes client request.
3.4.5 Reply to Client

• GSI Secure Conversation message handler deals with encrypting and signing messages using
a previously established security context.
• GSI XML Signature handler deals with messages without an established contact by signing
the messages using X509 certificates.
• Operations that are actually performed depend on the message properties associated with the
message by the inbound handlers, i.e. outbound messages will have the same security
attributes as inbound messages.
o But a service has the option of modifying the message properties if so desired.

3.5 Client-side Security

WS-Sec
Client
Handler
SecConv
Message
Handler
Sec Conv
Service
Handler
Service
SecConv
Service

Server Hosting
Environment
Client
Client Hosting Environment

Figure 3: Client-side security – GSI Secure Conversation


• Client-side security configuration is handled by the application.
• Client has to explicitly pass information to the client side handlers on what type of security to
use.
o Also true for the case of services acting as clients.
• Client can use either the GSI Secure Conversation or GSI Secure Message security
approaches.
• Sets a per-message property that is processed by the client-side security handlers.

SECURITY-FOR-DUMMIES-v1.2 12
















WS-Sec
Client
Handler
Sec Msg
Handler
Client
Client Hosting Environment

Server Hosting
Environmen
t

Service


Figure 4: Client-side security – GSI XML Signature
3.5.1 Outbound Client-side Security Handlers

GSI Secure Conversation – Secure Conversation Service Handler

• Only operational for GSI Secure Conversation.
• Establishes a security session with a secure conversation service collocated with the service to
which the client aims to communicate.
• When the client sends the initial message to the service with a property indicating that session
based security is required this handler intercepts the message and establishes a security
session.
• Authorizes the service by comparing the service’s principal/subject obtained during session
establishment with a value provided by the client application.
• Once the session has been established the handler passes on the original message.

GSI Secure Conversation – Secure Conversation Message Handler

• Only operational for GSI Secure Conversation.
• Signs and/or encrypts messages using an security session established by the first handler.

GSI XML Signature – GSI Secure Message Handler

• Only operational only for GSI XML Signature.
• Handles signing of messages in GSI Secure Message operation.
3.5.2 Inbound Client-side Handler (WS-Security Client Handler)

• Verifies and decrypts any signed and/or encrypted incoming messages.
• In the case of GSI XML Signature operation it will also authorize the remote side in a similar
fashion to the outbound secure conversation service handler.



SECURITY-FOR-DUMMIES-v1.2 13

4 General Configuration

These are general configuration actions which should be taken prior to installation or use of GT3.

4.1 Set GLOBUS_LOCATION

Prior to using any GT3 facilities you should set a GLOBUS_LOCATION environment variable to
point to your GT3 installation:

% export GLOBUS_LOCATION=<SOME-LOCATION>/GT3

4.2 Install JAAS

If you are using Java 1.3.1 then you need to install JAAS.

Download JAAS 1.0_01 Class Libraries from

Extract the jaas-1_0_01.zip file into a temporary directory.

Copy the jaas1_0_01/lib/jaas.jar file to the <GLOBUS_LOCATION>/lib directory.

Copy the jaas1_0_01/lib/jaas.jar file to the <TOMCAT>/commons/lib.

4.3 Configure Tomcat

If using Java 1.4.x with Tomcat 4.1.24 then copy $GLOBUS_LOCATION/lib/xalan.jar to
<TOMCAT>/common/endorsed.

4.4 Note a xalan.jar Issue

An older version of Xalan was shipped with Java 1.4.0/1.4.1 than the version the GT3 security libraries
require. The $GLOBUS_LOCATION/lib/xalan.jar file should be used.



SECURITY-FOR-DUMMIES-v1.2 14

5 Globus Toolkit Installation

This section describes information relating to configuring GT3 for security and for generating and
installing host private keys and certificates.

5.1 Install Globus Toolkit 3 and Configure Environment Variables

The GT3 Core provides OGSI services. However the full GT3 distribution provides useful facilities for
service configuration, private key generation, certificate generation and proxy creation. In this section
a full GT3 installation is assumed.

Prior to using any GT3 facilities you should run a GT3 script to configure important environment
variables.

% source $GLOBUS_LOCATION/etc/globus-user-env.sh

5.2 Configure GSI

If you do not have a pre-installed GT3 including an /etc/grid-security directory (see section 5.3) on
your host then you will have to configure the GT3 GSI.

If you have root access then run:

# GLOBUS_LOCATION/setup/globus/setup-gsi

If you do not have root access then run:

% GLOBUS_LOCATION/setup/globus/setup-gsi -nonroot

The output will be as follows:

Running grid-security-config

G S I : C O N F I G U R A T I O N P R O C E D U R E

Before you use the Grid Security Infrastructure, you should first

define the DN (distinguished name) that should be used for your
organization's X509 certificates. If you do not define a DN,
a default DN will be assigned to you.

This script will ask some questions about site specific
information. This information is used to configure
the Grid Security Infrastructure for your site.

For some questions, a default response is given in [].
Pressing RETURN in response to such a question will enable the
default.
This script will overwrite the file

<CERT-DIR>/certificates/grid-security.conf.42864e48

Do you wish to continue (y/n) [y] :

where <CERT-DIR> will be either /etc/grid-security if you are running as root or
$GLOBUS_LOCATION/share otherwise.



SECURITY-FOR-DUMMIES-v1.2 15

Enter y:

Do you wish to continue (y/n) [y] : y

=====================================================================

(1) Base DN for user certificates
[ ou=localdomain, o=Globus, o=Grid ]
(2) Base DN for host certificates
[ o=Globus, o=Grid ]

=====================================================================

(q) save, configure the GSI and Quit
(c) Cancel (exit without saving or configuring)
(h) Help
=====================================================================

Enter q:

q
Installing Globus CA certificate into trusted CA certificate
directory
Installing Globus CA signing policy into trusted CA certificate
directory
setup-gsi: Complete

This process creates a directory /etc/grid-security/certificates – if you ran setup-gsi as root – or
$GLOBUS_LOCATION/share/certificates – otherwise – with five files:

• 42864e48.0
• 42864e48.signing_policy
• grid-security.conf.42864e48
• globus-user-ssl.conf.42864e48
• globus-host-ssl.conf.42864e48

You should now create an /etc/grid-security directory as described in the next section. If you do not
have root access you should get your system administrator to do this for you providing them with the
files within $GLOBUS_LOCATION/share/certificates.

The next section tells you where to place these five files within /etc/grid-security.

5.3 The /etc/grid-security directory

The directory /etc/grid-security is a directory used to hold configuration information – trusted CAs and
host certificates – and private information used by the GSI libraries.

It should be on local disk and not, for example, NFS-mounted.

It and it's contents should not be writable by any untrusted users (generally this means only by root)
though all its contents – with the exception of the host’s private key – can be world-readable.
5.3.1 Creating /etc/grid-security

If you have run setup-gsi with root access this directory will have been created automatically as part of
the setup-gsi program so you can skip this section.



SECURITY-FOR-DUMMIES-v1.2 16

If you did not have root access then you should ask your administrator to create the directory /etc/grid-
security and make it world-readable:

# mkdir /etc/grid-security
# chmod 0755 /etc/grid-security

In /etc/grid-security make a certificates directory.

# mkdir /etc/grid-security/certificates

This can either be a copy of or a symbolic link to $GLOBUS_LOCATION/share/certificates

# ln -s ${GLOBUS_LOCATION}/share/certificates /etc/grid-
security/certificates

This directory should be non-writable by anyone except trusted users and should be world readable.
5.3.2 Contents of /etc/grid-security

The following files or directories are normally placed in /etc/grid-security.

certificates/

• This directory contains the X509 certificates of all CAs trusted by this system.
• For a user to authenticate with GSI to any GSI-based service on this system, the certificate of
the CA that signed the user’s certificate must be in this directory.
• All the contents of this directory are used by both GSI-based clients and GSI-based services.
• All the contents of this directory should be world-readable.
• This directory can be a symbolic link to $GLOBUS_LOCATION/share/certificates.
certificates/<CA-HASH>.0

• These files contain CA certificates.
• The file names are based on a hash of the CA identity for quick location.
• The Globus <CA-HASH> is 42864e48.
• The GSC <CA-HASH> is 01621954.
certificates/<CA-HASH>.0.signing_policy

• These files contains the policies describing whose certificates each CA can sign.
• See />.
certificates/<CA-HASH>.0.r

• These files contain Certificate Revocation Lists (CRLs).
certificates/grid-security.conf.42864e48
certificates/globus-user-ssl.conf.42864e48
certificates/globus-host-ssl.conf.42864e48

• Files used to generate certificate requests.
• See />.


SECURITY-FOR-DUMMIES-v1.2 17


grid-mapfile

• This file contains authorization information and information to map Grid identities (e.g. X509
subject names) to local system identities (e.g. Unix user IDs).
• See section 5.4.
• The file can have UNIX permission 600 – world-readable only.
grid-security.conf
globus-user-ssl.conf
globus-host-ssl.conf

• Symbolic links to:
o certificates/grid-security.conf.42864e48
o certificates/globus-user-ssl.conf.42864e48
o certificates/globus-host-ssl.conf.42864e48

• See />.

hostkey.pem

• This file contains the host’s private key used for doing mutual authentication with connecting
clients.
• This file should form a matched pair with hostcert.pem.
• The file should have UNIX permission 400 – owner-readable only.
• See section 5.5.
hostcert.pem

• This file contains the X509 certificate for the host used for doing mutual authentication with
connecting clients.
• This file should form a matched pair with hostkey.pem.
• The file should have UNIX permission 444 – world-readable only.
• See section 5.5.

5.4 /etc/grid-security/grid-mapfile

For users to be authorized to use GSI-enable services they need to be entered into the GSI access
control list, called the grid-mapfile.

It's purpose is to map a GSI Credential to a local user's login name.

The administrator on the site can map the holder of any GSI credential to any local user name.

It is up to the administrator to verify that the GSI Identity is owned by and matches the local username.

The grid-mapfile file is plain text file, containing a quoted GSI Credential Name (the subject of an
X509 certificate) and an unquoted local user name.

Each subject name in the grid-mapfile must be listed only once. However, multiple identities may map
to a shared local name. It is up to the GSI administrator to ensure that the grid-mapfile entries do not
violate any site security policies.

An example of a grid-mapfile entry is:


SECURITY-FOR-DUMMIES-v1.2 18


"/C=US/O=Globus/O=State University/CN=Joe User" juser

grid-mapfile-add-user can be used by an administrator to add entries to the grid-mapfile. For example
the following command would add a user to the mapfile:

grid-mapfile-add-entry -dn "/C=US/O=Globus/O=State University/CN=Joe
User" -ln juser

You must type in the distinguished name exactly as it appears in the user’s certificate. Not doing so
will result in an authentication failure. You can get this information directly from the user’s certificate
by using the following command:

grid-cert-info subject file <certificate file>

For example, the command

grid-cert-info subject file <USER>/.globus/usercert.pem

will print the certificate subject for the X509 certificate in the file <USER>/.globus/usercert.pem. This

is the default location for a user's certificate file (see section 7.2).

5.5 Get a Host Certificate

You will require a certificate and private key for your host. These will be stored within the /etc/grid-
security directory. You should check this to see if these have been installed already. If you have an
/etc/grid-security directory and it has contents which include the following:

• hostcert.pem
• hostkey.pem

Then you already have a host certificate so you can skip this section.

See section 8 for information on getting host certificates from the GSC.
5.5.1 Get a Host Certificate from the Globus CA

Run grid-cert-request to generate the private key and the certificate request.

% grid-cert-request -host <HOSTNAME> -dir <DIR>

• <HOSTNAME> should be the fully-qualified of the host for which you are requesting a
certificate.
• <DIR> is destination of the key and certificate. You should have write permission on this
directory.
o If you have root permission then this argument can be omitted. grid-cert-request will
use /etc/grid-security by default as the destination.

For example to generate a private key and a host certificate for modi4.ncsa.uiuc.edu you could type
(assuming you have root permission):

# grid-cert-request -host modi4.ncsa.uiuc.edu

Example output is as follows:



SECURITY-FOR-DUMMIES-v1.2 19

A private key and a certificate request have been generated with the
subject:

/C=US/O=Globus/OU=The National Computational Science
Alliance/CN=host/modi4.ncsa.uiuc.edu



The private key is stored in <dir>/hostkey.pem
The request is stored in <dir>/hostcert_request.pem

Please e-mail the certificate request to the Globus CA:

cat <DIR>/hostcert_request.pem | mail

Your certificate will be mailed to you within two working days.

Where <DIR> is the second argument you provided to grid-cert-dir.

Three files will be created in <DIR> with correct permissions for certificate and key files:

• hostcert.pem – placeholder for Globus CA certificate

o World readable, owner writable.
• hostkey.pem – private key for host.
o Owner readable.
• hostcert_request.pem – request for Globus CA certificate.
o World readable, owner writable.

Mail – as yourself, not root – hostcert_request.pem file to the Globus CA at Make sure
that the account you e-mail from can also receive mail.

Your response from the Globus CA should be placed in the <DIR>/hostcert.pem file.

If you have root permission you should copy your <DIR>/hostcert.pem and <DIR>/hostkey/pem files
into /etc/grid-security. If you do not have root access you should get your administrator to do this for
you.

You should ensure that you – or your administrator – configure file access permissions of these files in
/etc/grid-security as mentioned above.

# chmod 400 /etc/grid-security/hostkey.pem
# chmod 444 /etc/grid-security/hostcert.pem

grid-cert-request Options

The command

% grid-cert-request -help

provides a list of options to the grid-cert-request program.

SECURITY-FOR-DUMMIES-v1.2 20

6 Configuring Server-side Security

6.1 Security Handlers

Message level security is handled by a few client- and server- side Axis/JAX-RPC handlers. These
handlers must be properly installed in order for the message level security to work. The
<TOMCAT>/webapps/ogsa/WEB-INF/server-config.wsdd file must define the following request and
response flows:

<requestFlow>
<handler type="URLMapper"/>
<handler type="HandleResolverHandler"/>
<handler
type="java:org.globus.ogsa.impl.security.authentication.Authenticatio
nServiceHandler"/>
<handler type="java:org.globus.ogsa.utils.JAXRPCHandler">
<parameter name="className"
value="org.globus.ogsa.impl.security.authentication.wssec.WSSecurityH
andler"/>
</handler>
<handler
type="java:org.globus.ogsa.impl.security.authentication.SecurityPolic
yHandler"/>
<handler
type="java:org.globus.ogsa.impl.security.authorization.AuthorizationH

andler"/>
<! optional: only needed for credential refresh functionality >
<handler
type="java:org.globus.ogsa.impl.security.authentication.CredentialRef
reshHandler"/>
<! additional handlers >
</requestFlow>

<responseFlow>
<! additional handlers >
<handler type="java:org.globus.ogsa.utils.JAXRPCHandler">
<parameter name="className"
value="org.globus.ogsa.impl.security.authentication.X509SignHandler"/
>
</handler>
<handler type="java:org.globus.ogsa.utils.JAXRPCHandler">
<parameter name="className"
value="org.globus.ogsa.impl.security.authentication.GSSHandler"/>
</handler>
</responseFlow>

Note that these server-side handlers are installed by default.

6.2 GSI Authentication Service

The gsi/AuthenticationService service must also be deployed. This service is installed by default.

6.3 Operation Providers and Notification

If a service provides a NotificationSource port type it should specify the

org.globus.ogsa.impl.security.authentication.SecureNotificationSourceProvider instead of the


SECURITY-FOR-DUMMIES-v1.2 21

org.globus.ogsa.impl.ogsi.NotificationSourceProvider. Service credentials might not be propagated
correctly if the regular NotificationSourceProvider is used. All other operation providers remain the
same.

6.4 Service Credentials

Each service can also be configured with a separate set of credentials. This is done by adding either

<parameter name="serviceProxy" value="<proxy file>"/>

or

<parameter name="serviceCert" value="<certificate file>"/>
<parameter name="serviceKey" value="<unencrypted key file>"/>

to the <service> block of the service in the server-config.wsdd file.

Global credentials (container credentials) can also be specified in the <globalConfiguration> block in
similar way by adding "containerProxy" parameter or "containerCert" and "containerKey" parameters.
The “containerProxy” parameter is configured automatically if you have GT3 GRIM (Grid Resource
Identity Mapper) or MMJFS (Master Managed Job Factory Service) services installed.

A service will first check for the credential parameters in the <service> section. If no credential
parameters are defined in the <service> section, the service will check the <globalConfiguration> block
next. If no credentials are defined in either places, the service will rely on the underlying security

library to acquire credentials (the security library will try to load a proxy certificate of the user that is
running the container). If the credential files change during the runtime they will be automatically
reloaded.

A separate set of trusted CA certificates can also be configured for each service. This is done by adding

<parameter name="trustedCertificates"
value="<CA certificate locations>"/>

to the <service> block of the service in the server-config.wsdd file Global CA certificates can also be
specified in the <globalConfiguration> block in the same way. The <CA certificate locations> can be a
comma separated list of individual certificate files or directories contains certificates (files ending with
.<digit> extension) A service will first check for the trustedCertificates parameter in the <service>
section. If no such parameter is defined in the <service> section, the service will check the
<globalConfiguration> block next. If no trusted certificates are defined in either places, the service will
rely on the underlying security library to find the certificates.

The "trustedCertificates" parameter is currently ignored.

6.5 Service Authorization Settings

Each service can be configured with a separate authorization mechanism. Currently, there are three
supported authorization mechanisms: none, self, and gridmap. The authorization mechanism of a
service is configured by setting an "authorization" parameter in the service deployment descriptor, for
example:

<parameter name="authorization" value="self"/>

Authorization checks are only performed for authenticated clients. All authorized clients have the same
access to all methods of a service.

SECURITY-FOR-DUMMIES-v1.2 22


• If the "authorization" parameter is set to "none" no authorization is performed.
• If the "authorization" parameter is set to "self" only the clients with the same identity as the
service are allowed to access the service (if the service does not have its own identity, the
system identity is used instead for authorization).
• If the "authorization" parameter is set to "gridmap", gridmap file authorization is performed.
o A "gridmap" property pointing to the gridmap file location must be either specified in
the <service> section or in the <globalConfiguration> section of the deployment
descriptor.
o If the "authorization" parameter is not defined in the service deployment descriptor,
and the "gridmap" property is not defined in the <service> or <globalConfiguration>
section of the deployment descriptor, self authorization is performed.
o If the "authorization" parameter is not defined in the service deployment descriptor,
but the "gridmap" property is defined in the <service> or <globalConfiguration>
section of the deployment descriptor, gridmap authorization is performed.
o For services configured to perform gridmap file authorization, the gridmap file can
be updated dynamically using the SecurityManager API.
o Also, if the gridmap file changes during the runtime it will be automatically reloaded.

6.6 Security Deployment Descriptors

A separate security deployment descriptor – loaded when a service is activated – can be used to provide
more fine-grained control over security properties of a service such as authentication mechanisms
required to access a service and/or run-as identities of the service.

Security deployment descriptors are not reloaded if they change during runtime.

6.6.1 Specifying Security Deployment Descriptor Locations

The securityConfig parameter is used for persistent services. For example:

<parameter name="securityConfig" value="my-security-config.xml"/>

The instance-securityConfig parameter is used for transient services created by factory services. For
example:

<parameter name="instance-securityConfig"
value="my-security-config.xml"/>

The location of the security deployment descriptor must be within the
<TOMCAT>/webapps/ogsa/WEB-INF/classes directory or within a JAR file within the
<TOMCAT>/webapps/ogsa/WEB-INF/lib directory i.e. accessible from the CLASSPATH.
6.6.2 Security Deployment Descriptor Content

The security deployment descriptor is contained within a <securityConfig
xmlns=""> element.

Method-based security properties (for some properties) can be contained within <method
name="<QUALIFIED-NAME-OF-METHOD>"> elements.

For example, the following security deployment descriptor specifies that:

• All methods are to be run with the security identity of the caller
• GSI Secure Conversation authentication is to be applied on all method calls.


SECURITY-FOR-DUMMIES-v1.2 23

<securityConfig xmlns="">
<run-as>
<caller-identity/>
</run-as>
<auth-method>
<gsi/>
</auth-method>
</securityConfig>

The following security deployment descriptor specifies that:

• All methods are to be run with the security identity of the caller
• GSI Secure Conversation authentication is to be applied on a call to the sayHelloWorld
method.
o The namespace and local name specified should match the specification of the
associated operation as cited in the GWSDL document for the service.
• No authentication is to be applied on calls to all other methods.

<securityConfig xmlns="">
<run-as>
<caller-identity/>
</run-as>
<method name="hi:sayHelloWorld"
xmlns:hi="
<auth-method>
<gsi/>
</auth-method>
</method>

<auth-method>
<none/>
</auth-method>
</securityConfig>

In more detail the available options are as follows.

Authentication Methods

The <auth-method> element is used to configure the authentication mechanisms required to access a
service. The authentication methods can be configured on per method basis. Currently, the following
authentication methods are supported:

• <none/> – indicates none authentication method
• <pkey/> – indicates public key authentication method
• <gsi/> – the default which indicates GSI Secure Conversation authentication method:
o The <protection-level> sub element can be used to specify a specific protection level
that must be applied to the message:
 <integrity/> – indicates that the message must be integrity protected
(signed). If no <protection-level> is specified then this is the default.
 <privacy/> – indicates that the message must be privacy protected
(encrypted).

Multiple authentication methods can be specified under the <auth-method> element (except the
<none/> method). As long as one of the authentication methods is performed, the access to the service
is allowed. The <none/> method cannot be specified with any other authentication method.

Note that the org.globus.ogsa.impl.security.authentication.SecurityPolicyHandler handler must be
installed properly in order for this to work (see section 6.1). If the security deployment descriptor is not
specified, authentication method enforcement is not performed.

SECURITY-FOR-DUMMIES-v1.2 24


An example is as follows:

<securityConfig xmlns="">
<method name="ogsi:findServiceData"
xmlns:ogsi="
<auth-method>
<none/>
</auth-method>
</method>
<method name="ogsi:destroy"
xmlns:ogsi="
<auth-method>
<pkey/>
<gsi>
<protection-level>
<integrity/>
</protection-level>
</gsi>
</auth-method>
</method>
<! default auth-method for any other method >
<auth-method>
<gsi/>
</auth-method>
</securityConfig>

In the above example, the findServiceData() operation does not require any authentication while the
destroy() operation requires either public key or GSI Secure Conversation with integrity protection
authentication. Any other operation must be authenticated with GSI secure conversation with either
privacy or integrity protection.

RunAs Modes

The <run-as> element is used to configure the run-as identity under which the service method will be
executed. The run-as identity can be configured on per-method basis. Currently, the following run-as
identities are supported:

• <caller-identity/> – the service method will be run with the security identity of the client
• <system-identity/> – the service method will be run with security identity of the container
• <service-identity/> – the default in which the service method will be run with the security
identity of the service itself (if the service has one, otherwise the container identity will be
used)

Note that the org.globus.ogsa.impl.security.authentication.SecurityPolicyHandler handler must be
installed properly in order for this to work (see section 6.1). If the security deployment descriptor is not
specified, then the run-as identity is not set.

An example is as follows:

<securityConfig xmlns="">
<method name="ogsi:findServiceData"
xmlns:ogsi="
<run-as>
<caller-identity/>
</run-as>

</method>
<method name="ogsi:destroy"
xmlns:ogsi="
<run-as>
<system-identity/>


SECURITY-FOR-DUMMIES-v1.2 25

</run-as>
</method>
<! default run-as for any other method >
<run-as>
<service-identity/>
</run-as>
</securityConfig>

In the above example, the findServiceData() operation will be executed with caller's identity while the
destroy() call will be run with system identity. Any other operation will be run with the service identity
(if the service has one set).
6.6.3 Default Security Deployment Descriptor

The security deployment descriptor in org/globus/ogsa/impl/security/descriptor/gsi-security-config.xml
provides is a generic descriptor that can be used to secure a service with GSI secure conversation
authentication mechanism.