KERB_RETRIEVE_TKT_REQUEST structure (ntsecapi.h)

  • Article

The KERB_RETRIEVE_TKT_REQUEST structure contains information used to retrieve a ticket.

It is used by LsaCallAuthenticationPackage.The Kerberos ticket is defined in Internet RFC 4120. For more information, see http://www.ietf.org.

Syntax

typedef struct _KERB_RETRIEVE_TKT_REQUEST {
  KERB_PROTOCOL_MESSAGE_TYPE MessageType;
  LUID                       LogonId;
  UNICODE_STRING             TargetName;
  ULONG                      TicketFlags;
  ULONG                      CacheOptions;
  LONG                       EncryptionType;
  SecHandle                  CredentialsHandle;
} KERB_RETRIEVE_TKT_REQUEST, *PKERB_RETRIEVE_TKT_REQUEST;

Members

MessageType

KERB_PROTOCOL_MESSAGE_TYPE value indicating the type of request being made. This member must be set to KerbRetrieveEncodedTicketMessage.

LogonId

LUID structure containing the logon session identifier. This can be zero for the current user's logon session. If not zero, the caller must have the SeTcbPrivilege privilege set. If this fails, the Kerberos authentication package sets the ProtocolStatus parameter of LsaCallAuthenticationPackage to STATUS_ACCESS_DENIED.

TargetName

UNICODE_STRING containing the name of the target service.

TicketFlags

Contains flags specifying uses for the retrieved ticket. If TicketFlags is set to zero and if there is a matching ticket found in the cache, then that ticket will be returned, regardless of its flag values. If there is no match in the cache, a new ticket with the default flag values will be requested.

If this member is not set to zero, the returned ticket will not be cached.

CacheOptions

Indicates options for searching the cache. Set this member to zero to indicate that the cache should be searched and if no ticket if found, a new ticket should be requested.

If this member is not set to zero, the returned ticket will not be cached.

CacheOptions can contain the following values.

Value Meaning
KERB_RETRIEVE_TICKET_DONT_USE_CACHE
1
 Always request a new ticket; do not search the cache.

If a ticket is obtained, the Kerberos authentication package returns STATUS_SUCCESS in the ProtocolStatus parameter of the LsaCallAuthenticationPackage function.
KERB_RETRIEVE_TICKET_USE_CREDHANDLE
4
 Use the CredentialsHandle member instead of LogonId to identify the logon session. The credential handle is used as the client credential for which the ticket is retrieved

Note  This option is not available for 32-bit Windows-based applications running on 64-bit Windows.
KERB_RETRIEVE_TICKET_USE_CACHE_ONLY
2
 Return only a previously cached ticket.

If such a ticket is not found, the Kerberos authentication package returns STATUS_OBJECT_NAME_NOT_FOUND in the ProtocolStatus parameter of the LsaCallAuthenticationPackage function.
KERB_RETRIEVE_TICKET_AS_KERB_CRED
8
 Return the ticket as a Kerberos credential. The Kerberos ticket is defined in Internet RFC 4120 as KRB_CRED. For more information, see http://www.ietf.org.
KERB_RETRIEVE_TICKET_WITH_SEC_CRED
10
 Not implemented.
KERB_RETRIEVE_TICKET_CACHE_TICKET
20
 Return the ticket that is currently in the cache. If the ticket is not in the cache, it is requested and then cached. This flag should not be used with the KERB_RETRIEVE_TICKET_DONT_USE_CACHE flag.

Windows XP with SP1 and earlier and Windows Server 2003:  This option is not available.
KERB_RETRIEVE_TICKET_MAX_LIFETIME
40
 Return a fresh ticket with maximum allowed time by the policy. The ticker is cached afterwards. Use of this flag implies that KERB_RETRIEVE_TICKET_USE_CACHE_ONLY is not set and KERB_RETRIEVE_TICKET_CACHE_TICKET is set.

Windows Vista, Windows Server 2008, Windows XP with SP1 and earlier and Windows Server 2003:  This option is not available.

EncryptionType

Specifies the type of encryption to use for the requested ticket. If this member is not set to zero, the returned ticket will not be cached.

This member can have one of the following values.

Value Meaning
KERB_ETYPE_DES_CBC_CRC
 Use DES encryption in cipher-block-chaining mode with a CRC-32 checksum.
KERB_ETYPE_DES_CBC_MD4
 Use DES encryption in cipher-block-chaining mode with a MD4 checksum.
KERB_ETYPE_DES_CBC_MD5
 Use DES encryption in cipher-block-chaining mode with a MD5 checksum.
KERB_ETYPE_NULL
 Use no encryption.
KERB_ETYPE_RC4_HMAC_NT
 Use the RC4 stream cipher with a hash-based Message Authentication Code (MAC), as used by Windows.
KERB_ETYPE_RC4_MD4
 Use the RC4 stream cipher with the MD4 hash function.
>127
 Values greater than 127 are reserved for local values and may change without notice.

CredentialsHandle

An SSPI credentials handle used in place of a logon session identifier.

Requirements

Requirement Value
Minimum supported client Windows XP [desktop apps only]
Minimum supported server Windows Server 2003 [desktop apps only]
Header ntsecapi.h