Table of Contents
  1. JSON
  2. XML
  3. Input Parameters
  4. Response Parameters
  5. Calculating the Key Signature
  6. Calculating the Request Signature
  7. Javascript Library

/Crypto/CreateKey

Allows the client to create a cryptographic key on the server, and protect it with a password. The key will be stored encrypted on the server, protected with the key password. The creation of a key will require the user to provide the account password again.

JSON

Request
{
	"localName": Required(Str(PLocalName)),
	"namespace": Required(Str(PNamespace)),
	"id": Required(Str(PId)),
	"nonce": Required(Str(PNonce)),
	"keySignature": Required(Str(PKeySignature)),
	"requestSignature": Required(Str(PRequestSignature))
}
Response (if successful)
{
	"created": Required(DateTime(PCreated)),
	"updated": Required(DateTime(PUpdated))
}

XML

Request
<CreateKey xmlns="https://waher.se/Schema/BrokerAgent.xsd"
           localName=(Required(Str(PLocalName)))
           namespace=(Required(Str(PNamespace)))
           id=(Required(Str(PId)))
           nonce=(Required(Str(PNonce)))
           keySignature=(Required(Str(PKeySignature)))
           requestSignature=(Required(Str(PRequestSignature))) />
Response (if successful)
<Stored xmlns="https://waher.se/Schema/BrokerAgent.xsd"
		created=(Required(DateTime(PCreated)))
		updated=(Required(DateTime(PUpdated)))/>

Input Parameters

Parameter Description
PLocalName Local Name of the algorithm to use for the new key.
PNamespace Namespace, defining the algorithm.
PId ID of the key. The ID must be unique, for the current account. Different accounts can have keys with the same ID.
PNonce A unique random string, at least 32 characters long, with sufficient entropy to not be reused again. If reused, an error will be returned.
PKeySignature Cryptographic signature of the key ID, using the key password. (Password is not stored with the key, instead this signature will be the base for the cryptographic key used to encrypt the key on the server.
PRequestSignature Cryptographic signature of the requesut, using the account password.

Response Parameters

Parameter Description
PCreated When the information record was first created.
PUpdated When the information record was last updated.

Calculating the Key Signature

The signature in PKeySignature is calculated as follows.

  1. Concatenate the strings PUserName ":" Host ":" PLocalName ":" PNamespace ":" PId and call it s1, where Host is the host/domain name of the server. It is taken from the HTTP Host request header, so it must be the same as is used in the URL of the request. PUserName is the name of the account, used when creating the current account or logging in to the current account.

  2. UTF-8 encode the secret corresponding to the key, and call it Key1.

  3. UTF-8 encode the string s1, and call it Data1.

  4. Calculate the HMAC-SHA256 signature using Key1 and Data1, and call it H1.

  5. Base64-encode H1. The result is the key signature of the request.

Calculating the Request Signature

The signature in PRequestSignature is calculated as follows.

  1. Concatenate the strings s1 ":" PKeySignature ":" PNonce and call it s2. s1 is the intermediate result of computing the key signature in the previous step.

  2. UTF-8 encode the secret corresponding to the account, and call it Key2.

  3. UTF-8 encode the string s2, and call it Data2.

  4. Calculate the HMAC-SHA256 signature using Key2 and Data2, and call it H2.

  5. Base64-encode H2. The result is the signature of the request.

Javascript Library

Use the following asynchronous method in the Javascript Library, to call this resource. It computes the signatures according to the above specification.

var Response = await AgentAPI.Crypto.CreateKey(LocalName,Namespace,Id,KeyPassword,AccountPassword);
Test






Request Payload:

Response Payload: