diff --git a/API.md b/API.md new file mode 100644 index 0000000..b214027 --- /dev/null +++ b/API.md @@ -0,0 +1,264 @@ +# Enum Definitions + +## Crypto.Mode +:egg::egg::egg: +* Type: number + +Name | Value | Description +--- | --- | --- +RC4_40 | 0 | 40bit RC4 Encryption +RC4_128 | 1 | 128bit RC4 Encryption +AES_128 | 2 | 128bit AES Encryption +AES_256 | 3 | 256bit AES Encryption + +# Type Definitions + +## DSSInfo +:taco::taco::taco: + +Name | Type | Attributes | Description +--- | --- | --- | --- +certs | Array\ | optional | An array of necessary certificates. +ocsps | Array\ | optional | An array of [OCSP](#note)s' response. +crls | Array\ | optional | The array of [CRL](#note)s. + +## EncryptOption +:taco::taco::taco: + +Name | Type | Attributes | Description +--- | --- | --- | --- +mode | [Crypto.Mode](#Crypto.Mode) | required | The mode of encryption +permissions | Array\ | optional | The set of permissions to be blocked :one: +userpwd | string | optional | User password. Used when opening the pdf. +ownerpwd | string | optional | Owner password. If not specified, a random value is used. +pubkeys | Array\<[PubKeyInfo](#PubKeyInfo)\> | optional | An array of recipients containing public-key certificates ('c') and permissions ('p'). + +:one: `permissions` can be the values listed blow. + * `copy`: (Only valid on public-key mode) Copy text and graphics from the document; + * `print`: Print the document; + * `modify`: Modify the contents of the document by operations other than those controlled by 'fill-forms', 'extract' and 'assemble'; + * `copy-extract`: Copy or otherwise extract text and graphics from the document; + * `annot-forms`: Add or modify text annotations, fill in interactive form fields, and, if 'modify' is also set, create or modify interactive form fields (including signature fields); + * `fill-forms`: Fill in existing interactive form fields (including signature fields), even if 'annot-forms' is not specified; + * `extract`: Extract text and graphics (in support of accessibility to users with disabilities or for other purposes); + * `assemble`: Assemble the document (insert, rotate, or delete pages and create bookmarks or thumbnail images), even if 'modify' is not set; + * `print-high`: Print the document to a representation from which a faithful digital copy of the PDF content could be generated. When this is not set, printing is limited to a low-level representation of the appearance, possibly of degraded quality. + + +## PubKeyInfo +:taco::taco::taco: + +Name | Type | Attributes | Description +--- | --- | --- | --- +c | Array\
:fork_and_knife:Uint8Array
:fork_and_knife:ArrayBuffer
:fork_and_knife:string
:fork_and_knife:forge_cert | optional | A certificate. +p | Array\ | optional | An array of permissions you want to block. Valid values see [EncryptOption](#encryptoption) + +## SignAreaInfo +:taco::taco::taco: + +Name | Type | Attributes | Description +--- | --- | --- | --- +x | number | required | Distance from left +y | number | required | Distance from top +w | number | required | Width +h | number | required | Height + +## SignDrawInfo +:taco::taco::taco: + +Name | Type | Attributes | Description +--- | --- | --- | --- +area | [SignAreaInfo](#signareainfo) | required | The signature's drawing area, these numbers are dots on 72dpi. +pageidx | number | optional | The index of a page where the signature will be drawn. Default is 0. +imgData | Array\
:fork_and_knife:Uint8Array
:fork_and_knife:ArrayBuffer
:fork_and_knife:string | optional | The image's data. +imgType | string | optional | The image's type, only support jpg and png +text | string| optional | A text drawing for the signature, not implemented yet +fontData | PDFLib.StandardFonts
:fork_and_knife:Array\
:fork_and_knife:Uint8Array
:fork_and_knife:ArrayBuffer
:fork_and_knife:string | optional | The font's data for drawing text, not implemented yet + +## SignOption +:taco::taco::taco: + +Name | Type | Attributes | Description +--- | --- | --- | --- +p12cert | Array\
:fork_and_knife:Uint8Array
:fork_and_knife:ArrayBuffer
:fork_and_knife:string | optional | Certificate's data. In the case of adding a document timestamp, it must be omitted. +pwd | string | optional | The passphrase of the certificate. In the case of adding a document timestamp, it must be omitted. +permission | number | optional | The modification permissions granted for this document. :one: +reason | string | optional | The reason for signing +location | string | optional | Your location +contact | string | optional | Your contact information +signdate | [TsaServiceInfo](#tsaserviceinfo)
:fork_and_knife:string
:fork_and_knife:Date | optional | In the case of adding a document timestamp, it can't be omitted and can't be a Date. :two: +signame | string | optional | The name of the signature +drawinf | [SignDrawInfo](#SignDrawInfo) | optional | Visible signature's information +ltv | number | optional | The method of how to enable [LTV](#note) :three: +debug | boolean | optional | To output debug informations or not + +:one: `permission` is a setting of [DocMDP](#note). Valid values are: + * 1: No changes to the document are permitted; any change to the document invalidates the signature. + * 2: Permitted changes are filling in forms, instantiating page templates, and signing; other changes invalidate the signature. + * 3: Permitted changes are the same as for 2, as well as annotation creation, deletion, and modification; other changes invalidate the signature. + +:two: `signdate` + * When it is a Date, it means the date and time of signing. + * When it is a string, it can be an url of [TSA](#note) or an index of the preset [TSA](#note)s as below: + * "1": http://ts.ssl.com + * "2": http://timestamp.digicert.com + * "3": http://timestamp.sectigo.com + * "4": http://timestamp.entrust.net/TSS/RFC3161sha2TS + * "5": http://timestamp.apple.com/ts01 + * "6": http://www.langedge.jp/tsa + * "7": https://freetsa.org/tsr + * When it is a [TsaServiceInfo](#TsaServiceInfo), it means a full customized information of a [TSA](#note). + * When it is omitted, the system timestamp will be used. + +:three: `ltv`'s valid values are: + * 1: auto; Try using [OCSP](#note) only to enable the [LTV](#note) first; If can't, try using [CRL](#note) to enable the [LTV](#note). + * 2: crl only; Only try using [CRL](#note) to enable the [LTV](#note). + + +## TsaServiceInfo +:taco::taco::taco: + +Name | Type | Attributes | Description +--- | --- | --- | --- +url | string | required | The url of [TSA](#note). +len | number | optional | The length of signature's placeholder. +headers | Object\ | optional | The customized headers for sending to tsa server. + +# Function Definitions + +## u8arrToRaw +:fondue::fondue::fondue: +#### u8arrToRaw(uarr) :arrow_right: string +Converts an Uint8Array to a raw string. + +Name | Type | Attributes | Description +--- | --- | --- | --- +uarr | Uint8Array | required | The target Uint8Array + +## rawToU8arr +:fondue::fondue::fondue: +#### rawToU8arr(raw) :arrow_right: Uint8Array +Converts a raw string to an Uint8Array. + +Name | Type | Attributes | Description +--- | --- | --- | --- +raw | string | required | The target string + +# Classes + +## CertsChain +:croissant::croissant::croissant: +### Constructor +#### new CertsChain(certs*opt*) + +Name | Type | Attributes | Description +--- | --- | --- | --- +certs | Array\
:fork_and_knife:Array\
:fork_and_knife:Array\ | optional | An array of certificates. + +### Methods +#### buildChain(cert) :arrow_right: Promise\ +Build the certificates chain from the specified certificate, and returns true if this operation is successful. + +Name | Type | Attributes | Description +--- | --- | --- | --- +cert | forge_cert | required | A certificate to start build by looking for it's issuer. + +#### getAllCerts() :arrow_right: Array\ +Returns an array of all certificates. + +#### getSignCert() :arrow_right: forge_cert +Returns the certificate for signing. + +#### isSelfSignedCert() :arrow_right: boolean +Returns true if the certificate for signing is a self-signed certificate. + +#### prepareDSSInf(crlOnly*opt*) :arrow_right: Promise\<[DSSInfo](#dssinfo)\> +Returns the informations of [DSS](#note). + +Name | Type | Attributes | Description +--- | --- | --- | --- +crlOnly | boolean | optional | Query [CRL](#note) only or try query [OCSP](#note) first. + +## PdfCryptor +:croissant::croissant::croissant: +### Constructor +#### new PdfCryptor(encopt) + +Name | Type | Attributes | Description +--- | --- | --- | --- +encopt | [EncryptOption](#EncryptOption) | required | Infomations of encryption. + +### Methods +#### encryptObject(num, val) +Encrypts the content of the specified pdf object. + +Name | Type | Attributes | Description +--- | --- | --- | --- +num | number | required | The object number. +val | PDFLib.PDFObject | required | The target object. + +#### encryptPdf(pdf, ref*opt*) :arrow_right: Promise\ +Encrypts the contents in the pdf and returns the pdf document. + +Name | Type | Attributes | Description +--- | --- | --- | --- +pdf | PDFLib.PDFDocument
:fork_and_knife:Array\
:fork_and_knife:Uint8Array
:fork_and_knife:ArrayBuffer
:fork_and_knife:string | required | The target pdf. +ref | PDFLib.PDFRef | optional | The unique reference will be assigned to the encryption information. + +## PdfSigner +:croissant::croissant::croissant: +### Constructor +#### new PdfSigner(signopt) + +Name | Type | Attributes | Description +--- | --- | --- | --- +signopt | [SignOption](#SignOption) | required | Infomations of signing. + +### Methods +#### sign(pdf, cypopt*opt*) :arrow_right: Promise\ +Sign the pdf and returns the binary data. + +Name | Type | Attributes | Description +--- | --- | --- | --- +pdf | PDFLib.PDFDocument|Array\|Uint8Array|ArrayBuffer|string | required | The target pdf. +cypopt | [EncryptOption](#EncryptOption) | optional | The informations of encryption. + +## TsaFetcher +:croissant::croissant::croissant: +### Constructor +#### new TsaFetcher(inf) + +Name | Type | Attributes | Description +--- | --- | --- | --- +inf | [TsaServiceInfo](#TsaServiceInfo) | required | Infomations of [TSA](#note). + +### Properties + +Name | Type | Description +--- | --- | --- +url | string | The url of [TSA](#note). +len | number | The length of signature which is generated by the [TSA](#note). + +### Methods +#### getCertsChain() :arrow_right: [CertsChain](#CertsChain) +Get the certificates' chain from the response of [TSA](#note). + +#### getToken(forP7*opt*) :arrow_right: forge.asn1 +Get the token data in response from [TSA](#note). +Name | Type | Attributes | Description +--- | --- | --- | --- +forP7 | boolean | optional | To create an asn1 for appending to a pkcs#7 signature or not. + +#### queryTsa(data) :arrow_right: Promise\ +Query [TSA](#note) to sign the data and returns error message if error occured. +Name | Type | Attributes | Description +--- | --- | --- | --- +data | string | required | The data needs to be signed. + +## Note +1. __CRL__:loudspeaker: Certificate Revocation List +2. __DDS__:loudspeaker: Document Security Store +3. __DocMDP__:loudspeaker: Document Modification Detection and Prevention +4. __LTV__:loudspeaker: Long-Term Validation +5. __OCSP__:loudspeaker: Online Certificate Status Protocol +6. __TSA__:loudspeaker: Time Stamp Authority