public interface Secur32 extends StdCallLibrary
| Modifier and Type | Interface and Description |
|---|---|
static class |
Secur32.EXTENDED_NAME_FORMAT
Specifies a format for a directory service object name.
|
StdCallLibrary.StdCallCallbackLibrary.Handler| Modifier and Type | Field and Description |
|---|---|
static Secur32 |
INSTANCE |
FUNCTION_MAPPER, STDCALL_CONVENTIONOPTION_ALLOW_OBJECTS, OPTION_CALLING_CONVENTION, OPTION_CLASSLOADER, OPTION_FUNCTION_MAPPER, OPTION_INVOCATION_MAPPER, OPTION_OPEN_FLAGS, OPTION_STRING_ENCODING, OPTION_STRUCTURE_ALIGNMENT, OPTION_TYPE_MAPPER| Modifier and Type | Method and Description |
|---|---|
int |
AcceptSecurityContext(Sspi.CredHandle phCredential,
Sspi.CtxtHandle phContext,
Sspi.SecBufferDesc pInput,
int fContextReq,
int TargetDataRep,
Sspi.CtxtHandle phNewContext,
Sspi.SecBufferDesc pOutput,
IntByReference pfContextAttr,
Sspi.TimeStamp ptsTimeStamp)
The AcceptSecurityContext function enables the server component of a transport
application to establish a security context between the server and a remote client.
|
int |
AcquireCredentialsHandle(java.lang.String pszPrincipal,
java.lang.String pszPackage,
int fCredentialUse,
WinNT.LUID pvLogonID,
Pointer pAuthData,
Pointer pGetKeyFn,
Pointer pvGetKeyArgument,
Sspi.CredHandle phCredential,
Sspi.TimeStamp ptsExpiry)
The AcquireCredentialsHandle function acquires a handle to preexisting credentials
of a security principal.
|
int |
CompleteAuthToken(Sspi.CtxtHandle phContext,
Sspi.SecBufferDesc pToken)
The CompleteAuthToken function completes an authentication token.
|
int |
DecryptMessage(Sspi.CtxtHandle phContext,
Sspi.SecBufferDesc pMessage,
int MessageSeqNo,
IntByReference pfQOP)
DecryptMessage (Kerberos) function
The DecryptMessage (Kerberos) function decrypts a message.
|
int |
DeleteSecurityContext(Sspi.CtxtHandle phContext)
The DeleteSecurityContext function deletes the local data structures associated
with the specified security context.
|
int |
EncryptMessage(Sspi.CtxtHandle phContext,
int fQOP,
Sspi.SecBufferDesc pMessage,
int MessageSeqNo)
EncryptMessage (Kerberos) function
The EncryptMessage (Kerberos) function encrypts a message to provide
privacy.
|
int |
EnumerateSecurityPackages(IntByReference pcPackages,
Sspi.PSecPkgInfo ppPackageInfo)
The EnumerateSecurityPackages function returns an array of SecPkgInfo structures that
describe the security packages available to the client.
|
int |
FreeContextBuffer(Pointer buffer)
The FreeContextBuffer function enables callers of security package functions to free a memory
buffer that was allocated by the security package as a result of calls to InitializeSecurityContext
and AcceptSecurityContext.
|
int |
FreeCredentialsHandle(Sspi.CredHandle phCredential)
The FreeCredentialsHandle function notifies the security system that the
credentials are no longer needed.
|
boolean |
GetUserNameEx(int nameFormat,
char[] lpNameBuffer,
IntByReference len)
Retrieves the name of the user or other security principal associated with
the calling thread.
|
int |
ImpersonateSecurityContext(Sspi.CtxtHandle phContext)
The ImpersonateSecurityContext function allows a server to impersonate a client by using
a token previously obtained by a call to AcceptSecurityContext or QuerySecurityContextToken.
|
int |
InitializeSecurityContext(Sspi.CredHandle phCredential,
Sspi.CtxtHandle phContext,
java.lang.String pszTargetName,
int fContextReq,
int Reserved1,
int TargetDataRep,
Sspi.SecBufferDesc pInput,
int Reserved2,
Sspi.CtxtHandle phNewContext,
Sspi.SecBufferDesc pOutput,
IntByReference pfContextAttr,
Sspi.TimeStamp ptsExpiry)
The InitializeSecurityContext function initiates the client side, outbound security
context from a credential handle.
|
int |
MakeSignature(Sspi.CtxtHandle phContext,
int fQOP,
Sspi.SecBufferDesc pMessage,
int MessageSeqNo)
MakeSignature function.
|
int |
QueryContextAttributes(Sspi.CtxtHandle phContext,
int ulAttribute,
Structure pBuffer)
Enables a transport application to query a security package for certain
attributes of a security context.
|
int |
QueryCredentialsAttributes(Sspi.CredHandle phCredential,
int ulAttribute,
Structure pBuffer)
Retrieves the attributes of a credential, such as the name associated
with the credential.
|
int |
QuerySecurityContextToken(Sspi.CtxtHandle phContext,
WinNT.HANDLEByReference phToken)
The QuerySecurityContextToken function obtains the access token for a client security context
and uses it directly.
|
int |
QuerySecurityPackageInfo(java.lang.String pszPackageName,
Sspi.PSecPkgInfo ppPackageInfo)
Retrieves information about a specified security package.
|
int |
RevertSecurityContext(Sspi.CtxtHandle phContext)
Allows a security package to discontinue the impersonation of the caller and restore its
own security context.
|
int |
VerifySignature(Sspi.CtxtHandle phContext,
Sspi.SecBufferDesc pMessage,
int MessageSeqNo,
IntByReference pfQOP)
VerifySignature function.
|
static final Secur32 INSTANCE
boolean GetUserNameEx(int nameFormat,
char[] lpNameBuffer,
IntByReference len)
nameFormat - The format of the name.lpNameBuffer - A pointer to a buffer that receives the name in the specified format.len - On input, the size of the buffer, on output the number of characters copied into the buffer, not including the terminating null character.int AcquireCredentialsHandle(java.lang.String pszPrincipal,
java.lang.String pszPackage,
int fCredentialUse,
WinNT.LUID pvLogonID,
Pointer pAuthData,
Pointer pGetKeyFn,
Pointer pvGetKeyArgument,
Sspi.CredHandle phCredential,
Sspi.TimeStamp ptsExpiry)
pszPrincipal - A pointer to a null-terminated string that specifies the name of the principal whose
credentials the handle will reference.pszPackage - A pointer to a null-terminated string that specifies the name of the security package
with which these credentials will be used.fCredentialUse - A flag that indicates how these credentials will be used.pvLogonID - A pointer to a locally unique identifier (LUID) that identifies the user.pAuthData - A pointer to package-specific data. This parameter can be NULL, which indicates
that the default credentials for that package must be used. To use supplied
credentials, pass a Sspi.SEC_WINNT_AUTH_IDENTITY
structure that includes those credentials in this parameter.pGetKeyFn - This parameter is not used and should be set to NULL.pvGetKeyArgument - This parameter is not used and should be set to NULL.phCredential - A pointer to a CredHandle structure to receive the credential handle.ptsExpiry - A pointer to a TimeStamp structure that receives the time at which the returned
credentials expire. The value returned in this TimeStamp structure depends on
the security package. The security package must return this value in local time.int InitializeSecurityContext(Sspi.CredHandle phCredential, Sspi.CtxtHandle phContext, java.lang.String pszTargetName, int fContextReq, int Reserved1, int TargetDataRep, Sspi.SecBufferDesc pInput, int Reserved2, Sspi.CtxtHandle phNewContext, Sspi.SecBufferDesc pOutput, IntByReference pfContextAttr, Sspi.TimeStamp ptsExpiry)
phCredential - A handle to the credentials returned by AcquireCredentialsHandle. This handle is
used to build the security context. The InitializeSecurityContext function requires
at least OUTBOUND credentials.phContext - A pointer to a CtxtHandle structure. On the first call to InitializeSecurityContext,
this pointer is NULL. On the second call, this parameter is a pointer to the handle
to the partially formed context returned in the phNewContext parameter by the first
call.pszTargetName - A pointer to a null-terminated string that indicates the target of the context.
The string contents are security-package specific.fContextReq - Bit flags that indicate requests for the context. Not all packages can support all
requirements. Flags used for this parameter are prefixed with ISC_REQ_, for example,
ISC_REQ_DELEGATE.Reserved1 - This parameter is reserved and must be set to zero.TargetDataRep - The data representation, such as byte ordering, on the target. This parameter can be
either SECURITY_NATIVE_DREP or SECURITY_NETWORK_DREP.pInput - A pointer to a SecBufferDesc structure that contains pointers to the buffers supplied
as input to the package. The pointer must be NULL on the first call to the function.
On subsequent calls to the function, it is a pointer to a buffer allocated with enough
memory to hold the token returned by the remote peer.Reserved2 - This parameter is reserved and must be set to zero.phNewContext - A pointer to a CtxtHandle structure. On the first call to InitializeSecurityContext,
this pointer receives the new context handle. On the second call, phNewContext can be
the same as the handle specified in the phContext parameter.pOutput - A pointer to a SecBufferDesc structure that contains pointers to the SecBuffer structure
that receives the output data. If a buffer was typed as SEC_READWRITE in the input, it
will be there on output. The system will allocate a buffer for the security token if
requested (through ISC_REQ_ALLOCATE_MEMORY) and fill in the address in the buffer
descriptor for the security token.pfContextAttr - A pointer to a variable to receive a set of bit flags that indicate the attributes of
the established context. Flags used for this parameter are prefixed with ISC_RET,
such as ISC_RET_DELEGATE.ptsExpiry - A pointer to a TimeStamp structure that receives the expiration time of the context.
It is recommended that the security package always return this value in local time.
This parameter is optional and NULL should be passed for short-lived clients.int DeleteSecurityContext(Sspi.CtxtHandle phContext)
phContext - Handle of the security context to delete.int FreeCredentialsHandle(Sspi.CredHandle phCredential)
phCredential - A pointer to the credential handle obtained by using the AcquireCredentialsHandle
function.int AcceptSecurityContext(Sspi.CredHandle phCredential, Sspi.CtxtHandle phContext, Sspi.SecBufferDesc pInput, int fContextReq, int TargetDataRep, Sspi.CtxtHandle phNewContext, Sspi.SecBufferDesc pOutput, IntByReference pfContextAttr, Sspi.TimeStamp ptsTimeStamp)
phCredential - A handle to the credentials of the server. The server calls the AcquireCredentialsHandle
function with either the SECPKG_CRED_INBOUND or SECPKG_CRED_BOTH flag set to retrieve
this handle.phContext - A pointer to a CtxtHandle structure. On the first call to AcceptSecurityContext,
this pointer is NULL. On subsequent calls, phContext is the handle to the partially
formed context that was returned in the phNewContext parameter by the first call.pInput - A pointer to a SecBufferDesc structure generated by a client call to
InitializeSecurityContext that contains the input buffer descriptor.fContextReq - Bit flags that specify the attributes required by the server to establish the
context. Bit flags can be combined by using bitwise-OR operations.TargetDataRep - The data representation, such as byte ordering, on the target. This parameter can
be either SECURITY_NATIVE_DREP or SECURITY_NETWORK_DREP.phNewContext - A pointer to a CtxtHandle structure. On the first call to AcceptSecurityContext,
this pointer receives the new context handle. On subsequent calls, phNewContext
can be the same as the handle specified in the phContext parameter.pOutput - A pointer to a SecBufferDesc structure that contains the output buffer descriptor.
This buffer is sent to the client for input into additional calls to
InitializeSecurityContext. An output buffer may be generated even if the function
returns SEC_E_OK. Any buffer generated must be sent back to the client application.pfContextAttr - A pointer to a variable that receives a set of bit flags that indicate the
attributes of the established context. For a description of the various attributes,
see Context Requirements. Flags used for this parameter are prefixed with ASC_RET,
for example, ASC_RET_DELEGATE.ptsTimeStamp - A pointer to a TimeStamp structure that receives the expiration time of the context.int CompleteAuthToken(Sspi.CtxtHandle phContext, Sspi.SecBufferDesc pToken)
This function is supported only by the Digest security support provider (SSP).
CompleteAuthToken is used on the server side only.
phContext - A handle of the context that needs to be completed.pToken - A Sspi.SecBufferDesc structure that contains the
buffer descriptor for the entire message.If the function fails, it returns one of the following error codes.
| Return code | Description |
|---|---|
| SEC_E_INVALID_HANDLE | The handle that was passed to the function is not valid. |
| SEC_E_INVALID_TOKEN | The token that was passed to the function is not valid. |
| SEC_E_OUT_OF_SEQUENCE | The client's security context was located, but the message number is incorrect. This return value is used with the Digest SSP. |
| SEC_E_MESSAGE_ALTERED | The client's security context was located, but the client's message has been tampered with. This return value is used with the Digest SSP. |
| SEC_E_INTERNAL_ERROR | An error occurred that did not map to an SSPI error code. |
int EnumerateSecurityPackages(IntByReference pcPackages, Sspi.PSecPkgInfo ppPackageInfo)
pcPackages - A pointer to a int variable that receives the number of packages returned.ppPackageInfo - A pointer to a variable that receives a pointer to an array of SecPkgInfo structures.
Each structure contains information from the security support provider (SSP) that
describes a security package that is available within that SSP.int FreeContextBuffer(Pointer buffer)
buffer - A pointer to memory allocated by the security package.int QuerySecurityContextToken(Sspi.CtxtHandle phContext, WinNT.HANDLEByReference phToken)
phContext - Handle of the context to query.phToken - Returned handle to the access token.int ImpersonateSecurityContext(Sspi.CtxtHandle phContext)
phContext - The handle of the context to impersonate. This handle must have been obtained by a call
to the AcceptSecurityContext function.int RevertSecurityContext(Sspi.CtxtHandle phContext)
phContext - Handle of the security context being impersonated. This handle must have been obtained in
the call to the AcceptSecurityContext function and used in the call to the
ImpersonateSecurityContext function.int QueryContextAttributes(Sspi.CtxtHandle phContext, int ulAttribute, Structure pBuffer)
phContext - A handle to the security context to be queried.ulAttribute - Specifies the attribute of the context to be returned. This
parameter can be one of the SECPKG_ATTR_* values defined in
Sspi.pBuffer - A pointer to a structure that receives the attributes. The
type of structure pointed to depends on the value specified in
the ulAttribute parameter.int QueryCredentialsAttributes(Sspi.CredHandle phCredential, int ulAttribute, Structure pBuffer)
phCredential - A handle of the credentials to be queried.ulAttribute - Specifies the attribute of the context to be returned.
This parameter can be one of the SECPKG_ATTR_* values
defined in Sspi.pBuffer - A pointer to a structure that receives the attributes.
The type of structure pointed to depends on the value
specified in the ulAttribute parameter.int QuerySecurityPackageInfo(java.lang.String pszPackageName,
Sspi.PSecPkgInfo ppPackageInfo)
pszPackageName - Name of the security package.ppPackageInfo - Variable that receives a pointer to a SecPkgInfo
structure containing information about the
specified security package.int EncryptMessage(Sspi.CtxtHandle phContext, int fQOP, Sspi.SecBufferDesc pMessage, int MessageSeqNo)
The EncryptMessage (Kerberos) function encrypts a message to provide privacy. EncryptMessage (Kerberos) allows an application to choose among cryptographic algorithms supported by the chosen mechanism. The EncryptMessage (Kerberos) function uses the security context referenced by the context handle. Some packages do not have messages to be encrypted or decrypted but rather provide an integrity hash that can be checked.
phContext - A handle to the security context to be used to encrypt
the message.fQOP - Package-specific flags that indicate the quality of
protection. A security package can use this parameter to
enable the selection of cryptographic algorithms. This
parameter can be the following flag:
Sspi.SECQOP_WRAP_NO_ENCRYPT.pMessage - A pointer to a SecBufferDesc structure. On input, the
structure references one or more SecBuffer structures
that can be of type SECBUFFER_DATA. That buffer contains
the message to be encrypted. The message is encrypted in
place, overwriting the original contents of the
structure.
The function does not process buffers with the SECBUFFER_READONLY attribute.
The length of the SecBuffer structure that contains the message must be no greater than cbMaximumMessage, which is obtained from the QueryContextAttributes (Kerberos) (SECPKG_ATTR_STREAM_SIZES) function.
Applications that do not use SSL must supply a SecBuffer of type SECBUFFER_PADDING.
MessageSeqNo - The sequence number that the transport application
assigned to the message. If the transport application
does not maintain sequence numbers, this parameter
must be zero.int VerifySignature(Sspi.CtxtHandle phContext, Sspi.SecBufferDesc pMessage, int MessageSeqNo, IntByReference pfQOP)
Verifies that a message signed by using the MakeSignature function was received in the correct sequence and has not been modified.
Warning
The VerifySignature function will fail if the message was signed using the RsaSignPssSha512 algorithm on a different version of Windows. For example, a message that was signed by calling the MakeSignature function on Windows 8 will cause the VerifySignature function on Windows 8.1 to fail.
phContext - A handle to the security context to use for the
message.pMessage - Pointer to a SecBufferDesc structure that references
a set of SecBuffer structures that contain the
message and signature to verify. The signature is in
a SecBuffer structure of type SECBUFFER_TOKEN.MessageSeqNo - Specifies the sequence number expected by the
transport application, if any. If the transport
application does not maintain sequence numbers, this
parameter is zero.pfQOP - Pointer to a ULONG variable that receives
package-specific flags that indicate the quality of
protection.
Some security packages ignore this parameter.
If the function determines that the message is not correct according to the information in the signature, the return value can be one of the following error codes.
| Return code | Description |
|---|---|
| SEC_E_OUT_OF_SEQUENCE | The message was not received in the correct sequence. |
| SEC_E_MESSAGE_ALTERED | The message has been altered. |
| SEC_E_INVALID_HANDLE | The context handle specified by phContext is not valid. |
| SEC_E_INVALID_TOKEN | pMessage did not contain a valid SECBUFFER_TOKEN buffer, or contained too few buffers. |
| SEC_E_QOP_NOT_SUPPORTED | The quality of protection negotiated between the client and server did not include integrity checking. |
int MakeSignature(Sspi.CtxtHandle phContext, int fQOP, Sspi.SecBufferDesc pMessage, int MessageSeqNo)
The MakeSignature function generates a cryptographic checksum of the message, and also includes sequencing information to prevent message loss or insertion. MakeSignature allows the application to choose between several cryptographic algorithms, if supported by the chosen mechanism. The MakeSignature function uses the security context referenced by the context handle.
Remarks
Remarks
The MakeSignature function generates a signature that is based on the message and the session key for the context.
The VerifySignature function verifies the messages signed by the MakeSignature function.
If the transport application created the security context to support sequence detection and the caller provides a sequence number, the function includes this information in the signature. This protects against reply, insertion, and suppression of messages. The security package incorporates the sequence number passed down from the transport application.
phContext - A handle to the security context to use to sign the
message.fQOP - Package-specific flags that indicate the quality of
protection. A security package can use this parameter
to enable the selection of cryptographic algorithms.
When using the Digest SSP, this parameter must be set to zero.
pMessage - A pointer to a SecBufferDesc structure. On input, the
structure references one or more SecBuffer structures
that contain the message to be signed. The function
does not process buffers with the
SECBUFFER_READONLY_WITH_CHECKSUM attribute.
The SecBufferDesc structure also references a SecBuffer structure of type SECBUFFER_TOKEN that receives the signature.
When the Digest SSP is used as an HTTP authentication protocol, the buffers should be configured as follows.
| Buffer #/buffer type | Meaning |
|---|---|
| 0 / SECBUFFER_TOKEN | Empty. |
| 1 / SECBUFFER_PKG_PARAMS | Method. |
| 2 / SECBUFFER_PKG_PARAMS | URL. |
| 3 / SECBUFFER_PKG_PARAMS | HEntity. For more information, see Input Buffers for the Digest Challenge Response. |
| 4 / SECBUFFER_PADDING | Empty. Receives the signature. |
When the Digest SSP is used as an SASL mechanism, the buffers should be configured as follows.
| Buffer #/buffer type | Meaning |
|---|---|
| 0 / SECBUFFER_TOKEN | Empty. Receives the signature. This buffer must be large enough to hold the largest possible signature. Determine the size required by calling the QueryContextAttributes (General) function and specifying SECPKG_ATTR_SIZES. Check the returned SecPkgContext_Sizes structure member cbMaxSignature. |
| 1 / SECBUFFER_DATA | Message to be signed. |
| 2 / SECBUFFER_PADDING | Empty. |
MessageSeqNo - *
The sequence number that the transport application
assigned to the message. If the transport application
does not maintain sequence numbers, this parameter is
zero.
When using the Digest SSP, this parameter must be set to zero. The Digest SSP manages sequence numbering internally.
If the function fails, it returns one of the following error codes.
| Return code | Description |
|---|---|
| SEC_I_RENEGOTIATE | The remote party requires a new handshake sequence or the application has just initiated a shutdown. Return to the negotiation loop and call AcceptSecurityContext (General) or InitializeSecurityContext (General) again. An empty input buffer is passed in the first call. |
| SEC_E_INVALID_HANDLE | The context handle specified by phContext is not valid. |
| SEC_E_INVALID_TOKEN | pMessage did not contain a valid SECBUFFER_TOKEN buffer or contained too few buffers. |
| SEC_E_OUT_OF_SEQUENCE | The nonce count is out of sequence. |
| SEC_E_NO_AUTHENTICATING_AUTHORITY | The security context (phContext) must be revalidated. |
| STATUS_INVALID_PARAMETER | The nonce count is not numeric. |
| SEC_E_QOP_NOT_SUPPORTED | The quality of protection negotiated between the client and server did not include integrity checking. |
int DecryptMessage(Sspi.CtxtHandle phContext, Sspi.SecBufferDesc pMessage, int MessageSeqNo, IntByReference pfQOP)
The DecryptMessage (Kerberos) function decrypts a message. Some packages do not encrypt and decrypt messages but rather perform and check an integrity hash.
phContext - A handle to the security context to be used to
encrypt the message.pMessage - A pointer to a SecBufferDesc structure. On input, the
structure references one or more SecBuffer structures
that may be of type SECBUFFER_DATA. The buffer
contains the encrypted message. The encrypted message
is decrypted in place, overwriting the original
contents of its buffer.MessageSeqNo - The sequence number expected by the transport
application, if any. If the transport application
does not maintain sequence numbers, this parameter
must be set to zero.pfQOP - A pointer to a variable of type ULONG that receives
package-specific flags that indicate the quality of
protection. This parameter can be the following flag:
Sspi.SECQOP_WRAP_NO_ENCRYPT.