Appendix A: Secure Keystore¶

The Secure Keystore (SKS) is an Authenticated Identity Management Service tool used to obtain and restrict the use of keys for signing encrypted identity information, as defined in RFC 8224.

On the primary NIU, the PCS installation package will include the SKS RPM.

This provided SKS is an example implementation of the described API and can be used to provide the necessary cryptographic operations for secure identity assurance of originators of SIP requests.

The SKS runs on the Jetty Server. For information about further configuration of the Jetty server, see the Oracle documentation titled Jetty Configuration.

This appendix describes how to use the provided SKS and includes a reference for replacing the provided SKS with your own.

SKS Configuration¶

The following steps are required to configure the SKS for basic functionality.

Edit the /var/opt/sks-home/config.properties file.

In this text file, set the certificateStorePath property value to point to the location of your trusted certificates using the following syntax:

certificateStorePath=/var/opt/sks-home/<examplepath>/<filename>.p12

Also in this file, set the identifierBaseURL property value to define the location of the certificate detail files using the following syntax:

identifierBaseURL=/var/opt/sks-home/<identifierpath>/

These files should have a filename of <identifier>.json, where <identifier> matches the identifier for the certificate in the keystore. The file itself must contain a valid JSON body.

An example file may look like the following:

{
        "name": "TestName2",
        "notBefore": "SomeBeforeDate2",
        "notAfter": "SomeAfterDate2",
        "spc": "Spc2",
        "info": "URLTOCERT",
        "alg": "ES256",
        "surplusData": "this is a string for surplus data"
}

The info and alg parameters are required for the proper functioning of the SKS. The info parameter contains the URL of the public certificate that matches the private key certificate used to sign traffic. The alg parameter represents the algorithm used to sign traffic and must be ES256. All other parameters are optional.

Edit the /usr/sipxpress/ps_master_config.xml file.

In this file, add the following SKS process to the ps-init section.

<process name="integrated-sks"
        stop-script="stop-sks" />

Run the following script to initialize the SKS server to use HTTPS.

/usr/sipxpress/bin/init-sks

Cryptographic Configuration¶

Signing Keystore¶

The SKS uses a Java keystore in the PKCS12 format. For more information, see the Oracle documentation titled Creating a KeyStore in PKCS12 Format.

Note

The SKS requires the password for the keystore and the key to be the same. When prompted, use the password “password”.

Generate an Elliptic Curve (EC) key. As specified in RFC 8224, ECDSA256 (es256) is used to create our JWS signature in the SKS.

openssl ecparam -name prime256v1 -genkey -noout -out <identifier_name>.key.pem
Generate a certificate for the EC key.

openssl req -new -x509 -key <identifier_name>.key.pem -out <identifier_name>.pem -days 900000 -subj "/C=US/ST=New York/L=Rochester/O=Evolve/CN=SKS"
Export the certificate and key to a .p12 file.

openssl pkcs12 -export -inkey <identifier_name>.key.pem -in <identifier_name>.pem -name <identifier_name> -out <dentifier_name>.p12
Import the .p12 file into the shared keystore used by the SKS.

keytool -importkeystore -srckeystore <identifier_name>.p12 -destkeystore <SharedKeystore>.p12 -deststoretype pkcs12 -alias <identifier_name>

SSL Keystore¶

Follow this procedure to provide the SKS with a valid SSL certificate.

Combine the key and certificate into a pkcs12 file.

openssl pkcs12 -inkey example.key -in -example.crt -export -out example.p12

If you have a chain of certificates, run the following command instead:

cat example.crt intermediate.crt [intermediate2.crt] ... rootCA.crt > cert-chain openssl pkcs12 -export -inkey example.key -in cert-chain -out example.p12

Note

If prompted, use the password “keypwd”.

Import the keystore in the /var/opt/sks-home/etc/ file.

keytool -importkeystore -srckeystore example.p12 -srcstoretype PKCS12 -destkeystore keystore

Note

If prompted, use the password “storepwd”.

Non-200 Error Messages¶

For any non-200 response, the SKS may return additional error information for logging/diagnostics. 500 vs. 501 in this scenario.

For any such response, the response body will be JSON and will provide any of the following properties:

{
        "messageId": "...",
        "text": "...",
        "variables": [ "...", ... ],
        "url": "..."
}

messageId: A succinct code that uniquely identifies the error.

text: A human-readable error description.

variables: If present, this may contain replacement markers %1, %2, … to substitute details into a generic description.

url: A link to a more detailed description of the error or a support page.

The following is a list of possible errors.

UnknownInternalServiceError() {
        "messageId": "SVC5000",
        "text": "Error: Internal server error.  See SKS log.",
        "url": "imsworkx.com"
}

UnknownInternalPolicyError() {
        "messageId": "POL5000",
        "text": "Error: Internal server error.  See SKS log.",
        "url": "imsworkx.com"
}

UnknownInternalJKSError() {
        "messageId": "SVC5001",
        "text": "Error: Internal server error in cryptographic keystore. See SKS log.",
        "url": "imsworkx.com"
}

InternalKeyProvisionError() {
        "messageId": "POL4049",
        "text": "Error: No provisioned key for the specified identifier was found.",
        "url": "imsworkx.com"
}

MalformedMetadataJSONError(String identifier) {
        “messageId”: "POL5013",
        “text”: "Error: Metadata for %1 is not valid JSON.",
        “variables”: "[ \""+identifier+"\" ]"
}

IdentifierMetaDataNotFound(String identifier) {
        “messageId”: "SVC4042",
        “text”: "Error: Could not locate metadata file for identifier %1",
        "variables": "[ \""+identifier+"\" ]",
        "url": "imsworkx.com"
}

SKSConfigIOException () {
        “messageId”: "SVC5020",
        “text”: "Error: Internal server error in reading SKS configuration file.",
        “url”: "imsworkx.com"
}

InfoURLNotGettable (String identifier) {
        “messageId”: "SVC5014",
        “text”: "Error: Internal server error in retrieving info URL for identifier %1.",
        “variables”: "[ \""+identifier+"\" ]",
        “url”: "imsworkx.com"
}

InfoURLNotFound(String identifier) {
        “messageId”: "5015",
        “text”: "Error: No URL in metadata for identifier %1",
        “variables”: "[ \""+identifier+"\" ]",
        “url”: "imsworkx.com"
}

SKSConfigNotFound() {
        “messageId”: " SVC5004",
        “text”: "Error: Could not locate SKS configuration file. ",
        “url”: "imsworkx.com"
}

Base64URLParseError(String token) {
        “messageId”: " 4225",
        “text”: "Error: Token %1 cannot be parsed as a Base64URL. ",
        “variables”: "[ \""+token+"\" ]",
        “url”: "https://tools.ietf.org/html/rfc7515#section-5.1"
}

Base64URLHeaderError(String header) {
        “messageId”: " 4226",
        “text”: "Error: Encoded JWT header %1 incorrectly encoded.",
        “variables”: "[ \""+header+"\" ]",
        “url”: "https://tools.ietf.org/html/rfc7515#section-5.1"
}

Base64URLClaimsSetError (String claims) {
        “messageId”: " 4227",
        “text”: "Error: Encoded JWT claims set %1 incorrectly encoded.",
        “variables”: "[ \""+claims+"\" ]",
        “url”: "https://tools.ietf.org/html/rfc7515#section-5.1"
}

MalformedJSONError(String body) {
        “messageId”: " POL4000",
        “text”: "Error: Could not parse malformed JSON from %1.",
        “variables”: "[ \""+body+"\" ]",
        “url”: "imsworkx.com"
}

JSONTypeError() {
        “messageId”: "POL4222",
        “text”: "Error: Incorrect JSON types in signing request.",
        “url”: "imsworkx.com"
}

Secure Keystore API¶

This is an HTTPS API used to obtain a fixed (secret) API key/token to authenticate.

The keystore will have the following properties:

A base URL for the SKS (for example, https://api.provider.com/sks/v1/)
The API key for identifying authenticated sources
Any trust anchor information

Payloads and responses are JSON (Content-Type: application/json) unless otherwise noted.

The API key is provided to the SKS in the Authentication header as Basic authentication scheme. It is not required that a user name and password be encoded in the key. If the API key is not supplied or not valid, the SKS will return a 403 Forbidden response.

Signing Request¶

The only required API call is to support the signing of a JSON Web Signature (JWS) Signing Input based on an SKS-specific identifier that names the key to use for signing.

The signing request is formed as an HTTP POST to $baseurl/signing_request with a JSON body containing:

{
        "input": "...",
        "identifier": "..."
}

input: The input to the digital signature or JWS Signing Input, as defined in RFC 7515. Its value is ASCII(BASE64URL(UTF8(JWS Protected Header)) || ‘.’ || BASE64URL(JWS Payload)) || ‘.’ ||.

identifier: A unique string that represents the key identifier provisioned in PCS. Limit of 64 characters, and must contain only ASCII characters [A-Za-z0-9_-].

The successful operation of the SKS will return a JSON body in the response with an HTTP status of 200 Ok:

{
        "signature": "...",
        "alg": "...",
        "info": "..."
}

signature: The computed JWS Signature, BASE64URL encoded, as defined in RFC 7515.

alg: Identifies the cryptographic algorithm used to sign the payload and secure the JWS. This is a case-sensitive ASCII string containing a StringOrURI value.

info: The URL, included as the info parameter, which identifies the certificate associated with the key used for the signature, as defined in RFC 8224.

Note

The info URL is populated in the input in the “x5u” Header Parameter. If the returned info URL is different than expected, the request will be considered failed as if the SKS had refused to sign the request with a 4xx-class error.

If the SKS is unable to perform a signature due to an internal fault, it is expected to return a 5xx response. All such responses will be treated as failures of the SKS itself and not as a problem with the specific request.

If the SKS is unwilling to perform a signature for another reason, such as local/operator policy or errors that do not indicate failure of the SKS, any other 4xx response may be returned. All such responses will be treated as an issue with the specific request.

Identifier Listing¶

To facilitate provisioning, the SKS is expected to expose the set of available identifiers that are provisioned.

The identifier listing request is formed as an HTTP GET to $baseurl/identifier with no body.

The successful operation of the SKS will return a 200 response with a JSON body containing:

[
        {"identifier": "...", "info": "..."},
        ...
]

This is a single JSON array of objects with two properties. The first property is the identifiers for which the SKS is currently willing to accept signing requests from. The second property is the corresponding info URL that points to the certificate needed for validation.

If this endpoint is unable to be accessed for any reason, the cached data will either continue to be used with an indication in the web-based user interface that the data is stale or revert to a simple entry field that does not provide options if no cache is available.

Identifier Metadata¶

The SKS can optionally provide metadata about the key identifiers that it supports.

This endpoint is expected to enable caching of information as well.

The identifier metadata request is formed as an HTTP GET to $baseurl/identifier/$identifier with no body.

Here, $identifier is the identifier for which metadata is being retrieved.

The successful operation of the SKS will return a 200 reponse with a JSON body containing the any of following properties that are known:

{
        "name": "...",
        "notBefore": "...",
        "notAfter": "...",
        "spc": "...",
        "info": "...",
        "alg": "...",
        ...
}

It is expected that an SKS which cannot return any customized metadata for the identifier can always return the alg and info properties, as these are necessary for the signing request to function.

name: A string that is syntactically unconstrained. This is used in place of the identifier in the web-based user interface.

notBefore, notAfter: Date information from the associated certificate about the validity. These are to be returned in ISO8601 format YYYY-MM-DDTHH:MM:SSZ. It is expected that the notAfter value correlates with any Expires header to enable caching.

spc: A string that represents the Service Provider Code from the associated certificate’s TN Authorization List extension (as defined in RFC 8226), if one is known to the SKS and present.