Table of Contents

Class EncryptedFieldBinding

Namespace
Excalibur.Compliance
Assembly
Excalibur.Compliance.Abstractions.dll

The single owner of non-subject field selection — what EncryptedFieldAttribute and SensitiveAttribute select — and of how an annotated property value crosses between its declared type and the raw bytes an encryptor consumes.

public static class EncryptedFieldBinding
Inheritance
EncryptedFieldBinding
Inherited Members

Remarks

It is not the only selection authority in the framework, and reading it as one has produced a wrong conclusion. Subject-keyed encryption selects PersonalDataAttribute properties separately, because those are bound to a per-subject key that erasure destroys. This type owns the paths where the key is not derived from a data subject; the two authorities are disjoint by annotation and must stay so.

Every field-level encryption path routes property selection and value access through this type. The selection predicate previously existed as three byte-identical copies that each filtered PropertyType == typeof(byte[]), so an annotation on a string property was dropped silently and its value persisted as plaintext. Concentrating both halves here means a path cannot honour a different set of properties than its siblings, and cannot reintroduce a silent skip.

A byte[] property holds the envelope verbatim, identified by MagicBytes. A string property holds StringEnvelopePrefix followed by the Base64 of the same envelope, and is identified by that literal prefix alone, never by decoding. Decoding is not a sound test: an ordinary string can Base64-decode to bytes beginning with the magic, and a decode-first test then reads that plaintext as already-encrypted and stores it in the clear. The prefix ends in a colon, which is outside the Base64 alphabet, so no encoder output can accidentally wear it.

Fields

MaxEncodedEnvelopeLength

The largest encoded envelope, in characters, that a string property is decoded from.

public const int MaxEncodedEnvelopeLength = 1048576

Field Value

int

Remarks

Decoding is what a hostile length costs, so the length is checked before the buffer is allocated rather than after. A stored value is consumer-writable, and the decode path allocates the encoded text, the decode buffer, and then the JSON reader's own view of the result, so an unbounded value multiplies into large-object-heap pressure several times over. A field-level ciphertext does not legitimately approach this size.

StringEnvelopePrefix

The marker that begins a string property encrypted value. Versioned, so a later envelope format can be told apart from this one rather than guessed at.

public const string StringEnvelopePrefix = "EXCR1:"

Field Value

string

SupportedTypeNames

The property types that can carry an encrypted value, named once.

public const string SupportedTypeNames = "string, byte[]"

Field Value

string

Methods

Inspect(Type, out IReadOnlyList<string>)

Selects the annotated properties that CAN be honoured, and reports the ones that cannot, without throwing.

public static PropertyInfo[] Inspect(Type type, out IReadOnlyList<string> unhonourable)

Parameters

type Type

The annotated type.

unhonourable IReadOnlyList<string>

One message per annotated property that cannot be encrypted, explaining why. Empty when every annotation on the type can be honoured.

Returns

PropertyInfo[]

The annotated properties that can be encrypted, in declaration order.

Remarks

This is the question a caller asks when it is REPORTING on a type rather than encrypting it — an estimate, a diagnostic, an inventory. Such a caller wants the count it can honour plus the reasons for the rest; refusing outright would deny it the answer it exists to produce, and a type carrying one good annotation and one bad one would estimate as zero fields rather than one field and a warning. A caller that is about to ENCRYPT asks Select(Type), which refuses, because proceeding there would silently leave a field unprotected.

IsMarkedEncrypted(PropertyInfo, object)

Gets a value indicating whether an annotated property value is marked as encrypted, without validating that the envelope is readable.

public static bool IsMarkedEncrypted(PropertyInfo property, object instance)

Parameters

property PropertyInfo

The annotated property.

instance object

The instance carrying the value.

Returns

bool

true when the value carries the encrypted marker.

Remarks

This is the question a writer asks, and it is deliberately not TryReadEnvelope(PropertyInfo, object, out byte[]?). A writer only needs to know whether encrypting again would double-wrap a value; it has no use for the envelope contents, and it must not refuse to store a record because the value already in the field is damaged. Validating here would make a row whose stored ciphertext was truncated permanently unwritable — and truncation is a write-side cause, since Base64 inflates by four thirds and StringEnvelopePrefix adds six characters, so a column sized for the plaintext is exactly where it happens. A reader, which cannot return a value it failed to decrypt, asks TryReadEnvelope(PropertyInfo, object, out byte[]?) instead.

IsSupported(Type)

Gets a value indicating whether propertyType can carry an encrypted value.

public static bool IsSupported(Type propertyType)

Parameters

propertyType Type

The declared type of the annotated property.

Returns

bool

true when the type is supported.

ReadPlaintext(PropertyInfo, object)

Reads an annotated property plaintext as the bytes an encryptor consumes.

public static byte[]? ReadPlaintext(PropertyInfo property, object instance)

Parameters

property PropertyInfo

The annotated property.

instance object

The instance carrying the value.

Returns

byte[]

The plaintext bytes, or null when the property is empty.

Select(Type)

Selects the EncryptedFieldAttribute-annotated properties of T, rejecting any annotation that cannot be honoured instead of skipping it.

public static PropertyInfo[] Select(Type type)

Parameters

type Type

The annotated type.

Returns

PropertyInfo[]

The annotated properties, in declaration order.

Exceptions

EncryptionException

An annotated property is of an unsupported type, or is missing a getter or a setter. Such an annotation has never encrypted anything, so rejecting it withdraws no working behaviour: it discloses, at construction time, protection the caller did not have.

Select<T>()

Selects the EncryptedFieldAttribute-annotated properties of T, rejecting any annotation that cannot be honoured instead of skipping it.

public static PropertyInfo[] Select<T>()

Returns

PropertyInfo[]

The annotated properties, in declaration order.

Type Parameters

T

The annotated type.

Exceptions

EncryptionException

An annotated property is of an unsupported type, or is missing a getter or a setter. Such an annotation has never encrypted anything, so rejecting it withdraws no working behaviour: it discloses, at construction time, protection the caller did not have.

TryReadEnvelope(PropertyInfo, object, out byte[]?)

Determines whether an annotated property currently holds an encrypted envelope, and if so yields its raw bytes.

public static bool TryReadEnvelope(PropertyInfo property, object instance, out byte[]? envelope)

Parameters

property PropertyInfo

The annotated property.

instance object

The instance carrying the value.

envelope byte[]

The envelope bytes when the method returns true.

Returns

bool

true when the property holds an envelope. false when it is empty or holds plaintext.

Exceptions

EncryptionException

The value is marked as an envelope but is not one: a string carrying StringEnvelopePrefix whose remainder does not decode, which is how a truncated or corrupted ciphertext presents. This is thrown rather than reported as "not an envelope", because answering false would let a decrypting caller treat ciphertext as plaintext and hand it back as though it had been decrypted.

WriteEnvelope(PropertyInfo, object, byte[])

Writes a framed envelope in the declared representation of the property.

public static void WriteEnvelope(PropertyInfo property, object instance, byte[] framed)

Parameters

property PropertyInfo

The annotated property.

instance object

The instance carrying the value.

framed byte[]

The framed envelope bytes.

WritePlaintext(PropertyInfo, object, byte[]?)

Writes decrypted plaintext back in the declared representation of the property.

public static void WritePlaintext(PropertyInfo property, object instance, byte[]? plaintext)

Parameters

property PropertyInfo

The annotated property.

instance object

The instance carrying the value.

plaintext byte[]

The decrypted bytes, or null to clear the property.