-- 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
}

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

Allocate a new TGS exchange variable.

Return value: Returns SHISHI_OK iff successful.

— Function: void shishi_tgs_done (Shishi_tgs * tgs)

tgs: structure that holds information about AS exchange

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

— Function: Shishi_tkt * shishi_tgs_tgtkt (Shishi_tgs * tgs)

tgs: structure that holds information about TGS exchange

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.

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

Set the Ticket in the TGS exchange.

— Function: Shishi_ap * shishi_tgs_ap (Shishi_tgs * tgs)

tgs: structure that holds information about TGS exchange

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.

— Function: Shishi_asn1 shishi_tgs_req (Shishi_tgs * tgs)

tgs: structure that holds information about TGS exchange

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.

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

Set the TGS-REQ in the TGS exchange.

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

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.

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

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.

— Function: int shishi_tgs_req_process (Shishi_tgs * tgs)

tgs: structure that holds information about TGS exchange

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.

— Function: int shishi_tgs_req_build (Shishi_tgs * tgs)

tgs: structure that holds information about TGS exchange

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

Return value: Returns SHISHI_OK iff successful.

— Function: Shishi_asn1 shishi_tgs_rep (Shishi_tgs * tgs)

tgs: structure that holds information about TGS exchange

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.

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

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.

— Function: int shishi_tgs_rep_process (Shishi_tgs * tgs)

tgs: structure that holds information about TGS exchange

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.

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

Build TGS-REP.

Return value: Returns SHISHI_OK iff successful.

— Function: Shishi_asn1 shishi_tgs_krberror (Shishi_tgs * tgs)

tgs: structure that holds information about TGS exchange

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.

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

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.

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

Set the KRB-ERROR in the TGS exchange.

— Function: Shishi_tkt * shishi_tgs_tkt (Shishi_tgs * tgs)

tgs: structure that holds information about TGS exchange

Get Ticket from TGS exchange.

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

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

Set the Ticket in the TGS exchange.

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

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.

— Function: int shishi_tgs_sendrecv (Shishi_tgs * tgs)

tgs: structure that holds information about TGS exchange

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.

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

Set the server in the TGS-REQ.

Return value: Returns SHISHI_OK iff successful.

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

Set the server in the TGS-REQ.

Return value: Returns SHISHI_OK iff successful.

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

Set the realm and server in the TGS-REQ.

Return value: Returns SHISHI_OK iff successful.