Kerberos Security Support Provider (Windows CE 5.0)

Article
09/14/2012

The Kerberos protocol defines how clients interact with a network authentication service. Clients obtain tickets from the Kerberos Key Distribution Center (KDC), and they present these tickets to servers when connections are established. Kerberos tickets represent the client's network credentials.

The Kerberos authentication protocol provides a mechanism for mutual authentication between entities before a secure network connection is established. In the protocol model, every client/server connection begins with authentication. Client and server, in turn, step through a sequence of actions designed to verify to the party on each end of the connection that the party on the other end is genuine. If authentication is successful, session setup completes and establishes a client/server session with enhanced security.

The sequence of actions involves the following elements:

Key Distribution Center (KDC)
Session keys
Tickets

Key Distribution Center (KDC)

To implement Kerberos, you must have a KDC, which is a central authority performing dual roles: (1) authentication service to clients within its domain, and (2) ticket granting service to clients requesting connections to services or computers within its domain.

The following procedures show the two ways to specify the Kerberos KDC in your domain:

Specify the NetBIOS or DNS KDC name.

[HKEY_LOCAL_MACHINE\Comm\SecurityProviders\Kerberos]
[HKEY_LOCAL_MACHINE\Comm\SecurityProviders\Kerberos\NTDomains]
[HKEY_LOCAL_MACHINE\Comm\SecurityProviders\Kerberos\NTDomains\YOURDOMAIN]
    "KdcNames"="YOURKDCNAME"

Specify the IP address of the KDC

[HKEY_LOCAL_MACHINE\Comm\SecurityProviders\Kerberos\NTDomains\YOURDOMAIN.CORP.MICROSOFT.COM]
    "KdcNames"="123.45.6.78"

Session Keys

To help secure a connection with a server, the client begins by sending a request to the KDC, not to the server that the client wants to reach. The KDC creates and sends to the client a unique session key for the client and a server to use to authenticate each other. The KDC has access to both the client's master key and the server's master key. The KDC uses the server's master key to encrypt the server's copy of the session key, and uses the client's master key to encrypt the client's copy of the session key.

Tickets

Instead of sending the encrypted session keys to both principals, the KDC sends both the client's and the server's copies of the session key to the client. The client's copy of the session key is encrypted with the client's master key and therefore cannot be decrypted by any other entity. The server's copy of the session key is embedded, along with authorization data about the client, in a data structure called a ticket. The ticket is entirely encrypted with the server's master key and therefore cannot be read or changed by the client or any other entity that lacks access to the server's master key.

When the client receives the KDC's response, it extracts the ticket and its own copy of the session key, putting both aside in a cache. To establish a more protected session with the server, the client sends the server a message consisting of the ticket, still encrypted with the server's master key, and an authenticator message encrypted with the session key. The authenticator message contains the client's name and a timestamp in universal coordinated time. Together, the ticket and authenticator message are the client's credentials to the server.

When the server receives credentials from a client, it decrypts the ticket with its master key, extracts the session key, and then uses the session key to decrypt the client's authenticator message. If the server message is able to validate the client's message, the server knows that the client's credentials were issued by the KDC, a trusted authority. For mutual authentication, the server responds by using the session key to encrypt the timestamp from the client's authenticator message. This encrypted message is then sent to and decrypted by the client. If the returned message matches the timestamp in the original authenticator message, the server is authenticated.

The following steps show a brief outline of the process for client application authentication.

Call the AcquireCredentialsHandle function using the SEC_WINNT_AUTH_IDENTITY structure to specify the credentials. If the user saved a default NT domain name and password on the CE device, the application can use the cached credentials by passing NULL instead of the SEC_WINNT_AUTH_IDENTITY structure. If the Kerberos SSP cannot find the cached credentials, the function returns SEC_E_NO_CREDENTIALS.

The following code example shows how to make a connection.

SEC_WINNT_AUTH_IDENTITY AdditionalCredentials;
SECURITY_STATUS status;
CredHandle hCredential;
TimeStamp tsExpiry;
BOOL bSupplyCredentials;

// If there are additional credentials stored in lpszUserName, 
// lpszDomainName, and lpszPassword, fill them in here.
AdditionalCredentials.Flags = SEC_WINNT_AUTH_IDENTITY_UNICODE;

if (lpszUserName != NULL) 
{
  AdditionalCredentials.User = lpszUserName;
  AdditionalCredentials.UserLength = wcslen (lpszUserName);
}

if (lpszDomainName != NULL) 
{
  AdditionalCredentials.User = lpszDomainName;
  AdditionalCredentials.UserLength = wcslen (lpszDomainName);
}

if (lpszPassword != NULL) 
{
  AdditionalCredentials.User = lpszPassword;
  AdditionalCredentials.UserLength = wcslen (lpszPassword);
}

status = AcquireCredentialsHandle (
              NULL,                   // No principal name
              TEXT("Kerberos"),           // Package name
              SECPKG_CRED_OUTBOUND,   // Credential use flag
              NULL,                   // No logon identifier
              bSupplyCredentials ?  &AdditionalCredentials : NULL,
                                      // Package-specific data     
              NULL,                   // No GetKey function
              NULL,                   // No GetKey function argument
              &hCredential,           // Receives the new credential
              &tsExpiry);             // Receives the expiration 
                                      // time of the credential

Call the InitializeSecurityContext function to set up the security context.

In Kerberos, the pszTargetName parameter of the InitializeSecurityContext function call specifies the account name of the server that you are authenticating to. If the client wants to access a service, the pszTargetName parameter specifies the account name under whose security context the service is running.

The function returns SEC_E_OK or SEC_I_CONTINUE_NEEDED on success or an error code on failure. If the function is successful, the application passes the token buffer to the server. The token buffer is stored in the pvBuffer member of the SecBuffer structure.
Call the InitializeSecurityContext function again. Kerberos SSP may require one or two calls to InitializeSecurityContext; the return value from the function call indicates if a second call is necessary.

If the function returns SEC_E_OK, the application transmits the output security buffer and the buffer length to the server, as it did after the first call. If the function fails, an error value returns.

The following security context flags are used in Kerberos.
- ALLOCATE_MEMORY
- CONFIDENTIALITY
- CONNECTION
- DATAGRAM
- DELEGATE
- EXTENDED ERROR
- INTEGRITY
- MUTUAL_AUTH
- REPLAY_DETECT
- SEQUENCE_DETECT
- STREAM
- USE_DCE_STYLE
- USE_SESSION_KEY
For more information about using the context flags, see Context Requirements.

Kerberos Security Support Provider (Windows CE 5.0)

Key Distribution Center (KDC)

Session Keys

Tickets

See Also

Additional resources