Subfunction codes

Value	Subfunction
1	Initiate a GSS-API security context
2	Continue initiation of a GSS-API security context
3	Accept a GSS-API security context
4	Delete a GSS-API security context
5	Release a GSS-API credential
6	Get the MIC for a message
7	Verify the MIC for a message
8	Wrap a message
9	Unwrap a message
10	Export a GSS-API security context
11	Import a GSS-API security context
12	Export a GSS-API credential
13	Import a GSS-API credential
14	Acquire a GSS-API initiator credential

Initiate® a GSS-API security context (1)

This function will initiate a GSS-API security context and return a context token. This token would then be sent to the context acceptor. The RACF® userid associated with the thread that makes the request will be the owner of the security context. Refer to the description of the gss_init_sec_context() function for more information.

Function-specific parameters:

Address of a word containing the subfunction code (input)
Address of a word which will contain the GSS-API major status code (output)
Address of a word which will contain the GSS-API minor status code (output)
Address of ACEE to run under the authority of (input)
Address of the string block for the target principal or service name (input). The name has a maximum length of 240 bytes. A fully-qualified principal name is expressed as /.../realm-name/principal-name. A local principal name can be expressed as principal-name without a realm prefix. A service name is expressed as /:/host-name/service-name.
Address of a word containing the request flags (input). Refer to the description of the gss_init_sec_context() function for the flag definitions
Address of a word containing the requested context expiration time in seconds (input). An expiration time of 0 will request the default expiration time of two hours while an expiration time of -1 will request the maximum expiration time.
Address of a 24-byte credential handle (input). The RACF userid associated with the thread that makes the request must be the credential owner. The credential may have been created on any system in the sysplex. In order to use a credential created on a different system, the Kerberos ticket associated with the credential must not contain a client address list.
Address of a 24-byte buffer which will contain the context handle for the new security context (output). The caller is responsible for deleting the security context when it is no longer needed.
Address of a word which will contain the return flags (output). Specify a zero address if the return flags are not needed. Refer to the description of the gss_init_sec_context() function for the flag definitions.
Address of a word which will contain the actual context expiration time in seconds (output). Specify a zero address if the context expiration time is not needed.
Address of the buffer control block for the output token (output). The security server will obtain storage in the requested subpool for the return data. The caller must set the subpool number and the security server will set the length and address values in the buffer control block. The caller is responsible for releasing the return data when it is no longer needed.

Continue initiation of a GSS-API security context (2)

This function will continue context initiation using the context token returned by the remote partner after accepting the context. This sub-function is called only if sub-function 1 completed with GSS major status of GSS_S_CONTINUE_NEEDED. Refer to the description of the gss_init_sec_context() function for more information.

Function-specific parameters:

Address of a word containing the subfunction code (input)
Address of a word which will contain the GSS-API major status code (output)
Address of a word which will contain the GSS-API minor status code (output)
Address of ACEE to run under the authority of (input)
Address of a 24-byte buffer containing the context handle returned by function 1 (input). The RACF userid associated with the thread that makes the request must be the context owner and the context must have been created on the local system.
Address of a word containing the length of the context token (input)
Address of the context token returned by the context acceptor (input)
Address of a word which will contain the return flags (output). Specify a zero address if the return flags are not needed. Refer to the description of the gss_init_sec_context() function for the flag definitions.
Address of a word which will contain the actual context expiration time in seconds (output). Specify a zero address if the context expiration time is not needed.

Accept a GSS-API security context (3)

This function will accept a GSS-API security context. The RACF userid associated with the thread that makes the request will be the owner of the security context and delegated credentials. The Kerberos principal associated with the RACF userid must be the same as the target principal specified by the context initiator. The output token must be returned to the context initiator if it has a non-zero length (a length of zero indicates no output token is needed). See the description of the gss_accept_sec_context() function for more information.

Function-specific parameters:

Address of a word containing the subfunction code (input)
Address of a word which will contain the GSS-API major status code (output)
Address of a word which will contain the GSS-API minor status code (output)
Address of ACEE to run under the authority of (input)
Address of a word containing the length of the input context token (input)
Address of the input context token received from the context initiator (input)
Address of a 24-byte buffer which will contain the context handle for the new security context (output). The caller is responsible for deleting the security context when it is no longer needed.
Address of the string block for the source principal name (output). The string buffer should be 240 bytes. The principal name will be returned in global format (/.../realm-name/principal-name). Specify a zero address of the source principal name is not needed.
Address of a word which will contain the return flags (output). Specify a zero address if the return flags are not needed. Refer to the description of the gss_accept_sec_context() function for the flag definitions.
Address of the context expiration time in seconds (output). Specify a zero address if the expiration time is not needed.
Address of the buffer control block for the output token (output). The security server will obtain storage in the requested subpool for the return data. The caller must set the subpool number and the security server will set the length and address values in the buffer control block. The caller is responsible for releasing the return data when it is no longer needed.
Address of a 24-byte buffer which will contain the credential handle for the delegated credentials (output). The caller is responsible for deleting the credential when it is no longer needed. Specify a zero address if the delegated credentials are not needed. Delegated credentials are available only if the GSS_C_DELEG_FLAG flag is set in the return flags.

Delete a GSS-API security context (4)

This function will delete a GSS-API security context. The RACF userid associated with the thread that makes the request must be the security context owner and the security context must have been created on the local system. See the description of the gss_delete_sec_context() function for more information.

Function-specific parameters:

Address of a word containing the subfunction code (input)
Address of a word which will contain the GSS-API major status code (output)
Address of a word which will contain the GSS-API minor status code (output)
Address of ACEE to run under the authority of (input)
Address of the 24-byte context handle (input)

Release a GSS-API credential (5)

This function will release a GSS-API credential. The RACF userid associated with the thread that makes the request must be the credential owner and the credential must have been created on the local system. See the description of the gss_release_cred() function for more information.

Function-specific parameters:

Address of a word containing the subfunction code (input)
Address of a word which will contain the GSS-API major status code (output)
Address of a word which will contain the GSS-API minor status code (output)
Address of ACEE to run under the authority of (input)
Address of the 24-byte credential handle (input)

Get the MIC for a message (6)

This function will generate the MIC (message integrity code) for a message. The RACF userid associated with the thread that makes the request must be the owner of the GSS-API security context and the context must have been created on the local system. See the description of the gss_get_mic() function for more information.

Function-specific parameters:

Address of a word containing the subfunction code (input)
Address of a word which will contain the GSS-API major status code (output)
Address of a word which will contain the GSS-API minor status code (output)
Address of ACEE to run under the authority of (input)
Address of the 24-byte context handle (input)
Address of a word containing the message length (input). The maximum message length is 65536.
Address of the message (input)
Address of the buffer control block for the output token (output). The security server will obtain storage in the requested subpool for the return data. The caller must set the subpool number and the security server will set the length and address values in the buffer control block. The caller is responsible for releasing the return data when it is no longer needed.

Verify the MIC for a message (7)

This function will verify the MIC (message integrity code) for a message. The RACF userid associated with the thread that makes the request must be the owner of the GSS-API security context and the context must have been created on the local system. See the description of the gss_verify_mic() function for more information.

Function-specific parameters:

Address of a word containing the subfunction code (input)
Address of a word which will contain the GSS-API major status code (output)
Address of a word which will contain the GSS-API minor status code (output)
Address of ACEE to run under the authority of (input)
Address of the 24-byte context handle (input)
Address of a word containing the message length (input). The maximum message length is 65536.
Address of the message (input)
Address of a word containing the length of the input token (input)
Address of the input token (input)

Wrap a message (8)

This function will sign and optionally encrypt a message. The RACF userid associated with the thread that makes the request must be the owner of the GSS-API security context and the context must have been created on the local system. See the description of the gss_wrap() function for more information.

Function-specific parameters:

Address of a word containing the subfunction code (input)
Address of a word which will contain the GSS-API major status code (output)
Address of a word which will contain the GSS-API minor status code (output)
Address of ACEE to run under the authority of (input)
Address of a 24-byte context handle (input)
Address of a word containing the confidentiality request flag (input). Set the flag to 1 to request encryption or to 0 to request no encryption. A request for encryption will be ignored if the current system configuration does not support message encryption.
Address of a word containing the message length (input). The maximum message length is 65536.
Address of the message (input).
Address of a word which will contain the confidentiality state (output). The state will be set to 1 if the message was encrypted and to 0 otherwise. Specify a zero address if the confidentiality state is not needed.
Address of the buffer control block for the output token (output). The security server will obtain storage in the requested subpool for the return data. The caller must set the subpool number and the security server will set the length and address values in the buffer control block. The caller is responsible for releasing the return data when it is no longer needed.

Unwrap a message (9)

This function will verify the signature and optionally decrypt a message. The RACF userid associated with the thread that makes the request must be the owner of the GSS-API security context and the context must have been created on the local system. See the description of the gss_unwrap() function for more information.

Function-specific parameters:

Address of a word containing the subfunction code (input)
Address of a word which will contain the GSS-API major status code (output)
Address of a word which will contain the GSS-API minor status code (output)
Address of ACEE to run under the authority of (input)
Address of the 24-byte context handle (input)
Address of a word containing the input token length (input)
Address of the input token (input)
Address of the buffer control block for the unwrapped message (output). The security server will obtain storage in the requested subpool for the return data. The caller must set the subpool number and the security server will set the length and address values in the buffer control block. The caller is responsible for releasing the return data when it is no longer needed.
Address of a word which will contain the confidentiality state (output). The state will be set to 1 if the message was encrypted and to 0 otherwise. Specify a zero address if the confidentiality state is not needed.

Export GSS-API security context (10)

This function will export a GSS-API security context. The security context will no longer be available upon completion of the export request. The RACF userid associated with the thread that makes the request must be the owner of the GSS-API security context and the context must have been created on the local system. See the description of the gss_export_sec_context() function for more information.

Function-specific parameters:

Address of a word containing the subfunction code (input)
Address of a word which will contain the GSS-API major status code (output)
Address of a word which will contain the GSS-API minor status code (output)
Address of ACEE to run under the authority of (input)
Address of the 24-byte context handle (input)
Address of the buffer control block for the output token (output). The security server will obtain storage in the requested subpool for the return data. The caller must set the subpool number and the security server will set the length and address values in the buffer control block. The caller is responsible for releasing the return data when it is no longer needed.

Import GSS-API security context (11)

This function will import a GSS-API security context. The RACF userid associated with the thread that makes the request will be the owner of the new context. See the description of the gss_import_sec_context() function for more information.

Function-specific parameters:

Address of a word containing the subfunction code (input)
Address of a word which will contain the GSS-API major status code (output)
Address of a word which will contain the GSS-API minor status code (output)
Address of ACEE to run under the authority of (input)
Address of a word containing the length of the input token (input)
Address of the input token (input)
Address of a 24-byte buffer which will contain the context handle for the new security context (output). The caller should delete the security context when it is no longer needed.

Export GSS_API credential (12)

This function will export a GSS-API credential. The credential will still be available upon completion of the export request. The RACF userid associated with the thread that makes the request must be the owner of the GSS-API credential. The credential may have been created on any system in the sysplex. A credential can be exported only if it is an initiate credential (GSS_C_INITIATE was specified when the credential was created). See the description of the gss_export_cred() function for more information.

Function-specific parameters:

Address of a word containing the subfunction code (input)
Address of a word which will contain the GSS-API major status code (output)
Address of a word which will contain the GSS-API minor status code (output)
Address of ACEE to run under the authority of (input)
Address of the 24-byte credential handle (input)
Address of the buffer control block for the output token (output). The security server will obtain storage in the requested subpool for the return data. The caller must set the subpool number and the security server will set the length and address values in the buffer control block. The caller is responsible for releasing the return data when it is no longer needed.

Import GSS-API credential (13)

This function will import a GSS-API credential. The RACF userid associated with the thread that makes the request will be the owner of the new credential. See the description of the gss_import_cred() function for more information.

Function-specific parameters:

Address of a word containing the subfunction code (input)
Address of a word which will contain the GSS-API major status code (output)
Address of a word which will contain the GSS-API minor status code (output)
Address of ACEE to run under the authority of (input)
Address of a word containing the length of the input token (input).
Address of the input token (input)
Address of a 24-byte buffer which will contain the credential handle for the new credential (output). The caller should release the credential when it is no longer needed.

Acquire GSS-API initiator credential (14)

This function will acquire a GSS-API credential which can be used to initiate a GSS-API security context. The RACF userid associated with the thread that makes the request will be the owner of the new credential. The Kerberos principal associated with the RACF userid will be used to obtain the initial ticket-granting ticket for the credential. This initial ticket will be forwardable and will not contain a client address list.

Function-specific parameters:

Address of a word containing the subfunction code (input)
Address of a word which will contain the GSS-API major status code (output)
Address of a word which will contain the GSS-API minor status code (output)
Address of ACEE to run under the authority of (input)
Address of a word containing the requested credential expiration time in seconds (input). An expiration time of 0 will request the default expiration time of 2 hours while an expiration time of -1 will request the maximum expiration time. The actual credential expiration time will be limited by the lifetime of the Kerberos ticket-granting ticket.
Address of a 24-byte buffer which will contain the credential handle for the new credential (output). The caller should release the credential when it is no longer needed.
Address of a string block for the principal name (output). Specify a zero address if the principal name is not needed. The string buffer should be large enough for a 240-byte name. The principal name will be returned in global format (/.../realm-name/princ-name).
Address of a word which will contain the actual credential expiration time in seconds (output). Specify a zero address if the credential expiration time is not needed.