Next: , Previous: Ticket Functions, Up: Programming Manual


5.7 AS Functions

The Authentication Service (AS) is used to get an initial ticket using e.g. your password. The following illustrates the AS-REQ and AS-REP ASN.1 structures.

-- Request --

AS-REQ		::= KDC-REQ {10}

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

AS-REP		::= KDC-REP {11, EncASRepPart, {keyuse-EncASRepPart}}

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

EncASRepPart	::= [APPLICATION 25] 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_as

— Function: int shishi_as (Shishi * handle, Shishi_as ** as)

handle: shishi handle as allocated by shishi_init().

as: holds pointer to newly allocate Shishi_as structure.

Allocate a new AS exchange variable.

Return value: Returns SHISHI_OK iff successful.

shishi_as_done

— Function: void shishi_as_done (Shishi_as * as)

as: structure that holds information about AS exchange

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

shishi_as_req

— Function: Shishi_asn1 shishi_as_req (Shishi_as * as)

as: structure that holds information about AS exchange

Get ASN.1 AS-REQ structure from AS exchange.

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

shishi_as_req_build

— Function: int shishi_as_req_build (Shishi_as * as)

as: structure that holds information about AS exchange

Possibly remove unset fields (e.g., rtime).

Return value: Returns SHISHI_OK iff successful.

shishi_as_req_set

— Function: void shishi_as_req_set (Shishi_as * as, Shishi_asn1 asreq)

as: structure that holds information about AS exchange

asreq: asreq to store in AS.

Set the AS-REQ in the AS exchange.

shishi_as_req_der

— Function: int shishi_as_req_der (Shishi_as * as, char ** out, size_t * outlen)

as: structure that holds information about AS exchange

out: output array with newly allocated DER encoding of AS-REQ.

outlen: length of output array with DER encoding of AS-REQ.

DER encode AS-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_as_req_der_set

— Function: int shishi_as_req_der_set (Shishi_as * as, char * der, size_t derlen)

as: structure that holds information about AS exchange

der: input array with DER encoded AP-REQ.

derlen: length of input array with DER encoded AP-REQ.

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

Return value: Returns SHISHI_OK.

shishi_as_rep

— Function: Shishi_asn1 shishi_as_rep (Shishi_as * as)

as: structure that holds information about AS exchange

Get ASN.1 AS-REP structure from AS exchange.

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

shishi_as_rep_process

— Function: int shishi_as_rep_process (Shishi_as * as, Shishi_key * key, const char * password)

as: structure that holds information about AS exchange

key: user's key, used to encrypt the encrypted part of the AS-REP.

password: user's password, used if key is NULL.

Process new AS-REP and set ticket. The key is used to decrypt the AP-REP. If both key and password is NULL, the user is queried for it.

Return value: Returns SHISHI_OK iff successful.

shishi_as_rep_build

— Function: int shishi_as_rep_build (Shishi_as * as, Shishi_key * key)

as: structure that holds information about AS exchange

key: user's key, used to encrypt the encrypted part of the AS-REP.

Build AS-REP.

Return value: Returns SHISHI_OK iff successful.

shishi_as_rep_der

— Function: int shishi_as_rep_der (Shishi_as * as, char ** out, size_t * outlen)

as: structure that holds information about AS exchange

out: output array with newly allocated DER encoding of AS-REP.

outlen: length of output array with DER encoding of AS-REP.

DER encode AS-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_as_rep_set

— Function: void shishi_as_rep_set (Shishi_as * as, Shishi_asn1 asrep)

as: structure that holds information about AS exchange

asrep: asrep to store in AS.

Set the AS-REP in the AS exchange.

shishi_as_rep_der_set

— Function: int shishi_as_rep_der_set (Shishi_as * as, char * der, size_t derlen)

as: structure that holds information about AS exchange

der: input array with DER encoded AP-REP.

derlen: length of input array with DER encoded AP-REP.

DER decode AS-REP and set it AS exchange. If decoding fails, the AS-REP in the AS exchange remains.

Return value: Returns SHISHI_OK.

shishi_as_krberror

— Function: Shishi_asn1 shishi_as_krberror (Shishi_as * as)

as: structure that holds information about AS exchange

Get ASN.1 KRB-ERROR structure from AS exchange.

Return value: Returns the received KRB-ERROR packet from the AS exchange, or NULL if not yet set or an error occured.

shishi_as_krberror_der

— Function: int shishi_as_krberror_der (Shishi_as * as, char ** out, size_t * outlen)

as: structure that holds information about AS 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.

shishi_as_krberror_set

— Function: void shishi_as_krberror_set (Shishi_as * as, Shishi_asn1 krberror)

as: structure that holds information about AS exchange

krberror: krberror to store in AS.

Set the KRB-ERROR in the AS exchange.

shishi_as_tkt

— Function: Shishi_tkt * shishi_as_tkt (Shishi_as * as)

as: structure that holds information about AS exchange

Get Ticket in AS exchange.

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

shishi_as_tkt_set

— Function: void shishi_as_tkt_set (Shishi_as * as, Shishi_tkt * tkt)

as: structure that holds information about AS exchange

tkt: tkt to store in AS.

Set the Tkt in the AS exchange.

shishi_as_sendrecv_hint

— Function: int shishi_as_sendrecv_hint (Shishi_as * as, Shishi_tkts_hint * hint)

as: structure that holds information about AS exchange

hint: additional parameters that modify connection behaviour, or NULL.

Send AS-REQ and receive AS-REP or KRB-ERROR. This is the initial authentication, usually used to acquire a Ticket Granting Ticket. The hint structure can be used to set, e.g., parameters for TLS authentication.

Return value: Returns SHISHI_OK iff successful.

shishi_as_sendrecv

— Function: int shishi_as_sendrecv (Shishi_as * as)

as: structure that holds information about AS exchange

Send AS-REQ and receive AS-REP or KRB-ERROR. This is the initial authentication, usually used to acquire a Ticket Granting Ticket.

Return value: Returns SHISHI_OK iff successful.