class OpenSSL::PKCS12 - Documentation for Ruby 4.0
Description: class OpenSSL::PKCS12: Defines a file format commonly used to store private keys with accompanying public key certificates, protected with a password-based symmetric key.
Keywords: ruby,class,OpenSSL::PKCS12

🔍

No recent searches

# class OpenSSL::PKCS12

Defines a file format commonly used to store private keys with accompanying public key certificates, protected with a password-based symmetric key.

### Constants

KEY_EX

  MSIE specific `PKCS12` key usage extensions

KEY_SIG

### Attributes

ca_certs [R]
certificate [R]
key [R]

### Public Class Methods

create(pass, name, key, cert [, ca, [, key_pbe [, cert_pbe [, key_iter [, mac_iter [, keytype]]]]]])
Source

    static VALUE
    ossl_pkcs12_s_create(int argc, VALUE *argv, VALUE self)
    {
        VALUE pass, name, pkey, cert, ca, key_nid, cert_nid, key_iter, mac_iter, keytype;
        VALUE obj;
        char *passphrase, *friendlyname;
        EVP_PKEY *key;
        X509 *x509;
        STACK_OF(X509) *x509s;
        int nkey = 0, ncert = 0, kiter = 0, miter = 0, ktype = 0;
        PKCS12 *p12;

        rb_scan_args(argc, argv, "46", &pass, &name, &pkey, &cert, &ca, &key_nid, &cert_nid, &key_iter, &mac_iter, &keytype);
        passphrase = NIL_P(pass) ? NULL : StringValueCStr(pass);
        friendlyname = NIL_P(name) ? NULL : StringValueCStr(name);
        key = GetPKeyPtr(pkey);
        x509 = GetX509CertPtr(cert);
    /* TODO: make a VALUE to nid function */
        if (!NIL_P(key_nid)) {
            if ((nkey = OBJ_txt2nid(StringValueCStr(key_nid))) == NID_undef)
                ossl_raise(rb_eArgError, "Unknown PBE algorithm %"PRIsVALUE, key_nid);
        }
        if (!NIL_P(cert_nid)) {
            if ((ncert = OBJ_txt2nid(StringValueCStr(cert_nid))) == NID_undef)
                ossl_raise(rb_eArgError, "Unknown PBE algorithm %"PRIsVALUE, cert_nid);
        }
        if (!NIL_P(key_iter))
            kiter = NUM2INT(key_iter);
        if (!NIL_P(mac_iter))
            miter = NUM2INT(mac_iter);
        if (!NIL_P(keytype))
            ktype = NUM2INT(keytype);

    #if defined(OPENSSL_IS_AWSLC)
        if (ktype != 0) {
            ossl_raise(rb_eArgError, "Unknown key usage type %"PRIsVALUE, INT2NUM(ktype));
        }
    #else
        if (ktype != 0 && ktype != KEY_SIG && ktype != KEY_EX) {
            ossl_raise(rb_eArgError, "Unknown key usage type %"PRIsVALUE, INT2NUM(ktype));
        }
    #endif

        obj = NewPKCS12(cPKCS12);
        x509s = NIL_P(ca) ? NULL : ossl_x509_ary2sk(ca);
        p12 = PKCS12_create(passphrase, friendlyname, key, x509, x509s,
                            nkey, ncert, kiter, miter, ktype);
        sk_X509_pop_free(x509s, X509_free);
        if(!p12) ossl_raise(ePKCS12Error, NULL);
        SetPKCS12(obj, p12);

        ossl_pkcs12_set_key(obj, pkey);
        ossl_pkcs12_set_cert(obj, cert);
        ossl_pkcs12_set_ca_certs(obj, ca);

        return obj;
    }

### Parameters

- pass - string

- name - A string describing the key.

- key - Any `PKey`.

- cert - A `X509::Certificate`.

  - The public_key portion of the certificate must contain a valid public key.

  - The not_before and not_after fields must be filled in.

- ca - An optional array of `X509::Certificate`‘s.

- key_pbe - string

- cert_pbe - string

- key_iter - integer

- mac_iter - integer

- keytype - An integer representing an MSIE specific extension.

Any optional arguments may be supplied as `nil` to preserve the `OpenSSL` defaults.

See the `OpenSSL` documentation for PKCS12_create().

new → pkcs12
new(str) → pkcs12
new(str, pass) → pkcs12
Source

    static VALUE
    ossl_pkcs12_initialize(int argc, VALUE *argv, VALUE self)
    {
        BIO *in;
        VALUE arg, pass, pkey, cert, ca;
        char *passphrase;
        EVP_PKEY *key;
        X509 *x509;
        STACK_OF(X509) *x509s = NULL;
        int st = 0;
        PKCS12 *pkcs = DATA_PTR(self);

        if(rb_scan_args(argc, argv, "02", &arg, &pass) == 0) return self;
        passphrase = NIL_P(pass) ? NULL : StringValueCStr(pass);
        in = ossl_obj2bio(&arg);
        d2i_PKCS12_bio(in, &pkcs);
        DATA_PTR(self) = pkcs;
        BIO_free(in);

        pkey = cert = ca = Qnil;
        if(!PKCS12_parse(pkcs, passphrase, &key, &x509, &x509s))
            ossl_raise(ePKCS12Error, "PKCS12_parse");
        if (key) {
            pkey = rb_protect(ossl_pkey_wrap_i, (VALUE)key, &st);
            if (st) goto err;
        }
        if (x509) {
            cert = rb_protect(ossl_x509_new_i, (VALUE)x509, &st);
            if (st) goto err;
        }
        if (x509s) {
            ca = rb_protect(ossl_x509_sk2ary_i, (VALUE)x509s, &st);
            if (st) goto err;
        }

      err:
        X509_free(x509);
        sk_X509_pop_free(x509s, X509_free);
        ossl_pkcs12_set_key(self, pkey);
        ossl_pkcs12_set_cert(self, cert);
        ossl_pkcs12_set_ca_certs(self, ca);
        if(st) rb_jump_tag(st);

        return self;
    }

### Parameters

- str - Must be a DER encoded `PKCS12` string.

- pass - string

### Public Instance Methods

set_mac(pass, salt = nil, iter = nil, md_type = nil)
Source

    static VALUE
    pkcs12_set_mac(int argc, VALUE *argv, VALUE self)
    {
        PKCS12 *p12;
        VALUE pass, salt, iter, md_name, md_holder = Qnil;
        int iter_i = 0;
        const EVP_MD *md_type = NULL;

        rb_scan_args(argc, argv, "13", &pass, &salt, &iter, &md_name);
        rb_check_frozen(self);
        GetPKCS12(self, p12);

        StringValue(pass);
        if (!NIL_P(salt))
            StringValue(salt);
        if (!NIL_P(iter))
            iter_i = NUM2INT(iter);
        if (!NIL_P(md_name))
            md_type = ossl_evp_md_fetch(md_name, &md_holder);

        if (!PKCS12_set_mac(p12, RSTRING_PTR(pass), RSTRING_LENINT(pass),
                            !NIL_P(salt) ? (unsigned char *)RSTRING_PTR(salt) : NULL,
                            !NIL_P(salt) ? RSTRING_LENINT(salt) : 0,
                            iter_i, md_type))
            ossl_raise(ePKCS12Error, "PKCS12_set_mac");

        return Qnil;
    }

Sets MAC parameters and generates MAC over the PKCS #12 structure.

This method uses `HMAC` and the PKCS #12 specific password-based `KDF` as specified in the original PKCS #12.

See also the man page PKCS12_set_mac(3).

Added in version 3.3.0.

to_der ()
Source

    static VALUE
    ossl_pkcs12_to_der(VALUE self)
    {
        PKCS12 *p12;
        VALUE str;
        long len;
        unsigned char *p;

        GetPKCS12(self, p12);
        if((len = i2d_PKCS12(p12, NULL)) <= 0)
            ossl_raise(ePKCS12Error, NULL);
        str = rb_str_new(0, len);
        p = (unsigned char *)RSTRING_PTR(str);
        if(i2d_PKCS12(p12, &p) <= 0)
            ossl_raise(ePKCS12Error, NULL);
        ossl_str_adjust(str, p);

        return str;
    }