Update cups-oauth and cups-x509 man pages.

Author: michaelrsweet

doc/cups-oauth.html

@@ -196,35 +196,35 @@ <h2 id="cups-oauth-1.options">Options</h2>
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-s </strong><em>SCOPE(S)</em><br>
 Specifies a space-delimited list of scope names to use when authorizing access.
-The default is to request authorization for all supported scopes.
+The default is to request authorization for all supported OpenID scopes.
 </p>
-    <h2 id="cups-oauth-1.commands">Commands</h2>
-    <h3 id="cups-oauth-1.commands.authorize">Authorize</h3>
+    <h2 id="cups-oauth-1.sub-commands">Sub-Commands</h2>
+    <h3 id="cups-oauth-1.sub-commands.authorize">Authorize</h3>
 <p>Starts an authorization workflow with the default web browser.
 If a resource URI is specified, the authorization is specific to that resource.
 The access token is send to the standard output on success.
 </p>
-    <h3 id="cups-oauth-1.commands.clear">Clear</h3>
+    <h3 id="cups-oauth-1.sub-commands.clear">Clear</h3>
 <p>Clears any authorization for the specified resource or for all resources if no resource URI is supplied.
 </p>
-    <h3 id="cups-oauth-1.commands.get-access-token">Get-Access-Token</h3>
+    <h3 id="cups-oauth-1.sub-commands.get-access-token">Get-Access-Token</h3>
 <p>Output the current, unexpired access token, if any, to the standard output.
 </p>
-    <h3 id="cups-oauth-1.commands.get-client-id">Get-Client-Id</h3>
+    <h3 id="cups-oauth-1.sub-commands.get-client-id">Get-Client-Id</h3>
 <p>Output the client ID string, if any, to the standard output.
 </p>
-    <h3 id="cups-oauth-1.commands.get-metadata">Get-Metadata</h3>
+    <h3 id="cups-oauth-1.sub-commands.get-metadata">Get-Metadata</h3>
 <p>Get the OAuth/OpenID authorization server metadata and send it to the standard output.
 If a name is specified, the output is just the value for the specified metadata.
 </p>
-    <h3 id="cups-oauth-1.commands.get-user-id">Get-User-Id</h3>
+    <h3 id="cups-oauth-1.sub-commands.get-user-id">Get-User-Id</h3>
 <p>Get the OpenID user ID information and send it to the standard output.
 If a name is specified, the output is just the named claim from the user ID.
 </p>
-    <h3 id="cups-oauth-1.commands.set-access-token">Set-Access-Token</h3>
+    <h3 id="cups-oauth-1.sub-commands.set-access-token">Set-Access-Token</h3>
 <p>Set the access token (which is sometimes also called an API key) for the specified resource or for all resources.
 </p>
-    <h3 id="cups-oauth-1.commands.set-client-data">Set-Client-Data</h3>
+    <h3 id="cups-oauth-1.sub-commands.set-client-data">Set-Client-Data</h3>
 <p>Set the client ID string and secret for an OAuth/OpenID authorization server.
 </p>
     <h2 id="cups-oauth-1.environment-variables">Environment Variables</h2>
@@ -240,8 +240,18 @@ <h2 id="cups-oauth-1.notes">Notes</h2>
 <p>CUPS uses a redirect URI of &quot;<a href="http://127.0.0.1/&quot;">http://127.0.0.1/&quot;</a> for all authorization on the local system.
 </p>
     <h2 id="cups-oauth-1.examples">Examples</h2>
-<p>TBD
+<p>Register a client ID and secret for the OAuth server at &quot;<a href="https://oauth.example.com/&quot;:">https://oauth.example.com/&quot;:</a>
 </p>
+    <pre>     cups-oauth -a <a href="https://oauth.example.com/">https://oauth.example.com/</a> set-client-data CLIENT-ID CLIENT-SECRET
+</pre>
+<p>Save an access token (sometimes called an application or API key) for the OAuth server at &quot;<a href="https://oauth.example.com/&quot;:">https://oauth.example.com/&quot;:</a>
+</p>
+    <pre>     cups-oauth -a <a href="https://oauth.example.com/">https://oauth.example.com/</a> set-access-token TOKEN
+</pre>
+<p>Authorize against the OAuth server at &quot;<a href="https://oauth.example.com/&quot;">https://oauth.example.com/&quot;</a> using your web browser:
+</p>
+    <pre>     cups-oauth -a <a href="https://oauth.example.com/">https://oauth.example.com/</a> authorize
+</pre>
     <h2 id="cups-oauth-1.see-also">See Also</h2>
 <p><strong>cups</strong>(1)
 

doc/cups-x509.html

@@ -148,7 +148,7 @@ <h2 id="cups-x509-1.synopsis">Synopsis</h2>
 <strong>-u</strong>
 <em>USAGE</em>
 ]
-<em>COMMAND</em>
+<em>SUB-COMMAND</em>
 <em>[ARGUMENT(S)]</em>
 </p>
     <h2 id="cups-x509-1.description">Description</h2>
@@ -214,32 +214,46 @@ <h2 id="cups-x509-1.options">Options</h2>
 The supported uses are &quot;digitalSignature&quot;, &quot;nonRepudiation&quot;, &quot;keyEncipherment&quot;, &quot;dataEncipherment&quot;, &quot;keyAgreement&quot;, &quot;keyCertSign&quot;, &quot;cRLSign&quot;, &quot;encipherOnly&quot;, and  &quot;decipherOnly&quot;.
 The preset &quot;default-ca&quot; specifies those uses required for a Certificate Authority, and the preset &quot;default-tls&quot; specifies those uses required for TLS.
 </p>
-    <h2 id="cups-x509-1.commands">Commands</h2>
-    <h3 id="cups-x509-1.commands.ca-common-name">Ca Common-Name</h3>
+    <h2 id="cups-x509-1.sub-commands">Sub-Commands</h2>
+    <h3 id="cups-x509-1.sub-commands.ca-common-name">Ca Common-Name</h3>
 <p>Sign a certificate request for the specified common name.
 </p>
-    <h3 id="cups-x509-1.commands.cacert-common-name">Cacert Common-Name</h3>
+    <h3 id="cups-x509-1.sub-commands.cacert-common-name">Cacert Common-Name</h3>
 <p>Create a CA certificate for the specified common name.
 </p>
-    <h3 id="cups-x509-1.commands.cert-common-name">Cert Common-Name</h3>
+    <h3 id="cups-x509-1.sub-commands.cert-common-name">Cert Common-Name</h3>
 <p>Create a certificate for the specified common name.
 </p>
-    <h3 id="cups-x509-1.commands.client-uri">Client Uri</h3>
+    <h3 id="cups-x509-1.sub-commands.client-uri">Client Uri</h3>
 <p>Connect to the specified URI and validate the server's certificate.
 </p>
-    <h3 id="cups-x509-1.commands.csr-common-name">Csr Common-Name</h3>
+    <h3 id="cups-x509-1.sub-commands.csr-common-name">Csr Common-Name</h3>
 <p>Create a certificate signing request for the specified common name.
 </p>
-    <h3 id="cups-x509-1.commands.server-common-nameport">Server Common-Name[:Port]</h3>
+    <h3 id="cups-x509-1.sub-commands.server-common-nameport">Server Common-Name[:Port]</h3>
 <p>Run a HTTPS test server that echos back the resource path for every GET request.
 If PORT is not specified, uses a port number from 8000 to 8999.
 </p>
-    <h3 id="cups-x509-1.commands.show-common-name">Show Common-Name</h3>
+    <h3 id="cups-x509-1.sub-commands.show-common-name">Show Common-Name</h3>
 <p>Shows any stored credentials for the specified common name.
 </p>
     <h2 id="cups-x509-1.examples">Examples</h2>
-<p>TBD
+<p>Create a certificate signing request for a 384-bit ECDSA certificate for &quot;server.example.com&quot;:
 </p>
+    <pre>     cups-x509 csr -t ecdsa-p384 server.example.com
+</pre>
+<p>Install the certificate you get back from the CA for &quot;server.example.com&quot;:
+</p>
+    <pre>     cups-x509 install server.example.com server.example.com.crt
+</pre>
+<p>Run a test server for &quot;server.exmaple.com&quot; on port 8080:
+</p>
+    <pre>     cups-x509 server SERVER-NAME:8080
+</pre>
+<p>Test a HTTPS client connection to &quot;www.example.com&quot; with validation:
+</p>
+    <pre>     cups-x509 client --require-ca <a href="https://www.example.com/">https://www.example.com/</a>
+</pre>
     <h2 id="cups-x509-1.see-also">See Also</h2>
 <p><strong>cups</strong>(1)
 

man/cups-oauth.1

@@ -6,7 +6,7 @@
 .\" Licensed under Apache License v2.0.  See the file "LICENSE" for more
 .\" information.
 .\"
-.TH cups-oauth 1 "CUPS" "2025-03-04" "OpenPrinting"
+.TH cups-oauth 1 "CUPS" "2025-05-05" "OpenPrinting"
 .SH NAME
 cups-oauth \- interact with an oauth/openid authorization server
 .SH SYNOPSIS
@@ -104,8 +104,8 @@ Specifies the OAuth/OpenID authorization server URL.
 .TP 5
 \fB\-s \fISCOPE(S)\fR
 Specifies a space-delimited list of scope names to use when authorizing access.
-The default is to request authorization for all supported scopes.
-.SH COMMANDS
+The default is to request authorization for all supported OpenID scopes.
+.SH SUB-COMMANDS
 .SS authorize
 Starts an authorization workflow with the default web browser.
 If a resource URI is specified, the authorization is specific to that resource.
@@ -137,7 +137,18 @@ environment variable sets the default OAuth/OpenID scopes as a space-delimited l
 .SH NOTES
 CUPS uses a redirect URI of "http://127.0.0.1/" for all authorization on the local system.
 .SH EXAMPLES
-TBD
+Register a client ID and secret for the OAuth server at "https://oauth.example.com/":
+.nf
+     cups-oauth -a https://oauth.example.com/ set-client-data CLIENT-ID CLIENT-SECRET
+.fi
+Save an access token (sometimes called an application or API key) for the OAuth server at "https://oauth.example.com/":
+.nf
+     cups-oauth -a https://oauth.example.com/ set-access-token TOKEN
+.fi
+Authorize against the OAuth server at "https://oauth.example.com/" using your web browser:
+.nf
+     cups-oauth -a https://oauth.example.com/ authorize
+.fi
 .SH SEE ALSO
 .BR cups (1)
 .SH COPYRIGHT

man/cups-x509.1

@@ -6,7 +6,7 @@
 .\" Licensed under Apache License v2.0.  See the file "LICENSE" for more
 .\" information.
 .\"
-.TH cups-x509 1 "CUPS" "2025-03-04" "OpenPrinting"
+.TH cups-x509 1 "CUPS" "2025-05-05" "OpenPrinting"
 .SH NAME
 cups-x509 \- description
 .SH SYNOPSIS
@@ -58,7 +58,7 @@ cups-x509 \- description
 .B \-u
 .I USAGE
 ]
-.I COMMAND
+.I SUB-COMMAND
 .I [ARGUMENT(S)]
 .SH DESCRIPTION
 The
@@ -121,7 +121,7 @@ Specify the certificate type - "rsa-2048" for 2048-bit RSA, "rsa-3072" for 3072-
 Specify the usage for the certificate as a comma-delimited list of uses.
 The supported uses are "digitalSignature", "nonRepudiation", "keyEncipherment", "dataEncipherment", "keyAgreement", "keyCertSign", "cRLSign", "encipherOnly", and  "decipherOnly".
 The preset "default-ca" specifies those uses required for a Certificate Authority, and the preset "default-tls" specifies those uses required for TLS.
-.SH COMMANDS
+.SH SUB-COMMANDS
 .SS ca COMMON-NAME
 Sign a certificate request for the specified common name.
 .SS cacert COMMON-NAME
@@ -138,7 +138,22 @@ If PORT is not specified, uses a port number from 8000 to 8999.
 .SS show COMMON-NAME
 Shows any stored credentials for the specified common name.
 .SH EXAMPLES
-TBD
+Create a certificate signing request for a 384-bit ECDSA certificate for "server.example.com":
+.nf
+     cups-x509 csr -t ecdsa-p384 server.example.com
+.fi
+Install the certificate you get back from the CA for "server.example.com":
+.nf
+     cups-x509 install server.example.com server.example.com.crt
+.fi
+Run a test server for "server.exmaple.com" on port 8080:
+.nf
+     cups-x509 server SERVER-NAME:8080
+.fi
+Test a HTTPS client connection to "www.example.com" with validation:
+.nf
+     cups-x509 client --require-ca https://www.example.com/
+.fi
 .SH SEE ALSO
 .BR cups (1)
 .SH COPYRIGHT

tools/cups-x509.c

@@ -67,7 +67,7 @@
 
 static int	do_ca(const char *common_name, const char *csrfile, const char *root_name, int days);
 static int	do_cert(bool ca_cert, cups_credpurpose_t purpose, cups_credtype_t type, cups_credusage_t keyusage, const char *organization, const char *org_unit, const char *locality, const char *state, const char *country, const char *root_name, const char *common_name, size_t num_alt_names, const char **alt_names, int days);
-static int	do_client(const char *uri);
+static int	do_client(const char *uri, bool pin, bool require_ca);
 static int	do_csr(cups_credpurpose_t purpose, cups_credtype_t type, cups_credusage_t keyusage, const char *organization, const char *org_unit, const char *locality, const char *state, const char *country, const char *common_name, size_t num_alt_names, const char **alt_names);
 static int	do_server(const char *host_port);
 static int	do_show(const char *common_name);
@@ -94,6 +94,8 @@ main(int  argc,				// I - Number of command-line arguments
 		*state = NULL,		// State/province
 		*country = NULL,	// Country
 		*alt_names[100];	// Subject alternate names
+  bool		pin = false,		// Pin client cert?
+		require_ca = false;	// Require a CA-signed cert?
   size_t	num_alt_names = 0;
   int		days = 365;		// Days until expiration
   cups_credpurpose_t purpose = CUPS_CREDPURPOSE_SERVER_AUTH;
@@ -111,6 +113,14 @@ main(int  argc,				// I - Number of command-line arguments
     {
       return (usage(stdout));
     }
+    else if (!strcmp(argv[i], "--pin"))
+    {
+      pin = true;
+    }
+    else if (!strcmp(argv[i], "--require-ca"))
+    {
+      require_ca = true;
+    }
     else if (!strcmp(argv[i], "--version"))
     {
       puts(LIBCUPS_VERSION);
@@ -355,7 +365,7 @@ main(int  argc,				// I - Number of command-line arguments
 
   if (!command || !arg)
   {
-    cupsLangPuts(stderr, _("cups-x509: Missing command argument."));
+    cupsLangPuts(stderr, _("cups-x509: Missing sub-command argument."));
     return (usage(stderr));
   }
 
@@ -374,7 +384,7 @@ main(int  argc,				// I - Number of command-line arguments
   }
   else if (!strcmp(command, "client"))
   {
-    return (do_client(arg));
+    return (do_client(arg, pin, require_ca));
   }
   else if (!strcmp(command, "csr"))
   {
@@ -539,7 +549,9 @@ do_cert(
 //
 
 static int				// O - Exit status
-do_client(const char *uri)		// I - URI
+do_client(const char *uri,		// I - URI
+          bool       pin,		// I - Pin the cert?
+          bool       require_ca)	// I - Require a CA-signed cert?
 {
   http_t	*http;			// HTTP connection
   char		scheme[HTTP_MAX_URI],	// Scheme from URI
@@ -556,26 +568,19 @@ do_client(const char *uri)		// I - URI
 
 
   // Connect to the host and validate credentials...
-  if (httpSeparateURI(HTTP_URI_CODING_MOST, uri, scheme, sizeof(scheme), username, sizeof(username), hostname, sizeof(hostname), &port, resource, sizeof(resource)) < HTTP_URI_STATUS_OK)
+  if ((http = httpConnectURI(uri, hostname, sizeof(hostname), &port, resource, sizeof(resource), /*blocking*/true, /*msec*/30000, /*cancel*/NULL, require_ca)) == NULL)
   {
-    cupsLangPrintf(stderr, _("cups-x509: Bad URI '%s'."), uri);
-    return (1);
-  }
-
-  if ((http = httpConnect(hostname, port, NULL, AF_UNSPEC, HTTP_ENCRYPTION_ALWAYS, 1, 30000, NULL)) == NULL)
-  {
-    cupsLangPrintf(stderr, _("cups-x509: Unable to connect to '%s' on port %d: %s"), hostname, port, cupsGetErrorString());
+    cupsLangPrintf(stderr, _("cups-x509: Unable to connect to '%s': %s"), uri, cupsGetErrorString());
     return (1);
   }
 
   puts("TLS Server Credentials:");
   if ((hcreds = httpCopyPeerCredentials(http)) != NULL)
   {
-    trust = cupsGetCredentialsTrust(/*path*/NULL, hostname, hcreds, /*require_ca*/false);
+    trust = cupsGetCredentialsTrust(/*path*/NULL, hostname, hcreds, require_ca);
 
     cupsGetCredentialsInfo(hcreds, hinfo, sizeof(hinfo));
 
-//    printf("    Certificate Count: %u\n", (unsigned)cupsArrayGetCount(hcreds));
     if (trust == HTTP_TRUST_OK)
       puts("    Trust: OK");
     else
@@ -584,6 +589,9 @@ do_client(const char *uri)		// I - URI
     printf("     ValidName: %s\n", cupsAreCredentialsValidForName(hostname, hcreds) ? "true" : "false");
     printf("          Info: \"%s\"\n", hinfo);
 
+    if (pin)
+      cupsSaveCredentials(/*path*/NULL, hostname, hcreds, /*key*/NULL);
+
     free(hcreds);
   }
   else
@@ -835,9 +843,9 @@ do_show(const char *common_name)	// I - Common name
 static int				// O - Exit code
 usage(FILE *out)			// I - Output file (stdout or stderr)
 {
-  cupsLangPuts(out, _("Usage: cups-x509 [OPTIONS] [COMMAND] [ARGUMENT]"));
+  cupsLangPuts(out, _("Usage: cups-x509 [OPTIONS] [SUB-COMMAND] [ARGUMENT]"));
   cupsLangPuts(out, "");
-  cupsLangPuts(out, _("Commands:"));
+  cupsLangPuts(out, _("Sub-Commands:"));
   cupsLangPuts(out, "");
   cupsLangPuts(out, _("ca COMMON-NAME             Sign a CSR to produce a certificate."));
   cupsLangPuts(out, _("cacert COMMON-NAME         Create a CA certificate."));