__login, __login__applid, __certificate (BPX1SEC, BPX4SEC) — Provides an interface to the security product
Function
The BPX1SEC/BPX4SEC callable service provides an interface to the security product to allow the calling process to obtain security-related services.
No special authority is required to use this service to register or unregister a certificate that has the current identity of the calling process.
The C functions _login and _certificate result in a call to this service.
Requirements
| Operation | Environment |
|---|---|
| Authorization: | Supervisor state or problem state, any PSW key |
| Dispatchable unit mode: | Task |
| Cross memory mode: | PASN = HASN |
| AMODE (BPX1SEC): | 31-bit |
| AMODE (BPX4SEC): | 64-bit |
| ASC mode: | Primary mode |
| Interrupt status: | Enabled for interrupts |
| Locks: | Unlocked |
| Control parameters: | All parameters must be addressable by the caller and in the primary address space. |
Format
|
AMODE 64 callers use BPX4SEC with the same parameters.
Parameters
- Function_code
- Supplied parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword that specifies a numeric value identifying the function that is to be performed. The following Function_code constants are defined by the BPXYCONS macro. See BPXYCONS — Constants used by services.
Constant Description SECURITY_CREATE# Create the security environment for the caller's process. SECURITY_CERTREG# Register the passed certificate with the user ID that is associated with the current security environment. SECURITY_CERTDEREG# Deregister the passed certificate from the user ID that is associated with the current security environment. SECURITY_CERTAUTH# Authenticate the passed certificate for the caller. The certificate must have been registered. - Identity_type
- Supplied parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword that identifies the format of the Identity parameter and the Pass parameter. Constants are defined by the BPXYCONS macro. See BPXYCONS — Constants used by services.Constant Description SECURITY_USERID# The user identity is in the format of a 1-to 8-character user ID that is passed as input. - Identity_length
- Supplied parameter for SECURITY_USERID#
- Type:
- Integer
- Length:
- Fullword
The name of a fullword that contains the length of the Identity parameter. The specified length must be consistent with the allowable Identity types: for SECURITY_USERID#, the length is 1-to-8 characters.
- Identity
- Supplied parameter for SECURITY_USERID#
- Type:
- Character string
- Character set:
- For SECURITY_USERID#, the identity is a USERID that follows the XPG4 naming convention portable character set. This includes upper and lower-case letters (A-Z, a-z), numerics (0–9), period (.), dash (-), and underbar (_).
- Length:
- Specified by the Identity_length parameter
The name of a field that contains the user identity in the specified format.
- Pass_length
- Supplied parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword that contains the length of the Pass parameter. This length must be between 1 and 8 characters for a password or PassTicket or between 9 and 100 characters for a password phrase. A length of zero indicates that the Pass parameter is to be ignored.
- Pass
- Supplied parameter
- Type:
- Character string
- Character set:
- No restriction
- Length:
- Specified by the Pass_length parameter
The name of a field, of length Pass_length, that contains, left-justified, the password, PassTicket or password phrase that is to be verified.
- Certificate_length
- Supplied parameter
- Type:
- Integer
- Length:
- Fullword
For SECURITY_CERTREG#, SECURITY_CERTDEREG#, and SECURITY_CERTAUTH#, the name of a fullword that contains the length of a certificate structure as defined by the Certificate parameter. This parameter is ignored for all other function codes.
- Certificate
- Supplied parameter
- Type:
- Character string
- Character set:
- No restriction
- Length:
- Variable
For SECURITY_CERTREG#, SECURITY_CERTDEREG#, and SECURITY_CERTAUTH#, the name of an area that consists of a digital certificate. See the information on the initACEE callable service in z/OS Security Server RACF Callable Services for a description of the formats for a digital certificate. This parameter is ignored for all other function codes.
- Option_flags
- Supplied parameter
- Type:
- Structure
- Length:
- Fullword
The name of a fullword binary field that contains the BPX1SEC/BPX4SEC options. If no options are required, specify the name of a fullword field that contains 0. No options are currently defined.
- Return_value
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the BPX1SEC/BPX4SEC service returns 0 if the request is successful, or -1 if it is not successful. For SECURITY_CERTAUTH#, this field returns an address to read-only storage that contains the 8-character user ID. If the request is not successful, the service returns -1.
- Return_code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the BPX1SEC/BPX4SEC service stores the return code. The BPX1SEC/BPX4SEC service returns Return_code only if Return_value is -1. For a complete list of possible return code values, see z/OS UNIX System Services Messages and Codes. The BPX1SEC/BPX4SEC service can return one of the following values in the Return_code parameter:
Return_Code Explanation EINVAL A parameter is not valid, or a certificate was not specified, or no security product is installed. The following reason codes can accompany the return code: JrFunctionCode, JrIdentityType, JrBadOptions, JrUserNameLenError, JrPasswordLenError, JrNewPasswordLenError, JrCertificate, JrNoSecurityProduct. EPERM The operation is not permitted, or the calling task has a task level ACEE that was not created by a prior call to this service. The following reason codes can accompany the return code: JrNotServerAuthorized, JrSecurityEnv, JrEnvDirty, JrMultiThreaded, JrUnexpectedError. ESRCH The USERID cannot become an OMVS process. The following reason codes can accompany the return code: JrOK, JrNoCertforUser. EMVSSAF2ERR An error occurred in the security product, or there was a parameter list error on a call to initACEE. The following reason codes can accompany the return code: JrCertInvalid, JrSafInternal, JrSafGroupNoMVS, JrSafNoGid, JrSafNoUid, JrSafUserNoMVS, JrSafParmListErr, JrCertInvalid, JrCertDoesNotMeetReq, JrCertAlreadyDefined, JrUnexpectedError, JrOK, X' '0814' '. ENOSYS The function is not implemented. The following reason codes can accompany the return code: JrNoSecurityProduct, JrNoInitACEE. EACCES Permission is denied. The following reason codes can accompany the return code: JrOK, JrNoResourceAccess. EMVSEXPIRE The password for the resource that was specified has expired. The following reason code can accompany the return code: JrOK. EMVSPASSWORD The new password that was specified is not valid. The following reason code can accompany the return code: JrOK. - Reason_code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which this service stores the reason code. The BPX1SEC/BPX4SEC service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. See z/OS UNIX System Services Messages and Codes for the reason codes.
Table 1 shows the Return_code and Reason_code values that are returned when the BPX1SEC/BPX4SEC service is called to register or unregister a certificate and initACEE has a return code of 8.Table 1. BPX1SEC/BPX4SEC return values for certificate registration or deregistration with initACEE return code 8 initACEE reason code BPX1SEC/BPX4SEC return code BPX1SEC/BPX4SEC reason code Explanation 4 EMVSSAF2ERR JrSafParmListErr There was a parameter list error. 8 EMVSSAF2ERR JrSafInternal There was an internal RACF® error. 12 EMVSSAF2ERR JrSafInternal RACF recovery environment could not be established. 16 EACCES JrNoResourceAccess The user is not authorized. 20 EMVSSAF2ERR JrCertDoesNotMeetReq The certificate does not meet RACF requirements. 24 EMVSSAF2ERR JrCertAlreadyDefined The certificate is already defined for another user. 36 EMVSSAF2ERR JrCertInvalid The certificate is not valid.
Usage notes
- Table 2 shows the BPX1SEC/BPX4SEC parameters
that are used with each function.
Table 2. BPX1SEC/BPX4SEC parameter usage based on function requested Parameter Login as a new user Register a certificate Unregister a certificate Authenticate a certificate Function_Code _CREATE# _CERTREG# _CERTDEREG# _CERTAUTH# Identity_Type SECURITY_USERID# Not applicable Not applicable Not applicable Identity_Length Input Not applicable Not applicable Not applicable Pass_Length Input (optional) Not applicable Not applicable Not applicable Pass Input (optional) Not applicable Not applicable Not applicable Cert_Length Not applicable Input Input Input Certificate Not applicable Input Input Input Option_Byte Not applicable Not applicable Not applicable Not applicable Return_value Output Output Output Output (address) Return_code Output Output Output Output Reason_code Output Output Output Output For the SECURITY_CERTREG# and SECURITY_CERTDEREG# functions, the certificate is passed in the Certificate parameter, and not the Identity parameter. The certificate does not necessarily define the identity of the caller; these functions could be called with a user ID and password.
For the SECURITY_CERTAUTH# function, the certificate is passed in the Certificate parameter. The certificate contains the identity of the caller, and can be used instead of a user ID/password combination.
- When this service is called for function code SECURITY_CERTAUTH#:
- A certificate is passed for authentication. It is possible that
the USERID associated with the certificate was valid at the time the
certificate was created, but is no longer valid when this call is
made. For example, the USERID could have been revoked or its profile
could have been changed so that it no longer has any z/OS® UNIX System
Services information associated with it. However, the original ACEE
is still valid and can be cached. Because of this there are different
return/reason codes that are issued for revoked USERIDs and USERIDs
with no OMVS segment, depending on the ACEE that is used during this
call. That is:
If the USERID has no OMVS segment, when using a cached ACEE you will receive ESRCH and JrOK. When there is no cached ACEE, you will receive EMVSSAF2ERR/JrSafUserNoMVS
If the USERID has been revoked, when using a cached ACEE you will receive ESRCH/JrOK. When there is no cached ACEE you will receive EMVSSAF2ERR/JrOK.
If the USERID has an OMVS segment, but no UID defined, when using a cached ACEE you will receive EMVSSAF2ERR/X' '0814' '. When there is no cached ACEE you will receive EMVSSAF2ERR/JrSafNoUid.
- A certificate is passed for authentication. It is possible that
the USERID associated with the certificate was valid at the time the
certificate was created, but is no longer valid when this call is
made. For example, the USERID could have been revoked or its profile
could have been changed so that it no longer has any z/OS® UNIX System
Services information associated with it. However, the original ACEE
is still valid and can be cached. Because of this there are different
return/reason codes that are issued for revoked USERIDs and USERIDs
with no OMVS segment, depending on the ACEE that is used during this
call. That is:
- Mixed case passwords and PassTickets are supported when the installed
security product (such as RACF)
supports mixed case; otherwise, passwords and PassTickets are folded
to uppercase. Non-graphic characters are always folded to blanks.
The contents of the password phrase string are passed unchanged to the installed security product.
Although z/OS UNIX System Services supports password phrases that are 9-100 characters in length, your installation or the installed security product can have additional rules for password phrase lengths. Ask your security administrator or system programmer if any additional rules apply.
- The BPX1SEC/BPX4SEC service allows a process to assume an identity that is different from that of the address space. It is assumed that the process will either terminate or select a new user ID, but not try to revert back to the original address space identity. The user could issue the BPX1SEC/BPX4SEC request again with the original user identity; however, at this point the user has its own security environment, at the task level, rather than the address space level.
- For SECURITY_CREATE# and SECURITY_CERTAUTH#, if BPX.DAEMON is defined, then the address space must be program-controlled.
- When calling the BPX1SEC/BPX4SEC service with function code SECURITY_CREATE#,
the caller can change identities under any of the following conditions:
- The caller specifies the password for the requested identity.
- If no password is specified and the BPX.DAEMON profile is not defined in the FACILITY class, the caller must be a superuser. If no password is specified and the caller has read access to the BPX.SRV.userid SURROGAT profile, where userid is the user ID specified in the User_name parameter.
- If no password is specified and the BPX.DAEMON profile is defined in the FACILITY class, the caller must be permitted to that profile with at least READ access and must be a superuser.
- Only a single-threaded process can call the BPX1SEC/BPX4SEC service with function code SECURITY_CREATE#.
- The purpose of the BPX1SEC/BPX4SEC register/unregister service is to provide a way for the caller to associate or disassociate its user ID with a certificate. No new security environment is created, and no authentication of the user is done.
- The ability to call the BPX1SEC/BPX4SEC service to register or unregister a certificate with a user ID is not a privileged operation. The user does not need any special authority above that required by RACF to register or unregister certificates. The caller does not, for example, have to be a DAEMON or a SUPERUSER. RACF requires that the caller have access to the RACDCERT FACILITY class definitions (IRR.DIGTCERT.ADD and IRR.DIGTCERT.DELETE) for registration and deregistration.
- The BPX1SEC/BPX4SEC authenticate service provides the caller with a way to authenticate a security environment using a certificate. The certificate must already be registered. If the certificate is not registered, an error is returned.
- The __login__applid() function is equivalent to __login() with
the added feature that __login__applid() allows an application identifier
(applid) to be supplied. The applid is used to verify the user's authority
to access the application. When a PassTicket is specified, the applid
is also used in conjunction with the USERID to verify the PassTicket.
If an application is not using the __login__applid() function but
still wants to pass an applid to this service, the application can
set the applid value in the BPXYTHLI. Also:
- THLIEP_FunctionCode is set with ThliEP_ApplSet.
- THLIEP_ApplidLen is set to the length of the APPLID. If this value is less than 1 or greater than 8, the ThliEP_APPLID value is ignored.
- ThliEP_APPLID is set to the APPLID value.
If there is no applid value passed, the applid value defaults to OMVSAPPL.
- If environment variable BPXK_MIN_PWFOLD=YES is set then non-graphic characters will not be changed to blanks before being passed to the security product. This behavior will exist for all threads in the process where the environment variable was set
Related services
None.
Characteristics and restrictions
None.
Examples
For an example using this callable service, see BPX1SEC (__login, __login__applid, __certificate) example.