1.\" $OpenBSD: X509_check_purpose.3,v 1.12 2024/09/02 08:04:32 tb Exp $ 2.\" 3.\" Copyright (c) 2019, 2021 Ingo Schwarze <schwarze@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: September 2 2024 $ 18.Dt X509_CHECK_PURPOSE 3 19.Os 20.Sh NAME 21.Nm X509_check_purpose 22.Nd check intended usage of a public key 23.Sh SYNOPSIS 24.In openssl/x509v3.h 25.Ft int 26.Fo X509_check_purpose 27.Fa "X509 *certificate" 28.Fa "int purpose" 29.Fa "int ca" 30.Fc 31.Sh DESCRIPTION 32If the 33.Fa purpose 34argument is \-1, 35.Fn X509_check_purpose 36ignores the 37.Fa ca 38argument and checks that all the extensions of the 39.Fa certificate 40can be parsed and pass minimal sanity checks, ensuring that 41no extension occurs more than once. 42It also makes sure that all extensions are cached in the 43.Vt X509 44object. 45.Pp 46If the 47.Fa purpose 48argument is not \-1 and the 49.Fa ca 50flag is 0, 51.Fn X509_check_purpose 52also checks whether the public key contained in the 53.Fa certificate 54is intended to be used for the given 55.Fa purpose , 56which can be one of the following integer constants. 57The check succeeds if none of the conditions given in the list below 58are violated. 59It always fails if parsing fails for any extension contained in the 60.Fa certificate . 61.Bl -tag -width 1n 62.It Dv X509_PURPOSE_SSL_CLIENT 63.Bl -dash -width 1n -compact 64.It 65If the 66.Fa certificate 67contains an Extended Key Usage extension, it contains the RFC 5280 68.Dq TLS WWW client authentication 69purpose 70.Pq Dv NID_client_auth . 71.It 72If the 73.Fa certificate 74contains a Key Usage extension, the 75.Dv digitalSignature 76bit is set. 77.It 78If the 79.Fa certificate 80contains a Netscape Cert Type extension, the 81.Dq SSL client certificate 82bit is set 83.Pq Dv NS_SSL_CLIENT . 84.El 85.It Dv X509_PURPOSE_SSL_SERVER 86.Bl -dash -width 1n -compact 87.It 88If the 89.Fa certificate 90contains an Extended Key Usage extension, it contains the RFC 5280 91.Dq TLS WWW server authentication 92purpose 93.Pq Dv NID_server_auth 94or the private 95.Dq Netscape Server Gated Crypto 96.Pq Dv NID_ns_sgc 97or 98.Dq Microsoft Server Gated Crypto 99.Pq Dv NID_ms_sgc 100purpose. 101.It 102If the 103.Fa certificate 104contains a Key Usage extension, at least one of the 105.Dv digitalSignature 106and 107.Dv keyEncipherment 108bits is set. 109.It 110If the 111.Fa certificate 112contains a Netscape Cert Type extension, the 113.Dq SSL server certificate 114bit is set 115.Pq Dv NS_SSL_SERVER 116.El 117.It Dv X509_PURPOSE_NS_SSL_SERVER 118.\" check_purpose_ns_ssl_server, "Netscape SSL server" 119This does the same checks as 120.Dv X509_PURPOSE_SSL_SERVER 121and additionally requires that a Key Usage extension, if present, 122has the 123.Dv keyEncipherment 124bit set. 125.It Dv X509_PURPOSE_SMIME_SIGN 126.\" check_purpose_smime_sign, "S/MIME signing" 127.Bl -dash -width 1n -compact 128.It 129If the 130.Fa certificate 131contains an Extended Key Usage extension, it contains the RFC 5280 132.Dq Email protection 133purpose 134.Pq Dv NID_email_protect . 135.It 136If the 137.Fa certificate 138contains a Key Usage extension, at least one of the 139.Dv digitalSignature 140and 141.Dv nonRepudiation 142bits is set. 143.It 144If the 145.Fa certificate 146contains a Netscape Cert Type extension, it has the 147.Dq S/MIME certificate 148bit set. 149If the 150.Dq SSL client certificate 151bit is set but the 152.Dq S/MIME certificate 153bit is not, no decision is made. 154.El 155.It Dv X509_PURPOSE_SMIME_ENCRYPT 156.\" check_purpose_smime_encrypt, "S/MIME encryption" 157.Bl -dash -width 1n -compact 158.It 159If the 160.Fa certificate 161contains an Extended Key Usage extension, it contains the RFC 5280 162.Dq Email protection 163purpose 164.Pq Dv NID_email_protect . 165.It 166If the 167.Fa certificate 168contains a Key Usage extension, the 169.Dv keyEncipherment 170bit is set. 171.It 172If the 173.Fa certificate 174contains a Netscape Cert Type extension, it has the 175.Dq S/MIME certificate 176bit set. 177If the 178.Dq SSL client certificate 179bit is set but the 180.Dq S/MIME certificate 181bit is not, no decision is made. 182.El 183.It Dv X509_PURPOSE_CRL_SIGN 184.\" check_purpose_crl_sign, "CRL signing" 185.Bl -dash -width 1n -compact 186.It 187If the 188.Fa certificate 189contains a Key Usage extension, the 190.Dv cRLSign 191bit is set. 192.El 193.It Dv X509_PURPOSE_ANY 194Nothing is required except that, if any extensions are present, 195parsing them needs to succeed. 196.It Dv X509_PURPOSE_OCSP_HELPER 197.\" ocsp_helper, "OCSP helper" 198Nothing is required except that, if any extensions are present, 199parsing them needs to succeed. 200The application program is expected 201to do the actual checking by other means. 202.It Dv X509_PURPOSE_TIMESTAMP_SIGN 203.\" check_purpose_timestamp_sign, "Time Stamp signing" 204.Bl -dash -width 1n -compact 205.It 206The 207.Fa certificate 208contains an Extended Key Usage extension containing the RFC 5280 209.Dq Time Stamping 210purpose and no other purpose. 211This extension is marked as critical. 212.It 213If the 214.Fa certificate 215contains a Key Usage extension, at least one of the 216.Dv digitalSignature 217and 218.Dv nonRepudiation 219bits is set, and no other bits are set. 220.El 221.El 222.Pp 223If the 224.Fa purpose 225argument is not \-1 and the 226.Fa ca 227flag is non-zero, 228.Fn X509_check_purpose 229instead checks, in addition to the minimal sanity checks, whether the 230.Fa certificate 231can be used as a certificate authority certificate 232in the context of the given 233.Fa purpose . 234To succeed, the check always requires that none of the following 235conditions are violated: 236.Pp 237.Bl -dash -width 1n -compact 238.It 239If the 240.Fa certificate 241contains any extensions, parsing them succeeds. 242.It 243If the 244.Fa certificate 245contains a Key Usage extension, the 246.Dv keyCertSign 247bit is set. 248.It 249If the 250.Fa certificate 251contains a Basic Constraints extension, the 252.Fa cA 253field is set. 254.It 255If the 256.Fa certificate 257is a version 1 certificate, the subject name matches the issuer name 258and the certificate is self signed. 259.El 260.Pp 261The check succeeds if none of the additional conditions given in 262the list below are violated. 263.Bl -tag -width 1n 264.It Dv X509_PURPOSE_SSL_CLIENT 265.Bl -dash -width 1n -compact 266.It 267If the 268.Fa certificate 269contains an Extended Key Usage extension, it contains the RFC 5280 270.Dq TLS WWW client authentication 271purpose 272.Pq Dv NID_client_auth . 273.It 274If the 275.Fa certificate 276is not a version 1 certificate and does not contain a Basic Constraints 277extension, it contains a Key Usage extension with the 278.Dv keyCertSign 279bit set or a Netscape Cert Type extension with the 280.Dq SSL CA certificate 281bit set. 282.El 283.It Dv X509_PURPOSE_SSL_SERVER No or Dv X509_PURPOSE_NS_SSL_SERVER 284.Bl -dash -width 1n -compact 285.It 286If the 287.Fa certificate 288contains an Extended Key Usage extension, it contains the RFC 5280 289.Dq TLS WWW server authentication 290purpose 291.Pq Dv NID_server_auth 292or the private 293.Dq Netscape Server Gated Crypto 294.Pq Dv NID_ns_sgc 295or 296.Dq Microsoft Server Gated Crypto 297.Pq Dv NID_ms_sgc 298purpose. 299.It 300If the 301.Fa certificate 302is not a version 1 certificate and does not contain a Basic Constraints 303extension, it contains a Key Usage extension with the 304.Dv keyCertSign 305bit set or a Netscape Cert Type extension with the 306.Dq SSL CA certificate 307bit set. 308.El 309.It Dv X509_PURPOSE_SMIME_SIGN No or Dv X509_PURPOSE_SMIME_ENCRYPT 310.Bl -dash -width 1n -compact 311.It 312If the 313.Fa certificate 314contains an Extended Key Usage extension, it contains the RFC 5280 315.Dq Email protection 316purpose 317.Pq Dv NID_email_protect . 318.It 319If the 320.Fa certificate 321is not a version 1 certificate and does not contain a Basic Constraints 322extension, it contains a Key Usage extension with the 323.Dv keyCertSign 324bit set or a Netscape Cert Type extension with the 325.Dq S/MIME CA certificate 326bit set. 327.El 328.It Xo 329.Dv X509_PURPOSE_CRL_SIGN , 330.Dv X509_PURPOSE_OCSP_HELPER , 331or 332.Dv X509_PURPOSE_TIMESTAMP_SIGN 333.Xc 334.Bl -dash -width 1n -compact 335.It 336If the 337.Fa certificate 338is not a version 1 certificate and does not contain a Basic Constraints 339extension, it contains a Key Usage extension with the 340.Dv keyCertSign 341bit set or a Netscape Cert Type extension with at least one of the 342.Dq SSL CA certificate , 343.Dq S/MIME CA certificate , 344or 345.Dq Object-signing CA certificate 346bits set. 347.El 348.It Dv X509_PURPOSE_ANY 349Nothing is required except that, if any extensions are present, 350parsing them needs to succeed. 351The check even succeeds if the three other common conditions 352cited above this list are violated. 353.El 354.Pp 355If the function 356.Xr X509_PURPOSE_add 3 357was called before 358.Fn X509_check_purpose , 359it may have installed different, user-supplied checking functions 360for some of the standard purposes listed above, or it may have 361installed additional, user-supplied checking functions for user-defined 362.Fa purpose 363identifiers not listed above. 364.Sh RETURN VALUES 365If the parsing of certificate extensions fails, sanity checks fail or the 366.Fa purpose 367is invalid, 368.Fn X509_check_purpose 369returns \-1 to indicate the error. 370.Pp 371If the 372.Fa purpose 373argument is \-1 and parsing and minimal sanity checks succeed, 374.Fn X509_check_purpose 375returns 1 to indicate success. 376.Pp 377Otherwise, it returns the following values: 378.Pp 379If 380.Fa ca 381is 0: 382.Bl -column -1 Failure -compact 383.It 0 Ta Failure Ta The 384.Fa certificate 385cannot be used for the 386.Fa purpose . 387.It 1 Ta Success Ta The 388.Fa certificate 389can be used for the 390.Fa purpose . 391.It 2 Ta Unknown Ta \&No decision can be made. 392.El 393.Pp 394If 395.Fa ca 396is non-zero: 397.Bl -column -1 Failure -compact 398.It 0 Ta Failure Ta The 399.Fa certificate 400cannot be used as a CA for the 401.Fa purpose . 402.It 1 Ta Success Ta The 403.Fa certificate 404can be used as a CA for the 405.Fa purpose . 406.It 3 Ta Success Ta The Fa certificate No is a version 1 CA . 407.It 4 Ta Success Ta The Key Usage allows Dv keyCertSign . 408.It 5 Ta Success Ta A Netscape Cert Type allows usage as a CA. 409.El 410.Sh SEE ALSO 411.Xr BASIC_CONSTRAINTS_new 3 , 412.Xr EXTENDED_KEY_USAGE_new 3 , 413.Xr X509_new 3 , 414.Xr X509_PURPOSE_set 3 , 415.Xr X509V3_get_d2i 3 , 416.Xr x509v3.cnf 5 417.Sh STANDARDS 418RFC 5280: Internet X.509 Public Key Infrastructure Certificate and 419Certificate Revocation List (CRL) Profile 420.Bl -dash -offset indent -compact 421.It 422section 4.2.1.3: Key Usage 423.It 424section 4.2.1.9: Basic Constraints 425.It 426section 4.2.1.12: Extended Key Usage 427.El 428.Sh HISTORY 429.Fn X509_check_purpose 430first appeared in OpenSSL 0.9.5 and has been available since 431.Ox 2.7 . 432