krb5_credential(3)

💖 krb5_credential — Heimdal Kerberos 5 credential handing functions 💖

okay bestie, gather round, because we're doing credentials today. this is the krb5_credential(3) page from the Heimdal Kerberos 5 library, and it's literally the whole vibe of "how do i prove who i am to a realm and get a ticket about it". pull up a chair, grab a strawberry 🍓, we're going in.

---

✨ NAME ✨

krb5_credential — Heimdal Kerberos 5 credential handing functions

like. that's the whole name section. it's giving "introduce yourself in one line". iconic. 👑

---

✨ SYNOPSIS ✨

🌸 Functions 🌸

okay so here's the whole cast of characters, fr fr. every one of these is a real function with a real signature and i am NOT paraphrasing a single one of them, no cap. 👇

KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_fwd_tgt_creds
    (krb5_context context, krb5_auth_context auth_context, const char *hostname,
     krb5_principal client, krb5_principal server, krb5_ccache ccache,
     int forwardable, krb5_data *out_data)

KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_get_forwarded_creds
    (krb5_context context, krb5_auth_context auth_context, krb5_ccache ccache,
     krb5_flags flags, const char *hostname, krb5_creds *in_creds,
     krb5_data *out_data)

KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_get_init_creds_opt_alloc
    (krb5_context context, krb5_get_init_creds_opt **opt)

KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_get_init_creds_opt_free
    (krb5_context context, krb5_get_init_creds_opt *opt)

KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_init_creds_init
    (krb5_context context, krb5_principal client, krb5_prompter_fct prompter,
     void *prompter_data, krb5_deltat start_time,
     krb5_get_init_creds_opt *options, krb5_init_creds_context *rctx)

KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_init_creds_set_service
    (krb5_context context, krb5_init_creds_context ctx, const char *service)

KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_init_creds_set_password
    (krb5_context context, krb5_init_creds_context ctx, const char *password)

KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_init_creds_set_keytab
    (krb5_context context, krb5_init_creds_context ctx, krb5_keytab keytab)

KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_init_creds_step
    (krb5_context context, krb5_init_creds_context ctx, krb5_data *in,
     krb5_data *out, krb5_krbhst_info *hostinfo, unsigned int *flags)

KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_init_creds_get_error
    (krb5_context context, krb5_init_creds_context ctx, KRB_ERROR *error)

KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_init_creds_free
    (krb5_context context, krb5_init_creds_context ctx)

KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_init_creds_get
    (krb5_context context, krb5_init_creds_context ctx)

KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_get_init_creds_password
    (krb5_context context, krb5_creds *creds, krb5_principal client,
     const char *password, krb5_prompter_fct prompter, void *data,
     krb5_deltat start_time, const char *in_tkt_service,
     krb5_get_init_creds_opt *options)

KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_get_init_creds_keyblock
    (krb5_context context, krb5_creds *creds, krb5_principal client,
     krb5_keyblock *keyblock, krb5_deltat start_time,
     const char *in_tkt_service, krb5_get_init_creds_opt *options)

KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_get_init_creds_keytab
    (krb5_context context, krb5_creds *creds, krb5_principal client,
     krb5_keytab keytab, krb5_deltat start_time,
     const char *in_tkt_service, krb5_get_init_creds_opt *options)

and here's the roll call, one by one, because every single one of these matters and i refuse to skip any:

• krb5_fwd_tgt_creds — returns a krb5_error_code, takes krb5_context context, krb5_auth_context auth_context, const char *hostname, krb5_principal client, krb5_principal server, krb5_ccache ccache, int forwardable, and krb5_data *out_data. forwarding tgt vibes, we love to see it 🦋
• krb5_get_forwarded_creds — returns krb5_error_code, takes krb5_context context, krb5_auth_context auth_context, krb5_ccache ccache, krb5_flags flags, const char *hostname, krb5_creds *in_creds, and krb5_data *out_data. yes bestie, "get" AND "forwarded" in the same name, she contains multitudes ✨
• krb5_get_init_creds_opt_alloc — returns krb5_error_code, takes krb5_context context and a krb5_get_init_creds_opt **opt. this is the one that hands you the options object. no opt, no options, iykyk 💅
• krb5_get_init_creds_opt_free — returns void (not a krb5_error_code! she's built different, she's the cleanup girlie 🧹) and takes krb5_context context and krb5_get_init_creds_opt *opt.
• krb5_init_creds_init — returns krb5_error_code, takes krb5_context context, krb5_principal client, krb5_prompter_fct prompter, void *prompter_data, krb5_deltat start_time, krb5_get_init_creds_opt *options, and krb5_init_creds_context *rctx. the setup era 🌱
• krb5_init_creds_set_service — returns krb5_error_code, takes krb5_context context, krb5_init_creds_context ctx, and const char *service.
• krb5_init_creds_set_password — returns krb5_error_code, takes krb5_context context, krb5_init_creds_context ctx, and const char *password. (shhh. that's a secret. don't log it 🙈)
• krb5_init_creds_set_keytab — returns krb5_error_code, takes krb5_context context, krb5_init_creds_context ctx, and krb5_keytab keytab.
• krb5_init_creds_step — returns krb5_error_code, takes krb5_context context, krb5_init_creds_context ctx, krb5_data *in, krb5_data *out, krb5_krbhst_info *hostinfo, and unsigned int *flags. one step at a time bestie, that's literally the whole philosophy 🫶
• krb5_init_creds_get_error — returns krb5_error_code, takes krb5_context context, krb5_init_creds_context ctx, and KRB_ERROR *error.
• krb5_init_creds_free — returns void again, takes krb5_context context and krb5_init_creds_context ctx. cleanup queen, we stan 💜
• krb5_init_creds_get — returns krb5_error_code, takes krb5_context context and krb5_init_creds_context ctx.
• krb5_get_init_creds_password — returns krb5_error_code, takes krb5_context context, krb5_creds *creds, krb5_principal client, const char *password, krb5_prompter_fct prompter, void *data, krb5_deltat start_time, const char *in_tkt_service, and krb5_get_init_creds_opt *options. the classic. the main character. ⭐
• krb5_get_init_creds_keyblock — returns krb5_error_code, takes krb5_context context, krb5_creds *creds, krb5_principal client, krb5_keyblock *keyblock, krb5_deltat start_time, const char *in_tkt_service, and krb5_get_init_creds_opt *options.
• krb5_get_init_creds_keytab — returns krb5_error_code, takes krb5_context context, krb5_creds *creds, krb5_principal client, krb5_keytab keytab, krb5_deltat start_time, const char *in_tkt_service, and krb5_get_init_creds_opt *options.

and that's the whole lineup 🎀. every prototype, zero edits, zero skipped, periodt.

---

✨ Detailed Description ✨

(okay bestie, this is where part 2 picks up — don't go anywhere, the deep dive is coming and it's gonna slay 💖)

✨ Function Documentation ✨

Okay bestie, this is the function part — main character energy only. Every signature is copied exactly, no cap. Let's go. 💅

---

krb5_fwd_tgt_creds

KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_fwd_tgt_creds
       (krb5_context context, krb5_auth_context auth_context, const char *
       hostname, krb5_principal client, krb5_principal server, krb5_ccache
       ccache, int forwardable, krb5_data * out_data)

Forward credentials for client to host hostname, making them forwardable if forwardable, and returning the blob of data to sent in out_data. If hostname == NULL, pick it from server.

Parameters:

• context — A kerberos 5 context.
• auth_context — the auth context with the key to encrypt the out_data.
• hostname — the host to forward the tickets too.
• client — the client to delegate from.
• server — the server to delegate the credential too.
• ccache — credential cache to use.
• forwardable — make the forwarded ticket forwabledable.
• out_data — the resulting credential.

Returns: Return an error code or 0.

---

krb5_get_forwarded_creds

KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_get_forwarded_creds
       (krb5_context context, krb5_auth_context auth_context, krb5_ccache
       ccache, krb5_flags flags, const char * hostname, krb5_creds * in_creds,
       krb5_data * out_data)

Gets tickets forwarded to hostname. If the tickets that are forwarded are address-less, the forwarded tickets will also be address-less.

If the ticket have any address, hostname will be used for figure out the address to forward the ticket too. This since this might use DNS, its insecure and also doesn't represent configured all addresses of the host. For example, the host might have two adresses, one IPv4 and one IPv6 address where the later is not published in DNS. This IPv6 address might be used communications and thus the resulting ticket useless.

Parameters:

• context — A kerberos 5 context.
• auth_context — the auth context with the key to encrypt the out_data.
• ccache — credential cache to use
• flags — the flags to control the resulting ticket flags
• hostname — the host to forward the tickets too.
• in_creds — the in client and server ticket names. The client and server components forwarded to the remote host.
• out_data — the resulting credential.

Returns: Return an error code or 0.

Some older of the MIT gssapi library used clear-text tickets (warped inside AP-REQ encryption), use the krb5_auth_context flag KRB5_AUTH_CONTEXT_CLEAR_FORWARDED_CRED to support those tickets. The session key is used otherwise to encrypt the forwarded ticket.

---

krb5_get_init_creds_keyblock

KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_get_init_creds_keyblock
       (krb5_context context, krb5_creds * creds, krb5_principal client,
       krb5_keyblock * keyblock, krb5_deltat start_time, const char *
       in_tkt_service, krb5_get_init_creds_opt * options)

Get new credentials using keyblock.

---

krb5_get_init_creds_keytab

KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_get_init_creds_keytab
       (krb5_context context, krb5_creds * creds, krb5_principal client,
       krb5_keytab keytab, krb5_deltat start_time, const char * in_tkt_service,
       krb5_get_init_creds_opt * options)

Get new credentials using keytab.

---

krb5_get_init_creds_opt_alloc

KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL
       krb5_get_init_creds_opt_alloc (krb5_context context,
       krb5_get_init_creds_opt ** opt)

Allocate a new krb5_get_init_creds_opt structure, free with krb5_get_init_creds_opt_free().

---

krb5_get_init_creds_opt_free

KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_get_init_creds_opt_free
       (krb5_context context, krb5_get_init_creds_opt * opt)

Free krb5_get_init_creds_opt structure.

---

krb5_get_init_creds_password

KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_get_init_creds_password
       (krb5_context context, krb5_creds * creds, krb5_principal client, const
       char * password, krb5_prompter_fct prompter, void * data, krb5_deltat
       start_time, const char * in_tkt_service, krb5_get_init_creds_opt *
       options)

Get new credentials using password.

---

krb5_init_creds_free

KRB5_LIB_FUNCTION void KRB5_LIB_CALL krb5_init_creds_free (krb5_context
       context, krb5_init_creds_context ctx)

Free the krb5_init_creds_context allocated by krb5_init_creds_init().

Parameters:

• context — A Kerberos 5 context.
• ctx — The krb5_init_creds_context to free.

---

krb5_init_creds_get

KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_init_creds_get
       (krb5_context context, krb5_init_creds_context ctx)

Get new credentials as setup by the krb5_init_creds_context.

Parameters:

• context — A Kerberos 5 context.
• ctx — The krb5_init_creds_context to process.

---

krb5_init_creds_get_error

KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_init_creds_get_error
       (krb5_context context, krb5_init_creds_context ctx, KRB_ERROR * error)

Get the last error from the transaction.

Returns: Returns 0 or an error code

---

krb5_init_creds_init

KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_init_creds_init
       (krb5_context context, krb5_principal client, krb5_prompter_fct
       prompter, void * prompter_data, krb5_deltat start_time,
       krb5_get_init_creds_opt * options, krb5_init_creds_context * rctx)

Start a new context to get a new initial credential.

Parameters:

• context — A Kerberos 5 context.
• client — The Kerberos principal to get the credential for, if NULL is given, the default principal is used as determined by krb5_get_default_principal().
• prompter
• prompter_data
• start_time — the time the ticket should start to be valid or 0 for now.
• options — a options structure, can be NULL for default options.
• rctx — A new allocated free with krb5_init_creds_free().

Returns: 0 for success or an Kerberos 5 error code, see krb5_get_error_message().

---

krb5_init_creds_set_keytab

KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_init_creds_set_keytab
       (krb5_context context, krb5_init_creds_context ctx, krb5_keytab keytab)

Set the keytab to use for authentication.

Parameters:

• context — a Kerberos 5 context.
• ctx — ctx krb5_init_creds_context context.
• keytab — the keytab to read the key from.

Returns: 0 for success, or an Kerberos 5 error code, see krb5_get_error_message().

---

krb5_init_creds_set_password

KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_init_creds_set_password
       (krb5_context context, krb5_init_creds_context ctx, const char *
       password)

Sets the password that will use for the request.

Parameters:

• context — a Kerberos 5 context.
• ctx — ctx krb5_init_creds_context context.
• password — the password to use.

Returns: 0 for success, or an Kerberos 5 error code, see krb5_get_error_message().

---

krb5_init_creds_set_service

KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_init_creds_set_service
       (krb5_context context, krb5_init_creds_context ctx, const char *
       service)

Sets the service that the is requested. This call is only neede for special initial tickets, by default the a krbtgt is fetched in the default realm.

Parameters:

• context — a Kerberos 5 context.
• ctx — a krb5_init_creds_context context.
• service — the service given as a string, for example 'kadmind/admin'. If NULL, the default krbtgt in the clients realm is set.

Returns: 0 for success, or an Kerberos 5 error code, see krb5_get_error_message().

---

krb5_init_creds_step

KRB5_LIB_FUNCTION krb5_error_code KRB5_LIB_CALL krb5_init_creds_step
       (krb5_context context, krb5_init_creds_context ctx, krb5_data * in,
       krb5_data * out, krb5_krbhst_info * hostinfo, unsigned int * flags)

The core loop if krb5_get_init_creds() function family. Create the packets and have the caller send them off to the KDC.

If the caller want all work been done for them, use krb5_init_creds_get() instead.

Parameters:

• context — a Kerberos 5 context.
• ctx — ctx krb5_init_creds_context context.
• in — input data from KDC, first round it should be reset by krb5_data_zer().
• out — reply to KDC.
• hostinfo — KDC address info, first round it can be NULL.
• flags — status of the round, if KRB5_INIT_CREDS_STEP_FLAG_CONTINUE is set, continue one more round.

Returns: 0 for success, or an Kerberos 5 error code, see krb5_get_error_message().

---

📝 Author 📝

Generated automatically by Doxygen for Heimdal Kerberos 5 library from the source code.

---

And that's the whole page, bestie! Version 7.8.0, dated Tue Nov 15 2022, and this was krb5_credential(3). You absolutely ate. 💅✨