Update generateSecretKey() docs for Java 19+ keysize behavior

data/en/generatesecretkey.json

@@ -1,36 +1,81 @@
 {
-	"name":"generateSecretKey",
-	"type":"function",
-	"syntax":"generateSecretKey([algorithm] [,keysize])",
-	"returns":"string",
-	"related":["encrypt","decrypt"],
-	"description":"Generates a secure random key value for use in the encrypt and decrypt functions.",
-	"params": [
-		{"name":"algorithm","description":"The encryption algorithm used to generate the key. \nNOTE: You cannot use `generateSecretKey()` to create a key for the `CFMX_COMPAT` default algorithm in `encrypt()` and `decrypt()` functions.","required":false,"default":"","type":"string","values":["AES","BLOWFISH","DES","DESEDE"]},
-		{"name":"keysize","description":"Number of bits requested in the key for the specified algorithm (when allowed by JDK).","required":false,"default":"128","type":"numeric","values":["128", "192", "256", "512"]}
-
-	],
-	"engines": {
-		"coldfusion": {"minimum_version":"7", "notes":"", "docs":"https://helpx.adobe.com/coldfusion/cfml-reference/coldfusion-functions/functions-e-g/generatesecretkey.html"},
-		"lucee": {"minimum_version":"", "notes":"", "docs":"https://docs.lucee.org/reference/functions/generatesecretkey.html"},
-		"railo": {"minimum_version":"", "notes":"", "docs":"http://railodocs.org/index.cfm/function/generatesecretkey"},
-		"openbd": {"minimum_version":"", "notes":"", "docs":"http://openbd.org/manual/?/function/generatesecretkey"},
-		"boxlang": {"minimum_version":"1.0.0", "notes":"", "docs":"https://boxlang.ortusbooks.com/boxlang-language/reference/built-in-functions/encryption/generatesecretkey"}
-	},
-	"links": [
-		{
-			"title":"Generating AES 256 bit Key",
-			"description":"How to enable unlimited strength crypto in Java.",
-			"url":"http://www.petefreitag.com/item/803.cfm"
-		}
-	],
-	"examples": [
-		{
-			"title":"Generate an AES 128 bit Key",
-			"description":"Generate an AES key and use it to encrypt and decrypt a secret.",
-			"code":"ex={};\nex.key = generateSecretKey(\"AES\");\nex.secret = \"top secret\";\nex.encrypted=encrypt(ex.secret, ex.key, \"AES\", \"Base64\");\nex.decrypted=decrypt(ex.encrypted, ex.key, \"AES\", \"Base64\");\nwriteDump(ex);",
-			"result":""
-		}
-	]
-
-}
+  "name": "generateSecretKey",
+  "type": "function",
+  "syntax": "generateSecretKey([algorithm] [,keysize])",
+  "returns": "string",
+  "related": [
+    "encrypt",
+    "decrypt"
+  ],
+  "description": "Creates a secret encryption key that can be used with the encrypt() and decrypt() functions.",
+  "params": [
+    {
+      "name": "algorithm",
+      "description": "Encryption algorithm used to generate the key. Common values are AES, DES, BLOWFISH, and DESEDE (Triple DES). The generated key cannot be used with the default CFMX_COMPAT algorithm.",
+      "required": false,
+      "default": "AES",
+      "type": "string",
+      "values": [
+        "AES",
+        "BLOWFISH",
+        "DES",
+        "DESEDE"
+      ]
+    },
+    {
+      "name": "keysize",
+      "description": "Optional key size in bits for the generated encryption key. Common AES key sizes are 128, 192, and 256. If this value is not provided, the default size depends on the Java version used by the server. For example, Java 19 and later may automatically generate 256-bit AES keys instead of 128-bit keys.",
+      "required": false,
+      "default": "",
+      "type": "numeric",
+      "values": [
+        "128",
+        "192",
+        "256",
+        "512"
+      ]
+    }
+  ],
+  "engines": {
+    "coldfusion": {
+      "minimum_version": "7",
+      "notes": "ColdFusion 2025 running on Java 19 or later may generate AES 256-bit keys by default when keysize is not specified.",
+      "docs": "https://helpx.adobe.com/coldfusion/cfml-reference/coldfusion-functions/functions-e-g/generatesecretkey.html"
+    },
+    "lucee": {
+      "minimum_version": "",
+      "notes": "Available encryption algorithms may vary depending on the Java version and JVM configuration.",
+      "docs": "https://docs.lucee.org/reference/functions/generatesecretkey.html"
+    },
+    "railo": {
+      "minimum_version": "",
+      "notes": "",
+      "docs": "http://railodocs.org/index.cfm/function/generatesecretkey"
+    },
+    "openbd": {
+      "minimum_version": "",
+      "notes": "",
+      "docs": "http://openbd.org/manual/?/function/generatesecretkey"
+    },
+    "boxlang": {
+      "minimum_version": "1.0.0",
+      "notes": "",
+      "docs": "https://boxlang.ortusbooks.com/boxlang-language/reference/built-in-functions/encryption/generatesecretkey"
+    }
+  },
+  "links": [
+    {
+      "title": "Generating AES 256 Bit Keys",
+      "description": "More information about AES 256-bit encryption support in Java.",
+      "url": "http://www.petefreitag.com/item/803.cfm"
+    }
+  ],
+  "examples": [
+    {
+      "title": "Generate an AES Key",
+      "description": "Generate a secret key and use it to encrypt and decrypt a message.",
+      "code": "message = \"Top Secret\";\n\n// Generate AES secret key\nsecretKey = generateSecretKey(\"AES\", 256);\n\n// Encrypt the message\nencryptedText = encrypt(message, secretKey, \"AES\", \"Base64\");\n\n// Decrypt the message\ndecryptedText = decrypt(encryptedText, secretKey, \"AES\", \"Base64\");\n\nwriteDump({\n    encrypted = encryptedText,\n    decrypted = decryptedText\n});",
+      "result": "Displays the encrypted and decrypted message."
+    }
+  ]
+}

data/en/initsamlauthrequest.json

@@ -0,0 +1,78 @@
+{
+    "name":"initsamlauthrequest",
+    "type":"function",
+    "syntax":"InitSAMLAuthRequest(options)",
+    "returns":"void",
+    "description":"Starts the SAML Single Sign-On (SSO) login process by redirecting the user to an external login provider such as Okta, Azure AD, or ADFS. Before using this function, both the Identity Provider (IdP) and Service Provider (SP) must already be configured in ColdFusion Administrator or Application.cfc.",
+    "params":[
+        {
+            "name":"options",
+            "description":"Structure containing the SAML authentication settings.",
+            "required":true,
+            "type":"struct"
+        },
+        {
+            "name":"options.idp.name",
+            "description":"Name of the configured Identity Provider (IdP). The IdP is the external system that handles user login, such as Okta or Azure Active Directory.",
+            "required":true,
+            "type":"string"
+        },
+        {
+            "name":"options.sp.name",
+            "description":"Name of the configured Service Provider (SP). The SP represents your ColdFusion application that uses the external login system for authentication.",
+            "required":true,
+            "type":"string"
+        },
+        {
+            "name":"options.relayState",
+            "description":"Optional value used to return users to a specific page after successful login.",
+            "required":false,
+            "type":"string"
+        },
+        {
+            "name":"options.template",
+            "description":"Optional template page shown before redirecting users to the Identity Provider. Used only with POST binding.",
+            "required":false,
+            "type":"string"
+        },
+        {
+            "name":"options.lifetime",
+            "description":"Time in seconds that the authentication request remains valid while waiting for a response from the Identity Provider.",
+            "required":false,
+            "type":"numeric"
+        }
+    ],
+    "engines":{
+        "coldfusion":{
+            "minimum_version":"2021",
+            "notes":"Requires the SAML package to be installed using ColdFusion Package Manager (CFPM). Configure the Identity Provider and Service Provider in ColdFusion Administrator under Security > SAML before using this function.",
+            "docs":"https://helpx.adobe.com/coldfusion/cfml-reference/coldfusion-functions/functions-in-k/initsamlauthrequest.html"
+        }
+    },
+    "links":[
+        {
+            "title":"Adobe ColdFusion SAML Guide",
+            "description":"Step-by-step guide for configuring SAML authentication in ColdFusion.",
+            "url":"https://helpx.adobe.com/coldfusion/using/saml-coldfusion.html"
+        },
+        {
+            "title":"Adobe InitSAMLAuthRequest Function Reference",
+            "description":"Official Adobe documentation for the InitSAMLAuthRequest function and supported configuration options.",
+            "url":"https://helpx.adobe.com/coldfusion/cfml-reference/coldfusion-functions/functions-in-k/initsamlauthrequest.html"
+        },
+        {
+            "title":"SAML Authentication Demo with Okta and ColdFusion",
+            "description":"Video walkthrough by an Adobe developer demonstrating SAML Single Sign-On setup using Okta and Adobe ColdFusion.",
+            "url":"https://www.youtube.com/watch?v=IEVYCCKtAIM"
+        }
+    ],
+    "examples":[
+        {
+            "title":"Redirect Users to an External Login Provider",
+            "description":"This example starts a SAML login request using Okta as the Identity Provider (IdP). The ColdFusion application acts as the Service Provider (SP). Both configurations must already exist in ColdFusion Administrator under Security > SAML.",
+            "code":"<cfscript>\nconfig = {\n\n    // External login provider\n    idp = {\n        name = \"OktaIDP\"\n    },\n\n    // ColdFusion application\n    sp = {\n        name = \"EmployeePortal\"\n    },\n\n    // Optional page to return after login\n    relayState = \"dashboard\"\n};\n\n// Redirect user to the login provider\nInitSAMLAuthRequest(config);\n</cfscript>",
+            "result":"The user is redirected to the configured external login page for authentication.",
+            "runnable":false
+        }
+    ]
+}