This section describes the functions provided in the libkrb5.a library. The library is built from several pieces, mostly for convenience in programming, maintenance, and porting.
The main functions deal with the nitty-gritty details: verifying tickets, creating authenticators, and the like.
The krb5_context is designed to represent the per process state. When the library is made thread-safe, the context will represent the per-thread state. Global parameters which are "context" specific are stored in this structure, including default realm, default encryption type, default configuration files and the like. Functions exist to provide full access to the data structures stored in the context and should not be accessed directly by developers.
krb5_error_code krb5_init_context(/* IN/OUT */ krb5_context * context)
void krb5_free_context(/* IN/OUT */ krb5_context context)
krb5_error_code krb5_set_default_in_tkt_etypes(/* IN/OUT */ krb5_context context, /* IN */ const krb5_enctype * etypes)
krb5_error_code krb5_get_default_in_tkt_etypes(/* IN/OUT */ krb5_context context, /* OUT */ krb5_enctype ** etypes)
While the krb5_context represents a per-process or per-thread context, the krb5_auth_context represents a per-connection context are are used by the various functions involved directly in client/server authentication. Some of the data stored in this context include keyblocks, addresses, sequence numbers, authenticators, checksum type, and replay cache pointer.
krb5_error_code krb5_auth_con_init(/* IN/OUT */ krb5_context context, /* OUT */ krb5_auth_context * auth_context)
The default flags for the context are set to enable the use of the replay cache (KRB5_AUTH_CONTEXT_DO_TIME) but no sequence numbers. The function krb5_auth_con_setflags() allows the flags to be changed.
The default checksum type is set to CKSUMTYPE_RSA_MD4_DES. This may be changed with krb5_auth_con_setcksumtype().
The auth_context structure should be freed with krb5_auth_con_free().
krb5_error_code krb5_auth_con_free(/* IN/OUT */ krb5_context context, krb5_auth_context auth_context)
krb5_error_code krb5_auth_con_setflags(/* IN/OUT */ krb5_context context, krb5_auth_context auth_context, /* IN */ krb5_int32 flags)
Symbol | Meaning |
KRB5_AUTH_CONTEXT_DO_TIME | Use timestamps |
KRB5_AUTH_CONTEXT_RET_TIME | Save timestamps to output structure |
KRB5_AUTH_CONTEXT_DO_SEQUENCE | Use sequence numbers |
KRB5_AUTH_CONTEXT_RET_SEQUENCE | Copy sequence numbers to output structure |
krb5_error_code krb5_auth_con_getflags(/* IN/OUT */ krb5_context context, /* IN */ krb5_auth_context auth_context, /* OUT */ krb5_int32 * flags)
krb5_error_code krb5_auth_con_setaddrs(/* IN/OUT */ krb5_context context, krb5_auth_context auth_context, /* IN */ krb5_address * local_addr, krb5_address * remote_addr)
krb5_error_code krb5_auth_con_getaddrs(/* IN/OUT */ krb5_context context, krb5_auth_context auth_context, /* OUT */ krb5_address ** local_addr, krb5_address ** remote_addr)
krb5_error_code krb5_auth_con_setports(/* IN/OUT */ krb5_context context, krb5_auth_context auth_context, /* IN */ krb5_address * local_port, krb5_address * remote_port)
krb5_error_code krb5_auth_con_setuserkey(/* IN/OUT */ krb5_context context, krb5_auth_context auth_context, /* IN */ krb5_keyblock * keyblock)
krb5_error_code krb5_auth_con_getkey(/* IN/OUT */ krb5_context context, krb5_auth_context auth_context, /* OUT */ krb5_keyblock ** keyblock)
krb5_error_code krb5_auth_con_getlocalsubkey(/* IN/OUT */ krb5_context context, krb5_auth_context auth_context, /* OUT */ krb5_keyblock ** keyblock)
krb5_error_code krb5_auth_con_getremotesubkey(/* IN/OUT */ krb5_context context, krb5_auth_context auth_context, /* OUT */ krb5_keyblock ** keyblock)
krb5_error_code krb5_auth_setcksumtype(/* IN/OUT */ krb5_context context, krb5_auth_context auth_context, /* IN */ krb5_cksumtype cksumtype)
krb5_error_code krb5_auth_getlocalseqnumber(/* IN/OUT */ krb5_context context, krb5_auth_context auth_context, /* IN */ krb5_int32 * seqnumber)
krb5_error_code krb5_auth_getremoteseqnumber(/* IN/OUT */ krb5_context context, krb5_auth_context auth_context, /* IN */ krb5_int32 * seqnumber)
krb5_error_code krb5_auth_getauthenticator(/* IN/OUT */ krb5_context context, krb5_auth_context auth_context, /* OUT */ krb5_authenticator ** authenticator)
krb5_error_code krb5_auth_con_initivector(/* IN/OUT */ krb5_context context, krb5_auth_context auth_context)
krb5_error_code krb5_auth_con_setivector(/* IN/OUT */ krb5_context context, krb5_auth_context * auth_context, /* IN */ krb5_pointer ivector)
krb5_error_code krb5_auth_con_setrcache(/* IN/OUT */ krb5_context context, krb5_auth_context auth_context, /* IN */ krb5_rcache rcache)
Principals define a uniquely named client or server instance that participates in a network communication. The following functions allow one to create, modify and access portions of the krb5_principal.
Other functions found in orther portions of the manual include krb5_sname_to_principal(), krb5_free_principal(),
While it is possible to directly access the data structure in the structure, it is recommended that the functions be used.
krb5_error_code krb5_parse_name(/* IN/OUT */ krb5_context context, /* IN */ const char * name, /* OUT */ krb5_principal * principal)
A single-string representation of a Kerberos name consists of one or more principal name components, separated by slashes, optionally followed by the "@" character and a realm name. If the realm name is not specified, the local realm is used. The slash and "@" characters may be quoted (i.e., included as part of a component rather than as a component separator or realm prefix) by preceding them with a backslash ("\") character. Similarly, newline, tab, backspace, and null characters may be included in a component by using \n, \t, \b or \0, respectively.
The realm in a Kerberos name may not contain the slash, colon or null characters.
*principal will point to allocated storage which should be freed by the caller (using krb5_free_principal()) after use.
krb5_error_code krb5_unparse_name(/* IN/OUT */ krb5_context context, /* IN */ krb5_const_principal principal, /* OUT */ char ** name)
*name points to allocated storage and should be freed by the caller when finished.
krb5_error_code krb5_unparse_name_ext(/* IN/OUT */ krb5_context context, /* IN */ krb5_const_principal principal, /* IN/OUT */ char ** name, int * size)
krb5_data krb5_princ_realm(/* IN/OUT */ krb5_context context, krb5_principal principal )
void krb5_princ_set_realm(/* IN/OUT */ krb5_context context, krb5_principal principal, krb5_data *realm )
void krb5_princ_set_realm_data(/* IN/OUT */ krb5_context context, krb5_principal principal, char *data )
void krb5_princ_set_realm_length(/* IN/OUT */ krb5_context context, krb5_principal principal, int length )
void krb5_princ_size(/* IN/OUT */ krb5_context context, krb5_principal principal )
void krb5_princ_type(/* IN/OUT */ krb5_context context, krb5_principal principal )
krb5_princ_data( krb5_context context, krb5_principal principal )
krb5_princ_component( krb5_context context, krb5_principal principal, int i )
krb5_error_code krb5_build_principal(/* IN/OUT */ krb5_context context, /* OUT */ krb5_principal * princ, /* IN */ int rlen, const char * realm, char *s1, *s2, ..., 0)
krb5_error_code krb5_build_principal_va(/* IN/OUT */ krb5_context context, /* OUT */ krb5_principal * princ, /* IN */ int rlen, const char * realm, va_list ap)
krb5_error_code krb5_build_principal_ext(/* IN/OUT */ krb5_context context, /* OUT */ krb5_principal * princ, /* IN */ int rlen, const char * realm, int len1, char *s1, int len2, char *s2, ..., 0)
krb5_error_code krb5_copy_principal(/* IN/OUT */ krb5_context context, /* IN */ krb5_const_principal inprinc, /* OUT */ krb5_principal * outprinc)
krb5_boolean krb5_principal_compare(/* IN/OUT */ krb5_context context, /* IN */ krb5_const_principal princ1, krb5_const_principal princ2)
krb5_boolean krb5_realm_compare(/* IN/OUT */ krb5_context context, /* IN */ krb5_const_principal princ1, krb5_const_principal princ2)
krb5_error_code krb5_425_conv_principal(/* IN/OUT */ krb5_context context, /* IN */ const char * name, const char * instance, const char * realm, /* OUT */ krb5_principal * princ)
krb5_error_code krb5_encode_kdc_rep(/* IN */ const krb5_msgtype type, const krb5_enc_kdc_rep_part * encpart, krb5_encrypt_block * eblock, const krb5_keyblock * client_key, /* IN/OUT */ krb5_kdc_rep * dec_rep, /* OUT */ krb5_data ** enc_rep)
Takes KDC rep parts in *rep and *encpart, and formats it into *enc_rep, using message type type and encryption key client_key and encryption block eblock.
enc_rep->data will point to allocated storage upon non-error return; the caller should free it when finished.
krb5_error_code krb5_decode_kdc_rep(/* IN/OUT */ krb5_context context, /* IN */ krb5_data * enc_rep, const krb5_keyblock * key, const krb5_enctype etype, /* OUT */ krb5_kdc_rep ** dec_rep)
Takes a KDC_REP message and decrypts encrypted part using etype and *key, putting result in *dec_rep. The pointers in dec_rep are all set to allocated storage which should be freed by the caller when finished with the response (by using krb5_free_kdc_rep()).
If the response isn't a KDC_REP (tgs or as), it returns an error from the decoding routines.
krb5_error_code krb5_kdc_rep_decrypt_proc(/* IN/OUT */ krb5_context context, /* IN */ const krb5_keyblock * key, krb5_const_pointer decryptarg, /* IN/OUT */ krb5_kdc_rep * dec_rep)
The result is in allocated storage pointed to by dec_rep->enc_part2, unless some error occurs.
This function is suitable for use as the decrypt_proc argument to krb5_get_in_tkt().
krb5_error_code krb5_encrypt_tkt_part(/* IN/OUT */ krb5_context context, /* IN */ const krb5_keyblock * srv_key, /* IN/OUT */ krb5_ticket * dec_ticket)
Encrypts the unecrypted part of the ticket found in dec_ticket->enc_part2 using srv_key, and places result in dec_ticket->enc_part. The dec_ticket->enc_part will be allocated by this function.
enc_part->data is allocated and filled in with encrypted stuff.
krb5_error_code krb5_decrypt_tkt_part(/* IN/OUT */ krb5_context context, /* IN */ const krb5_keyblock * srv_key, /* IN/OUT */ krb5_ticket * dec_ticket)
Takes encrypted dec_ticket->enc_part, decrypts with dec_ticket->etype using srv_key, and places result in dec_ticket->enc_part2. The storage of dec_ticket->enc_part2 will be allocated before return.
krb5_error_code krb5_send_tgs(/* IN/OUT */ krb5_context context, /* IN */ const krb5_flags kdcoptions, const krb5_ticket_times * timestruct, const krb5_enctype * etypes, const krb5_cksumtype sumtype, krb5_const_principal sname, krb5_address * const * addrs, krb5_authdata * const * authorization_data, krb5_pa_data * const * padata, const krb5_data * second_ticket, /* IN/OUT */ krb5_creds * in_cred, /* OUT */ krb5_response * rep)
Sends a request to the TGS and waits for a response. kdcoptions is used for the options in the KRB_TGS_REQ. timestruct values are used for from, till, and rtime in the KRB_TGS_REQ. etypes is a list of etypes used in the KRB_TGS_REQ. sumtype is used for the checksum in the AP_REQ in the KRB_TGS_REQ. sname is used for sname in the KRB_TGS_REQ. addrs, if non-NULL, is used for addresses in the KRB_TGS_REQ. authorization_data, if non-NULL, is used for authorization_data in the KRB_TGS_REQ. padata, if non-NULL, is combined with any other supplied preauthentication data for the KRB_TGS_REQ. second_ticket, if required by options, is used for the 2nd ticket in the KRB_TGS_REQ. in_cred is used for the ticket and session key in the KRB_AP_REQ header in the KRB_TGS_REQ.
The KDC realm is extracted from in_cred->server's realm.
The response is placed into *rep. rep->response.data is set to point at allocated storage which should be freed by the caller when finished.
krb5_error_code krb5_get_cred_from_kdc(/* IN/OUT */ krb5_context context, /* IN */ krb5_ccache ccache, krb5_creds * in_cred, /* OUT */ krb5_cred ** out_cred, krb5_creds *** tgts)
ccache is used to fetch initial TGT's to start the authentication path to the server.
Credentials are requested from the KDC for the server's realm. Any TGT credentials obtained in the process of contacting the KDC are returned in an array of credentials; tgts is filled in to point to an array of pointers to credential structures (if no TGT's were used, the pointer is zeroed). TGT's may be returned even if no useful end ticket was obtained.
The returned credentials are NOT cached.
If credentials are obtained, creds is filled in with the results; creds->ticket and creds->keyblock->key are set to allocated storage, which should be freed by the caller when finished.
krb5_error_code krb5_get_cred_via_tkt(/* IN/OUT */ krb5_context context, /* IN */ krb5_creds * tkt, const krb5_flags kdcoptions, krb5_address *const * address, krb5_creds * in_cred, /* OUT */ krb5_creds ** out_cred)
kdcoptions refers to the options as listed in Table 2. The optional address is used for addressed in the KRB_TGS_REQ (see krb5_send_tgs()).
krb5_error_code krb5_get_credentials(/* IN/OUT */ krb5_context context, /* IN */ const krb5_flags options, krb5_ccache ccache, krb5_creds * in_creds, /* OUT */ krb5_creds * out_creds)
If options specifies KRB5_GC_CACHED, then krb5_get_credentials() will only search the credentials cache for a ticket.
If options specifies KRB5_GC_USER_USER, then krb5_get_credentials() will get credentials for a user to user authentication. In a user to user authentication, the secret key for the server is the session key from the server's ticket-granting-ticket (TGT). The TGT is passed from the server to the client over the network _this is safe since the TGT is encrypted in a key known only by the Kerberos server and the client must pass this TGT to krb5_get_credentials() in in_creds->second_ticket. The Kerberos server will use this TGT to construct a user to user ticket which can be verified by the server by using the session key from its TGT.
The effective expiration date is the minimum of the following:
If any special authorization data needs to be included in the ticket, for example, restrictions on how the ticket can be used _they should be specified in in_creds-> authdata. If there is no special authorization data to be passed, in_creds->authdata should be NULL.
Any returned ticket and intermediate ticket-granting tickets are stored in ccache.
krb5_error_code krb5_get_in_tkt(/* IN/OUT */ krb5_context context, /* IN */ const krb5_flags options, krb5_address * const * addrs, const krb5_enctype * etypes, const krb5_preauthtype * ptypes, krb5_error_code (*key_proc)(krb5_context context, const krb5_keytype type, krb5_data * salt, krb5_const_pointer keyseed, krb5_keyblock ** key), krb5_const_pointer keyseed, krb5_error_code (*decrypt_proc)(krb5_context context, const krb5_keyblock *key, krb5_const_pointer decryptarg, krb5_kdc_rep * dec_rep), krb5_const_pointer decryptarg, /* IN/OUT */ krb5_creds * creds, krb5_ccache ccache, krb5_kdc_rep ** ret_as_reply)
Attempts to get an initial ticket for creds->client to use server creds->server, using the following: the realm from creds->client; the options in options (listed in Table 2); and ptypes, the preauthentication method (valid preauthentication methods are listed in Table 2). krb5_get_in_tkt() requests encryption type etypes (valid encryption types are ETYPE_DES_CBC_CRC and ETYPE_RAW_DES_CBC), using creds->times.starttime, creds->times.endtime, creds->times.renew_till as from, till, and rtime. creds->times.renew_till is ignored unless the RENEWABLE option is requested.
key_proc is called, with context, keytype, keyseed andpadata as arguments, to fill in key to be used for decryption. The valid key types for keytype are KEYTYPE_NULL and KEYTYPE_DES However, KEYTYPE_DES is the only key type supported by MIT kerberos. The content of keyseed depends on the key_proc being used. The padata passed to key_proc is the preauthentication data returned by the KDC as part of the reply to the initial ticket request. It may contain an element of type KRB5_PADATA_PW_SALT, which key_proc should use to determine what salt to use when generating the key. key_proc should fill in key with a key for the client, or return an error code.
decrypt_proc is called to perform the decryption of the response (the encrypted part is in dec_rep->enc_part; the decrypted part should be allocated and filled into dec_rep->enc_part2. decryptarg is passed on to decrypt_proc, and its content depends on the decrypt_proc being used.
If addrs is non-NULL, it is used for the addresses requested. If it is null, the system standard addresses are used.
If ret_as_reply is non-NULL, it is filled in with a pointer to a structure containing the reply packet from the KDC. Some programs may find it useful to have direct access to this information. For example, it can be used to obtain the pre-authentication data passed back from the KDC. The caller is responsible for freeing this structure by using krb5_free_kdc_rep().
If etypes is non-NULL, the it is used as for the list of valid encyrption types. Otherwise, the context default is used (as returned by krb5_get_default_in_tkt_etypes().
A succesful call will place the ticket in the credentials cache ccache and fill in creds with the ticket information used/returned.
krb5_error_code krb5_get_in_tkt_with_password(/* IN/OUT */ krb5_context context, /* IN */ const krb5_flags options, krb5_address * const * addrs, const krb5_enctype * etypes, const krb5_preauthtype * pre_auth_types, const char * password, krb5_ccache ccache, /* IN/OUT */ krb5_creds * creds, krb5_kdc_rep ** ret_as_reply)
The password is converted into a key using the appropriate string-to-key conversion function for the specified keytype, and using any salt data returned by the KDC in response to the authentication request.
See krb5_get_in_tkt() for documentation of the options, addrs, pre_auth_type, etype, keytype, ccache, creds and ret_as_reply arguments.
krb5_error_code krb5_get_in_tkt_with_keytab(/* IN/OUT */ krb5_context context, /* IN */ const krb5_flags options, krb5_address * const * addrs, const krb5_enctype * etypes, const krb5_preauthtype * pre_auth_types, const krb5_keytab * keytab, krb5_ccache ccache, /* IN/OUT */ krb5_creds * creds, krb5_kdc_rep ** ret_as_reply)
See krb5_get_in_tkt() for documentation of the options, addrs, pre_auth_type, etype, ccache, creds and ret_as_reply arguments.
krb5_error_code krb5_get_in_tkt_with_skey(/* IN/OUT */ krb5_context context, /* IN */ const krb5_flags options, krb5_address * const * addrs, const krb5_enctype * etypes, const krb5_preauthtype * pre_auth_types, const krb5_keyblock * key, krb5_ccache ccache, /* IN/OUT */ krb5_creds * creds, krb5_kdc_rep ** ret_as_reply)
See krb5_get_in_tkt() for documentation of the options, addrs, pre_auth_type, etype, ccache, creds and ret_as_reply arguments.
krb5_error_code krb5_mk_req(/* IN/OUT */ krb5_context context, krb5_auth_context * auth_context, /* IN */ const krb5_flags ap_req_options, char * service, char * hostname, krb5_data * in_data, /* IN/OUT */ krb5_ccache ccache, /* OUT */ krb5_data * outbuf)
The server to receive the message is specified by hostname. The principal of the server to receive the message is specified by hostname and service. If credentials are not present in the credentials cache ccache for this server, the TGS request with default parameters is used in an attempt to obtain such credentials, and they are stored in ccache.
ap_req_options specifies the KRB_AP_REQ options desired. Valid options are:
The checksum method to be used is as specified in auth_context.
outbuf should point to an existing krb5_data structure. outbuf->length and outbuf->data will be filled in on success, and the latter should be freed by the caller when it is no longer needed; if an error is returned, however, no storage is allocated and outbuf->data does not need to be freed.
krb5_error_code krb5_mk_req_extended(/* IN/OUT */ krb5_context context, krb5_auth_context * auth_context, /* IN */ const krb5_flags ap_req_options, krb5_data * in_data, krb5_creds * in_creds, /* OUT */ krb5_data * outbuf)
outbuf, ap_req_options, auth_context, and ccache are used in the same fashion as for krb5_mk_req().
in_creds is used to supply the credentials (ticket and session key) needed to form the request.
If in_creds->ticket has no data (length == 0), then an error is returned.
During this call, the structure elements in in_creds may be freed and reallocated. Hence all of the structure elements which are pointers should point to allocated memory, and there should be no other pointers aliased to the same memory, since it may be deallocated during this procedure call.
If ap_req_options specifies AP_OPTS_USE_SUBKEY, then a subkey will be generated if need be by krb5_generate_subkey().
A copy of the authenticator will be stored in the auth_context, with the principal and checksum fields nulled out, unless an error is returned. (This is to prevent pointer sharing problems; the caller shouldn't need these fields anyway, since the caller supplied them.)
krb5_error_code krb5_generate_subkey(/* IN/OUT */ krb5_context context, /* IN */ const krb5_keyblock * key, /* OUT */ krb5_keyblock ** subkey)
subkey is filled in to point to the generated subkey, unless an error is returned. The returned key (i.e., *subkey) is allocated and should be freed by the caller with krb5_free_keyblock() when it is no longer needed.
krb5_error_code krb5_rd_req(/* IN/OUT */ krb5_context context, krb5_auth_context * auth_context, /* IN */ const krb5_data * inbuf, krb5_const_principal server, krb5_keytab keytab, /* IN/OUT */ krb5_flags * ap_req_options, /* OUT */ krb5_ticket ** ticket)
inbuf should contain the KRB_AP_REQ message to be parsed.
If auth_context is NULL, one will be generated and freed internally by the function.
server specifies the expected server's name for the ticket. If server is NULL, then any server name will be accepted if the appropriate key can be found, and the caller should verify that the server principal matches some trust criterion.
If server is not NULL, and a replay detaction cache has not been established with the auth_context, one will be generated.
keytab specifies a keytab containing generate a decryption key. If NULL, krb5_kt_default will be used to find the default keytab and the key taken from there11 .
If a keyblock is present in the auth_context, it will be used to decrypt the ticket request and the keyblock freed with krb5_free_keyblock(). This is useful for user to user authentication. If no keyblock is specified, the keytab is consulted for an entry matching the requested keytype, server and version number and used instead.
The authenticator in the request is decrypted and stored in the auth_context. The client specified in the decrypted authenticator is compared to the client specified in the decoded ticket to ensure that the compare.
If the remote_addr portion of the auth_context is set, then this routine checks if the request came from the right client.
sender_addr specifies the address(es) expected to be present in the ticket.
The replay cache is checked to see if the ticket and authenticator have been seen and if so, returns an error. If not, the ticket and authenticator are entered into the cache.
Various other checks are made of the decoded data, including, cross-realm policy, clockskew and ticket validation times.
The keyblock, subkey, and sequence number of the request are all stored in the auth_context for future use.
If the request has the AP_OPTS_MUTUAL_REQUIRED bit set, the local sequence number, which is stored in the auth_context, is XORed with the remote sequence number in the request.
If ap_req_options is non-NULL, it will be set to contain the application request flags.
krb5_error_code krb5_rd_req_decoded(/* IN/OUT */ krb5_context context, krb5_auth_context * auth_context, /* IN */ const krb5_ap_req * req, krb5_const_principal server, /* IN/OUT */ krb5_keytab keytab, /* OUT */ krb5_ticket ** ticket)
krb5_error_code krb5_mk_rep(/* IN/OUT */ krb5_context context, krb5_auth_context auth_context, /* OUT */ krb5_data * outbuf)
When successfull, outbuf->length and outbuf->data are filled in with the length of the AP_REQ message and allocated data holding it. outbuf->data should be freed by the caller when it is no longer needed.
If the flags in auth_context indicate that a sequence number should be used (either KRB5_AUTH_CONTEXT_DO_SEQUENCE or KRB5_AUTH_CONTEXT_RET_SEQUENCE) and the local sequqnce number in the auth_context is 0, a new number will be generated with krb5_generate_seq_number().
krb5_error_code krb5_rd_rep(/* IN/OUT */ krb5_context context, krb5_auth_context auth_context, /* IN */ const krb5_data * inbuf, /* OUT */ krb5_ap_rep_enc_part ** repl)
The keyblock stored in auth_context is used to decrypt the message after establishing any key pre-processing with krb5_process_key().
krb5_error_code krb5_mk_error(/* IN/OUT */ krb5_context context, /* IN */ const krb5_error * dec_err, /* OUT */ krb5_data * enc_err)
The error buffer storage (enc_err->data) is allocated, and should be freed by the caller when finished.
krb5_error_code krb5_rd_error(/* IN/OUT */ krb5_context context, /* IN */ const krb5_data * enc_errbuf, /* OUT */ krb5_error ** dec_error)
krb5_error_code krb5_generate_seq_number(/* IN/OUT */ krb5_context context, /* IN */ const krb5_keyblock * key, /* OUT */ krb5_int32 * seqno)
key parameterizes the choice of the random sequence number, which is filled into *seqno upon return.
krb5_error_code krb5_sendauth(/* IN/OUT */ krb5_context context, krb5_auth_context * auth_context, /* IN */ krb5_pointer fd, char * appl_version, krb5_principal client, krb5_principal server, krb5_flags ap_req_options, krb5_data * in_data, krb5_creds * in_creds, /* IN/OUT */ krb5_ccache ccache, /* OUT */ krb5_error ** error, krb5_ap_rep_enc_part ** rep_result, krb5_creds ** out_creds)
The paramter appl_version is a string describing the application protocol version which the client is expecting to use for this exchange. If the server is using a different application protocol, an error will be returned.
The parameters client and server specify the kerberos principals for the client and the server. They are ignored if in_creds is non-null. Otherwise, server must be non-null, but client may be null, in which case the client principal used is the one in the credential cache's default principal.
The ap_req_options parameters specifies the options which should be passed to krb5_mk_req(). Valid options are listed in Table 4.1.4. If ap_req_options specifies MUTUAL_REQUIRED, then krb5_sendauth() will perform a mutual authentication exchange, and if rep_result is non-null, it will be filled in with the result of the mutual authentication exchange; the caller should free *rep_result with krb5_free_ap_rep_enc_part() when done with it.
If in_creds is non-null, then in_creds->client and in_creds->server must be filled in, and either the other structure fields should be filled in with valid credentials, or in_creds->ticket.length should be zero.
If in_creds->ticket.length is non-zero, then in_creds will be used as-is as the credentials to send to the server, and ccache is ignored; otherwise, ccache is used as described below, and out_creds , if not NULL, is filled in with the retrieved credentials. ccache() specifies the credential cache to use when one is needed (i.e., when in_creds() is null or in_creds->ticket.length is zero). When a credential cache is not needed, ccache() is ignored. When a credential cache is needed and ccache() is null, the default credential cache is used. Note that if the credential cache is needed and does not contain the needed credentials, they will be retrieved from the KDC and stored in the credential cache.
If mutual authentication is used and rep_result is non-null, the sequence number for the server is available to the caller in *rep_result->seq_number. (If mutual authentication is not used, there is no way to negotiate a sequence number for the server.)
If an error occurs during the authenticated ticket exchange and error is non-null, the error packet (if any) that was sent from the server will be placed in it. This error should be freed with krb5_free_error().
krb5_error_code krb5_recvauth(/* IN/OUT */ krb5_context context, krb5_auth_context * auth_context, /* IN */ krb5_pointer fd, char * appl_version, krb5_principal server, char * rc_type, krb5_int32 flags, krb5_keytab keytab, /* OUT */ krb5_ticket ** ticket)
fd is a pointer to the network connection. As in krb5_sendauth(), in the MIT Unix implementation fd is a pointer to a file descriptor.
The parameter appl_version is a string describing the application protocol version which the server is expecting to use for this exchange. If the client is using a different application protocol, an error will be returned and the authentication exchange will be aborted.
If server is non-null, then krb5_recvauth() verifies that the server principal requested by the client matches server. If not, an error will be returned and the authentication exchange will be aborted.
The parameters server, auth_context, and keytab are used by krb5_rd_req() to obtain the server's private key.
If server is non-null, the princicpal component of it is used to determine the replay cache to use. Otherwise, krb5_recvauth() will use a default replay cache.
The flags argument allows the caller to modify the behavior of krb5_recvauth(). For non-library callers, flags should be 0.
ticket is optional and is only filled in if non-null. It is filled with the data from the ticket sent by the client, and should be freed with krb5_free_ticket() when it is no longer needed.
krb5_error_code krb5_mk_safe(/* IN/OUT */ krb5_context context, krb5_auth_context auth_context, /* IN */ const krb5_data * userdata, /* OUT */ krb5_data * outbuf, /* IN/OUT */ krb5_replay_data * outdata)
userdata is formatted as the user data in the message. Portions of auth_context specify the checksum type; the keyblockm which might be used to seed the checksum; full addresses (host and port) for the sender and receiver. The local_addr portion of *auth_context is used to form the addresses usedin the KRB_SAFE message. The remote_addr is optional; if the receiver's address is not known, it may be replaced by NULL. local_addr, however, is mandatory.
The auth_context flags select whether sequence numbers or timestamps should be used to identify the message. Valid flags are listed below.
Symbol | Meaning |
KRB5_AUTH_CONTEXT_DO_TIME | Use timestamps and replay cache |
KRB5_AUTH_CONTEXT_RET_TIME | Copy timestamp to *outdata |
KRB5_AUTH_CONTEXT_DO_SEQUENCE | Use sequence numbers |
KRB5_AUTH_CONTEXT_RET_SEQUENCE | Copy sequence numbers to *outdata |
If timestamps are to be used (i.e., if KRB5_AUTH_CONTEXT_DO_TIME is set), an entry describing the message will be entered in the replay cache so that the caller may detect if this message is sent back to him by an attacker. If KRB5_AUTH_CONTEXT_DO_TIME_NOTIME is not set, the auth_context replay cache is not used. If sequence numbers are to be used (i.e., if either KRB5_AUTH_CONTEXT_DO_SEQUENCE or KRB5_AUTH_CONTEXT_RET_SEQUENEC is set), then auth_context local sequence number will be placed in the protected message as its sequence number.
The outbuf buffer storage (i.e., outbuf->data) is allocated, and should be freed by the caller when finished.
krb5_error_code krb5_rd_safe(/* IN/OUT */ krb5_context context, krb5_auth_context auth_context, /* IN */ const krb5_data * inbuf, /* OUT */ krb5_data * outbuf, /* IN/OUT */ krb5_replay_data * outdata)
The keyblock used for verifying the integrity of the message is taken from the auth_context local_subkey, remote_subkey, or keyblock. The keyblock is chosen in the above order by the first one which is not NULL.
The remote_addr and localaddr portions of the *auth_context specify the full addresses (host and port) of the sender and receiver, and must be of type ADDRTYPE_ADDRPORT.
The remote_addr parameter is mandatory; it specifies the address of the sender.
If the address of the sender in the message does not match remote_addr, the error KRB5KRB_AP_ERR_BADADDR will be returned.
If local_addr is non-NULL, then the address of the receiver in the message much match it. If it is null, the receiver address in the message will be checked against the list of local addresses as returned by krb5_os_localaddr(). If the check fails, KRB5KRB_AP_ERR_BADARRD is returned.
The outbuf buffer storage (i.e., outbuf->data is allocated storage which the caller should free when it is no longer needed.
If auth_context_flags portion of auth_context indicates that sequence numbers are to be used (i.e., if KRB5_AUTH_CONTEXT_DOSEQUENCE is set in it), The remote_seq_number portion of auth_context is compared to the sequence number for the message, and KRB5_KRB_AP_ERR_BADORDER is returned if it does not match. Otherwise, the sequence number is not used.
If timestamps are to be used (i.e., if KRB5_AUTH_CONTEXT_DO_TIME is set in the auth_context), then two additional checks are performed:
krb5_error_code krb5_mk_priv(/* IN/OUT */ krb5_context context, krb5_auth_context auth_context, /* IN */ const krb5_data * userdata, /* OUT */ krb5_data * outbuf, krb5_replay_data * outdata)
inbuf, auth_context, outdata and outbuf function as in krb5_mk_safe().
As in krb5_mk_safe(), the remote_addr and remote_port part of the auth_context is optional; if the receiver's address is not known, it may be replaced by NULL. The local_addr, however, is mandatory.
The encryption type is taken from the auth_context keyblock portion. If i_vector portion of the auth_context is non-null, it is used as an initialization vector for the encryption (if the chosen encryption type supports initialization vectors) and its contents are replaced with the last block of encrypted data upon return.
The flags from the auth_context selects whether sequence numbers or timestamps should be used to identify the message. Valid flags are listed below.
Symbol | Meaning |
KRB5_AUTH_CONTEXT_DO_TIME | Use timestamps in replay cache |
KRB5_AUTH_CONTEXT_RET_TIME | Use timestamps in output data |
KRB5_AUTH_CONTEXT_DO_SEQUENCE | Use sequence numbers in replay cache |
KRB5_AUTH_CONTEXT_RET_SEQUENCE | Use sequence numbers in replay cache and output data |
krb5_error_code krb5_rd_priv(/* IN/OUT */ krb5_context context, krb5_auth_context auth_context, /* IN */ const krb5_data * inbuf, /* OUT */ krb5_data * outbuf, krb5_data * outdata)
inbuf, auth_context, outdata and outbuf function as in krb5_rd_safe().
The remote_addr part of the auth_context as set by krb5_auth_con_setaddrs() is mandatory; it specifies the address of the sender. If the address of the sender in the message does not match the remote_addr, the error KRB5KRB_AP_ERR_BADADDR will be returned.
If local_addr portion of the auth_context is non-NULL, then the address of the receiver in the message much match it. If it is null, the receiver address in the message will be checked against the list of local addresses as returned by krb5_os_localaddr().
The keyblock portion of auth_context specifies the key to be used for decryption of the message. If the i_vector element, is non-null, it is used as an initialization vector for the decryption (if the encryption type of the message supports initialization vectors) and its contents are replaced with the last block of encrypted data in the message.
The auth_context flags specify whether timestamps (KRB5_AUTH_CONTEXT_DO_TIME) and sequence numbers (KRB5_AUTH_CONTEXT_DO_SEQUENCE) are to be used.
krb5_boolean krb5_address_search(/* IN/OUT */ krb5_context context, /* IN */ const krb5_address * addr, krb5_address * const * addrlist)
krb5_boolean krb5_address_compare(/* IN/OUT */ krb5_context context, /* IN */ const krb5_address * addr1, const krb5_address * addr2)
int krb5_fulladdr_order(/* IN/OUT */ krb5_context context, /* IN */ const krb5_fulladdr * addr1, const krb5_fulladdr * addr2)
int krb5_address_order(/* IN/OUT */ krb5_context context, /* IN */ const krb5_address * addr1, const krb5_address * addr2)
krb5_error_code krb5_copy_addresses(/* IN/OUT */ krb5_context context, /* IN */ krb5_address * const * inaddr, /* OUT */ krb5_address *** outaddr)
krb5_error_code krb5_copy_authdata(/* IN/OUT */ krb5_context context, /* IN */ krb5_authdata * const * inauthdat, /* OUT */ krb5_authdata *** outauthdat)
krb5_error_code krb5_copy_authenticator(/* IN/OUT */ krb5_context context, /* IN */ const krb5_authenticator * authfrom, /* OUT */ krb5_authenticator ** authto)
krb5_error_code krb5_copy_keyblock(/* IN/OUT */ krb5_context context, /* IN */ const krb5_keyblock * from, /* OUT */ krb5_keyblock ** to)
krb5_error_code krb5_copy_keyblock_contents(/* IN/OUT */ krb5_context context, /* IN */ const krb5_keyblock * from, /* OUT */ krb5_keyblock * to)
krb5_error_code krb5_copy_checksum(/* IN/OUT */ krb5_context context, /* IN */ const krb5_checksum * ckfrom, /* OUT */ krb5_checksum ** ckto)
krb5_error_code krb5_copy_creds(/* IN/OUT */ krb5_context context, /* IN */ const krb5_creds * incred, /* OUT */ krb5_creds ** outcred)
krb5_error_code krb5_copy_data(/* IN/OUT */ krb5_context context, /* IN */ const krb5_data * indata, /* OUT */ krb5_data ** outdata)
krb5_error_code krb5_copy_ticket(/* IN/OUT */ krb5_context context, /* IN */ const krb5_ticket * from, /* OUT */ krb5_ticket ** pto)
krb5_error_code krb5_get_server_rcache(/* IN/OUT */ krb5_context context, /* IN */ const krb5_data * piece, /* OUT */ krb5_rcache * ret_rcache)
Upon successful return, ret_rcache is filled in to contain a handle to an open rcache, which should be closed with krb5_rc_close().
The credentials cache functions (some of which are macros which call to specific types of credentials caches) deal with storing credentials (tickets, session keys, and other identifying information) in a semi-permanent store for later use by different programs.
krb5_error_code krb5_cc_resolve(/* IN/OUT */ krb5_context context, /* IN */ char * string_name, /* OUT */ krb5_ccache * id)
krb5_error_code krb5_cc_gen_new(/* IN/OUT */ krb5_context context, /* IN */ krb5_cc_ops * ops, /* OUT */ krb5_ccache * id)
krb5_error_code krb5_cc_register(/* IN/OUT */ krb5_context context, /* IN */ krb5_cc_ops * ops, krb5_boolean override)
char * krb5_cc_get_name(/* IN/OUT */ krb5_context context, /* IN */ krb5_ccache id)
char * krb5_cc_default_name(/* IN/OUT */ krb5_context context)
krb5_error_code krb5_cc_default(/* IN/OUT */ krb5_context context, /* OUT */ krb5_ccache * ccache)
krb5_error_code krb5_cc_initialize(/* IN/OUT */ krb5_context context, krb5_ccache id, /* IN */ krb5_principal primary_principal)
krb5_error_code krb5_cc_destroy(/* IN/OUT */ krb5_context context, krb5_ccache id)
krb5_error_code krb5_cc_close(/* IN/OUT */ krb5_context context, krb5_ccache id)
krb5_error_code krb5_cc_store_cred(/* IN/OUT */ krb5_context context, /* IN */ krb5_ccache id, krb5_creds * creds)
krb5_error_code krb5_cc_retrieve_cred(/* IN/OUT */ krb5_context context, /* IN */ krb5_ccache id, krb5_flags whichfields, krb5_creds * mcreds, /* OUT */ krb5_creds * creds)
If at least one match is found, one of the matching credentials is returned in *creds. The credentials should be freed using krb5_free_credentials().
krb5_error_code krb5_cc_get_principal(/* IN/OUT */ krb5_context context, /* IN */ krb5_ccache id, krb5_principal * principal)
krb5_error_code krb5_cc_start_seq_get(/* IN/OUT */ krb5_context context, krb5_ccache id, /* OUT */ krb5_cc_cursor * cursor)
krb5_error_code krb5_cc_next_cred(/* IN/OUT */ krb5_context context, krb5_ccache id, /* OUT */ krb5_creds * creds, /* IN/OUT */ krb5_cc_cursor * cursor)
krb5_error_code krb5_cc_end_seq_get(/* IN/OUT */ krb5_context context, krb5_ccache id, krb5_cc_cursor * cursor)
krb5_error_code krb5_cc_remove_cred(/* IN/OUT */ krb5_context context, /* IN */ krb5_ccache id, krb5_flags which, krb5_creds * cred)
krb5_error_code krb5_cc_set_flags(/* IN/OUT */ krb5_context context, krb5_ccache id, /* IN */ krb5_flags flags)
unsigned int krb5_get_notification_message()
The replay cache functions deal with verifying that AP_REQ's do not contain duplicate authenticators; the storage must be non-volatile for the site-determined validity period of authenticators.
Each replay cache has a string "name" associated with it. The use of this name is dependent on the underlying caching strategy (for file-based things, it would be a cache file name). The caching strategy uses non-volatile storage so that replay integrity can be maintained across system failures.
krb5_error_code krb5_auth_to_rep(/* IN/OUT */ krb5_context context, /* IN */ krb5_tkt_authent * auth, /* OUT */ krb5_donot_replay * rep)
krb5_error_code krb5_rc_resolve_full(/* IN/OUT */ krb5_context context, krb5_rcache * id, /* IN */ char * string_name)
Before the cache can be used krb5_rc_initialize() or krb5_rc_recover() must be called.
krb5_error_code krb5_rc_resolve_type(/* IN/OUT */ krb5_context context, krb5_rcache * id, /* IN */ char * type)
If type is not found, krb5_rc_type_notfound is returned.
NOTE: This is an internal function, which is not necessarily intended for use by application programs. Its interface may change at any time.
krb5_error_code krb5_rc_register_type(/* IN */ krb5_context context, krb5_rc_ops * ops)
char * krb5_rc_default_name(/* IN */ krb5_context context)
char * krb5_rc_default_type(/* IN */ krb5_context context)
krb5_error_code krb5_rc_default(/* IN/OUT */ krb5_context context, krb5_rcache * id)
krb5_error_code krb5_rc_initialize(/* IN */ krb5_context context, krb5_rcache id, krb5_deltat auth_lifespan)
krb5_error_code krb5_rc_recover(/* IN */ krb5_context context, krb5_rcache id)
krb5_error_code krb5_rc_destroy(/* IN */ krb5_context context, krb5_rcache id)
krb5_error_code krb5_rc_close(/* IN */ krb5_context context, krb5_rcache id)
krb5_error_code krb5_rc_store(/* IN */ krb5_context context, krb5_rcache id, krb5_donot_replay * rep)
Returns KRB5KRB_AP_ERR_REPEAT if rep is already in the cache. May also return permission errors, storage failure errors.
krb5_error_code krb5_rc_expunge(/* IN */ krb5_context context, krb5_rcache id)
krb5_error_code krb5_rc_get_lifespan(/* IN */ krb5_context context, krb5_rcache id, /* OUT */ krb5_deltat * auth_lifespan)
krb5_error_code krb5_rc_resolve(/* IN/OUT */ krb5_context context, krb5_rcache id, /* IN */ char * name)
Since krb5_rc_resolve() allocates memory, krb5_rc_close() must be called to free the allocated memory, even if neither krb5_rc_initialize() or krb5_rc_recover() were successfully called by the application.
char * krb5_rc_get_name(/* IN */ krb5_context context, krb5_rcache id)
char * krb5_rc_get_type(/* IN */ krb5_context context, krb5_rcache id)
The key table functions deal with storing and retrieving service keys for use by unattended services which participate in authentication exchanges.
Keytab routines are all be atomic. Every routine that acquires a non-sharable resource releases it before it returns.
All keytab types support multiple concurrent sequential scans.
The order of values returned from krb5_kt_next_entry() is unspecified.
Although the "right thing" should happen if the program aborts abnormally, a close routine, krb5_kt_free_entry(), is provided for freeing resources, etc. People should use the close routine when they are finished.
krb5_error_code krb5_kt_register(/* IN/OUT */ krb5_context context, /* IN */ krb5_kt_ops * ops)
krb5_error_code krb5_kt_resolve(/* IN/OUT */ krb5_context context, /* IN */ const char * string_name, /* OUT */ krb5_keytab * id)
krb5_error_code krb5_kt_default_name(/* IN/OUT */ krb5_context context, /* IN */ char * name, int namesize)
krb5_error_code krb5_kt_default(/* IN/OUT */ krb5_context context, /* IN */ krb5_keytab * id)
krb5_error_code krb5_kt_read_service_key(/* IN/OUT */ krb5_context context, /* IN */ krb5_pointer keyprocarg, krb5_principal principal, krb5_kvno vno, krb5_keytype keytype, /* OUT */ krb5_keyblock ** key)
krb5_free_keyblock() should be called on *key when the caller is finished with the key.
krb5_error_code krb5_kt_add_entry(/* IN/OUT */ krb5_context context, /* IN */ krb5_keytab id, krb5_keytab_entry * entry)
krb5_error_code krb5_kt_remove_entry(/* IN/OUT */ krb5_context context, /* IN */ krb5_keytab id, krb5_keytab_entry * entry)
krb5_error_code krb5_kt_get_name(/* IN/OUT */ krb5_context context, krb5_keytab id, /* OUT */ char * name, /* IN */ int namesize)
krb5_error_code krb5_kt_close(/* IN/OUT */ krb5_context context, krb5_keytab id)
krb5_error_code krb5_kt_get_entry(/* IN/OUT */ krb5_context context, krb5_keytab id, /* IN */ krb5_principal principal, krb5_kvno vno, krb5_keytype keytype, /* OUT */ krb5_keytab_entry * entry)
krb5_error_code krb5_kt_free_entry(/* IN/OUT */ krb5_context context, krb5_keytab_entry * entry)
krb5_error_code krb5_kt_start_seq_get(/* IN/OUT */ krb5_context context, krb5_keytab id, /* OUT */ krb5_kt_cursor * cursor)
krb5_error_code krb5_kt_next_entry(/* IN/OUT */ krb5_context context, krb5_keytab id, /* OUT */ krb5_keytab_entry * entry, /* IN/OUT */ krb5_kt_cursor * cursor)
krb5_error_code krb5_kt_end_seq_get(/* IN/OUT */ krb5_context context, krb5_keytab id, krb5_kt_cursor * cursor)
The free functions deal with deallocation of memory that has been allocated by various routines. It is recommended that the developer use these routines as they will know about the contents of the structures.
void krb5_xfree(/* IN/OUT */ void * ptr)
void krb5_free_data(/* IN/OUT */ krb5_context context, krb5_data * val)
void krb5_free_princial(/* IN/OUT */ krb5_context context, krb5_principal val)
void krb5_free_authenticator(/* IN/OUT */ krb5_context context, krb5_authenticator * val)
void krb5_free_authenticator_contents(/* IN/OUT */ krb5_context context, krb5_authenticator * val)
void krb5_free_addresses(/* IN/OUT */ krb5_context context, krb5_address ** val)
void krb5_free_address(/* IN/OUT */ krb5_context context, krb5_address * val)
void krb5_free_authdata(/* IN/OUT */ krb5_context context, krb5_authdata ** val)
void krb5_free_enc_tkt_part(/* IN/OUT */ krb5_context context, krb5_enc_tkt_part * val)
void krb5_free_ticket(/* IN/OUT */ krb5_context context, krb5_ticket * val)
void krb5_free_tickets(/* IN/OUT */ krb5_context context, krb5_ticket ** val)
void krb5_free_kdc_req(/* IN/OUT */ krb5_context context, krb5_kdc_req * val)
void krb5_free_kdc_rep(/* IN/OUT */ krb5_context context, krb5_kdc_rep * val)
void krb5_free_kdc_rep_part(/* IN/OUT */ krb5_context context, krb5_enc_kdc_rep_part * val)
void krb5_free_error(/* IN/OUT */ krb5_context context, krb5_error * val)
void krb5_free_ap_req(/* IN/OUT */ krb5_context context, krb5_ap_req * val)
void krb5_free_ap_rep(/* IN/OUT */ krb5_context context, krb5_ap_rep * val)
void krb5_free_safe(/* IN/OUT */ krb5_context context, krb5_safe * val)
void krb5_free_priv(/* IN/OUT */ krb5_context context, krb5_priv * val)
void krb5_free_priv_enc_part(/* IN/OUT */ krb5_context context, krb5_priv_enc_part * val)
void krb5_free_cred(/* IN/OUT */ krb5_context context, krb5_cred * val)
void krb5_free_creds(/* IN/OUT */ krb5_context context, krb5_creds * val)
void krb5_free_cred_contents(/* IN/OUT */ krb5_context context, krb5_creds * val)
void krb5_free_cred_enc_part(/* IN/OUT */ krb5_context context, krb5_cred_enc_part * val)
void krb5_free_checksum(/* IN/OUT */ krb5_context context, krb5_checksum * val)
void krb5_free_keyblock(/* IN/OUT */ krb5_context context, krb5_keyblock * val)
void krb5_free_pa_data(/* IN/OUT */ krb5_context context, krb5_pa_data ** val)
void krb5_free_ap_rep_enc_part(/* IN/OUT */ krb5_context context, krb5_ap_rep_enc_part * val)
void krb5_free_tkt_authent(/* IN/OUT */ krb5_context context, krb5_tkt_authent * val)
void krb5_free_pwd_data(/* IN/OUT */ krb5_context context, passwd_pwd_data * val)
void krb5_free_pwd_sequences(/* IN/OUT */ krb5_context context, passwd_phrase_element ** val)
void krb5_free_realm_tree(/* IN/OUT */ krb5_context context, krb5_principal * realms)
void krb5_free_tgt_creds(/* IN/OUT */ krb5_context context, krb5_creds ** tgts)
The operating-system specific functions provide an interface between the other parts of the libkrb5.a libraries and the operating system.
Beware! Any of the functions below are allowed to be implemented as macros.
Prototypes for functions can be found in The following global symbols are provided in libos.a. If you wish to
substitute for any of them, you must substitute for all of them
(they are all declared and initialized in the same object file):
extern char *krb5_defkeyname default name of key table file extern char *krb5_lname_file name of aname/lname translation database extern int krb5_max_dgram_size maximum allowable datagram size extern int krb5_max_skdc_timeout maximum per-message KDC reply timeout extern int krb5_skdc_timeout_shift shift factor (bits) to exponentially back-off the KDC timeouts extern int krb5_skdc_timeout_1 initial KDC timeout extern char *krb5_kdc_udp_portname name of KDC UDP port extern char *krb5_default_pwd_prompt1 first prompt for password reading. extern char *krb5_default_pwd_prompt2 second prompt
The krb5_context has space for operating system specific data. These functions are called from krb5_init_context() and krb5_free_context(), but are included here for completeness.
krb5_error_code krb5_os_init_context(/* IN/OUT */ krb5_context context)
krb5_error_code krb5_os_free_context(/* IN/OUT */ krb5_context context)
krb5_error_code krb5_set_config_files(/* IN/OUT */ krb5_context context, /* IN */ const char ** filenames)
krb5_error_code krb5_get_krbhst(/* IN */ krb5_context context, const krb5_data * realm, /* OUT */ char *** hostlist)
If realm is unknown, the filled-in pointer is set to NULL.
The pointer array and strings pointed to are all in allocated storage, and should be freed by the caller when finished.
krb5_error_code krb5_free_krbhst(/* IN */ krb5_context context, char * const * hostlist)
krb5_error_code krb5_get_default_realm(/* IN */ krb5_context context, /* OUT */ char ** lrealm)
krb5_error_code krb5_set_default_realm(/* IN */ krb5_context context, char * realm)
If realm is NULL, then the operating system default value will used.
krb5_error_code krb5_get_host_realm(/* IN */ krb5_context context, const char * host, /* OUT */ char *** realmlist)
If host is NULL, the local host's realms are determined.
If there are no known realms for the host, the filled-in pointer is set to NULL.
The pointer array and strings pointed to are all in allocated storage, and should be freed by the caller when finished.
krb5_error_code krb5_free_host_realm(/* IN */ krb5_context context, char * const * realmlist)
krb5_error_code krb5_get_realm_domain(/* IN/OUT */ krb5_context context, /* IN */ const char * realm, /* OUT */ char ** domain)
These functions all relate to disk based I/O.
krb5_error_code krb5_lock_file(/* IN */ krb5_context context, int fd, int mode)
The caller should arrange for the file referred by fd to be opened in such a way as to allow the required lock.
Modes are given in
krb5_error_code krb5_unlock_file(/* IN */ krb5_context context, int fd)
krb5_error_code krb5_create_secure_file(/* IN */ krb5_context context, const char * pathname)
krb5_error_code krb5_sync_disk_file(/* IN */ krb5_context context, FILE * fp)
These routines send and receive network data the specifics of addresses and families on a given operating system.
krb5_error_code krb5_os_localaddr(/* IN */ krb5_context context, /* OUT */ krb5_address *** addr)
Compile-time configuration flags will indicate which protocol family addresses might be returned. *addr is filled in to point to an array of address pointers, terminated by a null pointer. All the storage pointed to is allocated and should be freed by the caller with krb5_free_address() when no longer needed.
krb5_error_code krb5_gen_portaddr(/* IN */ krb5_context context, const krb5_address * adr, krb5_const_pointer ptr, /* OUT */ krb5_address ** outaddr)
krb5_error_code krb5_sendto_kdc(/* IN */ krb5_context context, const krb5_data * send, const krb5_data * realm, /* OUT */ krb5_data * receive)
If the message is sent and a response is received, 0 is returned, otherwise an error code is returned.
The storage for receive is allocated and should be freed by the caller when finished.
int krb5_net_read(/* IN */ krb5_context context, int fd, /* OUT */ char * buf, /* IN */ int len)
(make sure your sender will send all the stuff you are looking for!) Only useful on stream sockets and pipes.
int krb5_net_write(/* IN */ krb5_context context, int fd, const char * buf, int len)
Only useful on stream sockets and pipes.
krb5_error_code krb5_write_message(/* IN */ krb5_context context, krb5_pointer fd, krb5_data * data)
krb5_error_code krb5_read_message(/* IN */ krb5_context context, krb5_pointer fd, /* OUT */ krb5_data * data)
These functions are involved with access control decisions and policies.
krb5_error_code krb5_aname_to_localname(/* IN */ krb5_context context, krb5_const_principal aname, int lnsize, /* OUT */ char * lname)
lnsize specifies the maximum length name that is to be filled into lname. The translation will be null terminated in all non-error returns.
krb5_boolean krb5_kuserok(/* IN */ krb5_context context, krb5_principal principal, const char * luser)
krb5_error_code krb5_sname_to_principal(/* IN */ krb5_context context, const char * hostname, const char * sname, krb5_int32 type, /* OUT */ krb5_principal * ret_princ)
The realm of the principal is determined internally by calling krb5_get_host_realm().
The type argument controls how krb5_sname_to_principal() generates the principal name, ret_princ, for the named service, sname. Currently, two values are supported: KRB5_NT_SRV_HOST, and KRB5_NT_UNKNOWN.
If type is set to KRB5_NT_SRV_HOST, the hostname will be canonicalized, i.e. a fully qualified lowercase hostname using the primary name and the domain name, before ret_princ is generated in the form "sname/hostname@LOCAL.REALM." Most applications should use KRB5_NT_SRV_HOST.
However, if type is set to KRB5_NT_UNKNOWN, while the generated principal name will have the form "sname/hostname@LOCAL.REALM" the hostname will not be canonicalized first. It will appear exactly as it was passed in hostname.
The caller should release ret_princ's storage by calling krb5_free_principal() when it is finished with the principal.
These functions handle the other operating specific functions that do not fall into any other major class.
krb5_error_code krb5_timeofday(/* IN */ krb5_context context, /* OUT */ krb5_context context, krb5_int32 * timeret)
krb5_error_code krb5_us_timeofday(/* IN */ krb5_context context, /* OUT */ krb5_int32 * seconds, krb5_int32 * microseconds)
krb5_error_code krb5_read_password(/* IN */ krb5_context context, const char * prompt, const char * prompt2, /* OUT */ char * return_pwd, /* IN/OUT */ int * size_return)
prompt is used as the prompt for the first reading of a password. It is printed to the terminal, and then a password is read from the keyboard. No newline or spaces are emitted between the prompt and the cursor, unless the newline/space is included in the prompt.
If prompt2 is a null pointer, then the password is read once. If prompt2 is set, then it is used as a prompt to read another password in the same manner as described for prompt. After the second password is read, the two passwords are compared, and an error is returned if they are not identical.
Echoing is turned off when the password is read.
krb5_error_code krb5_random_confounder(/* IN */ krb5_context context, int size, /* OUT */ krb5_pointer fillin)
krb5_error_code krb5_gen_replay_name(/* IN */ krb5_context context, const krb5_address * inaddr, const char * uniq, /* OUT */ char ** string)