Next: , Previous: , Up: Programming Manual   [Contents][Index]


5.8 TGS Functions

The Ticket Granting Service (TGS) is used to get subsequent tickets, authenticated by other tickets (so called ticket granting tickets). The following illustrates the TGS-REQ and TGS-REP ASN.1 structures.

-- Request --

TGS-REQ		::= KDC-REQ {12}

KDC-REQ {INTEGER:tagnum}	::= [APPLICATION tagnum] SEQUENCE {
	pvno		[1] INTEGER (5) -- first tag is [1], not [0] --,
	msg-type	[2] INTEGER (tagnum),
	padata		[3] SEQUENCE OF PA-DATA OPTIONAL,
	req-body	[4] KDC-REQ-BODY
}

KDC-REQ-BODY	::= SEQUENCE {
	kdc-options		[0] KDCOptions,
	cname			[1] PrincipalName OPTIONAL
				    -- Used only in AS-REQ --,
	realm			[2] Realm
				    -- Server's realm
				    -- Also client's in AS-REQ --,
	sname			[3] PrincipalName OPTIONAL,
	from			[4] KerberosTime OPTIONAL,
	till			[5] KerberosTime,
	rtime			[6] KerberosTime OPTIONAL,
	nonce			[7] UInt32,
	etype			[8] SEQUENCE OF Int32 -- EncryptionType
				    -- in preference order --,
	addresses		[9] HostAddresses OPTIONAL,
	enc-authorization-data	[10] EncryptedData {
					AuthorizationData,
					{ keyuse-TGSReqAuthData-sesskey
					  | keyuse-TGSReqAuthData-subkey }
				     } OPTIONAL,
	additional-tickets	[11] SEQUENCE OF Ticket OPTIONAL
}

-- Reply --

TGS-REP		::= KDC-REP {13, EncTGSRepPart,
			{ keyuse-EncTGSRepPart-sesskey
			  | keyuse-EncTGSRepPart-subkey }}

KDC-REP {INTEGER:tagnum,
	 TypeToEncrypt,
	 UInt32:KeyUsages}	::= [APPLICATION tagnum] SEQUENCE {
	pvno		[0] INTEGER (5),
	msg-type	[1] INTEGER (tagnum),
	padata		[2] SEQUENCE OF PA-DATA OPTIONAL,
	crealm		[3] Realm,
	cname		[4] PrincipalName,
	ticket		[5] Ticket,
	enc-part	[6] EncryptedData {TypeToEncrypt, KeyUsages}
}

EncTGSRepPart	::= [APPLICATION 26] EncKDCRepPart

EncKDCRepPart	::= SEQUENCE {
	key		[0] EncryptionKey,
	last-req	[1] LastReq,
	nonce		[2] UInt32,
	key-expiration	[3] KerberosTime OPTIONAL,
	flags		[4] TicketFlags,
	authtime	[5] KerberosTime,
	starttime	[6] KerberosTime OPTIONAL,
	endtime		[7] KerberosTime,
	renew-till	[8] KerberosTime OPTIONAL,
	srealm		[9] Realm,
	sname		[10] PrincipalName,
	caddr		[11] HostAddresses OPTIONAL
}

shishi_tgs

Function: int shishi_tgs (Shishi * handle, Shishi_tgs ** tgs)

handle: shishi handle as allocated by shishi_init().
tgs: holds pointer to newly allocate Shishi_tgs structure.

Description: Allocate a new TGS exchange variable.

Return value: Returns SHISHI_OK iff successful.

shishi_tgs_done

Function: void shishi_tgs_done (Shishi_tgs * tgs)

tgs: structure that holds information about AS exchange

Description: Deallocate resources associated with TGS exchange. This should be called by the application when it no longer need to utilize the TGS exchange handle.

shishi_tgs_tgtkt

Function: Shishi_tkt * shishi_tgs_tgtkt (Shishi_tgs * tgs)

tgs: structure that holds information about TGS exchange

Description: Get Ticket-granting-ticket from TGS exchange.

Return value: Returns the ticket-granting-ticket used in the TGS exchange, or NULL if not yet set or an error occured.

shishi_tgs_tgtkt_set

Function: void shishi_tgs_tgtkt_set (Shishi_tgs * tgs, Shishi_tkt * tgtkt)

tgs: structure that holds information about TGS exchange
tgtkt: ticket granting ticket to store in TGS.

Description: Set the Ticket in the TGS exchange.

shishi_tgs_ap

Function: Shishi_ap * shishi_tgs_ap (Shishi_tgs * tgs)

tgs: structure that holds information about TGS exchange

Description: Get the AP from TGS exchange.

Return value: Returns the AP exchange (part of TGS-REQ) from the TGS exchange, or NULL if not yet set or an error occured.

shishi_tgs_req

Function: Shishi_asn1 shishi_tgs_req (Shishi_tgs * tgs)

tgs: structure that holds information about TGS exchange

Description: Get the TGS-REQ from TGS exchange.

Return value: Returns the generated TGS-REQ from the TGS exchange, or NULL if not yet set or an error occured.

shishi_tgs_req_set

Function: void shishi_tgs_req_set (Shishi_tgs * tgs, Shishi_asn1 tgsreq)

tgs: structure that holds information about TGS exchange
tgsreq: tgsreq to store in TGS.

Description: Set the TGS-REQ in the TGS exchange.

shishi_tgs_req_der

Function: int shishi_tgs_req_der (Shishi_tgs * tgs, char ** out, size_t * outlen)

tgs: structure that holds information about TGS exchange
out: output array with newly allocated DER encoding of TGS-REQ.
outlen: length of output array with DER encoding of TGS-REQ.

Description: DER encode TGS-REQ. out is allocated by this function, and it is the responsibility of caller to deallocate it.

Return value: Returns SHISHI_OK iff successful.

shishi_tgs_req_der_set

Function: int shishi_tgs_req_der_set (Shishi_tgs * tgs, char * der, size_t derlen)

tgs: structure that holds information about TGS exchange
der: input array with DER encoded AP-REQ.
derlen: length of input array with DER encoded AP-REQ.

Description: DER decode TGS-REQ and set it TGS exchange. If decoding fails, the TGS-REQ in the TGS exchange remains.

Return value: Returns SHISHI_OK.

shishi_tgs_req_process

Function: int shishi_tgs_req_process (Shishi_tgs * tgs)

tgs: structure that holds information about TGS exchange

Description: Process new TGS-REQ and set ticket. The key to decrypt the TGS-REQ is taken from the EncKDCReqPart of the TGS tgticket.

Return value: Returns SHISHI_OK iff successful.

shishi_tgs_req_build

Function: int shishi_tgs_req_build (Shishi_tgs * tgs)

tgs: structure that holds information about TGS exchange

Description: Checksum data in authenticator and add ticket and authenticator to TGS-REQ.

Return value: Returns SHISHI_OK iff successful.

shishi_tgs_rep

Function: Shishi_asn1 shishi_tgs_rep (Shishi_tgs * tgs)

tgs: structure that holds information about TGS exchange

Description: Get TGS-REP from TGS exchange.

Return value: Returns the received TGS-REP from the TGS exchange, or NULL if not yet set or an error occured.

shishi_tgs_rep_der

Function: int shishi_tgs_rep_der (Shishi_tgs * tgs, char ** out, size_t * outlen)

tgs: structure that holds information about TGS exchange
out: output array with newly allocated DER encoding of TGS-REP.
outlen: length of output array with DER encoding of TGS-REP.

Description: DER encode TGS-REP. out is allocated by this function, and it is the responsibility of caller to deallocate it.

Return value: Returns SHISHI_OK iff successful.

shishi_tgs_rep_process

Function: int shishi_tgs_rep_process (Shishi_tgs * tgs)

tgs: structure that holds information about TGS exchange

Description: Process new TGS-REP and set ticket. The key to decrypt the TGS-REP is taken from the EncKDCRepPart of the TGS tgticket.

Return value: Returns SHISHI_OK iff successful.

shishi_tgs_rep_build

Function: int shishi_tgs_rep_build (Shishi_tgs * tgs, int keyusage, Shishi_key * key)

tgs: structure that holds information about TGS exchange
keyusage: keyusage integer.
key: user’s key, used to encrypt the encrypted part of the TGS-REP.

Description: Build TGS-REP.

Return value: Returns SHISHI_OK iff successful.

shishi_tgs_krberror

Function: Shishi_asn1 shishi_tgs_krberror (Shishi_tgs * tgs)

tgs: structure that holds information about TGS exchange

Description: Get KRB-ERROR from TGS exchange.

Return value: Returns the received TGS-REP from the TGS exchange, or NULL if not yet set or an error occured.

shishi_tgs_krberror_der

Function: int shishi_tgs_krberror_der (Shishi_tgs * tgs, char ** out, size_t * outlen)

tgs: structure that holds information about TGS exchange
out: output array with newly allocated DER encoding of KRB-ERROR.
outlen: length of output array with DER encoding of KRB-ERROR.

Description: DER encode KRB-ERROR. out is allocated by this function, and it is the responsibility of caller to deallocate it.

Return value: Returns SHISHI_OK iff successful.

shishi_tgs_krberror_set

Function: void shishi_tgs_krberror_set (Shishi_tgs * tgs, Shishi_asn1 krberror)

tgs: structure that holds information about TGS exchange
krberror: krberror to store in TGS.

Description: Set the KRB-ERROR in the TGS exchange.

shishi_tgs_tkt

Function: Shishi_tkt * shishi_tgs_tkt (Shishi_tgs * tgs)

tgs: structure that holds information about TGS exchange

Description: Get Ticket from TGS exchange.

Return value: Returns the newly acquired ticket from the TGS exchange, or NULL if not yet set or an error occured.

shishi_tgs_tkt_set

Function: void shishi_tgs_tkt_set (Shishi_tgs * tgs, Shishi_tkt * tkt)

tgs: structure that holds information about TGS exchange
tkt: ticket to store in TGS.

Description: Set the Ticket in the TGS exchange.

shishi_tgs_sendrecv_hint

Function: int shishi_tgs_sendrecv_hint (Shishi_tgs * tgs, Shishi_tkts_hint * hint)

tgs: structure that holds information about TGS exchange
hint: additional parameters that modify connection behaviour, or NULL.

Description: Send TGS-REQ and receive TGS-REP or KRB-ERROR. This is the subsequent authentication, usually used to acquire server tickets. The hint structure can be used to set, e.g., parameters for TLS authentication.

Return value: Returns SHISHI_OK iff successful.

shishi_tgs_sendrecv

Function: int shishi_tgs_sendrecv (Shishi_tgs * tgs)

tgs: structure that holds information about TGS exchange

Description: Send TGS-REQ and receive TGS-REP or KRB-ERROR. This is the subsequent authentication, usually used to acquire server tickets.

Return value: Returns SHISHI_OK iff successful.

shishi_tgs_set_server

Function: int shishi_tgs_set_server (Shishi_tgs * tgs, const char * server)

tgs: structure that holds information about TGS exchange
server: indicates the server to acquire ticket for.

Description: Set the server in the TGS-REQ.

Return value: Returns SHISHI_OK iff successful.

shishi_tgs_set_realm

Function: int shishi_tgs_set_realm (Shishi_tgs * tgs, const char * realm)

tgs: structure that holds information about TGS exchange
realm: indicates the realm to acquire ticket for.

Description: Set the server in the TGS-REQ.

Return value: Returns SHISHI_OK iff successful.

shishi_tgs_set_realmserver

Function: int shishi_tgs_set_realmserver (Shishi_tgs * tgs, const char * realm, const char * server)

tgs: structure that holds information about TGS exchange
realm: indicates the realm to acquire ticket for.
server: indicates the server to acquire ticket for.

Description: Set the realm and server in the TGS-REQ.

Return value: Returns SHISHI_OK iff successful.


Next: , Previous: , Up: Programming Manual   [Contents][Index]