CryptoServer Class
Properties Methods Events Config Settings Errors
The CryptoServer class offers capabilities in processing PKI Proxy REST protocol messages.
Syntax
pkiproxy.cryptoserver()
Remarks
TBD
Property List
The following is the full list of the properties of the class with short descriptions. Click on the links for further details.
| Keys | An accessor to the collection of keys contained in the key store. |
| Mechanisms | An accessor to the collection of mechanisms supported by the key store. |
| Objects | An accessor to the collection of objects - such as certificates - contained in the key store. |
| PinnedKey | A pinned key. |
| PinnedMechanism | An accessor to the collection of mechanism properties. |
| PinnedObject | A pinned object. |
| Request | Provides access to request properties after reading it or before saving. |
| RequestKey | A request key. |
| RequestObject | A request object. |
| Response | Provides access to response properties after reading it or before saving. |
Method List
The following is the full list of the methods of the class with short descriptions. Click on the links for further details.
| AddKey | Registers object information in the response. |
| AddMechanism | Registers mechanism information in the response. |
| AddObject | Registers object information in the response. |
| Config | Sets or retrieves a configuration setting. |
| CreateWebRequest | Creates a new REST request. |
| CreateWebResponse | Creates a new REST response. |
| GetRequestParam | Looks up for a parameter in various request locations. |
| GetResponseParam | Looks up for a parameter in various response locations. |
| OpenWebRequest | Opens a REST request and populates it in the Request property. |
| OpenWebResponse | Opens a REST response and populates it in the Response property. |
| Reset | Clear all list. |
| SetRequestParam | Sets up a request parameter in the designated location. |
| SetResponseParam | Sets up a response parameter in the designated location. |
Event List
The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.
| Error | Information about errors during data delivery. |
Config Settings
The following is a list of config settings for the class with short descriptions. Click on the links for further details.
| ResponseFormat | The format of response. |
| TempPath | Path for storing temporary files. |
CryptoServer.Keys Property
An accessor to the collection of keys contained in the key store.
Syntax
getKeys(): CryptoKeyList;
Default Value
Remarks
Use this property after loading the response to access, browse, or iterate over keys contained in the storage.
This property is read-only and not available at design time.
Please refer to the CryptoKey type for a complete list of fields.CryptoServer.Mechanisms Property
An accessor to the collection of mechanisms supported by the key store.
Syntax
getMechanisms(): CryptoMechanismList;
Default Value
Remarks
Use this property after loading the response to access cryptographic mechanisms supported by the key store.
This property is read-only and not available at design time.
Please refer to the CryptoMechanism type for a complete list of fields.CryptoServer.Objects Property
An accessor to the collection of objects - such as certificates - contained in the key store.
Syntax
getObjects(): CryptoObjectList;
Default Value
Remarks
Use this property after loading the response to access, browse, or iterate over objects contained in the storage.
This property is read-only and not available at design time.
Please refer to the CryptoObject type for a complete list of fields.CryptoServer.PinnedKey Property
A pinned key.
Syntax
getPinnedKey(): CryptoKey; setPinnedKey(pinnedKey: CryptoKey): void;
Default Value
Remarks
Use this property to pin an key before registering it with the response with AddKey method.
This property is not available at design time.
Please refer to the CryptoKey type for a complete list of fields.CryptoServer.PinnedMechanism Property
An accessor to the collection of mechanism properties.
Syntax
getPinnedMechanism(): CryptoMechanism;
Default Value
Remarks
Use this property to access cryptographic mechanism properties included in the request, or prepare them before adding to the response.
This property is read-only and not available at design time.
Please refer to the CryptoMechanism type for a complete list of fields.CryptoServer.PinnedObject Property
A pinned object.
Syntax
getPinnedObject(): CryptoObject; setPinnedObject(pinnedObject: CryptoObject): void;
Default Value
Remarks
Use this property to pin an object before registering it with the response with AddObject method.
This property is not available at design time.
Please refer to the CryptoObject type for a complete list of fields.CryptoServer.Request Property
Provides access to request properties after reading it or before saving.
Syntax
getRequest(): CryptoRequest;
Default Value
Remarks
Use this property to access the request properties or adjust them before creating a request.
This property is read-only.
Please refer to the CryptoRequest type for a complete list of fields.CryptoServer.RequestKey Property
A request key.
Syntax
getRequestKey(): CryptoKey;
Default Value
Remarks
Use this property to publishes the details of the key POSTed in the request.
This property is read-only and not available at design time.
Please refer to the CryptoKey type for a complete list of fields.CryptoServer.RequestObject Property
A request object.
Syntax
getRequestObject(): CryptoObject;
Default Value
Remarks
Use this property to publishes the details of the object POSTed in the request.
This property is read-only and not available at design time.
Please refer to the CryptoObject type for a complete list of fields.CryptoServer.Response Property
Provides access to response properties after reading it or before saving.
Syntax
getResponse(): CryptoResponse;
Default Value
Remarks
Use this property to access the response properties or adjust them before creating a response.
This property is read-only.
Please refer to the CryptoResponse type for a complete list of fields.CryptoServer.addKey Method
Registers object information in the response.
Syntax
async cryptoserver.addKey(): Promise<void>
Remarks
Use this method to register a single key details, provided via the PinnedKey property, in the response for GetObjectInfo or ListObjects requests.
If the ListObjects request you are handling results in truncated content, remember to set the Token property of the response to provide continuity.In the same manner, the Token property of the request lets you continue previously started listing requests.The key is added to the Keys list.
CryptoServer.addMechanism Method
Registers mechanism information in the response.
Syntax
async cryptoserver.addMechanism(): Promise<void>
Remarks
Use this method to register a single mechanism details, provided via the PinnedMechanism property, in the response for GetMechanismInfo or ListMechanism requests.
The mechanism info is added to the Mechanisms list.
CryptoServer.addObject Method
Registers object information in the response.
Syntax
async cryptoserver.addObject(): Promise<void>
Remarks
Use this method to register a single object details, provided via the PinnedObject property, in the response for GetObjectInfo or ListObjects requests.
If the ListObjects request you are handling results in truncated content, remember to set the Token property of the response to provide continuity.In the same manner, the Token property of the request lets you continue previously started listing requests.The object is added to the Objects list.
CryptoServer.config Method
Sets or retrieves a configuration setting.
Syntax
async cryptoserver.config(configurationString : string): Promise<string>
Remarks
Config is a generic method available in every class. It is used to set and retrieve configuration settings for the class.
These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the Config method.
To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).
To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.
CryptoServer.createWebRequest Method
Creates a new REST request.
Syntax
async cryptoserver.createWebRequest(): Promise<void>
Remarks
Use this method to create a new web request. Call this method after filling in the properties of the Request object.
Once this method completes, the Verb, Url, Headers, and Body fields of the Request object are updated to match the new request parameters.
CryptoServer.createWebResponse Method
Creates a new REST response.
Syntax
async cryptoserver.createWebResponse(): Promise<void>
Remarks
Use this method to create a new web request. Call this method after filling in the properties of the Response object.
Once this method completes, the Status, Headers, and Body fields of the Response object are updated to match the new response parameters.
CryptoServer.getRequestParam Method
Looks up for a parameter in various request locations.
Syntax
async cryptoserver.getRequestParam(paramName : string, lookIn : number, def : string): Promise<string>
Remarks
Use this method to retrieve secondary or custom request parameters not available via the Request object properties.
LookIn is a bit mask that specifies where to look: 1 in query, 2 in headers, 4 in the request body. Combine them as required. If no parameter with the requested name is found, the value of Def is returned.
CryptoServer.getResponseParam Method
Looks up for a parameter in various response locations.
Syntax
async cryptoserver.getResponseParam(paramName : string, lookIn : number, def : string): Promise<string>
Remarks
Use this method to retrieve secondary or custom request parameters not available via the Response object properties.
LookIn is a bit mask that specifies where to look: 1 in query, 2 in headers, 4 in the response body. Combine them as required. If no parameter with the requested name is found, the value of Def is returned.
CryptoServer.openWebRequest Method
Opens a REST request and populates it in the Request property.
Syntax
async cryptoserver.openWebRequest(verb : string, url : string, headers : string, body : string, bodyLen : number): Promise<void>
Remarks
Use this method to process a REST request and populate its parameters in the Request property.
CryptoServer.openWebResponse Method
Opens a REST response and populates it in the Response property.
Syntax
async cryptoserver.openWebResponse(statusCode : number, reasonPhrase : string, headers : string, body : string, bodyLen : number, operation : number): Promise<void>
Remarks
Use this method to process a REST response and populate its parameters in the Response property.
CryptoServer.reset Method
Clear all list.
Syntax
async cryptoserver.reset(): Promise<void>
Remarks
Use this method to clear all list (objects, keys, mechanisms).
CryptoServer.setRequestParam Method
Sets up a request parameter in the designated location.
Syntax
async cryptoserver.setRequestParam(paramName : string, paramValue : string, location : number): Promise<void>
Remarks
Use this method to set a secondary or custom request parameter not available via the Request object properties.
Location specifies what part of the request to use for the parameter: 1 in query, 2 in headers, 4 in the request body.
CryptoServer.setResponseParam Method
Sets up a response parameter in the designated location.
Syntax
async cryptoserver.setResponseParam(paramName : string, paramValue : string, location : number): Promise<void>
Remarks
Use this method to set a secondary or custom response parameter not available via the Response object properties.
Location specifies what part of the request to use for the parameter: 1 in query, 2 in headers, 4 in the response body.
CryptoServer.Error Event
Information about errors during data delivery.
Syntax
cryptoserver.on('Error', listener: (e: {readonly errorCode: number, readonly description: string}) => void )
Remarks
The Error event is fired in case of exceptional conditions during message processing.
ErrorCode contains an error code and Description contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.
CryptoKey Type
This container represents a cryptographic key.
Remarks
This type is a universal placeholder for cryptographic keys.
Fields
The length of the key in bits.
Returns True if the key can be used for decryption.
Returns True if the key can be used for key derivation.
Returns True if the key can be used for encryption.
Returns True if the key can be used for hashing/MACing.
Returns True if the key can be used for signing.
Returns True if the key can be used for enveloping signing.
Returns True if the key can be used for key unwrapping.
Returns True if the key can be used for verifying signatures.
Returns True if the key can be used for verifying enveloping signatures.
Returns True if the key can be used for key wrapping.
A collection of information about the key capabilities TBD: discuss type and options. The following capabilities are offered by PKCS#11: "local", "trusted", "sensitive", "always sensitive", "never extractable", "always authenticate", "modifiable", plus we need to support custom parameters (e.g. Key Checksum)
The description, or label, of the object.
Enables or disables this key for use in encryption or signing operation.
Returns True if the key is exportable (can be serialized into an array of bytes), and False otherwise.
Contains the fingerprint (a hash imprint) of this key.
Contains an associated alias (friendly name) of the key. PKCS#11 equivalent: Label.
The name of the group associated with this object. Groups allow to bind together multiple objects logically connected with each other, such as certificates and their keys.
Provides access to a storage-specific key identifier. Key identifiers are used by cryptographicproviders to refer to a particular key and/or distinguish between different keys. They aretypically unique within a storage, but there is no guarantee that a particular cryptoproviderwill conform to that (or will assign any key IDs at all).
The initialization vector (IV) of a symmetric key. This is normally a public part of a symmetric key, the idea of which is to introduce randomness to the encrypted dataand/or serve as a first block in chaining ciphers.
The type of the key contained in the object.
Use this property to establish the key type.
The algorithm of the cryptographic key. A cryptokey object may hold either symmetric, MAC, or public key.Public key algorithms: RSA, ECDSA, Elgamal, DH.
The parameters of the key algorithm, such as Curve for ECDSA keys or domain parameters for DH keys.
A nonce value associated with a key. It is similar to IV, but its only purpose is to introduce randomness.
Returns True if the object is private, and False otherwise.
Returns the origin (the Storage ID) of this key.
Returns True if the object is persistent in the store.
Returns a collection of object properties as a comma separated name=value list.
Returns True if the object is readonly.
Returns True if the object is sensitive, and False otherwise.
The size of the object in bytes
Returns the key subject. This is a cryptoprovider-dependent value,which normally aims to provide some user-friendly insight into thekey owner.
TBD
Returns True if this key is valid. The term Valid highly depends onthe kind of the key being stored. A symmetric key is considered validif its length fits the algorithm being set. The validity of anRSA key also ensures that the RSA key elements (primes, exponents,and modulus) are consistent.
The time point at which the key becomes valid, in UTC.
The time point at which the key expires, in UTC.
Constructors
public CryptoKey();
Creates an empty crypto key object.
CryptoMechanism Type
This container represents a cryptographic mechanism information.
Remarks
This type is a universal placeholder for cryptographic mechanisms.
Fields
A comma-separated list of aliases of the mechanism. These may be environment-specific or reflect the naming of the mechanism in otherstandards, such as OIDs (1.2.840.113549.1.1.11) or third-party numeric constants.
Returns True if the key can be used for decryption.
Returns True if the key can be used for key derivation.
Returns True if the key can be used for encryption.
Returns True if the keystore can generate keys using the mechanism.
Returns True if the key can be used for hashing/MACing.
Returns True if the mechanism can be used for generating pseudorandom numbers.
Returns True if the key can be used for signing.
Returns True if the key can be used for enveloping signing.
Returns True if the key can be used for key unwrapping.
Returns True if the key can be used for verifying signatures.
Returns True if the key can be used for verifying enveloping signatures.
Returns True if the key can be used for key wrapping.
The maximal supported length of the key in bits.
The official name of the mechanism, such as sha256WithRSAEncryption.
The minimal supported length of the key in bits.
A collection of custom mechanism properties as a collection of comma-separated name=value pairs.
Constructors
public CryptoMechanism();
Creates an empty crypto mechanism object.
CryptoObject Type
This container represents a cryptographic object.
Remarks
This type is a universal placeholder for cryptographic objects that are not keys: certificates, data objects, and similar.
Fields
The description, or label, of the object.
Enables or disables this key for use in encryption or signing operation.
Returns True if the object is exportable (can be serialized into an array of bytes), and False otherwise.
Contains the fingerprint (a hash imprint) of this object.
Contains an associated alias (friendly name) of the object. PKCS#11 equivalent: Label.
The name of the group associated with this object. Groups allow to bind together multiple objects logically connected with each other, such as certificates and their keys.
Provides access to a storage-specific object identifier.
Returns the object issuer. This is a cryptoprovider-dependent value,which normally aims to provide some user-friendly insight into thekey owner.
Indicates the purposes of the object. For certificate object, this corresponds to the elements contained in the Key Usage and Extended Key Usage extensions.
Returns True if the object is private, and False otherwise.
The type of the key contained in the object.
Use this property to establish the object type.
Returns the origin (the Storage ID) of this object.
Returns True if the object is persistent in the store.
Returns a collection of object properties as a comma separated name=value list.
Returns True if the object is readonly.
Returns True if the object is sensitive, and False otherwise.
Returns the certificate's serial number.
The size of the object in bytes
Returns the object subject. This is a cryptoprovider-dependent value,which normally aims to provide some user-friendly insight into thekey owner.
TBD
The time point at which the object becomes valid, in UTC.
The time point at which the object expires, in UTC.
Constructors
public CryptoObject();
Creates an empty crypto object.
CryptoRequest Type
A container for the PKI Proxy request.
Remarks
The class represents an PKI Proxy request, such as list objects or sign.
Fields
Contains the authentication token supplied with the request. The contents of the authentication tokenis opaque to the server SDK components and are processed externally. For that reason the authenticationscheme should incorporate all the details necessary to validate the tokens into them.
The request body, as provided..
The generated request body as a byte array.
Contains additional data assumed by the operation, for example the plaintext accompanying the detached signature (which in this case is provided in ).
The length of pseudorandom data block to return. The service may impose length restrictions.
List filter string. This is applicable to List Objects requests.
The request format (json, plain, or other)
The HTTP headers supplied with the request..
The data to be processed by the operation, such as plaintext to be encrypted or ciphertext to be decrypted.
The ID of the key object to be used for the operation.
The maximum number of elements (objects) to return with the response, or the maximum length of the data requested (e.g. from a random generator).
The name of the mechanism to use for the operation.
The list of mechanism parameters in comma-separated name=value form.
The ID of the object involved in the operation (e.g. updated or retrieved)
The PKI Proxy protocol operation.
Use this property to check or adjust the keystore request operation.
The list of operation parameters in comma-separated name=value form. One example of such parameter is the signature type (detached, enveloping, or enveloped)
Contains the raw signature over the request.
Indicates whether the request is signed.
Indicates whether the request signature is valid.
The requested response format (json, plain, or other)
The ID of the source object that is to be copied or used for other purpose.
The request URL.
The HTTP verb.
Constructors
public CryptoRequest();
Creates an empty request object.
CryptoResponse Type
A container for the PKI Proxy response.
Remarks
The class represents an PKI Proxy response, such as the object list or the signing result..
Fields
The generated response body.
The generated response body as a byte array.
The custom HTTP headers to be added to the response.
The generated HTTP headers to be supplied with the response.
The HTTP reason phrase to return.
The HTTP status code to return.
The PKI Proxy protocol operation.
Use this property to check or adjust the keystore request operation.
The logical result of an operation that is capable of returning it, such as signature verification. Note that this is different to HttpStatusCode (which conducts the REST command status and is normally generated automatically) and StatusCode (which indicates the overall outcome of the command andis typically used to convey exceptional situations or errors happening outside of the operation flow). OperationResult contains the logical result of an operation that, due to its nature, must return a value.One example of such operation is Verify. This operation must return the verification status. Note that even a bad verification status (invalid signature) does not imply failure of the operation itself,so StatusCode can still be set to 0 and HttpStatusCode to 200.Supported values:0 - SUCCESS1 - FAILURE
The service-local operation result comment.
The data representing the operation result, such as ciphertext, decrypted plaintext, or signature.
Use this property to provide the response content in non-interpreted form. Use to supply the content type.
Use this property to provide the raw response content type. If this property is set, the is used as the response content (be it set or not). If this property is not set but is, the content type is generated automatically basing on the processed operation expectations. If neither this property nor are set - which will be the case for the majority of uses - the response body is generated automaticallybasing on the data provided to the Response object properties.
The unique ID assigned to the processed request.
Contains the raw signature over the response.
Indicates whether the response is signed.
Indicates whether the response signature is valid.
Indicates whether the response is signed.
The description of the service.
The identifier of the service.
A collection of secondary or custom properties as a comma separated name=value list.
The services of the service.
The name of the service vendor.
The version identifier of the service. No specific format assumed.
The service status code to return. This is different to and contains service-local operation result code. The code of 0 indicates successful processing.
The service-local operation status message.
The listing continuation token to be returned. Set it if the returned object list is incomplete..
The trace (processing log or debug info) to include with the response.
Constructors
public CryptoResponse();
Creates an empty response object.