Module crypto

tds_protocol

Module crypto 

Source
Expand description

Always Encrypted cryptography metadata for TDS protocol.

This module defines the wire-level structures for SQL Server’s Always Encrypted feature. When a query returns encrypted columns, SQL Server sends additional metadata describing how to decrypt the data.

§TDS Wire Format

When Always Encrypted is enabled, the COLMETADATA token includes:

  1. CEK Table: A table of Column Encryption Keys needed for the result set
  2. CryptoMetadata: Per-column encryption information
COLMETADATA Token (with encryption):
┌─────────────────────────────────────────────────────────────────┐
│ Column Count (2 bytes)                                          │
├─────────────────────────────────────────────────────────────────┤
│ CEK Table (if encrypted columns present)                        │
│ ├── CEK Count (2 bytes)                                         │
│ ├── CEK Entry 1                                                 │
│ │   ├── Database ID (4 bytes)                                   │
│ │   ├── CEK ID (4 bytes)                                        │
│ │   ├── CEK Version (4 bytes)                                   │
│ │   ├── CEK MD Version (8 bytes)                                │
│ │   ├── CEK Value Count (1 byte)                                │
│ │   └── CEK Value(s)                                            │
│ │       ├── Encrypted Value Length (2 bytes)                    │
│ │       ├── Encrypted Value (variable)                          │
│ │       ├── Key Store Name (B_VARCHAR)                          │
│ │       ├── CMK Path (US_VARCHAR)                               │
│ │       └── Algorithm (B_VARCHAR)                               │
│ └── ...more CEK entries                                         │
├─────────────────────────────────────────────────────────────────┤
│ Column Definitions                                              │
│ ├── Column 1                                                    │
│ │   ├── User Type (4 bytes)                                     │
│ │   ├── Flags (2 bytes) - includes encryption flag              │
│ │   ├── Type ID (1 byte)                                        │
│ │   ├── Type Info (variable)                                    │
│ │   ├── CryptoMetadata (if encrypted)                           │
│ │   │   ├── CEK Table Ordinal (2 bytes)                         │
│ │   │   ├── Algorithm ID (1 byte)                               │
│ │   │   ├── Encryption Type (1 byte)                            │
│ │   │   └── Normalization Version (1 byte)                      │
│ │   └── Column Name (B_VARCHAR)                                 │
│ └── ...more columns                                             │
└─────────────────────────────────────────────────────────────────┘

Structs§

CekTable
CEK table containing all Column Encryption Keys needed for a result set.
CekTableEntry
Column Encryption Key table entry.
CekValue
A single CEK value (encrypted by CMK).
ColumnCryptoInfo
Extended column metadata with encryption information.
CryptoMetadata
Per-column encryption metadata.

Enums§

EncryptionTypeWire
Wire-level encryption type.

Constants§

ALGORITHM_AEAD_AES_256_CBC_HMAC_SHA256
Algorithm ID for AEAD_AES_256_CBC_HMAC_SHA256.
COLUMN_FLAG_ENCRYPTED
Column flags bit indicating the column is encrypted.
ENCRYPTION_TYPE_DETERMINISTIC
Encryption type: Deterministic.
ENCRYPTION_TYPE_RANDOMIZED
Encryption type: Randomized.
NORMALIZATION_RULE_VERSION
Current normalization rule version.

Functions§

is_column_encrypted
Check if a column flags value indicates encryption.