Steps for authorizing resources for NSS

Before network security services can be provided, authorization to several resources must be defined to the external security manager.

Before you begin

RACF® is used as the external security manager in the following examples. RACF commands shown in these examples are also provided in the EZARACF member of the SEZAINST data set. In these examples, it is assumed that the NSS server is running under the user ID NSSD.

Procedure

Perform the following steps to authorize access to the appropriate resources:

  1. Define and authorize the NSSD user ID. The NSS server is a z/OS® UNIX application that you can start from the z/OS UNIX shell or from an MVS™ started procedure. Before starting the NSS server, you must define the NSSD user ID to the external security manager with UID 0. If you start the NSS server from an MVS started procedure, the NSSD user ID must also be authorized to the STARTED class.

    Issue the following commands:

    ADDUSER  NSSD     DFLTGRP(OMVSGRP) NOPASSWORD OMVS(UID(0)  HOME('/'))
RDEFINE  STARTED  NSSD.*            STDATA(USER(NSSD))
SETROPTS RACLIST(STARTED) REFRESH
SETROPTS GENERIC(STARTED) REFRESH
  2. Permit the NSSD user ID to SYS1.PARMLIB. The NSS server uses the TCP/IP component trace (CTRACE) to perform service-level tracing. The default NSS server component trace parmlib member is stored in SYS1.PARMLIB. The NSSD user ID must be permitted to access SYS1.PARMLIB.

    Issue the following command:

    PERMIT   SYS1.PARMLIB  ID(NSSD) ACCESS(READ)
  3. Define key ring controls. Certificates used by NSS clients are stored on a SAF key ring. The RACDCERT command is used to manage a RACF key ring. The IRR.DIGTCERT FACILITY class resource is used to control access to the RACDCERT command. If these controls do not already exist, they must be defined as follows:
    RDEFINE FACILITY IRR.DIGTCERT.ADD UACC(NONE)
RDEFINE FACILITY IRR.DIGTCERT.ADDRING UACC(NONE)
RDEFINE FACILITY IRR.DIGTCERT.CONNECT UACC(NONE)
RDEFINE FACILITY IRR.DIGTCERT.GENCERT UACC(NONE)
RDEFINE FACILITY IRR.DIGTCERT.GENREQ UACC(NONE)

    For details about these controls, see z/OS Security Server RACF Command Language Reference.

  4. Give the user ID of the administrator that will manage the NSS server's key ring appropriate access to manage the key ring. Issue the following commands:
    PERMIT IRR.DIGTCERT.ADD CLASS(FACILITY) ID(userid) ACC(CONTROL)
PERMIT IRR.DIGTCERT.ADDRING CLASS(FACILITY) ID(userid) ACC(UPDATE)
PERMIT IRR.DIGTCERT.CONNECT CLASS(FACILITY) ID(userid) ACC(CONTROL)
PERMIT IRR.DIGTCERT.GENCERT CLASS(FACILITY) ID(userid) ACC(CONTROL)
PERMIT IRR.DIGTCERT.GENREQ CLASS(FACILITY) ID(userid) ACC(CONTROL)
PERMIT IRR.DIGTCERT.LIST CLASS(FACILITY) ID(userid) ACC(CONTROL)
PERMIT IRR.DIGTCERT.LISTRING CLASS(FACILITY) ID(userid) ACC(UPDATE)
    If you will issue the RACDCERT command using the NSSD user ID, READ authority to the IRR.DIGTCERT.ADD, IRR.DIGTCERT.ADDRING, IRR.DIGTCERT.GENREQ, and IRR.DIGTCERT.LISTRING resources is sufficient. Authority requirements for the other resources remain the same. If you will issue the RACDCERT command using a user ID other than the NSSD user ID, you must provide appropriate access for the NSSD user ID to its own key ring as follows: 
    PERMIT IRR.DIGTCERT.LIST CLASS(FACILITY) ID(NSSD) ACC(READ)
PERMIT IRR.DIGTCERT.LISTRING CLASS(FACILITY) ID(NSSD) ACC(READ)

    After you permit access to the various IRR.DIGTCERT resources, update the FACILITY class as follows:

    SETROPTS RACLIST(FACILITY) REFRESH
  5. Optionally, permit the NSS server to the BPX.DAEMON FACILITY class profile. For information concerning the use of the BPX.DAEMON profile, see BPX.DAEMON FACILITY class profile.

    If you decide to use this profile, permit the NSS server user ID to this profile using the following command, where the userid value is the user ID under which the NSS server runs:

    PERMIT BPX.DAEMON CLASS(FACILITY) ID(userid) ACCESS(READ)
  6. Enable the secured signon function. The NSS server supports the use of PassTickets. To use this support, the secured signon function must be enabled, and at least one profile must be created for the NSS server.

    The secured signon function of RACF is enabled by activating the PTKTDATA class as follows:

    SETROPTS CLASSACT(PTKTDATA) 
SETROPTS RACLIST(PTKTDATA) REFRESH

    Profiles in the PTKTDATA class control the use of the secured signon function by an application. A secured signon application key is associated with each profile. This key is stored in the external security manager's database. When RACF is used as the external security manager, this key is stored in a masked or encrypted state.

    With RACF, you can use a secured signon application key that is controlled at the following levels:

    • All users who need access to the application
    • A specific RACF group of users who need access to the application
    • A specific RACF user, when connected to a specific RACF group
    • A specific RACF user

    The application name NSSD must be used when defining the secured signon keys for the NSS server. The following example shows a RACF command that you can issue to assign a secured signon key that can be used by all NSS clients that are authenticating to the NSS server:

    RDEFINE PTKTDATA NSSD SSIGNON(KEYMASKED(E001193519561977)) UACC(NONE)

    For specific information about enabling the secured signon function and defining profiles to be used by the single signon function, see z/OS Security Server RACF Security Administrator's Guide.

  7. Define SERVAUTH profiles to authorize NSS clients to network security services. These profiles are on the same system as the NSS server. Many of these profiles are constructed using the name of an NSS client. NSS clients must authenticate to the NSS server using a valid user ID and password, or a valid user ID and PassTicket. This user ID must be given access to the SERVAUTH profiles created on behalf of the NSS client.

    For details about how to define the IKE daemon as an NSS client, see Using network security services.

    Perform the following steps to authorize NSS clients:

    1. Define a SAF user ID representing an NSS client to the external security manager.

      An NSS client must present valid credentials to the NSS server before accessing any services. Valid credentials include a user ID and password, or a user ID and PassTicket if secured signon is enabled. A SAF user ID representing an NSS client must be defined to the external security manager.

      Issue the following command:

      ADDUSER  userid   DFLTGRP(OMVSGRP)  OMVS(UID(x))
      Rules:
      • Multiple NSS clients can use a single user ID. However, each NSS client must have a unique client name.
      • A SAF user ID must have an OMVS segment with either AUTOID or a specific UID(x) defined for the NSSD to authenticate it as an NSS client.
      Guideline: Because SAF user IDs are used to authorize a client to the NSS services, avoid sharing a single user ID across NSS disciplines.
    2. If you choose to define an NSSD profile in the APPL class with UACC(NONE), issue the following command to authorize each SAF user ID to the NSSD application: 
      PERMIT NSSD CLASS(APPL) ID(userid) ACC(READ)
SETROPTS RACLIST(APPL) REFRESH
    3. Authorize the user ID associated with an NSS client for each of the network security services it will use.

      To authorize an NSS client to use a network security service, you must create a SERVAUTH resource profile for that service that represents the NSS client. The user ID associated with the NSS client must be permitted READ access to that profile. Table 1 shows the name of the SERVAUTH profile for each service, where sysname is the name of the z/OS system running the NSS server and clientname is the name by which the NSS server knows the NSS client.

      Table 1. SERVAUTH profile names for NSS
      Service SERVAUTH profile name
      IPSec certificate service EZB.NSS.sysname.clientname.IPSEC.CERT
      IPSec remote management service EZB.NSS.sysname.clientname.IPSEC.NETMGMT
      XMLAppliance certificate service EZB.NSS.sysname.clientname.XMLAPPLIANCE.CERT
      XMLAppliance private key service EZB.NSS.sysname.clientname.XMLAPPLIANCE.PRIVKEY
      XMLAppliance SAF access service EZB.NSS.sysname.clientname.XMLAPPLIANCE.SAFACCESS

      You can authorize the NSS client to a SERVAUTH profile using the following commands:

      RDEFINE SERVAUTH profile_name  UACC(NONE)
PERMIT  profile_name (SERVAUTH) ID(nssclient) ACCESS(READ)
SETROPTS GENERIC(SERVAUTH) REFRESH
SETROPTS RACLIST(SERVAUTH) REFRESH
      Tip: You can use a wildcard in the profiles to reduce the number of profile entries that must be defined.
    4. Create a SERVAUTH resource profile for each NSS IPSec client certificate added to the NSS server's key ring, and give each NSS IPSec client's user ID access to the profiles created for its own certificates.

      The name of such a resource profile is EZB.NSSCERT.sysname.mappedlabelname.HOST, where sysname is the name of the z/OS system running the NSS server and mappedlabelname is the mapped name of the certificate's label in the key ring. For details about determining a certificate label's mapped name, see NSS server certificate label naming considerations.

      This can be accomplished with the following commands:

      RDEFINE SERVAUTH EZB.NSSCERT.sysname.mappedlabelname.HOST UACC(NONE)
PERMIT EZB.NSSCERT.sysname.mappedlabelname.HOST CLASS(SERVAUTH) ID(userid) ACCESS(READ)
SETROPTS GENERIC(SERVAUTH) REFRESH
SETROPTS RACLIST(SERVAUTH) REFRESH
    5. Create a SERVAUTH resource profile for each certificate authority (CA) certificate that could be used by an NSS IPSec client, and give the NSS client's user ID access to the profiles.

      When the digital signature mode of authentication is used, an NSS IPSec client can provide a remote security endpoint with information about certificate authorities that are trusted by the NSS client. The remote security endpoint should use this information as a hint to decide which of its certificates to use when creating its signature.

      By default, an NSS IPSec client sends a remote security endpoint information about all the certificate authorities that the NSS IPSec client is authorized to advertise. This can result in an NSS IPSec client sending a large amount of data to a remote security endpoint. Use the CaLabel parameter on the RemoteSecurityEndpoint statement to reduce the amount of data sent to specific remote security endpoints. For details about the RemoteSecurityEndpoint statement, see z/OS Communications Server: IP Configuration Reference.

      A SERVAUTH resource profile is used to authorize NSS IPSec clients to use a CA. A SERVAUTH resource profile must be created for each CA certificate that could be used by an NSS IPSec client. The name of such a resource profile is EZB.NSSCERT.sysname.mappedlabelname.CERTAUTH, where sysname is the name of the z/OS system running the NSS server and mappedlabelname is the mapped name of the certificate's label in the key ring. For details about determining a certificate label's mapped name, see NSS server certificate label naming considerations. An NSS IPSec client's user ID must be given access to this profile before it can use the corresponding CA certificate.

      This can be accomplished with the following commands:

      RDEFINE  SERVAUTH EZB.NSSCERT.sysname.mappedlabelname.CERTAUTH UACC(NONE)
PERMIT   EZB.NSSCERT.sysname.mappedlabelname.CERTAUTH CLASS(SERVAUTH) ID(userid) ACCESS(READ)
SETROPTS GENERIC(SERVAUTH) REFRESH
SETROPTS RACLIST(SERVAUTH) REFRESH
    6. Create a SERVAUTH resource profile for each certificate that an NSS XMLAppliance client could retrieve and give the user ID of the NSS XMLAppliance client access to the appropriate profiles.

      In contrast to the IPSec discipline, the XMLAppliance discipline does not distinguish between host, site, or certificate authority certificates. For any given certificate request, the NSS server first checks the EZB.NSSCERT.sysname.mappedlabelname.HOST profile. If that check fails, the server then checks the EZB.NSSCERT.sysname.mappedlabelname.CERTAUTH profile. If the NSS XMLAppliance client has read access to either profile, the server permits access to the certificate resource. It is up to the NSS server administrator to allow or deny access to each certificate, and it is up to the XML appliance administrator to determine how each certificate should be used. The user ID of an NSS XMLAppliance client must be given access to one of these profiles before it can use the corresponding certificate. For examples on how to define the required profiles and permit access, see step 7.d and step 7.e, under Steps for authorizing resources for NSS. For details about determining the mapped name of a certificate label, see NSS server certificate label naming considerations.

    7. Create a SERVAUTH resource profile for the private key of each certificate to which an NSS XMLAppliance client requires access and give the user ID of the NSS XMLAppliance client access to the profiles.

      Use the SERVAUTH resource profile to authorize NSS XMLAppliance clients to retrieve the private key from a certificate, and to locally perform any RSA operations that are based on the private key or to make ICSF calls requesting RSA operations on System z® for ICSF-protected keys. You must create a SERVAUTH resource profile for each private key against which the XMLAppliance client needs to perform operations. The name of such a resource profile is EZB.NSSCERT.sysname.mappedlabelname.PRIVKEY, where sysname is the name of the z/OS system running the NSS server and mappedlabelname is the mapped name of the certificate label in the key ring. Ensure that the user ID of an NSS XMLAppliance client has appropriate access to this profile so that it can retrieve the private key or perform any RSA operations that are based on the private key. This can be accomplished with the following commands:

      RDEFINE  SERVAUTH EZB.NSSCERT.sysname.mappedlabelname.PRIVKEY UACC(NONE)
PERMIT   EZB.NSSCERT.sysname.mappedlabelname.PRIVKEY CLASS(SERVAUTH) ID(userid) ACCESS(READ)
SETROPTS GENERIC(SERVAUTH) REFRESH
SETROPTS RACLIST(SERVAUTH) REFRESH

      For details about determining the mapped name of a certificate label, see NSS server certificate label naming considerations.

    8. Create the following SERVAUTH profiles to enable users to remotely monitor (IPSEC.DISPLAY) or manage (IPSEC.CONTROL) NSS clients:
      • EZB.NETMGMT.sysname.clientname.IPSEC.DISPLAY
      • EZB.NETMGMT.sysname.clientname.IPSEC.CONTROL

      For more information, see the information about the -z option of the ipsec command in NSS client authorization example. For more details about managing network security, see z/OS Communications Server: IP System Administrator's Commands. For details about the network management interface, see z/OS Communications Server: IP Programmer's Guide and Reference.

  8. If you are using the NSS XMLAppliance private key service with ICSF-protected private keys, authorize the NSS server to the Integrated Cryptographic Service Facility (ICSF). ICSF is required when using the RSA operations in the XMLAppliance private key service. The XMLAppliance private key service uses ICSF in the following ways:
    • Encrypting signature data for the XMLAppliance private key service RSA signature generation message flow.
    • Decrypting data for the XMLAppliance private key service RSA decryption message flow.

    ICSF provides cryptography support through various cryptographic hardware features. The cryptographic features that are available to your applications depend on your processor or server model. For information about which features are available on your hardware, see the information about callable service support by hardware configuration in z/OS Cryptographic Services ICSF Overview. For details about configuring ICSF, see z/OS Cryptographic Services ICSF Administrator's Guide.

    When using a cryptographic coprocessor, the callable ICSF service names that are used by the XMLAppliance certificate service are as follows:

    • CSNDDSG
    • CSNDPKD
    Requirement: If you plan to use the RSA operations within the XMLAppliance private key service, the NSS server must be permitted to access the ICSF cryptographic services (CSFSERV). Use the following commands to define the appropriate profiles in the CSFSERV class, give the NSS server access to the profiles, activate the CSFSERV class, and refresh the RACF profiles in storage: 
    RDEFINE service-name CLASS(CSFSERV) UACC(NONE)
PERMIT service-name CLASS(CSFSERV) ID(server-name) ACCESS(READ)
SETROPTS CLASSACT(CSFSERV) 
SETROPTS RACLIST(CSFSERV) REFRESH
  9. If XMLAppliance clients using the SAF access service are using certificates for access checks, enable RACF certificate name filtering. The NSS XMLAppliance SAF access service can use RACF certificate name filtering to map an X.500 distinguished name to a RACF ID when performing SAF access checks. The DIGTNMAP class must be active to perform certificate name filtering. Activate the DIGTNMAP class with the following commands:
    SETOPS CLASSACT(DIGTNMAP) 
SETROPTS RACLIST(DIGTNMAP) REFRESH

    Create a certificate name filter for each mapping of an X.500 distinguished name to a RACF ID using the following commands:

    RACDCERT ID(userid) MAP SDNFILTER('x500dn') 
SETROPTS RACLIST(DIGTNMAP) REFRESH

    For specific details on enabling RACF certificate name filtering, see z/OS Security Server RACF Security Administrator's Guide.

  10. The NSSD uses ICSF callable services for ECDSA digital signature support. The services it uses are the PKCS11 private key sign service and the PKCS11 public key verify service. You can control access to these services with RACF, using the CSFSERV general resource class, and the CSF1PKS and CSF1PKV profiles. If the CSFSERV class is defined, and the CSF1PKS and CSF1PKV profiles are defined, grant the NSSD user ID read access to the defined profiles using the following commands: 
    PERMIT CSF1PKS CLASS(CSFSERV) ID(NSSD) ACCESS(READ)
PERMIT CSF1PKV CLASS(CSFSERV) ID(NSSD) ACCESS(READ)
SETROPTS RACLIST(CSFSERV) REFRESH

    See z/OS Cryptographic Services ICSF Administrator's Guide for more information about the CSFSERV general resource.

Parent topic: Preparing to provide network security services