Overview | Package | Class | Tree | Deprecated | Index | Help
| JSS 3.4
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.mozilla.jss.pkcs12
Class PFX

    java.lang.Object
      |
      +--org.mozilla.jss.pkcs12.PFX

All Implemented Interfaces:
  ASN1Value

public class PFX
extends java.lang.Object
implements ASN1Value

The top level ASN.1 structure for a PKCS #12 blob.

The general procedure for creating a PFX blob is as follows:

- Create instances of `SafeBag` containing things such as private keys, certificates, or arbitrary secrets.
- Store the SafeBags in one or more SEQUENCEs. Each SEQUENCE is called a SafeContents.
- Create an AuthenticatedSafes. Store each SafeContents into the AuthenticatedSafes with `addEncryptedSafeContents` or `addSafeContents`.

  Standard procedure for browsers is for the AuthenticatedSafes to contain two instances of SafeContents, one encrypted and the other not. Anything you want encrypted can go in the encrypted SafeContents, and anything you want in plaintext can go in the regular SafeContents. Keep in mind that private key SafeBags usually consist of an EncryptedPrivateKeyInfo, which has its own (strong) encryption, in which case it is not essential that the SafeContents containing the private key also be encrypted.

- Create a PFX containing the AuthenticatedSafes instance, using the `PFX(AuthenticatedSafes)` constructor.
- Add a MAC to the PFX so it can be verified, using `PFX.computeMacData`.

To decode a PFX,

- Use a `PFX.Template` to decode the ASN.1 into a `PFX` object.
- Check the output of `PFX.verifyAuthSafes` to verify the MAC on the PFX.
- Use `PFX.getAuthSafes` to extract the AuthenticatedSafes instance.
- Use `AuthenticatedSafes.getSafeContentsAt` to grab the SafeContents objects in the AuthenticatedSafes.
- Each SafeContents is a SEQUENCE of SafeBags, each of which may contain a private key, cert, or arbitrary secret.

Nested Class Summary
`static class` | `PFX.Template` A Template for decoding a BER-encoded PFX.

Field Summary
`static int` | `DEFAULT_ITERATIONS` The default number of iterations to use when generating the MAC.

Constructor Summary
`PFX(AuthenticatedSafes authSafes)` Creates a PFX with the default version and no MacData.
`PFX(AuthenticatedSafes authSafes, MacData macData)` Creates a PFX with the default version.
`PFX(INTEGER version, AuthenticatedSafes authSafes, MacData macData)` Creates a PFX with the given parameters.

Method Summary
`void` | `computeMacData(Password password, byte[] salt, int iterationCount)` Computes the macData field and adds it to the PFX.
`void` | `encode(java.io.OutputStream ostream)` Write this value's DER encoding to an output stream using its own base tag.
`void` | `encode(Tag implicitTag, java.io.OutputStream ostream)` Write this value's DER encoding to an output stream using an implicit tag.
`AuthenticatedSafes` | `getAuthSafes()`
`MacData` | `getMacData()` Returns the MacData of this PFX, which is used to verify the contents.
`Tag` | `getTag()` Returns the base tag for this type, not counting any tags that may be imposed on it by its context.
`INTEGER` | `getVersion()`
`static void` | `main(java.lang.String[] args)`
`boolean` | `verifyAuthSafes(Password password, java.lang.StringBuffer reason)` Verifies the HMAC on the authenticated safes, using the password provided.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### DEFAULT_ITERATIONS

    public static final int DEFAULT_ITERATIONS

  The default number of iterations to use when generating the MAC. Currently, it is 1.

  See Also:
    Constant Field Values

Constructor Detail

### PFX

    public PFX(INTEGER version,
               AuthenticatedSafes authSafes,
               MacData macData)

  Creates a PFX with the given parameters.

### PFX

    public PFX(AuthenticatedSafes authSafes,
               MacData macData)

  Creates a PFX with the default version.

### PFX

    public PFX(AuthenticatedSafes authSafes)

  Creates a PFX with the default version and no MacData. The MacData can be added later with `computeMacData`.

See Also:
  `computeMacData(org.mozilla.jss.util.Password, byte[], int)`

Method Detail

### getVersion

    public INTEGER getVersion()

### getAuthSafes

    public AuthenticatedSafes getAuthSafes()

### getMacData

    public MacData getMacData()

  Returns the MacData of this PFX, which is used to verify the contents. This field is optional. If it is not present, null is returned.

### verifyAuthSafes

    public boolean verifyAuthSafes(Password password,
                                   java.lang.StringBuffer reason)
                            throws CryptoManager.NotInitializedException

  Verifies the HMAC on the authenticated safes, using the password provided.

  Parameters:
    `password` - The password to use to compute the HMAC.
    `reason` - If supplied, the reason for the verification failure will be appended to this StringBuffer.
  Returns:
    true if the MAC verifies correctly, false otherwise. If this PFX does not contain a MacData, returns false.
    `CryptoManager.NotInitializedException`

### computeMacData

    public void computeMacData(Password password,
                               byte[] salt,
                               int iterationCount)
                        throws CryptoManager.NotInitializedException,
                               java.security.DigestException,
                               TokenException,
                               java.io.CharConversionException

  Computes the macData field and adds it to the PFX. The macData field is a Message Authentication Code of the AuthenticatedSafes, and is used to prove the authenticity of the PFX.

  Parameters:
    `password` - The password to be used to create the password-based MAC.
    `salt` - The salt to be used. If null is passed in, a new salt will be created from a random source.
    `iterationCount` - The iteration count for the key generation. Use DEFAULT_ITERATIONS unless there's a need to be clever.
    `CryptoManager.NotInitializedException`
    `java.security.DigestException`
    `TokenException`
    `java.io.CharConversionException`

### getTag

    public Tag getTag()

  Description copied from interface: `ASN1Value`
  Returns the base tag for this type, not counting any tags that may be imposed on it by its context.

  Specified by:
    `getTag` in interface `ASN1Value`

### encode

    public void encode(java.io.OutputStream ostream)
                throws java.io.IOException

  Description copied from interface: `ASN1Value`
  Write this value's DER encoding to an output stream using its own base tag.

  Specified by:
    `encode` in interface `ASN1Value`
    `java.io.IOException`

### encode

    public void encode(Tag implicitTag,
                       java.io.OutputStream ostream)
                throws java.io.IOException

  Description copied from interface: `ASN1Value`
  Write this value's DER encoding to an output stream using an implicit tag.

  Specified by:
    `encode` in interface `ASN1Value`
    `java.io.IOException`

### main

    public static void main(java.lang.String[] args)

Overview | Package | Class | Tree | Deprecated | Index | Help
| JSS 3.4
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD