Skip to main content

EnvelopedData

Represents the EnvelopedData structure described in RFC5652

Examples​

The following example demonstrates how to create and encrypt CMS Enveloped Data

const cmsEnveloped = new pkijs.EnvelopedData();

// Add recipient
cmsEnveloped.addRecipientByCertificate(cert, { oaepHashAlgorithm: "SHA-256" });

// Secret key algorithm
const alg = {
  name: "AES-GCM",
  length: 256,
}
await cmsEnveloped.encrypt(alg, dataToEncrypt);

// Add Enveloped Data into CMS Content Info
const cmsContent = new pkijs.ContentInfo();
cmsContent.contentType = pkijs.ContentInfo.ENVELOPED_DATA;
cmsContent.content = cmsEnveloped.toSchema();

const cmsContentRaw = cmsContent.toSchema().toBER();

The following example demonstrates how to decrypt CMS Enveloped Data

// Get a "crypto" extension
const crypto = pkijs.getCrypto();

// Parse CMS Content Info
const cmsContent = pkijs.ContentInfo.fromBER(cmsContentRaw);
if (cmsContent.contentType !== pkijs.ContentInfo.ENVELOPED_DATA) {
  throw new Error("CMS is not Enveloped Data");
}
// Parse CMS Enveloped Data
const cmsEnveloped = new pkijs.EnvelopedData({ schema: cmsContent.content });

// Export private key to PKCS#8
const pkcs8 = await crypto.exportKey("pkcs8", keys.privateKey);

// Decrypt data
const decryptedData = await cmsEnveloped.decrypt(0, {
  recipientCertificate: cert,
  recipientPrivateKey: pkcs8,
});

Extends​

Implements​

Constructors​

Constructor​

new EnvelopedData(parameters?): EnvelopedData

Initializes a new instance of the EnvelopedData class

Parameters​

parameters?​

EnvelopedDataParameters = {}

Initialization parameters

Returns​

EnvelopedData

Overrides​

PkiObject.constructor

Properties​

encryptedContentInfo​

encryptedContentInfo: EncryptedContentInfo

Encrypted content information

Implementation of​

IEnvelopedData.encryptedContentInfo

originatorInfo?​

optional originatorInfo?: OriginatorInfo

Optionally provides information about the originator. It is present only if required by the key management algorithm. It may contain certificates and CRLs.

Implementation of​

IEnvelopedData.originatorInfo

policy​

policy: Required<EncryptedContentInfoSplit>

recipientInfos​

recipientInfos: RecipientInfo[]

Collection of per-recipient information. There MUST be at least one element in the collection.

Implementation of​

IEnvelopedData.recipientInfos

unprotectedAttrs?​

optional unprotectedAttrs?: Attribute[]

Collection of attributes that are not encrypted

Implementation of​

IEnvelopedData.unprotectedAttrs

version​

version: number

Version number.

The appropriate value depends on originatorInfo, RecipientInfo, and unprotectedAttrs.

The version MUST be assigned as follows:

IF (originatorInfo is present) AND
   ((any certificates with a type of other are present) OR
   (any crls with a type of other are present))
THEN version is 4
ELSE
   IF ((originatorInfo is present) AND
      (any version 2 attribute certificates are present)) OR
      (any RecipientInfo structures include pwri) OR
      (any RecipientInfo structures include ori)
   THEN version is 3
   ELSE
      IF (originatorInfo is absent) AND
         (unprotectedAttrs is absent) AND
         (all RecipientInfo structures are version 0)
      THEN version is 0
      ELSE version is 2

Implementation of​

IEnvelopedData.version

CLASS_NAME​

static CLASS_NAME: string = "EnvelopedData"

Name of the class

Overrides​

PkiObject.CLASS_NAME

Accessors​

className​

Get Signature​

get className(): string

Returns​

string

Inherited from​

PkiObject.className

Methods​

addRecipientByCertificate()​

addRecipientByCertificate(certificate, parameters?, variant?, crypto?): boolean

Helpers function for filling "RecipientInfo" based on recipient's certificate. Problem with WebCrypto is that for RSA certificates we have only one option - "key transport" and for ECC certificates we also have one option - "key agreement". As soon as Google will implement DH algorithm it would be possible to use "key agreement" also for RSA certificates.

Parameters​

certificate​

Certificate

Recipient's certificate

parameters?​

object

Additional parameters necessary for "fine tunning" of encryption process

variant?​

number

Variant = 1 is for "key transport", variant = 2 is for "key agreement". In fact the "variant" is unnecessary now because Google has no DH algorithm implementation. Thus key encryption scheme would be choosen by certificate type only: "key transport" for RSA and "key agreement" for ECC certificates.

crypto?​

ICryptoEngine = ...

Crypto engine

Returns​

boolean

addRecipientByKeyIdentifier()​

addRecipientByKeyIdentifier(key?, keyId?, parameters?, crypto?): void

Add a "RecipientInfo" using a KeyAgreeRecipientInfo of type RecipientKeyIdentifier.

Parameters​

key?​

CryptoKey

Recipient's public key

keyId?​

ArrayBuffer

The id for the recipient's public key

parameters?​

any

Additional parameters for "fine tuning" the encryption process

crypto?​

ICryptoEngine = ...

Crypto engine

Returns​

void

addRecipientByPreDefinedData()​

addRecipientByPreDefinedData(preDefinedData, parameters?, variant, crypto?): void

Add recipient based on pre-defined data like password or KEK

Parameters​

preDefinedData​

ArrayBuffer

ArrayBuffer with pre-defined data

parameters?​

Additional parameters necessary for "fine tunning" of encryption process

hmacHashAlgorithm?​

string

iterationCount?​

number

keyEncryptionAlgorithm?​

AesKeyGenParams

keyEncryptionAlgorithmParams?​

any

keyIdentifier?​

ArrayBuffer

variant​

number

Variant = 1 for pre-defined "key encryption key" (KEK). Variant = 2 for password-based encryption.

crypto?​

ICryptoEngine = ...

Crypto engine

Returns​

void

decrypt()​

decrypt(recipientIndex, parameters, crypto?): Promise<ArrayBuffer>

Decrypts existing CMS Enveloped Data content

Parameters​

recipientIndex​

number

Index of recipient

parameters​

EnvelopedDataDecryptParams

Additional parameters

crypto?​

ICryptoEngine = ...

Crypto engine

Returns​

Promise<ArrayBuffer>

encrypt()​

encrypt(contentEncryptionAlgorithm, contentToEncrypt, crypto?): Promise<(void | { ecdhPrivateKey: CryptoKey; })[]>

Creates a new CMS Enveloped Data content with encrypted data

Parameters​

contentEncryptionAlgorithm​

Algorithm

WebCrypto algorithm. For the moment here could be only "AES-CBC" or "AES-GCM" algorithms.

contentToEncrypt​

ArrayBuffer

Content to encrypt

crypto?​

ICryptoEngine = ...

Crypto engine

Returns​

Promise<(void | { ecdhPrivateKey: CryptoKey; })[]>

fromSchema()​

fromSchema(schema): void

Converts parsed ASN.1 object into current class

Parameters​

schema​

any

ASN.1 schema

Returns​

void

Overrides​

PkiObject.fromSchema

toJSON()​

toJSON(): EnvelopedDataJson

Converts the class to JSON object

Returns​

EnvelopedDataJson

JSON object

Overrides​

PkiObject.toJSON

toSchema()​

toSchema(): Sequence

Converts current object to ASN.1 object and sets correct values

Returns​

Sequence

ASN.1 object

Overrides​

PkiObject.toSchema

toString()​

toString(encoding?): string

Parameters​

encoding?​

"hex" | "base64" | "base64url"

Returns​

string

Inherited from​

PkiObject.toString

blockName()​

static blockName(): string

Returns block name

Returns​

string

Returns string block name

Inherited from​

PkiObject.blockName

compareWithDefault()​

static compareWithDefault(memberName, memberValue): boolean

Compare values with default values for all class members

Parameters​

memberName​

string

String name for a class member

memberValue​

any

Value to compare with default value

Returns​

boolean

defaultValues()​

Call Signature​

static defaultValues(memberName): number

Returns default values for all class members

Parameters​
memberName​

"version"

String name for a class member

Returns​

number

Default value

Overrides​

PkiObject.defaultValues

Call Signature​

static defaultValues(memberName): OriginatorInfo

Returns default values for all class members

Parameters​
memberName​

"originatorInfo"

String name for a class member

Returns​

OriginatorInfo

Default value

Overrides​

PkiObject.defaultValues

Call Signature​

static defaultValues(memberName): RecipientInfo[]

Returns default values for all class members

Parameters​
memberName​

"recipientInfos"

String name for a class member

Returns​

RecipientInfo[]

Default value

Overrides​

PkiObject.defaultValues

Call Signature​

static defaultValues(memberName): EncryptedContentInfo

Returns default values for all class members

Parameters​
memberName​

"encryptedContentInfo"

String name for a class member

Returns​

EncryptedContentInfo

Default value

Overrides​

PkiObject.defaultValues

Call Signature​

static defaultValues(memberName): Attribute[]

Returns default values for all class members

Parameters​
memberName​

"unprotectedAttrs"

String name for a class member

Returns​

Attribute[]

Default value

Overrides​

PkiObject.defaultValues

fromBER()​

static fromBER<T>(this, raw): T

Creates PKI object from the raw data

Type Parameters​

T​

T extends PkiObject

Parameters​

this​

PkiObjectConstructor<T>

raw​

BufferSource

ASN.1 encoded raw data

Returns​

T

Initialized and filled current class object

Inherited from​

PkiObject.fromBER

schema()​

static schema(parameters?): any

Returns value of pre-defined ASN.1 schema for current class

Parameters​

parameters?​

SchemaParameters<{ encryptedContentInfo?: EncryptedContentInfoSchema; originatorInfo?: string; recipientInfos?: string; unprotectedAttrs?: string; version?: string; }> = {}

Input parameters for the schema

Returns​

any

ASN.1 schema object

Overrides​

PkiObject.schema