solarnetwork-api-core
    Preparing search index...

    Class HttpMessageSignatureBuilder

    A builder for RFC 9421 HTTP message signatures on a SolarNetwork API request.

    This is the RFC 9421 counterpart to Net.AuthorizationV2Builder, and uses the same security token credentials. A request is signed by covering a set of message components; SolarNetwork requires a minimum set of them, which coverRequiredComponents() configures:

    const builder = new HttpMessageSignatureBuilder("my-token")
        .method(HttpMethod.GET)
        .url("https://data.solarnetwork.net/solarquery/api/v1/sec/datum/stream/datum?nodeId=123")
        .coverRequiredComponents();

    headers.set("Signature-Input", builder.signatureInputHeaderValue());
    headers.set("Signature", builder.signatureHeaderValue("my-token-secret"));

    By default the signing key is derived from the token secret and the signing date, which works like the SNWS2 signing key in that it expires, and so can be handed to a signer without disclosing the secret. To sign with the token secret itself instead, which is what any RFC 9421 implementation can do with only the token ID and secret:

    builder.derivedSigningKey(false);

    Post requests

    RFC 9421 has no notion of message content: a request body is covered by covering a Content-Digest field that digests it. Use contentDigest() to compute that field, and pass the same value on the request.

    const body = JSON.stringify({foo: "bar"});
    const builder = new HttpMessageSignatureBuilder("my-token")
        .method(HttpMethod.POST)
        .url("https://data.solarnetwork.net/solaruser/api/v1/sec/...")
        .contentType("application/json")
        .contentDigest(body)
        .coverRequiredComponents();
    Index
    constructor
    httpHeaders tokenId
    coveredComponents keyId
    algorithm computeSigningKey contentDigest contentDigestHeaderValue contentType covered coverRequiredComponents date derivedSigningKey expires header label method nonce reset sign signatureBase signatureHeaderValue signatureHeaderValueWithKey signatureInputHeaderValue signatureParams signWithKey tag url
    httpHeaders: HttpHeaders

    The signed HTTP headers.

    tokenId: string

    The SolarNet auth token value.

    • Set the signature algorithm.

      The alg signature parameter is optional in RFC 9421, and is omitted unless set here.

      Parameters

      • Optionalval: HmacSha256

        the algorithm, or undefined to omit the parameter

      Returns this

      this object

    • Compute the signing key from a token secret.

      When a derived signing key is configured this is HMAC(HMAC("SNWS3"+secret, "YYYYMMDD"), "snws3_request"), which expires like an SNWS2 signing key does. Otherwise it is the token secret itself.

      Parameters

      • tokenSecret: string

        the token secret

      Returns string | WordArray

      the signing key

    • Set the HTTP Content-Type header.

      Parameters

      • val: string

        the content type to use

      Returns this

      this object

    • Cover the minimum set of components SolarNetwork requires.

      That is the request method, authority, and path, along with the query when the request has one, the content type and content digest when the request has content, and every X-SN-* header configured on this builder.

      Returns this

      this object

    • Set whether to derive the signing key from the token secret and the signing date.

      This is enabled by default, so that a token secret need not be handed to whatever signs the request.

      Parameters

      • val: boolean

        true to derive a signing key, false to use the token secret itself

      Returns this

      this object

    • Set the signature expiration date.

      Parameters

      • Optionalval: Date

        the expiration date, or undefined for none

      Returns this

      this object

    • Set an HTTP header value.

      Parameters

      • headerName: string

        the header name

      • headerValue: string

        the header value

      Returns this

      this object

    • Set the signature nonce.

      Parameters

      • Optionalval: string

        the nonce, or undefined for none

      Returns this

      this object

    • Reset to default property values.

      The token ID, label, tag, algorithm, and signing key mode are preserved.

      Returns this

      this object

    • Compute the signature value, using a token secret.

      Parameters

      • tokenSecret: string

        the token secret

      Returns string

      the Base64 encoded signature value

    • Get the Signature HTTP header value, using a token secret.

      Parameters

      • tokenSecret: string

        the token secret

      Returns string

      the header value

    • Get the Signature HTTP header value, using a signing key.

      Parameters

      • signingKey: string | WordArray

        the signing key

      Returns string

      the header value

    • Compute the serialized signature parameters.

      This is the value of the @signature-params line of the signature base, and also the Signature-Input member value.

      Returns string

      the serialized signature parameters

    • Compute the signature value, using a signing key.

      Parameters

      • signingKey: string | WordArray

        the signing key

      Returns string

      the Base64 encoded signature value

    • Set the application tag.

      SolarNetwork uses this to pick the signature meant for authentication when a request carries more than one. It defaults to solarnetwork.

      Parameters

      • Optionalval: string

        the tag, or undefined for none

      Returns this

      this object

    Settings
    Member Visibility

    On This Page
    Post requests
    Constructors
    Properties
    Accessors
    Methods