EnvelopedData

Represents the EnvelopedData structure described in RFC5652

Examples

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

// 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

• PkiObject

Implements

• IEnvelopedData

Constructors

new EnvelopedData()

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 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?

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

• 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

• recipientIndex: number

Index of recipient

• parameters: EnvelopedDataDecryptParams

Additional parameters

• crypto: ICryptoEngine = ...

Crypto engine

Returns

Promise<ArrayBuffer>

---

encrypt()

encrypt(contentEncryptionAlgorithm, contentToEncrypt, crypto): Promise<(void | object)[]>

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 | object)[]>

---

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: "base64" | "base64url" | "hex" = "hex"

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

defaultValues(memberName)

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

defaultValues(memberName)

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

defaultValues(memberName)

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

defaultValues(memberName)

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

defaultValues(memberName)

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 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<object> = {}

Input parameters for the schema

Returns

any

ASN.1 schema object

Overrides

PkiObject.schema