SmAuthQuery()

Programming Guides › Programming Guide for C › Authentication API › Create a Custom Authentication Scheme Library › SmAuthQuery()

SmAuthQuery()

Returns information about an authentication scheme.

Syntax

Sm_AuthApi_Status_t SM_EXTERN SmAuthQuery (
   const char*                   lpszParam,
   const char*                   lpszSharedSecret,
   const Sm_AuthApi_QueryCode_t  code,
   char*                         lpszStatusBuffer,
   int*                          lpnStatusCode
);

Parameter	I/O	Description
lpszParam	I	Pointer to the buffer containing the null-terminated parameter string as specified for the authentication scheme.
lpszSharedSecret	I	Pointer to the buffer containing the null-terminated shared secret string as specified for the authentication scheme.
code	I	Request code as defined by an enum type Sm_AuthApi_QueryCode_t, which contains the following values: Sm_AuthApi_QueryDescription. Requests the scheme's description. The scheme returns a description through lpszStatusBuffer and the Authentication API version number through lpnStatusCode. Sm_AuthApi_QueryCredentialsReq. Requests the credentials required by the scheme and where to obtain them. The scheme should return a bit mask through lpnStatusCode, which represents the credentials needed for authentication. Individual flags are defined by the enum type Sm_Api_Credentials_t. The scheme may return the location where the credentials can be obtained (that is, an HTTP URL) via the lpszStatusBuffer parameter.
lpszStatusBuffer	O	Receives a character string response. Up to Sm_AuthApi_StatusBufSize characters can be returned.
lpnStatusCode	O	If the call requests the scheme's description, receives a numeric response indicating the version number of the Authentication API. Supported versions are Sm_Api_Version_V4 and Sm_Api_Version_V4_1. If the call requests the credentials required by the scheme, the scheme returns one or more credentials. See Remarks. These constants are defined in SmApi.h.

Returns

This function returns one of the following values defined in the enumerated type Sm_AuthApi_Status_t:

Sm_AuthApi_Success. Function was successful.
Sm_AuthApi_Failure. An invalid request code has been specified.

Remarks

The scheme must support request codes as specified by enumeration type Sm_AuthApi_QueryCode_t. The caller queries the scheme to find out what kind of credentials are required for authentication and where to obtain them.

The credentials are defined by the enum type Sm_Api_Credentials_t and can be combined to request multiple credentials. The caller collects the requested credentials, places them into the Sm_AuthApi_UserCredentials_t context structure, and calls the SmAuthenticate() function.

The individual flags in Sm_Api_Credentials_t are as follows:

Sm_AuthApi_Cred_None—No credentials are required.
Sm_AuthApi_Cred_Basic—Username and password are required.
Sm_AuthApi_Cred_Digest—Required user name and password are exchanged using the digest protocol.
Sm_AuthApi_Cred_X509Cert—Full X.509 Client Certificate is required. Sm_AuthApi_Cred_SSLRequired must be specified.
Sm_AuthApi_Cred_X509CertUserDN—User DN from an X.509 Client Certificate is required. Sm_AuthApi_Cred_SSLRequired must be specified.
Sm_AuthApi_Cred_X509CertIssuerDN—Issuer DN from an X.509 Client Certificate is required. Sm_AuthApi_Cred_SSLRequired must be specified.
Sm_AuthApi_Cred_CertOrBasic—Either a certificate is required or a user name and password is required.
Sm_AuthApi_Cred_CertOrForm—Either a certificate is required or a form-based username and password are required.
Sm_AuthApi_Cred_SSLRequired—An SSL connection is required. A redirect to an https URL must be specified.
Sm_AuthApi_Cred_NTChalResp—Required user name and password are exchanged using the NT Challenge Response protocol.
Sm_AuthApi_Cred_AllowSaveCreds—Signifies whether the credentials can be saved for 30 days by the user. If a user saves their credentials, they do not need to enter their credentials, such as user name and password, each time they access the protected resource.
Sm_AuthApi_Cred_FormRequired—A form-based username and password are required. A redirect to a URL containing a form must be specified.
Sm_AuthApi_Cred_PreserveSessionId—The session ID should be preserved if the current session is still valid.
Sm_AuthApi_Cred_DoNotChallenge—Do not challenge for credentials
Sm_AuthAPI_Cred_AllowAnonymous—Allow validation of anonymous identity.

Examples

An Anonymous scheme combines these credential flags:

*lpnStatusCode = Sm_AuthApi_Cred_None|Sm_AuthApi_Cred_AllowAnonymous;

Collect username and password. The Agent uses HTTP basic authentication to challenge the user:
```
*lpnStatusCode = Sm_AuthApi_Cred_Basic;
```

Collect username and password. The Agent challenges the user over SSL using HTTP basic authentication:

*lpnStatusCode = Sm_AuthApi_Cred_Basic |
                           Sm_AuthApi_Cred_SSLRequired;
strcpy(lpszStatusBuffer,
                "https://xxx.yyy.zzz/secure.ssc?basic")

Collect username and password. The Agent challenges the user over SSL using an HTML form:

*lpnStatusCode = Sm_AuthApi_Cred_Basic |
                          Sm_AuthApi_Cred_FormRequired;
strcpy(lpszStatusBuffer,
               "https://xxx.yyy.zzz/getcredentials.fcc")

Collect an X.509 Certificate. The Agent challenges the user for a certificate:

*lpnStatusCode = Sm_AuthApi_Cred_SSLRequired |
                               Sm_AuthApi_Cred_X509Cert;
strcpy(lpszStatusBuffer,
                 "https://xxx.yyy.zzz/getcert.scc?cert")

Collect an X.509 Certificate, username, and password. The Agent challenges the user over SSL using HTTP basic authentication:

*lpnStatusCode = Sm_AuthApi_Cred_Basic |
                         Sm_AuthApi_Cred_SSLRequired |
                         Sm_AuthApi_Cred_X509Cert;
strcpy(lpszStatusBuffer,
           "https://xxx.yyy.zzz/getcert.scc?cert+basic")

Email CA about this topic