Next: AS Functions, Previous: SAFE and PRIV Functions, Up: Programming Manual [Contents][Index]
A Ticket is an ASN.1 structured that can be used to authenticate the holder to services. It contain an encrypted part, which the ticket holder cannot see, but can be encrypted by the service, and various information about the user and service, including an encryption key to use for the connection. See Ticket (ASN.1) Functions, for more details on the ASN.1 structure of a ticket.
handle: shishi handle as allocated by shishi_init().
tkt: output variable with newly allocated ticket.
Description: Create a new ticket handle.
Return value: Returns SHISHI_OK iff successful.
handle: shishi handle as allocated by shishi_init().
ticket: input variable with ticket.
enckdcreppart: input variable with auxiliary ticket information.
kdcrep: input variable with KDC-REP ticket information.
Description: Create a new ticket handle.
Return value: Returns new ticket handle, or NULL on error.
tkt: input variable with ticket info.
Description: Deallocate resources associated with ticket. The ticket must not be used again after this call.
tkt: input variable with ticket info.
Description: Get ASN.1 Ticket structure from ticket.
Return value: Returns actual ticket.
tkt: input variable with ticket info.
ticket: ASN.1 Ticket to store in ticket.
Description: Set the ASN.1 Ticket in the Ticket.
tkt: input variable with ticket info.
Description: Get ASN.1 EncKDCRepPart structure from ticket.
Return value: Returns auxiliary ticket information.
tkt: structure that holds information about Ticket exchange
enckdcreppart: EncKDCRepPart to store in Ticket.
Description: Set the EncKDCRepPart in the Ticket.
tkt: input variable with ticket info.
Description: Get ASN.1 KDCRep structure from ticket.
Return value: Returns KDC-REP information.
tkt: input variable with ticket info.
Description: Get ASN.1 EncTicketPart structure from ticket.
Return value: Returns EncTicketPart information.
tkt: input variable with ticket info.
encticketpart: encticketpart to store in ticket.
Description: Set the EncTicketPart in the Ticket.
tkt: input variable with ticket info.
Description: Get key used in ticket, by looking first in EncKDCRepPart and then in EncTicketPart. If key is already populated, it is not extracted again.
Return value: Returns key extracted from EncKDCRepPart or EncTicketPart.
tkt: input variable with ticket info.
key: key to store in ticket.
Description: Set the key in the EncTicketPart.
Return value: Returns SHISHI_OK iff successful.
tkt: input variable with ticket info.
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 Ticket KDC-REP 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.
tkt: input variable with ticket info.
client: client name of ticket.
Description: Determine if ticket is for specified client.
Return value: Returns non-0 iff ticket is for specified client.
tkt: input variable with ticket info.
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 AS-REQ 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.
tkt: input variable with ticket info.
client: principal name (client name and realm) of ticket.
Description: Determine if ticket is for specified client principal.
Return value: Returns non-0 iff ticket is for specified client principal.
tkt: input variable with ticket info.
realm: pointer to newly allocated character array with realm name.
realmlen: length of newly allocated character array with realm name.
Description: Extract realm of server in ticket.
Return value: Returns SHISHI_OK iff successful.
tkt: input variable with ticket info.
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.
tkt: input variable with ticket info.
server: server name of ticket.
Description: Determine if ticket is for specified server.
Return value: Returns non-0 iff ticket is for specified server.
tkt: input variable with ticket info.
flags: pointer to output integer with flags.
Description: Extract flags in ticket (i.e., EncKDCRepPart).
Return value: Returns SHISHI_OK iff successful.
tkt: input variable with ticket info.
flags: integer with flags to store in ticket.
Description: Set flags in ticket, i.e., both EncTicketPart and EncKDCRepPart. Note that this reset any already existing flags.
Return value: Returns SHISHI_OK iff successful.
tkt: input variable with ticket info.
flag: integer with flags to store in ticket.
Description: Add ticket flags to Ticket and EncKDCRepPart. This preserves all existing options.
Return value: Returns SHISHI_OK iff successful.
tkt: input variable with ticket info.
Description: Determine if ticket is forwardable.
The FORWARDABLE flag in a ticket is normally only interpreted by the ticket-granting service. It can be ignored by application servers. The FORWARDABLE flag has an interpretation similar to that of the PROXIABLE flag, except ticket-granting tickets may also be issued with different network addresses. This flag is reset by default, but users MAY request that it be set by setting the FORWARDABLE option in the AS request when they request their initial ticket-granting ticket.
Return value: Returns non-0 iff forwardable flag is set in ticket.
tkt: input variable with ticket info.
Description: Determine if ticket is forwarded.
The FORWARDED flag is set by the TGS when a client presents a ticket with the FORWARDABLE flag set and requests a forwarded ticket by specifying the FORWARDED KDC option and supplying a set of addresses for the new ticket. It is also set in all tickets issued based on tickets with the FORWARDED flag set. Application servers may choose to process FORWARDED tickets differently than non-FORWARDED tickets.
Return value: Returns non-0 iff forwarded flag is set in ticket.
tkt: input variable with ticket info.
Description: Determine if ticket is proxiable.
The PROXIABLE flag in a ticket is normally only interpreted by the ticket-granting service. It can be ignored by application servers. When set, this flag tells the ticket-granting server that it is OK to issue a new ticket (but not a ticket-granting ticket) with a different network address based on this ticket. This flag is set if requested by the client on initial authentication. By default, the client will request that it be set when requesting a ticket-granting ticket, and reset when requesting any other ticket.
Return value: Returns non-0 iff proxiable flag is set in ticket.
tkt: input variable with ticket info.
Description: Determine if ticket is proxy ticket.
The PROXY flag is set in a ticket by the TGS when it issues a proxy ticket. Application servers MAY check this flag and at their option they MAY require additional authentication from the agent presenting the proxy in order to provide an audit trail.
Return value: Returns non-0 iff proxy flag is set in ticket.
tkt: input variable with ticket info.
Description: Determine if ticket may be used to grant postdated tickets.
The MAY-POSTDATE flag in a ticket is normally only interpreted by the ticket-granting service. It can be ignored by application servers. This flag MUST be set in a ticket-granting ticket in order to issue a postdated ticket based on the presented ticket. It is reset by default; it MAY be requested by a client by setting the ALLOW- POSTDATE option in the KRB_AS_REQ message. This flag does not allow a client to obtain a postdated ticket-granting ticket; postdated ticket-granting tickets can only by obtained by requesting the postdating in the KRB_AS_REQ message. The life (endtime-starttime) of a postdated ticket will be the remaining life of the ticket-granting ticket at the time of the request, unless the RENEWABLE option is also set, in which case it can be the full life (endtime-starttime) of the ticket-granting ticket. The KDC MAY limit how far in the future a ticket may be postdated.
Return value: Returns non-0 iff may-postdate flag is set in ticket.
tkt: input variable with ticket info.
Description: Determine if ticket is postdated.
The POSTDATED flag indicates that a ticket has been postdated. The application server can check the authtime field in the ticket to see when the original authentication occurred. Some services MAY choose to reject postdated tickets, or they may only accept them within a certain period after the original authentication. When the KDC issues a POSTDATED ticket, it will also be marked as INVALID, so that the application client MUST present the ticket to the KDC to be validated before use.
Return value: Returns non-0 iff postdated flag is set in ticket.
tkt: input variable with ticket info.
Description: Determine if ticket is invalid.
The INVALID flag indicates that a ticket is invalid. Application servers MUST reject tickets which have this flag set. A postdated ticket will be issued in this form. Invalid tickets MUST be validated by the KDC before use, by presenting them to the KDC in a TGS request with the VALIDATE option specified. The KDC will only validate tickets after their starttime has passed. The validation is required so that postdated tickets which have been stolen before their starttime can be rendered permanently invalid (through a hot-list mechanism).
Return value: Returns non-0 iff invalid flag is set in ticket.
tkt: input variable with ticket info.
Description: Determine if ticket is renewable.
The RENEWABLE flag in a ticket is normally only interpreted by the ticket-granting service (discussed below in section 3.3). It can usually be ignored by application servers. However, some particularly careful application servers MAY disallow renewable tickets.
Return value: Returns non-0 iff renewable flag is set in ticket.
tkt: input variable with ticket info.
Description: Determine if ticket was issued using AS exchange.
The INITIAL flag indicates that a ticket was issued using the AS protocol, rather than issued based on a ticket-granting ticket. Application servers that want to require the demonstrated knowledge of a client’s secret key (e.g. a password-changing program) can insist that this flag be set in any tickets they accept, and thus be assured that the client’s key was recently presented to the application client.
Return value: Returns non-0 iff initial flag is set in ticket.
tkt: input variable with ticket info.
Description: Determine if ticket was pre-authenticated.
The PRE-AUTHENT and HW-AUTHENT flags provide additional information about the initial authentication, regardless of whether the current ticket was issued directly (in which case INITIAL will also be set) or issued on the basis of a ticket-granting ticket (in which case the INITIAL flag is clear, but the PRE-AUTHENT and HW-AUTHENT flags are carried forward from the ticket-granting ticket).
Return value: Returns non-0 iff pre-authent flag is set in ticket.
tkt: input variable with ticket info.
Description: Determine if ticket is authenticated using a hardware token.
The PRE-AUTHENT and HW-AUTHENT flags provide additional information about the initial authentication, regardless of whether the current ticket was issued directly (in which case INITIAL will also be set) or issued on the basis of a ticket-granting ticket (in which case the INITIAL flag is clear, but the PRE-AUTHENT and HW-AUTHENT flags are carried forward from the ticket-granting ticket).
Return value: Returns non-0 iff hw-authent flag is set in ticket.
tkt: input variable with ticket info.
Description: Determine if ticket has been policy checked for transit.
The application server is ultimately responsible for accepting or rejecting authentication and SHOULD check that only suitably trusted KDCs are relied upon to authenticate a principal. The transited field in the ticket identifies which realms (and thus which KDCs) were involved in the authentication process and an application server would normally check this field. If any of these are untrusted to authenticate the indicated client principal (probably determined by a realm-based policy), the authentication attempt MUST be rejected. The presence of trusted KDCs in this list does not provide any guarantee; an untrusted KDC may have fabricated the list.
While the end server ultimately decides whether authentication is valid, the KDC for the end server’s realm MAY apply a realm specific policy for validating the transited field and accepting credentials for cross-realm authentication. When the KDC applies such checks and accepts such cross-realm authentication it will set the TRANSITED-POLICY-CHECKED flag in the service tickets it issues based on the cross-realm TGT. A client MAY request that the KDCs not check the transited field by setting the DISABLE-TRANSITED-CHECK flag. KDCs are encouraged but not required to honor this flag.
Application servers MUST either do the transited-realm checks themselves, or reject cross-realm tickets without TRANSITED-POLICY- CHECKED set.
Return value: Returns non-0 iff transited-policy-checked flag is set in ticket.
tkt: input variable with ticket info.
Description: Determine if ticket is ok as delegated ticket.
The copy of the ticket flags in the encrypted part of the KDC reply may have the OK-AS-DELEGATE flag set to indicates to the client that the server specified in the ticket has been determined by policy of the realm to be a suitable recipient of delegation. A client can use the presence of this flag to help it make a decision whether to delegate credentials (either grant a proxy or a forwarded ticket- granting ticket) to this server. It is acceptable to ignore the value of this flag. When setting this flag, an administrator should consider the security and placement of the server on which the service will run, as well as whether the service requires the use of delegated credentials.
Return value: Returns non-0 iff ok-as-delegate flag is set in ticket.
tkt: input variable with ticket info.
etype: pointer to encryption type that is set, see Shishi_etype.
Description: Extract encryption type of key in ticket (really EncKDCRepPart).
Return value: Returns SHISHI_OK iff successful.
tkt: input variable with ticket info.
Description: Extract encryption type of key in ticket (really EncKDCRepPart).
Return value: Returns encryption type of session key in ticket (really EncKDCRepPart), or -1 on error.
tkt: input variable with ticket info.
etype: encryption type, see Shishi_etype.
Description: Determine if key in ticket (really EncKDCRepPart) is of specified key type (really encryption type).
Return value: Returns non-0 iff key in ticket is of specified encryption type.
tkt: input variable with ticket info.
lrtype: lastreq type to extract, see Shishi_lrtype. E.g.,
SHISHI_LRTYPE_LAST_REQUEST.
Description: Extract C time corresponding to given lastreq type field in the ticket.
Return value: Returns C time interpretation of the specified lastreq field, or (time_t) -1.
tkt: input variable with ticket info.
Description: Extract C time corresponding to the authtime field. The field holds the time when the original authentication took place that later resulted in this ticket.
Return value: Returns C time interpretation of the endtime in ticket.
tkt: input variable with ticket info.
Description: Extract C time corresponding to the starttime field. The field holds the time where the ticket start to be valid (typically in the past).
Return value: Returns C time interpretation of the endtime in ticket.
tkt: input variable with ticket info.
Description: Extract C time corresponding to the endtime field. The field holds the time where the ticket stop being valid.
Return value: Returns C time interpretation of the endtime in ticket.
tkt: input variable with ticket info.
Description: Extract C time corresponding to the renew-till field. The field holds the time where the ticket stop being valid for renewal.
Return value: Returns C time interpretation of the renew-till in ticket.
tkt: input variable with ticket info.
now: time to check for.
Description: Determine if ticket is valid at a specific point in time.
Return value: Returns non-0 iff ticket is valid (not expired and after starttime) at specified time.
tkt: input variable with ticket info.
Description: Determine if ticket is valid now.
Return value: Returns 0 iff ticket is invalid (expired or not yet valid).
tkt: input variable with ticket info.
Description: Determine if ticket has expired (i.e., endtime is in the past).
Return value: Returns 0 iff ticket has expired.
tkt: input variable with ticket info.
fh: file handle open for writing.
Description: Print a human readable representation of the various lastreq fields in the ticket (really EncKDCRepPart).
tkt: input variable with ticket info.
fh: file handle open for writing.
Description: Print a human readable representation of a ticket to file handle.
Next: AS Functions, Previous: SAFE and PRIV Functions, Up: Programming Manual [Contents][Index]