crypto/internal/kpp.h

0001 /* SPDX-License-Identifier: GPL-2.0-or-later */
0002 /*
0003  * Key-agreement Protocol Primitives (KPP)
0004  *
0005  * Copyright (c) 2016, Intel Corporation
0006  * Authors: Salvatore Benedetto <salvatore.benedetto@intel.com>
0007  */
0008 #ifndef _CRYPTO_KPP_INT_H
0009 #define _CRYPTO_KPP_INT_H
0010 #include <crypto/kpp.h>
0011 #include <crypto/algapi.h>
0012
0013 /**
0014  * struct kpp_instance - KPP template instance
0015  * @free: Callback getting invoked upon instance destruction. Must be set.
0016  * @s: Internal. Generic crypto core instance state properly layout
0017  *     to alias with @alg as needed.
0018  * @alg: The &struct kpp_alg implementation provided by the instance.
0019  */
0020 struct kpp_instance {
0021     void (*free)(struct kpp_instance *inst);
0022     union {
0023         struct {
0024             char head[offsetof(struct kpp_alg, base)];
0025             struct crypto_instance base;
0026         } s;
0027         struct kpp_alg alg;
0028     };
0029 };
0030
0031 /**
0032  * struct crypto_kpp_spawn - KPP algorithm spawn
0033  * @base: Internal. Generic crypto core spawn state.
0034  *
0035  * Template instances can get a hold on some inner KPP algorithm by
0036  * binding a &struct crypto_kpp_spawn via
0037  * crypto_grab_kpp(). Transforms may subsequently get instantiated
0038  * from the referenced inner &struct kpp_alg by means of
0039  * crypto_spawn_kpp().
0040  */
0041 struct crypto_kpp_spawn {
0042     struct crypto_spawn base;
0043 };
0044
0045 /*
0046  * Transform internal helpers.
0047  */
0048 static inline void *kpp_request_ctx(struct kpp_request *req)
0049 {
0050     return req->__ctx;
0051 }
0052
0053 static inline void *kpp_tfm_ctx(struct crypto_kpp *tfm)
0054 {
0055     return tfm->base.__crt_ctx;
0056 }
0057
0058 static inline void kpp_request_complete(struct kpp_request *req, int err)
0059 {
0060     req->base.complete(&req->base, err);
0061 }
0062
0063 static inline const char *kpp_alg_name(struct crypto_kpp *tfm)
0064 {
0065     return crypto_kpp_tfm(tfm)->__crt_alg->cra_name;
0066 }
0067
0068 /*
0069  * Template instance internal helpers.
0070  */
0071 /**
0072  * kpp_crypto_instance() - Cast a &struct kpp_instance to the corresponding
0073  *                         generic &struct crypto_instance.
0074  * @inst: Pointer to the &struct kpp_instance to be cast.
0075  * Return: A pointer to the &struct crypto_instance embedded in @inst.
0076  */
0077 static inline struct crypto_instance *kpp_crypto_instance(
0078     struct kpp_instance *inst)
0079 {
0080     return &inst->s.base;
0081 }
0082
0083 /**
0084  * kpp_instance() - Cast a generic &struct crypto_instance to the corresponding
0085  *                  &struct kpp_instance.
0086  * @inst: Pointer to the &struct crypto_instance to be cast.
0087  * Return: A pointer to the &struct kpp_instance @inst is embedded in.
0088  */
0089 static inline struct kpp_instance *kpp_instance(struct crypto_instance *inst)
0090 {
0091     return container_of(inst, struct kpp_instance, s.base);
0092 }
0093
0094 /**
0095  * kpp_alg_instance() - Get the &struct kpp_instance a given KPP transform has
0096  *                      been instantiated from.
0097  * @kpp: The KPP transform instantiated from some &struct kpp_instance.
0098  * Return: The &struct kpp_instance associated with @kpp.
0099  */
0100 static inline struct kpp_instance *kpp_alg_instance(struct crypto_kpp *kpp)
0101 {
0102     return kpp_instance(crypto_tfm_alg_instance(&kpp->base));
0103 }
0104
0105 /**
0106  * kpp_instance_ctx() - Get a pointer to a &struct kpp_instance's implementation
0107  *                      specific context data.
0108  * @inst: The &struct kpp_instance whose context data to access.
0109  *
0110  * A KPP template implementation may allocate extra memory beyond the
0111  * end of a &struct kpp_instance instantiated from &crypto_template.create().
0112  * This function provides a means to obtain a pointer to this area.
0113  *
0114  * Return: A pointer to the implementation specific context data.
0115  */
0116 static inline void *kpp_instance_ctx(struct kpp_instance *inst)
0117 {
0118     return crypto_instance_ctx(kpp_crypto_instance(inst));
0119 }
0120
0121 /*
0122  * KPP algorithm (un)registration functions.
0123  */
0124 /**
0125  * crypto_register_kpp() -- Register key-agreement protocol primitives algorithm
0126  *
0127  * Function registers an implementation of a key-agreement protocol primitive
0128  * algorithm
0129  *
0130  * @alg:    algorithm definition
0131  *
0132  * Return: zero on success; error code in case of error
0133  */
0134 int crypto_register_kpp(struct kpp_alg *alg);
0135
0136 /**
0137  * crypto_unregister_kpp() -- Unregister key-agreement protocol primitive
0138  * algorithm
0139  *
0140  * Function unregisters an implementation of a key-agreement protocol primitive
0141  * algorithm
0142  *
0143  * @alg:    algorithm definition
0144  */
0145 void crypto_unregister_kpp(struct kpp_alg *alg);
0146
0147 /**
0148  * kpp_register_instance() - Register a KPP template instance.
0149  * @tmpl: The instantiating template.
0150  * @inst: The KPP template instance to be registered.
0151  * Return: %0 on success, negative error code otherwise.
0152  */
0153 int kpp_register_instance(struct crypto_template *tmpl,
0154               struct kpp_instance *inst);
0155
0156 /*
0157  * KPP spawn related functions.
0158  */
0159 /**
0160  * crypto_grab_kpp() - Look up a KPP algorithm and bind a spawn to it.
0161  * @spawn: The KPP spawn to bind.
0162  * @inst: The template instance owning @spawn.
0163  * @name: The KPP algorithm name to look up.
0164  * @type: The type bitset to pass on to the lookup.
0165  * @mask: The mask bismask to pass on to the lookup.
0166  * Return: %0 on success, a negative error code otherwise.
0167  */
0168 int crypto_grab_kpp(struct crypto_kpp_spawn *spawn,
0169             struct crypto_instance *inst,
0170             const char *name, u32 type, u32 mask);
0171
0172 /**
0173  * crypto_drop_kpp() - Release a spawn previously bound via crypto_grab_kpp().
0174  * @spawn: The spawn to release.
0175  */
0176 static inline void crypto_drop_kpp(struct crypto_kpp_spawn *spawn)
0177 {
0178     crypto_drop_spawn(&spawn->base);
0179 }
0180
0181 /**
0182  * crypto_spawn_kpp_alg() - Get the algorithm a KPP spawn has been bound to.
0183  * @spawn: The spawn to get the referenced &struct kpp_alg for.
0184  *
0185  * This function as well as the returned result are safe to use only
0186  * after @spawn has been successfully bound via crypto_grab_kpp() and
0187  * up to until the template instance owning @spawn has either been
0188  * registered successfully or the spawn has been released again via
0189  * crypto_drop_spawn().
0190  *
0191  * Return: A pointer to the &struct kpp_alg referenced from the spawn.
0192  */
0193 static inline struct kpp_alg *crypto_spawn_kpp_alg(
0194     struct crypto_kpp_spawn *spawn)
0195 {
0196     return container_of(spawn->base.alg, struct kpp_alg, base);
0197 }
0198
0199 /**
0200  * crypto_spawn_kpp() - Create a transform from a KPP spawn.
0201  * @spawn: The spawn previously bound to some &struct kpp_alg via
0202  *         crypto_grab_kpp().
0203  *
0204  * Once a &struct crypto_kpp_spawn has been successfully bound to a
0205  * &struct kpp_alg via crypto_grab_kpp(), transforms for the latter
0206  * may get instantiated from the former by means of this function.
0207  *
0208  * Return: A pointer to the freshly created KPP transform on success
0209  * or an ``ERR_PTR()`` otherwise.
0210  */
0211 static inline struct crypto_kpp *crypto_spawn_kpp(
0212     struct crypto_kpp_spawn *spawn)
0213 {
0214     return crypto_spawn_tfm2(&spawn->base);
0215 }
0216
0217 #endif