ictxBuildAuthContext()--Build Authentication Context

 #include <ictx.h>;

 int ictxBuildAuthContext
 (
  char                  *  contextTypeOID,
  ictxAuthContextInfo_t *  contextInfo,
  ictxOptions_t         *  options,
  ictxIdContext_t      **  authContext,
  ictxError_t           *  errorInfo
 )

The ictxBuildAuthContext() function builds a new authentication context and returns the context to the caller. The authentication context will contain the information specified in the contextInfo parameter and is dependent on the Authentication Context Type (OID).

Parameters

contextTypeOID  (Input)

The type of authentication context to build. This is a NULL terminated string that contains the object identifier (OID) that identifies the context information.

Valid values are:

• 0.0.0.0.0 Authentication Context Type 1

contextInfo  (Input)

The information that is used to build the authentication context. This information is dependent on the type of authentication context that is to be built. For the format of the structure, see the ictxAuthContextInfo structure in the ictxAuthContextInfo--Authentication Context Information Parameter.

options  (Input)

The options that can be specified for the identity context reference. This parameter may be NULL. If this parameter is NULL, the default values will be used for the options. For the format of the structure, see ictxOptions--Identity Context Options Parameter.

authContext  (Output)

Return pointer to an authentication context object. When this context is no longer needed, it must be freed using the Free Identity Context (ictxFreeIdContext) API. For the format of the structure, see the ictxIdContext structure in the ictxIdContext--Identity Context Parameter.

errorInfo  (Output)

The structure in which to return error code information. If the return value is not 0, errorInfo is set with additional information. This parameter may be NULL. For the format of the structure, see ictxError--Identity Context Return Code Parameter.

Return Value

The return value from the API.

0

Request was successful.

ICTXERR_PARM_REQ (1)

Missing required parameter. Please check API documentation.

ICTXERR_NOMEM (2)

No memory available. Unable to allocate required space.

ICTXERR_OPTIONS_NOT_SUPPORTED (6)

Options are not supported.

ICTXERR_TIMEOUT_INVALID (7)

Timeout value in options is not valid.

ICTXERR_AUTH_CTX_TYPE_NOT_SUPPORTED (10)

Authentication Context Type is not supported.

ICTXERR_CTXINFO_FORMAT_NOT_SUPPORTED (11)

Format for ictxAuthContextInfo is not supported for this authentication context type.

ICTXERR_AUTHINFO_FORMAT_NOT_SUPPORTED (12)

Format for ictxAuthInfo is not supported for this authentication context type.

ICTXERR_AUTHINFO_INVALID (13)

Error occurred with the ictxAuthInfo parameter. May be missing required field for this authentication context type.

ICTXERR_DATA_CONVERSION (14)

Error occurred when converting data between code pages.

ICTXERR_APPINFO_FORMAT_NOT_SUPPORTED (15)

Format for ictxAppInfo is not supported for this authentication context type.

ICTXERR_APPINFO_INVALID (16)

Error occurred with the ictxAppInfo parameter. May be missing required field for this authentication context type.

ICTXERR_AUTHINFO_VERSION_NOT_SUPPORTED (21)

Error occurred with the ictxAuthInfo parameter. The requested version is not supported.

ICTXERR_APPINFO_VERSION_NOT_SUPPORTED (22)

Error occurred with the ictxAppInfo parameter. The requested version is not supported.

ICTXERR_PREMAPPEDINFO_VERSION_NOT_SUPPORTED (23)

Error occurred with the ictxPremappedInfo parameter. The requested version is not supported.

ICTXERR_PREMAPPEDINFO_FORMAT_NOT_SUPPORTED (24)

Format for ictxPremappedInfo is not supported for this authentication context type.

ICTXERR_PREMAPPEDINFO_INVALID (25)

Error occurred with the ictxPremappedInfo parameter. May be missing required field for this authentication context type.

ICTXERR_CTXINFO_INVALID (27)

Error occurred with the ictxAuthContextInfo parameter. May be missing required field for this authentication context type.

eServer Implementation Notes

1. AIX implementation details:
   • Authority: None
2. Linux implementation details:
   • Authority: None
3. i5/OS implementation details:
   
   • Service Program Name: QSYS/QSYICTX
     
   • Authority: Default public authority *USE
4. Windows implementation details:
   • Authority: Users must have administrative privilege to install and work with the APIs.
5. z/OS implementation details:
   
   • Authority: The caller of the API must be APF-authorized.

Related Information

• ictxDelegateAuthContext() --Delegate Authentication Context
  
  
• ictxParseAuthContext() --Parse Authentication Context
  
  
• ictxFreeIdContext() --Free Identity Context Storage
  
  
• ictxFreeParseInfo() --Free Authentication Context Parse Info Storage
  
  

Example

The following example builds an authentication context. Note: Read the Code example disclaimer for important legal information.

#include <ictx.h>
#include <string.h>
	
int buildAuthContext(ictxIdContext_t  ** authContext)
{
    int rc;
    
    ictxAuthenticationInfo_t authInfo;
    ictxAuthInfo_t authBlock;

    ictxAppInfo_t sendBlock;
    ictxApplicationInfo_t sender;
    
    ictxAppInfo_t recvBlock;
    ictxApplicationInfo_t receiver;

    ictxAuthContextInfo_t ctxInfo;

    ictxOptions_t options;


    ictxError_t errorInfo;
    /*----------------------------------------------------------------*/
    /*  Set up authentication information                             */
    /*----------------------------------------------------------------*/
    authInfo.user = "MARY";
    authInfo.registry = "ldap084.rchland.ibm.com";
    authInfo.hostName = "toro4lab.ibm.com";
    authInfo.authMech = "LDAP";
    authInfo.securityLabel = NULL;
    authInfo.implemSpecific = NULL;
    
    authBlock.format = ICTX_AUTH_INFO_FORMAT_0;
    authBlock.authInfo.format0.version = 0;
    authBlock.authInfo.format0.authInfo = &authInfo;

    /*----------------------------------------------------------------*/
    /*  Set up sender application information                         */
    /*----------------------------------------------------------------*/
    sender.appid = "Favorite App";
    sender.instance = "PremierUsage/xxx/yyy";
    sender.implemSpecific = NULL;
    
    sendBlock.format = ICTX_APP_INFO_FORMAT_0;
    sendBlock.appInfo.format0.version = 0;
    sendBlock.appInfo.format0.appInfo = &sender;

    /*----------------------------------------------------------------*/
    /*  Set up receiver application information                       */
    /*----------------------------------------------------------------*/
    receiver.appid = "Back end App";
    receiver.instance = "hostess with the mostest";
    receiver.implemSpecific = NULL;
    
    recvBlock.format = ICTX_APP_INFO_FORMAT_0;
    recvBlock.appInfo.format0.version = 0;
    recvBlock.appInfo.format0.appInfo = &receiver;
    
    /*----------------------------------------------------------------*/
    /*  Now combine all for the context information                   */
    /*----------------------------------------------------------------*/
    ctxInfo.format = ICTX_AUTHCTX_INFO_FORMAT_0;
    ctxInfo.contextInfo.format0.authData = &authBlock;
    ctxInfo.contextInfo.format0.sender = &sendBlock;
    ctxInfo.contextInfo.format0.receiver = &recvBlock;
    ctxInfo.contextInfo.format0.premappedUser = NULL;

    /*----------------------------------------------------------------*/
    /*  Set up options                                                */
    /*----------------------------------------------------------------*/
    options.format = ICTX_OPTIONS_FORMAT_0;
    options.options.format0.timeout = 600;

    /*----------------------------------------------------------------*/
    /*  Build authentication context                                  */
    /*----------------------------------------------------------------*/
    if (0 != (rc = ictxBuildAuthContext(ICTX_AUTH_CTX_TYPE1,
                                        &ctxInfo,
                                        &options,
                                        authContext,
                                        &errorInfo)))
    {
	.
	.
	.
        return -1;
    }
    
    return 0;
}