mlx5dv_crypto_lo...to_login_destroy(3)

💖 mlx5dv_crypto_login_create(3), mlx5dv_crypto_login_query(3), mlx5dv_crypto_login_destroy(3) 💖

okay so bestie, this is the mlx5dv_crypto_lo...to_login_destroy(3) page from the mlx5dv_crypto family of manual pages — yes the whole trio is crammed into one page, we love an efficient queen ✨

---

🌸 NAME 🌸

• mlx5dv_crypto_login_create — literally creates a crypto login object 🎀
• mlx5dv_crypto_login_query — queries the given crypto login object, like a vibe check but for creds 🔍
• mlx5dv_crypto_login_destroy — destroys the given crypto login object 💀

---

✨ SYNOPSIS ✨

#include <infiniband/mlx5dv.h>

struct mlx5dv_crypto_login_obj *
mlx5dv_crypto_login_create(struct ibv_context *context,
               struct mlx5dv_crypto_login_attr_ex *login_attr);

int mlx5dv_crypto_login_query(struct mlx5dv_crypto_login_obj *crypto_login,
                  struct mlx5dv_crypto_login_query_attr *query_attr);

int mlx5dv_crypto_login_destroy(struct mlx5dv_crypto_login_obj *crypto_login);

---

🦋 DESCRIPTION 🦋

So here's the tea ☕ — when you're using a crypto engine that's in wrapped import method, you must hand it a valid crypto login object in order to create and query wrapped Data Encryption Keys (DEKs). No object, no DEKs, periodt.

But like, don't panic 💅 — a valid crypto login object is necessary only to create and query wrapped DEKs. Existing DEKs that were previously created don't need a valid crypto login object in order to be used (in MKey or during traffic). They're already living their best life, no login required 🙌

mlx5dv_crypto_login_create() creates and returns a crypto login object with the credential given in login_attr. Heads up though — only one crypto login object can be created per device context. That's it. One. Main character energy only 👑 The created crypto login object must be provided to mlx5dv_dek_create() in order to create wrapped DEKs.

mlx5dv_crypto_login_query() queries the crypto login object crypto_login and returns the queried attributes in query_attr. It's giving "so tell me about yourself" 🫶

mlx5dv_crypto_login_destroy() destroys the given crypto login object. Bye bestie 💀✨

---

🎀 ARGUMENTS 🎀

context

The device context that will be associated with the crypto login object. Basically the setting where this whole thing goes down 🏠

login_attr

Crypto extended login attributes — they specify the credential to login with and the import KEK to be used for secured communications done with the crypto login object. So many jobs, but she handles it 🔥

struct mlx5dv_crypto_login_attr_ex {
    uint32_t credential_id;
    uint32_t import_kek_id;
    const void *credential;
    size_t credential_len;
    uint64_t comp_mask;
};

credential_id

An ID of a credential, from the credentials stored on the device, that indicates the credential that should be validated against the credential provided in credential. Think of it as the name tag pointing at which stored credential to check against 🏷️

import_kek_id

An ID of an import KEK, from the import KEKs stored on the device, that indicates the import KEK that will be used for unwrapping the credential provided in credential — and also for all other secured communications done with the crypto login object. It's the multitasking icon we deserve 💅

credential

The credential to login with. Credential is a piece of data used to authenticate the user for crypto login. The credential in credential is validated against the credential indicated by credential_id, which is stored on the device. The credentials must match in order for the crypto login to succeed — no match, no entry, sorry bestie 😭

credential must be provided wrapped by the AES key wrap algorithm using the import KEK indicated by import_kek_id. And the credential format is:

ENC(iv_64b + plaintext_credential)

where ENC() is the AES key wrap algorithm and iv_64b is 0xA6A6A6A6A6A6A6A6 as per the NIST SP 800-38F AES key wrap spec, and plaintext_credential is the credential value stored on the device. Very specific, very demure ✨

credential_len

The length of the provided credential value in bytes. 📏

comp_mask

Reserved for future extension, must be 0 now. Don't be cute and put something else in there 🙈

query_attr

Crypto login attributes to be populated when querying a crypto login object. She gets filled in when you ask 🫶

struct mlx5dv_crypto_login_query_attr {
    enum mlx5dv_crypto_login_state state;
    uint64_t comp_mask;
};

state

The state of the crypto login object, can be one of the following:

• MLX5DV_CRYPTO_LOGIN_STATE_VALID — the crypto login object is valid and can be used. Slay 💖
• MLX5DV_CRYPTO_LOGIN_STATE_INVALID — the crypto login object is invalid and cannot be used. A valid crypto login object can become invalid if the credential or the import KEK used in the crypto login object were deleted while in use (for example by a crypto officer). Rough, I know 😭 In this case, mlx5dv_crypto_login_destroy() should be called to destroy the invalid crypto login object, and if still necessary, mlx5dv_crypto_login_create() should be called to create a new crypto login object with valid credential and import KEK. Glow-up arc 🔥

comp_mask

Reserved for future extension, must be 0 now. Same rule as before, bestie — zero it out 🙏

---

👑 RETURN VALUE 👑

• mlx5dv_crypto_login_create() returns a pointer to a new valid struct mlx5dv_crypto_login_obj on success. On error NULL is returned and errno is set. 🎀
• mlx5dv_crypto_login_query() returns 0 on success and fills query_attr with the queried attributes. On error, errno is returned.
• mlx5dv_crypto_login_destroy() returns 0 on success and errno on error.

---

🌈 SEE ALSO 🌈

• mlx5dv_dek_create(3)
• mlx5dv_query_device(3)

---

💜 AUTHORS 💜

Avihai Horon <avihaih@nvidia.com> — thank you for your service 🫶

---

fr fr, that's the whole page. go forth and login responsibly ✨

---

sign-off szn 🦋 this lil masterpiece lives in mlx5dv_crypto_lo...to_login_destroy(3) land, sourced from the same, and it's dated the same as the original page footer — mwah, love u, bye 💅💖