SecureBlackbox 2020 .NET Edition

Questions / Feedback?

PDFSignature Type

This component is a container for PDF signature details.

Remarks

Use it to tune up signature properties and widget appearance when creating a signature, or to read the signature information when processing it.

Fields

AlgorithmCaption
String

Caption of the signature widget field with information about the signature algorithm.

AlgorithmInfo
String

Information about the algorithm to be shown on the signature widget.

This property contains information about the algorithm to be displayed in the signature widget. This property is taken into account only if AutoText is False. If AutoText is True, information about the algorithm is generated automatically in the form of "Algorithm/Key size", e.g. "RSA/1024 bits".

AllowedChanges
PDFSignatureAllowedChanges

The changes to the document are allowed by the signature.

This field is only applicable to MDP/certification signatures and has no effect for any other kinds of signatures (regular or document timestamps).

psacNone0No changes are allowed by the signature
psacFillInForms1Only form fill-in is allowed
psacComment2Commenting is allowed
psacAll3Form fill-in and commenting are allowed

AuthorName
String

A human-readable signer name. This is a PDF document property.

AutoFontSize
Boolean

Enables default widget font sizes.

The default font sizes are TitleFontSize: 8.77, TimestampFontSize: 4.89, SectionTitleFontSize: 7, and SectionTextFontSize: 5. Switch AutoFontSize off and use the respective properties to provide custom font sizes.

The standard unit of the symbol size in the default user space is 1/72 inch.

AutoPos
Boolean

Use the default widget position on a page.

The default position is aligned with the top right corner of the page. Switch this property off and use OffsetX and OffsetY to put the widget elsewhere on the page.

AutoSize
Boolean

Use the default widget size.

Switch this property off and use Height and Width properties to use a different size.

AutoStretchBackground
Boolean

Stretches the background picture to fit the signature widget.

AutoText
Boolean

Use the default widget descriptions.

The default texts are based on the information contained in the signing certificate. Set this property to false and use AlgorithmInfo, SignerInfo, and Header properties to generate customized descriptions.

BackgroundData
Byte()

Contains/takes the data of the signature widget background bitmap.

Assign the widget background data (in form of JPEG or JPEG2000 bytes) to this property.

BackgroundHeight
Integer

The height of the background image in pixels.

It is important that this property matches the exact size of the image when custom background is used.

BackgroundImageType
PDFWidgetImageTypes

The type of the image contained in BackgroundData. JPEG and JPEG2000 format are currently supported.

pwitJPEG20000JPEG 2000 format (supports transparency)
pwitJPEG1standard JPEG format (does not support transparency)
pwitCustom2Custom background format

BackgroundMask
Byte()

Contains the background image mask.

Masks provide means for marking transparent areas on your signature widgets. Specifically, a transparency mask tells PDF viewing apps which pixels of the signature widget should be kept visible and which should be rendered transparent instead.

In most cases, you will need a unique mask that is tailored for your signature widget image. This is something that you will need to create yourself basing on your preferences and the actual image design.

A mask is effectively a matrix of bits, with each bit corresponding to a pixel on your background bitmap. A bit is set to 1 if the corresponding pixel needs to be made transparent, or to 0 if it needs to be opaque.

To create the mask that can be passed to BackgroundMask, please follow the below procedure:

Go through the bitmap of your signature widget bitmap row to row, processing each row of pixels from left to right. For each row,

1. Start with an empty bit string.

2. For every pixel in a row, add '1' bit if you want it to be transparent, or '0' bit if you want it to be opaque.

3. Upon reaching the end of the row, append '0' bits to your bit string until the number of bits in it is a multiple of 8. This is because each row of pixels needs to be represented with a whole number of bytes.

4. Convert the bit string to a byte array by grouping every 8 bits into a byte.

Do the same for every row of pixels, and then concatenate the received byte arrays together. Pass the created byte array to SetSigBackgroundMask().

A small example. Imagine your image is 19 pixels wide and 3 pixels tall. Imagine you want to make it 'semi-transparent' by using a 'mesh' pattern. The mask will therefore look like this:

10101010 10101010 10100000 // first row

01010101 01010101 01000000 // second row

10101010 10101010 10100000 // third row

Note that the last 5 bits of each row are padding '0' bits and are ignored: you only need them to make each row contain a whole number of bytes. When converted to a byte string, this would look like

0xAA 0xAA 0xA0

0x55 0x55 0x40

0xAA 0xAA 0xA0

, or, if written as a byte array, (0xAA, 0xAA, 0xA0, 0x55, 0x55, 0x40, 0xAA, 0xAA, 0xA0): this is what you need to pass to SetSigBackgroundMask().

BackgroundStyle
PDFWidgetBackgroundStyles

The style of the signature widget background.

pwbsDefault uses the default image, pwbsNoBackground doesn't use background image at all, and pwbsCustom expects the application to provide a custom background image.

pwbsDefault0The default widget background
pwbsNoBackground1No (empty) background
pwbsCustom2Custom background (picture or vector)

BackgroundWidth
Integer

The width of the background image in pixels.

It is important that this property matches the exact size of the image when custom background is used.

Certification
Boolean

Specifies whether this is a Certification (MDP) signature.

Certification signatures is a feature that was used by earlier Acrobat versions. It has little use these days.

ChainValidationDetails
Integer

The details of a certificate chain validation outcome. They may often suggest what reasons that contributed to the overall validation result.

Returns a bit mask of the following options:

cvrBadData0x0001One or more certificates in the validation path are malformed

cvrRevoked0x0002One or more certificates are revoked

cvrNotYetValid0x0004One or more certificates are not yet valid

cvrExpired0x0008One or more certificates are expired

cvrInvalidSignature0x0010A certificate contains a non-valid digital signature

cvrUnknownCA0x0020A CA certificate for one or more certificates has not been found (chain incomplete)

cvrCAUnauthorized0x0040One of the CA certificates are not authorized to act as CA

cvrCRLNotVerified0x0080One or more CRLs could not be verified

cvrOCSPNotVerified0x0100One or more OCSP responses could not be verified

cvrIdentityMismatch0x0200The identity protected by the certificate (a TLS endpoint or an e-mail addressee) does not match what is recorded in the certificate

cvrNoKeyUsage0x0400A mandatory key usage is not enabled in one of the chain certificates

cvrBlocked0x0800One or more certificates are blocked

cvrFailure0x1000General validation failure

cvrChainLoop0x2000Chain loop: one of the CA certificates recursively signs itself

cvrWeakAlgorithm0x4000A weak algorithm is used in one of certificates or revocation elements

cvrUserEnforced0x8000The chain was considered invalid following intervention from a user code

ChainValidationResult
ChainValidities

The outcome of a certificate chain validation routine.

Available options:

cvtValid0The chain is valid

cvtValidButUntrusted1The chain is valid, but the root certificate is not trusted

cvtInvalid2The chain is not valid (some of certificates are revoked, expired, or contain an invalid signature)

cvtCantBeEstablished3The validity of the chain cannot be established because of missing or unavailable validation information (certificates, CRLs, or OCSP responses)

Use the ValidationLog property to access the detailed validation log.

ClaimedSigningTime
String

Returns or sets signature's creation time.

Use this property to get or set the signature creation time from the signer's computer. The claimed time, unlike ValidatedSigningTime does not originate from a trusted TSA and may be forfeited or wrong.

The time is provided in UTC.

CompressWidgetData
Boolean

Whether the signature widget data should be compressed before saving.

ContactInfo
String

Contains signer's contact information. This is a PDF document property.

CoverageEndsAt
Integer

Indicates the offset in the PDF file where signature coverage ends.

PDF generators often use incremental updates to make changes in the documents. This may result in the signature only covering a part of the document (one of the past revisions), but not the subsequent changes.

Use this property to identify the offset where the signature coverage ends. One option is to compare it to the length of the whole document. Alternatively, use the GetSignedVersion() method of the PDFVerifier class to extract the exact revision that was signed.

CustomAppearance
Byte()

Contains custom widget description in raw PDF graphic operators format.

Use this property to provide a PDF stream describing the widget appearance.

CustomBackgroundContentStream
String

Specifies custom custom background content stream for pwbsCustom BackgroundStyle.

CustomData
Byte()

A uninterpreted custom data to save with the signature.

CustomVisualStatusMatrix
String

Defines the custom visual status matrix.

Use of this property makes sense only if a visual status icon is displayed over the signature (ShowVisualStatus). Prior to Acrobat 6, signature's visual appearance was modified with a status icon, e.g., "valid" or "invalid". The visual status matrix is used to position the icon in the signature widget. If CustomVisualStatusMatrix is empty, the value of '0.25 0 0 0.25 0 0' is used.

DateCaptionFormat
String

The format string used to display the signing time in the signature widget.

Leave this property empty (default value) to use the default formatting.

EmptyField
Boolean

Indicates whether or not the signature created/read is an empty field (a signature placeholder).

FilterName
String

The signature filter name.

FullSignatureName
String

Specifies the full name of the signature field.

This is an internal identifier of a signature (such as Signature1) and is not meant to be human-readable.

HashAlgorithm
String

Specifies the hash algorithm to be used for signing.

SB_HASH_ALGORITHM_SHA1SHA1
SB_HASH_ALGORITHM_SHA224SHA224
SB_HASH_ALGORITHM_SHA256SHA256
SB_HASH_ALGORITHM_SHA384SHA384
SB_HASH_ALGORITHM_SHA512SHA512
SB_HASH_ALGORITHM_MD2MD2
SB_HASH_ALGORITHM_MD4MD4
SB_HASH_ALGORITHM_MD5MD5
SB_HASH_ALGORITHM_RIPEMD160RIPEMD160
SB_HASH_ALGORITHM_CRC32CRC32
SB_HASH_ALGORITHM_SSL3SSL3
SB_HASH_ALGORITHM_GOST_R3411_1994GOST1994
SB_HASH_ALGORITHM_WHIRLPOOLWHIRLPOOL
SB_HASH_ALGORITHM_POLY1305POLY1305
SB_HASH_ALGORITHM_SHA3_224SHA3_224
SB_HASH_ALGORITHM_SHA3_256SHA3_256
SB_HASH_ALGORITHM_SHA3_384SHA3_384
SB_HASH_ALGORITHM_SHA3_512SHA3_512
SB_HASH_ALGORITHM_BLAKE2S_128BLAKE2S_128
SB_HASH_ALGORITHM_BLAKE2S_160BLAKE2S_160
SB_HASH_ALGORITHM_BLAKE2S_224BLAKE2S_224
SB_HASH_ALGORITHM_BLAKE2S_256BLAKE2S_256
SB_HASH_ALGORITHM_BLAKE2B_160BLAKE2B_160
SB_HASH_ALGORITHM_BLAKE2B_256BLAKE2B_256
SB_HASH_ALGORITHM_BLAKE2B_384BLAKE2B_384
SB_HASH_ALGORITHM_BLAKE2B_512BLAKE2B_512
SB_HASH_ALGORITHM_SHAKE_128SHAKE_128
SB_HASH_ALGORITHM_SHAKE_256SHAKE_256
SB_HASH_ALGORITHM_SHAKE_128_LENSHAKE_128_LEN
SB_HASH_ALGORITHM_SHAKE_256_LENSHAKE_256_LEN

Header
String

Specifies the header text to put on the signature widget.

Height
Integer

Specifies the height of the signature widget.

The AutoSize property should be switched off for this to apply.

HideDefaultText
Boolean

Switch offs generation of any headers for the signature widget.

IgnoreExistingAppearance
Boolean

Tells the component to discard any existing widget parameters when signing empty signature fields.

IgnoreExistingAppearance only makes sense for signatures created by signing existing empty signature fields with pre-defined widget descriptions.

InvertMask
Boolean

Specifies whether BackgroundMask should be inverted.

Set this property to flip all the bits in the mask, by making opaque all the bits declared by the mask as transparent, and making transparent all the bits declared as opaque.

Invisible
Boolean

Controls whether the signature widget is visible on the page.

Level
PDFSignatureLevels

Specifies the signature kind and level.

pslLegacy0Legacy Adobe signature (adbe.pkcs7.detached or adbe.pkcs7.sha1)
pslBES1PAdES-BES signature (ETSI.CAdES.detached)
pslEPES2PAdES-EPES signature (ETSI.CAdES.detached + embedded policy)
pslLTV3PAdES-LTV signature (ETSI.CAdES.detached + revocation info)
pslDocumentTimestamp4Document timestamp (ETSI.RFC3161)

Location
String

Specifies the host name or the physical location of the signing entity. This is a PDF property.

Locked
Boolean

Specifies whether the signature widget can be moved by the user.

This is an obsolete property that would rarely need changing.

LockedContents
Boolean

Specifies whether signature widget contents should be locked.

This is an obsolete property that would rarely need changing.

NoRotate
Boolean

If this value is True the signature widget will not be rotated when the document is rotated in the viewing app.

NoView
Boolean

If this value is True the signature widget will not be displayed when the document is viewed.

NoZoom
Boolean

If this value is True the signature widget size will not be changed during zooming.

OffsetX
Integer

Specifies the signature widget offset from the left-hand page border when AutoPos is False.

OffsetY
Integer

Specifies the signature widget offset from the bottom page border when AutoPos is False.

Page
Integer

The index of the page on which to place the signature.

To place the signature widget on multiple pages, use PagesToPlaceOn and ShowOnAllPages properties.

PagesToPlaceOn
String

Page numbers on which the signature is shown.

PolicyHash
String

The signature policy hash value for EPES signatures.

PolicyHashAlgorithm
String

The algorithm that was used to calculate the signature policy hash.

PolicyID
String

The policy ID to be included into the signature.

Print
Boolean

Whether the signature shall appear in printed documents.

Qualified
QualifiedStatuses

Indicates a qualified electronic signature.

Use this property to check if an electronic signature is created using a qualified device for creating electronic signatures and that relies on a qualified electronic signature certificate.

Adjust UseDefaultTSLs property and/or CustomTSLs property before validating the signature/certificate to properly obtain TSP (Trust Service Provider) service status. Use Qualified* and TSL* config properties to obtain extended information.

The following qualified statuses are supported:

sqsUnknown0Qualified status unknown. Use config's QualifiedInfo setting to obtain service status URI.

sqsNone1None

sqsGranted2Granted

sqsWithdrawn3Withdrawn

sqsSetByNationalLaw4Set by national law

sqsDeprecatedByNationalLaw5Deprecated by national law

sqsRecognizedAtNationalLevel6Recognized at national level

sqsDeprecatedAtNationalLevel7Deprecated at national level

sqsUnderSupervision8Under supervision

sqsSupervisionInCessation9Supervision in cessation

sqsSupervisionCeased10Supervision ceased

sqsSupervisionRevoked11Supervision revoked

sqsAccredited12Accredited

sqsAccreditationCeased13Accreditation ceased

sqsAccreditationRevoked14Accreditation revoked

sqsInAccordance15Deprecated. The subject service is in accordance with the scheme's specific status determination criteria (only for use in positive approval schemes).

sqsExpired16Deprecated. The subject service is no longer overseen by the scheme, e.g. due to nonrenewal or withdrawal by the TSP, or cessation of the service or the scheme's operations.

sqsSuspended17Deprecated. The subject service's status is temporarily uncertain whilst checks are made by the scheme operator (typically e.g. while a revocation request is being investigated or if action is required to resolve a deficiency in the service fulfilling the scheme's criteria.

sqsRevoked18Deprecated. The subject service's approved status has been revoked because it is no longer in accordance with the scheme's specific status determination criteria (only for use in positive approval schemes).

sqsNotInAccordance19Deprecated. The subject service is not in accordance with the scheme's specific status determination criteria (only for use in negative approval schemes).

ReadOnly
Boolean

Controls the ReadOnly flag of the widget.

Reason
String

Specifies the reason for signing. This is a PDF document property.

Rotate
Integer

Specifies the rotation angle of the signature widget in degrees. Values of 0, 90, 180, and 270 are allowed.

SectionTextFontSize
String

Use this property to specify the font size to be used for general text on the widget.

SectionTitleFontSize
String

Use this property to specify the font size to be used for section title text on the widget.

ShowOnAllPages
Boolean

Forces the signature widget to be displayed on all pages in the document.

ShowTimestamp
Boolean

Whether to display the signing time details on the widget.

ShowVisualStatus
Boolean

Specifies whether to show the signature's status icon.

It is a good idea to avoid using the visual status icon, as described below:

According to the Digital Signature Appearances Adobe Acrobat SDK (May 2015), "Prior to Acrobat 6.0, signature appearances were manipulated at run-time in order to display the validity of the signature. The validity was shown as a graphic icon and with an additional, optional text message. The manipulated portions of the signature appearance were contained in layers n1, n3 and n4. Beginning with version 6, Acrobat does not maintain support for signature appearances that can be manipulated, though legacy signatures with these appearances may continue to display correctly. Use of layers n1, n3, and n4 is not recommended."

SignatureName
String

Specifies the unique signature identifier to use.

This is an internal identifier of a signature (such as Signature1) and is not meant to be human-readable.

SignatureValidationResult
SignatureValidities

The outcome of the cryptographic signature validation.

The following signature validity values are supported:

svtValid0The signature is valid

svtUnknown1Signature validity is unknown

svtCorrupted2The signature is corrupted

svtSignerNotFound3Failed to acquire the signing certificate. The signature cannot be validated.

svtFailure4General failure

SignerCaption
String

Specifies the caption for the signer section on the signature widget.

The default value is "Signer: ".

SignerInfo
String

Provides custom signer information to put on the signature widget.

This property is only considered if AutoText is set to False. The standard signature widget allows for several short strings separated by CRLF.

SimpleFontName
String

Specifies the Type 1 font name for the signature text.

PDF format supports 14 standard fonts, specifically: "Times-Roman", "Helvetica", "Courier", "Symbol", "Times-Bold", "Helvetica-Bold", "Courier-Bold", "ZapfDingbats", "Times-Italic", "Helvetica-Oblique", "Courier-Oblique", "Times-BoldItalic", "Helvetica-BoldOblique", "Courier-BoldOblique".

StretchX
String

Use this field to manually adjust the horizontal size of the stretched background picture.

StretchY
String

Use this field to manually adjust the size of the stretched background picture in the vertical direction.

SubjectRDN
String

Contains the RDN of the owner of the signing certificate.

RDN is a number of OID=Value pairs declared in the certificate and providing the owner's details.

Timestamped
Boolean

Indicates if the signature is timestamped.

TimestampFontSize
String

Use this property to specify the font size to be used for timestamp text on the widget.

TitleFontSize
String

Use this property to specify the font size to be used for the main title on the widget.

ToggleNoView
Boolean

When True, the signature widget will be displayed only when the user is moving a mouse over it.

ValidatedSigningTime
String

Contains the certified signing time.

Use this property to obtain the signing time as certified by a timestamp from a trusted timestamping authority. This property is only non-empty if there was a valid timestamp included in the signature.

ClaimedSigningTime returns a non-trusted signing time from the signer's computer.

Both times are in UTC.

ValidationLog
String

Contains the signing certificate's chain validation log. This information may be very useful in investigating chain validation failures.

Width
Integer

Specifies the width of the signature widget.

The AutoSize property should be switched off for this to apply.

Constructors

public PDFSignature();
Public PDFSignature()

Creates a new PDF signature object.

Copyright (c) 2022 /n software inc. - All rights reserved.
SecureBlackbox 2020 .NET Edition - Version 20.0 [Build 8165]