Top Description Inners Fields Methods
com.sun.jna.platform.win32

public Interface Secur32

extends StdCallLibrary
Imports
com.sun.jna.Native, .Pointer, .Structure, com.sun.jna.platform.win32.Sspi.CredHandle, .Sspi.CtxtHandle, .Sspi.PSecPkgInfo, .Sspi.SecBufferDesc, .Sspi.TimeStamp, .WinNT.HANDLEByReference, .WinNT.LUID, com.sun.jna.ptr.IntByReference, com.sun.jna.win32.StdCallLibrary, .W32APIOptions
Secur32.dll Interface.
Author
dblock[at]dblock.org

Nested and Inner Type Summary

Modifier and TypeClass and Description
public abstract static class
Secur32.EXTENDED_NAME_FORMAT

Specifies a format for a directory service object name.

Field Summary

Modifier and TypeField and Description
public static final Secur32
INSTANCE

Inherited from com.sun.jna.win32.StdCallLibrary:
FUNCTION_MAPPERSTDCALL_CONVENTION

Method Summary

Modifier and TypeMethod and Description
public int

Returns:

This function returns one of SEC_* values.
AcceptSecurityContext(Sspi.CredHandle
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.
phCredential, Sspi.CtxtHandle
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.
phContext, Sspi.SecBufferDesc
A pointer to a SecBufferDesc structure generated by a client call to InitializeSecurityContext that contains the input buffer descriptor.
pInput, int
Bit flags that specify the attributes required by the server to establish the context. Bit flags can be combined by using bitwise-OR operations.
fContextReq, int
The data representation, such as byte ordering, on the target. This parameter can be either SECURITY_NATIVE_DREP or SECURITY_NETWORK_DREP.
TargetDataRep, Sspi.CtxtHandle
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.
phNewContext, Sspi.SecBufferDesc
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.
pOutput, IntByReference
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.
pfContextAttr, Sspi.TimeStamp
A pointer to a TimeStamp structure that receives the expiration time of the context.
ptsTimeStamp)

The AcceptSecurityContext function enables the server component of a transport application to establish a security context between the server and a remote client.

public int

Returns:

If the function succeeds, the function returns one of the SEC_I_ success codes. If the function fails, the function returns one of the SEC_E_ error codes.
AcquireCredentialsHandle(String
A pointer to a null-terminated string that specifies the name of the principal whose credentials the handle will reference.
pszPrincipal, String
A pointer to a null-terminated string that specifies the name of the security package with which these credentials will be used.
pszPackage, int
A flag that indicates how these credentials will be used.
fCredentialUse, WinNT.LUID
A pointer to a locally unique identifier (LUID) that identifies the user.
pvLogonID, Pointer
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 com.sun.jna.platform.win32.Sspi.SEC_WINNT_AUTH_IDENTITY structure that includes those credentials in this parameter.
pAuthData, Pointer
This parameter is not used and should be set to NULL.
pGetKeyFn, Pointer
This parameter is not used and should be set to NULL.
pvGetKeyArgument, Sspi.CredHandle
A pointer to a CredHandle structure to receive the credential handle.
phCredential, Sspi.TimeStamp
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.
ptsExpiry)

The AcquireCredentialsHandle function acquires a handle to preexisting credentials of a security principal.

public int

Returns:

If the function succeeds, the function returns SEC_E_OK.

If the function fails, it returns one of the following error codes.

Return codeDescription
SEC_E_INVALID_HANDLEThe handle that was passed to the function is not valid.
SEC_E_INVALID_TOKENThe token that was passed to the function is not valid.
SEC_E_OUT_OF_SEQUENCEThe client's security context was located, but the message number is incorrect. This return value is used with the Digest SSP.
SEC_E_MESSAGE_ALTEREDThe 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_ERRORAn error occurred that did not map to an SSPI error code.
CompleteAuthToken(Sspi.CtxtHandle
A handle of the context that needs to be completed.
phContext, Sspi.SecBufferDesc
A Sspi.SecBufferDesc structure that contains the buffer descriptor for the entire message.
pToken)

The CompleteAuthToken function completes an authentication token.

public int

Returns:

If the function verifies that the message was received in the correct sequence, the function returns SEC_E_OK.
DecryptMessage(Sspi.CtxtHandle
A handle to the security context to be used to encrypt the message.
phContext, Sspi.SecBufferDesc
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.
pMessage, int
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.
MessageSeqNo, IntByReference
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.
pfQOP)

DecryptMessage (Kerberos) function

The DecryptMessage (Kerberos) function decrypts a message.

public int

Returns:

If the function succeeds, the return value is SEC_E_OK. If the function fails, the return value is SEC_E_INVALID_HANDLE;
DeleteSecurityContext(Sspi.CtxtHandle
Handle of the security context to delete.
phContext)

The DeleteSecurityContext function deletes the local data structures associated with the specified security context.

public int

Returns:

If the function succeeds, the function returns SEC_E_OK.
EncryptMessage(Sspi.CtxtHandle
A handle to the security context to be used to encrypt the message.
phContext, int
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.
fQOP, Sspi.SecBufferDesc
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.

pMessage, int
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.
MessageSeqNo)

EncryptMessage (Kerberos) function

The EncryptMessage (Kerberos) function encrypts a message to provide privacy.

public int

Returns:

If the function succeeds, the function returns SEC_E_OK. If the function fails, it returns a nonzero error code.
EnumerateSecurityPackages(IntByReference
A pointer to a int variable that receives the number of packages returned.
pcPackages, Sspi.PSecPkgInfo
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.
ppPackageInfo)

The EnumerateSecurityPackages function returns an array of SecPkgInfo structures that describe the security packages available to the client.

public int

Returns:

If the function succeeds, the function returns SEC_E_OK. If the function fails, it returns a nonzero error code.
FreeContextBuffer(Pointer
A pointer to memory allocated by the security package.
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.

public int

Returns:

If the function succeeds, the return value is SEC_E_OK. If the function fails, the return value is SEC_E_INVALID_HANDLE;
FreeCredentialsHandle(Sspi.CredHandle
A pointer to the credential handle obtained by using the AcquireCredentialsHandle function.
phCredential)

The FreeCredentialsHandle function notifies the security system that the credentials are no longer needed.

public boolean

Returns:

True if the function succeeds. False otherwise.
GetUserNameEx(int
The format of the name.
nameFormat, char[]
A pointer to a buffer that receives the name in the specified format.
lpNameBuffer, IntByReference
On input, the size of the buffer, on output the number of characters copied into the buffer, not including the terminating null character.
len)

Retrieves the name of the user or other security principal associated with the calling thread.

public int

Returns:

If the function succeeds, the function returns SEC_E_OK. If the function fails, it returns a SEC_E_INVALID_HANDLE, SEC_E_NO_IMPERSONATION or SEC_E_UNSUPPORTED_FUNCTION error code.
ImpersonateSecurityContext(Sspi.CtxtHandle
The handle of the context to impersonate. This handle must have been obtained by a call to the AcceptSecurityContext function.
phContext)

The ImpersonateSecurityContext function allows a server to impersonate a client by using a token previously obtained by a call to AcceptSecurityContext or QuerySecurityContextToken.

public int

Returns:

If the function succeeds, the function returns one of the SEC_I_ success codes. If the function fails, the function returns one of the SEC_E_ error codes.
InitializeSecurityContext(Sspi.CredHandle
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.
phCredential, Sspi.CtxtHandle
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.
phContext, String
A pointer to a null-terminated string that indicates the target of the context. The string contents are security-package specific.
pszTargetName, int
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.
fContextReq, int
This parameter is reserved and must be set to zero.
Reserved1, int
The data representation, such as byte ordering, on the target. This parameter can be either SECURITY_NATIVE_DREP or SECURITY_NETWORK_DREP.
TargetDataRep, Sspi.SecBufferDesc
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.
pInput, int
This parameter is reserved and must be set to zero.
Reserved2, Sspi.CtxtHandle
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.
phNewContext, Sspi.SecBufferDesc
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.
pOutput, IntByReference
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.
pfContextAttr, Sspi.TimeStamp
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.
ptsExpiry)

The InitializeSecurityContext function initiates the client side, outbound security context from a credential handle.

public int

Returns:

If the function succeeds, the function returns SEC_E_OK.

If the function fails, it returns one of the following error codes.

Return codeDescription
SEC_I_RENEGOTIATEThe 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_HANDLEThe context handle specified by phContext is not valid.
SEC_E_INVALID_TOKENpMessage did not contain a valid SECBUFFER_TOKEN buffer or contained too few buffers.
SEC_E_OUT_OF_SEQUENCEThe nonce count is out of sequence.
SEC_E_NO_AUTHENTICATING_AUTHORITYThe security context (phContext) must be revalidated.
STATUS_INVALID_PARAMETERThe nonce count is not numeric.
SEC_E_QOP_NOT_SUPPORTEDThe quality of protection negotiated between the client and server did not include integrity checking.
MakeSignature(Sspi.CtxtHandle
A handle to the security context to use to sign the message.
phContext, int
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.

fQOP, Sspi.SecBufferDesc
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 typeMeaning
0 / SECBUFFER_TOKENEmpty.
1 / SECBUFFER_PKG_PARAMSMethod.
2 / SECBUFFER_PKG_PARAMSURL.
3 / SECBUFFER_PKG_PARAMSHEntity. For more information, see Input Buffers for the Digest Challenge Response.
4 / SECBUFFER_PADDINGEmpty. Receives the signature.

When the Digest SSP is used as an SASL mechanism, the buffers should be configured as follows.

Buffer #/buffer typeMeaning
0 / SECBUFFER_TOKENEmpty. 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_DATAMessage to be signed.
2 / SECBUFFER_PADDINGEmpty.
pMessage, int
* 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.

MessageSeqNo)

MakeSignature function.

public int

Returns:

If the function succeeds, the return value is SEC_E_OK. If the function fails, the return value is a nonzero error code.
QueryContextAttributes(Sspi.CtxtHandle
A handle to the security context to be queried.
phContext, int
Specifies the attribute of the context to be returned. This parameter can be one of the SECPKG_ATTR_* values defined in Sspi.
ulAttribute, Structure
A pointer to a structure that receives the attributes. The type of structure pointed to depends on the value specified in the ulAttribute parameter.
pBuffer)

Enables a transport application to query a security package for certain attributes of a security context.

public int

Returns:

If the function succeeds, the return value is SEC_E_OK. If the function fails, the return value is a nonzero error code.
QueryCredentialsAttributes(Sspi.CredHandle
A handle of the credentials to be queried.
phCredential, int
Specifies the attribute of the context to be returned. This parameter can be one of the SECPKG_ATTR_* values defined in Sspi.
ulAttribute, Structure
A pointer to a structure that receives the attributes. The type of structure pointed to depends on the value specified in the ulAttribute parameter.
pBuffer)

Retrieves the attributes of a credential, such as the name associated with the credential.

public int

Returns:

If the function succeeds, the function returns SEC_E_OK. If the function fails, it returns a nonzero error code. One possible error code return is SEC_E_INVALID_HANDLE.
QuerySecurityContextToken(Sspi.CtxtHandle
Handle of the context to query.
phContext, WinNT.HANDLEByReference
Returned handle to the access token.
phToken)

The QuerySecurityContextToken function obtains the access token for a client security context and uses it directly.

public int

Returns:

If the function succeeds, the return value is SEC_E_OK. If the function fails, the return value is a nonzero error code.
QuerySecurityPackageInfo(String
Name of the security package.
pszPackageName, Sspi.PSecPkgInfo
Variable that receives a pointer to a SecPkgInfo structure containing information about the specified security package.
ppPackageInfo)

Retrieves information about a specified security package.

public int

Returns:

If the function succeeds, the return value is SEC_E_OK. If the function fails, the return value can be either SEC_E_INVALID_HANDLE or SEC_E_UNSUPPORTED_FUNCTION.
RevertSecurityContext(Sspi.CtxtHandle
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.
phContext)

Allows a security package to discontinue the impersonation of the caller and restore its own security context.

public int

Returns:

If the function verifies that the message was received in the correct sequence and has not been modified, the return value is SEC_E_OK.

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 codeDescription
SEC_E_OUT_OF_SEQUENCEThe message was not received in the correct sequence.
SEC_E_MESSAGE_ALTEREDThe message has been altered.
SEC_E_INVALID_HANDLEThe context handle specified by phContext is not valid.
SEC_E_INVALID_TOKENpMessage did not contain a valid SECBUFFER_TOKEN buffer, or contained too few buffers.
SEC_E_QOP_NOT_SUPPORTEDThe quality of protection negotiated between the client and server did not include integrity checking.
VerifySignature(Sspi.CtxtHandle
A handle to the security context to use for the message.
phContext, Sspi.SecBufferDesc
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.
pMessage, int
Specifies the sequence number expected by the transport application, if any. If the transport application does not maintain sequence numbers, this parameter is zero.
MessageSeqNo, IntByReference
Pointer to a ULONG variable that receives package-specific flags that indicate the quality of protection.

Some security packages ignore this parameter.

pfQOP)

VerifySignature function.

Field Detail

INSTANCEback to summary
public static final Secur32 INSTANCE

Method Detail

AcceptSecurityContextback to summary
public 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. The remote client uses the InitializeSecurityContext function to start the process of establishing a security context. The server can require one or more reply tokens from the remote client to complete establishing the security context.

Parameters
phCredential:Sspi.CredHandle

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:Sspi.CtxtHandle

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:Sspi.SecBufferDesc

A pointer to a SecBufferDesc structure generated by a client call to InitializeSecurityContext that contains the input buffer descriptor.

fContextReq:int

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:int

The data representation, such as byte ordering, on the target. This parameter can be either SECURITY_NATIVE_DREP or SECURITY_NETWORK_DREP.

phNewContext:Sspi.CtxtHandle

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:Sspi.SecBufferDesc

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:IntByReference

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:Sspi.TimeStamp

A pointer to a TimeStamp structure that receives the expiration time of the context.

Returns:int

This function returns one of SEC_* values.

AcquireCredentialsHandleback to summary
public int AcquireCredentialsHandle(String pszPrincipal, 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. This handle is required by the AcceptSecurityContext and InitializeSecurityContext functions. These can be either preexisting credentials, which are established through a system logon that is not described here, or the caller can provide alternative credentials.

Parameters
pszPrincipal:String

A pointer to a null-terminated string that specifies the name of the principal whose credentials the handle will reference.

pszPackage:String

A pointer to a null-terminated string that specifies the name of the security package with which these credentials will be used.

fCredentialUse:int

A flag that indicates how these credentials will be used.

pvLogonID:WinNT.LUID

A pointer to a locally unique identifier (LUID) that identifies the user.

pAuthData:Pointer

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 com.sun.jna.platform.win32.Sspi.SEC_WINNT_AUTH_IDENTITY structure that includes those credentials in this parameter.

pGetKeyFn:Pointer

This parameter is not used and should be set to NULL.

pvGetKeyArgument:Pointer

This parameter is not used and should be set to NULL.

phCredential:Sspi.CredHandle

A pointer to a CredHandle structure to receive the credential handle.

ptsExpiry:Sspi.TimeStamp

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.

Returns:int

If the function succeeds, the function returns one of the SEC_I_ success codes. If the function fails, the function returns one of the SEC_E_ error codes.

CompleteAuthTokenback to summary
public int CompleteAuthToken(Sspi.CtxtHandle phContext, Sspi.SecBufferDesc pToken)

The CompleteAuthToken function completes an authentication token. This function is used by protocols, such as DCE, that need to revise the security information after the transport application has updated some message parameters.

This function is supported only by the Digest security support provider (SSP).

CompleteAuthToken is used on the server side only.

Parameters
phContext:Sspi.CtxtHandle

A handle of the context that needs to be completed.

pToken:Sspi.SecBufferDesc

A Sspi.SecBufferDesc structure that contains the buffer descriptor for the entire message.

Returns:int

If the function succeeds, the function returns SEC_E_OK.

If the function fails, it returns one of the following error codes.

Return codeDescription
SEC_E_INVALID_HANDLEThe handle that was passed to the function is not valid.
SEC_E_INVALID_TOKENThe token that was passed to the function is not valid.
SEC_E_OUT_OF_SEQUENCEThe client's security context was located, but the message number is incorrect. This return value is used with the Digest SSP.
SEC_E_MESSAGE_ALTEREDThe 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_ERRORAn error occurred that did not map to an SSPI error code.
DecryptMessageback to summary
public int DecryptMessage(Sspi.CtxtHandle phContext, Sspi.SecBufferDesc pMessage, int MessageSeqNo, IntByReference pfQOP)

DecryptMessage (Kerberos) function

The DecryptMessage (Kerberos) function decrypts a message. Some packages do not encrypt and decrypt messages but rather perform and check an integrity hash.

Parameters
phContext:Sspi.CtxtHandle

A handle to the security context to be used to encrypt the message.

pMessage:Sspi.SecBufferDesc

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:int

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:IntByReference

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.

Returns:int

If the function verifies that the message was received in the correct sequence, the function returns SEC_E_OK.

See Also
MSDN Entry
DeleteSecurityContextback to summary
public int DeleteSecurityContext(Sspi.CtxtHandle phContext)

The DeleteSecurityContext function deletes the local data structures associated with the specified security context.

Parameters
phContext:Sspi.CtxtHandle

Handle of the security context to delete.

Returns:int

If the function succeeds, the return value is SEC_E_OK. If the function fails, the return value is SEC_E_INVALID_HANDLE;

EncryptMessageback to summary
public 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. 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.

Parameters
phContext:Sspi.CtxtHandle

A handle to the security context to be used to encrypt the message.

fQOP:int

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:Sspi.SecBufferDesc

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:int

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.

Returns:int

If the function succeeds, the function returns SEC_E_OK.

See Also
MSDN Entry
EnumerateSecurityPackagesback to summary
public 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.

Parameters
pcPackages:IntByReference

A pointer to a int variable that receives the number of packages returned.

ppPackageInfo:Sspi.PSecPkgInfo

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.

Returns:int

If the function succeeds, the function returns SEC_E_OK. If the function fails, it returns a nonzero error code.

FreeContextBufferback to summary
public 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.

Parameters
buffer:Pointer

A pointer to memory allocated by the security package.

Returns:int

If the function succeeds, the function returns SEC_E_OK. If the function fails, it returns a nonzero error code.

FreeCredentialsHandleback to summary
public int FreeCredentialsHandle(Sspi.CredHandle phCredential)

The FreeCredentialsHandle function notifies the security system that the credentials are no longer needed. An application calls this function to free the credential handle acquired in the call to the AcquireCredentialsHandle function. When all references to this credential set have been removed, the credentials themselves can be removed.

Parameters
phCredential:Sspi.CredHandle

A pointer to the credential handle obtained by using the AcquireCredentialsHandle function.

Returns:int

If the function succeeds, the return value is SEC_E_OK. If the function fails, the return value is SEC_E_INVALID_HANDLE;

GetUserNameExback to summary
public boolean GetUserNameEx(int nameFormat, char[] lpNameBuffer, IntByReference len)

Retrieves the name of the user or other security principal associated with the calling thread. You can specify the format of the returned name.

Parameters
nameFormat:int

The format of the name.

lpNameBuffer:char[]

A pointer to a buffer that receives the name in the specified format.

len:IntByReference

On input, the size of the buffer, on output the number of characters copied into the buffer, not including the terminating null character.

Returns:boolean

True if the function succeeds. False otherwise.

ImpersonateSecurityContextback to summary
public 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. This function allows the application server to act as the client, and thus all necessary access controls are enforced.

Parameters
phContext:Sspi.CtxtHandle

The handle of the context to impersonate. This handle must have been obtained by a call to the AcceptSecurityContext function.

Returns:int

If the function succeeds, the function returns SEC_E_OK. If the function fails, it returns a SEC_E_INVALID_HANDLE, SEC_E_NO_IMPERSONATION or SEC_E_UNSUPPORTED_FUNCTION error code.

InitializeSecurityContextback to summary
public int InitializeSecurityContext(Sspi.CredHandle phCredential, Sspi.CtxtHandle phContext, 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. The function is used to build a security context between the client application and a remote peer. InitializeSecurityContext returns a token that the client must pass to the remote peer, which the peer in turn submits to the local security implementation through the AcceptSecurityContext call. The token generated should be considered opaque by all callers. Typically, the InitializeSecurityContext function is called in a loop until a sufficient security context is established.

Parameters
phCredential:Sspi.CredHandle

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:Sspi.CtxtHandle

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:String

A pointer to a null-terminated string that indicates the target of the context. The string contents are security-package specific.

fContextReq:int

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:int

This parameter is reserved and must be set to zero.

TargetDataRep:int

The data representation, such as byte ordering, on the target. This parameter can be either SECURITY_NATIVE_DREP or SECURITY_NETWORK_DREP.

pInput:Sspi.SecBufferDesc

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:int

This parameter is reserved and must be set to zero.

phNewContext:Sspi.CtxtHandle

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:Sspi.SecBufferDesc

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:IntByReference

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:Sspi.TimeStamp

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.

Returns:int

If the function succeeds, the function returns one of the SEC_I_ success codes. If the function fails, the function returns one of the SEC_E_ error codes.

MakeSignatureback to summary
public int MakeSignature(Sspi.CtxtHandle phContext, int fQOP, Sspi.SecBufferDesc pMessage, int MessageSeqNo)

MakeSignature function.

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.

Parameters
phContext:Sspi.CtxtHandle

A handle to the security context to use to sign the message.

fQOP:int

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:Sspi.SecBufferDesc

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 typeMeaning
0 / SECBUFFER_TOKENEmpty.
1 / SECBUFFER_PKG_PARAMSMethod.
2 / SECBUFFER_PKG_PARAMSURL.
3 / SECBUFFER_PKG_PARAMSHEntity. For more information, see Input Buffers for the Digest Challenge Response.
4 / SECBUFFER_PADDINGEmpty. Receives the signature.

When the Digest SSP is used as an SASL mechanism, the buffers should be configured as follows.

Buffer #/buffer typeMeaning
0 / SECBUFFER_TOKENEmpty. 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_DATAMessage to be signed.
2 / SECBUFFER_PADDINGEmpty.
MessageSeqNo:int

* 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.

Returns:int

If the function succeeds, the function returns SEC_E_OK.

If the function fails, it returns one of the following error codes.

Return codeDescription
SEC_I_RENEGOTIATEThe 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_HANDLEThe context handle specified by phContext is not valid.
SEC_E_INVALID_TOKENpMessage did not contain a valid SECBUFFER_TOKEN buffer or contained too few buffers.
SEC_E_OUT_OF_SEQUENCEThe nonce count is out of sequence.
SEC_E_NO_AUTHENTICATING_AUTHORITYThe security context (phContext) must be revalidated.
STATUS_INVALID_PARAMETERThe nonce count is not numeric.
SEC_E_QOP_NOT_SUPPORTEDThe quality of protection negotiated between the client and server did not include integrity checking.
QueryContextAttributesback to summary
public 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.

Parameters
phContext:Sspi.CtxtHandle

A handle to the security context to be queried.

ulAttribute:int

Specifies the attribute of the context to be returned. This parameter can be one of the SECPKG_ATTR_* values defined in Sspi.

pBuffer:Structure

A pointer to a structure that receives the attributes. The type of structure pointed to depends on the value specified in the ulAttribute parameter.

Returns:int

If the function succeeds, the return value is SEC_E_OK. If the function fails, the return value is a nonzero error code.

QueryCredentialsAttributesback to summary
public int QueryCredentialsAttributes(Sspi.CredHandle phCredential, int ulAttribute, Structure pBuffer)

Retrieves the attributes of a credential, such as the name associated with the credential. The information is valid for any security context created with the specified credential.

Parameters
phCredential:Sspi.CredHandle

A handle of the credentials to be queried.

ulAttribute:int

Specifies the attribute of the context to be returned. This parameter can be one of the SECPKG_ATTR_* values defined in Sspi.

pBuffer:Structure

A pointer to a structure that receives the attributes. The type of structure pointed to depends on the value specified in the ulAttribute parameter.

Returns:int

If the function succeeds, the return value is SEC_E_OK. If the function fails, the return value is a nonzero error code.

QuerySecurityContextTokenback to summary
public int QuerySecurityContextToken(Sspi.CtxtHandle phContext, WinNT.HANDLEByReference phToken)

The QuerySecurityContextToken function obtains the access token for a client security context and uses it directly.

Parameters
phContext:Sspi.CtxtHandle

Handle of the context to query.

phToken:WinNT.HANDLEByReference

Returned handle to the access token.

Returns:int

If the function succeeds, the function returns SEC_E_OK. If the function fails, it returns a nonzero error code. One possible error code return is SEC_E_INVALID_HANDLE.

QuerySecurityPackageInfoback to summary
public int QuerySecurityPackageInfo(String pszPackageName, Sspi.PSecPkgInfo ppPackageInfo)

Retrieves information about a specified security package. This information includes the bounds on sizes of authentication information, credentials, and contexts.

Parameters
pszPackageName:String

Name of the security package.

ppPackageInfo:Sspi.PSecPkgInfo

Variable that receives a pointer to a SecPkgInfo structure containing information about the specified security package.

Returns:int

If the function succeeds, the return value is SEC_E_OK. If the function fails, the return value is a nonzero error code.

RevertSecurityContextback to summary
public int RevertSecurityContext(Sspi.CtxtHandle phContext)

Allows a security package to discontinue the impersonation of the caller and restore its own security context.

Parameters
phContext:Sspi.CtxtHandle

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.

Returns:int

If the function succeeds, the return value is SEC_E_OK. If the function fails, the return value can be either SEC_E_INVALID_HANDLE or SEC_E_UNSUPPORTED_FUNCTION.

VerifySignatureback to summary
public int VerifySignature(Sspi.CtxtHandle phContext, Sspi.SecBufferDesc pMessage, int MessageSeqNo, IntByReference pfQOP)

VerifySignature function.

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.

Parameters
phContext:Sspi.CtxtHandle

A handle to the security context to use for the message.

pMessage:Sspi.SecBufferDesc

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:int

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:IntByReference

Pointer to a ULONG variable that receives package-specific flags that indicate the quality of protection.

Some security packages ignore this parameter.

Returns:int

If the function verifies that the message was received in the correct sequence and has not been modified, the return value is SEC_E_OK.

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 codeDescription
SEC_E_OUT_OF_SEQUENCEThe message was not received in the correct sequence.
SEC_E_MESSAGE_ALTEREDThe message has been altered.
SEC_E_INVALID_HANDLEThe context handle specified by phContext is not valid.
SEC_E_INVALID_TOKENpMessage did not contain a valid SECBUFFER_TOKEN buffer, or contained too few buffers.
SEC_E_QOP_NOT_SUPPORTEDThe quality of protection negotiated between the client and server did not include integrity checking.
com.sun.jna.platform.win32 back to summary

public abstract Class Secur32.EXTENDED_NAME_FORMAT

extends Object
Class Inheritance
Specifies a format for a directory service object name. http://msdn.microsoft.com/en-us/library/ms724268(VS.85).aspx

Field Summary

Modifier and TypeField and Description
public static final int
NameCanonical

public static final int
NameCanonicalEx

public static final int
NameDisplay

public static final int
NameDnsDomain

public static final int
NameFullyQualifiedDN

public static final int
NameSamCompatible

public static final int
NameServicePrincipal

public static final int
NameUniqueId

public static final int
NameUnknown

public static final int
NameUserPrincipal

Constructor Summary

AccessConstructor and Description
public
EXTENDED_NAME_FORMAT()

Method Summary

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

NameCanonicalback to summary
public static final int NameCanonical
NameCanonicalExback to summary
public static final int NameCanonicalEx
NameDisplayback to summary
public static final int NameDisplay
NameDnsDomainback to summary
public static final int NameDnsDomain
NameFullyQualifiedDNback to summary
public static final int NameFullyQualifiedDN
NameSamCompatibleback to summary
public static final int NameSamCompatible
NameServicePrincipalback to summary
public static final int NameServicePrincipal
NameUniqueIdback to summary
public static final int NameUniqueId
NameUnknownback to summary
public static final int NameUnknown
NameUserPrincipalback to summary
public static final int NameUserPrincipal

Constructor Detail

EXTENDED_NAME_FORMATback to summary
public EXTENDED_NAME_FORMAT()