Kernel 8.0 APIs Banner [skip navigation]
Office of Information & Technology (OIT) Banner

$$RSAENCR^XUSHSH: Returns RSA Encrypted Ciphertext for String Entry

Reference Type: Supported, Category: Data Security, Integration Agreement: 6189

Description

This extrinsic function returns the RSA encrypted ciphertext for a string entry. RSA is a public-key encryption system that is widely used for secure data transmission. The encryption key is public and differs from the decryption key, which is kept secret.

NOTE: This API was released with Kernel patch XU*8.0*655.

Format

$$RSAENCR^XUSHSH(text,cert[,cafile][,crlfile][,enc])
Input Parameters: text: (required) The plaintext string to be encrypted.
  cert: (required) An X.509 certificate containing the RSA public key to be used for encryption, in PEM encoded or binary Distinguished Encoding Rules (DER) format. The length of the plaintext cannot be greater than the length of the modulus of the RSA public key contained in the certificate minus 42 bytes.
  cafile: (optional) The name of a file containing the trusted Certificate Authority X.509 Certificates in PEM-encoded format, one of which was used to sign the certificate.
  crlfile: (optional) The name of a file containing X.509 Certificate Revocation Lists in PEM-encoded format that should be checked to verify the status of the certificate.
  enc: (optional) Encoding - Public-Key Cryptography Standards (PKCS) #1 v2.1 encoding method:
  • 1 - Optimal Asymmetric Encryption Padding (OAEP; default).
  • 2 - PKCS 1-v1_5.
Output: returns: RSA encrypted ciphertext value of the text input parameter.

 

Example

NOTE: The RSA encryption API returns Unicode ciphertext, which does not properly display on an ASCII roll-and-scroll terminal; so the example demonstrated output is Base 64 encoded before display.
NOTE: On GT.M, pass the filename of the certificate rather than the certificate itself. On GT.M, the optional parameters are not supported. They can be passed, but they will have no effect.
  >S TEXT="This is a test"
  >S CREDSET=##class(%SYS.X509Credentials).GetByAlias("hgwds")
  >S CERT=CREDSET.Certificate
  >W $$B64ENCD^XUSHSH($$RSAENCR^XUSHSH(TEXT,CERT,,,1))
  PbFxIUBA+Mu5F4rtFHVJOusYfqFOm99eyhp3jYTBBIteSMYE1J+dHFqSePGtGXInBIy2f6gVxTvf
  WQyy8Le92tbqADftPsGKlBISaA1O3v2r0oxYQkwR6FPub3y/r92b6l/StwAzImMF9EP6vqLt/IOK
  1eu4UD+sT5qesGB9zgAmEfQgitT3qhXZJZUAbIi//NZbLiWVtGF+99GSa77VyMXkWqKiSVZZHCLG
  yUGgPn8SwFXEsZNs+STuFaQn6jialrn04NOuaqXEDSZu1qGpn5WE3fNcWeLZE5sXJX8rG0uW5R/O
  lx/Xlk3L2GhqELELsgzJY0RG5fp8wT58cJKqwQ==