# Pkcs7Signer

## Content

# Class: Pkcs7Signer

The implementation of [Pkcs7SignerBase](Pkcs7SignerBase), generates a detached PKCS#7 signature using:
- a private key provided in PEM format
- a corresponding certificate chain in PEM format

The first certificate in the chain must be the end-entity (signing) certificate,
followed by any intermediate certificates required to build a trust chain.

The private key is used to produce the signature value, while the certificate
chain is embedded into the resulting signature container.

## Remarks

This class provides a built-in signing implementation. For custom signing
scenarios (e.g., remote signing with external services such as HSM or cloud
key providers), extend [Pkcs7SignerBase](Pkcs7SignerBase).

## Extends

- [`Pkcs7SignerBase`](Pkcs7SignerBase)

## Constructors

### Constructor

```ts
new Pkcs7Signer(): Pkcs7Signer;
```

Creates a new [Pkcs7SignerBase](Pkcs7SignerBase).

#### Returns

`Pkcs7Signer`

#### Inherited from

[`Pkcs7SignerBase`](Pkcs7SignerBase).[`constructor`](Pkcs7SignerBase#constructor)

## Accessors

### certificateChainPem

#### Get Signature

```ts
get certificateChainPem(): string[];
```

Gets the certificate chain to embed into the PKCS#7 (CMS) signature.

The chain may contain only the signer's (end-entity) certificate or a
full chain including intermediate CA certificates and the root CA
certificate.

Providing more certificates increases the likelihood that verifiers can
successfully build and validate the trust chain without fetching missing
certificates from external sources.

##### Remarks

When multiple certificates are provided, they should be ordered from the
end-entity (signer) certificate up to the root CA certificate.

##### Returns

`string`[]

#### Set Signature

```ts
set certificateChainPem(value): void;
```

Sets the certificate chain to embed into the PKCS#7 (CMS) signature.

The chain may contain only the signer's (end-entity) certificate or a
full chain including intermediate CA certificates and the root CA
certificate.

Providing more certificates increases the likelihood that verifiers can
successfully build and validate the trust chain without fetching missing
certificates from external sources.

##### Remarks

When multiple certificates are provided, they should be ordered from the
end-entity (signer) certificate up to the root CA certificate.

##### Parameters

###### value

`string`[]

##### Returns

`void`

***

### contactInfo

#### Get Signature

```ts
get contactInfo(): string;
```

Gets the information provided by the signer to enable a recipient to contact the signer
to verify the signature (for example, a phone number).

##### Returns

`string`

#### Set Signature

```ts
set contactInfo(value): void;
```

Sets the information provided by the signer to enable a recipient to contact the signer
to verify the signature (for example, a phone number).

##### Parameters

###### value

`string`

##### Returns

`void`

#### Inherited from

[`Pkcs7SignerBase`](Pkcs7SignerBase).[`contactInfo`](Pkcs7SignerBase#contactinfo)

***

### crls

#### Get Signature

```ts
get crls(): (string | ArrayBuffer)[];
```

Gets the collection of certificate revocation lists (CRLs) to use.
Items in this collection may be of the following types:
<b>ArrayBuffer</b> An encoded CRL list.
<b>string</b> The URL of a CRL (e.g. http://crl.cacert.org/revoke.crl).

##### Returns

(`string` \| `ArrayBuffer`)[]

#### Set Signature

```ts
set crls(value): void;
```

Sets the collection of certificate revocation lists (CRLs) to use.
Items in this collection may be of the following types:
<b>ArrayBuffer</b> An encoded CRL list.
<b>string</b> The URL of a CRL (e.g. http://crl.cacert.org/revoke.crl).

##### Parameters

###### value

(`string` \| `ArrayBuffer`)[]

##### Returns

`void`

#### Inherited from

[`Pkcs7SignerBase`](Pkcs7SignerBase).[`crls`](Pkcs7SignerBase#crls)

***

### documentAccessPermissions

#### Get Signature

```ts
get documentAccessPermissions(): AccessPermissions;
```

Gets the information provided by the signer to enable a recipient to contact the signer
to verify the signature (for example, a phone number).

##### Returns

[`AccessPermissions`](../enumerations/AccessPermissions)

#### Set Signature

```ts
set documentAccessPermissions(value): void;
```

Sets the information provided by the signer to enable a recipient to contact the signer
to verify the signature (for example, a phone number).

##### Parameters

###### value

[`AccessPermissions`](../enumerations/AccessPermissions)

##### Returns

`void`

#### Inherited from

[`Pkcs7SignerBase`](Pkcs7SignerBase).[`documentAccessPermissions`](Pkcs7SignerBase#documentaccesspermissions)

***

### externalResourcesOptions

#### Get Signature

```ts
get externalResourcesOptions(): ExternalResourcesOptions;
```

Gets configuration options used to retrieve external X.509-related resources.

These options control how resources such as CRLs, OCSP responses, and TSA data
are resolved and fetched, including URL rewriting, custom network handling,
and request lifecycle hooks.

##### Returns

[`ExternalResourcesOptions`](../interfaces/ExternalResourcesOptions)

The current external resources configuration, or `undefined`
if default behavior is used.

#### Set Signature

```ts
set externalResourcesOptions(value): void;
```

Sets configuration options used to retrieve external X.509-related resources.

This allows customizing how external resources are accessed, for example:
- routing requests through a backend proxy to avoid CORS issues
- providing a custom loader implementation
- handling request/response lifecycle events (logging, caching, etc.)

##### Parameters

###### value

[`ExternalResourcesOptions`](../interfaces/ExternalResourcesOptions)

The external resources configuration to apply,
or `undefined` to use the default behavior.

##### Returns

`void`

#### Inherited from

[`Pkcs7SignerBase`](Pkcs7SignerBase).[`externalResourcesOptions`](Pkcs7SignerBase#externalresourcesoptions)

***

### format

#### Get Signature

```ts
get format(): Pkcs7SignatureFormat;
```

Gets or sets the PKCS#7 signature format.

##### Returns

[`Pkcs7SignatureFormat`](../enumerations/Pkcs7SignatureFormat)

#### Inherited from

[`Pkcs7SignerBase`](Pkcs7SignerBase).[`format`](Pkcs7SignerBase#format)

***

### hashAlgorithmOID

#### Get Signature

```ts
get hashAlgorithmOID(): HashAlgorithm;
```

Gets the object identifier (OID) of hash algorithm used to generate the signature.
Note! If [format](#format) [Pkcs7SignatureFormat#adbe\_pkcs7\_sha1](../enumerations/Pkcs7SignatureFormat#adbe_pkcs7_sha1)
then this property is ignored and always <b>SHA-1</b> used.

##### See

OID.HashAlgorithms

##### Example

``` typescript
const signer.hashAlgorithm = OID.HashAlgorithms.SHA512;
```

##### Returns

[`HashAlgorithm`](../type-aliases/HashAlgorithm)

#### Set Signature

```ts
set hashAlgorithmOID(value): void;
```

Sets the object identifier (OID) of hash algorithm used to generate the signature.
Note! If [format](#format) [Pkcs7SignatureFormat#adbe\_pkcs7\_sha1](../enumerations/Pkcs7SignatureFormat#adbe_pkcs7_sha1)
then this property is ignored and always <b>SHA-1</b> used.

##### See

OID.HashAlgorithms

##### Example

``` typescript
const signer.hashAlgorithm = OID.HashAlgorithms.SHA512;
```

##### Parameters

###### value

[`HashAlgorithm`](../type-aliases/HashAlgorithm)

##### Returns

`void`

***

### includeOcsp

#### Get Signature

```ts
get includeOcsp(): boolean;
```

Gets a value indicating whether to include OCSP information into the signature.

##### Returns

`boolean`

#### Set Signature

```ts
set includeOcsp(value): void;
```

Sets a value indicating whether to include OCSP information into the signature.

##### Parameters

###### value

`boolean`

##### Returns

`void`

#### Inherited from

[`Pkcs7SignerBase`](Pkcs7SignerBase).[`includeOcsp`](Pkcs7SignerBase#includeocsp)

***

### location

#### Get Signature

```ts
get location(): string;
```

Gets the CPU host name or physical location of the signing.

##### Returns

`string`

#### Set Signature

```ts
set location(value): void;
```

Sets the CPU host name or physical location of the signing.

##### Parameters

###### value

`string`

##### Returns

`void`

#### Inherited from

[`Pkcs7SignerBase`](Pkcs7SignerBase).[`location`](Pkcs7SignerBase#location)

***

### privateKeyPem

#### Get Signature

```ts
get privateKeyPem(): string;
```

Gets the private key used to generate the digital signature
for the PDF document.

The private key must correspond to the public key contained in the
signer's certificate included in the PKCS#7 (CMS) signature.

##### Remarks

The key is expected to be provided in PEM format (e.g., PKCS#8 PEM).
It should be handled securely and never exposed or persisted in an
unprotected form.

##### Returns

`string`

#### Set Signature

```ts
set privateKeyPem(value): void;
```

Sets the private key used to generate the digital signature
for the PDF document.

The private key must correspond to the public key contained in the
signer's certificate included in the PKCS#7 (CMS) signature.

##### Remarks

The key is expected to be provided in PEM format (e.g., PKCS#8 PEM).
It should be handled securely and never exposed or persisted in an
unprotected form.

##### Parameters

###### value

`string`

##### Returns

`void`

***

### reason

#### Get Signature

```ts
get reason(): string;
```

Gets the reason for the signing, such as "I agree...".

##### Returns

`string`

#### Set Signature

```ts
set reason(value): void;
```

Sets the reason for the signing, such as "I agree...".

##### Parameters

###### value

`string`

##### Returns

`void`

#### Inherited from

[`Pkcs7SignerBase`](Pkcs7SignerBase).[`reason`](Pkcs7SignerBase#reason)

***

### signatureAppearance

#### Get Signature

```ts
get signatureAppearance(): SignatureAppearance;
```

Gets a [SignatureAppearance](../type-aliases/SignatureAppearance) object defining the visual appearance
of the generated signature.
By default this property is initialized with a default instance of the [SignatureAppearance](../type-aliases/SignatureAppearance) class.
If null, the appearance streams of the signature field's widget are left as is
(not regenerated during signing).

##### Returns

[`SignatureAppearance`](../type-aliases/SignatureAppearance)

#### Set Signature

```ts
set signatureAppearance(value): void;
```

Sets a [SignatureAppearance](../type-aliases/SignatureAppearance) object defining the visual appearance
of the generated signature.
By default this property is initialized with a default instance of the [SignatureAppearance](../type-aliases/SignatureAppearance) class.
If null, the appearance streams of the signature field's widget are left as is
(not regenerated during signing).

##### Parameters

###### value

[`SignatureAppearance`](../type-aliases/SignatureAppearance)

##### Returns

`void`

#### Inherited from

[`Pkcs7SignerBase`](Pkcs7SignerBase).[`signatureAppearance`](Pkcs7SignerBase#signatureappearance)

***

### signatureField

#### Get Signature

```ts
get signatureField(): Field;
```

Gets an AcroForm field used to store a digital signature.
If <b>SignatureField.Widget</b> is not <b>null</b>,
a visual appearance will be generated based on values of the properties
[signingDateTime](Pkcs7SignerBase#signingdatetime), [location](#location) etc.

##### Returns

[`Field`](Field)

#### Set Signature

```ts
set signatureField(value): void;
```

Sets an AcroForm field used to store a digital signature.
If <b>SignatureField.Widget</b> is not <b>null</b>,
a visual appearance will be generated based on values of the properties
[signingDateTime](Pkcs7SignerBase#signingdatetime), [location](#location) etc.

##### Parameters

###### value

[`Field`](Field)

##### Returns

`void`

#### Inherited from

[`Pkcs7SignerBase`](Pkcs7SignerBase).[`signatureField`](Pkcs7SignerBase#signaturefield)

***

### signerName

#### Get Signature

```ts
get signerName(): string;
```

Gets the name of the person or authority signing the document.
NOTE: This value is used only if it is not possible to extract the name from the signature,
for example from the certificate of the signer.
By default this property is initialized with:
process.env.USER || process.env.USERNAME.

##### Returns

`string`

#### Set Signature

```ts
set signerName(value): void;
```

Sets the name of the person or authority signing the document.
NOTE: This value is used only if it is not possible to extract the name from the signature,
for example from the certificate of the signer.
By default this property is initialized with:
process.env.USER || process.env.USERNAME.

##### Parameters

###### value

`string`

##### Returns

`void`

#### Inherited from

[`Pkcs7SignerBase`](Pkcs7SignerBase).[`signerName`](Pkcs7SignerBase#signername)

***

### signingDateTime

#### Get Signature

```ts
get signingDateTime(): PdfDateTime;
```

Gets the time of signing.
NOTE: This value is used only if the time of signing is not available in the signature.
For example, a time stamp can be embedded in a PKCS#7 binary data object.
By default this property is initialized with the current date and time.

##### Returns

[`PdfDateTime`](../type-aliases/PdfDateTime)

#### Set Signature

```ts
set signingDateTime(value): void;
```

Sets the time of signing.
NOTE: This value is used only if the time of signing is not available in the signature.
For example, a time stamp can be embedded in a PKCS#7 binary data object.
By default this property is initialized with the current date and time.

##### Parameters

###### value

[`PdfDateTime`](../type-aliases/PdfDateTime)

##### Returns

`void`

#### Inherited from

[`Pkcs7SignerBase`](Pkcs7SignerBase).[`signingDateTime`](Pkcs7SignerBase#signingdatetime)

***

### timeStampProvider

#### Get Signature

```ts
get timeStampProvider(): TimeStampProviderBase;
```

Gets the [TimeStampProviderBase](../interfaces/TimeStampProviderBase) object that is used to generate the time-stamp token included
in the digital signature of the document.

##### Returns

[`TimeStampProviderBase`](../interfaces/TimeStampProviderBase)

#### Set Signature

```ts
set timeStampProvider(value): void;
```

Sets the [TimeStampProviderBase](../interfaces/TimeStampProviderBase) object that is used to generate the time-stamp token included
in the digital signature of the document.

##### Parameters

###### value

[`TimeStampProviderBase`](../interfaces/TimeStampProviderBase)

##### Returns

`void`

#### Inherited from

[`Pkcs7SignerBase`](Pkcs7SignerBase).[`timeStampProvider`](Pkcs7SignerBase#timestampprovider)

## Methods

### buildSignatureContainer()

```ts
buildSignatureContainer(docHash, signParams): Promise<Uint8Array<ArrayBufferLike>>;
```

Builds a PKCS#7 (CMS) signature container for the specified document byte ranges.

This method implements the third stage of the signing process. It constructs
a complete detached signature container by:

- Building the set of signed attributes (e.g. content type, message digest,
  revocation information, and optional CAdES attributes).
- Generating the signature value.
- Assembling the PKCS#7 SignedData structure, including:
  - digest algorithms
  - content info
  - certificate chain
  - signer info
- Optionally embedding CRLs, OCSP responses, and a timestamp token.

The resulting container can be embedded into a PDF signature field.

#### Parameters

##### docHash

`Uint8Array`

The document hash used to calculate signature

##### signParams

[`SignParams`](../type-aliases/SignParams)

Parameters produced by [Pkcs7SignerBase.getSignParams](Pkcs7SignerBase#getsignparams),
including certificate chain, revocation data, and additional signing configuration.

#### Returns

`Promise`&lt;`Uint8Array`&lt;`ArrayBufferLike`&gt;&gt;

A DER-encoded PKCS#7 (CMS) signature container as a Uint8Array.

#### Throws

May throw if signature generation fails or if the timestamp
provider (when configured) fails to produce a valid timestamp token.

#### Inherited from

[`Pkcs7SignerBase`](Pkcs7SignerBase).[`buildSignatureContainer`](Pkcs7SignerBase#buildsignaturecontainer)

***

### getSignParams()

```ts
getSignParams(): Promise<SignParams>;
```

Prepares parameters required for the first stage of the signing process.

This method performs validation, initializes signing-related data,
and collects all inputs required for building the final signature container.
It corresponds to the "preparation stage" of signing.

#### Returns

`Promise`&lt;[`SignParams`](../type-aliases/SignParams)&gt;

A [SignParams](../type-aliases/SignParams) object containing:
- certificate chain
- CRLs and OCSP responses (if available)
- additional parameters required for signature generation

#### Throws

If the configured signature format is invalid or unsupported.

#### Overrides

[`Pkcs7SignerBase`](Pkcs7SignerBase).[`getSignParams`](Pkcs7SignerBase#getsignparams)