src/transform_helpers.h - master - githubmirror/xmlsec

src/transform_helpers.h
269 строк12 KB
lsh123
Refactor KeyAgreement processing to cache key lookup results when signing / encrypting data (#1145)
22 апр 2026, 20:01
22 апр 2026, 20:016e931bd
/**
 * XML Security Library (http://www.aleksey.com/xmlsec).
 *
 * This is free software; see the Copyright file in the source distribution for precise wording.
 *
 * Copyright (C) 2002-2026 Aleksey Sanin <aleksey@aleksey.com>. All Rights Reserved.
 */
/**
 * @brief Internal helper functions for transform implementations.
 */
#ifndef __XMLSEC_TRANSFORMS_HELPERS_H__
#define __XMLSEC_TRANSFORMS_HELPERS_H__


#ifndef XMLSEC_PRIVATE
#error "transform_helpers.h file contains private xmlsec definitions and should not be used outside xmlsec or xmlsec-$crypto libraries"
#endif /* XMLSEC_PRIVATE */

#include <xmlsec/xmlsec.h>
#include <xmlsec/buffer.h>
#include <xmlsec/keyinfo.h>
#include <xmlsec/transforms.h>

#include "keysdata_helpers.h"

/* Internal helpers used by key-agreement and KEM code: read / write key info inside transforms */
XMLSEC_EXPORT xmlSecKeyPtr  xmlSecTransformReadKeyInfoNode       (xmlSecKeyDataType keyType,
                                                                  xmlNodePtr node,
                                                                  xmlSecTransformPtr transform,
                                                                  xmlSecTransformCtxPtr transformCtx);
XMLSEC_EXPORT int           xmlSecTransformWriteKeyInfoNode      (xmlSecKeyPtr key,
                                                                  xmlNodePtr node,
                                                                  xmlSecTransformPtr transform,
                                                                  xmlSecTransformCtxPtr transformCtx);


/******************************************************************************
 *
 * Key Agreement Method (KAM) Transform:
 * - The transform parameters (eg kdf transform) are stored in the
 * xmlSecTransformKAM structure.
 * - Keys (originator and recipient) are stored in the xmlSecKeyDataKAM
 * structure which is attached to the derived-key object and passed around
 * to avoid (potentially expensive) re-lookup of the keys.
 *
  *****************************************************************************/
/**
 * @brief Key Agreement transform parameters.
 *
 * Contains the parsed key agreement parameters (excluding the originator / recipient
 * keys which are cached in the xmlSecKeyDataKAM structure). These are populated
 * during NodeRead and used during Execute and NodeWrite.
 */
struct _xmlSecTransformKAM {
    xmlSecTransformPtr      kdfTransform;     /**< Key Derivation Function transform */
    xmlSecKeyInfoCtx        kdfKeyInfoCtx;    /**< Context for KDF key info */
    xmlSecTransformPtr      memBufTransform;  /**< Memory buffer to collect KDF output */
};
typedef struct _xmlSecTransformKAM                          xmlSecTransformKAM,
                                                            *xmlSecTransformKAMPtr;

XMLSEC_EXPORT int   xmlSecTransformKAMInitialize            (xmlSecTransformKAMPtr params);
XMLSEC_EXPORT void  xmlSecTransformKAMFinalize              (xmlSecTransformKAMPtr params);
XMLSEC_EXPORT int   xmlSecTransformKAMRead                  (xmlSecTransformKAMPtr params,
                                                             xmlNodePtr node,
                                                             xmlSecTransformPtr kamTransform,
                                                             xmlSecTransformCtxPtr transformCtx);
XMLSEC_EXPORT int   xmlSecTransformKAMWrite                 (xmlSecTransformKAMPtr params,
                                                             xmlNodePtr node,
                                                             xmlSecTransformPtr kamTransform,
                                                             xmlSecTransformCtxPtr transformCtx);


XMLSEC_EXPORT int   xmlSecTransformKAMExecuteKdf            (xmlSecTransformKAMPtr params,
                                                             xmlSecTransformOperation operation,
                                                             xmlSecBufferPtr secret,
                                                             xmlSecBufferPtr out,
                                                             xmlSecSize expectedOutputSize,
                                                             xmlSecTransformCtxPtr transformCtx);



#ifndef XMLSEC_NO_MLKEM
/******************************************************************************
 *
 * Key Encapsulation Method (KEM) Transform: the tranform doesn't have any
 * additional parameters except the data in the xmlSecKeyDataKEM structure
 * (which is attached to the derived-key object and passed around
 * to avoid (potentially expensive) re-lookup of the keys).
 *
  *****************************************************************************/

XMLSEC_EXPORT int  xmlSecTransformKEMRead                   (xmlNodePtr node,
                                                             xmlSecTransformPtr kemTransform,
                                                             xmlSecTransformCtxPtr transformCtx);
XMLSEC_EXPORT int  xmlSecTransformKEMWrite                  (xmlNodePtr node,
                                                             xmlSecTransformPtr kemTransform,
                                                             xmlSecTransformCtxPtr transformCtx);

#endif /* !defined(XMLSEC_NO_MLKEM) */


/* ConcatKDF */
#ifndef XMLSEC_NO_CONCATKDF

struct _xmlSecTransformConcatKdfParams {
    xmlChar* digestMethod;
    xmlSecBuffer bufAlgorithmID;
    xmlSecBuffer bufPartyUInfo;
    xmlSecBuffer bufPartyVInfo;
    xmlSecBuffer bufSuppPubInfo;
    xmlSecBuffer bufSuppPrivInfo;
};
typedef struct _xmlSecTransformConcatKdfParams   xmlSecTransformConcatKdfParams, *xmlSecTransformConcatKdfParamsPtr;

XMLSEC_EXPORT int   xmlSecTransformConcatKdfParamsInitialize    (xmlSecTransformConcatKdfParamsPtr params);
XMLSEC_EXPORT void  xmlSecTransformConcatKdfParamsFinalize      (xmlSecTransformConcatKdfParamsPtr params);
XMLSEC_EXPORT int   xmlSecTransformConcatKdfParamsRead          (xmlSecTransformConcatKdfParamsPtr params,
                                                                 xmlNodePtr node);
XMLSEC_EXPORT int   xmlSecTransformConcatKdfParamsGetFixedInfo  (xmlSecTransformConcatKdfParamsPtr params,
                                                                 xmlSecBufferPtr bufFixedInfo);

#endif /* XMLSEC_NO_CONCATKDF */


/* HMAC */
#ifndef XMLSEC_NO_HMAC

/* max HMAC output size in bytes */
#define XMLSEC_TRANSFORM_HMAC_MAX_OUTPUT_SIZE       128U

#define XMLSEC_TRANSFORM_HMAC_BITS_TO_BYTES(bits)   (((bits) + 7) / 8)

XMLSEC_EXPORT int xmlSecTransformHmacReadOutputBitsSize (xmlNodePtr node,
                                                         xmlSecSize defaultSize,
                                                         xmlSecSize* res);
XMLSEC_EXPORT int xmlSecTransformHmacWriteOutput        (const xmlSecByte * hmac,
                                                         xmlSecSize hmacSizeInBits,
                                                         xmlSecSize hmacMaxSizeInBytes,
                                                         xmlSecBufferPtr out);
XMLSEC_EXPORT int xmlSecTransformHmacVerify             (const xmlSecByte* data,
                                                         xmlSecSize dataSize,
                                                         const xmlSecByte * hmac,
                                                         xmlSecSize hmacSizeInBits,
                                                         xmlSecSize hmacMaxSizeInBytes);

#endif /* XMLSEC_NO_HMAC */

/* ML-DSA */
#ifndef XMLSEC_NO_MLDSA

#define XMLSEC_MLDSA_MAX_SIZE   ((xmlSecSize)255)

XMLSEC_EXPORT int xmlSecTransformMLDSAReadContextString(xmlNodePtr node,
                                                        xmlSecBufferPtr res);
#endif /* XMLSEC_NO_MLDSA */


/* SLH-DSA */
#ifndef XMLSEC_NO_SLHDSA

#define XMLSEC_SLHDSA_MAX_SIZE  ((xmlSecSize)255)

XMLSEC_EXPORT int xmlSecTransformSLHDSAReadContextString(xmlNodePtr node,
                                                        xmlSecBufferPtr res);
#endif /* XMLSEC_NO_SLHDSA */


/* EdDSA */
#ifndef XMLSEC_NO_EDDSA

#define XMLSEC_EDDSA_MAX_SIZE   ((xmlSecSize)255)

XMLSEC_EXPORT int xmlSecTransformEdDSAReadContextString(xmlNodePtr node,
                                                        xmlSecBufferPtr res);
#endif /* XMLSEC_NO_EDDSA */


/* PBKDF2 */
#ifndef XMLSEC_NO_PBKDF2

struct _xmlSecTransformPbkdf2Params {
    xmlSecBuffer salt;
    xmlSecSize iterationCount;
    xmlSecSize keyLength;
    xmlChar* prfAlgorithmHref;
};
typedef struct _xmlSecTransformPbkdf2Params   xmlSecTransformPbkdf2Params, *xmlSecTransformPbkdf2ParamsPtr;

XMLSEC_EXPORT int   xmlSecTransformPbkdf2ParamsInitialize    (xmlSecTransformPbkdf2ParamsPtr params);
XMLSEC_EXPORT void  xmlSecTransformPbkdf2ParamsFinalize      (xmlSecTransformPbkdf2ParamsPtr params);
XMLSEC_EXPORT int   xmlSecTransformPbkdf2ParamsRead          (xmlSecTransformPbkdf2ParamsPtr params,
                                                              xmlNodePtr node);

#endif /* XMLSEC_NO_PBKDF2 */


/* HKDF */
#ifndef XMLSEC_NO_HKDF

struct _xmlSecTransformHkdfParams {
    xmlChar*        prfAlgorithmHref;
    xmlSecBuffer    salt;
    xmlSecBuffer    info;
    xmlSecSize      keyLength;
};
typedef struct _xmlSecTransformHkdfParams   xmlSecTransformHkdfParams, *xmlSecTransformHkdfParamsPtr;

XMLSEC_EXPORT int   xmlSecTransformHkdfParamsInitialize (xmlSecTransformHkdfParamsPtr params);
XMLSEC_EXPORT void  xmlSecTransformHkdfParamsFinalize   (xmlSecTransformHkdfParamsPtr params);
XMLSEC_EXPORT int   xmlSecTransformHkdfParamsRead       (xmlSecTransformHkdfParamsPtr params,
                                                         xmlNodePtr node);

#endif /* XMLSEC_NO_HKDF */


/* ChaCha20 */
#ifndef XMLSEC_NO_CHACHA20

#define XMLSEC_CHACHA20_NONCE_SIZE          ((xmlSecSize)12)
#define XMLSEC_CHACHA20_COUNTER_SIZE        ((xmlSecSize)4)
#define XMLSEC_CHACHA20_IV_SIZE             (XMLSEC_CHACHA20_NONCE_SIZE + XMLSEC_CHACHA20_COUNTER_SIZE)
#define XMLSEC_CHACHA20_KEY_SIZE            ((xmlSecSize)32)
#define XMLSEC_CHACHA20_POLY1305_TAG_SIZE   ((xmlSecSize)16)


XMLSEC_EXPORT int   xmlSecTransformChaCha20ParamsRead               (xmlNodePtr node,
                                                                     xmlSecByte *iv,
                                                                     xmlSecSize ivSize,
                                                                     xmlSecSize *ivSizeOut,
                                                                     int *noncePresent);

XMLSEC_EXPORT int   xmlSecTransformChaCha20ParamsWrite              (xmlNodePtr node,
                                                                     const xmlSecByte *iv,
                                                                     xmlSecSize ivSize);

XMLSEC_EXPORT int   xmlSecTransformChaCha20Poly1305ParamsRead       (xmlNodePtr node,
                                                                     xmlSecBufferPtr aad,
                                                                     xmlSecByte *iv,
                                                                     xmlSecSize ivSize,
                                                                     xmlSecSize *ivSizeOut,
                                                                     int *noncePresent);

XMLSEC_EXPORT int   xmlSecTransformChaCha20Poly1305ParamsWrite      (xmlNodePtr node,
                                                                     const xmlSecByte *iv,
                                                                     xmlSecSize ivSize);
#endif /* XMLSEC_NO_CHACHA20 */


/* RSA */
#ifndef XMLSEC_NO_RSA

/* All OAEP params in one place */
struct _xmlSecTransformRsaOaepParams {
    xmlSecBuffer oaepParams;
    xmlChar *    digestAlgorithm;
    xmlChar *    mgf1DigestAlgorithm;
};
typedef struct _xmlSecTransformRsaOaepParams            xmlSecTransformRsaOaepParams,
                                                        *xmlSecTransformRsaOaepParamsPtr;

XMLSEC_EXPORT int  xmlSecTransformRsaOaepParamsInitialize   (xmlSecTransformRsaOaepParamsPtr oaepParams);
XMLSEC_EXPORT void xmlSecTransformRsaOaepParamsFinalize     (xmlSecTransformRsaOaepParamsPtr oaepParams);
XMLSEC_EXPORT int  xmlSecTransformRsaOaepParamsRead         (xmlSecTransformRsaOaepParamsPtr oaepParams,
                                                             xmlNodePtr node);

#endif /* XMLSEC_NO_RSA */

#endif /* __XMLSEC_TRANSFORMS_HELPERS_H__ */