Treatment sign

crypto/token/jwt::sign

Parameters

↳ var algorithm: string
↳ var key: Secret<string>
↳ var lifetime: u64 = 0
↳ var name: string
↳ var plain_reveal: bool = false
↳ var transmission: string = "local"

Inputs

⇥ claims: Block<string>

Outputs

↦ error: Block<string>
↦ failed: Block<void>
↦ token: Block<Secret<string>>

Signs a JSON Web Token, given as a secret.

Once claims is received, a JSON object such as {"iss": "123456"}, the token is signed with key and algorithm, and given through token:

• key: for HS256, HS384 and HS512, the secret shared with the receiver; for RS256, RS384 and RS512 (RSA), ES256 and ES384 (ECDSA with P-256 and P-384), and EdDSA (Ed25519), the private key in PEM, PKCS#8 (-----BEGIN PRIVATE KEY-----) or the RSA PRIVATE KEY and EC PRIVATE KEY forms, such as GitHub App keys.
• algorithm: one of the above, written in the token header.
• lifetime: when not 0, the token is valid for lifetime seconds from its signing: exp is set accordingly, and iat a minute before signing, for clocks running slightly ahead of the receiver’s.

The key is revealed only to sign. The token is a secret named name, kept in memory until it is dropped, whose policy is given by transmission (local, reference or value) and plain_reveal (whether the plain std/secret::reveal treatment may reveal it), as std/secret::conceal takes. Programs running longer than lifetime sign again before the token expires, as receivers refuse expired tokens.

Signing takes microseconds with HMAC and Ed25519, half a millisecond with ECDSA, and a few milliseconds with RSA, more with keys longer than 2048 bits.

If the key cannot be revealed or does not fit algorithm, algorithm is not supported, claims is not a JSON object, or transmission is not valid, failed is emitted and error contains the reason.