ERUCES::TEDelegatedAuthenticationContext
#include <teauthdelegatedctx.h>
The TEDelegatedAuthenticationContext class authenticates a delegated (impersonated) session through the Key Service's DelegatedAuthentication module (AM04).
AM04 AUTHENTICATES THE DELEGATOR, NOT THE TARGET. The delegator is the TLS client certificate the connection presents, so this context carries that certificate and its private key (setPKCS12 / setCredential) and must be opened on a TEConnection::SSLMutualConnection – the one connection type that presents a client certificate. The Key Service requires the certificate principal it loaded from that certificate to carry the DELEGATION flag, and refuses otherwise with its own authentication error, Impersonation is not allowed for principal; it further refuses unless every operation the target holds is also held by the delegator, so a delegation can never widen a privilege. The session that results acts as the TARGET: the principal id authenticate() returns, and the principal every operation is authorised as, is the target's.
THE TARGET SET IS CLOSED, AND CLOSED HERE. Exactly two kinds of principal can be impersonated, each named by its own method: a certificate principal by its DER-encoded certificate (setX509Target), and an Externally Authenticated principal (TEXAuthPrincipalInfo) by its id (setXAuthTarget). There is no method taking a selector string, and there is deliberately no way to name a native password (SRP) principal: delegation bypasses authentication, so a delegatable password identity would void the guarantee that principal type exists to provide. That exclusion is a settled security decision (ADR-0029), not an omission.
ONE TARGET PER CONTEXT. A second selector call – either method, after either method – is REFUSED with a TEException (ERR_DELEGATION_TARGET_SET), never silently honoured: the first choice is what authenticate() sends. Make a new context to name another target.
This class is derived from the TEAuthenticationContext class.
© Pi Soft, 2018-2026 · Tricryption Engine 8.1
Inheritance
- Inherits ERUCES::TEAuthenticationContext
Public Types
enum DELEGATION_TARGET
The kind of principal a context has been told to impersonate.
| Value | Description |
|---|---|
NoTarget | No selector has been called. |
X509Target | A certificate principal, named by its DER-encoded certificate (setX509Target). |
XAuthTarget | An Externally Authenticated principal, named by its id (setXAuthTarget). |
Public Member Functions
| Member | Description |
|---|---|
~TEDelegatedAuthenticationContext() | The TEDelegatedAuthenticationContext destructor is the class destructor. |
void setPKCS12(const _TESTD string &filename, const _TESTD string &password) | The setPKCS12 method loads the DELEGATOR's certificate chain and private key from a PKCS -12 file. |
void setCredential(const _TESTD string &certChain, const _TESTD string &privateKey) | The setCredential method sets the DELEGATOR's certificate chain and private key from material already in memory. |
const _TESTD string & getCertChain() const | The getCertChain method retrieves the delegator's certificate chain. |
const _TESTD string & getPrivateKey() const | The getPrivateKey method retrieves the delegator's private key. |
void setX509Target(const _TESTD string &certificateDer) | The setX509Target method names a CERTIFICATE principal as the target to impersonate. |
void setXAuthTarget(const _TESTD string &principalId) | The setXAuthTarget method names an EXTERNALLY AUTHENTICATED principal as the target to impersonate. |
DELEGATION_TARGET getTargetType() const | The getTargetType method reports which selector, if any, has been called. |
const _TESTD string getTarget() const | The getTarget method retrieves the selected target as it will be sent. |
te_oid authenticate() | The authenticate method performs the delegated authentication. |
TEObject * clone() const | The clone method clones a TEDelegatedAuthenticationContext object, credential and target included. |
Static Public Member Functions
| Member | Description |
|---|---|
_TESTD auto_ptr< TEDelegatedAuthenticationContext > getInstance() | The getInstance method creates a new TEDelegatedAuthenticationContext object. |
Member Function Documentation
~TEDelegatedAuthenticationContext()
The TEDelegatedAuthenticationContext destructor is the class destructor.
void setPKCS12(const _TESTD string &filename, const _TESTD string &password)
The setPKCS12 method loads the DELEGATOR's certificate chain and private key from a PKCS -12 file.
This is the credential AM04 authenticates. The same material a TESSLMutualAuthenticationContext loads with its setPKCS12.
Parameters
| Parameter | Description |
|---|---|
filename | A string naming the PKCS -12 file. |
password | A string holding the file's password. |
void setCredential(const _TESTD string &certChain, const _TESTD string &privateKey)
The setCredential method sets the DELEGATOR's certificate chain and private key from material already in memory.
The two strings are what TEKeyCertUtil::loadFromFile(filename, password, certificate, privatekey, false) produces: the DER-encoded chain and the DER-encoded private key, not base64.
Parameters
| Parameter | Description |
|---|---|
certChain | A string holding the DER-encoded certificate chain. |
privateKey | A string holding the DER-encoded private key. |
const _TESTD string & getCertChain() const
The getCertChain method retrieves the delegator's certificate chain.
Returns: A string holding the DER-encoded certificate chain, empty until a credential is set.
const _TESTD string & getPrivateKey() const
The getPrivateKey method retrieves the delegator's private key.
Returns: A string holding the DER-encoded private key, empty until a credential is set.
void setX509Target(const _TESTD string &certificateDer)
The setX509Target method names a CERTIFICATE principal as the target to impersonate.
Wire selector "X509"; the Key Service loads the TransportPrincipalInfo enrolled for this certificate. The certificate is the target's, not the delegator's; the delegator is the connection's own client certificate.
Parameters
| Parameter | Description |
|---|---|
certificateDer | A string holding the target's DER-encoded X.509 certificate (the bytes, not base64 and not PEM). |
Exceptions
| Exception | Description |
|---|---|
TEException | ERR_DELEGATION_TARGET_SET if a target has already been selected on this context. |
void setXAuthTarget(const _TESTD string &principalId)
The setXAuthTarget method names an EXTERNALLY AUTHENTICATED principal as the target to impersonate.
Wire selector "XAUTH"; the Key Service loads the XAuthPrincipalInfo whose id is the given name (TEXAuthPrincipalInfo::getID). An XAuth principal cannot authenticate on its own – it exists to be impersonated.
Parameters
| Parameter | Description |
|---|---|
principalId | A string holding the XAuth principal's id. |
Exceptions
| Exception | Description |
|---|---|
TEException | ERR_DELEGATION_TARGET_SET if a target has already been selected on this context. |
DELEGATION_TARGET getTargetType() const
The getTargetType method reports which selector, if any, has been called.
Returns: Returns NoTarget, X509Target or XAuthTarget.
const _TESTD string getTarget() const
The getTarget method retrieves the selected target as it will be sent.
Returns: The DER-encoded certificate (X509Target), the principal id (XAuthTarget), or an empty string (NoTarget).
te_oid authenticate()
The authenticate method performs the delegated authentication.
Refuses, before any wire I/O, with ERR_DELEGATION_NO_TARGET when no selector has been called and with ERR_DELEGATION_NO_CLIENT_CERT when the attached connection is not a TEConnection::SSLMutualConnection (nothing else presents the delegator's certificate). The Key Service's own refusals – the DELEGATION flag missing, an unknown or disabled target, a target holding an operation the delegator lacks – arrive as a TEException carrying the Key Service's message.
Returns: Returns the principal id of the TARGET, the principal the session now acts as.
TEObject * clone() const
The clone method clones a TEDelegatedAuthenticationContext object, credential and target included.
Returns: A cloned TEDelegatedAuthenticationContext object.
_TESTD auto_ptr< TEDelegatedAuthenticationContext > getInstance()
The getInstance method creates a new TEDelegatedAuthenticationContext object.
Returns: Returns a smart pointer to a TEDelegatedAuthenticationContext object.