This page gives a short introduction on the SkyTrust protocol, which is based on JSON messages that are consumed by a REST endpoint on the server. The information here does not represent a detailed specification of the protocol, but shows simple examples to highlight the basic functionality.
Authentication Process
Whenever a command with an invalid/not-set session ID is sent to the server, an authentication challenge is sent form the server to the user. This challenge describes the authentication method and optionally includes parameters (e.g. URLs in case of oAuth). The following example shows a simple user name/passwort authentication process.
Request (sent by the server as answer to an unauthenticated SkyTrust command sent by the client):
{
"header" : {
"protocolVersion" : "0.1",
"commandId" : "89eab553-5be0-43d7-beb2-66ad54cde44c",
"sessionId" : "",
"path" : [ ]
},
"payload" : {
"type" : "authChallenge",
"authType" : {
"type" : "UserNamePasswordAuthType"
}
}
}
Response (by client):
{
"header" : {
"protocolVersion" : "0.1",
"commandId" : "89eab553-5be0-43d7-beb2-66ad54cde44c",
"sessionId" : "",
"path" : [ ]
},
"payload" : {
"command" : "authenticate",
"type" : "authChallengeReply",
"authInfo" : {
"type" : "UserNamePasswordAuthInfo",
"userName" : "Peter-Franz-Teufl",
"passWord" : "secure passcode"
}
}
}
"header" : {
"protocolVersion" : "0.1",
"commandId" : "89eab553-5be0-43d7-beb2-66ad54cde44c",
"sessionId" : "",
"path" : [ ]
},
"payload" : {
"type" : "authChallenge",
"authType" : {
"type" : "UserNamePasswordAuthType"
}
}
}
Response (by client):
{
"header" : {
"protocolVersion" : "0.1",
"commandId" : "89eab553-5be0-43d7-beb2-66ad54cde44c",
"sessionId" : "",
"path" : [ ]
},
"payload" : {
"command" : "authenticate",
"type" : "authChallengeReply",
"authInfo" : {
"type" : "UserNamePasswordAuthInfo",
"userName" : "Peter-Franz-Teufl",
"passWord" : "secure passcode"
}
}
}
Algorithm IDs
SkyTrust uses W3C Crypto API algorithm IDs. More information will be added soon.
SkyTrust Command - DiscoverKeys
The "discoverKeys" command queries a SkyTrust server for the available keys. The "representation" parameters indicates whether only key handles (identifiers) or the encoded certificates should be returned by the server.
In this case, only the key handles are returned. These handles are unique identifiers that are used by the client application to select the desired key for the respective cryptographic operation.
Request:
{
"header" : {
"protocolVersion" : "0.1",
"commandId" : "",
"sessionId" : "504a3fa0-8880-498f-bee5-42d3962c5477",
"path" : [ ]
},
"payload" : {
"command" : "discoverKeys",
"type" : "discoverKeysRequest",
"representation" : "handle"
}
}
Response:
{
"header" : {
"protocolVersion" : "0.1",
"commandId" : "",
"sessionId" : "504a3fa0-8880-498f-bee5-42d3962c5477",
"path" : [ ]
},
"payload" : {
"type" : "discoverKeysResponse",
"key" : [ {
"id" : "email-encryption-key",
"subId" : "13",
"representation" : "handle",
"metaInformation" : [ {
"genericMetaInformation" : "user"
} ]
}, {
"id" : "email-sig-key",
"subId" : "9",
"representation" : "handle",
"metaInformation" : [ {
"genericMetaInformation" : "user"
} ]
}, {
"id" : "ssl-key",
"subId" : "11",
"representation" : "handle",
"metaInformation" : [ {
"genericMetaInformation" : "machine"
} ]
} ]
}
}
Here, the parameter "representation" is set to "certificate", which indicates that the user's certificate should be returned instead of the key identifiers. Obviously, the private key cannot be exported/requested.
Request:
{
"header" : {
"protocolVersion" : "0.1",
"commandId" : "",
"sessionId" : "504a3fa0-8880-498f-bee5-42d3962c5477",
"path" : [ ]
},
"payload" : {
"command" : "discoverKeys",
"type" : "discoverKeysRequest",
"representation" : "certificate"
}
}
Response:
{"header" : {
"protocolVersion" : "0.1",
"commandId" : "",
"sessionId" : "504a3fa0-8880-498f-bee5-42d3962c5477",
"path" : [ ]
},
"payload" : {
"type" : "discoverKeysResponse",
"key" : [ {
"id" : "email-sig-key",
"subId" : "9",
"representation" : "certificate",
"encodedCertificate" : "BASE64 encoded certificate, not shown here",
"metaInformation" : [ {
"genericMetaInformation" : "user"
} ]
}, {
"id" : "email-encryption-key",
"subId" : "13",
"representation" : "certificate",
"encodedCertificate" : "BASE64 encoded certificate, not shown here",
"metaInformation" : [ {
"genericMetaInformation" : "user"
} ]
}, {
"id" : "ssl-key",
"subId" : "11",
"representation" : "certificate",
"encodedCertificate" : "BASE64 encoded certificate, not shown here",
"metaInformation" : [ {
"genericMetaInformation" : "machine"
} ]
} ]
}
}
SkyTrust Commands - Sign/Decrypt
Actual signing/decrypting is carried out by selecting the appropriate "command" parameter ("sign" or "decrypt"). In addition to the command, the desired key needs to be selected in the parameter group "cryptoParams" and the specific "algorithm" must be chosen - in this case "RSAES-RAW".
Request:
{
"header" : {
"protocolVersion" : "0.1",
"commandId" : "",
"sessionId" : "504a3fa0-8880-498f-bee5-42d3962c5477",
"path" : [ ]
},
"payload" : {
"command" : “decrypt”,
"type" : "cryptoOperationRequest",
"cryptoParams" : {
"key" : {
"id" : "email-encryption-key",
"subId" : "13",
"representation" : "keyIdentifier",
"metaInformation" : [ ]
},
"algorithm" : "RSAES-RAW"
},
"load" : "ZW5jcnlwdCBtZQ=="
}
}
Response:
TBD
No comments:
Post a Comment