5.9 Ticket (ASN.1) Functions

See Ticket Functions, for an high-level overview of tickets. The following illustrates the Ticket and EncTicketPart ASN.1 structures.

Ticket          ::= [APPLICATION 1] SEQUENCE {
        tkt-vno         [0] INTEGER (5),
        realm           [1] Realm,
        sname           [2] PrincipalName,
        enc-part        [3] EncryptedData -- EncTicketPart
}

-- Encrypted part of ticket
EncTicketPart   ::= [APPLICATION 3] SEQUENCE {
        flags                   [0] TicketFlags,
        key                     [1] EncryptionKey,
        crealm                  [2] Realm,
        cname                   [3] PrincipalName,
        transited               [4] TransitedEncoding,
        authtime                [5] KerberosTime,
        starttime               [6] KerberosTime OPTIONAL,
        endtime                 [7] KerberosTime,
        renew-till              [8] KerberosTime OPTIONAL,
        caddr                   [9] HostAddresses OPTIONAL,
        authorization-data      [10] AuthorizationData OPTIONAL
}

shishi_ticket

Function: Shishi_asn1 shishi_ticket (Shishi * handle)

handle: shishi handle as allocated by shishi_init().

Description: This function creates a new ASN.1 Ticket, populated with some default values.

Return value: Returns the ticket or NULL on failure.

shishi_ticket_realm_get

Function: int shishi_ticket_realm_get (Shishi * handle, Shishi_asn1 ticket, char ** realm, size_t * realmlen)

handle: shishi handle as allocated by shishi_init().
ticket: input variable with ticket info.
realm: output array with newly allocated name of realm in ticket.
realmlen: size of output array.

Description: Extract realm from ticket.

Return value: Returns SHISHI_OK iff successful.

shishi_ticket_realm_set

Function: int shishi_ticket_realm_set (Shishi * handle, Shishi_asn1 ticket, const char * realm)

handle: shishi handle as allocated by shishi_init().
ticket: input variable with ticket info.
realm: input array with name of realm.

Description: Set the realm field in the Ticket.

Return value: Returns SHISHI_OK iff successful.

shishi_ticket_server

Function: int shishi_ticket_server (Shishi * handle, Shishi_asn1 ticket, char ** server, size_t * serverlen)

handle: Shishi library handle create by shishi_init().
ticket: ASN.1 Ticket variable to get server name from.
server: pointer to newly allocated zero terminated string containing principal name. May be NULL (to only populate serverlen).
serverlen: pointer to length of server on output, excluding terminating zero. May be NULL (to only populate server).

Description: Represent server principal name in Ticket as zero-terminated string. The string is allocate by this function, and it is the responsibility of the caller to deallocate it. Note that the output length serverlen does not include the terminating zero.

Return value: Returns SHISHI_OK iff successful.

shishi_ticket_sname_set

Function: int shishi_ticket_sname_set (Shishi * handle, Shishi_asn1 ticket, Shishi_name_type name_type, char * sname[])

handle: shishi handle as allocated by shishi_init().
ticket: Ticket variable to set server name field in.
name_type: type of principial, see Shishi_name_type, usually SHISHI_NT_UNKNOWN.
sname: input array with principal name.

Description: Set the server name field in the Ticket.

Return value: Returns SHISHI_OK iff successful.

shishi_ticket_get_enc_part_etype

Function: int shishi_ticket_get_enc_part_etype (Shishi * handle, Shishi_asn1 ticket, int32_t * etype)

handle: shishi handle as allocated by shishi_init().
ticket: Ticket variable to get value from.
etype: output variable that holds the value.

Description: Extract Ticket.enc-part.etype.

Return value: Returns SHISHI_OK iff successful.

shishi_ticket_set_enc_part

Function: int shishi_ticket_set_enc_part (Shishi * handle, Shishi_asn1 ticket, int32_t etype, uint32_t kvno, const char * buf, size_t buflen)

handle: shishi handle as allocated by shishi_init().
ticket: Ticket to add enc-part field to.
etype: encryption type used to encrypt enc-part.
kvno: key version number.
buf: input array with encrypted enc-part.
buflen: size of input array with encrypted enc-part.

Description: Set the encrypted enc-part field in the Ticket. The encrypted data is usually created by calling shishi_encrypt() on the DER encoded enc-part. To save time, you may want to use shishi_ticket_add_enc_part() instead, which calculates the encrypted data and calls this function in one step.

Return value: Returns SHISHI_OK iff successful.

shishi_ticket_add_enc_part

Function: int shishi_ticket_add_enc_part (Shishi * handle, Shishi_asn1 ticket, Shishi_key * key, Shishi_asn1 encticketpart)

handle: shishi handle as allocated by shishi_init().
ticket: Ticket to add enc-part field to.
key: key used to encrypt enc-part.
encticketpart: EncTicketPart to add.

Description: Encrypts DER encoded EncTicketPart using key and stores it in the Ticket.

Return value: Returns SHISHI_OK iff successful.

shishi_encticketpart_get_key

Function: int shishi_encticketpart_get_key (Shishi * handle, Shishi_asn1 encticketpart, Shishi_key ** key)

handle: shishi handle as allocated by shishi_init().
encticketpart: input EncTicketPart variable.
key: newly allocated key.

Description: Extract the session key in the Ticket.

Return value: Returns SHISHI_OK iff successful.

shishi_encticketpart_key_set

Function: int shishi_encticketpart_key_set (Shishi * handle, Shishi_asn1 encticketpart, Shishi_key * key)

handle: shishi handle as allocated by shishi_init().
encticketpart: input EncTicketPart variable.
key: key handle with information to store in encticketpart.

Description: Set the EncTicketPart.key field to key type and value of supplied key.

Return value: Returns SHISHI_OK iff successful.

shishi_encticketpart_flags_set

Function: int shishi_encticketpart_flags_set (Shishi * handle, Shishi_asn1 encticketpart, int flags)

handle: shishi handle as allocated by shishi_init().
encticketpart: input EncTicketPart variable.
flags: flags to set in encticketpart.

Description: Set the EncTicketPart.flags to supplied value.

Return value: Returns SHISHI_OK iff successful.

shishi_encticketpart_crealm_set

Function: int shishi_encticketpart_crealm_set (Shishi * handle, Shishi_asn1 encticketpart, const char * realm)

handle: shishi handle as allocated by shishi_init().
encticketpart: input EncTicketPart variable.
realm: input array with name of realm.

Description: Set the realm field in the KDC-REQ.

Return value: Returns SHISHI_OK iff successful.

shishi_encticketpart_cname_set

Function: int shishi_encticketpart_cname_set (Shishi * handle, Shishi_asn1 encticketpart, Shishi_name_type name_type, const char * principal)

handle: shishi handle as allocated by shishi_init().
encticketpart: input EncTicketPart variable.
name_type: type of principial, see Shishi_name_type, usually SHISHI_NT_UNKNOWN.
principal: input array with principal name.

Description: Set the client name field in the EncTicketPart.

Return value: Returns SHISHI_OK iff successful.

shishi_encticketpart_transited_set

Function: int shishi_encticketpart_transited_set (Shishi * handle, Shishi_asn1 encticketpart, int32_t trtype, const char * trdata, size_t trdatalen)

handle: shishi handle as allocated by shishi_init().
encticketpart: input EncTicketPart variable.
trtype: transitedencoding type, e.g. SHISHI_TR_DOMAIN_X500_COMPRESS.
trdata: actual transited realm data.
trdatalen: length of actual transited realm data.

Description: Set the EncTicketPart.transited field to supplied value.

Return value: Returns SHISHI_OK iff successful.

shishi_encticketpart_authtime_set

Function: int shishi_encticketpart_authtime_set (Shishi * handle, Shishi_asn1 encticketpart, const char * authtime)

handle: shishi handle as allocated by shishi_init().
encticketpart: input EncTicketPart variable.
authtime: character buffer containing a generalized time string.

Description: Set the EncTicketPart.authtime to supplied value.

Return value: Returns SHISHI_OK iff successful.

shishi_encticketpart_endtime_set

Function: int shishi_encticketpart_endtime_set (Shishi * handle, Shishi_asn1 encticketpart, const char * endtime)

handle: shishi handle as allocated by shishi_init().
encticketpart: input EncTicketPart variable.
endtime: character buffer containing a generalized time string.

Description: Set the EncTicketPart.endtime to supplied value.

Return value: Returns SHISHI_OK iff successful.

shishi_encticketpart_client

Function: int shishi_encticketpart_client (Shishi * handle, Shishi_asn1 encticketpart, char ** client, size_t * clientlen)

handle: Shishi library handle create by shishi_init().
encticketpart: EncTicketPart variable to get client name from.
client: pointer to newly allocated zero terminated string containing principal name. May be NULL (to only populate clientlen).
clientlen: pointer to length of client on output, excluding terminating zero. May be NULL (to only populate client).

Description: Represent client principal name in EncTicketPart as zero-terminated string. The string is allocate by this function, and it is the responsibility of the caller to deallocate it. Note that the output length clientlen does not include the terminating zero.

Return value: Returns SHISHI_OK iff successful.

shishi_encticketpart_clientrealm

Function: int shishi_encticketpart_clientrealm (Shishi * handle, Shishi_asn1 encticketpart, char ** client, size_t * clientlen)

handle: Shishi library handle create by shishi_init().
encticketpart: EncTicketPart variable to get client name and realm from.
client: pointer to newly allocated zero terminated string containing principal name and realm. May be NULL (to only populate clientlen).
clientlen: pointer to length of client on output, excluding terminating zero. May be NULL (to only populate client).

Description: Convert cname and realm fields from EncTicketPart to printable principal name format. The string is allocate by this function, and it is the responsibility of the caller to deallocate it. Note that the output length clientlen does not include the terminating zero.

Return value: Returns SHISHI_OK iff successful.