AS Functions (GNU Shishi 1.0.3)

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.

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

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

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

Description: 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.

Description: 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.

Description: 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.

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

Description: 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.

Description: 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.

Description: 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.

Description: 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.

Description: 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.

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

Description: 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.

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

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

Description: 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.

Description: 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.

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

Description: 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.