/Storage/CreateVaultLink

Allows the client to create a secure link to a vault item, for distribution. The client can set the number of times the link can be used, as well as an expiration time.

JSON

Request

{
	"vaultId": Required(Str(PVaultId)),
	"ttl": Optional(Int(PTtl > 0)),
	"useCount": Optional(Int(PUseCount > 0)),
	"masked": Optional(Bool(PMasked)),
	"keyId": Required(Str(PKeyId)),
	"nonce": Required(Str(PNonce)),
	"keySignature": Required(Str(PKeySignature)),
	"requestSignature": Required(Str(PRequestSignature))
}

Response (if successful)

{
	"url": Required(Str(PUrl))
}

XML

Request

<CreateVaultLink xmlns="https://waher.se/Schema/BrokerAgent.xsd"
                 vaultId=(Required(Str(PVaultId)))
                 ttl=(Optional(Int(PTtl > 0)))
                 useCount=(Optional(Int(PUseCount > 0)))
                 masked=(Optional(Bool(PMasked)))
                 keyId=(Required(Str(PKeyId)))
                 nonce=(Required(Str(PNonce)))
                 keySignature=(Required(Str(PKeySignature)))
                 requestSignature=(Required(Str(PRequestSignature))) />

Response (if successful)

<Link xmlns="https://waher.se/Schema/BrokerAgent.xsd"
      url=(Required(Str(PUrl)))/>

Input Parameters

Response Parameters

Note: Do not share links to sensitive information over insecure channels, especially not social networks or similar. To check if any middleware scans or previews the links you send, you can create a vault item without sensitive information, and create a link to it with a use count of one. Send the link over the channel, and when received, try to use the link. If the link returns an error saying the reference cannot be found, it has already been used by the middleware. Do not create links to sensitive information over such channels, incrementing the use count to two. Links should only be sent over secure channels, such as end-to-end encrypted messaging systems or server-to-server channels protected by mutual TLS (mTLS), or similar.

Calculating the Key Signature

The signature in PKeySignature is calculated as follows.

1. Concatenate the strings PUserName ":" Host ":" PLocalName ":" PNamespace ":" PKeyId 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. PLocalName and PNamespace are the local name and namespace corresponding to the algorithm used for the key.

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 followed by ":" PVaultId ":" PTtl ":" PUseCount ":" PMasked, and call it s2. If PTtl is not provided the string "0" is used instead. If PUseCount is not provided, the string "0" is used instead. If PMasked is not provided, the string "1" is used instead. If PMasked is provided, the string "1" is used if its value is true, and "0" if its value is false. 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.

var Response = await AgentAPI.Storage.CreateVaultLink(LocalName,Namespace,KeyId,KeyPassword,AccountPassword,VaultId,Ttl,UseCount,Masked);