Class: EnvelopedData

Represents the EnvelopedData structure described in RFC5652

Example

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();

Example

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,
});

Hierarchy

• PkiObject

  ↳ EnvelopedData

Implements

• IEnvelopedData

Constructors

constructor

• new EnvelopedData(parameters?): EnvelopedData

Initializes a new instance of the EnvelopedData class

Parameters

Name	Type	Description
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 className(): string

Returns

string

Inherited from

PkiObject.className

Methods

_addKeyAgreeRecipientInfo

▸ _addKeyAgreeRecipientInfo(recipientIdentifier, encryptionParameters, extraRecipientInfoParams, crypto?): void

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

Parameters

Name	Type	Description
recipientIdentifier	KeyAgreeRecipientIdentifier	Recipient identifier
encryptionParameters	EnvelopedDataEncryptionParams	Additional parameters for "fine tuning" the encryption process
extraRecipientInfoParams	KeyAgreeRecipientInfoParameters	Additional params for KeyAgreeRecipientInfo
crypto	ICryptoEngine	Crypto engine

Returns

void

---

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

Name	Type	Description
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

Name	Type	Description
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

Name	Type	Description
preDefinedData	ArrayBuffer	ArrayBuffer with pre-defined data
parameters	Object	Additional parameters necessary for "fine tunning" of encryption process
parameters.hmacHashAlgorithm?	string	-
parameters.iterationCount?	number	-
parameters.keyEncryptionAlgorithm?	AesKeyGenParams	-
parameters.keyEncryptionAlgorithmParams?	any	-
parameters.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

Name	Type	Description
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

Name	Type	Description
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

Name	Type	Description
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

Name	Type	Default value
encoding	"base64" | "base64url" | "hex"	"hex"

Returns

string

Inherited from

PkiObject.toString

---

blockName

▸ blockName(): string

Returns block name

Returns

string

Returns string block name

Inherited from

PkiObject.blockName

---

compareWithDefault

▸ compareWithDefault(memberName, memberValue): boolean

Compare values with default values for all class members

Parameters

Name	Type	Description
memberName	string	String name for a class member
memberValue	any	Value to compare with default value

Returns

boolean

---

defaultValues

▸ defaultValues(memberName): number

Returns default values for all class members

Parameters

Name	Type	Description
memberName	"version"	String name for a class member

Returns

number

Default value

Overrides

PkiObject.defaultValues

▸ defaultValues(memberName): OriginatorInfo

Parameters

Name	Type
memberName	"originatorInfo"

Returns

OriginatorInfo

Overrides

PkiObject.defaultValues

▸ defaultValues(memberName): RecipientInfo[]

Parameters

Name	Type
memberName	"recipientInfos"

Returns

RecipientInfo[]

Overrides

PkiObject.defaultValues

▸ defaultValues(memberName): EncryptedContentInfo

Parameters

Name	Type
memberName	"encryptedContentInfo"

Returns

EncryptedContentInfo

Overrides

PkiObject.defaultValues

▸ defaultValues(memberName): Attribute[]

Parameters

Name	Type
memberName	"unprotectedAttrs"

Returns

Attribute[]

Overrides

PkiObject.defaultValues

---

fromBER

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

Creates PKI object from the raw data

Type parameters

Name	Type
T	extends PkiObject

Parameters

Name	Type	Description
this	PkiObjectConstructor<T>	-
raw	BufferSource	ASN.1 encoded raw data

Returns

T

Initialized and filled current class object

Inherited from

PkiObject.fromBER

---

schema

▸ schema(parameters?): any

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

Parameters

Name	Type	Description
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