Skip to content
Developer API

Password helpers and security

3 min read

Password fields (and password Global Data variables) are designed so that a stored secret never appears in output. Two functions let your own code use them. How the three storage modes work is described under Password.

wpmcf_check_password()

php
wpmcf_check_password( string $group_key, string $field_key, string $password, mixed $object = null, array $args = [] ): bool

True when the plain $password matches the stored value of a top-level Password field. Works for hashed, encrypted and plain-text storage.

It returns false when:

  • the password does not match (the comparison is exact and case-sensitive);
  • $password is empty;
  • the field is empty (never set, or cleared);
  • the field is not a Password field;
  • the group, field or object is unknown, or the object reference is invalid.

$args takes context (post, user, term, comment, options, widget) and the widget_* arguments; $object accepts every object reference.

php
// Gate a download behind a per-post password field.
if ( wpmcf_check_password( 'download', 'access_code', sanitize_text_field( wp_unslash( $_POST['code'] ?? '' ) ), $post_id ) ) {
    // serve the file
}

// Options-page secret.
wpmcf_check_password( 'integration', 'webhook_secret', $supplied, 'option' );

Verified for all three storage modes on posts, users and options.

wpmcf_get_password()

php
wpmcf_get_password( string $group_key, string $field_key, mixed $object = null, array $args = [] ): ?string

Returns the readable secret of a Password field stored encrypted or as plain text. Returns null for a hashed password, an empty field, a non-Password field, or a failed read.

php
$apiKey = wpmcf_get_password( 'integration', 'api_secret', 'option' );
if ( $apiKey !== null ) {
    wp_remote_get( $url, [ 'headers' => [ 'Authorization' => 'Bearer ' . $apiKey ] ] );
}

Never print the result. Encrypted values use a key derived from the site's SECURE_AUTH_SALT: if the salts change, they can no longer be decrypted and null is returned.

What the other functions do with a Password field

Verified for a hashed, an encrypted and a plain-text field:

Call

Result

wpmcf_get_field()

the stored sealed string: $wp$2y$10$... (hash), $wpmcf-enc$... (encrypted) or the plain text. It is a raw getter; it can leak plain-text secrets, so do not print it.

wpmcf_has_field()

true when something is stored

wpmcf_the_field() / [wpmcf_field] / block / binding

prints nothing

wpmcf_update_field( ..., 'text' )

stores the value sealed according to the field's Store as setting

wpmcf_update_field( ..., '' )

keeps the stored value, returns true

wpmcf_update_field( ..., null )

clears it

wpmcf_update_field() with a value over 128 bytes, or violating min/max length

false and a _doing_it_wrong() notice

wpmcf_query / orderby on the field

not allowed: matches nothing

REST wpmcf attribute

never returned and refused on write (400 wpmcf_rest_unknown_field)

{{ fg.group.field }} variables

empty

Letting a Password field print

The filter wpmcf/field/the_password (default false) lets the printing functions reveal plain and encrypted values (never a hash). Verified: with the filter returning true, a plain-text password printed; a hash still printed nothing. wpmcf/global/the_password does the same for Global Data (verified: with it on, wpmcf_the_global() and [wpmcf_global] print the decrypted value with auto). Leave both off on public output; enable only in code paths you control.

Global Data passwords

A Global Data variable of type password is encrypted at rest. wpmcf_get_global() returns the decrypted value, so never echo it. wpmcf_the_global(), [wpmcf_global] and {{ glb.key }} print nothing for it. See Global Data functions.

Security checklist

  1. Escape every raw value. wpmcf_get_* returns unescaped data. Use esc_html(), esc_attr(), esc_url(), wp_kses_post() or wp_json_encode() for the place you print into, or use a wpmcf_the_* function.
  2. Writes are not capability-checked. wpmcf_update_field(), wpmcf_delete_field(), wpmcf_update_option_field(), wpmcf_delete_option_field() and wpmcf_update_global() trust the caller. Verify a nonce and current_user_can() before calling them with visitor input.
  3. Reads are not restricted either. wpmcf_get_field( ..., 'user_5' ) returns another user's value; wpmcf_get_field( ..., $private_post_id ) returns a private post's value. Only the shortcode, the block and the bindings enforce visibility.
  4. The REST wpmcf attribute is public for published posts. Anyone who can read a post reads its REST-enabled groups. Writing needs edit_post.
  5. Do not put secrets in non-Password fields. Text fields are readable by REST, the shortcode and exports.
  6. Prefer hashed passwords and compare with wpmcf_check_password(). Use encrypted storage only when your code must send the secret to another service.
  7. Values with {{ }} run only for trusted writers. Expressions in post values run only when the post's author may use unfiltered HTML; comments never run them. See Reading values.
  8. Queries are injection-safe. wpmcf_query binds every value and validates every identifier; bad input matches nothing instead of failing open. See Querying posts.
Was this page helpful?

Still stuck? Contact support