Package 'jose'

Title: JavaScript Object Signing and Encryption
Description: Read and write JSON Web Keys (JWK, rfc7517), generate and verify JSON Web Signatures (JWS, rfc7515), encrypt and decrypt with JSON Web Encryption (JWE, rfc7516) and encode/decode JSON Web Tokens (JWT, rfc7519) <https://datatracker.ietf.org/wg/jose/documents/>. These standards provide modern signing and encryption formats that are natively supported by browsers via the JavaScript WebCryptoAPI <https://www.w3.org/TR/webcrypto/#jose>, and used by services like OAuth 2.0, LetsEncrypt, and Github Apps.
Authors: Jeroen Ooms [aut, cre] (ORCID: <https://orcid.org/0000-0002-4035-0289>)
Maintainer: Jeroen Ooms <[email protected]>
License: MIT + file LICENSE
Version: 2.0.0
Built: 2026-11-18 19:37:58 UTC
Source: https://github.com/r-lib/jose

Help Index


Base64URL encoding

Description

The base64url_encode functions are a variant of the standard base64. They are specified in Section 5 of RFC 4648 as a URL-safe alternative. They use different symbols for the 62:nd and 63:rd alphabet character and do not include trailing == padding.

Usage

base64url_encode(bin)

base64url_decode(text)

Arguments

bin

a binary blob to encode

text

a base64url encoded string


JSON Web Encryption

Description

Encrypt or decrypt data or a JWT claim using JSON Web Encryption (JWE) in compact serialization, see RFC7516. The content is encrypted with a random content encryption key (CEK), which is in turn encrypted for the recipient using the key management algorithm alg.

Usage

jwe_encrypt(payload, key, alg = NULL, enc = "A256GCM", header = NULL)

jwe_decrypt(jwe, key)

jwt_encrypt(
  claim = jwt_claim(),
  key,
  alg = NULL,
  enc = "A256GCM",
  header = NULL
)

jwt_decrypt(jwt, key)

Arguments

payload

string or raw vector with the data to encrypt

key

for encryption: path or object with the RSA or EC public key of the recipient, or a raw vector with a shared secret. For decryption: path or object with the RSA or EC private key, or a raw vector with the shared secret.

alg

key management algorithm, see details.

enc

content encryption algorithm, see details.

header

named list with additional parameter fields to include in the protected header, for example kid.

jwe

string containing the JWE in compact serialization

claim

a named list with fields to include in the jwt payload, see jwt_claim

jwt

string containing the encrypted JSON Web Token

Details

Supported key management algorithms (alg) are:

  • RSA-OAEP and RSA-OAEP-256: for an RSA key.

  • ECDH-ES, ECDH-ES+A128KW, ECDH-ES+A192KW and ECDH-ES+A256KW: for an EC key (P-256, P-384, or P-521).

  • A128KW, A192KW and A256KW: AES key wrap with a shared secret (raw vector) of 16, 24 or 32 bytes.

  • dir: direct encryption with a shared secret (raw vector) that has the key size of enc.

If alg is NULL, it defaults to RSA-OAEP-256 for RSA keys, ECDH-ES for EC keys, and the AES key wrap of the matching size for raw keys.

Supported content encryption algorithms (enc) are A128GCM, A192GCM, A256GCM, A128CBC-HS256, A192CBC-HS384 and A256CBC-HS512.

Value

jwe_encrypt and jwt_encrypt return a string with the JWE. jwe_decrypt returns a raw vector with the decrypted payload, and jwt_decrypt returns the decrypted claim.

Examples

# Encrypt with RSA
key <- openssl::rsa_keygen()
pubkey <- as.list(key)$pubkey
token <- jwe_encrypt("Hello world", pubkey)
rawToChar(jwe_decrypt(token, key))

# Encrypt with EC
key <- openssl::ec_keygen()
pubkey <- as.list(key)$pubkey
token <- jwe_encrypt("Hello world", pubkey, enc = "A128CBC-HS256")
rawToChar(jwe_decrypt(token, key))

# Encrypt with a shared secret
secret <- openssl::rand_bytes(32)
token <- jwe_encrypt("Hello world", secret)
rawToChar(jwe_decrypt(token, secret))

# Encrypt a JWT
claim <- jwt_claim(name = "jeroen", session = 123456)
token <- jwt_encrypt(claim, pubkey)
jwt_decrypt(token, key)

Generate claim

Description

Helper function to create a named list used as the claim of a JWT payload. See https://datatracker.ietf.org/doc/html/rfc7519 for details.

Usage

jwt_claim(
  iss = NULL,
  sub = NULL,
  aud = NULL,
  exp = NULL,
  nbf = NULL,
  iat = Sys.time(),
  jti = NULL,
  ...
)

Arguments

iss

(Issuer) Claim, should be rfc7519 'StringOrURI' value

sub

(Subject) Claim, should be rfc7519 'StringOrURI' value

aud

(Audience) Claim, should contain one or rfc7519 'StringOrURI' values

exp

(Expiration Time) Claim, should be rfc7519 'NumericDate' value; R POSIXct values are automatically coerced.

nbf

(Not Before) Claim, should be rfc7519 'NumericDate' value; R POSIXct values are automatically coerced.

iat

(Issued At) Claim, should be rfc7519 'NumericDate' value; R POSIXct values are automatically coerced.

jti

(JWT ID) Claim, optional unique identifier for the JWT

...

additional custom claims to include


JSON Web Token

Description

Sign or verify a JSON web token. The jwt_encode_hmac, jwt_encode_rsa, and jwt_encode_ec default to HS256, RS256, and ES256 respectively. See jwt.io or RFC7519 for more details.

Usage

jwt_encode_hmac(claim = jwt_claim(), secret, size = 256, header = NULL)

jwt_decode_hmac(jwt, secret)

jwt_encode_sig(claim = jwt_claim(), key, size = 256, header = NULL)

jwt_decode_sig(jwt, pubkey)

jwt_split(jwt)

Arguments

claim

a named list with fields to include in the jwt payload

secret

string or raw vector with a secret passphrase

size

bitsize of sha2 signature, i.e. sha256, sha384 or sha512. Only for HMAC/RSA, not applicable for ECDSA keys.

header

named list with additional parameter fields to include in the jwt header as defined in rfc7515 section 9.1.2

jwt

string containing the JSON Web Token (JWT)

key

path or object with RSA or EC private key, see openssl::read_key.

pubkey

path or object with RSA or EC public key, see openssl::read_pubkey.

Examples

# HMAC signing
mysecret <- "This is super secret"
token <- jwt_claim(name = "jeroen", session = 123456)
sig <- jwt_encode_hmac(token, mysecret)
jwt_decode_hmac(sig, mysecret)

# RSA encoding
mykey <- openssl::rsa_keygen()
pubkey <- as.list(mykey)$pubkey
sig <- jwt_encode_sig(token, mykey)
jwt_decode_sig(sig, pubkey)

# Same with EC
mykey <- openssl::ec_keygen()
pubkey <- as.list(mykey)$pubkey
sig <- jwt_encode_sig(token, mykey)
jwt_decode_sig(sig, pubkey)

# Get elements of the key
mysecret <- "This is super secret"
token <- jwt_claim(name = "jeroen", session = 123456)
jwt <- jwt_encode_hmac(token, mysecret)
jwt_split(jwt)

JSON web-keys

Description

Read and write RSA, ECDSA or AES keys as JSON web keys.

Usage

read_jwk(file)

write_jwk(x, path = NULL)

Arguments

file

path to file with key data or literal json string

x

an RSA or EC key or pubkey file

path

file path to write output

Examples

# generate an ecdsa key
library(openssl)
key <- ec_keygen("P-521")
write_jwk(key)
write_jwk(as.list(key)$pubkey)

# Same for RSA
key <- rsa_keygen()
write_jwk(key)
write_jwk(as.list(key)$pubkey)