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 deregister a certificate that has the current identity of the calling process.
The C functions _login and _certificate result in a call to this service.
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. |
|
AMODE 64 callers use BPX4SEC with the same parameters.
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. |
Constant | Description |
---|---|
SECURITY_USERID# | The user identity is in the format of a 1-to 8-character user ID that is passed as input. |
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.
The name of a field that contains the user identity in the specified format.
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.
The name of a field, of length Pass_length, that contains, left-justified, the password, PassTicket or password phrase that is to be verified.
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.
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.
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.
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.
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. |
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.
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. |
Parameter | Login as a new user | Register a certificate | Deregister 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 identify 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.
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.
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.
If there is no applid value passed, the applid value defaults to OMVSAPPL.
None.
None.
For an example using this callable service, see BPX1SEC (__login, __login__applid, __certificate) example.