コンテキスト構造

sm1252sp1jjp
Sm_Api_AppSpecificContext_t
この構造には共有メモリ情報が含まれます。
構文
typedef struct
{
   void* pHandle;
   Sm_Api_GetBufferFunc fGetBuffer;
   Sm_Api_AllocBufferFunc fAllocBuffer; 
   Sm_Api_FreeBufferFunc fFreeBuffer;
   Sm_Api_GetBufferSizefunc fGetBufferSize;
} Sm_Api_AppSpecificContext_t;
フィールド
説明
pHandle
渡されるハンドルで、メモリ管理機能に必要です。このハンドルは Sm_Api_Context_t の
pAppSpecific
なフィールドから取得されます。
fGetBuffer
メモリが割り当てられなかった場合、以前割り当てられた要求に固有のメモリまたは NULL にポインタを返す関数。
pHandle
は関数の唯一のパラメータです。
 
fAllocBuffer
要求に固有のメモリを割り当てて、ポインタを割り当てられたバッファに返す関数。バッファがすでに割り当てられているか、メモリが利用可能でない場合、それは NULL を返します。
パラメータは
pHandle
、およびバッファのサイズを指定する int です。
 
fFreeBuffer
渡された
pHandle
引数と関連する要求に固有のメモリを解放する関数。値は返されません。
 
fGetBufferSize
バッファのサイズを取得する関数。
 
関数宣言
構造 Sm_Api_AppSpecificContext_t では、関数 fGetBuffer、fAllocBuffer、fFreeBuffer および fGetBufferSize は、SmApi.h で以下のように宣言されます。
fGetBuffer
typedef void* (SM_EXTERN *Sm_Api_GetBufferFunc) 
    (const void *pHandle);
fAllocBuffer
typedef void* (SM_EXTERN *Sm_Api_AllocBufferFunc) 
    (const void *pHandle, const int nSize);
fFreeBuffer
typedef void (SM_EXTERN *Sm_Api_FreeBufferFunc) 
   (const void *pHandle);
fGetBufferSize
typedef int (SM_EXTERN *Sm_Api_GetBufferSizeFunc) 
   (const void *pHandle);
例:
// Allocate 64 bytes
char* pBuffer = (char*) lpApiContext->pAppSpecific->fAllocBuffer
                (lpApiContext->pAppSpecific->pHandle, 64);
strcpy (pBuffer, "id=5");
...
 
// Use it somewhere else
char id[20];
char* pBuffer = (char*) lpApiContext->pAppSpecific->fGetBuffer
                (lpApiContext->pAppSpecific->pHandle);
if (pBuffer != NULL)
{
   strcpy (id, pBuffer);
}
 
//Free the memory when done
...
(char*) lpApiContext->pAppSpecific->fFreeBuffer
                (lpApiContext->pAppSpecific->pHandle);
Sm_Api_Context_t
Sm_Api_Context_t 構造は以下の
Single Sign-On
API によって使用されます。 
  • 認証 API
  • 許可 API
  • トンネル サービス API
  • DMS ワークフロー API
  • ディレクトリ API
この構造は、ログ記録ユーティリティ、トレース ユーティリティ、およびエラー ユーティリティに関数ポインタを与えます。この構造には一般的な API 情報が含まれます。
構文
typedef struct
{
   int nVersion;
   Sm_Api_LogFunc fLog;
   Sm_Api_TraceFunc fTrace;
   Sm_Api_ErrorFunc fError;
   Sm_Api_AppSpecificContext_t*  pAppSpecific;
} Sm_Api_Context_t;
フィールド
説明
nVersion
使用されている API のバージョン番号。指定可能な値
Sm_Api_Version_V3
Sm_Api_Version_V4
Sm_Api_Version_V4_1
バージョン定数は SmApi.h で定義されています。
fLog
CA Single Sign-on
ログ記録ユーティリティにアクセスするための関数。
CA Single Sign-on
ログ記録ユーティリティにアクセスするための関数。
この関数の呼び出し構文: char* lpszMessage = "Log this text"; lpApiContext->fLog (lpszMessage)
 
fTrace
CA Single Sign-on
トレース ユーティリティにアクセスするための関数。
CA Single Sign-on
はトレースが有効な状態で実行されている必要があります。
この関数の呼び出し構文: char* lpszCheckpoint = "MyLib"; char* lpszTraceMessage = "Trace text";lpApiContext->fTrace (lpszCheckpoint, lpszTraceMessage)
 
fError
CA Single Sign-on
エラー ユーティリティにアクセスするための関数。
CA Single Sign-on
はログ記録が有効な状態で実行されている必要があります。
この関数の呼び出し構文: char* lpszMessage = "Log this Error text"; lpApiContext->fError (lpszMessage)
 
pAppSpecific
pAppSpecific
ポインタは、Sm_Api_AppSpecificContext_t 構造内のメソッドへのアクセス権があります。これらのメソッドは要求に固有のメモリの割り当て、削除、および解放を行います。このメモリは単一のエージェント要求の全処理中も存続し、認証デーモンや認可デーモンなどの各サーバ プロセスに局所的です。
メモリがモジュールによって割り当てられ解放される回数に関して制限はありません。いったん要求が処理されれば、メモリは自動的に解放されます。
関数宣言
構造 Sm_Api_Context_t では、関数 fLog、fTrace および fError は、SmApi.h で以下のように宣言されます。
fLog
/* string to log (null-terminated) */
typedef void (SM_EXTERN *Sm_Api_LogFunc) (const char* lpszBuffer);
fTrace
/* string to log (null-terminated) */
typedef void (SM_EXTERN *Sm_Api_TraceFunc)
   (const char* lpszCheckpoint, const char* lpszBuffer);
fError
/* string to log (null-terminated) */
typedef void (SM_EXTERN *Sm_Api_ErrorFunc) 
   (const char* lpszBuffer);
Sm_Api_RequestContext_t
実行中の要求に関する情報を含みます。
構文
typedef struct
{
   char* lpszServer;
   char* lpszResource;
   char* lpszAction;
} Sm_Api_RequestContext_t;
フィールド
説明
lpszServer
ユーザ アクセス要求のサーバ部分。たとえば、ユーザが http://www.server.com/index.html にアクセスする場合、サーバは www.server.com です。
lpszResource
ユーザ アクセス要求のリソース部分。たとえば、ユーザが http://www.server.com/index.html にアクセスする場合、リソースは /index.html です。
lpszAction
ユーザによって要求されるようなアクション。たとえば、Web リソースにアクセスするときの標準的なアクションは GET です。
Sm_Api_TunnelContext_t
トンネル エージェントから渡された情報を保持します。
構文
typedef struct
{
   char* lpszClientIp;
   char* lpszTransactionId;
   char* lpszParameter;
} Sm_Api_TunnelContext_t;
フィールド
説明
lpszClientIP
トンネル コールを行うトンネル エージェントの IP アドレス。
lpszTransactionId
(オプション)エージェントがセキュリティ アクティビティをアプリケーション アクティビティに関連付けるために使用する IDです。ポリシー サーバは、この ID をログ記録します。
lpszParameter
トンネル エージェントから渡された任意の文字列パラメータ。トンネル エージェント側で、この情報は Sm_AgentApi_TunnelServiceRequest_t 内の
lpszParameter
に渡されます。
Sm_Api_UserContext_t
ユーザに関する情報が含まれます。
構文
typedef struct
{
   unsigned char  bIsUserContext;
   char* lpszUserName;
   char* lpszUserPath;
   char* lpszDirPath;
   void* lpReserved1;
   char* lpszDirServer;
   char* lpszDirNamespace;
   char* lpszSessionId;
   Sm_Api_GetDnProp fGetDnProp;
   Sm_Api_SetDnProp fSetDnProp;
   void* lpParam;
   Sm_Api_GetUserProp fGetProp;
   Sm_Api_SetUserProp fSetProp;
   Sm_Api_AuthenticateUser fAuthenticate;
} Sm_Api_UserContext_t;
フィールド
説明
bIsUserContext
CA Single Sign-on
がユーザの ID を確立し、ユーザ コンテキストが利用可能であることを示すフラグ。このフラグが設定されると、
fGetProp
fSetProp
fGetDnProp
および
fSetDnProp
ユーザ属性関数が利用可能になります。
lpszUserName
ユーザの完全識別名。
lpszUserPath
以下の形式のユーザ パス。
directory-namespace
+
server
+ / +
user-DN
例: ldap://server.company.com/ uid=user1,ou=people,o=company.com
lpszDirPath
ユーザ コンテキストが確立された
CA Single Sign-on
ユーザ ディレクトリのディレクトリ パスで、形式は
directory-namespace
+
server
になります。
例: ldap://server.company.com
lpReserved1
内部使用向けです。
lpszDirServer
ユーザ コンテキストが確立された
CA Single Sign-on
ユーザ ディレクトリのディレクトリ サーバ。
lpszDirNamespace
LDAP:、AD:、WinNT:、または ODBC: などのディレクトリ ネームスペース。
lpszSessionId
ユーザのセッションに割り当て済みまたは割り当てられる予定のセッション ID。セッションがすでに確立されているかどうかによって決まります。
fGetDnProp
ディレクトリ エントリの属性を返す関数。ユーザ コンテキスト フラグ bIsUserContext が設定される場合、開発者はこの関数を呼び出し、ディレクトリのコンテキストでユーザが関連付けられる DN の既知の属性を取得することができます(たとえば、ユーザはグループのメンバです)。
この関数の呼び出し構文: if (lpUserContext->bIsUserContext){char lpszDN[]="cn=group,ou=org unit,o=org";char lpszCommonName[100];int nBytes = lpUserContext->fGetDnProp(                lpUserContext->lpParam,                lpszDN,                "accesslevel",                sizeof (lpszCommonName),                lpszCommonName);}
エラーが発生しない場合、この関数は要求された属性の値を NULL で終わる出力バッファに配置し、その長さを返します。それ以外の場合、関数は –1 を返します。
この関数から返された属性は
nBytesValueBuf
引数で指定された最大バッファ サイズより小さくなければなりません。それより大きい属性は
nBytesValueBuf
に切り捨てられます。
 
fSetDnProp
ディレクトリ エントリの属性を設定する関数。ユーザ コンテキスト フラグ bIsUserContext が設定される場合、開発者はこの関数を呼び出し、ディレクトリのコンテキストでユーザが関連付けられる DN の既知の属性を設定することができます(たとえば、ユーザはグループのメンバです)。この時、タイプ「文字列」の属性のみがサポートされます。
この関数の呼び出し構文: if (lpUserContext->bIsUserContext){char lpszDN[]="cn=group,ou=org unit,o=org";char lpszTimestamp[] = "<timestamp>";int nErr = lpUserContext->fSetDnProp (                 lpUserContext->lpParam,                 lpszDN,                 "lastaccess",                 sizeof (lpszTimestamp),                 lpszTimestamp);}
 
 
lpParam
fGetProp
fSetProp
fGetDnProp
、および
fSetDnProp
関数に渡されるパラメータへのポインタ。
fGetProp
ユーザ属性を返す関数。ユーザ コンテキスト フラグ bIsUserContext が設定される場合、開発者はこの関数を呼び出し、既知のユーザ属性を取得することができます。
この関数の呼び出し構文は次のとおりです。
if (lpUserContext->bIsUserContext){char lpszCommonName[100];int nBytes = lpUserContext->fGetProp ( lpUserContext->lpParam, "cn", sizeof (lpszCommonName), lpszCommonName);}
エラーが発生しない場合、この関数は要求された属性の値を NULL で終わる出力バッファに配置し、その長さを返します。それ以外の場合、関数は -1 を返します。
この関数から返された属性は
nBytesValueBuf
引数で指定された最大バッファ サイズより小さくなければなりません。それより大きい属性は
nBytesValueBuf
に切り捨てられます。
 
fSetProp
ユーザ属性を設定する関数。ユーザ コンテキスト フラグ bIsUserContext が設定される場合、開発者はこの関数を呼び出し、既知のユーザ属性を設定することができます。この時、タイプ「文字列」の属性のみがサポートされます。
この関数の呼び出し構文は次のとおりです。
if (lpUserContext->bIsUserContext){char lpszCommonName[] = "John Smith";int nErr = lpUserContext->fSetProp ( lpUserContext->lpParam, "cn", sizeof (lpszCommonName), lpszCommonName);}
エラーが発生しない場合、関数は 0 を返します。それ以外の場合、関数は -1 を返します。
関数宣言
構造体 Sm_Api_UserContext_t で、関数 fGetDnProp、fSetDnProp、fGetProp、fSetProp および fAuthenticate は、SmApi.h で以下のように宣言されます。
fGetDnProp
typedef int (SM_EXTERN *Sm_Api_GetDnProp)
(
const void* lpParam,        /* The function parameter */
const char* lpDn,           /* The DN of a directory object */
const char* lpszPropName,   /* User property name (null-term) */
const int nBytesValueBuf,   /* Max size of user property buffer */
char* lpszValueBuf /* Output buffer to hold the user property */
);
fSetDnProp
typedef int (SM_EXTERN *Sm_Api_SetDnProp)
(
const void* lpParam,        /* The function parameter */
const char* lpDn,           /* The DN of a directory object */
const char* lpszPropName,   /* User property name (null-term) */
const int nBytesValueBuf,   /* Size of user property buffer */
const char* lpszValueBuf    /* The user property buffer */
);
fGetProp
typedef int (SM_EXTERN *Sm_Api_GetUserProp)
(
const void* lpParam,        /* The function parameter */
const char* lpszPropName,   /* User property name (null-term) */
const int nBytesValueBuf,   /* Max size of user property buffer */
char* lpszValueBuf   /* Output buffer to hold the user property */
);
fSetProp
typedef int (SM_EXTERN *Sm_Api_SetUserProp)
(
const void* lpParam,        /* The function parameter */
const char* lpszPropName,   /* User property name (null-term) */
const int nBytesValueBuf,   /* Size of user property buffer */
const char* lpszValueBuf    /* The user property buffer */
);
fAuthenticate
typedef int (SM_EXTERN *Sm_Api_AuthenticateUser)
(
const void* lpParam,        /* The function parameter */
const char* lpszPassword,   /* User password (null-terminated) */
const int nBytesUserMsg,    /* Max size of user message buffer */
char* lpszUserMsg,   /* Output buffer to hold the user message */
const int nBytesErrMsg,    /* Maximum size of the error buffer */
char* lpszErrMsg    /* Output buffer to hold the error message */
);
LDAP の複数値属性
LDAP ユーザ ストアで複数値属性を設定または取得する場合、その値は単一の文字列で示され、キャラット文字(^)によって区切られます。
たとえば、3 つの異なる電話番号を以下のように設定することができます。
char lpszTemp[] = "111-1234^111-5678^111-0000";
 
int getResult = lpUserContext->fSetProp (lpUserContext->lpParam,
                                         "telephonenumber",
                                         strlen(lpszTemp),
                                         lpszTemp);
複数値属性を設定または取得するカスタム コードは、予期される複数値文字列形式をサポートする必要があります。
: ODBC ユーザ ストアは複数値属性設定をサポートしません。
ポリシー サーバ バージョンのサポート
4.61 またはそれ以降のポリシー サーバでは、上記の例における電話番号は、以下のように LDAP ユーザ ストア内のユーザの電話番号属性に入れられます。
111-1234
111-5678
111-0000
4.61 ポリシー サーバより前に、上記のコードは以下のように電話番号属性を設定します。
111-1234^111-5678^111-0000
Sm_AuthApi_UserCredentials_t
ユーザ認証情報に関する情報が含まれます。
CA Single Sign-on
は利用可能な情報を指定します。通常は、ユーザ名とパスワード フィールドが指定されます。認証方式はそれぞれ、可能な認証情報のサブセットを予期します。
この構造内のフィールドは、要求された認証情報に基づいて入力されます。
構文
typedef struct
{
   char* lpszUsername;
   char* lpszPassword;
   int   nBytesChapPassword;
   char* lpszChapPassword;
   int   nBytesChapChallenge;
   char* lpszChapChallenge;
   char* lpReserved1;
   char* lpszCertUserDN;
   char* lpszCertIssuerDN;
   int   nCertBinLen;
   void* lpCertBinary;
   char* lpszDirPath;
   char* lpszDirServer;
   char* lpszDirNamespace;
   char* lpszNewPassword;
   char* lpszPasswordToken;
} Sm_AuthApi_UserCredentials_t;
フィールド
説明
lpszUsername
ユーザによって指定されたユーザ名から
CA Single Sign-on
によって特定されるユーザの DN。
lpszPassword
ユーザによって指定されるユーザ パスワード。
nBytesChapPassword
CHAP パスワードの長さ。
lpszChapPassword
CHAP パスワード。
nBytesChapChallenge
CHAP チャレンジの長さ。
lpszChapChallenge
CHAP チャレンジ。
lpReserved1
内部使用向けです。
lpszCertUserDN
X.509 ユーザの証明書のユーザ DN 部分。
lpszCertIssuerDN
X.509 ユーザの証明書の発行者 DN 部分。
nCertBinLen
ユーザのバイナリ X.509 証明書の長さ。
lpCertBinary
ユーザのバイナリ X.509 証明書。
lpszDirPath
ユーザ コンテキストが確立された
CA Single Sign-on
ユーザ ディレクトリの
CA Single Sign-on
表記法におけるディレクトリ パス。
lpszDirServer
ユーザ コンテキストが確立された
CA Single Sign-on
ユーザ ディレクトリのディレクトリ サーバ。
lpszDirNamespace
ユーザ コンテキストが確立された
CA Single Sign-on
ユーザ ディレクトリのディレクトリ ネームスペース。
lpszNewPassword
ユーザの新しいパスワード。
lpszPasswordToken
パスワード サービスからのパスワード トークン。